Run DAST scans from the CLI

AlertaVuln’s dynamic analysis (DAST) scans a running web application or API - crawling it and probing its live responses - normalises what the scanners find into one set, and tiers each finding RED / YELLOW / GREEN. It runs from the av CLI against any URL you can reach, and lands results on the project’s Dynamic Scan page.

A passive scan of a running staging site is one command:

av dast scan --target https://staging.example.com

Scans are passive by default: the scanners observe the app’s responses without sending attack traffic, so a passive scan is non-intrusive and safe to run anywhere. Add --active to also run attack-payload rules (see Active scans).

Only scan what you own

A DAST scan sends live requests to the target - and, with --active, real attack payloads. Only scan systems you own or are explicitly authorized to test. Unauthorized scanning may be illegal (for example under the US CFAA or the UK Computer Misuse Act) and is your sole responsibility.

Prove you own the target

DAST has two authorization gates, and a scan of a public URL clears both:

1. You attest. Every scan prints the disclaimer above and then asks for authorization. Confirm at the interactive [y/N] prompt, or attest up front with --i-am-authorized. In a non-interactive context (CI, no TTY) the scan is refused unless --i-am-authorized is passed.

2. Your organisation proves domain control. Before AlertaVuln authorizes a scan of a non-loopback target, your org must hold a verified claim on the target’s domain. Add the domain in the web app under Settings and complete the DNS check; once verified, scans of that domain and its subdomains are authorized. Targets on localhost / 127.0.0.1 are exempt from this check, so you can scan a service on the runner without registering a domain.

If the domain is not verified, the scan is refused with an explanation rather than run.

Run your first scan

Point av dast scan at a running target. You confirm authorization at the prompt:

av dast scan --target https://staging.example.com

What a run prints

$ av dast scan --target https://staging.example.com
This sends live requests to https://staging.example.com. Only scan systems you
own or are authorized to test. Continue? [y/N] y
Scanning https://staging.example.com (passive)
SEVERITY  COUNT
RED       0
YELLOW    3
GREEN     11
YELLOW  GET /   Missing Content-Security-Policy header
Run with --project <id> to upload these findings.

Add --json for machine-readable output, or --export ./reports to write a self-contained HTML report you can share.

Send findings to a project

To see findings on the project’s Dynamic Scan page and track them over time, pass --project. That uploads the findings (never your traffic or credentials), so the CLI needs to be authenticated.

Local (interactive)

Sign in once and the CLI remembers you:

av login
av dast scan --target https://staging.example.com --project <projectId>

CI / headless

There is no browser login in a pipeline. Put an organisation API key in the ALERTAVULN_API_KEY environment variable; the CLI uses it as the request token for that one invocation and never writes it to disk:

ALERTAVULN_API_KEY=av_live_... \
  av dast scan --target https://staging.example.com \
  --project <projectId> --i-am-authorized

The first av dast scan of a URL auto-registers it as a target on the project. --no-upload keeps a scan local-only even when --project is set.

Active scans

--active runs attack-payload rules in addition to the passive checks. --intensity (low / medium / high) tunes the request rate, concurrency, and time budget, and --environment (staging / production / internal) declares what you are pointing at:

av dast scan --target https://staging.example.com \
  --active --intensity high --i-am-authorized

Running --active against an --environment production target additionally requires --i-am-authorized and fails fast without it - a guard against accidentally firing attack traffic at production.

av dast scan --target https://app.example.com \
  --environment production --active --i-am-authorized

Scan behind a login

By default the scanner tests your unauthenticated surface. To reach pages behind a sign-in, set the ALERTAVULN_DAST_AUTH_* environment variables before the scan - the credentials stay in your environment and are never uploaded:

export ALERTAVULN_DAST_AUTH_KIND=bearer
export ALERTAVULN_DAST_AUTH_BEARER_TOKEN="<token>"
av dast scan --target https://staging.example.com --project <projectId>

All five credential kinds - header, bearer, cookie, form and oauth - work for a local or CI scan. With a form login the web-scanner signs in and crawls as that user, while the template-scanner runs unauthenticated. See av dast targets auth for every kind, the exact variables, and which scanner uses which credential.

Before you start

1. Verify the target’s domain. In the web app, open Settings, add the domain you want to scan, and complete the DNS check (skip this for a localhost target).

2. Create an organisation API key with ReadWrite scope for uploads. In Settings -> API Keys (org-admin only), create a ReadWrite key - it looks like av_live_ followed by 64 hex characters and is shown once, so copy it immediately.

3. Find the project ID. Run av project list and copy the ID from the first column (it is also on the project’s page in the web app).

4. (CI) Store the key as a secret in your CI platform, and the project ID as a plain variable. Never commit either or print the key in logs.

Add it to CI

The job installs the CLI and scans a deployed URL. In CI there is no TTY, so authorization is attested with --i-am-authorized; --fail-on turns a bad finding into a failed build.

GitHub Actions

.github/workflows/alertavuln-dast.yml

name: DAST scan
on:
  # Run after your app is deployed to staging - e.g. on a deploy event,
  # a schedule, or manual dispatch.
  workflow_dispatch:
  schedule:
    - cron: '0 3 * * 1'   # weekly, Monday 03:00 UTC

jobs:
  dast:
    runs-on: ubuntu-latest
    env:
      # Injected from the repository/organisation secret; read by the CLI.
      ALERTAVULN_API_KEY: ${{ secrets.ALERTAVULN_API_KEY }}
      TARGET_URL: https://staging.example.com
    steps:
      - name: Install the AlertaVuln CLI
        run: |
          curl -fsSL https://get.alertavuln.com/cli/install.sh | sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Scan the running app
        run: |
          av dast scan --target "$TARGET_URL" \
            --project "${{ vars.ALERTAVULN_PROJECT_ID }}" \
            --i-am-authorized --fail-on red

Azure DevOps

azure-pipelines.yml

# Run after your app is deployed to staging - e.g. on a schedule or manually.
schedules:
  - cron: '0 3 * * 1'
    displayName: Weekly DAST
    branches:
      include: [main]
    always: true

pool:
  vmImage: ubuntu-latest

variables:
  TARGET_URL: https://staging.example.com

steps:
  - script: |
      curl -fsSL https://get.alertavuln.com/cli/install.sh | sh
      echo "##vso[task.prependpath]$HOME/.local/bin"
    displayName: Install the AlertaVuln CLI

  - script: |
      av dast scan --target "$(TARGET_URL)" \
        --project "$(ALERTAVULN_PROJECT_ID)" \
        --i-am-authorized --fail-on red
    displayName: DAST scan
    env:
      # Secret variables are NOT auto-exposed to the environment - map it here.
      ALERTAVULN_API_KEY: $(ALERTAVULN_API_KEY)

Caution

Azure DevOps does not expose secret variables to a script’s environment automatically. Map the secret into the step’s env: block explicitly (shown above), or the CLI reports not logged in.

A passive run like this is safe on a schedule. Keep --active for deliberate, authorized runs against non-production targets rather than every pipeline.

Verify it worked

Pull the consolidated findings the server holds for the project, from the pipeline or your machine:

av dast findings

$ av dast findings --project "$ALERTAVULN_PROJECT_ID" --severity red
SEVERITY  STATE  ENGINE       RULE                 METHOD  URL
RED       Open   web-scanner  sql-injection        POST    /api/search

The same findings appear on the project’s Dynamic Scan page, and any new or reopened RED / YELLOW finding raises an alert through whatever notification channels you have configured.

Keep the key safe

• Use a dedicated ReadWrite key for CI, separate from any personal login, so you can rotate or revoke it without disrupting anyone else.
• Keep it in your platform’s secret store. Do not echo it, and prefer a Key Vault-backed variable group on Azure DevOps.
• If a key is exposed, revoke it in Settings -> API Keys and issue a new one.

See also

• av dast scan reference - every flag, the authorization rules, and exit codes.
• av dast targets auth - scan pages behind a login.
• Help us find your pages - seed a scan of a SPA or API with --seed-urls / --openapi, and add the browser crawl with --ajax-spider.
• av dast findings - pull a project’s consolidated findings.
• av dast targets - list a project’s registered targets.
• Dynamic scanning (DAST) - what DAST covers, passive vs active, hosted vs self-hosted.
• Authentication - interactive login for local use.