Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    keryn artifact analyze

    Describes Keryn 0.5.2 and keryn-rules 0.8.0. Changelog

    View as Markdown

    Binary / strings triage (MCP servers, agent helpers, CLIs) and model files (pickle, safetensors, GGUF, ONNX): capabilities, secrets, prompts -> findings, reports, gate.

    keryn artifact analyze <file>
    Usage: keryn artifact analyze <file|package> [--kind binary|text|metadata_json] [--report-dir <dir>] [--manifest <file|->] [--no-unpack]
    [--max-artifact-size <bytes>] [options]
    keryn artifact rules
    Static triage of a binary, a strings dump or a metadata JSON (Keryn's artifact analyzer core in WebAssembly): identity
    hashes, format by magic bytes, string extraction and tagging, marker rules, agent/MCP/model-provider surfaces,
    capabilities, secrets, endpoints, embedded prompts, a risk score. Model files are read, never loaded: pickle (PyTorch, joblib,
    NumPy object arrays, compressed members inflated), Keras .keras/.h5, TensorFlow graphs, safetensors, GGUF and ONNX; past 64 MiB
    only the header and code-bearing parts are read, and such a file is never called safe to load. The console names each finding
    (up to 20). Findings gate, write and annotate like a scan;
    --report-dir also writes the markdown, public-safe summary, IOC JSON, YARA draft and the full analysis JSON.
    --max-strings <n> --min-string-length <n> --no-redact string extraction (defaults 50000, 5, redacted)
    Third-party tools (capa, rabin2, GoReSym, redress, rustfilt, YARA) do not run here. No AI-BOM (--aibom is refused).
    A release package (.deb, .rpm, AppImage, .tar[.gz|.xz|.zst|.bz2], .zip) is unpacked, nothing executed, and every binary
    and maintainer script in it analysed (findings cite <package>!/<member>); xz/bzip2 and AppImage need xz/bzip2/unsquashfs,
    a missing helper, dmg and msi are "unsupported" (exit 3); unsafe members are refused; caps 1 GiB, 20000 members, 3 levels.
    A .vsix, .xpi, .jar, .whl, .nupkg, .apk is a zip and is unpacked too. Anything else unrecognised (compressed, packed, 7z/rar) is
    never a clean pass: coverage is incomplete (exit 3) and the limitation says why.
    --manifest <file|-> write the member manifest (sizes, sha256, metadata, helpers) --no-unpack analyse the file as is
    --max-artifact-size <bytes> per-artifact cap: the file given, or each package member (default 67108864 = 64 MiB, at most 1 GiB);
    a larger non-executable member is listed, not analysed, and the run (exit 3) names the value that includes it.
    Executables (ELF, Mach-O, PE) are never refused for size: without the flag they are parsed whole up to 256 MiB;
    past that (or past the flag) they are read in 2 MiB windows: strings, markers, crates, runtime and signature
    from every byte, structure (sections, imports, hardening) not parsed, so coverage is incomplete (exit 3).
    Also read from the file (components in the JSON result, basis observed-in-binary): the Rust crates linked into an executable
    (cargo-auditable .dep-v0 when present, else <crate>-<version> panic paths, else symbol names: evidence strength in each
    component), the Node.js runtime of a single-executable app (node@<version>, SEA or not), the signature kind (Mach-O none/ad-hoc/
    certificate/developer-id/notarized-ticket, PE none/authenticode), and the npm packages inside a JavaScript bundle (module keys,
    licence banners, a <file>.map or esbuild metafile beside it; versions from the nearest package-lock.json). Browser extension
    manifest.json and VS Code package.json members give permission and capability findings. coverage.artifact states the bytes read,
    the mode (in-memory / streamed) and whether the string cap (--max-strings) was reached. --online checks the versioned crates and npm
    packages against OSV.dev (names and versions only); offline they are named as not checked.
    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
    Terminal window
    # Triage a compiled MCP server without running it.
    keryn artifact analyze ./my-mcp-server --report-dir out/artifact
    # Analyse every member of a package and print the manifest.
    keryn artifact analyze release.deb --manifest -
    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)