Authentication Overview
In Create Scan → Step 2, you first choose whether the scan is Unauthenticated (crawl only the publicly reachable pages) or Authenticated (provide credentials so the scanner can reach pages behind login). When you pick Authenticated, the scanner shows four authentication methods — pick the one that matches how your app expects callers to prove who they are.
Decision tree
| If your app is… | Use | Why |
|---|---|---|
| Public, no login (marketing site, open API) | Unauthenticated Scan | Nothing to authenticate — scan the whole public surface. |
| An API that accepts a Bearer/JWT/API key header | Token Based | The scanner attaches one header to every request. |
| A web app with a username + password form | Username and password | The scanner logs in once, captures the session, and replays it. |
| You already have a logged-in browser session you want to hand to the scanner | Browser session | Reuse an existing authenticated session — no credentials given to the scanner. |
| Complex, multi-step, or you don't want to encode selectors | AI-assisted login | An LLM navigates the login flow for you. |
Public apps and open APIs — no login required.
Bearer tokens, JWTs, API keys.
HTML login forms.
Reuse an existing logged-in session — dashboard-only.
LLM-guided login discovery.
Dashboard vs CLI vs YAML
The same methods exist everywhere. The dashboard label is the user-facing card name; the CLI and YAML names are the underlying strategy keys.
| Method | Dashboard (Step 2) | CLI flag | levo-dast.yml (auth.strategy) |
|---|---|---|---|
| Unauthenticated | Unauthenticated Scan card | --auth none | none |
| Token | Token Based card | --auth token --token $TOKEN | token |
| Form login | Username and password card | --auth form --username … --password … --login-url … | form |
| Browser session | Browser session card | --auth-session-file ./session.json (or SHADOWNET_AUTH_SESSION_FILE) | — (use the env var) |
| AI-assisted | AI-assisted login card | --auth ai | ai |
The dashboard also exposes a "Login URL is the same as target URL" checkbox under Username and password — convenient when the login form is on the same URL you're scanning.
Pre-Auth values — shared across methods
Three fields on the Authentication step apply regardless of which method you pick. Use them when your app needs state in place before the login request is sent:
- Pre-Auth Cookies — CSRF tokens, tenant selectors, feature flags read by the login page.
- Pre-Auth Headers — tenant headers (
X-Tenant-Id), API gateway tokens,Accept-Language. - Local Storage Items / Local Storage Items (Base64) — SPA bootstrap data read on first load, or base64-encoded blobs.
Passwords, bearer tokens, raw cookie values, and API keys always come from a CLI flag or environment variable — never the YAML file. See the secrets policy.
Picking a test account
- Create a dedicated scan account in each environment — don't reuse a developer's account.
- Give it the same role as a normal user (not admin) unless you want admin-only paths tested.
- Expect the scan to submit forms, trigger emails, and change state. Keep it off production where possible — see Scanning production safely.
Next
- Unauthenticated Scan — simplest, start here if you don't have a login.
- Token Based — one header, one scan.
- Username and password — the most common case.
- Browser session — paste an existing logged-in session.
- AI-assisted login — when the flow is too complex to script.