Scan | mint

mint guard finds leaked secrets in a project and points to the command that should replace them. It is offline by design: no network calls, no telemetry and no execution of repository code.

mint guard scan [path] [--staged | --history [--since <rev>]]

path defaults to the current directory and must be a directory.

The three scan modes#

Mode	What it reads	Typical use
Working tree	Files on disk, honoring ignore rules	Local audit before pushing
`--staged`	`git show` for paths in the index	Pre-commit hook
`--history`	Added lines from `git log -p --all`	Finding what was already exposed

--staged and --history are mutually exclusive. --since only applies to history.

Working tree#

mint guard scan
mint guard scan ./packages/api

The walker skips node_modules, .git, dist, build, out, coverage, .next, .vercel, vendor, target, caches, IDE folders and similar generated directories. Lockfiles, binary files, symlinks and files larger than --max-file-size are skipped. Lines longer than 8 KB are ignored so minified bundles cannot stall a scan.

It honors:

.gitignore, including nested files and negations.
.git/info/exclude.
.mintguardignore.
The exclude list in .mintguard.json.
Inline suppression comments when inlineComments is enabled.

Staged changes#

mint guard scan --staged

This reads the git index, not the working tree. It scans added, copied, modified and renamed files that would be committed. Deleted files are not scanned.

If nothing is staged, the report notes that git diff --cached was empty.

History#

mint guard scan --history
mint guard scan --history --since "2 weeks ago"
mint guard scan --history --since HEAD~20

History scanning streams git log -p --all with zero context. Every added line is scanned with the commit hash, author and date attached. A revision passed to --since becomes <rev>..HEAD; a date is passed to git log --since.

Because history only has the added lines, whole-file marker rules such as the GCP service account check are not applied in this mode.

Example report#

$ mint guard scan
mint guard · worktree scan

! 3 findings (1 critical, 2 high)
  184 files scanned · 3.4 MB · 0.21s

CRITICAL github-token                src/config.ts:14
         GitHub token
         preview: ghp_...9f
         why: A GitHub token can read or push code...
         fix: mint token --bytes 32
         id: github-token-8c1f9a2e

HIGH     aws-access-key-id           deploy/config.ts:7
         AWS access key ID
         preview: AKIA...QZ
         why: AWS access key IDs identify the account...
         fix: mint base64url --length 40

next steps
  1. rotate the exposed secret first - it is compromised the moment it was committed
  2. store the replacement in your secret manager or a gitignored .env
  3. commit an .env.example with placeholders instead
  4. clean up git history only after rotating

Previews are illustrative. They show the first four and last two characters; values shorter than 12 characters are fully masked.

Flags#

Flag	Effect
`--staged`	Scan the git index
`--history`	Scan every commit and diff
`--since <rev\|date>`	Limit history to a revision or date
`--fail-on <severity>`	Exit 1 at or above `low`, `medium`, `high` or `critical`. Default `medium`
`--format <name>`	`text`, `json`, `sarif` or `markdown`
`--entropy-threshold <bits>`	Bits per character for entropy detection. Default 4.5
`--max-file-size <n>`	Skip larger files. Default `1mb`; supports `k` and `m`
`--include-lockfiles`	Scan lockfiles too
`--no-gitignore`	Do not read gitignore and mintguard ignore files
`--no-baseline`	Do not load the baseline
`--baseline-file <path>`	Baseline path. Default `.mintguard-baseline.json`
`--config <path>`	Config path
`--rules <id,id>`	Only run these rule ids
`--fix`	Print the remediation plan. Never edits files
`--quiet`	Suppress progress output
`--no-inline-comments`	Do not honor `mintguard:ignore` comments

--format is processed by the scan command. Global generator flags are parsed but are not useful here.

What happens with findings#

Findings at or above --fail-on make the command exit 1.
Findings below the threshold are still reported, but do not fail the scan.
Exit code 0 means clean with respect to the threshold.
Exit code 2 means a usage or runtime error.
The report contains a redacted preview, why the rule matters, a finding id and the mint command for a replacement.
The terminal report adds a four-step rotation reminder. --fix expands the provider plan and writes the same plan only, with no file edits.