Skip to content

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

    keryn dast plan

    Describes Keryn 0.5.2 and keryn-rules 0.8.0. Changelog

    View as Markdown

    Incremental web checks from URLs/spec/HAR/sitemap, scoped ZAP execution, Burp/ZAP XML intake, one-GET Nuclei public profiles, offline HAR boundary checks.

    keryn dast plan <url...> [--spec f] [--har f] [--sitemap f] [--include p] [--exclude p] [--header-env Name=ENV] [--module passive,crawl] [--rps n] [--max-urls n] [--max-requests n] [--json]
    Usage: keryn dast plan|test <url...> [--spec f] [--har f] [--sitemap f] [--include p] [--exclude p] [--header-env Name=ENV] [--module passive,crawl]
    [--rps n] [--max-urls n] [--max-requests n] [--mode auto|cached|recheck|full] [--store dir] [--fail-on error|warning|info|none] [--json]
    keryn dast scan <application-url> --out <new-directory> [--active [--strength low|medium|high] [--seed <seeds.json>]] [--test-run <id>] [--ajax] [--executable <zap.sh>]
    keryn dast import <report.xml> --parser burp|zap --target <application-url> --out <new-directory>
    [--completion complete|partial|unknown|failed]
    keryn dast boundaries <capture.har> --policy <policy.json> --out <new-directory> [--fail-on error|warning|info|none] [--json]
    keryn dast ownership mint <origin-or-host> --out <new-file> [--json]
    keryn dast ownership check <challenge.json> --out <new-directory> [--json]
    keryn dast nuclei <profile.json|template.yaml> --ownership <challenge.json> --out <new-directory> [--target <url>] [--timeout <seconds>] [--max-requests <n>] [--json]
    plan prints what a test would cover (scope, sign-in, rate, modules, an estimate) and sends nothing. test runs it incrementally: the surface is
    fingerprinted (URLs, responses, module and engine versions), so an unchanged one does no work (zero requests, "Unchanged since <date> . 0 new URLs
    tested") and a changed one tests only the delta, carrying earlier results with their provenance. Secrets come from the environment, never argv.
    --include/--exclude match path prefixes or * globs on every spelling a server may map a path to (escaped letters decoded,
    repeated slashes collapsed, dot segments resolved); exclude wins if any spelling hits it. Matching is case-sensitive.
    --module crawl follows <a href> links only. A page with script bundles and no links is reported as script-rendered navigation
    not crawled, and test exits 3; plan shows the same limit from the last run.
    nuclei requires fresh ownership. It admits public JSON profiles or one-GET YAML templates with body word/status matchers and matches
    YAML needs --target; raw requests, multiple paths, payloads, headers, DSL and other capabilities are refused before probes.
    It runs in the included keryn-nuclei module. Exit 1 matched, 3 incomplete.
    A query-differential profile (keryn.dev/nuclei-query-differential/v1) replaces one query parameter's value with literal true/false
    pairs and compares status and a masked body against a doubled baseline and a closing control, on 1 or 2 trials (at most 12 GETs a
    trial, --max-requests total, default 24). Exit 1 suspected differential (a lead, not a confirmed finding), 0 no supported signal,
    3 incomplete. Timing is not read; reflection or error text alone is not a signal.
    boundaries reads an existing HAR offline and sends nothing. --policy <policy.json> (keryn.dev/capture-boundaries/v1) names, by zero-based
    entry index, the redirect hops whose credential headers must not reach an unapproved origin and the test scopes whose private
    markers must not appear in another scope's responses. Exit 1 a boundary was crossed, 3 the capture cannot show it (a missing
    hop, a redacted value, no decoded body). Credential values and markers stay in the input.
    scan invokes an already installed ZAP (2.17.0 or newer, automation add-on 0.58.0 or newer) Automation Framework against one explicit HTTP(S) target scope. Default spider plus
    passive analysis still sends HTTP requests; --active additionally enables active attack checks. Use only an authorized target.
    Without --ajax, one more GET of the target page checks for script-rendered navigation the spider cannot follow; if found, the run
    is incomplete (exit 3) and says so. --ajax also runs ZAP's AJAX spider in the same context and time budget, driving a headless
    Chrome, Chromium or Firefox already on PATH (1 browser, depth 5, at most 50 crawl states, no random input). It needs the
    spiderAjax, selenium and webdriver add-ons in the ZAP install; anything missing fails before scanning. Nothing is downloaded.
    KERYN_ZAP_CHROMEDRIVER / KERYN_ZAP_GECKODRIVER point ZAP at an installed driver matching the browser; a browser that does not
    start fails the run with the reason (for example a driver built for another Chrome version), never a clean pass.
    ownership mint <origin-or-host> --out <new-file> creates a random local challenge; publish the TXT/file token it prints.
    ownership check <challenge.json> --out <new-directory> checks its current publication and writes proof evidence.
    --active requires --ownership <challenge.json>; ownership is rechecked immediately before execution, never trusted from a cached receipt.
    --strength low|medium|high (with --active, default low) sets how many requests each attack rule spends on a parameter. Low is quick
    and misses what needs more than a rule's first payloads (on the Juice Shop lab only medium or higher finds the search SQL injection);
    medium and high send several times more requests in the same time budget, so rules ZAP cuts short are named and the run exits 3.
    --seed <seeds.json> (with --active) names requests no crawl reaches, such as a JSON login call made from script or an unlinked path:
    {"schema": "keryn.dev/dast-seeds/v1", "requests": [{"method": "POST", "path": "/api/login", "contentType":
    "application/x-www-form-urlencoded", "body": "email=a%40example.com&password=x"}, {"path": "/metrics"}]}. Each is sent once after the crawl and its
    parameters are attacked with the rest. At most 50 requests, paths under the target only, no headers or credentials in the file.
    --test-run <id> sends the header x-keryn-test-run-id: <id> on every request of the scan. An application running a Keryn Runtime
    agent records it with each flow of request input it observes; keryn ledger build then puts on each web finding the code location
    its input was observed reaching. The id is yours to choose (letters, digits, . _ -), is not a credential, and is in provenance.json.
    --active also runs Open MCP Server Detection (ZAP rule 100045, ported): the MCP initialize probes of the upstream script that lie
    inside the target subtree (/app covers /app/..., not /mcp at the host root), without credentials, stopping at the first MCP server
    that answers; mcp-probe.json lists every probe and what happened to it.
    --active also runs Keryn's exposure checks: plain GETs of the target, the GET seeds, three well-known management paths under the
    target (actuator, actuator/prometheus, metrics) and one path beside each declared one that should not exist, read for a generated
    directory listing (CWE-548), Prometheus metrics (CWE-538), an error page that prints a stack trace (CWE-209) and a Spring Boot
    Actuator index or environment (CWE-538). At most 24 URLs, each requested without credentials and, with --auth, again with the
    scan's header (never a path the file excludes); a metrics or management page only the session sees is reported as INFO.
    exposure-probe.json lists each request and what it showed.
    --auth <auth.json> adds one reviewed header (its value from an environment variable, sent through ZAP's own ZAP_AUTH_HEADER mechanism to the target host only, never in the plan or argv), a same-scope identity poll, and authentication-statistics gates.
    The file may also name "exclude": ["/app/logout"] (1 to 20 paths, each with everything under it, that no job requests: the sign-out
    link would end the one session ZAP holds) and "start": "/app/home" (the page a signed-in user lands on; the spiders start there
    when the target root is not a page once signed in). Both must lie inside the target; scope is unchanged.
    Instead of headers, the file may hold a session (keryn.dev/ai-session/v1): Keryn logs in with environment-referenced credentials,
    hands the header to ZAP the same way, logs out after the scan (session.json records the outcome, never the value), and refuses a
    session that would expire inside the scan's time budget, since ZAP cannot refresh it. ZAP's own state (its session database) is
    removed after every scan; zap.log is kept.
    --expect-build <web.zip> hashes captured same-origin assets against an explicit web build; mismatch exits 1, incomplete evidence exits 3.
    asset-correlation.json and run.json include spider discovery and captured request counts; raw HAR stays in the private run directory.
    Only observed assets are compared; uncrawled lazy assets and application-wide coverage are not established.
    The generated plan and execution receipt are saved. No service, browser or scanner is installed automatically; only --ajax starts a browser.
    import reads Burp or ZAP XML locally. --target declares provenance; it does not fetch the target. Completion defaults unknown.
    --out must be new or empty. Raw evidence is preserved; out-of-scope findings make coverage incomplete rather than disappearing.
    --timeout <seconds> (scan, default 300, max 3600); --fail-on error|warning|info|none (default error); --json prints the receipt.
    Exit 0 pass | 1 findings | 2 usage | 3 partial/unknown completion | 4 execution/normalization failure.
    Terminal window
    # See scope and estimate before sending anything.
    keryn dast plan https://staging.example.com --spec openapi.json
    Code Meaning
    0 planned
    2 usage error