CVE Enrichment

DevGuard's vulnerability database automatically enriches CVE data from multiple authoritative sources and exposes it through a REST API. The enrichment process aggregates data from 7+ sources including OSV, EPSS, CISA KEV, and exploit databases. The API provides programmatic access to enriched CVE information with advanced risk calculations, package vulnerability lookups, and ecosystem statistics.

Base URL: /api/v1/vulndb

API Endpoints

1. List CVEs (Paginated)

GET /api/v1/vulndb

Get a paginated list of enriched CVEs with filtering and sorting capabilities.

Query Parameters

Parameter	Type	Description	Default
`page`	integer	Page number	1
`limit`	integer	Items per page	50
`sort[field]`	string	Sort direction (asc/desc)	-
`filterQuery[field][operator]`	string	Filter conditions	-
`confidentialityRequirements`	string	CIA - Confidentiality (low/medium/high)	medium
`integrityRequirements`	string	CIA - Integrity (low/medium/high)	medium
`availabilityRequirements`	string	CIA - Availability (low/medium/high)	medium

Example Request

GET /api/v1/vulndb?page=1&limit=10&sort[cvss]=desc&filterQuery[cvss][is greater than]=7&confidentialityRequirements=high

Example Response

{
  "page": 1,
  "pageSize": 10,
  "total": 245,
  "data": [
    {
      "cve": "CVE-2024-1234",
      "datePublished": "2024-01-15T00:00:00Z",
      "dateLastModified": "2024-01-20T00:00:00Z",
      "description": "A critical vulnerability in...",
      "cvss": 9.8,
      "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
      "epss": 0.95432,
      "percentile": 0.99876,
      "cisaExploitAdd": "2024-01-16",
      "cisaActionDue": "2024-02-16",
      "cisaRequiredAction": "Apply updates per vendor instructions",
      "cisaVulnerabilityName": "Critical Remote Code Execution",
      "risk": {
        "baseScore": 9.8,
        "withEnvironment": 9.5,
        "withThreatIntelligence": 10.0,
        "withEnvironmentAndThreatIntelligence": 9.8
      },
      "exploits": [
        {
          "id": "exploitdb:12345",
          "description": "Remote code execution exploit",
          "verified": true,
          "sourceURL": "https://exploit-db.com/exploits/12345"
        }
      ],
    }
  ]
}

CVE Object

All API responses include CVE objects with the following structure:

Field	Type	Description	Source
`cve`	string	CVE identifier	OSV/NVD
`datePublished`	timestamp	Publication date	OSV/NVD
`dateLastModified`	timestamp	Last modification date	OSV/NVD
`description`	string	Vulnerability description	OSV/NVD
`cvss`	float	Base CVSS score (0-10)	OSV/NVD
`vector`	string	CVSS vector string (enhanced)	Calculated
`references`	string (JSON)	Array of reference URLs	OSV/NVD
`epss`	float	EPSS probability (0-1)	FIRST EPSS
`percentile`	float	EPSS percentile ranking	FIRST EPSS
`cisaExploitAdd`	date	Date added to CISA KEV	CISA KEV
`cisaActionDue`	date	Remediation deadline	CISA KEV
`cisaRequiredAction`	string	Required remediation action	CISA KEV
`cisaVulnerabilityName`	string	CISA vulnerability name	CISA KEV
`risk`	RiskMetrics	Enhanced risk calculations	Calculated
`exploits`	array	Known exploits	ExploitDB + GitHub
`weaknesses`	array	Associated CWEs	MITRE CWE
`affectedComponents`	array	Vulnerable packages/versions	OSV + Debian
`relationships`	array	Related CVEs	OSV

RiskMetrics Object

Enhanced risk calculation beyond base CVSS:

Field	Type	Description
`baseScore`	float	Original CVSS base score
`withEnvironment`	float	Score adjusted for environment (CIA requirements)
`withThreatIntelligence`	float	Score adjusted for EPSS + exploits
`withEnvironmentAndThreatIntelligence`	float	Fully contextualized risk score

Exploit Object

Field	Type	Description
`id`	string	Exploit identifier (exploitdb:XXX or github:XXX)
`description`	string	Exploit description
`verified`	boolean	Whether exploit is verified
`published`	timestamp	Publication date
`updated`	timestamp	Last update date
`author`	string	Exploit author
`sourceURL`	string	Source URL
`stars`	integer	GitHub stars (GitHub exploits only)
`forks`	integer	GitHub forks (GitHub exploits only)
`integrityRequirements`	string	Integrity requirement
`availabilityRequirements`	string	Availability requirement

Example Request

GET /api/v1/vulndb/CVE-2024-1234?confidentialityRequirements=high

Example Response

{
  "cve": "CVE-2024-1234",
  "datePublished": "2024-01-15T00:00:00Z",
  "dateLastModified": "2024-01-20T00:00:00Z",
  "description": "Detailed vulnerability description...",
  "cvss": 9.8,
  "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H/E:F/RC:C/CR:H",
  "references": "[{\"url\":\"https://...\",\"source\":\"nvd@nist.gov\",\"tags\":[\"Vendor Advisory\"]}]",
  "epss": 0.95432,
  "percentile": 0.99876,
  "cisaExploitAdd": "2024-01-16",
  "cisaActionDue": "2024-02-16",
  "cisaRequiredAction": "Apply updates per vendor instructions",
  "cisaVulnerabilityName": "Critical Remote Code Execution",
  "risk": {
    "baseScore": 9.8,
    "withEnvironment": 9.5,
    "withThreatIntelligence": 10.0,
    "withEnvironmentAndThreatIntelligence": 9.8
  },
  "exploits": [...],
  "weaknesses": [...],
  "affectedComponents": [...],
  "relationships": [...]
}

3. Inspect Package URL (PURL)

GET /api/v1/vulndb/purl-inspect/:purl

Analyze a Package URL to discover vulnerabilities and malicious package information.

Path Parameter: purl (URL-encoded, e.g., pkg:npm/lodash@4.17.20)

Example

GET /api/v1/vulndb/purl-inspect/pkg%3Anpm%2Flodash%404.17.20

Returns: PURL details, affected components, vulnerabilities, and malicious package status.

4. List CVE IDs by Creation Date

GET /api/v1/vulndb/list-ids-by-creation-date

Query Parameters

Parameter	Type	Default
`offset`	integer	0
`limit`	integer	all

5. Get Ecosystem Distribution

GET /api/v1/vulndb/affected-package-distribution

Returns package counts by ecosystem (npm, maven, pypi, go, cargo, nuget, etc.).

Data Sources

Source	Data Provided	Update Frequency
OSV	CVE details, affected packages, version ranges (Go, npm, Maven, PyPI, etc.)	Continuous
EPSS	Exploit prediction scores, percentile rankings	Daily
CISA KEV	Known exploited CVEs, remediation deadlines, required actions	As published
ExploitDB	Verified exploits, publication info	Continuous
GitHub POCs	Proof-of-concept exploits, repository metrics	Continuous
MITRE CWE	Weakness classifications and descriptions	Periodic
Debian Security	Debian package vulnerability info	Continuous

Enhanced Risk Calculation

Risk scores are enhanced beyond base CVSS by incorporating:

Threat Intelligence: EPSS scores, exploit availability, verified exploits, CISA KEV status
Environmental Context: Confidentiality, Integrity, Availability requirements (CIA triad)
CVSS Support: Versions 2.0, 3.0, 3.1, 4.0

The API returns enhanced CVSS vectors with temporal and environmental metrics automatically populated.

Use Cases

1. Vulnerability Assessment

Query CVEs with specific CVSS thresholds and environmental context:

GET /api/v1/vulndb?filterQuery[cvss][is greater than]=7.0&confidentialityRequirements=high

2. Package Vulnerability Scanning

Check if a specific package version has known vulnerabilities:

GET /api/v1/vulndb/purl-inspect/pkg%3Anpm%2Fexpress%404.17.1

3. Exploit Intelligence

Find CVEs with active exploits in CISA KEV:

GET /api/v1/vulndb?filterQuery[cisaExploitAdd][is not null]=true&sort[cisaExploitAdd]=desc

4. Ecosystem Analysis

GET /api/v1/vulndb/affected-package-distribution

Filtering and Sorting

Filter Operators

The API supports sophisticated filtering on CVE fields:

Operator	Example	Description
`is equal to`	`filterQuery[cvss][is equal to]=9.8`	Exact match
`is greater than`	`filterQuery[cvss][is greater than]=7.0`	Greater than
`is less than`	`filterQuery[cvss][is less than]=5.0`	Less than
`is not null`	`filterQuery[epss][is not null]=true`	Field has value
`contains`	`filterQuery[description][contains]=injection`	Text search

Sorting

Sort results by any field in ascending or descending order:

# Sort by CVSS score (descending)
GET /api/v1/vulndb?sort[cvss]=desc

# Sort by publication date (ascending)
GET /api/v1/vulndb?sort[datePublished]=asc

# Sort by EPSS percentile (descending)
GET /api/v1/vulndb?sort[percentile]=desc

Combining Filters and Sorts

GET /api/v1/vulndb?filterQuery[cvss][is greater than]=8.0&filterQuery[epss][is not null]=true&sort[epss]=desc&limit=50

Database Synchronization

Automatic: Updates run via daemon using incremental diffs from ghcr.io/l3montree-dev/devguard/vulndb/v1

Manual Sync:

devguard-cli vulndb sync                                      # Sync all
devguard-cli vulndb sync --databases epss,cisa-kev,exploitdb # Specific sources

Available Sources: cwe, osv, epss, cisa-kev, exploitdb, github-poc, dsa, malicious-packages

Disable Auto-Updates: export DISABLE_VULNDB_UPDATE=true

CVE Enrichment#

API Endpoints#

1. List CVEs (Paginated)#

Query Parameters#

Example Request#

Example Response#

CVE Object#

RiskMetrics Object#

Exploit Object#

Example Request#

Example Response#

3. Inspect Package URL (PURL)#

Example#

4. List CVE IDs by Creation Date#

Query Parameters#

5. Get Ecosystem Distribution#

Data Sources#

Enhanced Risk Calculation#

Use Cases#

1. Vulnerability Assessment#

2. Package Vulnerability Scanning#

3. Exploit Intelligence#

4. Ecosystem Analysis#

Filtering and Sorting#

Filter Operators#

Sorting#

Combining Filters and Sorts#

Database Synchronization#

CVE Enrichment

API Endpoints

1. List CVEs (Paginated)

Query Parameters

Example Request

Example Response

CVE Object

RiskMetrics Object

Exploit Object

Example Request

Example Response

3. Inspect Package URL (PURL)

Example

4. List CVE IDs by Creation Date

Query Parameters

5. Get Ecosystem Distribution

Data Sources

Enhanced Risk Calculation

Use Cases

1. Vulnerability Assessment

2. Package Vulnerability Scanning

3. Exploit Intelligence

4. Ecosystem Analysis

Filtering and Sorting

Filter Operators

Sorting

Combining Filters and Sorts

Database Synchronization