Skip to content

docs(vuln): align Vulnerability Reporting doc with shipped code#224

Merged
maximelb merged 1 commit into
vuln-uplift/asset-tags-and-extension-docsfrom
vuln-uplift/doc-code-alignment-fixes
May 13, 2026
Merged

docs(vuln): align Vulnerability Reporting doc with shipped code#224
maximelb merged 1 commit into
vuln-uplift/asset-tags-and-extension-docsfrom
vuln-uplift/doc-code-alignment-fixes

Conversation

@maximelb
Copy link
Copy Markdown
Contributor

Summary

Audited docs/5-integrations/extensions/limacharlie/vulnerability-reporting.md against the actual ext-vulnerability-reporting/ext/ source. Found six things wrong or missing — this PR fixes them. Stacked on top of vuln-uplift/asset-tags-and-extension-docs (#223) since that's where the doc lives.

Wrong claims removed

  • sla_windows_hours config field — doc described it as a top-level config knob with defaults and a JSON example. The Configuration struct (extension.go:87-99) has only scan_mode and criticality_tag_overrides; configSchema() confirms only those two are exposed. Removed from the config table, JSON example, validation paragraph, and the SLA-configuration best-practices section.
  • vuln_finding.sla_breach_warning event — never emitted anywhere in code; no sla_breach scan exists in the daily tick. Removed from the events table, the workflow text, the Outputs-integration list, and the glossary.
  • vuln_finding.resolution_changed event name — the actual constant is vuln_finding.state_changed (events.go:18). Renamed everywhere.
  • Daily tick = "four scans" with "60-second timeout"scans.go:97-105 runs three scans (kev_match, daily_snapshot, epss_history) with scanLongRunningTimeout = 10 * time.Minute. Updated the tick description, the table, and the glossary.
  • "Counts against SLA" lifecycle column — implied SLA enforcement that does not exist. Dropped the column; surviving language describes posture only.
  • "Prioritize findings" bullet calling lc:asset:criticality:* the SLA-window source — only the LC Risk multiplier remains.

Capabilities now documented

  • vuln_finding.closed event (events.go:16 / events.go:185) — fires when the last sensor holding (cve, normalized_package_name) clears it on a rescan, and per cleared fingerprint when reset_asset_findings wipes a host. Added to the events table.
  • reset_asset_findings action (extension.go:812, reset_findings.go) — wipes every finding owned by (oid, sid). Added to the API actions table and given a reference subsection with request, response, and side-effect notes.

Replacement guidance

The deleted "SLA configuration" section is replaced with a "Tracking remediation deadlines" section explaining that the extension does not enforce a built-in SLA and pointing operators at the available signals (vuln_finding.created, first_seen_at, vuln_finding.closed, mitigated state_changed) for wiring deadlines in their downstream ticketing system.

Test plan

  • Open the rendered doc in a preview and skim each updated section for flow.
  • Verify the events table renders four rows (created, closed, kev_match, state_changed).
  • Verify the Daily Update tick table renders three rows.
  • Search the rendered doc for sla_breach, resolution_changed, and sla_windows_hours — should be zero hits.

🤖 Generated with Claude Code

Removes claims that don't match the extension as it ships:

- `sla_windows_hours` config field (doesn't exist in Configuration struct)
- `vuln_finding.sla_breach_warning` event (never emitted; no SLA-breach
  scan in the daily tick)
- `vuln_finding.resolution_changed` event (real name is
  `vuln_finding.state_changed`)
- Lifecycle "Counts against SLA" column (no SLA enforcement in code)
- Daily tick described as four scans (it's three) with 60s timeout
  (it's 10 minutes — `scanLongRunningTimeout`)

Adds documentation for capabilities the doc had previously omitted:

- `vuln_finding.closed` event (fired by org-scope fingerprint reconciliation
  and by `reset_asset_findings`)
- `reset_asset_findings` action (used for reformat / reimage / decommission
  of a host)

Replaces the SLA-configuration best-practices section with guidance on
how to track remediation cadence externally given that the extension
does not enforce SLAs natively.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@maximelb maximelb requested a review from steveatlc May 13, 2026 03:12
@maximelb maximelb added the to-code-review Used to tag PRs that are force-pushed and will need to be reviewed after the fact. label May 13, 2026
@maximelb maximelb marked this pull request as ready for review May 13, 2026 03:12
@maximelb maximelb merged commit f2d02ae into vuln-uplift/asset-tags-and-extension-docs May 13, 2026
1 of 2 checks passed
@maximelb maximelb deleted the vuln-uplift/doc-code-alignment-fixes branch May 13, 2026 03:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

to-code-review Used to tag PRs that are force-pushed and will need to be reviewed after the fact.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant