av dast targets auth

Give a DAST scan the credentials it needs to reach pages behind a login, so the scanner tests your authenticated surface instead of stopping at the sign-in wall. There are two ways to supply them, covered below.

The binary ships as alertavuln; av is the common alias - they are interchangeable in every example.

Authorization still applies

Authenticating a scan does not change the rule that you may only scan systems you own or are explicitly authorized to test - see the note on av dast scan. Supply credentials only for targets you control.

Two ways to authenticate

Approach	Use when	Where the secret lives
ALERTAVULN_DAST_AUTH_* environment variables	You run av dast scan yourself (local or CI)	In your shell/CI only - never uploaded
Stored profile (av dast targets auth set)	You want AlertaVuln’s hosted worker to scan on a schedule	Encrypted at rest on the server, per target

Both describe the same five credential kinds - header, bearer, cookie, form, and oauth - with the caveats noted below.

Local scan: environment variables

For a scan you run yourself, set ALERTAVULN_DAST_AUTH_* in the environment before av dast scan. Nothing is stored server-side and no round trip is needed. If ALERTAVULN_DAST_AUTH_KIND is unset the scan runs unauthenticated, exactly as before.

Kind	Required variables	Optional
header	ALERTAVULN_DAST_AUTH_KIND=header, ALERTAVULN_DAST_AUTH_HEADER_NAME, ALERTAVULN_DAST_AUTH_HEADER_VALUE	-
bearer	ALERTAVULN_DAST_AUTH_KIND=bearer, ALERTAVULN_DAST_AUTH_BEARER_TOKEN	-
cookie	ALERTAVULN_DAST_AUTH_KIND=cookie, ALERTAVULN_DAST_AUTH_COOKIE_NAME, ALERTAVULN_DAST_AUTH_COOKIE_VALUE	-
form	ALERTAVULN_DAST_AUTH_KIND=form, ALERTAVULN_DAST_AUTH_FORM_LOGIN_URL, ALERTAVULN_DAST_AUTH_FORM_USERNAME_FIELD, ALERTAVULN_DAST_AUTH_FORM_PASSWORD_FIELD, ALERTAVULN_DAST_AUTH_FORM_USERNAME, ALERTAVULN_DAST_AUTH_FORM_PASSWORD, ALERTAVULN_DAST_AUTH_FORM_LOGGED_IN_INDICATOR	ALERTAVULN_DAST_AUTH_FORM_LOGGED_OUT_INDICATOR
oauth	ALERTAVULN_DAST_AUTH_KIND=oauth, ALERTAVULN_DAST_AUTH_OAUTH_TOKEN_URL, ALERTAVULN_DAST_AUTH_OAUTH_CLIENT_ID, ALERTAVULN_DAST_AUTH_OAUTH_CLIENT_SECRET	ALERTAVULN_DAST_AUTH_OAUTH_SCOPE

Which scanner uses which credential

header, bearer, cookie and oauth are static headers: both the web-scanner (the crawler) and the template-scanner send them on every request. The header reaches each scanner through a permissions-restricted file that is deleted when the scan ends - it is never placed on a command line.

form is a login flow: the web-scanner signs in with the username and password, checks the logged-in indicator itself, and crawls as that user. The template-scanner has no login flow, so it runs unauthenticated (the CLI prints a one-line notice saying so). A form login therefore needs the web-scanner to be able to run - a container runtime, or Java for the native fallback - and the scan fails with a clear message if it cannot.

A static header the template-scanner cannot send intact is refused before the scan starts: a value containing a # or a line break, or a header longer than 65535 bytes. The error names the header, never its value.

Examples

Scan with a static header (for example an API gateway key):

export ALERTAVULN_DAST_AUTH_KIND=header
export ALERTAVULN_DAST_AUTH_HEADER_NAME="X-API-Key"
export ALERTAVULN_DAST_AUTH_HEADER_VALUE="<key>"
av dast scan --target https://staging.example.com

Scan with a bearer token:

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

Scan with an OAuth client-credentials grant (the CLI fetches a token from the token endpoint before scanning):

export ALERTAVULN_DAST_AUTH_KIND=oauth
export ALERTAVULN_DAST_AUTH_OAUTH_TOKEN_URL="https://id.example.com/oauth/token"
export ALERTAVULN_DAST_AUTH_OAUTH_CLIENT_ID="<client-id>"
export ALERTAVULN_DAST_AUTH_OAUTH_CLIENT_SECRET="<client-secret>"
av dast scan --target https://staging.example.com

Scan behind a login form (the web-scanner signs in before crawling):

export ALERTAVULN_DAST_AUTH_KIND=form
export ALERTAVULN_DAST_AUTH_FORM_LOGIN_URL="https://staging.example.com/login"
export ALERTAVULN_DAST_AUTH_FORM_USERNAME_FIELD=email
export ALERTAVULN_DAST_AUTH_FORM_PASSWORD_FIELD=password
export ALERTAVULN_DAST_AUTH_FORM_USERNAME="[email protected]"
export ALERTAVULN_DAST_AUTH_FORM_PASSWORD="<password>"
export ALERTAVULN_DAST_AUTH_FORM_LOGGED_IN_INDICATOR="Sign out"
av dast scan --target https://staging.example.com

Stored profile: av dast targets auth set

Store an encrypted auth profile against a registered target so AlertaVuln’s hosted worker can scan it for you. The secret is encrypted at rest on the server; only the hosted worker decrypts it at scan time.

av dast targets auth set --project <projectId> --target <targetId> --kind <kind> --secret <value> [kind flags]
av dast targets auth clear --project <projectId> --target <targetId>

--target here is the target ID (from av dast targets), not a URL. You must be logged in (av login).

What the hosted worker does with a stored profile

With no profile stored, a hosted scan runs unauthenticated, as before. With one, it runs authenticated or not at all. form login is available on this path - the hosted scan signs in through your login page before it crawls. For oauth, the hosted worker exchanges the client credentials for an access token inside AlertaVuln’s infrastructure and the scanner only ever sees the resulting bearer token; the client secret goes to your token endpoint and nowhere else.

av dast targets auth set refuses a profile that breaks these rules, with the reason:

• An oauth token endpoint must be an absolute https URL with no embedded credentials (user:pass@) and no #fragment. http is accepted only for a loopback host (localhost, 127.0.0.1, ::1), and a hosted scan still refuses it - the hosted worker sends a client secret over https only.
• A form login URL follows the same shape rules, must use the target’s scheme or https (never http for an https target), and must be on the same site as the target: auth.example.com for a target on app.example.com is fine; a different domain is not, and neither is one that only shares a public suffix such as co.uk.

When the hosted scan runs, the worker also has to reach those hosts from AlertaVuln’s infrastructure:

• The token endpoint and the login URL must resolve to a publicly reachable address. One on a private network cannot be used by a hosted scan - scan that app yourself with av dast scan and the environment variables above.
• The token endpoint must answer within 10 seconds and without a redirect (redirects are not followed), with JSON that carries an access_token and, if it sends a token_type, a type of bearer.
• The access token itself must be printable ASCII with no spaces, so it fits an Authorization: Bearer header. Any other token fails the scan with “The token endpoint returned an unusable token.”

If a stored profile cannot be applied - the token endpoint is unreachable or rejects the credentials, a required value is missing, or the login URL is off the target’s site or resolves to a private address - the hosted scan fails rather than quietly running unauthenticated and reporting a clean login wall. The job’s error reads “The stored credentials for this target could not be applied by the hosted scanner (the token endpoint must be publicly reachable and accept the credentials).” and, in most cases, adds the specific reason. Fix the profile with av dast targets auth set, or remove it with av dast targets auth clear to scan unauthenticated.

Options

Flag	Kind	Description
--project	all	Project ID (required)
--target	all	Target ID (required)
--kind	all	header, bearer, cookie, form, or oauth (required)
--secret	all	The secret value: header value / bearer token / cookie value / password / client secret (required)
--header-name	header	Header name
--cookie-name	cookie	Cookie name
--login-url	form	Login form URL
--username-field	form	Username field name
--password-field	form	Password field name
--username	form	Username value
--logged-in-indicator	form	Text present only when logged in
--logged-out-indicator	form	Text present only when logged out (optional)
--token-url	oauth	Token endpoint
--client-id	oauth	Client ID
--scope	oauth	Scope (optional)

Examples

Store a bearer token for a target:

av dast targets auth set --project <projectId> --target <targetId> \
  --kind bearer --secret "<token>"

Store a form-login profile (hosted worker signs in before scanning):

av dast targets auth set --project <projectId> --target <targetId> \
  --kind form --secret "<password>" \
  --login-url https://app.example.com/login \
  --username-field email --password-field password \
  --username [email protected] \
  --logged-in-indicator "Sign out"

Remove a stored profile:

av dast targets auth clear --project <projectId> --target <targetId>

Security

Credentials supplied through ALERTAVULN_DAST_AUTH_* stay in your environment - they are never uploaded with a scan’s findings. Stored profiles are encrypted at rest and only decrypted by the hosted worker at scan time, and the hosted worker hands their values to the scanner as environment variables, never on a command line. On the hosted path an oauth client secret is used once per scan, server-side, to obtain a token and is never handed to the scanner. When that exchange fails, the scan error names at most the HTTP status the token endpoint returned - the endpoint’s response is never echoed back into it. Either way, any credential the scanner sees reflected back in a response is scrubbed from finding evidence before it is uploaded or displayed, the same as every other DAST finding.

See also

• av dast scan - run a scan (reads ALERTAVULN_DAST_AUTH_*)
• av dast targets - list a project’s registered targets and their IDs
• Dynamic scanning (DAST) - what DAST covers, passive vs active, hosted vs self-hosted