# Test a running web app (DAST)

> Check captured traffic with the passive web rules, run a scoped ZAP scan against a target you own, or import a Burp or ZAP report, and gate on the result.

Source: https://keryn.dev/docs/guides/dast/

## Goal

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. |

> **Note: In the next release**
> `keryn dast`, the passive web rules in `keryn import`, and the `--dast-*` options of `keryn ci` are not in Keryn 0.5.2. Run `keryn dast --help` and `keryn ci --help` on the version you have to see what it supports.

> **Caution: Only test what you own or may test**
> `keryn dast scan` talks to the target you name. Point it only at systems you own or have written permission to test. Active mode sends attack payloads and can change data or cause load; use a staging copy with disposable data. Active ZAP and Nuclei require fresh published ownership proof for the exact origin; permission to test and the safety of the target remain your responsibility.

## Before you start

- For `dast scan`: ZAP installed on the machine that runs the scan. Keryn runs the `zap.sh` it 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 `--ajax` starts a browser, one that is already installed (see [single-page apps](#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: `--out` takes a directory that is new or empty.

## 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.

```sh
keryn import session.har --fail-on warning
```

The 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-1` and the engine named `keryn-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, `Authorization` headers, decoded Basic credentials and session ids in URLs are redacted in every finding.
- [Coverage](https://keryn.dev/docs/concepts/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](https://keryn.dev/evals/). Keryn is not affiliated with or endorsed by the ZAP project.

## 2. Run a scoped ZAP scan

```sh
keryn dast scan https://staging.example.com/app --out out/dast
```

This 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/app` and below; the path is a prefix, so `/application` is 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

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

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.

```sh
keryn dast ownership mint https://staging.example.com --out owner.json
```

After publishing the token:

```sh
keryn dast ownership check owner.json --out out/ownership
```

```sh
keryn 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

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:

```json
{
  "schema": "keryn.dev/zap-auth/v1",
  "headers": { "authorization": { "env": "STAGING_TOKEN" } },
  "verification": {
    "path": "/app/api/me",
    "identityMarker": "user@example.com",
    "loggedOutMarker": "Please sign in"
  }
}
```

```sh
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.path` must be inside the target scope. `identityMarker` (8 to 512 characters, literal text) must appear in the response when the session works; `loggedOutMarker` is 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.log` is kept.

#### 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:

```json
{
  "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" }
}
```

```sh
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 `--timeout` or lengthen the session.
- `session.json` in 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](https://keryn.dev/docs/guides/ai-testing/) accept.

## 3. Import a Burp or ZAP report

If a scan already ran in your own tooling, bring the result in without scanning again.

```sh
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

`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.

```sh
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.json` for active mode and `--dast-auth <auth.json>` for the authenticated variant.
- `--dast-report <report.xml> --dast-url <url> --dast-parser burp|zap` imports a report instead of scanning; `--dast-completion` sets the completion statement.
- `--dast-active` and `--dast-auth` cannot be combined with `--dast-report`.

The general CI shape, pinning and platform recipes are in [Add Keryn to CI](https://keryn.dev/docs/guides/ci/). Source analysis is in [static analysis](https://keryn.dev/docs/guides/sast/) and dependencies in [software composition](https://keryn.dev/docs/guides/sca/).

## 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.json` with 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](https://keryn.dev/docs/concepts/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

- `keryn import <capture>` and `keryn dast import` read local files. Nothing is sent anywhere, and a report is not fetched or re-uploaded.
- `keryn dast scan` sends 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

- 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](https://keryn.dev/docs/concepts/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](https://keryn.dev/evals/nuclei/)) for one public profile (`keryn/nuclei-public/1` JSON): 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.

## Next

- Test the AI-specific boundaries of the app (tenant isolation, tool authorisation): [test AI security boundaries](https://keryn.dev/docs/guides/ai-testing/).
- Put it in the pipeline with the other checks: [Add Keryn to CI](https://keryn.dev/docs/guides/ci/).
- Look at the source for the same app: [static analysis](https://keryn.dev/docs/guides/sast/) and [dependencies](https://keryn.dev/docs/guides/sca/).
