# DAST Scanner Configuration

### DAST Scanner Configuration

The [**DAST Scanner**](/xygeni-products/dast-security/dast-scanner.md) is configured through **YAML scan profiles** that control how the scanner behaves for different types of applications.

Profiles can be selected with the `--profile` option:

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

### Profile Locations

Custom profiles can be placed in any of these directories:

| Directory                    | Description                                |
| ---------------------------- | ------------------------------------------ |
| `$XYGENI_DAST_DIR/profiles/` | Installation-level profiles                |
| `./profiles/`                | Project-level profiles (current directory) |
| `./conf/profiles/`           | Alternative project-level location         |

List all available profiles (built-in and custom):

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

### Profile Schema

A profile is a YAML file with the following sections:

```yaml
# Identity
name: my-profile
description: "Description of the profile"
extends: openapi  # Optional: inherit from a base profile

# Scope - URL patterns to include/exclude
scope:
  includePatterns:
    - "https://api.example.com/v2/.*"
  excludePatterns:
    - ".*logout.*"
    - ".*\\.js$"
    - ".*\\.css$"

# Authentication
authentication:
  method: BEARER            # NONE, FORM, BEARER, HEADER, BASIC, JSON, SCRIPT
  loginUrl: ""              # Login form URL (for FORM method)
  usernameField: "username" # Form field name for username
  passwordField: "password" # Form field name for password
  headerName: "Authorization"  # Header name (for BEARER/HEADER)
  headerValue: "${env:API_TOKEN}"  # Header value
  headerPrefix: "Bearer "   # Header value prefix

# Users (for form-based authentication)
users:
  - name: "test-user"
    username: "admin"
    password: "admin123"
    default: true

# Session management
session:
  method: COOKIE  # COOKIE, HEADER, or SCRIPT

# Technology context (helps optimize scanning)
technology:
  language: javascript
  database: mysql
  framework: express
  include:
    - "Db / MySQL"
    - "Language / JavaScript"

# Spider configuration
spider:
  duration: 10   # Maximum duration in minutes
  depth: 5       # Maximum crawl depth
  children: 10   # Maximum children per node

# AJAX Spider configuration (for SPAs)
ajaxSpider:
  duration: 15   # Maximum duration in minutes
  depth: 5       # Maximum crawl depth
  browsers: 4    # Number of browser instances
  skip: false    # Set to true to disable AJAX spider

# Active scan configuration
activeScan:
  duration: 20       # Maximum duration in minutes
  ruleDuration: 5    # Maximum duration per rule in minutes
  policy: ""         # Scan policy (e.g., "API-Scan")
  strength: "MEDIUM" # Attack strength: LOW, MEDIUM, HIGH, INSANE
  threshold: "MEDIUM" # Alert threshold: LOW, MEDIUM, HIGH
  rules: []          # Per-rule overrides (see below)

# Passive scan configuration
passiveScan:
  waitDuration: 5  # Maximum wait time in minutes

# Deep crawl (headless browser-based pre-scan crawling)
deepCrawl:
  enabled: false    # Enable deep crawl before the scan
  depth: 3          # Maximum crawl depth
  duration: "5m"    # Crawl timeout (accepts: 30s, 5m, 1h)

# Vulnerability check (template-based CVE/misconfiguration detection)
vulnCheck:
  enabled: false    # Enable post-scan vulnerability check
  severities:       # Severity filter
    - critical
    - high
    - medium
  excludeTags:      # Template tags to exclude (default: dos, fuzz)
    - dos
    - fuzz
  rateLimit: 50     # Requests per second
  timeout: "15m"    # Scan timeout
  # templates:      # Advanced: override template directories. The defaults
  #   - ...         # cover CVEs, exposures, misconfigurations, and known
  #                 # vulnerabilities and rarely need to be customised.

# Client certificate (mTLS) — optional
# Equivalent to --client-cert / --client-cert-password on the CLI.
# Orthogonal to other authentication methods (combine as needed).
clientCertificate:
  path: /path/to/client.p12        # PKCS#12 (.p12 / .pfx) certificate
  password: "${env:CERT_PASSWORD}" # Read from env to keep secrets out of YAML

# Result filtering
filtering:
  excludeRules:       # Rule IDs to exclude from results
    - "10094"
  riskThreshold: ""   # Minimum risk: INFO, LOW, MEDIUM, HIGH
```

### Profile Inheritance

Use `extends` to inherit settings from a built-in or custom profile. Only the fields you specify are overridden; all other settings come from the parent.

```yaml
name: my-api
description: "Custom API profile with stricter scanning"
extends: openapi

activeScan:
  duration: 30
  strength: HIGH
```

This profile inherits all settings from `openapi` (minimal spidering, no AJAX spider, API-Scan policy) but overrides the active scan duration and strength.

### Authentication Configuration

#### FORM - HTML Form Login

```yaml
authentication:
  method: FORM
  loginUrl: "https://app.example.com/login"
  usernameField: "username"
  passwordField: "password"

users:
  - name: "test-user"
    username: "admin"
    password: "${env:APP_PASSWORD}"
    default: true
```

#### BEARER - Bearer Token

```yaml
authentication:
  method: BEARER
  headerName: "Authorization"
  headerValue: "${env:API_TOKEN}"
  headerPrefix: "Bearer "
```

#### HEADER - Custom Header

```yaml
authentication:
  method: HEADER
  headerName: "X-API-Key"
  headerValue: "${env:API_KEY}"
  headerPrefix: ""
```

#### BASIC - HTTP Basic Authentication

```yaml
authentication:
  method: BASIC

users:
  - name: "test-user"
    username: "admin"
    password: "${env:BASIC_PASSWORD}"
    default: true
```

Credentials are Base64-encoded and sent as `Authorization: Basic <encoded>` on every request (RFC 7617).

{% hint style="info" %}
Environment variables can be referenced with `${env:VARNAME}` syntax anywhere in profile values. This is the recommended approach for sensitive values like tokens and passwords.
{% endhint %}

### Authentication Methods Reference

| Method   | Description                            | Required Fields                                       |
| -------- | -------------------------------------- | ----------------------------------------------------- |
| `NONE`   | No authentication                      | --                                                    |
| `FORM`   | HTML form login with username/password | `loginUrl`, `usernameField`, `passwordField`, `users` |
| `BEARER` | Bearer token in Authorization header   | `headerName`, `headerValue`, `headerPrefix`           |
| `HEADER` | Custom header authentication           | `headerName`, `headerValue`                           |
| `BASIC`  | HTTP Basic authentication (RFC 7617)   | `users` (username and password)                       |
| `JSON`   | JSON body authentication               | `loginUrl`, request body fields                       |
| `SCRIPT` | Script-based authentication            | Custom authentication script                          |

### Per-Rule Policy Overrides

The `activeScan.rules` list allows you to override threshold and strength for individual scan rules, or disable rules entirely:

```yaml
activeScan:
  duration: 20
  strength: MEDIUM
  rules:
    # Enable specific rules with higher strength
    - id: 40018
      name: "SQL Injection"
      threshold: "Medium"
      strength: "High"
    - id: 40012
      name: "Cross Site Scripting (Reflected)"
      threshold: "Medium"
      strength: "High"
    # Disable a rule
    - id: 30001
      name: "Buffer Overflow"
      threshold: "Off"
```

{% hint style="info" %}
Setting `threshold: "Off"` disables a rule entirely. Valid threshold values are `Off`, `Low`, `Medium`, and `High`. Valid strength values are `Low`, `Medium`, `High`, and `Insane`.
{% endhint %}

### Example: OWASP Juice Shop Profile

This complete example shows a custom profile for scanning the OWASP Juice Shop application:

```yaml
name: example-juiceshop
description: "Profile for OWASP Juice Shop application"
extends: spa

scope:
  includePatterns:
    - "http://localhost:3000/.*"
  excludePatterns:
    - ".*\\.js$"
    - ".*\\.css$"
    - ".*\\.png$"
    - ".*socket\\.io.*"
    - ".*logout.*"

technology:
  language: javascript
  database: mysql
  framework: express
  include:
    - "Db / MySQL"
    - "Language / JavaScript"

ajaxSpider:
  duration: 10
  depth: 8
  browsers: 3
  skip: false

activeScan:
  duration: 20
  ruleDuration: 5
  strength: "HIGH"
  threshold: "MEDIUM"
  rules:
    - id: 40018
      name: "SQL Injection"
      threshold: "Medium"
      strength: "High"
    - id: 40012
      name: "Cross Site Scripting (Reflected)"
      threshold: "Medium"
      strength: "High"
    - id: 40014
      name: "Cross Site Scripting (Persistent)"
      threshold: "Medium"
      strength: "High"
    - id: 40026
      name: "Cross Site Scripting (DOM Based)"
      threshold: "Medium"
      strength: "High"
    - id: 6
      name: "Path Traversal"
      threshold: "Medium"
      strength: "High"
    - id: 90023
      name: "XML External Entity Attack"
      threshold: "Medium"
      strength: "High"
    # Disable low-value rules for this app
    - id: 30001
      name: "Buffer Overflow"
      threshold: "Off"
    - id: 40003
      name: "CRLF Injection"
      threshold: "Off"
```

Run with:

```bash
xy-dast scan -u http://localhost:3000 --profile example-juiceshop -o report.json
```

### Profile Schema Reference

| Section               | Fields                                                                                              | Description                                                                    |
| --------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `name`, `description` | string                                                                                              | Profile identity                                                               |
| `extends`             | string                                                                                              | Parent profile to inherit from                                                 |
| `scope`               | `includePatterns`, `excludePatterns`                                                                | Regex lists for URL filtering                                                  |
| `authentication`      | `method`, `loginUrl`, `usernameField`, `passwordField`, `headerName`, `headerValue`, `headerPrefix` | Authentication settings                                                        |
| `users`               | List of `{name, username, password, default}`                                                       | Credentials for form-based auth                                                |
| `session`             | `method`                                                                                            | Session management: `COOKIE`, `HEADER`, or `SCRIPT`                            |
| `technology`          | `language`, `database`, `framework`, `include`                                                      | Technology context for scan optimization                                       |
| `spider`              | `duration`, `depth`, `children`                                                                     | Traditional spider settings                                                    |
| `ajaxSpider`          | `duration`, `depth`, `browsers`, `skip`                                                             | AJAX spider settings (for SPAs)                                                |
| `activeScan`          | `duration`, `ruleDuration`, `policy`, `strength`, `threshold`, `rules`                              | Active scan settings                                                           |
| `passiveScan`         | `waitDuration`                                                                                      | Passive scan wait time                                                         |
| `deepCrawl`           | `enabled`, `depth`, `duration`                                                                      | Pre-scan deep crawling                                                         |
| `vulnCheck`           | `enabled`, `templates`, `severities`, `excludeTags`, `rateLimit`, `timeout`                         | Post-scan vulnerability checking                                               |
| `clientCertificate`   | `path`, `password`                                                                                  | PKCS#12 client certificate for mTLS targets (orthogonal to other auth methods) |
| `filtering`           | `excludeRules`, `riskThreshold`                                                                     | Result filtering                                                               |


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.