Usage and Examples

Secrets Hunter runs scans from the command line:

secrets-hunter [OPTIONS] [target]

If no target is provided, Secrets Hunter scans the current directory.

Common Options

For git history and domain scan options, see Scan Modes.

Filesystem Scans

Scan the current directory

secrets-hunter .

Example output:

========================================================================================
[1] Hardcoded jwt secret token at server.js:3
    Severity:   CRITICAL (confidence: 100%, reasoning: Pattern Match)
    Variable:   jwt_secret_token
    Match:      ***MASKED***
    Context:    ***MASKED***
----------------------------------------------------------------------------------------
[2] Hardcoded aws access key id at app.py:6
    Severity:   CRITICAL (confidence: 100%, reasoning: Pattern Match)
    Variable:   aws_access_key_id
    Match:      ***MASKED***
    Context:    ***MASKED***
----------------------------------------------------------------------------------------
[3] Hardcoded aws secret access key at app.py:7
    Severity:   CRITICAL (confidence: 100%, reasoning: High Entropy in context of secret key/variable assignment - secret)
    Variable:   aws_secret_access_key
    Match:      ***MASKED***
    Context:    ***MASKED***
----------------------------------------------------------------------------------------
[4] Hardcoded build id at app.py:10
    Severity:   INFO (confidence: 0%, reasoning: SHA1 hash in value)
    Variable:   build_id
    Match:      ***MASKED***
    Context:    ***MASKED***
----------------------------------------------------------------------------------------

Scan a directory

secrets-hunter path/to/project

Scan a directory with Docker

Mount the directory you want to scan and pass the mounted path as the target:

docker run --rm -v ~/projects/my-app:/scan ghcr.io/fvlcn/secrets-hunter:latest /scan

Scan a single file

secrets-hunter path/to/file.py

Git History Scans

Git history scans use --git-revset, which accepts a git revision expression. It is not parsed as arbitrary git rev-list options.

Scan a commit

Use <commit-sha>^! to scan only one commit:

secrets-hunter . --git-revset '<commit-sha>^!'

Scan a pull request

Scan commits that are on the current branch but not on main:

secrets-hunter . --git-revset main..HEAD

Replace main with the base branch if needed.

Scan branch history

Scan the last 20 commits reachable from HEAD:

secrets-hunter . --git-revset HEAD --git-max-count 20

Scan git history with Docker

Mount the repository, set it as the working directory, and mark the mounted path as a safe Git directory inside the container:

docker run --rm \
  -e GIT_CONFIG_COUNT=1 \
  -e GIT_CONFIG_KEY_0=safe.directory \
  -e GIT_CONFIG_VALUE_0=/scan \
  -v ~/projects/my-app:/scan \
  -w /scan \
  ghcr.io/fvlcn/secrets-hunter:latest \
  . --git-revset main..HEAD

Domain Scans

Domain scans check the built-in list of commonly exposed relative paths on the target host.

Scan exposed domain paths

secrets-hunter --domain example.com

Scan exposed domain paths with Docker

Domain scans do not need a mounted local directory:

docker run --rm ghcr.io/fvlcn/secrets-hunter:latest --domain example.com

Skip TLS verification

For internal or controlled environments with custom TLS, certificate verification can be skipped:

secrets-hunter --domain https://internal.example --skip-tls-verify

Output and Filtering

Reveal findings

Findings are masked by default. To show raw values, use the --reveal-findings flag:

secrets-hunter . --reveal-findings

Export as JSON

secrets-hunter . --json results.json

Example output:

[
    {
        "title": "Hardcoded jwt secret token at server.js:3",
        "file": "server.js",
        "line": 3,
        "type": "JWT Token",
        "match": "***MASKED***",
        "context": "***MASKED***",
        "severity": "CRITICAL",
        "confidence_reasoning": "Pattern Match",
        "detection_method": "pattern",
        "confidence": 100,
        "context_var": "jwt_secret_token",
        "commit": null,
        "vulnerable_url": null
    }
]

Export as JSON and reveal findings

secrets-hunter . --reveal-findings --json results.json

Export as JSON, reveal findings and truncate long matches

secrets-hunter . --reveal-findings --json results.json --truncate-long-matches

Export as JSON, reveal findings and filter out low-confidence findings

secrets-hunter . --reveal-findings --json results.json --min-confidence 75

Export as SARIF

secrets-hunter . --sarif results.sarif

Fail only on higher-confidence findings

secrets-hunter . --min-confidence 75 --fail-on-findings

Config

Use overlay config

Apply custom configuration using an overlay file:

secrets-hunter . --config team.toml

Stack multiple overlays

Apply multiple configuration files in sequence:

secrets-hunter . --config ci.toml --config local.toml

Learn more about configuration in the Configuration docs.

Exit Codes

• 0 - scan completed successfully. Findings may still be present unless --fail-on-findings is used.
• 1 - scan failed because of an input or runtime error.
• 2 - scan completed successfully and actionable findings were reported while --fail-on-findings was set.