Report Templates

## Two levels in one job The `report` job is one of the few automation jobs whose important settings are not all in `parameters:`. It reads two different places, and the split is meaningful rather than accidental: | where | keys | what they decide | |---|---|---| | under `parameters:` | `template`, `theme`, `reportDir`, `reportFile`, `reportTitle`, `reportDescription`, `displayReport` | which document, what it looks like, where it lands | | at the **job's own level**, beside `parameters:` | `risks`, `confidences`, `sections`, `sites` | **what is in it** | That is a YAML indentation trap with no diagnostic to help you: indent `risks:` under `parameters:` and the job never reads it as a filter, so the report silently contains everything. The reverse mistake is just as quiet. Notice which side `theme` falls on. A theme resolves to a stylesheet inside the template's resources, so it changes colours and layout and nothing else. **A theme changes how the report looks, never which findings it contains.** If someone reaches for a theme to make a report shorter, they have reached for the wrong key. ## Absent means everything This is the single most consequential default in the job: - **`risks` absent** - every risk level is included. - **`confidences` absent** - every confidence band is included, *including the lowest one*, the band that marks an alert as a probable false positive. An unfiltered report is not a filtered-for-signal report. - **`sections` absent** - every section the chosen template declares is rendered. - **`sites` absent** - every site in the session's tree. So the shortest possible `report` job is also the widest one. Narrowing is an opt-in act, and a report nobody configured is the maximal document, not the sensible one. ## What the lists accept, and what a bad entry costs `risks` accepts `high`, `medium`, `low` and `info` (with `information` accepted as an alias). `confidences` accepts `high`, `medium`, `low`, `falsepositive` and `confirmed`. Matching is case-insensitive. Two traps live here. 1. **The add-on's own fully-populated example of this job lists the confidence names without `confirmed`.** The job accepts `confirmed` perfectly well, but a `confidences` list copied from that example and then edited drops every alert a human has explicitly confirmed - the opposite of what anyone filtering for signal intends. Read the accepted values, not the example. 2. **An unrecognised entry is a warning, and contributes nothing.** It does not fall back to including everything. A `risks` list whose entries are all misspelled therefore yields a report containing **no alerts at all**, which looks identical to a clean scan. This is the failure mode to check first when a pipeline suddenly starts reporting nothing. A `sections` entry the chosen template does not declare behaves differently again: it produces a warning and is dropped, and the rest of the report renders normally. Sections can only ever *subtract* from what the template offers, because the template's own markup is what tests each name before emitting its block. A section name the markup never tests does nothing even when you spell it correctly. `sites` is looser than it looks: each entry is matched as a **substring** against the site names in the session tree, and an alert is then kept when its URI starts with a matched site. A short fragment can therefore match more sites than you meant. ## The filter you did not write The job also passes **the plan's own contexts** to the report as a filter, every time, whether or not you asked for it. If your plan defines contexts - and any plan that targets a URL does - then an alert has to fall inside one of them to appear. That is usually what you want, but it means a report can be narrower than its `risks` and `confidences` lists suggest, and the reason lies in a different part of the plan entirely. ## Where the filtering actually happens Filtering is not something the template does. When the job runs it takes the session's alert tree, walks it, and builds a **filtered copy**: an alert instance is carried over only if it is well-formed, falls inside the contexts and sites, and passes both the confidence and risk lists. A parent alert node survives only when at least one of its instances did. The template is then handed that copy and renders whatever reached it. Two things follow. First, the template cannot show you *which alerts* the filter removed, because it never sees them - though it is handed the filter settings themselves, and the default template ships a `reportParameters` section that prints the contexts, the sites and the risk and confidence levels both included and excluded. That disclosure is itself a section, so a `sections` list can remove the paragraph that would have told the reader the report was narrowed. Second, **the session's alerts are untouched** - filtering a report changes the document, not the findings, and running the job again with a different list gives you the other document from the same evidence.