Secret Sprawl Scanner

The Secret Sprawl Scanner detects accidentally committed secrets in code repositories. It scans source code, configuration files, and commit diffs for patterns that match known credential formats -- catching leaked API keys, database passwords, and private keys before they become a security incident.

Detected Patterns

The scanner recognizes the following secret types:

Pattern	Example Match
AWS Access Key	AKIAIOSFODNN7EXAMPLE
AWS Secret Key	wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
GitHub Token	ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GitHub Fine-Grained Token	github_pat_xxxxxxxxxxxxxxxxxxxxxxx
Slack Bot Token	xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxx
Slack Webhook URL	https://hooks.slack.com/services/T.../B.../...
Stripe Secret Key	sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Stripe Restricted Key	rk_live_xxxxxxxxxxxxxxxxxxxxxxxx
RSA Private Key	-----BEGIN RSA PRIVATE KEY-----
EC Private Key	-----BEGIN EC PRIVATE KEY-----
Database Connection String	postgresql://user:pass@host/db
SendGrid API Key	SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Twilio Auth Token	32-character hex string paired with Twilio Account SID
JWT Secret	HS256/HS384/HS512 hardcoded signing keys
Google API Key	AIza... (39-character string)
Heroku API Key	[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-...-[0-9a-fA-F]{12} in Heroku context

API Reference

Submit Code for Scanning

POST /api/sprawl/scan

Submit a block of text (file content, diff output, or any string) for synchronous scanning.

curl -X POST https://vault.example.com/api/sprawl/scan \
  -H "Authorization: Bearer $SM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "const API_KEY = \"AKIAIOSFODNN7EXAMPLE\";",
    "source": "config/settings.js"
  }'

Response (200):

{
  "findings": [
    {
      "type": "aws_access_key",
      "severity": "critical",
      "line": 1,
      "column": 19,
      "match": "AKIA***AMPLE",
      "source": "config/settings.js",
      "recommendation": "Rotate this AWS access key immediately and store it in SyVault Secrets Manager."
    }
  ],
  "scanned_at": "2026-04-06T12:00:00Z",
  "total_findings": 1
}

If no secrets are found, findings is an empty array and total_findings is 0.

List Scan Results

GET /api/sprawl/results

Retrieve historical scan results for your organization.

curl https://vault.example.com/api/sprawl/results \
  -H "Authorization: Bearer $SM_TOKEN"

Response (200):

{
  "data": [
    {
      "id": "scan-uuid-1",
      "source": "github:myorg/myrepo@main",
      "total_findings": 3,
      "critical": 1,
      "high": 2,
      "medium": 0,
      "scanned_at": "2026-04-06T12:00:00Z"
    }
  ]
}

GitHub Webhook

POST /api/sprawl/webhook/github

This endpoint receives GitHub push events, scans the pushed commits for secrets, and creates findings automatically. It does not require Bearer authentication -- it uses the GitHub webhook signature for verification.

GitHub Webhook Setup

Step 1: Generate a Webhook Secret

In the SyVault web vault, navigate to Secrets Manager > Sprawl Scanner > Integrations and click Generate Webhook Secret. Copy the generated secret.

Step 2: Configure the Webhook in GitHub

1. Go to your repository's Settings > Webhooks > Add webhook.
2. Set the Payload URL to:

   https://vault.example.com/api/sprawl/webhook/github

3. Set Content type to application/json.
4. Paste the webhook secret from Step 1 into the Secret field.
5. Under Which events would you like to trigger this webhook?, select Just the push event.
6. Click Add webhook.

Step 3: Verify

Push a test commit. In the SyVault web vault, navigate to Secrets Manager > Sprawl Scanner > Scan History to see results.

Webhook Payload Processing

When a push event arrives, SyVault:

1. Validates the X-Hub-Signature-256 header against the stored webhook secret using HMAC-SHA256.
2. Iterates over each commit in the push payload.
3. Fetches the diff for each commit via the GitHub API (using an optional GitHub App installation token or the repository's configured PAT).
4. Scans each diff for matching secret patterns.
5. Creates findings with the source set to github:{owner}/{repo}@{ref}.
6. If critical findings are detected, SyVault can optionally post a commit status check marking the commit as failed (configurable under Sprawl Scanner > Settings).

Example: Handling Findings Programmatically

from syvault import SecretsManagerClient

client = SecretsManagerClient(
    server="https://vault.example.com",
    client_id="c9a1b2d3-4e5f-6789-abcd-ef0123456789",
    private_key_path="/etc/syvault/client.pem"
)

results = client.sprawl.list_results()
for scan in results:
    if scan.critical > 0:
        print(f"ALERT: {scan.source} has {scan.critical} critical findings")

Security Considerations

• Content is not stored. The submitted code content is scanned in-memory and discarded after processing. Only the findings metadata (type, line, column, redacted match) is persisted.
• Matches are redacted. The match field in findings shows only a partial value (first 4 and last 5 characters) to prevent the scanner itself from becoming a source of credential leaks.
• Webhook signature verification is mandatory. Requests without a valid X-Hub-Signature-256 header are rejected with 403 Forbidden.
• Rate limits. The /api/sprawl/scan endpoint is limited to 60 requests per minute per client. Webhook events are limited to 300 per hour per repository.
• False positives. Some patterns (e.g., example keys in documentation) may trigger findings. You can dismiss false positives in the web vault, which trains the scanner to skip identical matches in future scans.