secretlock

A local Git pre-commit hook and CLI that scans staged changes for accidentally committed secrets — API keys, tokens, private keys, passwords — before they're committed. Zero network calls, fully local, nothing ever leaves your machine.

Think of it as the local, pre-commit sibling to CI-level scanners: it stops a leak before it's even in your commit history, rather than catching it after you've pushed.

Features

• Fast, targeted scanning — only scans added lines from git diff --staged by default (not your whole repo), so it's instant even on large codebases
• 16 built-in detection rules — AWS keys, GitHub tokens (classic + fine-grained), Slack tokens & webhooks, PEM private keys, Google API keys, Stripe keys, npm tokens, database connection strings with embedded credentials, JWTs, bearer tokens, and generic password=/api_key=/secret= assignments
• Entropy fallback — Shannon entropy analysis catches high-randomness strings that don't match any known format, for secrets from services with no dedicated rule
• Redacted output — findings show only the first/last 3 characters of a match, never the full secret, so it's safe to paste scan output into a Slack message or CI log
• Allowlisting — .secretlockignore glob patterns for whole files/folders, plus inline // secretlock-ignore-next-line comments for one-off false positives
• Zero network calls — nothing is sent anywhere, ever

Installation

npm install -g secretlock
# or run without installing:
npx secretlock scan

Usage

Scan staged changes (what runs automatically via the hook)

secretlock scan

Scan the entire working tree (not just staged changes)

secretlock scan --full

Install the pre-commit hook

secretlock install

This writes a pre-commit hook into .git/hooks/. If you already have a pre-commit hook that isn't secretlock's, it's backed up to .git/hooks/pre-commit.backup rather than overwritten.

Uninstall the hook

secretlock uninstall

Restores your original hook from the backup, if one exists.

Options

secretlock scan [options]

  --full                    Scan the entire working tree instead of staged changes
  --no-entropy              Disable the entropy-based fallback scanner
  --entropy-threshold <n>   Entropy threshold in bits/char (default: 4.5)

Allowlisting false positives

Create a .secretlockignore file at your repo root:

# Skip test fixtures entirely
test/fixtures/**
**/*.test.ts

# Skip a specific file
docs/example-config.env

Or suppress a single line inline:

const exampleKey = "AKIAIOSFODNN7EXAMPLE"; // secretlock-ignore-next-line

(The comment goes on the line above the flagged line.)

Exit codes

• 0 — clean scan, no secrets found
• 1 — secrets found, commit blocked
• 2 — an error occurred (not a git repo, git not found, etc.)

How it compares to CI-level scanners

If you're also running something like Gitleaks, TruffleHog, or a CI-integrated scanner (e.g. this author's own PR Risk Gate), secretlock isn't a replacement — it's a first line of defense. It catches the mistake locally, before the secret is in any commit history at all, while the CI-level scanner remains your backstop for anything that slips through (forced pushes, hooks not installed on a teammate's machine, etc.).

Development

npm install
npm run dev -- scan       # run from source via tsx
npm test                  # run the Vitest suite
npm run build              # bundle to dist/ via tsup
npm run typecheck

Project structure

src/
  rules.ts        # regex-based secret detection rules
  entropy.ts       # Shannon entropy calculator + fallback detector
  gitDiff.ts        # git diff parsing / working tree reading
  allowlist.ts      # .secretlockignore + inline ignore comment handling
  scanner.ts        # ties rules + entropy together, produces findings
  output.ts          # colored terminal output formatting
  hook.ts             # pre-commit hook install/uninstall
  cli.ts               # commander-based CLI entrypoint
  index.ts              # library exports for programmatic use

License

MIT