Skip to content

Created cve-enrichment page #98

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Ph4t3 merged 1 commit into from
Feb 24, 2026
Merged

Created cve-enrichment page #98

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
286 changes: 285 additions & 1 deletion src/pages/reference/vulnerability-database/cve-enrichment.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,288 @@ import PageContentComingSoon from '@/components/PageContentComingSoon'

# CVE Enrichment

<PageContentComingSoon />
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
```bash
GET /api/v1/vulndb?page=1&limit=10&sort[cvss]=desc&filterQuery[cvss][is greater than]=7&confidentialityRequirements=high
```

#### Example Response
```json
{
"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) |confidentialityRequirements` | string | Confidentiality requirement | medium |
| `integrityRequirements` | string | Integrity requirement | medium |
| `availabilityRequirements` | string | Availability requirement | medium |

#### Example Request
```bash
GET /api/v1/vulndb/CVE-2024-1234?confidentialityRequirements=high
```

#### Example Response
```json
{
"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
```bash
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:
```bash
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:
```bash
GET /api/v1/vulndb/purl-inspect/pkg%3Anpm%2Fexpress%404.17.1
```

### 3. Exploit Intelligence
Find CVEs with active exploits in CISA KEV:
```bash
GET /api/v1/vulndb?filterQuery[cisaExploitAdd][is not null]=true&sort[cisaExploitAdd]=desc
```

### 4. Ecosystem Analysis
```bash
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:

```bash
# 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

```bash
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**:
```bash
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`