Test a running web app (DAST)
Look at an application while it runs, not only at its source: find missing security headers, leaky cookies and the other things a running site shows, and turn the result into the same findings, SARIF and exit codes as the rest of Keryn.
Keryn has three ways in, from the one that touches nothing to the one that attacks:
| Way in | Command | Does it send requests to a site? |
|---|---|---|
| Passive web rules over a capture you already have | keryn import <capture> |
No. It reads a saved HAR or proxy export. |
| Scoped ZAP scan, passive mode | keryn dast scan <url> --out <dir> |
Yes: ZAP spiders the target and sends ordinary requests. |
| Scoped ZAP scan, active mode | keryn dast scan <url> --active --ownership owner.json --out <dir> |
Yes: the same, plus active attack checks. |
| Import a finished Burp or ZAP report | keryn dast import <report.xml> ... |
No. It reads the file. |
Before you start
Section titled “Before you start”- For
dast scan: ZAP installed on the machine that runs the scan. Keryn runs thezap.shit finds (or the file you give with--executable) with ZAP’s Automation Framework. It never installs ZAP, a browser, a driver or a ZAP add-on, and never starts Docker. Only--ajaxstarts a browser, one that is already installed (see single-page apps). - For
dast import: a Burp issues export or a ZAP XML report (traditional-xml) of a scan you ran yourself. - A target as an HTTP or HTTPS URL without credentials, query string or fragment. A path is allowed and becomes the scope (see below).
- Where results go:
--outtakes a directory that is new or empty.
1. Check captured traffic with the passive rules (no requests)
Section titled “1. Check captured traffic with the passive rules (no requests)”If you can save a HAR from your browser’s network tab (with response bodies), a Burp proxy-history export or a ZAP message export, Keryn can check that traffic offline.
keryn import session.har --fail-on warningThe rules are Rust ports of the OWASP ZAP passive scan rules. They read responses that were already captured; the command sends nothing to your site, and nothing to Keryn. A capture is recognised by its shape. A ZAP alert report or a Burp issues export is a scanner report, not traffic, and is read by the same command as a report (use --parser to force the report parsers).
What you get:
- One finding per deduplicated passive result, on the URL it was observed at, with rule ids like
zap-passive:10038-1and the engine namedkeryn-passive. - Severity follows ZAP: High is an error, Medium a warning, Low and Informational are info. Informational results are audit findings and never gate. With the default
--fail-on error, only High findings gate. - Cookie values,
Authorizationheaders, decoded Basic credentials and session ids in URLs are redacted in every finding. - Coverage lists the rules that could not run because the capture lacks their evidence (a HAR saved without bodies, for example). They appear as limitations, not as passes.
Keryn’s own measurement against the pinned ZAP rule classes, and what it covers, is on the evals page. Keryn is not affiliated with or endorsed by the ZAP project.
2. Run a scoped ZAP scan
Section titled “2. Run a scoped ZAP scan”keryn dast scan https://staging.example.com/app --out out/dastThis writes a plan for ZAP’s Automation Framework, runs it, and imports ZAP’s XML report. What the plan does, exactly:
- Scope. One context. Only URLs under the origin and path you gave are in scope (
https://staging.example.com/appand below; the path is a prefix, so/applicationis not included). - Spider. At most depth 5, 20 children per node, 2 threads, no form submission, no robots.txt or sitemap parsing. The scan fails its own check if the spider finds no URL.
- Passive analysis of everything the spider fetched, then the report.
- Script-rendered pages. The spider follows links in the HTML; it does not run JavaScript. Keryn also makes one GET of the target page, without credentials. If that page loads script bundles and has no links, its navigation is built in the browser and was not crawled: the result names the page as a coverage limitation and the scan exits 3 instead of passing on one URL.
- Time.
--timeout <seconds>defaults to 300 and can be at most 3600. The spider’s duration is a share of it; the process is stopped when the budget runs out. - Output. The process output is capped at 1 MiB; a report must be a regular file of 1 byte to 32 MiB.
Passive mode is not silent. ZAP still sends the spider’s requests to the target; “passive” means no attack payloads.
Single-page apps
Section titled “Single-page apps”Add --ajax to crawl an app whose links are created by JavaScript. ZAP’s AJAX spider then drives a headless Chrome, Chromium or Firefox that is already on the machine, inside the same scope and time budget: one browser, depth 5, at most 50 crawl states, no random form input. The browser runs on the machine that runs the scan and loads the target’s own scripts.
It needs the spiderAjax, selenium and a webdriver* add-on in the ZAP install, and a browser on PATH. If any of these is missing, the scan stops before sending anything and names what is missing. ZAP’s bundled driver must match the installed browser. If it does not, set KERYN_ZAP_CHROMEDRIVER (or KERYN_ZAP_GECKODRIVER) to a matching driver you installed. A browser that does not start fails the scan with the reason; it never counts as a clean crawl. keryn ci --dast-ajax passes the flag to the DAST stage.
Active mode
Section titled “Active mode”Mint a challenge locally, publish its token using the DNS TXT or well-known file instructions it prints, then check the proof. Each active scan verifies the proof again.
keryn dast ownership mint https://staging.example.com --out owner.jsonAfter publishing the token:
keryn dast ownership check owner.json --out out/ownershipkeryn dast scan https://staging.example.com/app --active --ownership owner.json --out out/dast-active--active adds ZAP’s active scan to the plan: strength Low, threshold Medium, 2 threads per host, 100 ms delay between requests, at most 1 minute per rule. These are the limits Keryn sets; there is no option to raise them. Active checks send attack requests such as injection attempts. Run them only against a copy you can afford to break.
Authenticated scans
Section titled “Authenticated scans”The --auth file names exactly one header by environment variable, never by value, and says how to prove the session works. Keryn hands that header to ZAP through ZAP’s own environment variables for the target’s host name, so neither the value nor the variable’s name appears in the plan, the command line or the evidence:
{ "schema": "keryn.dev/zap-auth/v1", "headers": { "authorization": { "env": "STAGING_TOKEN" } }, "verification": { "path": "/app/api/me", "identityMarker": "user@example.com", "loggedOutMarker": "Please sign in" }}export STAGING_TOKEN='...'keryn dast scan https://staging.example.com/app --auth zap-auth.json --out out/dast-auth- Exactly one header; a file with more is refused. Hop-by-hop and browser-controlled headers (
host,origin,referer,content-length,proxy-*,sec-*and a few others) are refused. verification.pathmust be inside the target scope.identityMarker(8 to 512 characters, literal text) must appear in the response when the session works;loggedOutMarkeris optional.- Keryn adds checks before and after the scan: the authenticated state must be seen, with no unknown and no logged-out state. If the session expires mid-scan, the run fails instead of reporting an unauthenticated scan as an authenticated one.
- The header values are read from the environment, never written to the plan, and replaced by
[REDACTED]in ZAP’s captured output. - ZAP’s own working state (its session database records the requests it sent, header included) is deleted after the scan;
zap.logis kept.
Logging in first
Section titled “Logging in first”If the app issues short-lived tokens from a login request, put a session in the file instead of headers. Keryn sends the login with credentials named by environment variable, gives the resulting header to ZAP the same way, and logs out after the scan:
{ "schema": "keryn.dev/zap-auth/v1", "session": { "schema": "keryn.dev/ai-session/v1", "acquire": { "request": { "method": "POST", "path": "/login" }, "credentials": { "username": { "env": "APP_USER" }, "password": { "env": "APP_PASSWORD" } }, "extract": { "from": "json", "pointer": "/accessToken" }, "expiresInPointer": "/expiresIn" }, "header": { "name": "authorization", "prefix": "Bearer " }, "authLoss": { "status": [401] }, "maxRefreshes": 0, "logout": { "request": { "method": "POST", "path": "/logout" }, "checks": [{ "kind": "status", "equals": 200 }] } }, "verification": { "path": "/app/api/me", "identityMarker": "user@example.com", "loggedOutMarker": "Please sign in" }}export APP_USER='user@example.com' APP_PASSWORD='...'keryn dast scan https://staging.example.com/app --auth zap-session.json --out out/dast-session- The login and logout go to the target’s origin only; a redirect is refused.
- ZAP cannot renew a session during a scan. If the server says the session expires before the scan’s time limit (
--timeout), Keryn logs out and stops before ZAP starts; lower--timeoutor lengthen the session. session.jsonin the run directory records the header name, the session lifetime and whether logout worked. No token, password or cookie value is written anywhere.- It is the same session format that actors in AI security tests accept.
3. Import a Burp or ZAP report
Section titled “3. Import a Burp or ZAP report”If a scan already ran in your own tooling, bring the result in without scanning again.
keryn dast import zap-report.xml --parser zap \ --target https://staging.example.com/app --completion complete --out out/dast-import--parser is burp or zap. --target is a statement of what the report covers; Keryn does not fetch it. --completion is what you say about the original scan: complete, partial, unknown or failed. The default is unknown, because an export of issues does not show whether the scan finished.
The import checks that the file is the right kind of document (a Burp issues export or a ZAP OWASPZAPReport) and is 1 byte to 32 MiB. Findings whose URL lies outside the declared target are kept for review, counted, and make coverage incomplete.
4. In CI
Section titled “4. In CI”keryn ci can run the same stages in one call, each with its own artifacts, and combine the exit codes. Only the analyzers you ask for run.
keryn ci . --out out/ci --dast-url https://staging.example.com/app--dast-url <url>runs the ZAP scan in passive mode; add--dast-active --dast-ownership owner.jsonfor active mode and--dast-auth <auth.json>for the authenticated variant.--dast-report <report.xml> --dast-url <url> --dast-parser burp|zapimports a report instead of scanning;--dast-completionsets the completion statement.--dast-activeand--dast-authcannot be combined with--dast-report.
The general CI shape, pinning and platform recipes are in Add Keryn to CI. Source analysis is in static analysis and dependencies in software composition.
What you get
Section titled “What you get”For each of dast scan and dast import, in the --out directory:
raw-report: the scanner’s report as received, with its SHA-256 in the receipt.result.json,results.sarif,summary.md: the normalised findings, a SARIF 2.1.0 file for code-scanning upload, and a short summary.provenance.json(and for a scan,execution.jsonwith the saved plan’s digest and the mode): where the report came from, who declared the target and the completion, and how many locations were out of scope.run.json: a receipt that lists every artifact with its digest and the gate decision.
Every finding says it came from a DAST run and carries that provenance. Findings sit at the lower rungs of the proof ladder: a scanner saw a behaviour on a URL. They are not reproductions.
The gate uses --fail-on error|warning|info|none (default error).
| Exit | Meaning |
|---|---|
| 0 | pass |
| 1 | findings at or above --fail-on |
| 2 | usage error |
| 3 | the scan is partial, or an imported report’s completion is unknown or partial |
| 4 | ZAP failed, timed out, exceeded its output budget or produced no usable report |
Note the default for an import: with --completion left at unknown, a report with no findings still exits 3, not 0. Say complete only when you know the original scan was complete.
What leaves your machine
Section titled “What leaves your machine”keryn import <capture>andkeryn dast importread local files. Nothing is sent anywhere, and a report is not fetched or re-uploaded.keryn dast scansends HTTP requests from ZAP, on your machine, to the target you named and nowhere else. No request goes to Keryn, and your findings and the report are not sent to Keryn.- ZAP itself is a separate program with its own settings, and Keryn does not control what else it does on the network. What Keryn does is give it a plan with one target scope, run it with a fresh home directory inside the run folder, and run no other job than the spider, the optional active scan and the report.
Limits
Section titled “Limits”- DAST finds what a scanner can reach from the URL you gave. An uncrawled page, a login the scan did not complete, or a feature behind a form is not covered; the coverage statement says so rather than implying a pass.
- A scan does not establish that the tested deployment matches your source. The target and, for imports, the completion are what you declared.
- The ZAP-based path needs ZAP; the passive-rules path needs a capture with the evidence the rules read.
keryn dast nuclei <profile.json> --ownership owner.json --out <dir>runs the Nuclei-compatible engine measured against the Nuclei reference (Nuclei results) for one public profile (keryn/nuclei-public/1JSON): one bounded GET, no credentials or redirects, matched by keryn-nuclei. It needs a CLI built with the opt-in Nuclei module and otherwise says so and sends nothing. Template YAML and multi-request templates do not run.- Other scanners are supported only as imports (Burp, ZAP). There is no adapter that drives them.
- Test the AI-specific boundaries of the app (tenant isolation, tool authorisation): test AI security boundaries.
- Put it in the pipeline with the other checks: Add Keryn to CI.
- Look at the source for the same app: static analysis and dependencies.