> For the complete documentation index, see [llms.txt](https://docs.xygeni.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner.md).

# DAST Scanner

## Table of Contents

1. [Purpose](#purpose)
2. [Installation](#installation)
3. [Quick Start](#quick_start)
4. [Usage](#usage)
5. [Discovering the Application](#discovery)
6. [Built-in Scan Profiles](#profiles)
7. [Authentication](#authentication)
8. [Corporate Proxies and TLS Inspection](#proxy_tls)
9. [CI/CD Integration](#cicd)
10. [Command Reference](#command_reference)
11. [Exit Codes](#exit_codes)

### Purpose <a href="#purpose" id="purpose"></a>

The **DAST Scanner** (`xy-dast`) performs automated **dynamic security testing** of running web applications and REST APIs. It tests applications from the outside -- simulating real-world attacks against live endpoints -- to identify vulnerabilities that are only exploitable at runtime.

The scanner supports different application types:

* **Traditional** server-rendered web apps (PHP, JSP, ASP.NET)
* **SPA** JavaScript-heavy Single Page Applications (React, Angular, Vue)
* **REST API** with OpenAPI/Swagger specifications or Postman collections
* **GraphQL** APIs (schema import or introspection)
* **SOAP** web services (WSDL import)
* **CMS** platforms (WordPress, Drupal, Joomla)

You choose *what* the target is and *how hard* to scan it on **two independent axes**: a **tech-stack profile** (`--profile`) and a **scan intensity** (`--intensity`). They compose freely — e.g. a deep scan of an SPA is `--profile spa --intensity deep`. See [Built-in Scan Profiles](#profiles).

What the scan can attack depends on what it finds: imported endpoint definitions, a link spider, and a real browser that crawls the pages scripts build. See [Discovering the Application](#discovery).

### Installation <a href="#installation" id="installation"></a>

The DAST scanner is distributed as a Docker image (`xygeni/xy-dast`). Install a lightweight wrapper directly from the image — no separate download is needed. The wrapper is a small, signed script that delegates to `docker compose run`, so once installed you invoke `xy-dast` as if it were a native command.

#### One-command install (recommended)

From 6.14.0 there is an installer that does all of the below for you: it finds Docker, pulls the image, **verifies its signature**, creates the install directory, and pins the wrapper to the exact image digest it verified. On a host with only Podman it stops and tells you to install Docker, rather than installing a wrapper that could not run.

{% tabs %}
{% tab title="Linux / macOS" %}

```bash
curl -fsSL https://get.xygeni.io/latest/dast/get-dast.sh | sh

# To pass options through the pipe, separate them with `-s --`:
curl -fsSL https://get.xygeni.io/latest/dast/get-dast.sh | sh -s -- -d /usr/local/bin --add-to-path
```

Installs into the first writable of `$HOME/.local/bin` or a `$HOME/bin` already on your `PATH`, falling back to `$HOME/.local/bin`.
{% endtab %}

{% tab title="Windows" %}

```powershell
iwr -useb https://get.xygeni.io/latest/dast/get-dast.ps1 | iex

# `iex` cannot pass parameters. To use any, download the script and run the file:
iwr -useb https://get.xygeni.io/latest/dast/get-dast.ps1 -OutFile get-dast.ps1
.\get-dast.ps1 -InstallDir C:\Tools\bin -AddToPath
```

Installs into `$HOME\.local\bin` unless `-InstallDir` says otherwise.
{% endtab %}
{% endtabs %}

| Linux / macOS             | Windows                       | Effect                                                        |
| ------------------------- | ----------------------------- | ------------------------------------------------------------- |
| `-d <dir>`                | `-InstallDir <dir>`           | Install somewhere other than the default                      |
| `-i <tag\|sha256:digest>` | `-Image <tag\|sha256:digest>` | Pin a version instead of `latest`                             |
| `--add-to-path`           | `-AddToPath`                  | Add the install directory to your shell profile / user `PATH` |
| `--prune`                 | `-Prune`                      | Also delete `xy-dast` wrappers found elsewhere on `PATH`      |
| `--allow-unverified`      | `-AllowUnverified`            | Proceed when no verifier is available                         |

To check the installer itself before running it, compare it against the digest published in the `xygeni/xygeni` repository:

{% tabs %}
{% tab title="Linux / macOS" %}

```bash
curl -fsSLO https://get.xygeni.io/latest/dast/get-dast.sh
h=$(curl -fsS https://raw.githubusercontent.com/xygeni/xygeni/main/checksum/latest/get-dast.sh.sha256)
echo "$h get-dast.sh" | sha256sum -c
sh ./get-dast.sh
```

{% endtab %}

{% tab title="Windows" %}

```powershell
iwr -useb https://get.xygeni.io/latest/dast/get-dast.ps1 -OutFile get-dast.ps1
$h = (iwr -useb https://raw.githubusercontent.com/xygeni/xygeni/main/checksum/latest/get-dast.ps1.sha256).Content.Trim()
(Get-FileHash .\get-dast.ps1 -Algorithm SHA256).Hash -eq $h.ToUpper()
.\get-dast.ps1
```

{% endtab %}
{% endtabs %}

The digest lives in a different place from the script it vouches for: an attacker would have to compromise both `get.xygeni.io` and the GitHub repository to pass this check.

A signature that **fails** verification always stops the install. If no verifier is available at all (no `cosign`, no Docker-run fallback), the install reports that it could not verify and continues only when you pass `--allow-unverified`.

#### Keeping it up to date

```bash
xy-dast update                       # pull, verify, re-pin to the latest
xy-dast update --version 6.14.0      # or a specific tag / sha256: digest
```

`update` verifies the new image exactly as the installer does, so it fails rather than re-pin to something it could not check. `--allow-unverified` covers the case where no verifier is available; a signature that *fails* is always fatal.

`update` moves the wrapper and the image together. That matters: the two speak a versioned calling contract, and an image newer than its wrapper refuses to run rather than mis-resolve your local file paths — which used to surface as a confusing "file not found" for a file that was plainly there.

#### Manual install

The step-by-step route below works with any released image, and is the one to use where the installer cannot reach the internet.

**Requirements**

* **Docker Engine 20.10+** (or Docker Desktop) with Compose v2 — i.e. the `docker compose ...` subcommand. The legacy `docker-compose` v1 binary is not supported, and Podman is not a substitute: the wrapper drives `docker compose`, which Podman does not provide.
* A directory on your `PATH` to drop the wrapper into. This guide uses `~/.local/bin` (Linux/macOS) and `%USERPROFILE%\.local\bin` (Windows).

#### Step 1 — Create the install directory and ensure it is on your `PATH`

This is the most common source of "command not found: xy-dast" issues. The install directory **must exist before the install command** (Docker creates it as `root` if it does not, which then fails to write), and it **must be on your `PATH`** for the short `xy-dast` command to work.

{% hint style="warning" %}
On **Windows** and **macOS** the `~/.local/bin` directory is **not** on the default `PATH`. On most Linux distributions it *is* added by `~/.profile`, but **only if the directory exists at login** — if you create it now in an existing shell, you still need to add it to `PATH` for the current session (or open a new login shell after creating it).
{% endhint %}

{% tabs %}
{% tab title="Linux" %}

```bash
# 1. Create the directory (idempotent)
mkdir -p ~/.local/bin

# 2. Make sure it is on PATH for the current shell
case ":$PATH:" in *":$HOME/.local/bin:"*) ;; *) export PATH="$HOME/.local/bin:$PATH" ;; esac

# 3. Persist for future shells (only needed once per shell rc)
grep -q '\.local/bin' ~/.bashrc 2>/dev/null \
  || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
# zsh users: replace ~/.bashrc with ~/.zshrc
```

Verify:

```bash
echo "$PATH" | tr ':' '\n' | grep -F "$HOME/.local/bin"   # should print the path
```

{% endtab %}

{% tab title="macOS" %}

```bash
# 1. Create the directory
mkdir -p ~/.local/bin

# 2. Add to PATH for the current shell
export PATH="$HOME/.local/bin:$PATH"

# 3. Persist for future shells (zsh is the default since macOS Catalina)
grep -q '\.local/bin' ~/.zshrc 2>/dev/null \
  || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
# bash users: replace ~/.zshrc with ~/.bash_profile
```

Verify:

```bash
echo "$PATH" | tr ':' '\n' | grep -F "$HOME/.local/bin"
```

{% endtab %}

{% tab title="Windows (PowerShell)" %}

```powershell
# 1. Create the directory
New-Item -ItemType Directory -Force -Path "$HOME\.local\bin" | Out-Null

# 2. Add to PATH for the current shell
$env:PATH = "$HOME\.local\bin;$env:PATH"

# 3. Persist for future shells (User scope, no admin needed)
$userPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
if ($userPath -notlike "*$HOME\.local\bin*") {
  [Environment]::SetEnvironmentVariable('PATH', "$HOME\.local\bin;$userPath", 'User')
}
```

Verify (open a **new** PowerShell window after persisting):

```powershell
$env:PATH -split ';' | Select-String '\.local\\bin'
```

{% hint style="info" %}
The Windows wrapper is a PowerShell script (`xy-dast.ps1`) signed with an Authenticode certificate. If your execution policy blocks running scripts, run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once.
{% endhint %}
{% endtab %}
{% endtabs %}

#### Step 2 — Install the wrapper from the Docker image

The image's `install` subcommand drops two files into the mounted directory: the `xy-dast` wrapper script itself and a sidecar `xy-dast-compose.yml` that holds the image reference, environment forwarding, and runtime parameters.

{% tabs %}
{% tab title="Linux / macOS" %}

```bash
docker run --rm -v ~/.local/bin:/mnt/install xygeni/xy-dast install
```

{% endtab %}

{% tab title="Windows (PowerShell)" %}

```powershell
docker run --rm -v "${HOME}\.local\bin:/mnt/install" xygeni/xy-dast install --powershell
```

`--powershell` produces the signed `.ps1` wrapper (and matching sidecar) instead of the bash one.
{% endtab %}
{% endtabs %}

Verify:

```bash
xy-dast --version
```

If you get `command not found` (or `not recognized as ... cmdlet`), revisit Step 1 — the directory is almost certainly not on your `PATH` yet.

#### Quick install vs. secure install

The plain `install` command above is a **quick install**: convenient for desktop and ad-hoc use. The wrapper itself is signed at release time, but the image reference written into `xy-dast-compose.yml` is a mutable tag (e.g. `xygeni/xy-dast:6.7.0`).

For production environments — and any setting that needs defence-in-depth against registry-side supply-chain attacks — use the **secure install** flow, which pins the image to its immutable digest and verifies the cosign (Sigstore keyless) signature before installing:

```bash
TAG=xygeni/xy-dast:6.7.0     # or :latest

# 1. Pull the image so the digest is in your local image cache.
docker pull "$TAG"

# 2. Verify the cosign signature, signed by the xy-dast GitHub Actions identity.
cosign verify \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp 'github\.com/xygeni/xy-dast' \
  "$TAG"

# 3. Resolve the immutable digest the registry served us.
DIGEST=$(docker image inspect "$TAG" --format '{{index .RepoDigests 0}}')

# 4. Install. --image rewrites only the `image:` line in xy-dast-compose.yml
#    to pin the resolved digest — wrapper bytes stay byte-identical.
docker run --rm -v ~/.local/bin:/mnt/install "$TAG" install --image "$DIGEST"
```

To upgrade later, repeat the four-step flow with the new version — or run `xy-dast update`, which pulls, verifies and re-pins the wrapper and the image together.

#### How the wrapper works

* It is a pre-built, byte-stable script signed at release time (Authenticode for `.ps1`); `install` copies it byte-exact so the signature is preserved.
* It delegates to `docker compose -f xy-dast-compose.yml run --rm xy-dast …`. Compose handles env forwarding (`XYGENI_TOKEN`, `XYGENI_URL`, `XYGENI_DASHBOARD_URL`, `XYGENI_DAST_DIR`), `network_mode: host`, and `shm_size: 2gb`.
* When you pass `-o <file>`, the wrapper mounts the output directory into the container (read-write) so the report appears on your host filesystem.
* Local input files (`--openapi`, `--api-inventory`, `--postman`, `--graphql`, `--wsdl`, `--url-list`, `--client-cert`, `--auth-config`, `--session-file`, and a `--profile` file) are read from a **base directory** — your current directory by default, or set explicitly with `--base-dir`. It is mounted read-only, so paths must live under it; relative paths resolve against it. This also reaches files referenced *inside* a profile or auth config. Use a `--base-dir` that contains all your inputs, or pass URLs instead.
* It looks for the sidecar at `<wrapper-dir>/xy-dast-compose.yml` by default. Override the location with the `XY_DAST_COMPOSE_FILE` environment variable. To pin a different image, edit the `image:` line in the sidecar or re-run `install --image <ref>`.
* From release 6.23.0, the bash wrapper also runs from Git Bash, MSYS2 or Cygwin on Windows, with paths written either way (`C:\work\report.json` or `/c/work/report.json`). It turns off the shell's automatic path conversion for its own Docker call, which used to lose the `-o` output and fail to find input files. Run `xy-dast update` to get it.

### Quick Start <a href="#quick_start" id="quick_start"></a>

#### Let the scanner write your configuration

From 6.14.0, if you would rather be asked than read the options, run the guided setup:

```bash
xy-dast interactive
```

It asks about your target and writes a profile YAML, a ready-to-run command line, or both. Only relevant questions are asked — answering "REST API" skips the crawling questions — and every question has a default, so pressing `Enter` throughout still produces a working configuration. It can also probe the target and propose the profile matching what it finds.

Where a question offers a list, move with the arrow keys or `Tab`, press `1`-`9` to take an option outright, and `Enter` to accept the highlighted one. Single keys carry the commands: `b` back, `s` skip, `d` defaults for everything remaining, `q` quit without writing, `?` help. `Esc` swaps the list for a typed prompt.

At a typed question the same commands are written with a colon — `:b`, `:s`, `:d`, `:q` — and `?` still asks for help. The keys in use are always shown under the question, so there is nothing to memorise.

{% hint style="info" %}
The wizard never asks you to type a password or token. Where a credential is needed it asks for the **name of the environment variable** holding it and writes `${env:VAR}` into the profile, so the generated files are safe to commit.
{% endhint %}

Scan a web application:

```bash
xy-dast scan -u https://example.com
```

Results are uploaded to the Xygeni platform by default. To save a local report instead, use `-o`:

```bash
xy-dast scan -u https://example.com -o report.json
```

Scan a REST API with an OpenAPI specification:

```bash
xy-dast scan -u https://api.example.com \
  -p openapi \
  --openapi https://api.example.com/v3/api-docs \
  --bearer-token env:API_TOKEN
```

From release 6.22.0, a specification that uses schemas or path parameters it never declares (common in generated specifications) is repaired before the import instead of failing the scan.

Scan a REST API from a Postman collection (v2.x). Use a local file or a URL, and override collection variables with `--postman-vars`:

```bash
xy-dast scan -u https://api.example.com \
  --postman ./api.postman_collection.json \
  --postman-vars "baseUrl=https://api.example.com,apiKey=demo"
```

Scan a Single Page Application:

```bash
xy-dast scan -u https://app.example.com -p spa
```

Scan a GraphQL API:

```bash
# With schema URL
xy-dast scan -u https://api.example.com \
  -p graphql \
  --graphql https://api.example.com/graphql/schema

# With introspection (no schema needed)
xy-dast scan -u https://api.example.com -p graphql
```

An app that serves GraphQL next to its pages (a single-page app with a `/graphql` endpoint) keeps its own profile: set `graphqlEndpoint` in it, and the operations are imported by introspection whatever the profile extends. From release 6.23.0 this works with any profile, not only `graphql`. The scanner first checks that the endpoint answers introspection; if it refuses, the scan warns, records `dast.graphql.introspection: false`, and continues without the import (pass the schema with `--graphql` then).

```yaml
name: my-spa
extends: spa
graphqlEndpoint: /graphql
```

Scan a SOAP web service:

```bash
xy-dast scan -u https://api.example.com \
  --wsdl https://api.example.com/service?wsdl
```

Scan a REST API with OAuth2 (client credentials). The scanner obtains a token from the token endpoint before the scan and sends it as a bearer token on every request:

```bash
xy-dast scan -u https://api.example.com \
  --oauth2-token-url https://idp.example.com/oauth/token \
  --oauth2-client-id env:OAUTH_CLIENT_ID \
  --oauth2-client-secret env:OAUTH_CLIENT_SECRET \
  --oauth2-scope api.read
```

The `password` and `refresh_token` grants and advanced options are configured via a [profile](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner/dast-scanner-configuration.md).

Seed the scan from traffic you have already recorded with `--navigation`, so endpoints that crawling alone would miss are scanned too. The format is auto-detected: a recorded **browser navigation** — a **Selenium IDE** (`.side`) or a **Chrome DevTools Recorder** (`.json`) recording — is replayed in a real browser to generate the traffic; a recorded **HAR** (from browser DevTools, a proxy, or a test tool) is imported directly:

```bash
# A recorded browser navigation (replayed): Selenium IDE .side …
xy-dast scan -u https://app.example.com --navigation ./browse.side

# … or a Chrome DevTools Recorder export
xy-dast scan -u https://app.example.com --navigation ./recording.json

# A recorded HAR (imported; local file or URL)
xy-dast scan -u https://app.example.com --navigation ./recording.har
```

Use `--navigation-format selenium|chrome-devtools|har` to set the format explicitly when the extension is ambiguous (for example, a `.json` that is neither a DevTools recording nor a HAR).

A `.side` given to `--navigation` is **always** replayed and seeded — it is a navigation input, not a login method, so the profile `script.seedNavigation` setting does not apply to it (that setting gates a scripted *login* `.side`; see [Scripted Browser Login](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner/dast-scanner-configuration.md)). The navigation script and an optional scripted login are separate inputs: when both are given, a `.side` navigation is replayed in the same authenticated browser so it can reach gated pages. Only requests on the target's host are kept. Add `--navigation-only` to scan **only** the recorded endpoints (skipping the crawl).

### Usage <a href="#usage" id="usage"></a>

The DAST Scanner is launched using the `xy-dast scan [options]` command.

To view all available options, use the `--help` flag:

```bash
xy-dast scan --help
```

The most important options are:

* **Target URL** (`-u` or `--url`) -- the base URL of the application to scan (required).
* **Tech-stack profile** (`-p` or `--profile`) -- what the target is: `traditional`, `spa`, `openapi`, `graphql`, `soap`, `cms` or `blazor` (or a custom profile).
* **Scan intensity** (`--intensity`) -- how hard to scan: `quick`, `balanced` (default), `deep`, or `passive`. Overlays attack strength, durations, and CVE / deep-crawl on top of the tech profile.
* **OpenAPI spec** (`--openapi`) -- URL or file path to an OpenAPI/Swagger specification (for REST API scans).
* **API inventory** (`--api-inventory`) -- the endpoints Xygeni API Security discovered in the sources, imported like an OpenAPI specification. See [REST API from the Xygeni API Inventory](#api-inventory).
* **Postman collection** (`-pm` or `--postman`) -- URL or file path to a Postman v2.x collection; `--postman-vars` overrides its variables (`key=value`, comma-separated).
* **Recorded traffic** (`--navigation`) -- seed the scan from a recorded browser navigation (`.side`, replayed) or a recorded HAR (imported); `--navigation-only` scans only the recorded endpoints.
* **Output file** (`-o` or `--output`) -- path for the JSON report. Use `-` for stdout.
* **Project name** (`-n` or `--project-name`) -- identifies the project in the Xygeni platform.
* **Upload** -- reports are uploaded to the Xygeni backend by default. Disable with `--no-upload`.
* **Filtering** -- use `--exclude-rules` to skip noisy rules, or `--risk-threshold` to set a minimum severity.
* **Excluded URLs** (`--exclude`) -- regexes for URLs the scan must never request. See [Excluding URLs](#excluding-urls).

#### Custom Scan Settings

Override timing defaults directly from the command line:

```bash
xy-dast scan -u https://example.com \
  --spider-duration 15 \
  --browser-crawl-duration 10 \
  --active-scan-duration 30 \
  --timeout 90 \
  -o report.json
```

Durations accept `30s` / `5m` / `1h` (a bare number is minutes). A duration of **`0` means unlimited** (no timeout for that phase, or no overall cap for `--timeout`) — it never means "skip". Durations you set are used as they are; the [scan effort](#scan-effort) never scales them.

**Overall timeout.** From release 6.23.0, `--timeout` has no fixed default. Without it, the cap is the sum of the scan's phase budgets (crawls, passive-scan wait, every active-scan pass) plus 20% (at least 10 minutes), and never less than 60 minutes, so a longer scan effort is not cut short. A phase with no limit (`0`) counts as 60 minutes there, with a warning: only `--timeout 0` removes the overall limit. The deep crawl (`--crawl-timeout`) and the vulnerability check (`--vuln-check-timeout`) have their own timeouts.

To disable a phase, use an explicit flag — `--passive-only` (alias `--skip-active-scan`), `--skip-spider`, or `--skip-browser-crawl`:

```bash
# Passive-only scan (no active attacks)
xy-dast scan -u https://example.com --passive-only -o report.json

# Spider + passive only (skip the active scan and the browser crawl)
xy-dast scan -u https://example.com --passive-only --skip-browser-crawl -o report.json
```

`--browser-crawl-duration` and `--skip-browser-crawl` are the 6.23.0 names; the older `--ajax-spider-duration` and `--skip-ajax-spider` are still accepted.

For a production-safe scan packaged as a profile, use `--intensity passive` (crawl + passive analysis, no active attack payloads) with any tech base: `xy-dast scan -u https://app.example.com --profile spa --intensity passive`.

#### Filtering Results

```bash
# Exclude noisy rules by ID
xy-dast scan -u https://api.example.com \
  --exclude-rules 10094,10038 \
  -o report.json

# Only report findings at MEDIUM risk or above
xy-dast scan -u https://api.example.com \
  --risk-threshold MEDIUM \
  -o report.json

# Set attack strength
xy-dast scan -u https://example.com \
  --policy-strength LOW \
  -o report.json
```

#### Excluding URLs <a href="#excluding-urls" id="excluding-urls"></a>

`--exclude` (and a profile's `scope.excludePatterns`) takes regexes for URLs the scan must not request. From release 6.23.0 they are matched against the **whole URL, query included**, and every phase honours them: the crawl, the browser crawl, the deep crawl and the active scan do not send a matching URL, and the vulnerability check is not pointed at one. A pattern on a query parameter therefore works:

```bash
# Keep a change-password form that submits by GET from being sent
xy-dast scan -u https://app.example.com --exclude '.*password_new.*' -o report.json
```

* **Request bodies are not matched.** A form that POSTs its fields is kept out by its action path (`--exclude '.*/account/password([?#].*)?$'`), not by a field name.
* **The query now counts.** A pattern ending in a file extension, such as `.*\.pdf$`, now also stops `/download?file=a.pdf`. Anchor it on the path when only the file is meant: `.*\.pdf(\?.*)?$`.
* The static-file patterns the built-in profiles ship (`.*\.js$` and so on) only keep files out of the crawl: `/download?file=report.png` is still attacked.
* **Endpoint imports are filtered before they are imported**: OpenAPI operations (the [API inventory](#api-inventory)'s included), Postman requests and recorded HAR entries whose URL matches are removed, a WSDL port whose address matches is removed with all its operations, an excluded GraphQL endpoint skips the GraphQL import, and an [incremental scan](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner/incremental-scanning.md) does not request a changed endpoint that matches. An OpenAPI operation is matched against the URL the import sends, with its path parameters filled in, so `.*/users/[^/]+/password.*` matches `/users/{id}/password`. A source left with nothing to import is skipped, not reported as a failed import.
* **Not filtered**: the scan's login and its session checks, the final logout pass, and the OAuth2 token refresh. They send what you configured.
* A descriptor the scanner cannot read before the scan (an OpenAPI schema behind a form login) is imported unfiltered by query, with a warning.
* The deep crawler cannot use a pattern with lookaround, backreferences or possessive quantifiers: the scan warns, and the deep crawler may request matching URLs, though none of them reaches the rest of the scan.

The report records what was kept out: `dast.exclude.imports.removed` counts the endpoints removed from imports (the log names each source), and `dast.exclude.dropped` the requests stopped on their way out because only their query matched (a lower bound).

#### REST API from the Xygeni API Inventory <a href="#api-inventory" id="api-inventory"></a>

When the API publishes no specification, the endpoints that Xygeni [API Security](https://docs.xygeni.io/xygeni-products/api-security.md) discovers in its source code can be the endpoint source instead. Each one is imported like an OpenAPI operation, with its parameter types, defaults, allowed values and request body, so the active scan attacks it whether or not the crawl reaches it.

```bash
# 1. Discover the API endpoints in the sources (discovery only; nothing is uploaded)
xygeni apisecurity --discovery-only --dir ./my-api -f json -o apisec-inventory.json

# 2. Scan them
xy-dast scan -u https://api.example.com --api-inventory apisec-inventory.json
```

If the Xygeni scanner is installed alongside the DAST scanner, `--sources ./my-api` runs step 1 for you (unless `--api-inventory` is also given). That discovery is kept apart from the project's API Security baseline. Inside the Docker image the Xygeni scanner is not available, so the scan prints the command to run instead.

In a profile:

```yaml
apiInventory:
  file: ./apisec-inventory.json   # resolved relative to the profile file
```

* **Paths are relative to `-u`.** A service context path or module base path the route does not already carry is added, and the part of it `-u` already ends with is not repeated.
* **With `--openapi` as well**, an operation the specification already declares (same method, same path) is imported from the specification only.
* Constrained placeholders (`{id:[0-9]+}`, `{id:int}`, `{id?}`) are imported as `{id}`. Routes that cannot be requested as written (wildcards, regex alternations) are left out and listed in the log.
* **Logout and account-changing routes are left out** (logout, change password, delete account…): the import sends every endpoint as the scan's user, and one of them would end the session before the crawl.
* **Coverage is recorded** in `dast.inventory.endpoints.declared` / `.imported`, and `dast.inventory.source` is `file` or `sources`. An import that adds none of the endpoints fails the run, as an empty OpenAPI import does (`--lenient` continues). A file that is not an API Security report, or declares no endpoint, fails the command before anything is sent.
* [Incremental scans](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner/incremental-scanning.md) ignore it: the changed endpoints stay the only seed.

{% hint style="info" %}
`--api-inventory`, the `apiInventory` profile block and the inventory discovery with `--sources` are available from release 6.23.0. The wrapper reads a local `--api-inventory` file from the [base directory](#how-the-wrapper-works) from release 6.23.0: run `xy-dast update`.
{% endhint %}

#### Vulnerability Check

The `--vuln-check` option runs a template-based vulnerability scanner after the main scan completes. It checks the discovered endpoints against thousands of known CVEs, misconfigurations, and exposures — complementing the active scanning with signature-based detection.

```bash
xy-dast scan -u https://app.example.com --vuln-check
```

Both features can be combined for maximum coverage:

```bash
xy-dast scan -u https://app.example.com -n my-app \
  --deep-crawl --vuln-check
```

Vulnerability check findings appear in the same report as regular scan findings, with detector IDs prefixed by `vuln/` (e.g., `vuln/CVE-2021-44228`). See [DAST Detectors](https://docs.xygeni.io/xygeni-products/dast-security/dast-detectors.md) for details.

You can filter by severity and control the scan rate:

```bash
xy-dast scan -u https://app.example.com \
  --vuln-check \
  --vuln-check-severity critical,high \
  --vuln-check-timeout 5m
```

The `deep` intensity (`--intensity deep`) enables vulnerability check by default.

#### Out-of-Band Detection (OAST)

Some vulnerabilities never surface in the HTTP response — the proof is a *side effect*: the target opens a connection to a server you control. Blind SSRF, blind XXE, Log4Shell, blind SSTI and out-of-band XSS are detected this way. The scanner injects a payload and, if the target is vulnerable, it calls back to an **OAST server** (out-of-band application security testing). These rules are inert unless an OAST service is configured, so it is **off by default** — enable it explicitly:

```bash
# Same network: the scanner is its own OAST server (no external service)
xy-dast scan -u http://target:8080 --oast-service=callback -o report.json

# Public server (target needs outbound egress)
xy-dast scan -u https://app.example.com --oast-service=boast -o report.json

# Self-hosted server for an internal / air-gapped target
xy-dast scan -u https://app.internal \
  --oast-service=interactsh \
  --oast=https://oast.internal.example.com \
  --oast-token env:OAST_TOKEN \
  -o report.json
```

**Choosing a service.** An OAST callback only works if the target can reach the server *and* the scanner can observe the hit:

| Service      | Best for                                            | Reachability                                        |
| ------------ | --------------------------------------------------- | --------------------------------------------------- |
| `callback`   | Internal targets on the same network as the scanner | Target must route back to the **scanner** container |
| `boast`      | Public targets (zero-config public server)          | Target needs outbound internet egress               |
| `interactsh` | Public or **self-hosted**                           | Public egress, or a self-hosted server both reach   |

`callback` is the simplest and most reliable choice for internal targets and detects the HTTP-based out-of-band rules (blind SSRF, blind XXE). For a **self-hosted** OAST — the option for internal targets with no public egress that cannot route back to the scanner — run an [Interactsh](https://github.com/projectdiscovery/interactsh) server (version 1.3.0 or later) both the target and the scanner can reach, and point `--oast` at it. Tokens are read from the environment (`env:VAR` / `${env:VAR}`) and never logged. See [DAST Scanner Configuration](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner/dast-scanner-configuration.md#out-of-band-detection-oast) for the profile block, per-rule detection notes, and self-hosting guidance.

#### Automatic Profile Selection

If you are unsure which profile fits your target, use `--auto-profile` to let the scanner probe the application and select the most appropriate profile:

```bash
xy-dast scan -u https://app.example.com --auto-profile
```

This detects the technology stack (e.g., React SPA, REST API with OpenAPI, a WordPress/Drupal/Joomla site → `cms`, or an ASP.NET Core Blazor app → `blazor`) and selects the corresponding **tech base**. If `--profile` is also specified, it takes precedence. `--intensity` still applies on top of the auto-detected base — e.g. `--auto-profile --intensity deep`.

To see the available profiles:

```bash
xy-dast scan --list-profiles
```

#### Incremental Scans

Re-test only the endpoints that changed since a baseline — driven by Xygeni's API Security scan — for a large wall-time saving on pull-request pipelines, then merge with the previous report so the output is still a complete snapshot. Off by default; enable with `--incremental`. See [**Incremental DAST Scanning**](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner/incremental-scanning.md) for the full workflow, the `--baseline-report` merge, and the full-scan fallback.

#### Rate Limiting

By default a scan runs as fast as the target accepts. Against production or rate-sensitive targets that can degrade the service, trip a WAF, or get the scanner's address banned — so a scan can be told how hard to push:

```bash
# Cap the whole scan at 5 requests per second
xy-dast scan -u https://example.com --rate-limit 5 -o report.json

# Or say it as a delay between requests, whichever is more natural
xy-dast scan -u https://example.com --request-delay 200 -o report.json

# Gentler still: one request at a time
xy-dast scan -u https://example.com --rate-limit 5 --scan-threads 1 -o report.json
```

The limit applies to **every phase** — active scan, crawl, deep crawl and vulnerability check alike. `--rate-limit` and `--request-delay` are two spellings of one setting (`--rate-limit 5` is `--request-delay 200`); set whichever fits, not both, and each phase uses the form it can honour exactly.

Every request is paced on a **single shared schedule**, so the figure you set is a ceiling for the scan as a whole rather than a per-phase or per-thread one. Sustained throughput sits below the ceiling — a scan spends time waiting on responses and between phases — while the peak in any one second stays at the rate you configured, which is what matters for a fragile target.

Two things worth knowing:

* **`--scan-threads` is the only lever the crawl has besides pacing.** The crawler exposes no per-request delay of its own, so concurrency bounds how many requests it can have in flight. Setting it also lowers the active scan's threads per host.
* **Pacing applies to browser-driven crawling too.** Under the browser crawl, page resources are fetched through the same schedule, so a low rate slows page loads as well as navigation. On a JS-heavy application prefer bounding `--scan-threads` over setting a very low rate.

The vulnerability check can be exempted so a careful overall pace does not hold back the CVE sweep:

```bash
xy-dast scan -u https://example.com --rate-limit 5 --vuln-check-rate-limit 50 -o report.json
```

Only that flag exempts it. A profile's `vulnCheck.rateLimit` sets the sweep's speed when nothing was asked for on the command line, but never overrides an explicit `--rate-limit`, `--request-delay`, or a limit discovered adaptively — a file's default must not hold the CVE sweep at full speed against a target the rest of the scan is treading carefully around.

**Letting the target set the pace.** Where the target states its own limit, `--adaptive-rate-limit` uses that instead of a number you had to guess:

```bash
xy-dast scan -u https://example.com --adaptive-rate-limit -o report.json
```

* **Probes first** for advertised rate-limit headers (`RateLimit-*`, `X-RateLimit-*`) and adopts what it finds, keeping a safety margin below the stated ceiling so a shared counter or a misaligned window does not push the scan over it.
* **Backs off during the scan** when the target answers `429`, or `503` with `Retry-After`, waiting as long as it asked and easing back up once it stops complaining.
* **Slows before being blocked**, stretching the remaining quota to last until the limit resets rather than sprinting into a wall of rejections.

An explicit `--rate-limit` or `--request-delay` always wins: adaptive mode fills in a limit you did not state, it does not override one you did.

{% hint style="warning" %}
**A throttled request tests nothing.** Without a signal, a scan that was rate-limited into near-silence looks exactly like a scan of an application with nothing wrong with it. A throttled scan therefore warns when the target pushed back, and records three report properties:

| Property                   | Meaning                                                                |
| -------------------------- | ---------------------------------------------------------------------- |
| `dast.ratelimit.throttled` | Responses the target **refused** (429, or 503 with `Retry-After`)      |
| `dast.ratelimit.paced`     | **Successful** responses whose rate-limit headers slowed the scan down |
| `dast.ratelimit.enforced`  | `false` when throttling was requested but never took effect            |

`dast.ratelimit.paced` matters most in CI: those responses are all successes, so a target advertising a nearly-exhausted quota can hold a scan to a crawl while refusing nothing at all. Gate on **non-zero**, not on the precise value — the counts are lower bounds, since reporting is batched. On a scan with no limit at all the properties are **absent rather than zero**; absence means "not measured", not "never throttled".

```bash
jq -r '.metadata.reportProperties."dast.ratelimit.throttled" // 0' report.json
```

{% endhint %}

Two intensity overlays set pacing by default: **`deep`** throttles (10 req/s, 2 threads) because it is long-running and trades throughput for politeness, and **`passive`** turns on adaptive mode without imposing a fixed limit, so a target that never pushes back is still scanned at full speed. `quick` and `balanced` leave pacing unset. The equivalent profile block is `rateLimit` — see [Rate Limiting](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner/dast-scanner-configuration.md#rate-limiting) in the configuration reference.

#### Identifying the Scan's Traffic

Every scan stamps one header on every request it sends, so the team that owns the application under test can tell the scanner's traffic apart in their own access logs:

```
X-Xygeni-DAST: scan-20260821-143052
```

The **presence** of the header identifies DAST traffic; the **value** identifies one particular scan and states when it started (`scan-<yyyyMMdd>-<HHmmss>`, in UTC). The value is stamped once per run, so every request belonging to a scan carries the same one, and it is recorded in the report as the `dast.request.marker` property — a report and the target's logs can therefore be lined up from either side.

Every phase that talks to the target sends it: the crawl, the active scan, the deep crawl, the vulnerability check, the pre-flight probes, and the browser that replays a recorded login or navigation.

To pick the traffic out of an access log:

```bash
# All DAST traffic, from any scan
grep 'X-Xygeni-DAST' access.log

# Just the scan that started 2026-08-21 14:30:52 UTC
grep 'X-Xygeni-DAST: scan-20260821-143052' access.log
```

Your log format has to record the header for this to work — most servers omit unknown request headers by default. In nginx it is available as `$http_x_xygeni_dast`, and in Apache as `%{X-Xygeni-DAST}i`.

Filtering by **source IP** is not an alternative the scanner can offer: the requests come from the host running the scanner, every phase shares that address, and in CI it is usually a shared NAT pool.

{% hint style="warning" %}
**The marker identifies traffic, it does not authenticate it.** The header name is published and its value is a plain timestamp, so anyone can send it. Use it to *recognise* traffic — correlating a scan with your logs, tagging entries in a SIEM, explaining a traffic spike after the fact — and never to decide what *happens* to traffic. Suppressing alerts, dropping requests, allowlisting through a WAF, or skipping authorization for requests that carry it all build a filter an attacker can put themselves inside.

Where a scan genuinely needs different treatment, gate it on something the sender cannot choose — the scanner's **source address**, allowlisted for the duration of the engagement. If a header is also wanted, give the marker a value only you and the target know, with `--request-header "X-Xygeni-DAST: env:SCAN_SECRET"`, and rotate it as you would any credential.
{% endhint %}

#### Custom Request Headers

`--request-header` adds any other header to the same set — a partner id, a tracing header, or a token an API gateway in front of the target requires:

```bash
xy-dast scan -u https://example.com \
  --request-header "X-Trace-Id: nightly-42" \
  --request-header "X-Partner: env:PARTNER_ID" \
  -o report.json
```

* Repeatable. Both `"Name: Value"` and `Name=Value` are accepted.
* `env:VAR_NAME` reads the value from an environment variable, keeping a token out of the command line and the process list.
* Naming `X-Xygeni-DAST` changes the marker's value. Giving it an **empty** value — `--request-header "X-Xygeni-DAST:"` — suppresses the header entirely, for a target that rejects unknown headers.
* These are not authentication headers. They combine with every authentication method, including form login, and a header that collides with the one the authentication injects is ignored rather than overriding it. `Authorization`, `Proxy-Authorization` and `Cookie` are rejected outright: setting one would *replace* the scan's own credentials or session rather than add to them, leaving the scan running unauthenticated behind a report that looks clean. Use the [authentication options](#authentication) for those.

The equivalent profile block is `requestHeaders` — see [Identifying Scan Traffic](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner/dast-scanner-configuration.md#identifying-scan-traffic) in the configuration reference.

### Discovering the Application <a href="#discovery" id="discovery"></a>

A DAST scan can only attack what it finds. Before the active scan, xy-dast builds the list of pages and endpoints to attack from several sources, and how much of the application it reaches decides how much the report can say.

{% hint style="warning" %}
**Docker images 6.15.0 to 6.22.0 could not start the browser at all.** Docker's default security profile blocks Chrome's own sandbox, so the browser crawl found 0 URLs and the scan still exited 0. From release 6.23.0 the image runs Chrome without its sandbox (the container is the isolation boundary). If a scan of a web application made with those images shows no URLs from the browser crawl, run `xy-dast update` and scan again: expect more findings.
{% endhint %}

| Source                                                                                                                                           | What it finds                                                                                    | Runs                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| **Endpoint imports**: OpenAPI, Postman, GraphQL, WSDL, the [Xygeni API inventory](#api-inventory), a recorded navigation or HAR (`--navigation`) | Every operation or request they declare, whether a page links to it or not                       | When given                                                                                                 |
| **Link spider**                                                                                                                                  | Pages linked from the HTML the server returns                                                    | Always                                                                                                     |
| [**Browser crawl**](#browser-crawl)                                                                                                              | Pages that only exist once scripts run: client-side routes, menus, views opened by clicks        | Web profiles (`spa`, `blazor`, `traditional`, `cms`); never for API profiles                               |
| **AJAX crawl**                                                                                                                                   | The same, replaying each path from the start page; fills and submits more forms                  | Instead of the browser crawl when that cannot run, or after it at `--intensity deep` / with `--deep-crawl` |
| [**Deep crawl**](#deep-crawl)                                                                                                                    | URLs found by a fast headless crawler before the scan, including ones referenced only in scripts | `--deep-crawl` or `--intensity deep`                                                                       |
| [**Blazor route discovery**](#blazor)                                                                                                            | Routes of Blazor apps, which travel over a realtime connection the crawlers cannot follow        | `blazor` profile                                                                                           |

How long each crawler runs follows the [scan effort](#scan-effort): `--intensity` scales the profile's own budgets, and durations you set are used as given.

**Is the coverage good enough?** Look at the endpoints in the report before the findings, then at what the crawl reports about itself:

* `dast.browsercrawl.urls`: pages the browser crawl visited. Zero on a web application means it did not run: see [When the Browser Crawl Cannot Start](#when-the-browser-crawl-cannot-start).
* `dast.browsercrawl.timeup: true` together with a high `dast.browsercrawl.urls.unvisited`: the crawl ran out of time with pages left. The summary marks it `time limit reached`.
* `dast.browsercrawl.fallback: ajax`: the browser crawl could not run and the AJAX crawl took its place (summary: `browser crawl did not run; the AJAX crawl ran instead`).

**To reach more of the application**, roughly in order of payoff:

1. **Log in.** Most of an application is behind its login: see [Authentication](#authentication). From release 6.23.0 the deep crawl and the vulnerability check run with the login's session too.
2. **Give an endpoint source** for APIs: an OpenAPI file, a Postman collection, or the [API inventory](#api-inventory). Imported endpoints are attacked even if no page links to them.
3. **Raise the effort** (`--intensity deep`) or give the crawl more time (`--browser-crawl-duration`) when it stopped on its time limit.
4. **Switch crawler** with `--browser-crawler ajax` when a form-driven area goes unvisited.
5. **Add the deep crawl** (`--deep-crawl`) for URLs referenced in scripts.
6. **Record a navigation** (`--navigation`) through the areas no crawler reaches: multi-step wizards, pages behind specific input (see [Quick Start](#quick_start)).
7. **Keep the crawl away from what must not be touched** with [`--exclude`](#excluding-urls), rather than shortening it.

#### Browser Crawl <a href="#browser-crawl" id="browser-crawl"></a>

The profiles for web applications (`spa`, `blazor`, `traditional`, `cms`) crawl with a real browser after the link spider, to reach pages that only exist once scripts run. Two crawlers can drive that browser:

| Crawler                                 | Option                      | How it explores                                                                                                                                          |
| --------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `browser` (default from release 6.23.0) | `--browser-crawler browser` | The **browser crawl**: follows what each page shows next, without returning to the start page. Reaches routes that open on clicks on other elements.     |
| `ajax`                                  | `--browser-crawler ajax`    | The **AJAX crawl** (the default before 6.23.0): clicks links, buttons and inputs, replaying each path from the start page. Fills and submits more forms. |

```bash
xy-dast scan -u https://app.example.com --profile spa --browser-crawler ajax -o report.json
```

In a profile, use the `browserCrawl` block (see [DAST Scanner Configuration](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner/dast-scanner-configuration.md#browser-crawl)):

```yaml
browserCrawl:
  engine: ajax        # browser (default) | ajax
```

* **Which to choose.** In benchmarks the browser crawl reached 30–40% more of the test applications than the AJAX crawl, but it submits fewer forms. Keep the default, and try `ajax` where a form-driven area goes unvisited. Compare the endpoints in the report, not only the findings.
* **When the browser crawl cannot run.** If it crawls no page at all (its browser did not start, for instance), the AJAX crawl runs in its place with the same budget. The scan warns, the summary says `browser crawl did not run; the AJAX crawl ran instead`, and the report records `dast.browsercrawl.fallback: ajax`.
* **Deep crawling adds the AJAX crawl.** With `--deep-crawl` or `--intensity deep`, the AJAX crawl also runs after the browser crawl, on half its budget, to pick up what it left (mostly form submissions). Recorded as `dast.browsercrawl.leftovers: ajax`.
* **Older profiles and options keep working.** An `ajaxSpider:` block is read as the crawl's settings; it does not select the AJAX crawl unless it sets `engine: ajax`. `--ajax-spider-duration` and `--skip-ajax-spider` are aliases of `--browser-crawl-duration` and `--skip-browser-crawl`.
* **Logins.** On an authenticated scan both crawlers keep off the logout. For the browser crawl, the target's logout URLs and any path that says log out / sign out (`/logout`, `/Account/LogOff`) are left out of the scan's scope, and its browser is held to that scope. A logout chosen by the query alone (`?action=logout`) is not covered, and only form and JSON logins look for the target's own logout URL: with an imported session or a header token, prefer `ajax` when the logout has an unusual address. Held to scope, the browser also gets no third-party requests and none of the files your profile excludes (scripts and stylesheets still load).

The report records what the browser crawl explored:

| Property                                        | Meaning                                                                                                                                                          |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dast.browsercrawl.engine`                      | The crawler that ran: `browser` or `ajax`                                                                                                                        |
| `dast.browsercrawl.urls`                        | URLs the browser crawl crawled                                                                                                                                   |
| `dast.browsercrawl.urls.unvisited`              | In-scope URLs it found but never requested                                                                                                                       |
| `dast.browsercrawl.tasks.completed` / `.failed` | Its tasks; many failed ones mean its browsers crashed, and the scan warns                                                                                        |
| `dast.browsercrawl.timeup`                      | `true` when it stopped on its time limit. A crawl that ran out of time with URLs left warns: raise the [scan effort](#scan-effort) or `--browser-crawl-duration` |

{% hint style="info" %}
The browser crawl as default crawler, `--browser-crawler` and the `browserCrawl` block are available from release 6.23.0. A crashed browser tab no longer ends the crawl early.
{% endhint %}

#### Deep Crawl

The `--deep-crawl` option runs a headless browser-based crawler before the main scan. It discovers URLs that traditional spiders miss, especially in JavaScript-heavy applications where content is rendered dynamically.

```bash
xy-dast scan -u https://app.example.com --deep-crawl
```

Discovered URLs are fed as seed URLs into the scanner's spider, improving coverage. From release 6.23.0, on a scan with a form or JSON login the deep crawl runs with the login's session, so it reaches pages behind the login.

You can tune the crawl depth and timeout:

```bash
xy-dast scan -u https://app.example.com \
  --deep-crawl \
  --crawl-depth 5 \
  --crawl-timeout 10m
```

The `deep` intensity (`--intensity deep`) enables deep crawl by default (10 minutes; 5 with `--deep-crawl` at other efforts, see [Scan Effort](#scan-effort)).

#### When the Browser Crawl Cannot Start

Both [browser crawlers](#browser-crawl) drive a headless Chrome. When that browser cannot start, the crawl used to finish with no URLs and no error. From release 6.22.0:

* A browser and driver whose versions do not match stop the scan with exit code 1 and a message naming both versions: before any traffic when detected up front, otherwise as soon as the browser crawl ends, before the active scan. The report is written with a fatal `ajax-spider-browser` error, and it is not uploaded.
* Any other launch failure (a browser that crashes, missing shared memory) is logged as an error and recorded as a non-fatal `ajax-spider-browser` error. The scan continues without the browser crawl, and the summary marks it: `Crawl: AJAX spider browser failed to start, crawl incomplete`.
* The report records the URLs the browser crawl found as `dast.ajaxspider.urls`, and `dast.ajaxspider.browser: failed` when it did not start.
* From release 6.23.0, when no page of the default browser crawl could be crawled, the AJAX crawl runs in its place (see [Browser Crawl](#browser-crawl)), and only its own launch failure is recorded as above.

### Built-in Scan Profiles <a href="#profiles" id="profiles"></a>

Profiles have **two independent axes** — pick a **tech base** with `--profile` and a **scan intensity** with `--intensity`, and combine them freely.

**Tech base** (`--profile`) — *what the target is*. Controls the crawl, endpoint import, and scan policy. Auto-selectable with `--auto-profile`.

| Tech base     | Best for                                           | Crawl                                                                  | Endpoint import                                                               |
| ------------- | -------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `traditional` | Server-rendered apps (PHP, JSP, ASP.NET)           | Spider + moderate browser crawl                                        | —                                                                             |
| `spa`         | JS-heavy SPAs (React, Angular, Vue)                | Heavy browser crawl                                                    | —                                                                             |
| `openapi`     | REST APIs with an OpenAPI spec                     | Minimal spider, no browser                                             | OpenAPI spec (API-Scan policy)                                                |
| `graphql`     | GraphQL APIs                                       | Minimal spider, no browser                                             | Schema import / introspection                                                 |
| `soap`        | SOAP web services                                  | Minimal spider, no browser                                             | WSDL                                                                          |
| `cms`         | WordPress / Drupal / Joomla                        | Server-rendered crawl                                                  | — (CVE checking on, CMS templates)                                            |
| `blazor`      | ASP.NET Core Blazor (Server, WebAssembly, Web App) | As `spa`, plus routes found in a browser and in the WebAssembly client | Identity pages and the client's API URLs (see [Blazor Applications](#blazor)) |

**Scan intensity** (`--intensity`) — *how hard*. Overlays attack strength, thresholds, CVE / deep-crawl on top of the tech base, and scales its discovery budgets (see [Scan Effort](#scan-effort)).

| Intensity            | Attack strength             | CVE check | Deep crawl | Active scan                                               | Pacing                   |
| -------------------- | --------------------------- | --------- | ---------- | --------------------------------------------------------- | ------------------------ |
| `quick`              | Low                         | off       | off        | on (fast; from release 6.23.0 with a short browser crawl) | unset                    |
| `balanced` (default) | Medium                      | off       | off        | on                                                        | unset                    |
| `deep`               | Insane (extended durations) | **on**    | **on**     | on                                                        | 10 req/s, 2 threads      |
| `passive`            | —                           | off       | off        | **skipped** (production-safe, no attack payloads)         | adaptive, no fixed limit |

**Composition recipes:**

| Goal                                      | Command                                |
| ----------------------------------------- | -------------------------------------- |
| Deep scan of a REST API                   | `--profile openapi --intensity deep`   |
| Fast CI gate on an SPA                    | `--profile spa --intensity quick`      |
| Production-safe scan (no attack payloads) | `--profile <tech> --intensity passive` |
| Auto-detect the stack, deep intensity     | `--auto-profile --intensity deep`      |

{% hint style="info" %}
If no `--intensity` is given, `balanced` is used. Passing an intensity name directly to `--profile` (e.g. `--profile deep`) is accepted as shorthand for the `traditional` base at that intensity.
{% endhint %}

{% hint style="info" %}
From release 6.23.0, the profiles that name no scan policy (`spa`, `traditional`, `graphql`, `soap`) use the bundled default scan policy, as intended. Earlier images could not load it and ran the DAST scanner's built-in default instead: expect more findings.
{% endhint %}

#### Scan Effort <a href="#scan-effort" id="scan-effort"></a>

The intensity and `--deep-crawl` decide how much time discovery gets; the tech base decides how it is spent. From release 6.23.0, each budget is the tech base's own, **scaled**, so a SPA keeps most of its crawl in the browser and a server-rendered app in the spider, at every effort:

| Effort                   | Spider    | Browser crawl     | AJAX crawl                            | Deep crawl |
| ------------------------ | --------- | ----------------- | ------------------------------------- | ---------- |
| `quick`                  | ×0.5      | ×0.33, 2 browsers | only if the browser crawl cannot run  | off        |
| `balanced`, `passive`    | ×1        | ×1                | only if the browser crawl cannot run  | off        |
| `deep`                   | ×2        | ×2                | after the browser crawl, ½ its budget | 10 min     |
| any, with `--deep-crawl` | unchanged | unchanged         | after the browser crawl, ½ its budget | 5 min      |

| Tech base                    | At `balanced`: spider / browser crawl / active scan | At `deep`                      |
| ---------------------------- | --------------------------------------------------- | ------------------------------ |
| `spa`, `blazor`              | 5 / 15 / 20 min                                     | 10 / 30 / 60 min               |
| `traditional`, `cms`         | 10 / 5 / 15 min                                     | 20 / 10 / 60 min               |
| `openapi`, `graphql`, `soap` | 2 / — / 10 min                                      | no browser crawl at any effort |

* **What you state is used as is.** `--spider-duration`, `--browser-crawl-duration`, `--active-scan-duration`, `--crawl-timeout`, and the same durations in a profile file of your own are never scaled. Only the built-in profiles' values are.
* **The overall timeout follows**: without `--timeout`, it is derived from these budgets (see [Custom Scan Settings](#custom-scan-settings)).
* **Blazor route discovery** gets the effort too: 2 minutes and 40 pages at `balanced`, scaled like the browser crawl (at least 1 minute and 20 pages).
* **Memory.** The browser crawl drives several browsers at once (4 for `spa`) beside the scanner. Give the container at least 5 GB for a SPA; 8 GB leaves headroom on large applications. The DAST scanner's own memory follows the container's memory limit (the machine's without one), so the browsers keep the rest: a quarter of it by default. Set `scannerHeap` in `conf/xy-dast.yml`, or the `XY_DAST_SCANNER_HEAP` environment variable, to change it:
  * `auto`: a quarter of the memory (the default);
  * a share, such as `40%`: still follows the memory;
  * a size, such as `3g` (512m to 1024g): fixed, whatever the container has. Above half the memory it is warned about, as the browsers may no longer fit.

The report records the effort and the budgets it resolved:

| Property               | Meaning                                                                                                                       |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `dast.effort`          | The effort the scan ran at                                                                                                    |
| `dast.budget.<phase>`  | Each resolved budget in minutes (`spider`, `browsercrawl`, `ajaxcrawl`, `deepcrawl`, `activescan`, `timeout`); `0` = no limit |
| `dast.budget.explicit` | Which budgets you stated                                                                                                      |

`dast.browsercrawl.urls.unvisited` tells whether more effort would help: only when the browser crawl stopped on its time limit (`dast.browsercrawl.timeup: true`) are those URLs what more time would explore. A crawl that ran out of work left them out on purpose (scope, depth).

{% hint style="info" %}
Effort scaling, the derived timeout and `scannerHeap` / `XY_DAST_SCANNER_HEAP` are available from release 6.23.0. `XY_DAST_SCANNER_HEAP` needs the 6.23.0 wrapper: run `xy-dast update`.
{% endhint %}

List all available profiles (including custom ones):

```bash
xy-dast scan --list-profiles
```

{% hint style="info" %}
Custom profiles can be placed in `$XYGENI_DAST_DIR/profiles/`, `./profiles/`, or `./conf/profiles/`. See [DAST Scanner Configuration](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner/dast-scanner-configuration.md) for the full profile schema and examples.
{% endhint %}

#### Blazor Applications <a href="#blazor" id="blazor"></a>

{% hint style="info" %}
Available from release 6.22.0.
{% endhint %}

```bash
xy-dast scan -u https://app.example.com --profile blazor -o report.json
```

`--auto-profile` selects `blazor` when the start page loads the Blazor runtime. The profile crawls like `spa` and keeps the framework's own endpoints (`/_blazor`, `/_framework`, `/_content`) out of the active scan; they stay crawlable, since the browser needs them to render the app.

Interactive Blazor pages run over a realtime (WebSocket) connection, not over HTTP. Clicks and form submits on those pages travel over that connection, and a DAST scan cannot attack them. What the scan can test depends on how the app renders:

| How the app renders                            | Pages the scan finds                | What the active scan tests                                 |
| ---------------------------------------------- | ----------------------------------- | ---------------------------------------------------------- |
| Static server rendering                        | All linked pages                    | Each page, its query parameters and forms                  |
| Interactive, prerendered (the .NET 8+ default) | All linked pages                    | Each page's initial render: its route and query parameters |
| Interactive, **not** prerendered               | The routes found in the browser     | Almost nothing: every page arrives as an empty shell       |
| WebAssembly                                    | The routes compiled into the client | The API the client calls                                   |

The report records how the start page renders as `dast.blazor.rendering` (`static`, `prerendered`, `not-prerendered` or `client`). When it is `not-prerendered`, the scan logs a warning: a report with few findings then means the scan could not reach the app, not that the app is clean.

Before crawling, the `blazor` profile adds what a crawl of a Blazor app does not find on its own:

* **ASP.NET Core Identity pages** (`Account/Login`, `Account/Register`, `Account/Manage/*`, …) are requested and tested even when no link leads there. They are listed in the profile's `scope.seedPaths`; a custom profile can set its own. The logout, 2FA reset and delete-personal-data pages are never requested.
* **Exposed files.** Configuration files (`appsettings.json`, `appsettings.Development.json`, …) and the client's debug symbols (`_framework/*.pdb`) are requested. A served one is reported as *Configuration file served* (high for an environment file, low for the base file, which a WebAssembly app downloads by design) or *Debug symbols served*.
* **Routes found in a browser.** A browser opens the app, follows the links as rendered and records the in-page navigations. The routes are listed in the report as `dast.blazor.routes`. In a non-prerendered app they cannot be tested over HTTP, so the list shows how much of the app the report does not cover. Bounded to 40 pages and 2 minutes at `balanced`, scaled by the [scan effort](#scan-effort) from release 6.23.0; skipped with `--skip-browser-crawl`, `--navigation-only` and incremental scans.
* **The WebAssembly client's routes and API URLs**, read from the app's assemblies under `_framework/`. The API URLs are tested, which reaches API endpoints no page links to. The page routes are tested when the server renders them, and otherwise only recorded. Both are listed in the report (`dast.blazor.client.routes`, `dast.blazor.client.apis`). Every visitor downloads those assemblies, so anything written in them is public: they are saved under `blazor-assemblies/` in the work directory (pass `--work-dir` to keep it), ready for a secrets scan.

For better coverage of an interactive app:

* Scan the API behind it with its OpenAPI description (`--openapi`): that is where its logic can be attacked.
* Scan a build whose interactive pages are prerendered: `@rendermode InteractiveServer` rather than `new InteractiveServerRenderMode(prerender: false)`, or `render-mode="ServerPrerendered"` in an older Blazor Server app.
* Complement it with SAST: in Blazor Server, the page logic runs on the server.

To log in through ASP.NET Core Identity, use [form login](#authentication) with its field names; the anti-forgery token is handled for you:

```bash
xy-dast scan -u https://app.example.com --profile blazor \
  --login-url https://app.example.com/Account/Login \
  --username-field Input.Email --password-field Input.Password \
  --username "$APP_USER" --password env:APP_PASSWORD \
  -o report.json
```

Behind SSO, [import the session](#pre-authenticated-session-import-sso) instead: the browser crawl and the route discovery then run inside it, on the realtime connection too. Check that the imported session really opens the app in a browser: in an app whose pages are not prerendered, every URL answers HTTP 200 with the same empty page, with or without a session.

### Authentication <a href="#authentication" id="authentication"></a>

The DAST scanner supports authenticated scanning to test areas of the application behind login.

#### Form-Based Login

```bash
xy-dast scan -u https://app.example.com \
  --login-url https://app.example.com/login \
  --username testuser \
  --password testpass \
  -o report.json
```

Use `--username-field` and `--password-field` when the form's inputs are not named `username` and `password`.

Before the scan, xy-dast loads the login page and tries the login once:

* The form's hidden fields are sent back with the credentials: anti-forgery tokens such as ASP.NET's `__RequestVerificationToken`, Django's `csrfmiddlewaretoken` or Rails' `authenticity_token`, and fields such as `_handler`. The login page is fetched again before every login, re-logins during the scan included, so the token is always fresh.
* The form's submit button is sent too when it has a name (`Login=Login`, for instance), as a browser does: some applications refuse a login without it.
* A login that does not work (an error status, the login form shown again, a redirect back to the login page, or an account-lockout message such as "too many attempts") is logged as a warning and recorded in the report as `dast.auth.verified: false`. The scan continues, but it covers only the pages anyone can reach. The check is one extra login attempt: mind the account lockout policy when the password may be wrong.
* A login is `dast.auth.verified: true` only when the answer proves it: a redirect into the application, or a page that shows the logged-in user. An answer that proves neither success nor failure is recorded as `unconfirmed`, with a warning.

**Keeping the session.** When the pre-scan login reaches a logged-in page (following the redirects after the login), the scan opens that page again every 60 requests and logs in again only when it shows the session lost. Otherwise it judges every response: logged in when a response shows what only an authenticated page shows (typically the logout link), logged out on a redirect to the login page or a 401. To set your own indicators, use `loginSuccessRegex` / `loginFailureRegex` in the profile's `authentication` block; every response is then judged by them.

From release 6.23.0:

* A redirect to the login page counts as a lost session whatever form its `Location` takes: absolute, root-relative or relative (`login.php`, `../../login.php`).
* A profile's `loginSuccessRegex` / `loginFailureRegex` also apply when the login itself is given on the command line (`--login-url`).
* A `403` never triggers a login with the derived indicators, nor with a `loginSuccessRegex` alone: it says who may see a page, not whether the session is alive.

**Choosing how the session is checked.** From release 6.23.0 you can choose the strategy above yourself, with the `--session-*` options or the `sessionVerification` block of a profile's `authentication` (the command line wins field by field). They apply to a form login and to a profile's [JSON login](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner/dast-scanner-configuration.md#json-login-returning-a-token):

| Option                                        | Profile field       | Meaning                                                                                                                                                                                                                                                 |
| --------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--session-verification auto\|poll\|response` | `method`            | `poll`: request one page now and then and judge only its answer. `response`: judge every response. `auto` (default): poll the page the pre-scan login proved private, if any, else judge every response                                                 |
| `--session-poll-url <url>`                    | `pollUrl`           | The page to poll, absolute or relative to `-u`, on the same site (another site is ignored with a warning, as the poll carries the session). Default: the page the pre-scan login proved private. It must show the logged-in indicator to a live session |
| `--session-poll-every-requests <n>`           | `pollEveryRequests` | Poll after this many requests (default 60)                                                                                                                                                                                                              |
| `--session-poll-every-seconds <n>`            | `pollEverySeconds`  | Poll when this many seconds have passed since the last poll. With `--session-poll-every-requests`, whichever comes first                                                                                                                                |

```bash
xy-dast scan -u https://app.example.com \
  --login-url https://app.example.com/login \
  --username testuser --password env:APP_PASSWORD \
  --session-verification poll --session-poll-url /account/profile \
  -o report.json
```

* `poll` with no page to poll (none given, none found) warns and judges every response.
* With `poll`, `loginSuccessRegex` / `loginFailureRegex` are judged against the polled page only.
* After 15 seconds without any request, the next one is always checked with a poll, so a session that expired while the scan was idle is renewed before more requests go out logged out.
* A poll whose answer shows neither indicator is taken as logged in. The scan then warns and records how many in `dast.auth.poll.undecided`: the session may have been lost unnoticed. Set `loginFailureRegex` to what the polled page shows when logged out.

**Expiring sessions.** From release 6.23.0, when the login sets its session cookie with `Max-Age` / `Expires`, or a cookie holds a JWT with an `exp` claim, the scanner logs in again shortly before it expires (a tenth of the lifetime before, between 5 and 60 seconds), so no request goes out with an expired session. A cookie the server re-issues with a later expiry moves that point. Only a cookie that holds the session counts (a JWT, or a session-like name such as `session`, `sid`, `auth`, `token`; never an anti-forgery token). An idle timeout is noticed by the next poll, or by the next redirect to the login or `401`.

**When logins fail.** From release 6.23.0 the scanner's logins during the scan (form and JSON) are governed, so a broken login never turns into a login loop or locks the account:

* A failed login is retried once, 10 seconds later. If the retry fails too, the scanner **stops logging in** for the rest of the scan, warns, and records `dast.auth.gaveup: true` with the cause in `dast.auth.gaveup.reason`: `rejected-after-success` (logins worked earlier, so the password was probably changed or the account disabled, possibly by the scan), `never-succeeded`, `lockout` or `target-unavailable`. A login failing after earlier successes is also warned about when it happens.
* After a lockout answer (`423`, `429`, a redirect to a lockout page, or a failed login saying "account locked" / "too many attempts"), the next try comes 30 seconds later, then 60; a third lockout in a row gives up.
* A login the target cannot answer (a `5xx`, or no answer) is not held against the credentials: the next try comes 30 seconds later, and the scanner gives up (`target-unavailable`) only after six in a row.
* Never more than 10 logins in any 60 seconds. The final passes, which log in again after every attack that ends the session, are exempt.

Nothing waits during these pauses: the scan carries on, and requests sent as the user meanwhile go out with whatever session is left. Their number is recorded as `dast.auth.suspended.requests`.

**Logout and account endpoints.** An authenticated scan, whatever the login method (form, header or an imported session), keeps away from what would end its session or damage its account:

* The crawl does not follow logout links or click logout buttons.
* From release 6.23.0, the crawl also keeps off the account-changing pages, so it no longer submits a password change or an account deletion with made-up values (unless a form or JSON login profile opts in with `attackAccountEndpoints`, below).
* The active scan does not attack logout endpoints, nor those that change the account: password, e-mail, 2FA, deletion of the account or its personal data. The account pages themselves are still scanned.
* With form or JSON login, the logout endpoints are attacked last, in a pass of their own, since each attack may end the session. The account-changing endpoints are attacked only when a profile opts in:

  ```yaml
  authentication:
    attackAccountEndpoints: true   # use a throwaway account: a changed password breaks later scans
  ```
* With form or JSON login, the login endpoint itself is attacked after everything else, without a session: each attack is a failed login. Where the application locks an account after failed logins, the test account may be locked when the scan ends. Use an account dedicated to the scan, whose lockout you can reset.

**Does logout end the session?** After a form-login scan, xy-dast logs in once more, logs out the way the page does, and sends the session cookies from before the logout again. If they still open a logged-in page, the report gets a `session_not_invalidated_on_logout` finding (CWE-613): the logout only cleared the cookie in the browser, and a copied cookie stays valid until it expires.

Report properties of a form or [JSON](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner/dast-scanner-configuration.md#authentication-configuration) login:

| Property                                  | Meaning                                                                                                                                                                               |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dast.auth.verified`                      | The pre-scan login: `true` (proven), `false` (refused) or `unconfirmed` (neither)                                                                                                     |
| `dast.auth.logins`                        | Logins the scanner performed, the first included                                                                                                                                      |
| `dast.auth.relogin.<reason>`              | From 6.23.0: logins by reason: `initial`, `session-lost` (a response judged logged out), `poll-failed`, `expiry` (renewed before the session expired), `retry` (after a failed login) |
| `dast.auth.backoffs` / `dast.auth.capped` | From 6.23.0: logins that waited after a failed or locked-out login / for the login cap                                                                                                |
| `dast.auth.lockouts`                      | From 6.23.0: login answers that signalled a lockout                                                                                                                                   |
| `dast.auth.suspended.requests`            | From 6.23.0: requests sent as the user while logins were paused                                                                                                                       |
| `dast.auth.gaveup`                        | From 6.23.0: whether the scanner stopped logging in; `dast.auth.gaveup.reason` says why                                                                                               |
| `dast.auth.poll.undecided`                | From 6.23.0: polls whose answer showed neither indicator, taken as logged in                                                                                                          |
| `dast.auth.logout.checked`                | Form login: the logout check reached a verdict; `dast.auth.logout.reason` says why not                                                                                                |
| `dast.auth.logout.invalidated`            | Its verdict: the server refused the cookies from before the logout                                                                                                                    |

A scan that logs in many times ends with a warning. Some re-logins are expected: a rule that removes the session cookie to see what changes is sent to the login page each time. Many more, or many on a crawl-only scan, mean logged-in pages are read as logged out: set the indicators in the profile. When `dast.auth.gaveup` is `true`, the rest of the scan after that point may have run without a session.

**The deep crawl and the vulnerability check run logged in.** From release 6.23.0, with a form or JSON login, xy-dast hands those two phases the session its pre-scan login check opened (its cookies, or its token header); before, they ran anonymously. Both then act with the account's privileges: use a dedicated test account. With any credentials (that session, an authentication header, an imported session) the deep crawl runs without its browser and stays on the scanned host, so links that only JavaScript renders are not discovered by it. It stays off the logout, the account-changing URLs and the login itself, and the vulnerability check is not pointed at them. The vulnerability check starts after the whole active scan, so xy-dast logs in again just before it. The report records whether each ran with a session: `deepCrawl.authenticated`, `vulnCheck.authenticated`.

{% hint style="info" %}
The login verification (form and JSON), the session indicators, the logout and login-endpoint protections and the logout check are available from release 6.22.0. The selectable session verification, the renewal before expiry, the login retry, back-off, cap and give-up, the authenticated deep crawl and vulnerability check, and the account-changing pages kept out of the crawl are available from release 6.23.0.
{% endhint %}

#### Bearer Token

Read the token from an environment variable to avoid exposing secrets in command history:

```bash
export API_TOKEN=your-secret-token
xy-dast scan -u https://api.example.com \
  --bearer-token env:API_TOKEN \
  -o report.json
```

#### API Key / Custom Header

For APIs that authenticate via a custom header (e.g., `X-API-Key`):

```bash
xy-dast scan -u https://api.example.com \
  --api-key-header X-API-Key \
  --api-key-value env:MY_API_KEY \
  -o report.json
```

#### HTTP Basic Authentication

For targets protected with HTTP Basic auth (RFC 7617):

```bash
xy-dast scan -u https://app.example.com \
  --basic-username admin \
  --basic-password env:BASIC_PASS \
  -o report.json
```

#### Client Certificate (mTLS)

For targets that require mutual TLS, supply a PKCS#12 (`.p12` / `.pfx`) certificate. The password is read from an environment variable and is redacted from any log output:

```bash
export CERT_PASSWORD=cert-secret
xy-dast scan -u https://mtls.example.com \
  --client-cert /path/to/client.p12 \
  --client-cert-password env:CERT_PASSWORD \
  -o report.json
```

mTLS is orthogonal to the other authentication methods — combine it with `--bearer-token`, `--api-key-*`, `--basic-*`, or form login when the target requires both transport-level and application-level auth. The certificate path can also be set via the `clientCertificate` block in a profile YAML.

#### OAuth2

The scanner obtains a token from the OAuth2 token endpoint before the scan and injects it as a bearer token on every request:

```bash
xy-dast scan -u https://api.example.com \
  --oauth2-token-url https://idp.example.com/oauth/token \
  --oauth2-client-id env:OAUTH_CLIENT_ID \
  --oauth2-client-secret env:OAUTH_CLIENT_SECRET \
  --oauth2-scope api.read \
  -o report.json
```

The `password` and `refresh_token` grants (and provider-specific options) are configured via the `authentication` block in a profile YAML — see [DAST Scanner Configuration](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner/dast-scanner-configuration.md).

For long scans where a short-lived token would expire before the scan finishes, add `--token-refresh` so the scanner renews the token during the scan and keeps authenticated coverage:

```bash
xy-dast scan -u https://api.example.com \
  --oauth2-token-url https://idp.example.com/oauth/token \
  --oauth2-client-id env:OAUTH_CLIENT_ID \
  --oauth2-client-secret env:OAUTH_CLIENT_SECRET \
  --token-refresh \
  -o report.json
```

The `refresh_token` grant and finer token-renewal settings are configured via the profile `tokenLifecycle` block — see [DAST Scanner Configuration](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner/dast-scanner-configuration.md).

#### Pre-authenticated Session Import (SSO)

For OIDC/SAML SSO targets (Okta, Microsoft Entra ID, …), authenticate out-of-band and supply the resulting session cookies/headers — the scanner sends them on every request:

```bash
xy-dast scan -u https://app.example.com \
  --session-cookie "SESSION=env:SESSION_ID" \
  --session-file session.json \
  -o report.json
```

`--session-file` also accepts a **Playwright `storageState.json`** directly — the artifact produced by `context.storage_state()` in an existing Playwright login script. Its cookies are imported, and a JWT found in local storage is turned into an `Authorization: Bearer` header, so a session captured by a Playwright test can drive an authenticated scan with no conversion:

```bash
xy-dast scan -u https://app.example.com \
  --session-file storageState.json \
  -o report.json
```

Opaque (non-JWT) local-storage tokens are **not** auto-mapped — the target header is ambiguous — so inject those explicitly with `--session-cookie` or a header.

Session-file values can reference environment variables (`"value": "${env:SESSION_C1}"`), so the file holds no secret. The wrapper reads the file before starting the container and passes every variable it references into the container; no name prefix is needed. Running the Docker image directly, pass each one with `-e NAME`. A variable that is not set becomes an **empty** value, with no error, and the scan then runs unauthenticated: check that each one is set in the same shell before scanning.

From release 6.22.0, an imported session keeps the scan away from logout and account-changing endpoints, as described under [form login](#form-based-login), and the route discovery of a [Blazor app](#blazor) runs inside it as well as the browser crawl.

#### Scripted Browser Login (multi-step / advanced)

For logins that simple form/bearer auth cannot express (identifier-first or multi-page flows, JavaScript-gated logins, SSO), provide a recorded **Selenium IDE (`.side`)** script via an auth-config file. The scanner drives a real browser through the login and reuses the captured session for the scan:

```bash
xy-dast scan -u https://app.example.com \
  --auth-config auth.yaml \
  -o report.json
```

```yaml
# auth.yaml
authentication:
  method: script
  script:
    engine: selenium            # Selenium today; other frameworks (e.g. Playwright) planned
    file: auth/login.side
    vars: { USERNAME: "${env:DAST_USER}", PASSWORD: "${env:DAST_PASS}" }
```

See [DAST Scanner Configuration](https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner/dast-scanner-configuration.md) for capture/extraction options.

{% hint style="warning" %}
Always use `env:VAR_NAME` syntax for secrets (tokens, passwords, API keys, certificate passwords) rather than passing values directly on the command line, to prevent accidental exposure in shell history and process listings.
{% endhint %}

### Corporate Proxies and TLS Inspection <a href="#proxy_tls" id="proxy_tls"></a>

Behind a corporate proxy, every connection the scan makes goes through it: to the target, to the Xygeni platform, and to an out-of-band detection server. The proxy is set with the same environment variables as the Xygeni scanner, or with the `proxy:` block in `conf/xy-dast.yml`, which defaults to them:

```bash
export PROXY_HOST=proxy.corp.example PROXY_PORT=3128
export PROXY_AUTH=basic PROXY_USERNAME=scanner PROXY_PASSWORD=...   # if the proxy asks for credentials
export NO_PROXY='*.internal.example|10.0.0.0/8'                      # hosts reached directly
xy-dast scan -u https://app.example.com -o report.json
```

* `NO_PROXY` takes host names, `*.domain` wildcards, IP addresses and CIDR ranges, separated by `|` or by commas. A leading-dot `.domain` entry reads as `*.domain`. `localhost` is always reached directly, and `*` means no proxy at all.
* A target listed in `NO_PROXY` is scanned directly by every phase.
* The DAST scanner cannot exclude a CIDR range from the proxy: list those hosts by name.
* From release 6.22.0, a proxy that rejects the credentials stops the scan at once with `Proxy authentication failed: the proxy at … rejected the credentials`. Check `PROXY_USERNAME`, `PROXY_PASSWORD`, and that `PROXY_AUTH=basic` is what the proxy expects.
* The browser that replays a recorded login (`.side`) cannot answer a proxy's credential challenge. If your proxy requires authentication, allow that browser through without it, or the replay fails.

#### Trusting the inspecting proxy's CA (Zscaler and similar)

A TLS-inspecting proxy re-signs every HTTPS connection with its own certificate authority (CA). Without that CA, the scan stops with `PKIX path building failed` or `unable to get local issuer certificate`. Give the scan the CA with `XY_DAST_CA_CERTS`, and every component trusts it. This is the setup to use in production:

{% tabs %}
{% tab title="Linux / macOS" %}

```bash
export XY_DAST_CA_CERTS=/etc/pki/corp/zscaler-root.crt    # a file, or a directory of them
xy-dast scan -u https://app.example.com -o report.json
```

{% endtab %}

{% tab title="Windows" %}

```powershell
# Trust what this machine trusts: the proxy's CA is usually deployed there by policy
$env:XY_DAST_CA_CERTS = 'system'
xy-dast scan -u https://app.example.com -o report.json
```

`system` exports the machine's and the current user's trusted root certificates to a temporary bundle for the run, and deletes it afterwards. To trust only the proxy's CA, export it and name the file instead:

```powershell
$c = Get-ChildItem Cert:\LocalMachine\Root | Where-Object Subject -like '*Zscaler*' | Select-Object -First 1
Export-Certificate -Cert $c -FilePath C:\certs\zscaler-root.cer -Type CERT   # DER .cer is fine
$env:XY_DAST_CA_CERTS = 'C:\certs\zscaler-root.cer'
```

{% endtab %}
{% endtabs %}

The scanner imports the certificates when it starts and prints what it now trusts:

```
Trusting 1 additional CA certificate(s): CN = Zscaler Root CA, ...
```

* Files may be PEM (one or several certificates each) or DER, named `.crt`, `.pem`, `.cer` or `.der`. A file that is not a certificate stops the scan before it starts.
* Running the Docker image without the wrapper, mount the certificates read-only at `/mnt/ca-certs`: `docker run -v /etc/pki/corp:/mnt/ca-certs:ro ... xygeni/xy-dast:latest scan ...`. The container must start as root (the default) to import them; with `--user` it prints a warning instead.
* The same works for a target or an identity provider signed by an internal PKI.
* `XY_DAST_CA_CERTS` and the proxy variables need the wrapper from release 6.21.0 or later: run `xy-dast update`.

{% hint style="info" %}
The DAST scanner, the deep crawler and the vulnerability check do not validate the **target's** certificate. The CA matters for the connection to the Xygeni platform, for the scanner's own requests (OpenAPI descriptor fetches, probes, OAuth2 token requests) and for the browser that replays a recorded login. From release 6.22.0, a recording that browser cannot open, because it refuses the certificate, stops at that step and names the error (`net::ERR_CERT_AUTHORITY_INVALID`, for instance).
{% endhint %}

#### Skipping certificate validation (testing only)

```bash
xy-dast scan -u https://staging.example.com --skip-ssl-verify -o report.json
```

`--skip-ssl-verify` turns certificate validation off for every connection, the Xygeni platform one included. It is the same option as the Xygeni scanner's.

{% hint style="warning" %}
`--skip-ssl-verify` removes the protection against a man-in-the-middle. Use it only for tests and proofs of concept against a target with a self-signed certificate. Behind a TLS-inspecting proxy, trust its CA with `XY_DAST_CA_CERTS` instead. The scan prints a warning, and the report records `dast.tls.verify=false`.
{% endhint %}

### CI/CD Integration <a href="#cicd" id="cicd"></a>

Use `--quiet` for minimal output and `--fail-on` to gate builds on vulnerability severity:

```bash
xy-dast scan -u https://example.com \
  --quiet \
  --fail-on high \
  -o report.json

# Exit code 128 means alerts were found at or above the threshold
if [ $? -eq 128 ]; then
  echo "Security vulnerabilities found!"
  exit 1
fi
```

The `--quiet` flag outputs a single summary line:

```
Scan completed in 5m 23s | 42 URLs | 15 alerts (2 critical, 5 high, 4 low, 4 info)
```

Pipe JSON to stdout for downstream processing:

```bash
xy-dast scan -u https://example.com --quiet --output - | jq '.vulnerabilities | length'
```

#### SARIF output for GitHub Code Scanning

`--format sarif` produces SARIF v2.1.0 output that GitHub Code Scanning, Azure DevOps, the VS Code SARIF Viewer, and most CI/CD security dashboards ingest natively. Findings appear in the repo's **Security → Code scanning** tab alongside SAST/SCA results.

```yaml
# .github/workflows/dast.yml
- name: Run xy-dast scan
  run: |
    xy-dast scan -u https://staging.example.com \
      --format sarif \
      --branch ${{ github.ref_name }} \
      --no-upload \
      -o dast.sarif

- name: Upload SARIF to GitHub Code Scanning
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: dast.sarif
    category: dast/xygeni-dast
```

{% hint style="info" %}
DAST findings reference HTTP URLs rather than source-tree files, so they appear in the Security tab but **do not** produce inline PR annotations. This is a known limitation of all DAST tooling that emits SARIF.
{% endhint %}

The `--format` flag only affects the file written by `-o`. The Xygeni backend upload payload (when `--no-upload` is omitted) is always Xygeni JSON regardless of `--format`.

#### Saving raw scan artifacts

Use `--keep-details` to save the underlying scanner output and the generated automation plan alongside the report. This is the easiest way to debug a scan that does not produce expected findings:

```bash
xy-dast scan -u https://example.com -o report.json --keep-details
# Creates: report.json, report.scan.json, report.plan.yml
```

From release 6.22.0, long request and response bodies and headers in `report.scan.json` are shortened: their start, the part around the finding's evidence and their end are kept, and `[N chars omitted]` marks each cut. The report itself is unchanged.

#### GitHub Actions Example

```yaml
- name: DAST Scan
  run: |
    xy-dast scan \
      -u ${{ vars.APP_URL }} \
      --profile spa \
      --fail-on high \
      --quiet \
      -n ${{ github.repository }} \
      -o dast-report.json
  env:
    XYGENI_TOKEN: ${{ secrets.XYGENI_TOKEN }}

- name: Upload DAST Report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: dast-report
    path: dast-report.json
```

#### GitLab CI Example

```yaml
dast_scan:
  image: xygeni/xy-dast:latest
  stage: test
  script:
    - xy-dast scan
        -u $APP_URL
        --profile spa
        --fail-on high
        --quiet
        -n $CI_PROJECT_NAME
        -o dast-report.json
  artifacts:
    paths:
      - dast-report.json
    when: always
  variables:
    XYGENI_TOKEN: $XYGENI_TOKEN
```

### Command Reference <a href="#command_reference" id="command_reference"></a>

```
Usage: xy-dast scan [OPTIONS] -u <url>

Target Options:
  -u, --url=<url>           Base URL of the target application (required)
  --context-name=<name>     Scanner context name
  --openapi=<url>           OpenAPI/Swagger specification URL
  --graphql=<url|file>      GraphQL schema URL or file (introspection if omitted)
  --wsdl=<url|file>         WSDL definition URL or file for SOAP web services
  -pm, --postman=<url|file> Postman collection (v2.x JSON) URL or file
  --postman-vars=<k=v,...>  Override Postman variables (comma-separated key=value)
  --api-inventory=<file>    Xygeni API inventory (apisecurity --discovery-only
                            JSON) to import as an endpoint source
  --navigation=<url|file>   Recorded navigation to seed the scan (.side and Chrome
                            DevTools Recorder .json replayed, .har imported)
  --navigation-format=<fmt> Format of --navigation: selenium|chrome-devtools|har
                            (default: auto-detect)
  --navigation-only         Scan only the recorded --navigation endpoints (skip crawl)
  --url-list=<file>         File with additional URLs
  --include=<patterns>      URL patterns to include (regex)
  --exclude=<patterns>      URL patterns to exclude (regex on the whole URL,
                            query included; also filters endpoint imports)

Scan Options:
  -p, --profile=<name>      Tech-stack profile: traditional, spa, openapi,
                            graphql, soap, cms, blazor, or custom
  --intensity=<name>        Scan intensity: quick, balanced (default), deep,
                            passive
  --auto-profile            Auto-detect target technology and select tech profile
  --list-profiles           List available profiles and exit
  --timeout=<duration>      Overall scan timeout (default: the phases' budgets
                            plus a margin, at least 60m)
  --spider-duration=<dur>   Override spider duration
  --browser-crawl-duration=<dur>  Override browser crawl duration
                            (alias: --ajax-spider-duration)
  --browser-crawler=<engine>  Browser crawl engine: browser (default) or ajax
  --skip-browser-crawl      Skip the browser crawl (alias: --skip-ajax-spider)
  --active-scan-duration=<dur>  Override active scan duration
  --passive-only            Run only passive scan
  --lenient                 Continue scan despite OpenAPI validation errors
  --policy-strength=<level> Attack strength: LOW, MEDIUM (default), HIGH,
                            INSANE
  --exclude-rules=<ids>     Comma-separated rule IDs to exclude
  --risk-threshold=<level>  Minimum risk level: HIGH, MEDIUM, LOW, INFO
  --request-header=<h>      Extra request header sent by every phase, as
                            "Name: Value" (repeatable; supports env:VAR_NAME).
                            Every scan already sends X-Xygeni-DAST:
                            scan-<yyyyMMdd>-<HHmmss> (UTC); name it here to
                            change its value, or give it an empty value to
                            suppress it

Rate Limiting:
  --rate-limit=<rps>        Maximum requests per second across the scan
                            (default: unlimited)
  --request-delay=<ms>      Delay in milliseconds between requests
                            (default: none). Mutually derivable with
                            --rate-limit
  --scan-threads=<n>        Concurrent requests per host (default: tool
                            defaults)
  --adaptive-rate-limit     Infer the target's own rate limit and back off
                            when it throttles. Probes for advertised
                            rate-limit headers before scanning and honours
                            429/503 and Retry-After during the scan

Deep Crawl:
  --deep-crawl              Run deep crawl before scanning to discover
                            URLs with headless JS support
  --crawl-depth=<n>         Deep crawl max depth (default: 3)
  --crawl-timeout=<dur>     Deep crawl timeout (default: 5m)

Vulnerability Check:
  --vuln-check                   Run vulnerability check after scanning for
                                 CVE detection and known vulnerability checks
  --vuln-check-severity=<s>      Severity filter (default: critical,high,medium)
  --vuln-check-rate-limit=<n>    Requests per second (default: 50)
  --vuln-check-timeout=<dur>     Vulnerability check timeout (default: 15m)

Out-of-Band Detection (OAST):
  --oast-service=<kind>     Enable out-of-band detection: interactsh, boast,
                            callback, none (default: none; inferred as
                            interactsh when --oast is given)
  --oast=<url>              OAST server URL (Interactsh/BOAST) or callback
                            advertised address
  --oast-token=<value>      Self-hosted OAST server auth token (supports env:VAR_NAME)
  --oast-poll-seconds=<n>   Poll frequency for interactsh/boast
  --oast-callback-port=<n>  Advertised callback port (0 = random); callback only

Authentication:
  --login-url=<url>         Login form URL
  --username=<user>         Form authentication username
  --password=<pass>         Form authentication password
  --username-field=<name>   Username field name (default: username)
  --password-field=<name>   Password field name (default: password)
  --bearer-token=<token>    Bearer token (supports env:VAR_NAME)
  --api-key-header=<name>   Header name for API key auth (e.g., X-API-Key)
  --api-key-value=<value>   Header value for API key auth (supports env:VAR_NAME)
  --basic-username=<user>   Username for HTTP Basic authentication
  --basic-password=<pass>   Password for HTTP Basic auth (supports env:VAR_NAME)
  --client-cert=<file>      PKCS#12 client certificate for mTLS targets
  --client-cert-password=<pw> Certificate password (supports env:VAR_NAME)
  --session-verification=<m>  How the login session is checked: auto (default),
                            poll or response
  --session-poll-url=<url>  Page polled to check the session (default: the page
                            the pre-scan login proved private)
  --session-poll-every-requests=<n>  Poll after this many requests (default: 60)
  --session-poll-every-seconds=<n>   Poll after this many seconds

Incremental Scan:
  --incremental             Scan only endpoints changed since a baseline
                            (seed the changed set, skip the crawl); falls
                            back to a full scan when none are available
  --changed-endpoints-file=<file>
                            Changed-endpoint manifest from
                            'xygeni apisecurity --incremental' (required)
  --baseline-report=<file>  Prior DAST report to carry unchanged-endpoint
                            findings forward from (tagged 'kept-untested')
  --sources=<dir>           Application sources: the Xygeni scanner (when
                            installed) discovers their API endpoints, imported
                            in a full scan (unless --api-inventory is given) or
                            used to derive the changed endpoints with
                            --incremental

Output Options:
  -o, --output=<file>       Output file (use '-' for stdout)
  --format=<json|sarif>     Output format for the file written by -o
                            (default: json). 'sarif' emits SARIF v2.1.0
                            for GitHub Code Scanning. The Xygeni upload
                            payload is always JSON.
  -n, --project-name=<name> Project name for report
  --pretty                  Pretty-print the report (JSON or SARIF)
  --work-dir=<dir>          Working directory for artifacts
  --no-upload               Disable report upload to Xygeni backend
  --branch=<name>           Branch name for report upload
  --keep-details            Keep raw scanner output (.scan.json) and
                            generated automation plan (.plan.yml)
  -q, --quiet               Suppress progress output, show only summary
  --fail-on=<severity>      Exit with code 128 if alerts at or above severity
                            (info, low, high, critical)

Global Options:
  -v, --verbose             Enable verbose output
  -nb, --no-banner          Suppress the startup banner
  --skip-ssl-verify         Do not validate TLS certificates (testing only;
                            see Corporate Proxies and TLS Inspection)
  -h, --help                Show help message
  -V, --version             Show version information
```

### Exit Codes <a href="#exit_codes" id="exit_codes"></a>

| Code | Description                                |
| ---- | ------------------------------------------ |
| 0    | Scan completed successfully                |
| 1    | General error                              |
| 2    | Scanner engine not found                   |
| 3    | Scanner engine execution failed            |
| 4    | Invalid input arguments                    |
| 128  | Alert threshold exceeded (see `--fail-on`) |

### Environment Variables

| Variable                            | Description                                                                                                                                                                   | Default                             |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `XYGENI_TOKEN`                      | API access token (required for report upload)                                                                                                                                 | --                                  |
| `XYGENI_URL`                        | Xygeni API endpoint                                                                                                                                                           | `https://api.xygeni.io`             |
| `XYGENI_DASHBOARD_URL`              | Xygeni dashboard URL                                                                                                                                                          | `https://in.xygeni.io/dashboard`    |
| `XYGENI_DIR`                        | Base directory for logs                                                                                                                                                       | Current directory                   |
| `XYGENI_DAST_DIR`                   | Configuration directory (containing `conf/`)                                                                                                                                  | Script directory                    |
| `XY_DAST_SCANNER_HEAP`              | The DAST scanner's memory (`scannerHeap` in `conf/xy-dast.yml`): `auto`, a share of the memory (`40%`) or a size (`3g`). See [Scan Effort](#scan-effort). From release 6.23.0 | `auto` (25%)                        |
| `XY_DAST_COMPOSE_FILE`              | Override the location of the wrapper's `xy-dast-compose.yml` sidecar (which holds the image reference, environment forwarding, and runtime parameters)                        | `<wrapper-dir>/xy-dast-compose.yml` |
| `PROXY_PROTOCOL`                    | Proxy protocol: `http` or `socks`                                                                                                                                             | `http`                              |
| `PROXY_HOST`                        | Proxy hostname (empty: no proxy)                                                                                                                                              | --                                  |
| `PROXY_PORT`                        | Proxy port                                                                                                                                                                    | `3128`                              |
| `PROXY_AUTH`                        | Proxy authentication: `none` or `basic`                                                                                                                                       | `none`                              |
| `PROXY_USERNAME` / `PROXY_PASSWORD` | Proxy credentials, for `PROXY_AUTH=basic`                                                                                                                                     | --                                  |
| `NO_PROXY`                          | Hosts that bypass the proxy (see [Corporate Proxies and TLS Inspection](#proxy_tls))                                                                                          | --                                  |
| `XY_DAST_CA_CERTS`                  | Docker wrapper: a CA certificate file, or a directory of them, for the scan to trust; on Windows, `system` for the machine's trusted roots                                    | --                                  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.xygeni.io/xygeni-products/dast-security/dast-scanner.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
