docs(vuln-uplift): asset-tag namespace and Vulnerability Reporting extension#223
Merged
Merged
Conversation
…tension 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
…ory, 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>
… 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>
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.
4 tasks
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>
…ote 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>
… 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>
…kquote 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>
…ags-and-extension-docs
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>
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
Documentation-only PR for the vulnerability-management uplift (one of a 4-agent fan-out; the other three are landing the code). Adds:
lc:asset:*tag namespace (docs/2-sensors-deployment/asset-tags.md) — canonical asset-metadata tag convention covering criticality, exposure, environment, owner, and compliance. Schema, validation rules, mass-tagging examples, and the override-hatch pattern. Intended as a cross-cutting reference; vulnerabilities is the first consumer but the convention applies broadly.docs/5-integrations/extensions/limacharlie/vulnerability-reporting.md) — customer-facing page forext-vulnerability-reporting. Setup, scan modes (scheduled/manual/all), per-criticality SLA windows, criticality-tag overrides, KEV + EPSS enrichment, Phase 2 lifecycle workflow + events (caveated as not-yet-GA), and the full action surface.mkdocs.ymlnav. The two new pages cross-link to each other.2026-05-09) summarizing the uplift.Refs refractionPOINT/tracking#4259
Test plan
mkdocs build --strictpasses (warnings are pre-existing pages-not-in-nav from unrelated1-getting-started/use-cases/*, unchanged by this PR).markdownlint-cli2returns 0 errors on the four touched files (and on the fulldocs/tree).cases.mdandintegrity.mdas templates).Notes
vuln_finding.*events,set_finding_state/clear_finding_state/bulk_set_finding_state/list_finding_statesactions) are explicitly caveated as Phase 2 of the uplift; they may not be live in production at the time this lands.