devmaxxx/shell-secrets

Catch a secret in a shell command or an AI-agent tool call before it runs — written to a file, exported, or put in a commit message. Zero dependencies.
Install · Agent hooks · Quick start · Detected secrets · API · Recipes · Compared
Table of contents
Why
Features
Install
Agent hooks
Quick start
Detected secrets
API
findSecrets
findNewSecrets
findSecretsInCommand
onlyWritesTo
findCredentialSlots
Custom and disabled rules
Recipes
Compared with other scanners
Limits
Contributing
License
## Why
Coding agents and CI bots run shell commands, and that is where secrets leak now: echo "$KEY" > config.js, export GITHUBTOKEN=ghp… landing in a transcript, a token pasted into the message file of git commit -F msg.txt. Repository scanners like gitleaks and secretlint catch it after the fact, in files and history. Generic string scanners see the token but not what the command does with it.
findSecretsInCommand reads the command the way the shell would: it reports each secret, the variable it is exported or assigned to, the files the command writes through >, >> or tee, the message files git / gh would publish, and the files curl, scp or nc would send off the machine. It is a plain JavaScript function with no dependencies, so it fits in a pre-tool-use hook. It returns where the secret is and a masked preview, never the secret itself. findSecrets does the same for any plain string — a log line, a prompt, a staged diff.
## Features
Reads shell commands. findSecretsInCommand reports secrets assigned or exported (NAME=secret), the files a command writes through >, >> or tee, the message files git / gh would publish, and the files curl, scp or nc would send off the machine.
Built for agent tool calls. onlyWritesTo answers "does this command only write the secret into an allowed file, such as a gitignored .env?".
Catches credential slots. findCredentialSlots finds the other half of the problem: a command with a stand-in for the user to type a secret into (Authorization: Bearer , export APIKEY=your-key, --client-secret= , postgres://app: @db). The hook blocks one in a Bash call and sends back a reply that hands one to the user.
Zero runtime dependencies. ESM, fully typed, about 12 kB gzipped.
Tuned for precision. Placeholders (ghpxxxx…, , example), variable references (${DBPASSWORD}) and local dev credentials (postgres:postgres@localhost) are not reported, so a hit is worth stopping for. Classic GitHub tokens must carry a valid CRC32 checksum, so made-up ones in docs and tests pass.
Sees through base64. A blob that decodes to text, such as a Kubernetes Secret value or an echo … | base64 -d, is decoded and scanned, nested encodings included; the finding spans the encoded text.
Catches unnamed secrets too. A value under a secret-sounding name (APITOKEN=…, clientsecret: "…", --api-key …) is reported when a statistical test reads it as machine-generated, not a word, identifier, path or UUID.
Safe to log. A finding holds the rule, the offsets and a redacted preview such as ghp. It never holds the value.
Diff-aware. findNewSecrets reports only what an edit adds, not secrets the text already had.
Extensible. Add your own rules or drop built-in ones with a plain array.