docs(vuln-uplift): asset-tag namespace and Vulnerability Reporting extension#223
Draft
maximelb wants to merge 4 commits into
Draft
docs(vuln-uplift): asset-tag namespace and Vulnerability Reporting extension#223maximelb wants to merge 4 commits into
maximelb wants to merge 4 commits into
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.
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.