scan

Probes one or more URLs to determine whether each response is cacheable per HTTP semantics (RFC 9111), whether it’s actually being cached, and how the fronting CDN/reverse proxy handles the cache key.

cache-detective scan --url https://example.com/

Resource selection

Exactly one of these must be set:

Flag	Description
--url	Single target URL to scan
--list	Path to a newline-delimited list of URLs (#-prefixed lines are comments)
--sitemap	URL of a sitemap.xml to scan (flat <urlset> only, not <sitemapindex>)
--har	Path to a .har file to import GET/HEAD requests from
--crawl	Crawl same-origin links starting from --url instead of scanning it alone

Crawl-specific flags

Flag	Default	Description
--path-prefix	(none)	Restrict --crawl to URLs under this path prefix
--max-pages	50	Maximum pages to discover with --crawl
--respect-robots	true	Honor robots.txt Disallow rules for * during --crawl

cache-detective scan --url https://example.com/ --crawl --path-prefix /blog --max-pages 100

Request configuration

Flag	Default	Description
--method	GET	HTTP method to test
--header	(none)	Custom request header "Name=Value" (repeatable)
--cookie	(none)	Cookie "name=value" to send with every request (repeatable)
--bearer	(none)	Bearer token for authenticated cache testing
--auth-profiles	(none)	Path to a JSON file mapping target origin (scheme://host[:port]) to per-origin headers/cookies/bearer, overriding --header/--cookie/--bearer for matching resources
--max-retries	0	Maximum retry attempts per probe request on transient failures (0 = no retries)
--retry-delay	500ms	Base delay between retry attempts (grows with backoff, honors Retry-After)
--requests	3	Probe requests issued per resource for live cache-state detection
--interval	500ms	Delay between consecutive probe requests to the same resource
--timeout	15s	Per-request timeout
--stale-window-max-wait	30s	Maximum time to wait for a resource to enter its declared stale-while-revalidate window before giving up on actively confirming it
--max-concurrency	number of CPUs	Maximum concurrent checks
--max-resource-concurrency	number of CPUs	Maximum concurrent resources per check

cache-detective scan --url https://example.com/account \
  --bearer "$TOKEN" \
  --cookie "session=abc123" \
  --header "X-Api-Version=2"

Per-target auth profiles

--header, --cookie, and --bearer apply the same credentials to every resource in the scan. When a --list, --sitemap, --har, or --crawl run spans multiple hosts that each need different credentials, use --auth-profiles instead: a JSON file mapping each target’s origin to its own headers, cookies, and/or bearer token. A resource whose origin has no matching entry falls back to --header/--cookie/--bearer.

auth-profiles.json

{
  "https://api.example.com": {
    "bearer": "eyJhbGciOi...",
    "headers": { "X-Api-Version": ["2"] }
  },
  "https://admin.example.com": {
    "cookies": { "session": "abc123" }
  }
}

cache-detective scan --list urls.txt --auth-profiles auth-profiles.json

Security probing

Attention

--aggressive probes for cache poisoning and cache deception — a positive result means the probe just demonstrated it can plant content in a shared cache other users may be served. Only run it against systems you own or have explicit written permission to test.

Flag	Default	Description
--aggressive	false	Enable cache poisoning/deception probing
--max-aggressive-requests	10	Hard cap on extra probe requests per resource for --aggressive checks (and the read-only vary-key check), even with --aggressive set
--cache-buster-mode	query	How --aggressive checks isolate poison/confirm requests from the resource’s real cache entry: query, header, or both
--cache-buster-param	cd_cachebuster	Query parameter name used in query/both cache-buster mode
--cache-buster-header	X-Cache-Detective-Buster	Request header name used in header/both cache-buster mode
--unkeyed-wordlist	(none)	Path to a newline-delimited wordlist of extra candidate names to supplement the bundled header/cookie/query-parameter unkeyed-input mining wordlists

cache-detective scan --url https://staging.example.com/ --aggressive

--aggressive also gates stale-if-error confirmation — since confirming it means asking the origin to simulate a failure.

Cache-buster isolation

Every check that writes attacker-controlled content or an error response back through the resource’s own URL (unkeyed header injection, error-response caching, response splitting, CPDoS) sends its poison-then-confirm request pair to a cache-buster-isolated URL/header instead of the plain resource URL — a fresh random token per attempt, reused for both the poisoning request and its confirmation. This is what lets the check confirm a shared cache actually replays what it just planted, without ever poisoning the cache entry a real visitor’s plain request to that URL would read from.

If a target’s cache normalizes/strips one buster form (e.g. drops unrecognized query params), point it at the other:

cache-detective scan --url https://staging.example.com/ --aggressive --cache-buster-mode header

Unkeyed-input mining wordlist

The unkeyed-header-injection check (§5) mines each of three input surfaces — headers, cookies, and query parameters — against a bundled default wordlist per surface. --unkeyed-wordlist supplements all three with app-specific candidate names of your own, e.g. an internal feature-flag cookie or an API-gateway routing header the bundled lists don’t cover:

wordlist.txt

# blank lines and "#" comments are ignored
X-Internal-Route
feature-flag
api_version

cache-detective scan --url https://staging.example.com/ --aggressive --unkeyed-wordlist wordlist.txt

--max-aggressive-requests is shared across all three surfaces (headers mined before cookies before query parameters), so mining the full bundled wordlist — let alone a custom one — may need raising it well past its default of 10.

Output

scan shares its output/reporting flags with the rest of the CerberAuth CLI suite:

Flag	Default	Description
--format	terminal	Terminal display format
--no-color	false	Disable ANSI colors in terminal output
--quiet	false	Suppress terminal display of the report
--output	(none)	File path to additionally write the report to
--output-format	json	Format for --output
--show-all-findings	false	Show every finding on stdout, not just active ones
--report-url	(none)	HTTP endpoint to POST the report to
--report-header	(none)	Additional HTTP headers for the report transport (key=value)
--report-format	json	Format for --report-url

cache-detective scan --url https://example.com/ --output-format json --output report.json --quiet

Exit codes

scan exits 1 if any check itself failed to execute (network errors, timeouts, …) and 0 otherwise — findings are reported but don’t affect the exit code on their own. To gate a build on specific findings, parse the JSON output (see the GitHub Actions guide) or use diff to detect drift against a baseline.