SecretGuard

Scans your code and git history for leaked secrets.

Why

Secrets are often committed accidentally, removed from the working directory, and then forgotten. Git still keeps those values recoverable in commit history unless the history itself is rewritten.

Regex-only scanners catch known formats, but they miss custom or unknown-format tokens. Entropy-based scanning helps fill that gap, but it has to be selective because lockfiles contain cryptographic checksums that look statistically similar to real secrets.

Features

Working Tree Scanning

• Scans directories or individual files with secretguard scan <path>.
• Uses a regex pattern library for AWS keys, GitHub and GitLab tokens, Slack tokens, Stripe keys, Google API keys, private key blocks, JWTs, database connection strings, generic API key assignments, generic secret assignments, bearer tokens, and password assignments.
• Groups duplicate findings by fingerprint so the same secret found in multiple files or locations is reported once with all known locations.

Entropy Detection

• Detects unknown-format secrets using Shannon entropy.
• Uses separate thresholds for hex-like strings and base64-like strings.
• Skips entropy scanning for lockfiles such as package-lock.json, yarn.lock, pnpm-lock.yaml, composer.lock, Gemfile.lock, and Cargo.lock, where checksums produce high false-positive rates.

Confidence Scoring

• Assigns each finding a 0-100 confidence score.
• Base score depends on the detection method: named regex pattern, generic regex pattern, or entropy-only finding.
• Adjusts confidence using variable-name context, placeholder-looking values, and test/spec/mock/fixture file paths.
• Supports filtering with --min-confidence <N>.

Git History Scanning

• Scans commit diffs with secretguard history instead of re-scanning full files at every commit.
• Attributes each unique historical secret to the first commit where SecretGuard sees it introduced.
• Deduplicates repeated historical findings by fingerprint.
• Supports scanning commits reachable from all local branches with --all-branches.

File Walking And Filtering

• Reads nested .gitignore files, not only the root .gitignore.
• Skips .git, node_modules, binary files, and unsupported file types.
• Tracks ignored files, skipped binary files, and skipped file types in scan summaries.
• Annotates .env.example, .env.sample, and .env.template findings as likely template/example files.

Built-In Concept Help

• secretguard help <topic> explains SecretGuard concepts in plain language.
• Supported topics: entropy, confidence, risk-levels, fingerprint, and detection-methods.

Terminal UI

• Uses chalk, ora, and boxen for readable terminal output.
• Shows spinners in interactive terminals and falls back to plain progress lines when output is piped or run in non-TTY environments.

Installation

npm install -g @nithin-npm/secretguard

Usage

Scan the current directory:

secretguard scan .

Filter out lower-confidence findings:

secretguard scan . --min-confidence 60

Scan the current branch's git history:

secretguard history

Scan commits reachable from all local branches:

secretguard history --all-branches

Explain a concept:

secretguard help entropy

Example Scan Output

Scanning ....
Scanned .

--------------------------------------------------------
HIGH  (confidence: 85)
  src/config/aws.js
    Line 12
    AWS Access Key
    Detection method: Regex pattern

--------------------------------------------------------
MEDIUM  (confidence: 55)
  services/payments/.env.example
    Line 4
    High-entropy string (likely a template/example file) (entropy: 4.63)
    Detection method: Entropy analysis

+------------------------------+
|                              |
|   Files scanned: 48          |
|   Ignored: 6                 |
|   Skipped (binary): 3        |
|   Skipped (file type): 12    |
|   Secrets: 2                 |
|   Risk: HIGH                 |
|                              |
+------------------------------+

Example History Output

Walking 42 commits...
Walked 42 commits

HIGH  GitHub PAT (classic)

Introduced:
Commit: a1b2c3d
Author: Jane Developer
Date: 2026-07-14T10:23:18+05:30
File: scripts/deploy.js

MEDIUM  Stripe Test Key

Introduced:
Commit: e4f5a6b
Author: Jane Developer
Date: 2026-07-18T16:02:41+05:30
File: test/fixtures/payment-config.js

+-------------------------------------------------+
|                                                 |
|   2 unique secrets, found in 3 commits total.   |
|                                                 |
+-------------------------------------------------+

Design Decisions

• The directory walker ignores names such as node_modules and .git at any recursion depth, because dependency folders can appear inside sub-packages and nested workspaces.
• .gitignore files are parsed at each directory level, since multi-package repositories often define local ignore rules below the root.
• Git history scanning operates on commit diffs instead of full-file re-scans, which keeps the historical scan focused on newly introduced lines.
• Overlapping regex and entropy candidates are collapsed so a known-format match is not double-counted as both a regex finding and an entropy finding.
• Lockfiles are excluded from entropy scanning because cryptographic checksums are statistically indistinguishable from real secrets by randomness alone. On a real test repository, this reduced entropy false positives from 600+ to under 10.
• Confidence scoring layers multiple signals, including detection method, naming context, placeholder patterns, and file path, rather than treating every regex match as equally reliable.

Tech Stack

• Node.js
• Commander.js
• simple-git
• ignore
• isbinaryfile
• chalk
• ora
• boxen

Status And Roadmap

SecretGuard currently covers working-tree scanning, git history scanning, entropy detection, confidence scoring, duplicate grouping, and concept help.

Auto-remediation, CI hooks, HTML reports, and JSON reports are deliberately out of scope for this version. The current focus is a focused CLI that produces human-readable findings for local review.

License

ISC