secretsweep

[English] · 简体中文

Zero-dependency credential leak scanner. 86 provider rules, entropy detection, placeholder triage, and baseline diffs that make it usable as a PR gate instead of a one-off report.

pip install secretsweep            # or: uvx secretsweep
secretsweep scan .

The leading tools in this space are excellent and written in Go (gitleaks ~30k★, trufflehog ~28k★). The Python slot is served by detect-secrets, which carries dependencies and a plugin architecture. secretsweep is the other shape: one import-free package, deterministic, fast enough to run on every commit.

Three steps

pip install secretsweep
secretsweep demo                   # 1. see it work on a repo that leaks on purpose
secretsweep scan .                 # 2. scan your own tree

$ secretsweep scan .
src/config.py
  CRITICAL     4:17  github-pat  ghp_************7g
          GitHub personal access token | confidence=likely entropy=5.17
          classic personal access token (repo + org scopes possible)
  CRITICAL     5:31  postgres-uri  R7kQ******Zx
          PostgreSQL URI with password | confidence=likely entropy=3.58
  HIGH         2:22  aws-access-key-id  AKIA************PU
          AWS access key id | confidence=likely entropy=4.22
          long-lived IAM user key

Related MCP server: MegaLinter MCP Server

What it does differently

1. It separates real leaks from documented examples

Most false positives are not "strings that look like keys" - they are documented keys. AKIAIOSFODNN7EXAMPLE matches every AWS regex ever written. secretsweep scores each candidate:

2. It reads the room, not just the string

The same 40 characters mean different things in docs/example.env and in .github/workflows/deploy.yml. Every finding carries the bucket it was found in (source, config, ci, test, example, docs, vendor, lockfile) and the severity is adjusted from there:

tests/fixtures/tokens.json
  INFO         2:13  generic-token-assignment  R7kQ************7g
          Generic token assignment | confidence=likely | bucket=test
          bucket:test

3. It tells you what the credential can do

Offline inference from the shape of the value - no network calls, nothing leaves the machine:

• AKIA… is a long-lived IAM user key; ASIA… is a temporary STS session that expires on its own; AGPA… cannot sign requests at all.

• ghp_… is a classic token that cannot be scoped to one repo; github_pat_… is fine-grained.

• sk_live_… moves real money; sk_test_… does not.

• A JWT is decoded (not verified) to report alg, sub, and exp - an expired token is downgraded a level because it is not what you rotate first.

4. Baselines: the only way this survives an old repository

secretsweep baseline .                       # snapshot what is already there
secretsweep scan . --baseline .secretsweep-baseline.json

Fingerprints are path|rule|value-hash, so a baseline survives line drift but a new secret in a baselined file still fails the build. --prune shrinks the baseline as leaks get fixed.

Commands

Exit codes: 0 clean, 1 findings at or above --fail-on (default high), 2 usage error.

Useful scan flags: --min-severity, --entropy-min (raise every gate), --tag, --exclude-rule, --ignore-glob, --skip-dir, --show-placeholders, --no-inline-ignore, --no-evidence.

Inline suppressions

TOKEN = "ghp_..."        # secretsweep:ignore
KEY = "AKIA..."          # secretsweep:ignore[aws-access-key-id]

.secretsweepignore

gitignore-style globs, read from the scan root:

# the rule library carries one sample per rule - fixtures, not leaks
src/secretsweep/samples.py
tests/**

CI

- name: secret scan
  run: |
    pip install secretsweep
    secretsweep scan . --baseline .secretsweep-baseline.json --sarif secrets.sarif.json
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: secrets.sarif.json

SARIF 2.1.0 output includes security-severity, so findings land in code scanning with the right ranking.

GitHub Action

- uses: xuange-hu/secretsweep@v1
  with:
    path: .
    fail-on: high
    baseline: .secretsweep-baseline.json   # optional
    sarif: secrets.sarif.json              # optional

The action installs nothing: it runs the checked-out Python source with the runner's interpreter. A credential scanner that pulled a dependency tree into your CI would be working against its own purpose.

Outputs: findings, max-severity, files-scanned, exit-code, report, sarif. The report is also written to the job summary, capped at 64 KB so a noisy run cannot drown the log.

- uses: xuange-hu/secretsweep@v1
  id: sweep
  continue-on-error: true
  with:
    path: .
- name: Upload
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: ${{ steps.sweep.outputs.sarif }}

action-test.yml runs the action against a tree that leaks on purpose and asserts that it fails, so a regression in the action breaks CI here rather than in your workflow.

MCP server

pip install "secretsweep[mcp]"
secretsweep-mcp

Claude Code / Cursor / Cline config:

{
  "mcpServers": {
    "secretsweep": {
      "command": "uvx",
      "args": ["--from", "secretsweep[mcp]", "secretsweep-mcp"]
    }
  }
}

Pinned to mcp>=1.2,<2 on purpose: 2.x renames FastMCP to MCPServer.

Zero dependencies

The runtime package imports nothing outside the standard library. mcp is an optional extra and is the only entry in it.

Coverage

• 86 rules across cloud (AWS/GCP/Azure), git hosting, package registries, chat, payments, LLM providers, observability, SaaS, databases, and key material - plus entropy-gated generic assignments.

• Connection URIs: postgres, mysql, mongodb, redis, amqp, basic-auth URLs.

• Key material: PEM blocks, inline SSH keys, JWTs, Kubernetes service account tokens.

• History: secretsweep scan --history walks git log -p.

Scope

Secret detection - finding credentials that are already sitting in a tree so they can be rotated. It never calls out to a provider, never verifies a credential, and does nothing about bypassing access controls.

License

MIT. See LICENSE.