feat(009): Affected Products column — Cisco's own scope statements (4.3.0)

[Ali Bahaloo (alibahaloo)]

What and why

The bundle report was authoritative about impact and silent about applicability. A row read "5 devices · 2 affected releases · fixed in 7.4.6" but never said what Cisco scoped the advisory to, nor which Cisco products Cisco had explicitly confirmed are not vulnerable. So an analyst opened Cisco's page once per advisory — 25 times per review of ERP-75736 — and the archived report carried no record of the scope the patch decision rested on.

This adds that context beside the finding:

#	Before (4.2.1)	After (4.3.0)
1	Advisory	Advisory — + publication date beside the CVSS score
2	Published — one 19-char timestamp in 12% of the width	Affected Products — Cisco's two scope statements
3	Impacted products	Your impacted devices

Column 3's rename is not cosmetic: Affected Products (Cisco's scope) and Impacted products (your fleet) are near-synonyms for very different things, and the mistake that invites — reading Cisco's generic scope as a finding about your own estate — is worth designing out.

Where the data comes from

A new shared-surface module, caia/csaf.py — the only module that reads Cisco's published advisory documents. It exists rather than extending erp or psirt for reasons stronger than tidiness:

• erp is deliberately built with no route to supplying an advisory fact. Its docstring states both the rule and the enforcement. Putting content retrieval there would dismantle a safeguard to avoid creating a file.
• psirt owns the API credentials that this request must not carry. Hosting an unauthenticated path there inverts the separation that prohibition creates.

Retrieval follows the csafUrl the advisory API already returns in every record the report holds, so no URL is constructed and no additional advisory-API request is made. Verified live: 0 extra requests.

Measured live against ERP-75736

Statements retrieved	6/6
Bytes transferred	131 KB vs 2.53 MB read in full
Per advisory	0.48 s
Advisory-API requests added	0

Each response is streamed and reading stops as soon as the top-level document object parses — raw_decode raises while the value is incomplete, so the loop is accumulate → attempt → read more. No JSON repair, no brace counting. One advisory came back at revision 1.2.0, which makes the provenance record load-bearing rather than decorative.

Safety properties

• Exactly two normalisations are permitted, each with its own test, plus a test that reconstructs all eight recorded statements from those two rules alone and asserts the output is identical. The worked example matches Cisco's published text character for character.
• No cell is ever blank. Every failure resolves to one of five named causes, so a reader can separate a local network problem from a change on Cisco's side. A blank cell would read as "Cisco affects no products".
• Nothing here decides anything. No verdict, count, population, family derivation, ordering, filter or sort can read the column. Asserted by comparing a report rendered with and without scope statements.
• A retrieval failure never fails a run. Every device finding is identical with retrieval succeeding, failing partially, or failing entirely.
• Escaping is correctness, not just safety. 7 of 25 statements contain raw <, > or & in CLI placeholders like <interface_name>. Unescaped, a browser deletes the placeholder and the text after it — so the tests assert the trailing text survives, not merely that the placeholder renders.

Constitution

Both amendments are in this branch and were prerequisites, not afterthoughts:

• 3.3.0 — new Advisory scope statements bullet admitting the source for two named values only, located by the API-supplied pointer, identity cross-checked, API wins on disagreement, with a faithful-rendering obligation. Scope selectors deliberately not relaxed. Also records that this partly reverses the spec-007 decommission, under narrower terms: no on-disk retention, no temporary folder, no AI processing.
• 3.3.1 — names csaf in the shared surface, discharging 3.3.0's own follow-up item.

Defects found while building

Worth reading, because two changed the design:

1. The extract hid the substance of every not-vulnerable statement. My earlier fix — replacing FR-031's vague "long enough to dominate its row" with "always extract + disclosure" — removed the vagueness but started collapsing short statements, showing only the boilerplate "Only products listed in the Vulnerable Products section…" and hiding the four products Cisco rules out. Now gated on a stated 900-character threshold, set from the measured distribution (Vulnerable Products 217–4,783; Products Confirmed Not Vulnerable 218–818) so no not-vulnerable statement ever collapses.
2. The flow tests were making real network calls — 7.4 s, up from milliseconds — breaking the constitution's no-network test rule.
3. delay=COURTESY_DELAY bound at import, so adjusting the constant did nothing and the suite slept for real.
4. Two fixtures carried placeholders that didn't look like live data: a csafUrl that didn't encode the advisory id (correctly rejected by the identity check) and an advisoryTitle of "Title for <id>" that made rendered previews look as though the title duplicated the identifier.
5. The publication timestamp broke mid-value across lines — published 2026-03- / 04T16:00:00 reads as two facts.

Also corrected: 3.4% is the document object-size floor, not what a chunked reader transfers (5.2% measured live). And spec 008's suite never asserted the column headers at all, so renaming two of them broke nothing — all three are now pinned.

Tests

537 pass, up from 402, in 0.4 s, with no credentials and no network access. Earlier during this work the flow tests took 7.4 s because they were genuinely reaching out; that is fixed and guarded.

Principle compliance

• I — no new dependency; urllib, json, re, html only.
• IV — the column cannot reach a verdict; unavailability is stated, never absent; text is Cisco's under two tested normalisations.
• V — unauthenticated, no Authorization header, and nothing inventory-derived leaves the machine — not even the family/platform/release triple the advisory API is permitted. Asserted against the full captured request.
• VI — csaf prints nothing, prompts for nothing, writes no file, exits nothing; progress goes through a caller-supplied callback. The plan records why non-fatal scope failure does not breach the error-versus-undecided clause.
• Documentation gate — README.md and docs/index.html updated for the seven-module surface, including correcting erp.py's "only module that talks to Cisco's Security Center".
• Versioning gate — VERSION 4.2.1 → 4.3.0 (MINOR: additive report change plus a shared-surface addition).

Left for the reviewer

The one validation I could not run from here is the print / PDF check — that collapsed statements appear in full when the report is printed. <details> keeps the text in the document (asserted), but the rendered output is worth one manual look.

🤖 Generated with Claude Code