# Droid Shield

Automatic secret detection to prevent accidental exposure of credentials in your git commits and pushes.

## What is Droid Shield?

Droid Shield is a built-in security feature that automatically scans un-committed changes for potential secrets before committing and pushing them to remote. It is a safety net that prevents accidental exposure of sensitive credentials like API keys, tokens, and passwords in your version control history.

Organization admins can enforce Droid Shield through [Enterprise Controls](/enterprise/hierarchical-settings-and-org-control). For the broader enterprise safety model, see [Agent Safety & Controls](/enterprise/llm-safety-and-agent-controls).

## How Droid Shield works

When you use Droid to perform `git commit` or `git push` operations, Droid Shield automatically:

1. **Scans the diff** - Analyzes only the lines being added (not removed or unchanged)
2. **Detects secrets** - Uses pattern matching to identify potential credentials
3. **Blocks execution** - Stops the git operation if secrets are detected
4. **Reports findings** - Shows exactly where potential secrets were found

<Note>
  Droid Shield only scans git operations performed through Droid. Manual git commands run outside of Droid are not affected.
</Note>

---

## What Droid Shield detects

Droid Shield scans for a wide range of credential patterns, including:

<CardGroup cols={2}>
  <Card title="API Keys & Tokens" icon="key">
    Factory API keys, GitHub tokens, GitLab tokens, npm tokens, and API keys from (e.g. AWS, Google Cloud, Stripe, SendGrid) and more.
  </Card>
  <Card title="Authentication Credentials" icon="user-lock">
    (e.g. JWT, OAuth, session tokens), and URLs with embedded credentials.
  </Card>
  <Card title="Private Keys" icon="file-shield">
    (e.g. SSH private keys, PGP keys, age secret keys, OpenSSH keys), and other cryptographic key formats.
  </Card>
  <Card title="Service-Specific Secrets" icon="cloud">
    (e.g. Slack webhooks and tokens, Twilio credentials, Mailchimp keys, Square OAuth secrets, Azure storage keys).
  </Card>
</CardGroup>

### Detection algorithm

Droid Shield uses smart pattern matching with randomness validation:

{/* sweep-allow: term-bullets */}

- **Pattern matching** - Identifies credentials by format
- **Randomness check** - Validates that captured values look like actual secrets
- **Context awareness** - Considers variable names and assignment patterns to reduce false positives

---

## Droid Shield 2.0: learned secret detection

Droid Shield 2.0 augments the deterministic scanner with two fine-tuned classification models that add a semantic layer on top of pattern-based detection. Every commit and push still passes through the deterministic scanner first; the models then classify specific contexts the scanner flagged or missed.

<Note>
  Droid Shield 2.0 is in Private Preview. To enable it for your organization, contact [support@factory.ai](mailto:support@factory.ai).
</Note>

### The two classification models

The models sit on opposite sides of the deterministic scanner and are optimized for distinct failure modes:

<CardGroup cols={2}>
  <Card title="Risk model" icon="shield-exclamation">
    Runs on changed lines the deterministic scanner did **not** fire on, but that still look secret-bearing based on surrounding context. Optimized for recall to catch real secrets the pattern set would miss. Produces a warning when it flags a possible missed secret.
  </Card>
  <Card title="Downgrade model" icon="rotate">
    Runs on lines where the scanner **did** fire. It reviews the surrounding context with the detected secret masked out, and decides whether the scanner hit is a true positive (keep blocking) or a false alarm (downgrade to a warning).
  </Card>
</CardGroup>

---

## When Droid Shield activates

Droid Shield automatically activates during these git operations:

- **`git commit`** - Scans staged changes before creating the commit
- **`git push`** - Scans commits that would be pushed to the remote

<Warning>
  If secrets are detected, the git operation is blocked to prevent credential exposure. You'll need to remove the secrets before proceeding.
</Warning>

---

## Managing Droid Shield settings

### In the CLI

You can toggle Droid Shield on or off through the settings menu:

1. Run `droid`
2. Enter `/settings`
3. Toggle **"Droid Shield"** setting
4. Changes take effect immediately

<Info>
  Droid Shield is **enabled by default** for your protection. We strongly recommend keeping it enabled.
</Info>

---

## What to do if secrets are detected

When Droid Shield detects potential secrets, you'll see an error message like:

```text
Droid-Shield has detected potential secrets in 2 location(s) across files:
src/config.ts, .env.example

If you would like to override, you can either:
1. Perform the commit/push yourself manually
2. Disable Droid Shield by running /settings and toggling the "Droid Shield" option
```

### Recommended actions

<Steps>
  <Step title="Review the findings">
    Carefully examine the files and lines mentioned to identify what was detected.
  </Step>
  <Step title="Remove the secrets">
    - Use environment variables instead of hardcoded credentials
    - Move secrets to secure credential stores
    - Add sensitive files to `.gitignore`
    - Use git filter-branch or BFG Repo-Cleaner if secrets were already committed
  </Step>
  <Step title="Retry the operation">
    Once secrets are removed, run the git command again through Droid.
  </Step>
</Steps>

<Warning>
  **Never disable Droid Shield just to bypass the check.** Exposed credentials can lead to security breaches, unauthorized access, and compliance violations.
</Warning>

### If you get a false positive

Droid Shield uses conservative patterns to err on the side of caution. If you believe a detection is a false positive:

1. **Verify it's not a real secret** - Double-check that the value isn't sensitive
2. **Use a manual commit** - Perform the git operation yourself outside of Droid
3. **Report the pattern** - Contact [support@factory.ai](mailto:support@factory.ai) if you encounter recurring false positives

<Note>
  When Droid Shield 2.0 is enabled, the downgrade model automatically reviews scanner hits and can clear obvious false alarms (placeholders, examples, test fixtures) without manual intervention.
</Note>

---

## Best practices

### Use environment variables

Store all secrets in environment variables or secure credential managers, never hardcode them in source files.

```javascript
// Good - Using environment variable
const apiKey = process.env.FACTORY_API_KEY;

// Bad - Hardcoded secret
const apiKey = "never-hardcode-secrets";
```

### Keep Droid Shield enabled

Droid Shield provides an essential safety layer. Keep it enabled at all times, especially in team environments.

### Review before committing

Even with Droid Shield, manually review your changes before committing to ensure no sensitive data is included.

### Educate your team

Make sure all team members understand how Droid Shield works and why it's important to keep it enabled.

---

## Limitations

<Note>
  **Droid Shield is a detection tool, not a guarantee.** While it catches many common secret patterns, the deterministic scanner alone cannot detect:
  - Custom secret formats not in the pattern database
  - Secrets that don't follow recognizable patterns
  - Obfuscated or encoded credentials
  - Business logic vulnerabilities or code security issues
</Note>

---

<RelatedLinks>
  <RelatedLink href='/enterprise/security' title='CLI Security'>
    Learn about Factory's comprehensive security features and best practices.
  </RelatedLink>
  <RelatedLink href='/droid-cli/settings' title='Settings'>
    Configure Droid settings including Droid Shield preferences.
  </RelatedLink>
  <RelatedLink href="https://factory.ai/news/droid-shield-2-0" title='Droid Shield 2.0 Research Post'>
    Classification models, training data, and results.
  </RelatedLink>
  <RelatedLink href='/enterprise/llm-safety-and-agent-controls' title='Agent Safety & Controls'>
    How Droid Shield fits into the broader enterprise safety model.
  </RelatedLink>
  <RelatedLink href="mailto:security@factory.ai" title='Security questions'>
    Email the security team at security@factory.ai.
  </RelatedLink>
  <RelatedLink href="mailto:support@factory.ai" title='Report false positives'>
    Contact support@factory.ai about persistent false positive patterns.
  </RelatedLink>
</RelatedLinks>