Authenticated Scanning — Shieldome Docs

Why authenticated scanning matters

Many vulnerabilities only appear after login — broken access control, IDOR, sensitive data in authenticated pages, and logic flaws in user-specific flows. An unauthenticated scan misses all of these. Authenticated scanning lets Shieldome act as a logged-in user and test the full attack surface.

⚠️

You are responsible for only scanning systems you are authorized to test. Using authenticated scanning against a system without explicit written permission is illegal in most jurisdictions.

Method 1 — Cookie injection

The simplest approach: log in manually in your browser, copy the session cookie string from DevTools, and pass it as auth_config.cookie_string. Shieldome attaches these cookies to every request.

json — POST /api/scan body

{
  "target_url": "https://app.example.com",
  "scan_type": "both",
  "auth_config": {
    "type":          "cookie",
    "cookie_string": "sessionid=abc123xyz; csrftoken=def456uvw"
  }
}

💡

In Chrome: open DevTools → Application → Cookies → right-click the domain → Copy all as cURL, then extract the -b "..." cookie string value.

Method 2 — Bearer token

For API-first apps and JWTs, pass the bearer token via auth_config.token. Shieldome automatically prefixes it with Bearer if not already present and adds it as the Authorization header on every request:

json — POST /api/scan body

{
  "target_url": "https://api.example.com",
  "scan_type": "vuln",
  "auth_config": {
    "type":  "token",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

For additional custom headers not related to authentication (e.g. X-Tenant-ID), use the top-level custom_headers field alongside auth_config.

Method 3 — Playwright form login

Shieldome can automate the login form using a headless browser. Provide the login page URL, credentials, and an optional string that appears in the URL after a successful login. Shieldome auto-detects the username and password fields — no CSS selectors required.

json — POST /api/scan body

{
  "target_url": "https://app.example.com/dashboard",
  "scan_type": "both",
  "auth_config": {
    "type":                 "form",
    "login_url":            "https://app.example.com/login",
    "username":             "[email protected]",
    "password":             "s3cur3p@ss",
    "success_url_contains": "/dashboard"  // optional — verify login succeeded
  }
}

After the Playwright login completes, Shieldome extracts the resulting session cookies and uses them for all subsequent scan requests. The browser session is discarded immediately after cookie extraction.

⚠️

Playwright login requires the optional Playwright dependency: pip install playwright && playwright install chromium. If Playwright is not installed, Shieldome returns 412 Precondition Failed with a clear error message.

Verifying authentication worked

After a scan completes, check the auth_status field in the scan result. A value of "authenticated" confirms credentials were attached. If authentication failed — expired cookie, wrong password, MFA challenge — the value is "auth_failed" and the scan falls back to unauthenticated mode, noting this in the scan summary.

json — scan result excerpt

{
  "auth_status":      "authenticated",
  "auth_method":      "playwright",
  "authenticated_as": "[email protected]"  // only set for Playwright logins
}