> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vigolium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticated Scanning

> Configure multi-session authenticated scanning with login flows, IDOR/BOLA testing, and token refresh.

Vigolium supports multi-session authenticated scanning via the `--auth` and `--auth-file` flags. This enables scanning behind login walls and detecting authorization bypass vulnerabilities (IDOR/BOLA).

> [!NOTE]
>
> The `--auth` / `--auth-file` flags were previously named `--session` / `--session-file`, and a single bundle file holding multiple sessions used the separate `--auth-config` flag. The old names still work as deprecated aliases (`--session` → `--auth`, `--session-file` → `--auth-file`), and `--auth-file` now also accepts the multi-session `sessions:` bundle that used to require `--auth-config`. Update your commands to the new names.

Session config files can be written in **YAML or JSON**, the format is auto-detected by file extension (`.json`) or by content sniffing (leading `{` or `[`).

> [!NOTE]
>
> Separate from configured sessions, the browser crawler can also try a short list of common **default credentials** (`admin:admin`, …) against a confirmed local login form during spidering, so the crawl reaches authenticated areas without an `--auth` session. It's off by default and auto-enabled at `balanced`/`deep` intensity, negative-control gated, and never a brute-force. See [Default-credential login attempts](https://docs.vigolium.com/native-scan/phases/spidering.md#default-credential-login-attempts).

> [!NOTE]
>
> When `--spider` runs, any session the browser establishes — cookies from a cleared WAF/bot challenge plus its User-Agent — is **carried forward** into the discovery and scanning phases (per host), so later probes reuse the cleared session. It's on by default; disable with `--no-carry-browser-session`, and your own `-H/--header` overrides always win. See [Session carry-forward](https://docs.vigolium.com/native-scan/phases/spidering.md#session-carry-forward).

## Quick Start

```bash theme={null}
# Inline session (simplest)
vigolium scan https://app.com --auth "admin:Cookie:session_id=abc123"

# Single-session file (YAML or JSON)
vigolium scan https://app.com --auth-file ./admin-session.yaml
vigolium scan https://app.com --auth-file ./admin-session.json

# Multi-session bundle file (sessions: key, YAML or JSON)
vigolium scan https://app.com --auth-file ./auth-config.yaml
vigolium scan https://app.com --auth-file ./auth-config.json
```

## Authentication Flags

| Flag | Description |
| - | - |
| `--auth` | Inline session in `name:Header:value` format. Repeatable. |
| `--auth-file` | Path to an auth file (YAML or JSON). Accepts either a single session or a `sessions:` bundle with multiple definitions. Repeatable. Also available on `agent swarm` and `agent autopilot` since v0.5.3. |
| `--require-auth` | A failed login is **fatal** for that target rather than a silent anonymous scan (config: `spidering.require_auth`). |

Both flags can be combined. If no session is explicitly marked as `primary`, the first session loaded is used as the primary.

## Session Roles

Each session has a **role** that determines how it is used during the scan:

* **`primary`**: The main session. Used for discovery, spidering, and as the default requester during the audit phase. There should be exactly one primary session.
* **`compare`**: Comparison sessions for IDOR/BOLA testing. During the audit phase, every request made by the primary session is replayed with each compare session's credentials. If a compare session can access resources it shouldn't, the `authz-compare` module flags it.

## Inline Sessions

The `--auth` flag accepts sessions in `name:Header:value` format:

```bash theme={null}
# Single session with a cookie
vigolium scan https://app.com --auth "admin:Cookie:session_id=abc123"

# Bearer token
vigolium scan https://app.com --auth "user1:Authorization:Bearer eyJhbGciOi..."

# Multiple sessions for IDOR testing
vigolium scan https://app.com \
  --auth "admin:Cookie:session=admin_token" \
  --auth "regular:Cookie:session=user_token"
```

Values containing colons are handled correctly, only the first two colons are used as delimiters.

## Session Files

For sessions with multiple headers or login flows, use files. Both YAML and JSON formats are supported.

### Static Headers

**YAML:**

```yaml theme={null}
name: admin
role: primary
headers:
  Cookie: "session_id=abc123"
  Authorization: "Bearer mytoken"
```

**JSON:**

```json theme={null}
{
  "name": "admin",
  "role": "primary",
  "headers": {
    "Cookie": "session_id=abc123",
    "Authorization": "Bearer mytoken"
  }
}
```

Use with:

```bash theme={null}
vigolium scan https://app.com --auth-file ./admin-session.yaml
vigolium scan https://app.com --auth-file ./admin-session.json
```

Session files are resolved from the configured `session_dir` (default `~/.vigolium/sessions/`) if the path is not absolute. See [Session Strategy Configuration](#session-strategy-configuration) below.

### Login Flows

Session files can define automated login flows. The scanner executes the login request at scan start and extracts credentials from the response.

**YAML:**

```yaml theme={null}
name: admin
role: primary
login:
  url: "https://app.com/api/auth/login"
  method: POST
  content_type: "application/json"
  body: '{"username":"${ADMIN_USER}","password":"${ADMIN_PASS}"}'
  extract:
    - source: json
      path: "$.token"
      apply_as: "Authorization: Bearer {value}"
```

**JSON:**

```json theme={null}
{
  "name": "admin",
  "role": "primary",
  "login": {
    "url": "https://app.com/api/auth/login",
    "method": "POST",
    "content_type": "application/json",
    "body": "{\"username\":\"${ADMIN_USER}\",\"password\":\"${ADMIN_PASS}\"}",
    "extract": [
      {
        "source": "json",
        "path": "$.token",
        "apply_as": "Authorization: Bearer {value}"
      }
    ]
  }
}
```

### Login Request Headers

Added in v0.5.3. `login.headers` adds request headers to **every** request the login sends — the single request, each step of a multi-step flow, or the OAuth2 token request. A step's own `headers` are applied after the flow's, so a step header wins on a clash. Values take `{name}` step variables and the templates below, exactly like `url` and `body`; a `Host` header sets the request's Host.

```yaml theme={null}
login:
  headers:
    Origin: https://app.example.com
    X-Client-Version: "4.2"
  steps:
    - url: https://identity.example.com/sdk/authenticate
      method: POST
      headers:
        Authorization: "Basic {{env:SDK_BASIC_AUTH}}"
      body: '{"email":"${TEST_EMAIL}","password":"${TEST_PASSWORD}"}'
      extract:
        - source: json
          path: .intermediate_token
          apply_as: "var:intermediate"
    - url: https://api.example.com/auth/exchange
      method: POST
      headers:
        X-Intermediate-Token: "{intermediate}"
      extract:
        - source: json
          path: .token
          apply_as: "Authorization: Bearer {value}"
```

### Templates: environment variables and TOTP

Added in v0.5.3. Login `url`, `body`, header values and the OAuth2 fields accept **function templates**, evaluated every time the login runs — including an in-scan re-login — so a TOTP code is always current and a secret never has to live in the file.

| Template | Value |
| - | - |
| `{{env:NAME}}` | Environment variable `NAME`, read when the login runs |
| `{{totp:NAME}}` | Current 6-digit TOTP code (RFC 6238, SHA-1, 30 s) for the base32 secret in `$NAME` |
| `{{totp_secret_file:PATH}}` | The same, for a base32 secret stored in file `PATH` (`~/` expands) |

```yaml theme={null}
login:
  steps:
    - url: https://app.example.com/login
      method: POST
      body: '{"user":"{{env:APP_USER}}","password":"{{env:APP_PASS}}"}'
      extract:
        - source: json
          path: .mfa_ticket
          apply_as: "var:ticket"
    - url: https://app.example.com/login/mfa
      method: POST
      body: '{"ticket":"{ticket}","code":"{{totp:APP_TOTP_SECRET}}"}'
      extract:
        - source: cookie
```

**This is what makes MFA-gated targets scannable without a human in the loop.** A variable that is not set, an unreadable secret file or an invalid secret **fails the login** and names the template — nothing is ever sent with an empty value.

> [!NOTE]
>
> Templates expand **before** `{name}` step variables, so a value the server returned is never itself treated as a template.
>
> `vigolium auth lint` reports an unknown template function or malformed name as an error, and **warns when `{{totp:…}}` holds what looks like a literal base32 secret** rather than the name of a variable — the easy mistake. `vigolium auth totp` prints the code a template would produce, so you can check it against your authenticator before a scan depends on it.
>
> The older `${NAME}` syntax still works; it is expanded **once**, when the file is loaded, which is why it cannot carry a rotating code.

### OAuth2 token endpoints

Added in v0.5.3. `type: oauth2_client_credentials` and `type: oauth2_refresh_token` log in against an OAuth2 token endpoint instead of a login form.

```yaml theme={null}
sessions:
  - name: service
    role: primary
    login:
      type: oauth2_client_credentials
      token_url: https://idp.example.com/oauth/token
      client_id: vigolium-scanner
      client_secret: "{{env:SCANNER_CLIENT_SECRET}}"
      scope: "read:orders write:orders"
      audience: https://api.example.com
      auth_style: header        # or body; omit to try header, then body

  - name: user
    role: compare
    login:
      type: oauth2_refresh_token
      token_url: https://idp.example.com/oauth/token
      client_id: vigolium-scanner
      client_secret: "{{env:SCANNER_CLIENT_SECRET}}"
      refresh_token: "{{env:USER_REFRESH_TOKEN}}"
```

| Field | Meaning |
| - | - |
| `token_url` | Token endpoint (**required**) |
| `client_id`, `client_secret` | Client credentials (both required for `oauth2_client_credentials`) |
| `scope` | Space- or comma-separated scopes (client credentials only) |
| `audience` | Sent as the `audience` parameter (client credentials only) |
| `refresh_token` | **Required** for `oauth2_refresh_token` |
| `auth_style` | `header` (HTTP Basic) or `body` (form fields); omit to try header, then body |

The access token is sent as `Authorization: <token_type> <access_token>` (`Bearer` for a bearer token).

> [!NOTE]
>
> **The token is refreshed before it expires, not after a 401.** The response's `expires_in` becomes the session's expiry, and during a native scan the token is renewed shortly ahead of it — a tenth of its lifetime, between 5 s and 60 s, at most half of it — without waiting for a rejection and without holding scan traffic, **even when the session has no `check` block**. A refresh token the server rotates replaces the configured one for the next refresh.
>
> `auth load -j` reports the expiry as `expires_at`. A token-endpoint error (`invalid_client`, `invalid_grant`, …) fails the login with that error. `auth lint` checks the required fields, the `token_url` scheme and `auth_style`, and warns about request-flow fields (`url`, `method`, `body`, `extract`, …) that an OAuth2 login ignores.

### Extraction Sources

| Source | Description | Example |
| - | - | - |
| `json` | Extract a value from the JSON response body using dot-notation. | `path: "$.token"` |
| `cookie` | Extract cookies from `Set-Cookie` response headers. Omit `name` to extract all cookies. | `name: "session_id"` |
| `header` | Extract a value from a response header. | `name: "X-Auth-Token"` |

The `apply_as` field defines how the extracted value is applied as a request header. Use `{value}` as a placeholder. `apply_as: "var:<name>"` instead stores the value as a step variable for a later step to reference as `{<name>}`.

## Multi-Session Bundle File

A bundle file defines all sessions in one place under a `sessions` key, and is loaded with `--auth-file` (this is what the removed `--auth-config` flag used to do).

### YAML Format

```yaml theme={null}
sessions:
  # Primary session: JSON API login
  - name: admin
    role: primary
    login:
      url: "https://app.com/api/auth/login"
      method: POST
      content_type: "application/json"
      body: '{"username":"${ADMIN_USER}","password":"${ADMIN_PASS}"}'
      extract:
        - source: json
          path: "$.token"
          apply_as: "Authorization: Bearer {value}"

  # Compare session: form-based login
  - name: regular_user
    role: compare
    login:
      url: "https://app.com/login"
      method: POST
      content_type: "application/x-www-form-urlencoded"
      body: "username=${USER_NAME}&password=${USER_PASS}"
      extract:
        - source: cookie

  # Compare session: static API key (no login needed)
  - name: api_key_user
    role: compare
    headers:
      X-API-Key: "${API_KEY}"
```

### JSON Format

```json theme={null}
{
  "sessions": [
    {
      "name": "admin",
      "role": "primary",
      "login": {
        "url": "https://app.com/api/auth/login",
        "method": "POST",
        "content_type": "application/json",
        "body": "{\"username\":\"${ADMIN_USER}\",\"password\":\"${ADMIN_PASS}\"}",
        "extract": [
          {
            "source": "json",
            "path": "$.token",
            "apply_as": "Authorization: Bearer {value}"
          }
        ]
      }
    },
    {
      "name": "regular_user",
      "role": "compare",
      "login": {
        "url": "https://app.com/login",
        "method": "POST",
        "content_type": "application/x-www-form-urlencoded",
        "body": "username=${USER_NAME}&password=${USER_PASS}",
        "extract": [
          {
            "source": "cookie"
          }
        ]
      }
    },
    {
      "name": "api_key_user",
      "role": "compare",
      "headers": {
        "X-API-Key": "${API_KEY}"
      }
    }
  ]
}
```

Use with:

```bash theme={null}
vigolium scan https://app.com --auth-file ./auth-config.yaml
vigolium scan https://app.com --auth-file ./auth-config.json
```

### When to Use JSON

JSON is a good choice when:

* **AI agents generate session configs**: most LLMs produce cleaner JSON than YAML, and agent modes (swarm, autopilot) already output session config as JSON natively.
* **Programmatic generation**: scripts, CI pipelines, or tools that build session configs are often simpler in JSON.
* **Embedding in other JSON payloads**: e.g., the REST API `POST /api/agent/run/swarm` body includes session config as a nested JSON object.

YAML remains convenient for hand-written configs where comments and multi-line strings help readability.

### Format Detection

The format is detected automatically:

1. **File extension**: `.json` files are parsed as JSON; `.yaml` / `.yml` as YAML.
2. **Content sniffing**: if the extension is ambiguous (or missing), content starting with `{` or `[` (after whitespace trimming) is parsed as JSON.
3. **Fallback**: everything else is parsed as YAML.

This means extensionless files work too, pipe JSON directly and it will be detected:

```bash theme={null}
# Generate config from a script, write to a temp file, scan
./gen-auth-config.sh > /tmp/auth-config
vigolium scan https://app.com --auth-file /tmp/auth-config
```

## Session Config Schema Reference

Both YAML and JSON use the same field names. Here is the full schema:

```
SessionConfig
├── sessions[]              # Array of session definitions
│   ├── name                # (string, required) Unique session name
│   ├── role                # (string) "primary" or "compare"
│   ├── headers             # (map) Static headers, e.g. {"Cookie": "sid=abc"}
│   ├── login               # (object) Automated login flow
│   │   ├── type            # (string) "" (request flow), "oauth2_client_credentials",
│   │   │                   #          or "oauth2_refresh_token"
│   │   ├── url             # (string, required for a request flow) Login endpoint URL
│   │   ├── method          # (string, required for a request flow) HTTP method
│   │   ├── content_type    # (string) Request Content-Type
│   │   ├── headers         # (map) Headers added to EVERY request the login sends
│   │   ├── body            # (string) Request body
│   │   ├── steps[]         # (array) Multi-step flow; each step takes url/method/headers/
│   │   │                   #         body/extract/expect
│   │   ├── token_url       # (string) OAuth2 token endpoint
│   │   ├── client_id       # (string) OAuth2 client id
│   │   ├── client_secret   # (string) OAuth2 client secret
│   │   ├── scope           # (string) OAuth2 scopes (client credentials)
│   │   ├── audience        # (string) OAuth2 audience (client credentials)
│   │   ├── refresh_token   # (string) OAuth2 refresh token
│   │   ├── auth_style      # (string) "header", "body", or "" (try header, then body)
│   │   └── extract[]       # (array, required for a request flow) Extraction rules
│   │       ├── source      # (string) "json", "cookie", or "header"
│   │       ├── name        # (string) Cookie/header name to extract
│   │       ├── path        # (string) JSONPath for json source
│   │       └── apply_as    # (string) Header template ("Authorization: Bearer {value}")
│   │                       #          or "var:<name>" to hold it for a later step
│   ├── check               # (object) What "logged in" looks like on this target
│   │   ├── url             # (string) Probe URL; a path resolves against the target origin
│   │   ├── method          # (string) Probe method (default GET)
│   │   ├── logged_in       # (object) ALL must hold: status[], body_contains,
│   │   │                   #          body_regex, header_regex
│   │   ├── logged_out      # (object) ANY match means logged out: status[],
│   │   │                   #          redirect_regex, body_regex
│   │   ├── sample_every    # (int) Check body_regex on 1 response in N
│   │   └── interval        # (duration) Re-probe check.url at most this often
│   ├── reauth              # (object) What to do once the session is logged out
│   │   ├── enabled         # (bool)
│   │   ├── max_attempts    # (int)
│   │   ├── backoff         # (duration) Doubles after each failure
│   │   ├── on_failure      # (string) "continue" or "abort"
│   │   └── pause_traffic   # (bool, default true) Hold this session's requests
│   │                       #          through the confirm probe and re-login
│   └── login_request       # (string) Raw HTTP request for login (alternative to login)
```

Only one of `headers`, `login`, or `login_request` can be set per session. `check` and `reauth` were added in v0.5.3; `scanning_strategy.session.validate_url`, `reauth_on_status` and `reauth_interval` fill `check.url`, `check.logged_out.status` and `check.interval` for every session that leaves them unset.

### Logged-in check and in-scan re-login

```yaml theme={null}
sessions:
  - name: admin
    role: primary
    login: { ... }
    check:
      url: /api/me                 # a path resolves against the target origin
      method: GET
      logged_in:                   # ALL listed conditions must hold
        status: [200]
        body_contains: '"email"'
        header_regex: '(?i)^content-type: application/json'
      logged_out:                  # ANY match means logged out
        status: [401, 419, 440]
        redirect_regex: '(?i)/(login|signin|sso)\b'
        body_regex: '(?i)(session (has )?expired|please (log|sign) in)'
      sample_every: 50
      interval: 2m
    reauth:
      enabled: true
      max_attempts: 3
      backoff: 10s
      on_failure: continue         # or abort
      pause_traffic: true
```

A session with a `check` block is **kept live for the whole scan** (v0.5.3). This matters because a long scan routinely outlives its own session, and every request after that point tests the logged-out surface while reporting nothing wrong.

1. **Sampling.** Every response received with the session's credentials is matched against `logged_out`: `status` and `redirect_regex` (against `Location`) on all of them, `body_regex` on one in `sample_every` (first 64 KiB). Cached responses are not fresh evidence and are not sampled.
2. **Confirming.** A match marks the session *suspect* and emits `auth.session_suspect`. With a `check.url`, one probe goes out with the current credentials — if it is still logged in, the session stays valid, which is the common case of **a module that provoked a 401 on purpose**. Without a `check.url`, three matches within 10 s confirm the logout.
3. **Re-login.** The login flow runs again on a copy of the session, through the same login transport and the egress gate's priority lane, so it never queues behind the scan's own traffic. Up to `reauth.max_attempts`, waiting `backoff` after the first failure and doubling it. Success publishes the new credentials as the next *generation* and emits `auth.relogin` with `ok: true`.
4. **One login per expiry.** However many workers see the 401 at once, only the first confirms and re-logs-in. A response to an older generation's credentials is never evidence against the new ones.
5. **Pausing.** With `pause_traffic: true` (the default) this session's requests wait from the first logged-out match through the re-login — at most the 2-minute login budget — and leave with the new credentials. Only requests already in flight come back logged out.
6. **Proactive probe.** `check.interval` re-runs the probe at most that often even when nothing looked logged out.
7. **Expiry.** When the login reported when its credentials expire (an OAuth2 `expires_in`), the session is kept live **even without a `check` block**, and renews shortly before that time — no confirm probe, no paused traffic, since the old token is still good.

> [!WARNING]
>
> **When every re-login attempt fails, the session is *lost* and the scan says so.** `auth.relogin` reports `ok: false`; the running phase and every later phase that sends with that session are recorded **partial** with reason `auth_lost`; and the scan carries on unauthenticated rather than pretending otherwise. With `reauth.on_failure: abort` the scan stops instead — the remaining phases are skipped with `auth_lost` and the command exits `1` with `error.code: "login_failed"`.
>
> Responses received while the session was logged out are reported as the `responses_while_logged_out` limit on the phase, with the count under `counts.responses_while_logged_out`. They are **not** re-queued, so treat that number as the size of the hole in your coverage.

> [!NOTE]
>
> `--require-auth` (or `spidering.require_auth`, v0.5.2) makes a *failed initial login* fatal for that target, rather than silently scanning it anonymously. Credential-stripped requests — the authorization-differential modules' anonymous replays — are never sampled, so their deliberate 401s cannot trigger a re-login. A header you set explicitly with `-H` is never taken over by a session.
>
> All login flows together are bounded by a **2-minute budget** (v0.5.2), and login flows now honour `--proxy` and the scan's TLS stance like every other request — they used to ignore both.

## Managing Sessions with the `auth` Command

The `--auth`/`--auth-file` flags load sessions for a single scan. The `vigolium auth` subcommand manages reusable, persisted sessions and provides helpers for validating configs and automating 2FA.

| Command | Purpose |
| - | - |
| `vigolium auth list` | Print every session stored for the active project. |
| `vigolium auth load` | Persist sessions from a file, stdin, or a raw login request into the database. |
| `vigolium auth lint` | Validate a session config file for errors and warnings before you use it. |
| `vigolium auth check` | Prove a session actually authenticates against a URL. |
| `vigolium auth totp` | Generate an RFC 6238 TOTP code for scripting 2FA login flows. |

### List stored sessions

```bash theme={null}
vigolium auth list
# Filter to a single host
vigolium auth list --host app.example.com
```

Each row shows hostname, session name, role (primary/compare), position, a token preview, and extract rules. Sessions are scoped to the active project.

### Load sessions into the database

`auth load` persists sessions so subsequent scans pick them up automatically. It accepts a native config file, an agent-produced `session-config.json`, stdin, or even a raw HTTP login request (which it sends, then auto-discovers tokens from the JSON body, `Set-Cookie`, and auth headers):

```bash theme={null}
# From a YAML/JSON session config
vigolium auth load ./auth-config.yaml

# From stdin
cat auth-config.json | vigolium auth load -

# From a raw login request — tokens auto-discovered from the response
vigolium auth load ./login-request.txt --host app.example.com --name admin

# Skip the validation login round-trip
vigolium auth load ./auth-config.yaml --no-validate
```

By default, `load` executes each login flow once to verify the credentials work; pass `--no-validate` to skip. Agent format is auto-detected when the path contains `agent-sessions/` (or force it with `--agent-format`). The hostname is derived from the first login URL when `--host` is omitted. `--force` stores a session whose login failed anyway, and `--timeout` bounds the round-trip.

> [!WARNING]
>
> **`auth load` exits `1` on a failed login as of v0.5.3, and runs the *full* scan login flow.** It used to validate only part of a multi-step flow, ignore `expect` conditions and `--proxy`, and then **save the failed session anyway** — so a broken credential set looked loaded and every scan after it ran unauthenticated against a target that looked clean.
>
> Under `-j` each session reports its own login result, so a bundle with one bad session says which.

### Lint a session config

Catch mistakes before a scan — missing/invalid fields, bad extract rules, unknown login or extract types, multiple primary sessions, or duplicate names:

```bash theme={null}
vigolium auth lint ./auth-config.yaml
vigolium auth lint ./admin.yaml ./readonly.yaml ./service.yaml   # several files at once
cat auth-config.json | vigolium auth lint --stdin
vigolium auth lint ./auth-config.yaml -j
```

Since v0.5.3 it takes **multiple files**, reports **unknown fields with line and column**, and supports `-j` (one item per file, with each issue's severity, line, column, message and rule; `ok` is false exactly when there are errors). `auth load`, `auth lint` and `--auth-file` share one session-file parser, so a file that lints clean is a file the scan can load.

### Check that a session really authenticates

```bash theme={null}
vigolium auth check sessions.yaml --url https://app.example.com/account
vigolium auth check admin --url https://app.example.com/api/me -j   # a stored session
vigolium auth check sessions.yaml --session admin                    # uses check.url
```

Added in v0.5.3, and the answer to the most expensive failure mode in authenticated scanning: **a session that loads, lints and looks fine, but is not actually logged in** — so the whole scan crawls the public surface and reports a small, clean result.

It logs each session in exactly as a scan does (the scan's login transport: `--proxy`, the scan's TLS stance, `--timeout`), then requests the URL **twice** through the scan's HTTP stack — once with the session's credentials and once without — following no redirects. The two responses decide the verdict:

| Verdict | Meaning |
| - | - |
| `authenticated` | The session reached what the anonymous request did not (status pair, the anonymous request redirected to a login page or served a password form, different content), or `check.logged_in` held with credentials and failed without them |
| `login_wall` | The authenticated request was redirected to a login URL, got a password form, or matched `check.logged_out` by redirect or body |
| `unauthorized` | 401/403 with credentials, a `check.logged_out` status, or `check.logged_in` failed |
| `indistinguishable` | Same status and the same body (volatile tokens such as nonces and timestamps ignored) with and without credentials — **the URL proves nothing.** Pick a page only a logged-in user sees, or configure `check.logged_in` |
| `error` | The login failed, or a request did not complete |

The URL is `--url`, else `check.url`, else `validate_url`; a path resolves against the login URL's origin. It exits `0` **only when every checked session is `authenticated`**, otherwise `1` with `error.code` `login_failed` (the login itself did not work) or `not_authenticated` (any other verdict) — so it drops straight into CI ahead of the scan.

`-j` gives one item per session: `session`, `url`, `method`, `verdict`, `authenticated`, `reason`, `signals` (`name`, `side`, `detail`), `similarity`, `auth_response` and `anon_response` (`status`, `length`, `location`, `error`), and `login`.

> [!NOTE]
>
> The database has no columns for `check` / `reauth`, so a **stored** session is checked with `--url` (or `validate_url`) and the heuristics alone.

### Generate a TOTP code for 2FA

For automating two-factor login flows, `auth totp` turns a base32 secret into the current code:

```bash theme={null}
vigolium auth totp --secret JBSWY3DPEHPK3PXP
# 123456

vigolium auth totp --secret JBSWY3DPEHPK3PXP -j
# {"code":"123456","expires_in":18}

# Keep the secret off the command line (and out of your shell history)
vigolium auth totp --secret-env TOTP_SECRET
vigolium auth totp --secret-file ~/.config/app-totp.key
printf '%s' "$SECRET" | vigolium auth totp --secret -
```

> [!WARNING]
>
> **`auth totp` prints the bare code as of v0.5.3; JSON is behind `-j`.** A script doing `vigolium auth totp --secret "$S" | jq -r .code` now gets a jq parse error. Drop the `jq`, or add `-j`.

`--secret-env`, `--secret-file` and `--secret -` were added in the same release so the secret never appears in `ps` output or shell history. In a session file, prefer the `{{totp:NAME}}` template over shelling out at all — it re-derives the code on every re-login, which a value captured once cannot do.

## Environment Variables

Session files (both YAML and JSON) support `${VAR}` syntax for secrets. This keeps credentials out of config files:

```bash theme={null}
export ADMIN_USER=admin
export ADMIN_PASS=s3cret
vigolium scan https://app.com --auth-file ./auth-config.json
```

All `${VAR}` references are expanded from the environment at load time, before format parsing.

## IDOR/BOLA Testing

To test for authorization bypass vulnerabilities, define at least two sessions, one primary and one or more compare sessions.

**YAML:**

```yaml theme={null}
sessions:
  - name: admin
    role: primary
    headers:
      Cookie: "${ADMIN_SESSION_COOKIE}"

  - name: regular_user
    role: compare
    headers:
      Cookie: "${USER_SESSION_COOKIE}"

  # Optional: unauthenticated session
  - name: unauthenticated
    role: compare
```

**JSON:**

```json theme={null}
{
  "sessions": [
    {
      "name": "admin",
      "role": "primary",
      "headers": {
        "Cookie": "${ADMIN_SESSION_COOKIE}"
      }
    },
    {
      "name": "regular_user",
      "role": "compare",
      "headers": {
        "Cookie": "${USER_SESSION_COOKIE}"
      }
    },
    {
      "name": "unauthenticated",
      "role": "compare"
    }
  ]
}
```

The built-in `authz-compare` module automatically activates when compare sessions are present. It replays primary session requests with compare session credentials and flags responses that indicate broken access control.

### How Detection Works

1. The primary session makes a request and gets a response (e.g., `GET /api/users/42` -> 200 OK with user data).
2. The same request is replayed with each compare session's credentials.
3. If a compare session also receives a successful response with similar content, the module reports a potential IDOR/BOLA finding with **High** severity.

### Filtering to Auth Modules Only

To run only authorization testing without other active modules:

```bash theme={null}
vigolium scan https://app.com \
  --auth-file ./auth-config.json \
  --module-tag access-control
```

## How Sessions Affect Scan Phases

| Phase | Session Usage |
| - | - |
| Discovery / Spidering | Primary session only (controlled by `use_in_discovery`) |
| Audit | Primary session for main scanning; compare sessions for IDOR/BOLA replay (controlled by `compare_enabled`) |

## Session Strategy Configuration

Session behavior is configured under `scanning_strategy.session` in `vigolium-configs.yaml` (see `public/vigolium-configs.example.yaml` for the full annotated example).

```yaml theme={null}
scanning_strategy:
  session:
    # Directory where session files are stored.
    # When --auth-file receives a bare name (e.g. "myapp"), the scanner
    # resolves it as <session_dir>/myapp.yaml (or .yml, .json).
    # Default: ~/.vigolium/sessions/
    session_dir: ~/.vigolium/sessions/

    # Apply primary session headers during discovery and spidering phases.
    # When false, those phases run unauthenticated and credentials are only
    # used during the audit phase.
    # Default: true
    use_in_discovery: true

    # Enable cross-session IDOR/BOLA replay with compare sessions.
    # When true and multiple sessions are defined, the authz-compare module
    # replays primary-session requests with each compare session's credentials.
    # When false, compare sessions are ignored even if defined.
    # Default: true
    compare_enabled: true

    # Re-execute login flows at this interval to refresh expiring tokens.
    # Format: Go duration string (e.g. "15m", "1h", "30m").
    # Default: "" (disabled — login once at scan start)
    reauth_interval: ""

    # Trigger reactive re-authentication when the primary session receives
    # one of these HTTP status codes. The login flow is re-executed immediately
    # and the failed request is retried.
    # Default: [] (disabled)
    reauth_on_status: []

    # URL to GET after login to verify that extracted credentials work.
    # The scanner checks for a 2xx response before proceeding.
    # Can be a relative path (resolved against the target) or absolute URL.
    # Default: "" (disabled)
    validate_url: ""
```

### Field Reference

| Field | Type | Default | Description |
| - | - | - | - |
| `session_dir` | string | `~/.vigolium/sessions/` | Directory for session file lookup. `--auth-file myapp` resolves to `<session_dir>/myapp.yaml` (tries `.yaml`, `.yml`, `.json` in order). Supports `~` expansion. |
| `use_in_discovery` | bool | `true` | When `true`, the primary session's headers are injected into the requester used for discovery and spidering. When `false`, those phases run unauthenticated, useful for mapping the public attack surface first, then scanning authenticated. |
| `compare_enabled` | bool | `true` | When `true`, compare sessions are created and the `authz-compare` module is activated for IDOR/BOLA testing. When `false`, compare sessions are ignored even if defined, handy when you only need authenticated scanning without authorization comparison. |
| `reauth_interval` | duration | `""` (disabled) | Go duration string (e.g. `"15m"`, `"1h"`). When set, login flows are re-executed at this interval to refresh tokens that expire mid-scan. |
| `reauth_on_status` | \[]int | `[]` (disabled) | HTTP status codes that trigger reactive re-authentication. When the primary session receives one of these codes, its login flow is re-executed immediately and the request is retried. |
| `validate_url` | string | `""` (disabled) | Relative or absolute URL to GET after login. The scanner checks for a 2xx response to confirm credentials are working before proceeding. Catches bad credentials early. |

### Session Directory Resolution

When `--auth-file` receives a bare name (no path separators), the scanner resolves it from `session_dir`. Extensions are tried in order: `.yaml`, `.yml`, `.json`.

```bash theme={null}
# These are all equivalent when session_dir is ~/.vigolium/sessions/
vigolium scan https://app.com --auth-file myapp
vigolium scan https://app.com --auth-file ~/.vigolium/sessions/myapp.yaml
vigolium scan https://app.com --auth-file ~/.vigolium/sessions/myapp.json
```

If the bare name has no matching file with any extension, `.yaml` is appended as the default. Absolute paths and relative paths with directory separators (e.g. `./sessions/myapp.json`) bypass `session_dir` and are used as-is.

To change the lookup directory:

```yaml theme={null}
scanning_strategy:
  session:
    session_dir: /opt/vigolium/shared-sessions/
```

### Common Patterns

**Unauthenticated discovery, authenticated scanning:**

```yaml theme={null}
scanning_strategy:
  session:
    use_in_discovery: false
```

Crawls the public-facing site first, then applies session headers only during the audit phase. This is useful when you want to see what an unauthenticated attacker can discover before testing the authenticated surface.

**Authenticated scanning without IDOR testing:**

```yaml theme={null}
scanning_strategy:
  session:
    compare_enabled: false
```

Useful when you only need to scan behind a login wall but don't have multiple user roles to compare. The primary session's credentials are applied to all phases, but no compare requesters are created and the `authz-compare` module stays inactive.

**Long-running scan with token refresh:**

```yaml theme={null}
scanning_strategy:
  session:
    reauth_interval: "30m"
    reauth_on_status: [401, 403]
    validate_url: "/api/whoami"
```

Re-executes login flows every 30 minutes proactively, and also reactively when a 401 or 403 is received. The `validate_url` confirms credentials work after each login before resuming scanning.

**Team shared sessions directory:**

```yaml theme={null}
scanning_strategy:
  session:
    session_dir: /shared/team/vigolium-sessions/
```

Point all team members to a shared directory so `--auth-file staging-admin` resolves the same file for everyone.

Scanning profiles (`~/.vigolium/profiles/`) can also override session strategy values, useful for having a "quick unauthenticated" profile alongside a "deep authenticated" profile.

## Using Session Config with Agent Modes

Agent modes (`swarm`, `autopilot`) can auto-generate session configs from source code analysis. The generated configs are always written as JSON to the session directory.

When running agent swarm with `--source`, the source-analysis phase discovers authentication flows in the codebase and produces a `session-config.json` and `auth-config.yaml` in the session directory. This config is then fed into subsequent scan phases automatically.

**Since v0.5.3 both `agent swarm` and `agent autopilot` take `--auth-file`**, so a session bundle you already lint, check and version-control drives an agentic run exactly as it drives a native scan — no prompt engineering, no credentials in a transcript.

Swarm additionally accepts a pre-built bundle via its own `--auth-config` flag (it skips browser/CLI auth synthesis and uses the file verbatim). You can still put credentials, roles, login URL and browser requirements in `--prompt` (or the positional prompt) for either command; browser tooling is always available and the intent parser extracts the auth signals:

```bash theme={null}
# Swarm with a pre-built auth-config bundle
vigolium agent swarm \
  --target https://app.com \
  --auth-config ./auth-config.json

# Autopilot prepares auth from the task prompt during preflight
vigolium agent autopilot \
  --target https://app.com \
  --prompt "Log in with admin/admin123 and user/user123. Compare both roles for IDOR."

# Or hand either command the same session file a native scan uses (v0.5.3)
vigolium agent autopilot --target https://app.com --auth-file ./sessions.yaml
vigolium agent swarm --target https://app.com --auth-file ./sessions.yaml
```

The REST agent endpoints still accept structured `credentials`, `credential_sets`, `auth_required`, `requires_browser`, `browser_start_url`, and `focus_routes` fields. Their removal applies to the autopilot/swarm CLI flags only.

## Examples

### Scan a REST API with Bearer Token

```bash theme={null}
vigolium scan https://api.example.com \
  --auth "admin:Authorization:Bearer eyJhbG..."
```

### Scan with Cookie-Based Auth

```bash theme={null}
vigolium scan https://app.example.com \
  --auth "user:Cookie:PHPSESSID=abc123; csrftoken=xyz"
```

### Full IDOR Test with Login Automation (YAML)

```bash theme={null}
export ADMIN_USER=admin ADMIN_PASS=admin123
export USER_NAME=user1 USER_PASS=user123

vigolium scan https://app.example.com \
  --auth-file ./auth-config.yaml \
  --module-tag access-control
```

### Full IDOR Test with Login Automation (JSON)

```bash theme={null}
export ADMIN_USER=admin ADMIN_PASS=admin123
export USER_NAME=user1 USER_PASS=user123

vigolium scan https://app.example.com \
  --auth-file ./auth-config.json \
  --module-tag access-control
```

### Combine with Other Scan Options

Auth flags work with all other scan options:

```bash theme={null}
vigolium scan https://app.example.com \
  --auth-file ./auth-config.json \
  --strategy blackbox \
  --only audit \
  --concurrency 10 \
  --format html -o report.html
```

### One-Liner JSON Auth Config

For quick testing or CI scripts, you can write a JSON config inline:

```bash theme={null}
echo '{"sessions":[{"name":"admin","role":"primary","headers":{"Authorization":"Bearer '"$TOKEN"'"}}]}' > /tmp/auth.json
vigolium scan https://app.com --auth-file /tmp/auth.json
```

### Agent-Generated Session Config

When an AI agent discovers auth flows in source code, it produces JSON like:

```json theme={null}
{
  "sessions": [
    {
      "name": "default_user",
      "role": "primary",
      "login": {
        "url": "https://app.com/api/login",
        "method": "POST",
        "content_type": "application/json",
        "body": "{\"email\":\"test@test.com\",\"password\":\"testpassword\"}",
        "extract": [
          {
            "source": "json",
            "path": "$.token",
            "apply_as": "Authorization: Bearer {value}"
          }
        ]
      }
    }
  ]
}
```

This can be saved and reused across scans:

```bash theme={null}
vigolium scan https://app.com --auth-file ./agent-generated-auth.json
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.