scan
Runs the declared security controls against a Saga descriptor and returns a verdict with findings ranked by priority. Use when you need a reproducible gate, not a substitute for full code review.
Instructions
Run a scan for a Saga descriptor and return the verdict with findings ranked by priority. This is expensive and has side effects: it clones repositories, executes external scanners and reaches the network. Prefer summarize_report when a recent report already exists.
Scope: this runs the controls the descriptor declares over the components it declares, and nothing else. It is a reproducible floor, not a substitute for reading the code. It does not reason about trust boundaries, whether a build context carries secrets into an image, how credentials are passed to subprocesses, protocol assumptions, or anything a control was not enabled for. If the question was whether a repository is safe to ship rather than whether it passes this gate, keep looking after this returns, the findings here are the part that can be checked the same way every time, not the whole answer. A scan whose scanners do more than read, such as probing a live host or sending data to a third party, or whose results are delivered off this machine, asks the user to approve it first.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | path to the Saga descriptor to scan | |
| limit | No | maximum findings to return; defaults to 20 | |
| minPriority | No | only return findings at this priority or above: p1, p2, p3 or p4 |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| next | Yes | what to do with this result | |
| note | No | ||
| feeds | No | exploitability datasets the scan consulted; absent means no finding was checked against KEV or EPSS | |
| total | Yes | findings the report judged, before any priority filter; excludes suppressed | |
| counts | Yes | ||
| unread | No | dependency files no scanner took packages from, and Terraform files calling a module no scanner loaded; what they declare was not checked | |
| verdict | Yes | pass or fail, by the same policy the CI gate applies | |
| accepted | No | the suppressed findings with who decided and why, most severe first, capped at limit; report each as a decision, never as work to fix | |
| controls | Yes | the controls this scan ran; nothing outside them was examined | |
| findings | Yes | ||
| returned | Yes | ||
| delivered | No | where this run's reports were delivered, from the descriptor's config.publishers | |
| uncovered | No | surfaces this descriptor declares that no enabled control examined | |
| suppressed | No | findings a recorded decision took out of the ranking; not part of total | |
| unexamined | Yes | what a Draugr scan does not examine, whatever the verdict |