RiskGrep is a local scanner that scores files from 0 to 100 per sensitive-data category. Version 1 has two categories: secret (API keys, tokens, private keys, credentials) and biometric (voice and face embedding files and printed embedding arrays). Scoring uses YARA-X rules and small structural checks in Rust; it never calls an LLM, never uses the network at scan time, and never records matched values. Reports hold rule identifiers, paths, line numbers, and scores only.
It has three front ends: the riskgrep command line, a git pre-commit hook, and riskgrep-claude, a Claude Code PreToolUse hook that asks or denies before an agent reads a sensitive file.
Licensed under MIT or Apache-2.0, at your option.
- A static risk-assessment tool. It scores files, directories, standard input, and the files a shell command names, from 0 to 100 for each category of sensitive data.
- Heuristic, with no LLM. Scores come from pattern rules, checksums, and structural checks such as file headers and tensor shapes. Nothing is sent to a model or over the network, and with the same rules and configuration the same input always gets the same score.
- A way to assess content without reading it. Agents and automated systems learn how risky something is before they open it. Reports carry rule identifiers, paths, line numbers, and scores, never the matched content.
- Scores first, decisions second. The command line reports scores and fails only at thresholds you choose; the git hook blocks at its thresholds; the Claude Code hook asks or denies at its own. Each consumer sets the policy that fits it.
- Not a security measure against a hostile agent. It protects against accidental exposure by a cooperative agent or person. An agent that sets out to get around it can do so, for example by editing your configuration, reading a file through a path RiskGrep does not see, or running a program that opens the file itself.
- Not a replacement for sandboxing. It does not isolate processes or restrict what a program can reach on the filesystem or the network.
- Not a replacement for permission rules. It does not control access to files or tools; it scores content so that something else can decide. Keep your file permissions and your agent's allow and deny rules.
- Not a guarantee of anything. Heuristics miss sensitive content and flag harmless content. A low score does not mean a file is safe, and a hook decision does not guarantee that a read, a commit, or a leak is prevented. See Known limitations.
Use it as one layer alongside those controls, not in place of them.
RiskGrep is published on crates.io and builds from source with Rust 1.99.1 or later (rustup installs Rust). Install both binaries with:
cargo install --locked riskgrep riskgrep-claude--locked builds with the exact dependency versions RiskGrep was tested with. To build from a clone of this repository instead, which uses the toolchain pinned in rust-toolchain.toml:
cargo install --locked --path crates/riskgrep
cargo install --locked --path crates/riskgrep-claudeEither way, riskgrep and riskgrep-claude go to ~/.cargo/bin. Upgrade the two together: they share the evidence cache, and when they expect different cache schema versions, each run of either resets the cache, so cached reads miss until both are at the same version. Run riskgrep rules compile once afterwards, from any directory: it compiles the rulesets the Claude Code hook uses (the defaults and your user configuration) and stores them in the cache directory, so the first scan or hook call does not pay for it (about one second). It prints already compiled when the cache already holds them. Add --repo to compile the rulesets a repository's .riskgrep.toml selects instead; run it from inside that repository.
riskgrep scan path/to/file.env # a file
riskgrep scan src/ --format json # a directory, as JSON
cat notes.txt | riskgrep scan - # standard input
riskgrep scan . --fail-at secret=80,biometric=75
riskgrep baseline . # record current findings as known
riskgrep show config/app.env # the file with every match masked
riskgrep rules list # every rule, category, and weight
riskgrep rules test # run the rulesets' own test cases
riskgrep cache prune --dry-run # what pruning the cache would remove--fail-at CATEGORY=N[,CATEGORY=N…] makes the exit status 1 when a target's score for that category is at or above N. A target meets a threshold when its score rounded to one decimal, the number every output shows, is at least the threshold; --fail-at, the git hook's block_at, and the Claude Code hook's ask and deny thresholds all use that one rule (cargo test -p riskgrep --test cli fail_at_is_inclusive). Exit status 2 means a target could not be scanned and --on-error block applies, or part of a target's content was not read (text sampled at its ends; a key store, a tensor header, or standard input past its limit; a zip archive's member not read whole, a sampled member included; or an .npz member that cannot be read) and --on-partial blocks (--on-partial error, the default, follows --on-error; a score at its threshold exits 1 either way); 3 is a usage or configuration error. When standard output is closed early (riskgrep scan … | head -1), the command stops writing without a message and keeps the exit status the scan computed, so a gate in a pipeline with set -o pipefail still fails on 1 or 2; a scan that passed exits 0 (cargo test -p riskgrep --test epipe). --category and --ruleset narrow what runs, and --no-cache skips the evidence cache. Findings recorded by riskgrep baseline go to .riskgrep-baseline.json in the repository root; later scans treat them as known. Run riskgrep --help and riskgrep <command> --help for every option.
riskgrep show FILE prints a text file with every match of every rule replaced by <redacted> (--rule-ids names the ruleset and rule instead, as <redacted: secrets_core:aws_access_token>; --lines FIRST:LAST prints only those lines). A match spanning lines leaves the same number of line feeds after its marker, so line numbers match the file's. UTF-16 and UTF-32 text is printed as UTF-8. The file is read once and scanned whole, up to [show] max_bytes (64 MiB), by every built-in rule and any rules extra_ruleset_dirs adds (see Configuration for when a repository's count): thresholds, categories, rulesets, weight_overrides, [ignore], baselines, and path_allowlist never narrow the mask (path allowlists are always off for it, so a match under node_modules/ is masked too). The masked text is scanned again before anything is printed, and a match found outside the markers is masked too. The command refuses, printing nothing on standard output and the reason on standard error with exit status 2, when the file is over the size limit, a scan fails, times out, or reads only part of it, the scans together run past [show] time_budget_ms (60 s), a rule matches the content without a location, or no rule matches a text file's content, so there is nothing to mask (a rule that matches only the file's name does not count). A file that is not text and was scanned whole (a tensor file, key store, or archive) gets a summary instead: its format, the data types and shapes of the tensors found, member counts, and scores, never names or values. A file in a format RiskGrep cannot read (PDF, image, bzip2, xz, 7z, or other binary), a damaged archive, and an archive past the container limits are refused the same way. Values the rules do not detect are printed (see Known limitations).
riskgrep git install-hook # writes the pre-commit hook (honours core.hooksPath)
riskgrep git pre-commit # what the hook runs; also usable by handThe hook scores the lines added by the staged changes (--full-files or git.full_files = true scores whole files; renamed and copied files, binary files such as key stores and tensor files, and partly read files are always scored whole) and exits 1 when a category reaches its git.block_at threshold: 80 for secret and 75 for biometric by default. It also exits 1 by default for a staged file it could not scan or read only in part, such as a text file over 8 MiB (git.on_error, git.on_partial). It prints the path, rule identifiers, score, and line numbers, never the matched text.
riskgrep-claude checks Read, NotebookRead, Grep, Bash, and MCP tool calls before they run, and judges the file names a Glob call would reveal (see MCP tools). It finds the files the call would read, scans them, and answers ask or deny when a score reaches its threshold (defaults: biometric ask at 50 and deny at 75, secret ask at 80 and deny at 95). It never answers allow, and any other tool is untouched. When every finding in a text file comes from a rule whose locations cover every match on their own lines, the reason names the flagged line numbers and tells the agent to read the rest with offset and limit, and a Read whose requested lines, widened by one line on each side, avoid every flagged line gets no decision; other files get no partial read (see Partial reads). When a flagged text file has a match in its content and riskgrep show can show it (the hook makes the view first, within its budget, and discards it), the reason also offers riskgrep show on it, with the absolute path of the riskgrep binary installed beside the hook, and the hook answers ask for exactly that command shape unless the command would refuse (see Masked view). The offer needs that riskgrep to report the hook's own version. A Bash command whose files the analysis cannot determine gets no decision by default (claude_code.on_unresolved = "allow"); set it to "ask" or "deny" to prompt or block on such commands (see Known limitations).
riskgrep rules compile # warm the rules cache before the first call (any directory)
riskgrep-claude print-config # prints a settings.json fragmentMerge the printed fragment into ~/.claude/settings.json by hand: a PreToolUse hook entry and deny rules that keep the agent from editing ~/.config/riskgrep/. The hook entry sets "onFailure": "block" (Claude Code 2.1.295 or later), so a hook that cannot start, crashes, times out, or prints invalid output blocks the call instead of letting it through; print-config --no-block-on-failure leaves it out. The full behaviour, decision rules, time budget, and what was verified against Claude Code is in docs/claude-code.md.
Settings are layered: built-in defaults, then ~/.config/riskgrep/config.toml (both platforms), then the repository's .riskgrep.toml, then command-line options. [ignore] paths and rules in a later layer replace the earlier layer's lists rather than adding to them. The user configuration is read from $HOME/.config/riskgrep/config.toml on both macOS and Linux; XDG_CONFIG_HOME is not consulted. Example:
trusted_repos = ["/Users/me/work/project"]
[claude_code.thresholds.secret]
ask = 80
deny = 95
[git.block_at]
secret = 85
[limits]
walk_files = 20000limits.walk_files is the most files one directory walk visits (default 10,000); a directory with more is reported unscanned, and the Claude Code hook applies the same limit to the files a Grep would search, to directory walks, and to the names a Glob or a directory-listing MCP tool would reveal.
Zip archives (and jar, docx, xlsx, and wheel files), tar archives, and gzip files (.tar.gz, .tgz, and .gz) are opened and their members scanned like files; findings name the member as archive.zip!/path/in/archive, archive.tar.gz!/path/in/archive, or app.log.gz!/app.log. The members of one archive, nested archives included, share these limits, shown with their defaults:
[limits]
container_bytes = 8388608 # uncompressed bytes read from all members
member_bytes = 8388608 # bytes read from one member
container_members = 1000 # members examined
container_depth = 3 # nesting depth; the archive itself is depth 1
container_ratio = 100 # uncompressed-to-compressed ratio, per member and overall, checked past 1 MiB
[claude_code]
on_partial = "error" # a target read in part: "error" follows on_error, or allow, ask, deny, block
[git]
on_partial = "error"A target with content that was not read is reported partial and never passes silently: on_partial applies, and by default it follows on_error, so the Claude Code hook asks and the git hook blocks. That covers text over limits.text_max (8 MiB), which is sampled at its ends; a key store or .npy header over the text limit; a safetensors header over 100 MiB; standard input over 64 MiB; an archive with a member not read whole (a limit reached, an encrypted member, or a member sampled because it is over the text limit); and an .npz with a member named .npy that cannot be read or is not an npy file, or with members past the 1,024th (an .npz with any other member, or a comment, is read as a zip archive). A finding in the part read keeps its result, and on_partial never lowers a decision. on_partial = "allow" accepts all of these, including an archive that holds a member it cannot open, such as a bzip2 stream, next to members it read; the same stream on its own follows on_error. [ignore] and baselines suppress findings, not this status. See Files read in part, Zip members are read within shared limits, and the same for tar and gzip.
SQLite databases are read under the same limits, through the file format rather than the SQLite library, so a scan never writes to a database, checkpoints it, or locks it. Each column with text or BLOB cells is a member: findings name it as app.db!/table/column, with lines and offsets in the column's cells joined by line feeds. A table that does not fit is read from both ends and the database is partial, as it is when a write-ahead log or rollback journal lies beside it, since those are not read; a new database in WAL mode before its first checkpoint, whose own pages hold nothing yet, is unscanned. Encrypted databases are unscanned. See Known limitations.
Other keys select rulesets (rulesets, extra_ruleset_dirs), adjust rule weights (weight_overrides), and list paths and rules to ignore ([ignore]). path_allowlist = false turns off gitleaks' global path allowlist, which the converted secret rules apply to lockfiles, vendored directories such as node_modules/, and image, font, and document names; path_allowlist under [claude_code] or [git], or riskgrep scan --path-allowlist on|off, overrides it for that integration. A target the allowlist applied to reports path_allowlisted. See the allowlist.
riskgrep show reads only its own table and extra_ruleset_dirs. A repository file's extra_ruleset_dirs count only when the repository is in the user file's trusted_repos; those entries are added to the user file's rather than replacing them. A repository file's [show] limits count only when they are lower than the values so far, unless the repository is in trusted_repos:
[show]
max_bytes = 67108864 # default (64 MiB); a larger file is refused
time_budget_ms = 60000 # default; bounds each scan, and no rescan starts after itTrust: the Claude Code hook reads a repository's .riskgrep.toml and .riskgrep-baseline.json only when the repository is listed in trusted_repos in the user config. An agent can write files in a repository, so an untrusted repository file is never allowed to loosen the checks. The command line and the git hook read the repository files without this restriction, except that riskgrep show takes a repository's extra_ruleset_dirs, and lets its [show] limits raise a value, only when it is listed in trusted_repos. An error about a file an untrusted repository supplies (its .riskgrep.toml, or a ruleset.toml or *.yar file of its rulesets) names the file and does not quote it, in every command. trusted_repos in a repository file is ignored.
The cache (compiled rules and per-file evidence, with no file content) is in ~/Library/Caches/riskgrep on macOS and $XDG_CACHE_HOME/riskgrep or ~/.cache/riskgrep on Linux.
The cache is pruned so it does not grow without limit. riskgrep cache prune removes compiled rule bundles that are no longer in use (those of a rule set no configuration you use resolves to, once older than the maximum age), the evidence written under bundles that are gone, rows older than the maximum age, rows for files that no longer exist, and the oldest rows when the database is over the maximum size. riskgrep cache prune --dry-run lists what would go and the sizes first. riskgrep scan and riskgrep git pre-commit prune on their own at most once a day, after they finish; the check is one stat of the file last-prune in the cache directory. The Claude Code hook never prunes. A pruned row or bundle costs a rescan or a recompile and never changes a score. The limits are set in the user configuration only (a repository file cannot size the cache every repository shares):
[cache]
max_age_days = 30 # default; at least 1
max_size_mb = 256 # default; at least 1; the database file after pruning, 1 MB = 10^6 bytes--fail-aboveis replaced by--fail-at, which is inclusive like the hook thresholds.- Relative paths in configuration (
extra_ruleset_dirs,trusted_repos) resolve against the directory of the file that declares them (~/.config/riskgrep/for the user file, the repository root for.riskgrep.toml), never against the working directory. Use absolute paths where a path meant the working directory. - The user configuration file is read only when
HOMEis an absolute path; without one, the defaults apply and the cache is off. - Baselines identify findings decided by a tensor header or a path-name rule by the file's content, not by rule and path. Regenerate
.riskgrep-baseline.jsonwithriskgrep baselineif it holds such findings from an earlier build. - Text output and git pre-commit messages show
line unknownfor findings in the last MiB of a text file larger than 8 MiB; JSON output keepsline_startandline_endat 0 for them.
cargo xtask eval measures the shipped release binary against a generated corpus and 13 pinned public repositories (55,877 files scanned in the 2026-10-20 run; files whose scan times out are listed by the run and not counted). The release bar is at most 1 flagged file per 1,000 ordinary files per category, 100% recall on the generated positives for provider-specific secrets and biometric file formats, and at least 90% for generic secrets; the current numbers meet it. The 100% recall figures cover only the generated formats: AWS, GitHub, Anthropic, Stripe, Slack, npm, and OpenAI tokens, PEM private keys, PKCS#12 files, and DER private-key headers for secrets, and .npy, .npz, safetensors (named, unnamed, and banks), and printed float arrays at the listed embedding widths for biometrics. Most of the 222 rules converted from gitleaks have no generated positive in the evaluation, and formats outside these lists are not measured at all. The measurements, corpus, and caveats are in eval/README.md. The recall figures on generated positives are circular by construction, and the public-repository figures are the better estimate of false positives.
Latency is checked in two ways. Whether a change makes RiskGrep slower is checked on every pull request by cargo xtask instructions, which counts the instructions each benchmark case runs under Valgrind's callgrind on Linux x86_64 and fails when a case is more than 1% over the committed baseline (or more than 1% under it, until the baseline is rewritten). Instruction counts depend far less on the machine's load than time does: on 10 hosted ubuntu-latest runner virtual machines with four CPU models, cargo xtask instructions --counter callgrind --runs 3 counted one commit within 0.18% per case. Whether it is fast enough in absolute terms is checked by cargo xtask bench against the targets in bench/targets.toml (for example, a cached hook call under 5 ms at the 95th percentile) and against a stored baseline per OS, on an otherwise idle machine. CI runs that benchmark on hosted runners as an informational step that cannot fail the build, because shared runners are slower and noisier than the reference machine the targets were set on.
What RiskGrep does not detect, what it may flag wrongly, and why is listed in Known limitations. Read it before relying on a score.
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo xtask eval --skip-oss # synthetic corpus only; omit the flag to include public repositories
cargo xtask instructions # Linux: needs valgrind; macOS: compares local builds only
cargo xtask bench # needs hyperfineCI (.github/workflows/ci.yml) runs the same checks on macOS and Ubuntu.
MIT or Apache-2.0, at your option: see LICENSE-MIT and LICENSE-APACHE. The secrets-core ruleset is converted from gitleaks (MIT); see UPSTREAM.md.