CLI Reference

xgrep [flags] -f <rules> <targets...>

Flags:
  -f, --rules string      path to rule file or directory
  -c, --config string     path to rule file or directory (alias for --rules)
      --json              output results as JSON
      --stream            with --json: emit findings as newline-delimited JSON (NDJSON) during the scan
      --sarif             output results as SARIF
      --gitlab            output results as a GitLab SAST report (gl-sast-report.json)
      --fex               output results as Mondoo FEX finding documents (JSON) — the same documents reported to Mondoo Platform (inspect what gets uploaded; no service account needed)
      --project-root string        repository root for report file paths (default: auto-detected git root)
      --sarif-category string      SARIF automationDetails.id / GitHub Code Scanning category (default: xgrep)
      --error             exit with code 1 if findings are found (default: exit 0 even with findings)
      --max-findings int  exit 1 only when active findings exceed N (gradual rollout); takes precedence over --error; -1 disables (default)
      --disable-nosemgrep ignore inline nosemgrep/nogrep suppression comments and report all findings
  -j, --jobs int          number of parallel workers (default: NumCPU)
      --severity string   minimum severity to report (LOW, MEDIUM, HIGH, CRITICAL; Semgrep names INFO/WARNING/ERROR also accepted)
      --category string   only run rules in this category (e.g. security, correctness); default: security,secrets for built-in rules
      --subcategory string         only run rules in this subcategory tier (e.g. vuln for exploitable-only)
      --exclude-subcategory string skip rules in this subcategory tier (e.g. audit to drop hardening/advisory rules)
      --with-builtin string        with -f/--rules, also run the built-in rules from the given categories (comma-separated)
      --include-opt-in             also run rules marked metadata.opt-in: true (off by default)
      --include-tests              keep security findings in test/spec/fixture/example paths (dropped by default; secrets are always kept)
      --all-files                  also scan untracked files (default: git-tracked only)
      --no-ignore                  scan everything: disable the default-on ignores (node_modules, vendor, dist, minified, lockfiles)
      --include string             include only files matching glob pattern
      --exclude string             exclude files matching glob pattern
      --max-target-bytes int       skip files larger than N bytes
  -o, --output string     write output to file instead of stdout
      --rule-id string    only run rules with matching IDs (comma-separated)
      --skip-rule string  skip rules with matching IDs (comma-separated)
      --no-cache          do not write the .xgrep/findings.json cache that `xgrep fix` reads
      --no-dep-scan       skip dependency vulnerability scanning; report code (SAST) findings only
      --no-code-scan      skip the rule/SAST code scan; report dependency vulnerability findings only
      --redact            hide detected secret values in all output and in the Mondoo upload; keeps the rule ID, location, and fingerprint
      --sbom string       scan an existing SBOM file (CycloneDX/SPDX/Mondoo JSON) for dependency vulnerabilities instead of walking a code tree
      --incognito         local-only scan: do not report findings to Mondoo Platform (reporting is otherwise automatic when a service account is configured)
      --scope-mrn string  target Mondoo space/org MRN for reporting (defaults to the scope in the service-account config)
      --mondoo-config string  path to the Mondoo service-account config (default: MONDOO_CONFIG_PATH or ~/.config/mondoo/mondoo.yml)
      --timeout int       per-file timeout in seconds (default 60; 0 disables) — a pathological file is skipped and recorded, not left to hang the scan
      --verbose           show the full per-finding list (default output is a concise summary) and enable debug logging

Flags shown with a type (string, int) take an argument; the rest (--include-opt-in, --include-tests, --no-cache, --no-ignore, …) are booleans that take none. For the complete, current flag list (including --baseline-commit, --history, --decode, --max-memory, --lang, --metrics, --stdin, and profiling flags), run xgrep --help.

Default output vs. `--verbose`

On an interactive terminal, xgrep scan prints a concise executive summary — a scan headline, the top findings (most-severe first, with location), a severity breakdown (CRITICAL/HIGH/MEDIUM/LOW), and a → xgrep fix next step that works from the cached results. Pass --verbose to stream every finding inline (high-severity first; lower severities collapse to a hint unless you lower --severity). Piped/redirected output and every machine format (--json/--sarif/--gitlab) are unaffected. Severity is shown on the security-standard ladder (CRITICAL/HIGH/MEDIUM/LOW) in human output; the Semgrep-compatible names (ERROR/WARNING/INFO) are retained in --json and SARIF.

Rule selection

The built-in corpus is filtered by category and tier before it runs:

--category (default security,secrets) picks the top-level rule sets: security, secrets, correctness, … Secrets scanning is on by default, so a committed credential is reported without any extra flag.
--subcategory / --exclude-subcategory narrow by exploitability tier (vuln vs audit, below).
--rule-id / --skip-rule (and the Semgrep-compatible --exclude-rule alias) include or exclude individual rule IDs.
--include-opt-in additionally runs rules marked metadata.opt-in: true — higher-noise or situational rules that are off by default. --skip-rule still excludes them.

To run your own rules alongside the built-ins, pass -f/--rules together with --with-builtin <categories>; a custom rule overrides a built-in rule with the same ID, and an explicit --category still filters the whole merged set:

xgrep scan -f rules/ --with-builtin security,secrets src/

Exploitability tier (`--subcategory`)

Every built-in security rule carries a metadata.subcategory tier:

vuln — exploitable / attacker-reachable impact: injection, eval/dynamic exec, deserialization, SSRF, path traversal, auth bypass, open redirect, hardcoded credentials/secret exposure, and insecure-TLS / disabled cert validation.
audit — hardening / best-practice / advisory with no direct exploit: missing security headers, cookie flags, weak hashing/ciphers, timing attacks on constants, info disclosure (stacktraces, cleartext logging), availability DoS (ReDoS), and regex/validation smells.

Filter on it to get an exploitable-only scan (high signal, fewer advisories):

xgrep scan --category security --subcategory vuln <target>

--exclude-subcategory audit is the inverse and yields the same set when every rule is tiered. Combine with --xgrepignore to also drop non-source trees — the recommended setup for scanning a focused executable surface (e.g. an AI-agent skill):

xgrep scan --category security --subcategory vuln --xgrepignore <target>

Both flags accept a comma-separated list and compose with --category, --severity, and --rule-id/--skip-rule.

Subcommands

scan              scan targets (default when -f is provided)
sbom              generate a Software Bill of Materials (deps), or a CBOM with --cbom
ci                CI-optimized diff-aware scan (auto-detects the CI environment)
login             authenticate with Mondoo Platform using a registration token
inspect           code intelligence: search symbols, navigate definitions, assess impact
graph             build and query the code graph
mcp               run as an MCP server over stdio (for AI agents)
skill             list and install the bundled AI-agent skills (Claude Code or Codex)
test <path>       run tests on rule files in a directory
validate <path>   validate rule files without scanning
lsp               start an LSP server over stdio
version           print version and exit

login and reporting to the platform (automatic when a service account is configured; --incognito to disable) are documented under Mondoo Platform.
inspect and graph are documented under Code intelligence.
lsp is documented under IDE integration.
mcp is documented under Integrations.
skill is documented under AI agents → Skills.
test is documented under Testing rules.
sbom generates a dependency SBOM, or a Cryptography Bill of Materials with sbom --cbom — see CBOM.

Fixing findings (`xgrep fix`)

xgrep fix — a scan flags a disabled-TLS-verification finding, then fix apply rewrites verify=False to verify=True through the verification harness and prints the applied diff

scan discovers and never mutates source; the separate fix command is the only one that writes. scan --json emits each fixable finding's edits (extra.fix_info.edits) and contracts; fix consumes those and applies them through the verification harness. Every fix carries a confidence kind, surfaced in --json as extra.fix_info:

deterministic — exactly one correct edit, computed from the match. fix applies these directly.
assisted — context-dependent; emitted as a contract for an external agent (not auto-applied). The contract is extra.fix_info.contract: the unsafe_region to change (byte span + enclosing function when a code graph is available), the strategy (the rule's fix-hint), an optional canonical_fix ("from → to"), the recognized_sanitizers the re-scan gate accepts, and the acceptance_criteria the harness enforces.
advisory — natural-language guidance only (the rule's fix-hint).

A deterministic fix carries its edits as extra.fix_info.edits — one or more byte-span replacements (start_byte/end_byte/replacement), each annotated with its 1-based line/column span so renderers can place a multi-edit fix without re-reading the file. The same edits drive the SARIF fixes (one replacement per edit) and the LSP quickfix (one TextEdit per edit).

Every edit passes a verification harness before being written:

Parse-clean gate — the patched file is re-parsed; a fix that would introduce a syntax error into a previously-clean file is rejected. xgrep never writes code it would refuse to report.
Atomic write — a temp file in the same directory is renamed over the target, preserving mode; there is no partial-write window.
Re-scan gate (on by default; --no-rescan skips it) — the patched file is re-scanned and the fix is rejected unless it actually cleared the finding without introducing an equal-or-higher-severity finding in the region it touched.

fix has two verbs: fix verify never writes (returns a verdict + diff preview), fix apply writes the accepted edit atomically. Input precedence: a scan --json report or candidate piped on stdin wins; otherwise the .xgrep/findings.json cache scan writes is used. fix emits a FixOutcome per finding — applied / verified / rejected / needs-agent / advisory / out-of-scope / stale-cache. Scope which findings are fixed with --rule (rule-ID allowlist), --min-confidence, --max-severity, and --confirmed (triage-reviewed true-positives only — see Fixing only confirmed findings below); out-of-scope fixes are reported, never silently dropped. Pass --strict to exit non-zero on any rejection, so a CI pipeline can gate on fix failures.

# Preview every deterministic fix as a diff (no write).
xgrep scan --json ./src | xgrep fix verify

# Apply only high-confidence fixes for one rule.
xgrep scan --json ./src | xgrep fix apply --rule js-incorrect-suffix-check

# Or use the cache scan writes: discover once, then fix.
xgrep scan ./src && xgrep fix apply

Interactive review + agent fixing (`xgrep fix`)

Run bare xgrep fix in a terminal (no pipe) and it becomes an interactive review session: walk the findings, triage each, and apply or delegate the fixes — a TUI over the same harness.

xgrep fix                 # review the .xgrep cache interactively
xgrep fix ./src           # scan ./src first if there's no cache, then review

Keys: ↑/↓ move (or click a finding) · t/f/s mark true-positive / false-positive / needs-review (written to extra.triage) · u reset the verdict to unreviewed · x fix this finding (xgrep applies the deterministic edit or delegates the assisted one to the agent automatically) · space add to the batch, * select all, enter fix the selected set · g show xgrep graph context · P open a pull/merge request for the fixes you've applied (also offered when you q quit) · q quit. The mouse wheel (or PgUp/PgDn) scrolls the detail pane.

The detail pane previews the fix for the selected finding — a real before→after diff for deterministic fixes, or the plan/contract for assisted ones (the agent authors those at run time). To fix several at once, space toggles a finding into the batch (* selects all fixable), then enter shows a plan summary you confirm (enter) or cancel (esc); the confirmed set is fixed in one pass — deterministic edits applied, assisted findings delegated — each proven by the same re-scan.

Open a pull / merge request when you're done. Once you've applied at least one fix, press P (or just q to quit — it offers the same thing) to open a change request: xgrep creates a branch, stages only the files it changed, commits, and pushes, then opens the request with the host's CLI — while the agent writes the title and summary. The git host is detected from your origin remote: GitHub → a pull request via gh (gh pr create); GitLab → a merge request via glab (glab mr create). If the matching CLI isn't installed (or the push is rejected), it stops after the commit/push and shows you the branch so you can open the request by hand. This needs git push access and the relevant CLI authenticated; the base/target branch is your project's default. (Only files xgrep modified are staged, so unrelated uncommitted edits to those files would be included in the commit.)

Delegation shells out to your installed coding-agent CLI — claude by default, or codex, or a custom command. The agent investigates with xgrep graph/inspect and lands its edit through xgrep fix verify/apply; xgrep re-scans afterward and only reports applied if the finding actually cleared. xgrep never calls a model itself — it orchestrates the agent you already run.

Pick the agent with --agent (or XGREP_AGENT, or agent.default in the config):

xgrep fix --agent claude
xgrep fix --agent codex
xgrep fix --agent "my-agent --flag {prompt}"   # custom; {prompt} marks the prompt

The same orchestration runs non-interactively for CI — no terminal, driven by flags:

# Delegate triage of un-reviewed findings to the agent, then fix the confirmed ones.
xgrep fix --agent claude --triage-agent --yes

--yes (or any non-terminal invocation) skips the TUI; piped input (scan --json | fix) stays the batch path.

Fixing only confirmed findings

Between discovery and fixing, a finding is usually triaged — reviewed as a true positive, a false positive, or needs-review. xgrep carries that verdict on the finding itself, in an optional extra.triage object, so the whole scan → triage → fix loop round-trips through one findings.json:

"triage": {
  "reviewed": true,
  "status": "true-positive",          // | "false-positive" | "needs-review"
  "rationale": "uid flows unsanitized into execute()",
  "reviewed_by": "alice",             // a reviewer or a tool name
  "reviewed_at": "2026-07-01T10:30:00Z"
}

xgrep never sets triage during a scan — it is written after the scan by a reviewer or an agent (the xgrep-triage skill writes it back, joined to findings by fingerprint). xgrep fix then reads it:

By default, a finding marked status: false-positive is never auto-fixed — fix will not undo a verdict a reviewer made (the triage analog of an inline nosemgrep). Everything else fixes as usual.
With --confirmed, only findings marked status: true-positive are fixed; un-reviewed findings (no triage, or needs-review) are reported out-of-scope.

# Fix only what review confirmed — a one-flag CI gate after triage.
xgrep fix apply --confirmed < triaged-findings.json

--confirmed scopes the deterministic auto-apply batch; for assisted fixes, the agent driving the contract applies the same true-positive filter.

Triage without fixing (`--triage-only`)

--triage-only runs just the triage half of the loop: it hands all un-reviewed findings to the agent in one read-only session, and the agent records each verdict by calling xgrep triage set <fingerprint> <status> — so xgrep, not the agent, owns the findings file. It applies nothing. It's the headless false-positive review for CI — an LLM sifts findings before they gate a build, without touching source. (One agent invocation for the whole set, not one per finding.)

# Pipe a scan report through triage; emit the annotated report for the CI gate.
xgrep scan . --json | xgrep fix --triage-only --agent claude --json > triaged.json

# Or triage the scan cache in place (writes verdicts back to .xgrep/findings.json).
xgrep scan .
xgrep fix --triage-only --agent claude

Input: a scan --json report on stdin, the .xgrep/findings.json cache, or a path to scan first — same precedence as fix.
Output: the annotated scan report under --json (verdicts in extra.triage), else a one-line verdict tally. When reading the cache, verdicts are written back so a later xgrep fix --confirmed acts on them.
False positives are suppressed by default. A false-positive verdict is a suppression (the triage analog of an inline nosemgrep), so the agent's FPs drop out of the emitted report — the gate or upload downstream only sees real findings. The cache always keeps the full triaged set (FPs retained, marked, with the agent's rationale) as the audit record. Pass --include-false-positives to keep them in the emitted report too — a full annotated artifact, mainly for the piped flow where there is no cache to inspect.
Never writes source; idempotent (findings already carrying a verdict are skipped).

The verdict write path is a standalone command too — xgrep triage set <fingerprint> <true-positive|false-positive|needs-review> [--rationale "…"] records a verdict on the finding in .xgrep/findings.json (or the file named by XGREP_FINDINGS_FILE). That's what the agent calls under the hood, and it's usable directly by a reviewer or a custom script.

Pairs with --confirmed: --triage-only produces the verdicts, fix --confirmed fixes only the confirmed true-positives.

Agent round-trip (assisted fixes)

assisted findings aren't auto-applied — xgrep emits a fix contract and an external agent authors the edit, which fix then verifies through the same harness. A candidate is a JSON object on stdin (path, rule_id, edits):

# Verify a candidate without writing; returns a verdict + diff preview.
echo '{"path":"src/db.py","rule_id":"py-sql-injection","edits":[
  {"start_byte":420,"end_byte":480,"replacement":"..."}]}' \
  | xgrep fix verify -f rules.yaml

# Apply it (fix apply always writes the accepted edit, gated by the same harness).
echo '{…candidate…}' | xgrep fix apply -f rules.yaml

# Fix many findings in one process with NDJSON streaming.
cat candidates.ndjson | xgrep fix apply --batch -f rules.yaml

A fix that spans more than one file — e.g. add an import in one file and change the call site in another — is expressed as a changeset: a top-level files array of {path, edits}, verified and applied as one all-or-nothing unit (no file is written unless every file passes the harness). fix autodetects it on stdin and reports one FixOutcome whose paths lists every file touched.

echo '{"rule_id":"py-sql-injection","files":[
  {"path":"src/db.py",   "edits":[{"start_byte":420,"end_byte":480,"replacement":"…"}]},
  {"path":"src/util.py", "edits":[{"start_byte":0,"end_byte":0,"replacement":"import shlex\n"}]}
]}' | xgrep fix apply -f rules.yaml

A rejected candidate returns a machine-readable reason — span-conflict, parse-error, finding-not-cleared, new-finding-introduced, or no-change — to iterate on. The same operations are available over MCP as fix_verify and fix_apply. See the AI agent guide for the full loop.

In the LSP, each diagnostic's server-defined data payload carries fixKind (deterministic / assisted / advisory, omitted when the rule offers no remediation) alongside hasFix. Editor clients read it to decide which affordance to surface — e.g. an "Apply xgrep fix" quickfix for deterministic, or an AI-assisted fix action for assisted (which then fetches the contract via scan --json and drives the xgrep fix verify/apply round-trip).

Scan targets

A scan target is more than a single file. xgrep accepts any of these as <targets...>, and you can pass several at once:

A file — xgrep scan app.py scans just that file.
A directory — xgrep scan . scans it recursively. By default xgrep scans the git-tracked files under the directory (respecting .gitignore), falling back to a filesystem walk when the target isn't a git repository. See File filtering for what is and isn't included.
Multiple targets — xgrep scan src/ lib/ config.yaml scans the union.
A remote git repository — xgrep scan github.com/expressjs/express clones and scans it, no manual checkout needed. See Scanning a remote repository below.
stdin — pipe a single source with --stdin, or a multi-file JSON manifest with --stdin-files. See Scanning from stdin below.
No target — xgrep scan (with no path) scans the current directory, so you don't have to type xgrep scan .. A rules path with no target (xgrep -f rules.yaml) does the same. A bare xgrep with no subcommand and nothing to scan prints a welcome screen instead (so it never silently scans a large directory you didn't ask for).

Scanning from stdin

When the code to scan isn't on disk — an editor buffer, a generated snippet, a file pulled from an API — feed it on stdin instead of a path:

# A single source. --lang is required (there's no filename to detect from).
cat app.py | xgrep scan --stdin --lang python

# A set of files in one call, as a JSON manifest [{path, content}, ...].
# Cross-file taint is preserved across the set.
xgrep scan --stdin-files < files.json

--stdin reads one source from stdin and requires --lang to set the language. Findings are reported against a synthetic path.
--stdin-files reads a JSON array of {path, content} objects and scans them together, preserving the relative paths (so cross-file dataflow works).
stdin input is mutually exclusive with --history and --baseline-commit.

Scanning a remote repository

A scan target can be a remote git repository instead of a local path; xgrep clones it (shallowly, default branch) into a temp directory, scans it, and reports repo-relative paths. Cloning uses a built-in git client — no git binary required.

xgrep scan github.com/expressjs/express            # host/owner/repo shorthand
xgrep scan https://github.com/expressjs/express    # explicit https
xgrep scan git@github.com:expressjs/express.git    # SSH
xgrep scan github.com/expressjs/express --ref 4.18.2   # a tag, branch, or commit
xgrep scan github.com/expressjs/express --full-clone   # full history instead of shallow

A target is treated as remote only when it isn't an existing local path, so a local directory always scans in place.
--ref <branch|tag|commit> checks out a specific ref before scanning (default: the repo's default branch). A commit SHA implies a full clone.
--depth <n> sets the shallow clone depth (default 1); --full-clone clones full history. The two are mutually exclusive.
Private repositories use your usual git credentials: SSH targets via the ssh-agent; HTTPS targets via a token in the environment — GITHUB_TOKEN, GITLAB_TOKEN, or the generic XGREP_GIT_TOKEN.
Diff-aware scanning of a remote works: combine --baseline-commit with a remote target and xgrep clones it with full history automatically (a shallow clone has none to diff a range against), then diffs and reports only changed lines, repo-relative — the same behavior as a local diff-aware scan. Only a single remote target is supported in this mode.
```
xgrep scan github.com/acme/app --baseline-commit v1.0.0..v1.1.0
```
Remote scanning needs outbound network access (governed by your environment's network policy in hosted/CI setups).

Suppressing findings (nosemgrep)

Add a nosemgrep (or nogrep) comment on the matched line or the line directly above it to suppress a finding. Scope it to specific rules with nosemgrep: <id>; a bare nosemgrep suppresses every rule on that line.

dangerous(user_input)  # nosemgrep
dangerous(user_input)  # nosemgrep: python-command-injection

Suppressed findings are retained, not deleted, and surface differently per output so CI behaves predictably:

Output	Suppressed finding
Console text	hidden
JSON	included, `extra.is_ignored: true`
SARIF	included with `suppressions[].kind: "inSource"` → GitHub shows it dismissed
GitLab SAST	omitted
Exit code / `--error`	not counted (a file with only suppressed findings exits 0)

Pass --disable-nosemgrep to ignore all suppression comments and report every finding as active — useful for auditing what suppressions are hiding.

Diff-aware scanning (`--baseline-commit`)

For pull-request / CI checks, --baseline-commit scopes the scan to the files changed since a baseline so xgrep only parses and runs rules over what changed, and only reports findings on changed lines. This matches Semgrep/Opengrep, which expose diff-aware scanning under the same flag.

xgrep --baseline-commit HEAD               # changes in the working tree vs HEAD
xgrep --baseline-commit origin/main        # changes since origin/main (use the merge-base in CI)
xgrep --baseline-commit origin/main..HEAD  # changes in a commit range

The spec is a single ref (diffed against the working tree) or a <base>..<head> / <base>...<head> range.
Only changed files are scanned; findings on unchanged lines of changed files are dropped. --error exits 1 only when a changed line has a finding.
Content scanned is the working tree, and paths are repository-root relative — run xgrep from the repo root (the standard CI setup). For an accurate range, the head should be the working tree / HEAD.
Because unchanged files are not scanned, interfile (cross-file) analysis sees only the changed files; omit --baseline-commit for a full-context scan.

Scanning git history for secrets (`--history`)

A secret that was committed and later deleted still lives in the repository's git history, so it is still compromised. A normal scan only sees the working tree, and even a diff-aware scan (--baseline-commit) misses an add-then-remove. --history walks the full commit history and scans the content each commit introduced, so it catches secrets that no longer exist in the current tree.

# Scan a repo's whole history for secrets (pass the repo path)
xgrep --history --category secrets .

# Bound the walk for speed on large repos
xgrep --history --category secrets --since 2024-01-01 .
xgrep --history --category secrets --max-commits 5000 .

Each finding carries commit provenance — who introduced the secret and when — so you can rotate the credential and purge the history. In JSON/SARIF output this appears as a commit object:

{
  "check_id": "aws-access-key-id",
  "path": "config/app.yaml",
  "commit": {
    "sha": "b719f81a0c…",
    "author": "Jane Dev",
    "email": "jane@example.com",
    "date": "2024-03-02T11:07:14Z"
  }
}

Notes:

Pair it with --category secrets. History scanning runs whatever rules are selected; secrets are the use case it exists for. (The built-in default category is security, so without --category secrets you would scan history with the code-vulnerability rules instead.)
Additions only. Each commit is compared to its first parent and only the lines it added are attributed to it, so a secret is reported at the commit that introduced it — with its true line number in that commit's file.
Reported once. The same secret touched by many commits is de-duplicated to its earliest introducing commit.
--since <date> accepts YYYY-MM-DD or an RFC3339 timestamp; --max-commits <n> caps how many commits are walked (0 = no limit). Both require --history.
Hermetic. It reads only the local .git object store — no network. To scan a remote repository's history, clone it with full history first (xgrep scan <url> --full-clone) or check it out locally, then run --history.
Mutually exclusive with --baseline-commit and stdin input.

Decoding encoded payloads (`--decode`)

Secrets are often committed one encoding layer deep — a base64-wrapped .env, a gzip'd Kubernetes secret, a token inside a percent-encoded URL. To a normal scan that outer blob is opaque, so the credential inside it is missed. --decode decodes encoded payloads and re-runs the secret/generic rules over the decoded content, so the hidden token is found and reported at the encoded span in the original file.

# Find secrets hidden inside base64 / hex / url / gzip payloads
xgrep --decode --category secrets .

# Combine with history to sweep encoded secrets across deleted code too
xgrep --history --decode --category secrets .

Each decoded finding records the decode chain in metadata.decoded-from, and its position points at the encoded blob you can see in the file:

{
  "check_id": "aws-access-key-id",
  "path": "config/app.yaml",
  "start": { "line": 12, "col": 14 },
  "extra": {
    "metadata": { "decoded-from": "base64 > gzip" }
  }
}

Notes:

Opt-in. Off by default; a scan without --decode is byte-for-byte unchanged. Decoders supported today: base64 (standard + URL-safe), hex, url (percent-encoding), and gzip/zlib (peeled when nested).
Bounded. Nesting depth, per-payload input/output size, and per-file budgets are all capped, and an over-sized inflation is abandoned — so a decompression bomb cannot blow up a scan.
Precise. Decoded bytes that are not printable text are dropped before matching, so decoding never manufactures false positives; it only adds findings on content that really decodes to a credential.
Hermetic. Decoding is a local, deterministic transform — no network, no temp files. Decoded content is scanned as text, never parsed back into the language/AST engine.
Pair it with --category secrets for the intended use case (the built-in default category is security).

Selecting what to scan (code vs. dependencies)

A scan has two independent halves: the rule/SAST scan (code + secrets, narrowed by --category) and the dependency vulnerability scan (the SBOM). Both run by default; two flags turn either half off:

--no-dep-scan — run the rule scan only (no dependency findings).
--no-code-scan — run the dependency scan only (no code/secret findings).

xgrep --no-code-scan <target>   # dependency vulnerabilities only
xgrep --no-dep-scan  <target>   # code + secrets only

Setting both leaves nothing to scan and is rejected with an error. --no-code-scan cannot be combined with --history (a code/secrets walk).

Validating secrets (`--validate`)

Detection finds strings that look like credentials; --validate confirms whether one is actually live by probing its provider. It turns a finding's validation_state into:

confirmed — the provider accepted the secret; it is live (act now).
unconfirmed — the provider rejected it; revoked/invalid (lower urgency).
error — could not determine (network issue / unexpected response).
unvalidated — not probed (the default; no --validate, or the rule has no validation endpoint).

xgrep --validate --category secrets <target>

{ "check_id": "github-personal-access-token", "extra": { "validation_state": "confirmed" } }

This is opt-in and off by default — it is the one mode that makes outbound network calls, so the hermetic default is preserved unless you ask for it:

The candidate secret is sent only to that rule's fixed provider endpoint (built into the rule, not anything from the scanned content), and is never logged or written to disk — it is held in memory only for the probe.
Validation runs after detection; it never changes which findings are reported, only their validation_state. Probes are bounded by a small concurrency limit and short timeouts to stay gentle on provider APIs.
Only rules with a provider introspection endpoint are validated; the rest stay unvalidated. Validators currently ship for GitHub, GitLab, Slack, and Stripe tokens (more to follow).
Severity follows the result. A validatable secret is reported at its reduced unvalidated-severity until proven live; a confirmed finding is raised to the rule's full severity, while unconfirmed/error keep the reduced one. So --validate sharpens the signal — live keys rise to the top, dead ones stay low — rather than just adding a field.

Validating GitHub Action pins (`--validate`)

The same --validate flag also verifies GitHub Action SHA pins. Pinning an action to a commit SHA with a version comment is the recommended practice:

uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1

The static rules (in the default scan, no flag needed) check the shape of this line — that a SHA pin has a version comment, uses a full-length SHA, and isn't annotated with a mutable ref like # latest. What they cannot check offline is whether the comment tells the truth: that b4ffde6… really is the commit the v4.1.1 tag points to. A comment that lies — through drift or a malicious PR — slips a wrong or hostile commit past a reviewer who trusts the # v4.1.1 they see.

You must pass --validate to get this check — like secret validation, it is the one mode that makes outbound calls (it resolves the tag through the GitHub REST API), so it is off by default. Without --validate, the actions-sha-pin-version-mismatch rule stays silent: a version-commented pin is the good state, so it is only ever surfaced as a finding when the API proves the comment is wrong.

xgrep --validate <target>

When enabled, each pin's comment is checked and a mismatch is reported at a severity that reflects how wrong it is:

CRITICAL — the pinned SHA matches no published release tag of the action: an off-release (arbitrary, fork, or unreleased) commit posing as a trusted version.
HIGH — the version named in the comment does not exist (deleted/yanked or fabricated), though the SHA is some other real release.
MEDIUM — the comment names a real but different release than the SHA.
Honest pins, and pins that can't be checked (network/rate-limit), produce no finding.

Notes:

Set GITHUB_TOKEN to raise the GitHub API rate limit (the same token pinact uses).
For GitHub Enterprise Server, point the resolver at your instance with XGREP_GITHUB_API_BASE=https://ghe.example.com/api/v3.
Honest pins cost a single tag lookup; the heavier release-tag listing runs only when a comment doesn't match, so validation stays cheap on a clean repo.
The version comment must be v-prefixed (# v4.1.1) — the form pinact, Dependabot, and Renovate emit. Bare-semver comments (# 4.0.2) are left to the static shape checks.

Redacting secret values (`--redact`)

By default a secret finding prints the matched line verbatim, which includes the detected credential — fine for a local review, but a leak if the output is piped into CI logs or another system. --redact replaces every detected secret value with [REDACTED] while keeping everything a triage needs: the rule ID, file, line, and fingerprint.

xgrep --redact --category secrets <target>

{
  "check_id": "github-personal-access-token",
  "extra": { "lines": "github_token = \"[REDACTED]\"", "fingerprint": "0e1eb049fd5121aa" }
}

Opt-in, off by default — output is unchanged unless you pass --redact.
Covers every output format and the Mondoo upload. The masking runs once over the assembled report before rendering and before any upload, so the raw value never leaves the process — in text, --json, --sarif, --gitlab, --fex, or the platform report. The matched line, captured metavariables, and any dataflow-trace snippets are all scrubbed.
The fingerprint is unchanged. It is a one-way hash computed before redaction, so deduplication and cross-run stability are unaffected — a redacted and an unredacted scan of the same code produce the same fingerprints.
Not compatible with --stream or --sqlite, which emit or persist matched content during the scan, before the redaction pass runs. Combining them errors rather than silently leaking. Works with --validate: the secret is still probed (validation reads the raw match at scan time) and the validation_state is reported with the value hidden.

CLI Reference

On this page