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 import <report.xml> --parser burp|zap --target <application-url> --out <new-directory> [--completion complete|partial|unknown|failed]Options
Section titled “Options”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.Examples
Section titled “Examples”# Gate a report from another run.keryn dast import zap.xml --parser zap --target https://staging.example.com --out out/dastExit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
| 0 | pass |
| 1 | findings or a requested change gate |
| 2 | usage error or invalid input |
| 3 | incomplete or unknown completion |
| 4 | execution or normalization failure |