secret-and-config-audit

Heuristic, redacting scanner for committed secrets and risky configuration in a directory tree. It reports leads — file, line, rule, severity and a masked shape of the match — and never emits the original value.

When to use

• Pre-release or pre-publication audit of a repository that will become public.
• A reviewer or CI job asking "does this tree contain a credential-shaped string?".
• Establishing which token formats a codebase is even capable of containing, via rules.
• Producing a JSON report an agent or shell script can gate on (--fail-on).
• Sanity-checking a newly introduced integration file (CI config, terraform, .npmrc).
• Reviewing a working-tree snapshot before sharing a patch, publishing a repository, or opening an incident ticket.

When not to use

• Proving a credential is live. Nothing here contacts a provider.
• Scanning git history, other branches, or a remote. Only the working tree is read.
• Replacing a dedicated tool such as Gitleaks, TruffleHog or detect-secrets. Those maintain richer fingerprints and entropy checks.
• Deciding what to do about a finding. Rotation and cleanup are human decisions.
• Grepping binary artefacts: binary files are skipped by design, not scanned.

Requirements

• Node.js >= 20 (uses node:fs/promises, TextDecoder, createRequire).
• No npm dependencies.
• git on PATH is optional: used for .gitignore resolution (git check-ignore --stdin -z). Without it, a root-.gitignore fallback reader is used.

Output contract

Success (exit 0) — one line on stdout, nothing on stderr:

{"data":{"root":"/abs/path","files_scanned":12,"files_skipped":3,"bytes_scanned":48213,"findings":[],"counts":{"by_rule":{},"by_severity":{"high":0,"medium":0,"low":0},"placeholder":4},"skipped":{"excluded":2,"extension":1,"gitignored":0,"too_large":0,"binary":0,"unreadable":0,"symlink":1,"other":0},"symlinks":{"count":1,"sample":["escape"]},"placeholders_sample":[{"file":"README.md","line":4,"rule":"github-token","reason":"example"}],"gitignore":{"mode":"git","files_ignored":0},"truncated":false,"exit_recommended":false}}

• findings[] entries: {file, line, column, rule, severity, kind, match, evidence}.
• file is relative to root; line is 1-based; column is 1-based.
• severity is high | medium | low.
• match is the non-reversible shape abcd…wxyz (first 4 + last 4 characters). Values shorter than 12 characters render as [redacted:too-short] and are never shown.
• evidence is the source line with the match replaced by [redacted], truncated to 240 characters.
• counts.placeholder is the number of matches suppressed as documentation. placeholders_sample[] shows up to 10 of them with file, line, rule, reason.
• skipped breaks files_skipped down by reason; gitignore.mode is git | fallback | disabled.
• exit_recommended is true when at least one high finding exists.
• truncated is true when --max-files or --max-findings cut the report short.

Failure (exit 1) — one line on stderr, nothing on stdout:

{"error":"directory not found: ./missing"}

• --help prints {"data":{"usage":"..."}} (exit 0).
• --version prints {"data":{"name":"@unreadlogs/skill-secret-and-config-audit","version":"0.1.0"}} (exit 0).
• With --fail-on high|medium|low and a matching finding, the report is still printed to stdout as {"data":...} but the exit code is 1 and stderr stays empty. This is the only case where a successful report accompanies a non-zero exit.

Commands

Flags in detail:

• --exclude a,b — extra comma-separated glob patterns (*, ?, **) matched against both the file name and the repo-relative path; skipped files count as skipped.excluded. Added to (never replaces) the built-in directory skip list.
• --include a,b — comma-separated globs. A matching file is scanned even when its extension is not text-like, and a matching directory is traversed even when it is in the built-in skip list. This is the escape hatch for node_modules, but it also means --include '**/*' will happily walk a vendor tree.
• --max-file-bytes N — files larger than this are skipped as too_large without being read. Default 1048576.
• --max-files N — only the first N candidate files are scanned; the rest count as excluded and truncated becomes true. Default 20000.
• --max-findings N — scanning stops once N findings exist. Default 500.
• --min-severity LEVEL — report only LEVEL or worse (high, medium, low). Default low, i.e. report everything. Placeholders are counted before this filter applies, so counts.placeholder does not shrink when you raise the bar.
• --rules a,b — restrict to specific rule ids; an unknown id is an error.
• --no-gitignore — disables .gitignore filtering (gitignore.mode becomes disabled).
• --fail-on LEVEL — exit 1 when any finding at LEVEL or worse exists (high, medium, low, or none, the default).

Rules

23 rules. kind groups them; false_positives is the honest caveat for each. rules prints the same table at runtime, including the false-positive notes.

A value that matches a rule but looks like documentation is not reported as a finding. It is counted in counts.placeholder and sampled in placeholders_sample. The placeholder reasons are: example, placeholder, redacted, changeme, pronoun-prefix, your-thing-here, x-mask, angle-mask, shell-expansion (${VAR}, $VAR), shell-variable, env-reference (process.env.X, import.meta.env.X, os.environ[…]), printf-format (%s), dummy-word, numeric, and prose.

Limits

Directories skipped by default: .git, .hg, .svn, .idea, .vscode-test, .cache, .parcel-cache, .turbo, .svelte-kit, .next, .nuxt, .output, .vercel, .netlify, .terraform, .gradle, .mvn, .venv, venv, env, __pycache__, node_modules, bower_components, vendor, Pods, target, out, dist, build, coverage, .nyc_output, .serverless, .expo, DerivedData, tmp.

Examples

Confirm nothing was committed before publishing a package:

node scripts/index.js scan . --min-severity high --fail-on high

Exit 1 with the report on stdout means at least one high-severity lead.

See what the scanner is capable of finding before trusting a clean result:

node scripts/index.js rules

{"data":{"count":23,"rules":[{"id":"private-key","severity":"high",...}]}} — every rule with its severity and its known false positives.

Audit only the files you are about to change, ignoring vendored trees:

node scripts/index.js scan services/api --exclude '**/*.snap' --min-severity medium

files_skipped.excluded tells you how many paths the --exclude patterns removed.

Triage a noisy report down to one provider and cap the output:

node scripts/index.js scan . --rules github-token,gitlab-token --max-findings 20

Shape of one finding — note that the value itself is absent and the masked shape cannot be reversed into it:

{
  "file": "src/billing.js",
  "line": 2,
  "column": 18,
  "rule": "stripe-key",
  "severity": "high",
  "kind": "provider-token",
  "match": "sk_l…mnop",
  "evidence": "const stripeKey = '[redacted]';"
}

Notes and limitations

• This is a heuristic scanner. A finding is a lead, not proof of a live credential; a clean scan is not proof of safety. Regexes cannot tell a real key from a 40-character fixture that happens to look like one.
• Values are never printed. match is first-4 + … + last-4. Eight characters of a key are not enough to use it, but they are enough to confirm a finding by eye — treat stdout as sensitive anyway. Values under 12 characters are not shown at all. evidence masks the match and truncates the line.
• False negatives are expected: secrets split across lines, base64 blobs with no keyword, encrypted blobs, and providers without a rule here.
• False positives are expected: see the false_positives column, and the generic assigned-secret rule especially, which is low severity for a reason.
• Not scanned: git history, submodules, packed objects, files whose extension is unknown, anything skipped by the directory list, anything ignored by .gitignore (unless --no-gitignore), and every file above --max-file-bytes.
• Symlinks are never followed, so no symlinked directory can cause infinite recursion or pull the scan outside root. Symlinks are counted in skipped.symlink and sampled in symlinks.sample.
• Binary detection uses a NUL byte in the first 8192 bytes plus a fatal UTF-8 decode. Valid-UTF-8 binaries are rare, so a misclassification is possible in both directions; both outcomes are visible in skipped.binary.
• .gitignore resolution prefers git check-ignore (correct, includes nested .gitignore files and negations). Outside a git work tree, or without git on PATH, only the root .gitignore is honoured and negations (!pattern) are ignored; gitignore.mode tells you which path was taken.
• What to do with a hit: treat it as compromised. Revoke/rotate at the provider first, then remove it from the tree — deleting the file does not remove it from git history.

Triage workflow

1. Decide whether the scope is the whole working tree or a smaller path set. Use rules first when you need to understand scanner coverage or tune a focused audit.
2. Run scan with a severity threshold that fits the task. Check the file, line, rule, and redacted evidence; never ask the tool or shell to print the original matched value.
3. Inspect the source locally to determine whether the match is a real credential, a fixture, or a documented placeholder. Do not repeat the value in chat, a ticket, or command output.
4. For a likely live credential, recommend revocation/rotation with the provider, then removal and an appropriate history-remediation process. A working-tree scan cannot establish whether a value was previously committed.
5. Report the scope, exclusions, truncation state, and key limitations with the findings. A clean result is useful evidence, not a security guarantee.

Detailed audit scenarios

Before publishing or making a repository public

Scan the working tree at the repository root and review the scan counters, ignored-file behavior, exclusions, and truncation. Include configuration and deployment files that may be outside the default extension set only when you understand the scope of --include. Check the intended release artifacts separately if they are generated or bundled; a tree scan does not inspect published packages or build output that was skipped.

If a clean scan is important, run rules to understand which token families are covered, and state that the scanner is heuristic. For a publication or incident with a high assurance requirement, pair it with a dedicated history scanner and provider-side controls.

Review one integration or configuration change

Pass the relevant subtree or use an include/exclude filter for the target files. Check whether .gitignore excluded the new file and whether the result was truncated. Review the redacted finding and inspect source context without copying secret-bearing lines into terminal logs, chat, or the final response. The scanner reports matching content; it does not determine whether the application actually uses the value.

Gate a CI job

Choose --fail-on based on the team's tolerance for false positives. high is the default recommended exit signal (exit_recommended tracks high findings), while medium/low thresholds can be noisy. Preserve the JSON report from stdout: with a matching --fail-on finding, exit code 1 still accompanies a successful report and stderr remains empty. Distinguish that policy failure from a tool error, which emits an error object on stderr.

Pin the scan root and limits in CI, and monitor truncated and skipped counts. A CI gate that silently scans only the first capped set of files can create a false sense of coverage. Avoid --include '**/*' without considering the cost and noise of scanning vendor trees.

Reading a finding without leaking it

Use file, line, column, rule, severity, kind, and redacted evidence to locate a candidate. The masked match still reveals a short prefix and suffix and must be treated as sensitive metadata. Keep raw values out of copied logs. If a candidate is a likely active secret, recommend immediate provider-side revocation or rotation and a history-remediation plan; do not test the credential by attempting to use it. If it is a fixture or placeholder, document why and consider a safer synthetic fixture that does not resemble a usable credential.

Report template

Scope: working tree at <root>; 1,245 files scanned; truncated: false
Finding: high / stripe-key at src/payments/config.js:18
Evidence: redacted match; likely credential-shaped value
Assessment: source context suggests it is configured as a runtime key; live
status was not checked and must not be tested from this scan.
Next step: rotate at the provider, replace with secret injection, and review
history exposure. Scan does not cover previous commits or remote branches.

Use this as a structure, not as a claim. Fill it only with observed evidence.

Troubleshooting