HawkScan REST coverage needs a real OpenAPI spec; spider-only scans test a fraction

HawkScan REST coverage needs a real OpenAPI spec; spider-only scans test a fraction

TL;DR

Before your first HawkScan against a REST API, get an accurate OpenAPI spec wired in. Preference order: a spec the running app itself serves, then a build step that generates one, then a spec published outside the repo, and only then a hand-derived one. Then resolve-check it: host + spec-path must return real routes, not 404s, before you scan.

Use this when you run into the situation in the title.

When not to use this skill: unrelated tasks. It covers only the procedure above.

Compatibility

The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.

Details

A spider-only scan looks green while missing most of your API surface, and a stale spec is worse: every path 404s and the scan reports nothing because it tested nothing. For SPAs, the same logic applies to the backend API: the Ajax spider can crawl the UI, but the higher-value target is usually the API behind it, scanned with its spec.

Real reported problem from web:github.com:stackhawk-openapi-spec: Web source (StackHawk's agent-skills repo, plugins/hawkscan/skills/hawkscan/SKILL.md on github.com): documents a coverage gotcha for REST API scans. A REST scan with no OpenAPI spec (spider or seedPaths only) reaches a small fraction of the API, and a scan with a wrong spec 404s every path. Reaching for spider seedPaths instead of a spec is a last resort, not a shortcut. The verified fix/answer: Before your first HawkScan against a REST API, get an accurate OpenAPI spec wired in. Preference order: a spec the running app itself serves, then a build step that generates one, then a spec published outside the repo, and only then a hand-derived one. Then resolve-check it: host + spec-path must return real routes, not 404s, before you scan. A spider-only scan looks green while missing most of your API surface, and a stale spec is worse: every path 404s and the scan reports nothing because it tested nothing. For SPAs, the same logic applies to the backend API: the Ajax spider can crawl the UI, but the higher-value target is usually the API behind it, scanned with its spec. Source: https://github.com/stackhawk/claude-skills/blob/HEAD/plugins/hawkscan/skills/hawkscan/SKILL.md