# keryn forensics scan

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> keryn forensics scan: AI forensics of a repository tree (repo-ai-forensics: stacks, prompt files, tool definitions, RAG, model artifacts, routes, controls, risks) -> findings, gate

Source: https://keryn.dev/docs/reference/cli/forensics-scan/

AI forensics of a repository tree (repo-ai-forensics: stacks, prompt files, tool definitions, RAG, model artifacts, routes, controls, risks) -> findings, gate.

```text
keryn forensics scan <path>
```

## Options

```text
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 warnings
```

## Examples

```sh
# Risks gate and write like audit findings.
keryn forensics scan . --sarif forensics.sarif
```

## 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) |
