# keryn import

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> third-party scanner report (Semgrep, Trivy, SARIF, gitleaks, ZAP, ...) -> findings, outputs, gate; captured HTTP traffic (HAR, Burp items, ZAP messages) -> findings of 63 ZAP-compatible passive rules (cookies, headers, CSP, leaks), gate

Source: https://keryn.dev/docs/reference/cli/import/

> **Caution: Next release: keryn import capture.har**
> `keryn import <capture.har>` is on main; not in Keryn 0.5.2, the latest release.

Third-party scanner report (Semgrep, Trivy, SARIF, gitleaks, ZAP, ...) -> findings, outputs, gate.

Captured HTTP traffic (HAR, Burp items, ZAP messages) -> findings of 63 ZAP-compatible passive rules (cookies, headers, CSP, leaks), gate.

```text
keryn import <report> [--parser id]
keryn import <capture.har>
```

## Options

```text
Usage: keryn import <report-file | capture> [--parser <id>] [--scan-type <name>] [options]
  keryn import --list    show the 97 supported report formats
  keryn import runtime <events.jsonl | log export> [options]    decisions a Keryn Runtime agent reported
  Parses a scanner's own report locally (the DefectDojo parser corpus, ported to Rust, compiled to WebAssembly) and
  gates, writes and annotates its findings exactly like a scan. No rules run; no AI-BOM is produced (--aibom is refused).
  Without --parser the format is detected from the bytes and must be unambiguous.
  Captured HTTP traffic is recognised and checked instead: a HAR (DevTools: Save all as HAR with content), a Burp
  proxy-history export (<items>) or ZAP messages run through Keryn's Rust ports of the OWASP ZAP passive scan rules (63
  of 64, all identical to the pinned upstream on every differential case), plus a twin of the community script 100045
  Open MCP Server Detection that recognises an unauthenticated MCP initialize answer. Findings name the upstream rule and the
  capture; cookie values, Authorization headers and session ids are redacted; Informational alerts never gate; rules
  whose evidence the capture lacks are listed as limitations. Nothing is sent to the site.
  keryn import runtime reads keryn.dev/runtime-observations/v1 batches: the agent's events file (one batch per line) or a
  platform log export whose lines carry "keryn.rt {...}". Each decision record's hash and chain are checked first; a record
  that does not match its hash is left out, and a broken chain, an incomplete batch or dropped events make coverage
  incomplete. One finding per rule, function, route, operation, sink and input, counting refused (enforced), shadowed and
  failed-open requests; requests with no decision add nothing. Request-filter (Edge) matches are read too: one INFO finding
  per rule, function, route and input, counting requests refused, requests that would be refused in monitor mode and
  requests only flagged. A matched request is not a defect in the application, so these do not gate unless --fail-on info.
  Write --json into a directory and pass it to keryn ledger build to merge both with source and web findings.

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
# Gate and convert a Semgrep report.
keryn import semgrep.json --sarif keryn.sarif

# Show every supported format.
keryn import --list

# Run the passive web rules over captured traffic.
keryn import traffic.har --fail-on warning
```

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