# Leak Detection

## Keys Will Leak

No matter how many warnings you put in your documentation, API keys end up in places they shouldn't: public GitHub repos, client-side JavaScript bundles, CI logs, Slack messages, Stack Overflow answers, and Docker images. Accepting that leaks are inevitable, and building systems to detect and respond to them, is more effective than hoping it never happens.

## Key Prefixes Enable Detection

The single most impactful thing you can do for leak detection is give your API keys a [recognizable prefix](/docs/implementation/key-formats-and-prefixes):

```
myapi_live_7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c
```

Prefixes like `sk_live_`, `pk_test_`, or `myapi_` serve two purposes:

1. **Automated scanning tools** can write regex patterns to find your keys in code, logs, and documents.
2. **Humans** can immediately recognize the key and know which service it belongs to.

Without a prefix, your keys are random strings indistinguishable from any other base64 or hex value. With a prefix, they become detectable.

Choose a prefix format that includes:

- **Service identifier**: `sk` (secret key), `pk` (publishable key), or your service name.
- **Environment**: `live`, `test`, `staging`.
- **Separator**: Use underscores for readability.

```
{type}_{environment}_{random_value}
```

## GitHub Secret Scanning

GitHub automatically scans every push to public repositories for known secret formats. If you're an API provider, you can register your key pattern with [GitHub's secret scanning partner program](https://docs.github.com/en/code-security/secret-scanning/introduction/about-secret-scanning). When GitHub detects a matching token, it sends a webhook to your service so you can automatically revoke or flag the key.

Even if you haven't partnered with GitHub, you can enable secret scanning for your own organization's repositories to catch keys from other providers that your developers may have accidentally committed.

### What GitHub needs from you

- A regex pattern matching your key format.
- A webhook endpoint that accepts notifications when keys are found.
- A response indicating whether the key is active, revoked, or unknown.

## Scanning Tools

Several tools scan codebases, commit histories, and infrastructure for leaked secrets:

| Tool | What It Does |
|---|---|
| **GitHub Secret Scanning** | Scans public and private repos for partner-registered patterns |
| **GitGuardian** | Real-time monitoring of GitHub, GitLab, Bitbucket, and CI/CD logs |
| **truffleHog** | Scans git history for high-entropy strings and known patterns |
| **gitleaks** | Fast, configurable scanner for git repos, supporting custom rules |
| **detect-secrets** | Yelp's tool for preventing secrets from entering code in the first place |

For CI/CD pipelines, run a scanner as a pre-commit hook or CI step:

```bash
# Using gitleaks in a CI pipeline
gitleaks detect --source . --report-format json --report-path gitleaks-report.json

# Using truffleHog to scan git history
trufflehog git file://. --only-verified
```

## Monitoring and Alerting

Beyond scanning repositories, monitor other channels where keys appear:

- **Application logs**: Audit your logging pipeline to ensure keys are redacted. Search existing logs for your key prefix to find historical leaks.
- **Error tracking services**: Tools like Sentry or Datadog may capture keys in request headers or stack traces.
- **Public paste sites**: Services like GitGuardian also monitor Pastebin, Gist, and other public paste sites.
- **npm / PyPI packages**: Keys occasionally ship inside published packages.

Set up alerts so your security team is notified within minutes of detection, not days.

## Automated Revocation

Detection without action is just awareness. Build an automated response pipeline:

1. **Detection**: A scanning tool identifies a leaked key.
2. **Verification**: Confirm the key is active (call your own validation endpoint).
3. **[Revocation](/docs/implementation/revocation)**: Automatically revoke the key or mark it for immediate [rotation](/docs/security/key-rotation).
4. **Notification**: Alert the key owner via email, Slack, or your developer portal that their key has been revoked due to a detected leak.
5. **Audit log**: Record the event, including where the key was found and what action was taken.

```json
{
  "event": "key_leaked",
  "key_prefix": "sk_live_7f8a9b",
  "detected_by": "github_secret_scanning",
  "source": "https://github.com/user/repo/blob/main/config.js#L12",
  "action": "revoked",
  "notified": "owner@example.com",
  "timestamp": "2026-04-14T10:30:00Z"
}
```

For high-security environments, revoke automatically and require the consumer to create a new key. For lower-risk scenarios, you might flag the key and give the owner a short window to rotate before forced revocation.

## Best Practices

- Use a unique, [recognizable prefix](/docs/implementation/key-formats-and-prefixes) for every key you issue.
- Register your key format with GitHub's secret scanning partner program.
- Run a secret scanner in CI to catch leaks before code is merged.
- Redact keys from all application logs and error reports.
- Automate the detection-to-revocation pipeline so leaked keys are neutralized in minutes, not days.
- Notify key owners immediately when a leak is detected, with clear instructions for generating a replacement.