Vulnerability Management

Overview

Vulnerability management is a critical pillar of proactive security operations. While the Alerts and Incidents modules handle real-time threat response, the Vulnerability Management module addresses the underlying attack surface — the known weaknesses in infrastructure, applications, and endpoints that adversaries can exploit before they do.

This module provides a full vulnerability lifecycle management system: asset inventory tracking, multi-scanner ingestion (Tenable, Qualys, Rapid7), risk-based prioritization using CVSS + EPSS scores with CISA Known Exploited Vulnerabilities (KEV) correlation, remediation SLA tracking with per-severity deadlines, a severity-vs-exploitability risk matrix heatmap, and trending velocity metrics (discovery rate, remediation rate, MTTR by week).

What Was Proposed

• Asset inventory management with hostname, IP, OS, criticality, owner, and department
• Vulnerability tracking with CVE ID, CVSS score, EPSS score, CISA KEV status, and affected asset mapping
• Risk-based prioritization engine combining CVSS, EPSS, and KEV factors into a composite risk score
• Multi-scanner import support for Tenable, Qualys, and Rapid7 scan result normalization
• CISA KEV catalog synchronization (live HTTP fetch from CISA)
• Remediation SLA enforcement: critical=15 days, high=30 days, medium=90 days, low=180 days
• Severity vs exploitability risk matrix for dashboard heatmap visualization
• Trending analytics: discovery velocity, remediation velocity, and MTTR trend by week
• Status lifecycle: open → in_progress → remediated / accepted / risk_accepted
• CSV bulk import for asset inventory

What's Built

Architecture

Backend Service: VulnerabilityManager

File: app/services/vulnerability_mgmt.py — The VulnerabilityManager class is instantiated as a singleton (vuln_manager) at module import time. It holds two in-memory dictionaries (assets and vulnerabilities) and a KEV catalog dict that is populated via async HTTP fetch from CISA. Demo data is loaded in __init__ via _load_demo_data().

Key Methods

Remediation SLA Thresholds

SLA_DAYS = {
    "critical": 15,   # Must remediate within 15 days of discovery
    "high":     30,   # Must remediate within 30 days
    "medium":   90,   # Must remediate within 90 days
    "low":      180,  # Must remediate within 180 days
}

CISA KEV Integration

The KEV (Known Exploited Vulnerabilities) catalog is fetched from https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json using httpx.AsyncClient. The catalog is stored in vuln_manager.kev_catalog as a dict keyed by CVE ID. Vulnerabilities with cisa_kev=True receive an elevated risk priority in the prioritization sort. The catalog sync records a timestamp in kev_last_sync.

Scanner Normalization

The ingest_scan_results method accepts three scanner types and maps their field names to the internal Vulnerability dataclass. This allows raw scan output from different tools to be stored in a unified schema:

API Endpoints

All endpoints are defined in app/routers/vulnerability.py under the prefix /api/v1.

Vulnerability Endpoints

GET  /api/v1/vulnerabilities
     # List all vulns with optional filters
     # Query params: severity, status, asset_id, cve_id, skip=0, limit=100

GET  /api/v1/vulnerabilities/prioritized?limit=50
     # Active vulns sorted by risk_score descending

GET  /api/v1/vulnerabilities/risk-matrix
     # Severity vs exploitability count matrix for heatmap

GET  /api/v1/vulnerabilities/stats
     # Dashboard stats: total_vulns, critical_open, high_open, avg_risk_score, sla_compliance

GET  /api/v1/vulnerabilities/sla
     # Remediation SLA compliance per severity tier (15/30/90/180 day thresholds)

GET  /api/v1/vulnerabilities/trending
     # Weekly discovery_velocity, remediation_velocity, mttr_trend data points

GET  /api/v1/vulnerabilities/kev/{cve_id}
     # Check if a CVE ID is in the CISA KEV catalog (case-insensitive, normalized to uppercase)

GET  /api/v1/vulnerabilities/{vuln_id}
     # Get a single vulnerability by ID (404 if not found)

PATCH /api/v1/vulnerabilities/{vuln_id}
     # Update status, notes, assigned_to
     # Body: VulnStatusUpdate { status, notes?, assigned_to? }
     # Valid statuses: open | in_progress | remediated | accepted | risk_accepted
     # 400 on invalid status, 404 if not found

Scanner Integration

POST /api/v1/vulnerabilities/scan/import
     # Import and normalize scan results
     # Body: ScanImport { scanner_type: "tenable|qualys|rapid7", results: [...] }
     # Returns: { status, scanner, vulnerabilities_processed, total_tracked }

POST /api/v1/vulnerabilities/kev/sync
     # Sync CISA KEV catalog (async HTTP fetch from CISA)
     # Returns: { synced: bool, count: int, last_sync: ISO timestamp }

Asset Endpoints

POST /api/v1/assets                             (HTTP 201)
     # Register a new asset
     # Body: AssetCreate { hostname, ip, os?, criticality?, owner?, department?, tags? }

GET  /api/v1/assets
     # List all assets with optional filters
     # Query params: department, criticality, skip=0, limit=100

GET  /api/v1/assets/{asset_id}
     # Get asset with associated vulnerability list
     # Returns: Asset fields + vulnerability_count + vulnerabilities: [...]
     # 404 if not found

Routing

Data Model

The Vulnerability Management module uses in-memory Python dataclasses. No SQLAlchemy ORM tables are used for this module. Data is pre-seeded with realistic demo entries on startup.

Asset Dataclass

Vulnerability Dataclass

Demo Data (pre-loaded)

Prerequisites

• VulnerabilityManager singleton — app/services/vulnerability_mgmt.py imports and instantiates vuln_manager at module level. The router imports this singleton directly. No database or migration required.
• httpx — The sync_kev_catalog() method requires httpx (async HTTP client) to fetch the CISA KEV JSON feed. It is listed in requirements.txt. If CISA is unreachable, the method returns an error response without raising.
• Router registration — app/main.py must include app.include_router(vulnerability.router) for the endpoints to be served. Both /api/v1/vulnerabilities and /api/v1/assets are registered under the same router with prefix /api/v1.
• Frontend API Client — src/lib/api-client.ts provides api.get() used for the six parallel data fetches on page mount. Each individual call uses .catch(() => null) so a single endpoint failure does not break the entire page. Mock data is used as initial state and updated only when API returns valid data.

UI Layout