Documentation
¶
Overview ¶
Package surfaces maps what a descriptor declares to the controls that look at it.
It exists so the question "what did this scan not look at?" has one answer regardless of who asks. The console prints it as a note after a scan; the MCP server returns it beside the verdict. Those two answers diverging would be worse than either being absent, because a reader comparing them has no way to tell which is stale.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Controls = map[string][]string{
"repositories": {"sca", "secrets", "sast", "iac"},
"images": {"images"},
"hosts": {"headers", "tls"},
"infrastructure": {"infrastructure"},
}
Controls names, for each surface a component can declare, the controls that examine it.
Discovery's promise is that the descriptor writes itself, and a descriptor enabling no control has not written itself. It has written a shape, whose first scan reports PASS having checked nothing. This map is what turns a declared surface into the controls that would look at it.
`dast` is deliberately absent from the host list, and is in NeverSuggested instead. The passive host controls read a response; dast sends real traffic at a live service, and turning that on because something noticed the service exists is not a decision Draugr gets to make on someone's behalf.
var NeverSuggested = map[string][]string{
"hosts": {"dast"},
}
NeverSuggested names controls that examine a surface and are never turned on for anybody.
Two questions, two answers. "What should a descriptor enable for this" must not answer dast, and "what is looking at this" must, because a host nothing is testing is a host nothing is testing however the omission came about. Reporting coverage from the enabling list described a host as covered by two controls when three exist.
Functions ¶
func ComponentHas ¶
ComponentHas reports whether a component declares the given surface.
func EnableControls ¶ added in v0.98.0
EnableControls turns on the controls the discovered components can be checked with.
Only controls the descriptor says nothing about are touched. A control someone set, including one they set to `enabled: false`. Is left exactly as it is, because `--merge` runs against a descriptor people edit, and a survey that re-enabled something you had switched off would be a worse failure than the one this fixes.
Returns the controls it added, so the command can say what it did rather than changing the descriptor silently.
func Uncovered ¶
Uncovered is Gaps as sentences, for a caller with one line to say it in.
Each name carries the noun that says which vocabulary it came from. A surface is a word the reader wrote in their own descriptor and a control is a word from Draugr's, and for `images`, `hosts` and `repositories` they are spelled the same. Without the nouns the sentence reads "api declares images, and images is not enabled", which parses as a tautology until somebody already knows one of them is a control, and the reader this is written for does not.
The console says it with column headings instead. A caller with one line has nowhere to put those, so the line carries them.
Types ¶
type Gap ¶ added in v0.119.0
type Gap struct {
// Component and Surface name what was declared and went unexamined.
Component, Surface string
// Controls are the ones that would have looked at it, every one of them off. Partial cover is
// still cover, so a gap is only a gap when none of them is enabled.
Controls []string
}
Gap is one component surface that no enabled control looks at, and the controls that would.
func Gaps ¶ added in v0.119.0
Gaps names each component surface that no enabled control looks at.
A descriptor that declares a `hosts:` entry with the host controls off scans everything about that component except the thing it exposes to the internet, and says nothing. The run is a clean pass over a surface nobody looked at, the same shape as a scan that enables no control at all, which fails loudly, but with a smaller blast radius and no signal whatsoever.
Advisory rather than fatal: the choice may be deliberate, and refusing to scan because a control is off would be worse than the gap.
Source Files