AI forensics of a repository tree (repo-ai-forensics: stacks, prompt files, tool definitions, RAG, model artifacts, routes, controls, risks) -> findings, gate.
keryn forensics scan <path>Options
Section titled “Options”Usage: keryn forensics scan <path> [options] keryn forensics report <path> Lists the tree (the same include/exclude/limits as a scan), lets repo-ai-forensics (savvy-cli, compiled to WebAssembly) triage it into the files worth reading (manifests always; up to 60 more by priority), reads those and classifies them: AI stacks the manifests declare, prompt files, tool definitions and their side effects, RAG plumbing, model artifacts, AI routes, controls, and the risks that follow. The risks gate, write and annotate like audit findings. No AI-BOM (--aibom is refused; components stay the inventory rules' business). 'report' prints the engine's full JSON instead.
Inputs --rules <a.yml,bundled:aibom> rule files or bundled packs: aibom, vuln, audit, inventory, all, risk (default: bundled:all for scan, bundled:aibom for bom/diff) --policy <file> policy-as-code YAML --config <file> | --no-config .keryn.yml (default: ./.keryn.yml if present) --base <git ref | bom.json | result.json> baseline for diff --include/--exclude <glob,...> path globs relative to the scan root (ts/fixtures/** is that one folder; **/fixtures/** any depth) --repo-root <dir> (scan, bundle) the repository the scanned folder belongs to: report paths, rule paths:, code roles, --include/--exclude and .keryn.yml (default <dir>/.keryn.yml) see repository-relative paths, as a scan of the whole repository would; fingerprints stay relative to the folder, so earlier baselines still match --max-file-size <bytes> --max-files <n> --max-total-size <bytes> --timeout <seconds> (lockfiles past --max-file-size are still read for dependencies, up to 64 MiB) --symlinks skip|follow-confined|error (default: skip) --subject <name> --revision <id> --timestamp <iso|now> --observed-browser <snapshot.json> a page snapshot (extension download): its AI technologies join the BOM, basis observed-in-browser --observed-network <observed-ports.json> network observations: classified AI services join the BOM (observed-on-network), their findings gate --summary-by owasp_llm|owasp_agentic|cwe|nist_ai_rmf|atlas group findings by a framework taxonomy in the console and markdown summary (reference only; not a compliance assessment) --offline (source scan/import: accepted and a no-op; these commands do not use the network)
Outputs ("-" writes to stdout; several per run) --aibom <f> CycloneDX 1.6 --sarif <f> SARIF 2.1.0 --sbom <f> dependency SBOM: every locked package, licence, graph (--sbom-format cyclonedx|spdx: CycloneDX 1.6, SPDX 2.3) --junit <f> JUnit XML --gitlab-sast <f> GitLab SAST report --codequality <f> Code Quality --json <f> Keryn result JSON --markdown <f> PR/MR summary --annotations github|azure|gitlab|teamcity -q, --quiet --verbose list findings with proof rung and flow
Gate --fail-on error|warning|info|none (default error) --fail-on-unsupported exit 3 on unsupported/partial/timed-out rules (now the default; kept for scripts) --allow-incomplete do not exit 3 when rules were unsupported/partial/timed out (default: exit 3) --dependencies <file> (scan) a resolved dependency list your build produced, read like a lockfile; repeatable. dependency-tree.json or dependency-tree.txt (mvn dependency:tree), or a CycloneDX / SPDX JSON SBOM named bom.json, sbom.json, *.cdx.json or *.spdx.json. It supersedes the pom.xml or Gradle build of its project. Keryn does not run Maven or Gradle --advisory-max-age <days> (scan) the installed offline advisory snapshot (keryn sca db update) may be this old; an older one still checks the dependencies but the run is incomplete (exit 3). Without --online an installed snapshot is used with no flag --require-advisories exit 3 when lockfiles were not checked against advisories (offline); the verdict always says so --gate-confidence P1|P2 lowest rule confidence that counts toward --fail-on (default P1; P2 widens) --secrets-config <file> (scan, ci) gitleaks TOML with your own secret rules ([extend] useDefault = true keeps the 222 defaults); default: .gitleaks.toml at the scanned root when present. A .gitleaksignore at the root is read. keryn rules lint <file.toml> checks one without scanning --secrets-history (scan, ci) also scan the added lines of every commit reachable from HEAD for secrets; --secrets-since <ref|date>, --secrets-max-commits N --no-deep (scan, bundle) skip the Deep pass: pattern rules only (default: Deep runs after them, fed with their facts) --deep-timeout <seconds> (scan, bundle) Deep's time limit (default 300; KERYN_DEEP_TIMEOUT_MS sets it in milliseconds). A Deep run stopped by it leaves the pattern findings and makes the scan incomplete (exit 3 in keryn ci) --engine deep|forge (scan) the interprocedural engine of the Deep pass: deep (default) or forge, the fact-bundle solver with KSQL rules (Python and TypeScript today); side by side while Forge proves itself --vex <local-file> repeatable OpenVEX, CSAF 2.0 VEX or CycloneDX VEX; attributed producer assertions, exact advisory and purl match --vex-product <purl|url> root context for VEX subcomponents; claims for other containers never apply globally --online (scan, bundle, artifact analyze) check locked dependencies (artifact: crates and npm packages read from the file) against OSV.dev advisories, and (scan) look up on deps.dev the licences lockfiles do not record: sends package names and versions only, never code or paths (default: offline; the report says which lockfiles were not checked). Reads deno.lock, and Deno code without one as declared, not locked; JSR, deno.land/x and URL modules are never sent --no-cache (scan, bundle) neither read nor write the rescan cache (KERYN_NO_CACHE=1 does the same); 'keryn cache clear' empties it --no-ignore scan files that .gitignore / .git/info/exclude exclude too (default: they are skipped and counted in the coverage line); Keryn's own earlier outputs are never scanned --new-only gate new findings against a paired Git --base; incomplete comparison fails --fail-on-added (diff) exit 1 when components were added --exit-warn exit 10 for pass-with-warnings
Exit codes: 0 pass | 1 violations | 2 usage/config | 3 coverage | 4 internal/timeout | 10 warningsExamples
Section titled “Examples”# Risks gate and write like audit findings.keryn forensics scan . --sarif forensics.sarifExit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
| 0 | pass: nothing at or above –fail-on, coverage complete |
| 1 | violations: findings at or above –fail-on, or a policy violation |
| 2 | usage or configuration error |
| 3 | coverage incomplete: a rule was unsupported, partial or timed out (–allow-incomplete opts out) |
| 4 | internal error or timeout |
| 10 | pass with warnings (only with –exit-warn) |