docs(vuln): align Vulnerability Reporting doc with shipped code#224
Merged
maximelb merged 1 commit intoMay 13, 2026
Conversation
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
added
the
to-code-review
maximelb
merged commit f2d02ae
into
vuln-uplift/asset-tags-and-extension-docs
1 of 2 checks passed
maximelb
added a commit
that referenced
this pull request
May 20, 2026
…tension (#223) * docs(vuln-uplift): asset-tag namespace and Vulnerability Reporting extension Vulnerability-management uplift documentation: - New concept page for the canonical lc:asset:* tag namespace under 2-sensors-deployment/ — schema, validation rules, mass-tagging examples, and override-hatch behaviour. Intended to be a cross-cutting reference, not specific to vulnerabilities. - New extension overview for ext-vulnerability-reporting under 5-integrations/extensions/limacharlie/ — covers scan modes, configuration, asset metadata, KEV/EPSS enrichment, the Phase 2 lifecycle workflow and events (caveated as not-yet-GA), and the full API action surface. - Cross-links the two pages, adds them to mkdocs.yml nav and the LimaCharlie extensions index, and adds a 2026-05-09 entry to release notes summarizing the uplift. Refs refractionPOINT/tracking#4259 * docs(vuln-uplift): document LC Risk persistence, audit log, EPSS history, and reachability deferral Extends the Vulnerability Reporting extension page with the new pieces landing in this round of the vuln-management uplift: - New API actions: list_finding_state_history (audit log read path) and query_epss_history (90-day EPSS percentile time-series, backs the CVE-detail sparkline). Replaces the prior round's placeholder list_finding_states entry with the shipping name. - Row schema additions: query_host_vuln_packages now returns fix_version (NVD-derived) and lc_risk; query_cves now returns max_lc_risk; set_finding_state and bulk_set_finding_state responses now echo first_seen_at and remediated_at. - New sort_by value lc_risk on query_cves (max_lc_risk DESC) and query_host_vuln_packages (lc_risk DESC). - Lifecycle audit log subsection: vuln_finding_state_history table, state="cleared" event for clear_finding_state, list_finding_state_history as the read path, with cross-link from Accepted exceptions. - mitigated_by validation: write-time D&R hive lookup, hard-fail with HTTP 400 on unknown rule key, no soft-fail mode. - LC Risk section: scan-time computation in ApplySensorReports, persisted to vuln_reports.lc_risk and rolled up to vuln_cve_counts.max_lc_risk, formula reproduced verbatim and noted as hardcoded-in-sync with src/utils/lcRisk.ts in web-app-frontend. - EPSS history section: daily Update-tick capture model, 90-day default / 365-day max window, reference consumer is the CVE-detail sparkline. - Reachability subsection: documented as deferred (sensor-side telemetry not exposed today); LC Risk criticality multiplier is the interim proxy for triage prioritization. Cross-links from the audit-log and EPSS-history sections to the actions they describe; cross-links from the action table back to the conceptual sections. mkdocs build --strict and markdownlint-cli2 both clean. Refs: refractionPOINT/tracking#4259 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(vuln-uplift): full Vulnerability Reporting reference, workflows, and best practices Pivot the page from a Phase-1/2 milestone-keyed reference into an operator-facing extension manual: complete API action reference for every read/write action including request/response shapes, concept sections for lifecycle states / fingerprints / LC Risk / KEV / EPSS / daily snapshots / the daily Update tick, ten numbered operator workflows (triage, acceptance, mitigated-by-DR, compliance export, audit-log review, EPSS trend monitoring, bulk ops), a real best-practices section (state choice decision tree, tag combos, LC Risk vs CVSS, mitigated_by wiring, SLA configuration, daily-tick expectations, downstream Output wiring), and a glossary. Flagged the backend/frontend `low` criticality multiplier mismatch (0.6 vs 0.8) inline. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(vuln): collapse lifecycle states to 3-resolution model The remediation surface collapsed from a 5-state machine + audit log to a 3-resolution model (mitigated / accepted / false_positive) with no per-finding history. Update the docs to match: rewrite the lifecycle section, replace the set/clear/bulk/list state actions with the new resolution actions, drop the D&R-rule and audit-log workflows + best practices, and note that case_number is reserved for upcoming ext-cases linkage. * docs(vuln): align doc with shipped code (#224) 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> * docs(vuln): fix bulk-resolution example, output filter key, release-note drift Three doc-vs-code mismatches surfaced after the previous align-with-code pass: - `bulk_set_finding_resolution` example showed a per-target `resolution` field. The real `FindingTarget` carries only scope + finding identifiers; `resolution` / `expires_at` / `case_number` are top-level on the request and apply to every target. The response example also flattened `results[].row` into the result object — restored the `row` wrapper so the shape matches `BulkSetFindingResolutionResult`. - Slack output example used a non-existent `filter_event_type:` key. The Outputs system filters by event type via the standard `event_white_list` newline-separated whitelist (see stream-structures.md). Switched the example to use it and linked the reference. - 2026-05-09 release note still listed "per-criticality SLA windows" and the `in_progress` lifecycle state. Both were removed earlier in this branch (no SLA enforcement in code; lifecycle collapsed to the 3-resolution model). Updated the bullets to match what shipped. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(vuln): add blank lines around fenced code blocks inside numbered lists markdownlint MD031 flagged five fenced code blocks (one bash, one bash, one bash, one json) that sit immediately under a numbered-list line without a blank line. The list-item indentation was carried into the fence but the blank-line buffer was missing, so the rule failed even though the rendered output looked fine. Inserts a blank line between the list item's prose line and the following fence (and after each closing fence) so the rule is satisfied. No content changes; verified locally with markdownlint-cli2 v0.20.0 (the CI version) — 0 errors on this file after the edit. The remaining check-markdown failures on the PR — MD028 in docs/8-reference/edr-events.md:362 and :453 — are pre-existing on master (master's own CI is currently failing on the same two lines) and out of scope here. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(edr-events): lift FILE_DELETE/FILE_MODIFIED examples out of blockquote markdownlint MD028 was firing on the two `history_dump` examples inside the FILE_DELETE and FILE_MODIFIED "Best Practices" blockquotes — the indented fenced code block inside a list inside a blockquote was being parsed as a separate blockquote, leaving a blank line between two blockquote blocks. Master's own CI has been red on these two lines all day. Moving the example fence out of the blockquote (it still reads naturally — the bullet ends with "ex." pointing at the example below) satisfies the rule and keeps the rendered output identical. Tagging the fix here so this PR's CI can go green; same edit would be welcome on master. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(edr-events): join Note + Be Aware into single blockquote (MD028) After merging master into the branch, edr-events.md picked up the new `> Note:` block that lives immediately before each `> Be Aware:` block (FILE_DELETE and FILE_MODIFIED). The blank line separating the two adjacent blockquotes is the MD028 trigger the lint check is failing on — most parsers treat them as a single quote, but markdownlint considers the bare blank line ambiguous. Replaces the blank line with `>` so the two paragraphs share one blockquote. Rendered output is unchanged; the Note paragraph and Be Aware paragraph still read as two distinct sections separated by a visual gap. Verified locally: `markdownlint-cli2@0.20.0` (the CI version) reports 0 errors across all 308 files. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Audited
docs/5-integrations/extensions/limacharlie/vulnerability-reporting.mdagainst the actualext-vulnerability-reporting/ext/source. Found six things wrong or missing — this PR fixes them. Stacked on top ofvuln-uplift/asset-tags-and-extension-docs(#223) since that's where the doc lives.Wrong claims removed
sla_windows_hoursconfig field — doc described it as a top-level config knob with defaults and a JSON example. TheConfigurationstruct (extension.go:87-99) has onlyscan_modeandcriticality_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_warningevent — never emitted anywhere in code; nosla_breachscan exists in the daily tick. Removed from the events table, the workflow text, the Outputs-integration list, and the glossary.vuln_finding.resolution_changedevent name — the actual constant isvuln_finding.state_changed(events.go:18). Renamed everywhere.scans.go:97-105runs three scans (kev_match,daily_snapshot,epss_history) withscanLongRunningTimeout = 10 * time.Minute. Updated the tick description, the table, and the glossary.lc:asset:criticality:*the SLA-window source — only the LC Risk multiplier remains.Capabilities now documented
vuln_finding.closedevent (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 whenreset_asset_findingswipes a host. Added to the events table.reset_asset_findingsaction (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, mitigatedstate_changed) for wiring deadlines in their downstream ticketing system.Test plan
created,closed,kev_match,state_changed).sla_breach,resolution_changed, andsla_windows_hours— should be zero hits.🤖 Generated with Claude Code