Skip to content

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

    keryn surface signatures

    Describes Keryn 0.5.2 and keryn-rules 0.8.0. Changelog

    View as Markdown

    The service signatures surface classification uses.

    keryn surface signatures
    Usage: keryn surface classify <observed-ports.json> [options]
    keryn surface signatures
    Classifies supplied network observations ({observedPorts: [{host, port, protocol, open, tlsObserved, http: {status, headers,
    title, bodySnippet}}]}; a savvy-cli AI surface scan result is accepted too) into self-hosted AI services with the
    20-signature table (model runtimes and gateways, UIs, workflow builders, notebooks, MLOps, vector stores, object stores,
    MCP servers), infers exposure (from address literals) and auth state, scores risk and derives findings (unauthenticated,
    public, missing TLS, permissive CORS, ...) that gate like a scan. Services become AI-BOM components with basis
    observed-on-network (--aibom, --policy as for a scan). Nothing is probed: this command never touches the network.
    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
    # List the signatures.
    keryn surface signatures
    Code Meaning
    0 success
    2 usage error or unreadable input