Skip to content

Commit 2181990

Browse files
Ph4t3Ph4t3
authored
Merge pull request #98 from l3montree-dev/reference/vulnerability-database/cve-enrichment
Created cve-enrichment page
2 parents 0d2cc74 + c6ca82f commit 2181990

File tree

1 file changed

+285
-1
lines changed

1 file changed

+285
-1
lines changed

‎src/pages/reference/vulnerability-database/cve-enrichment.mdx‎

Lines changed: 285 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,288 @@ import PageContentComingSoon from '@/components/PageContentComingSoon'
99

1010
# CVE Enrichment
1111

12-
<PageContentComingSoon />
12+
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.
13+
14+
**Base URL**: `/api/v1/vulndb`
15+
16+
## API Endpoints
17+
18+
### 1. List CVEs (Paginated)
19+
20+
**GET** `/api/v1/vulndb`
21+
22+
Get a paginated list of enriched CVEs with filtering and sorting capabilities.
23+
24+
#### Query Parameters
25+
26+
| Parameter | Type | Description | Default |
27+
|-----------|------|-------------|---------|
28+
| `page` | integer | Page number | 1 |
29+
| `limit` | integer | Items per page | 50 |
30+
| `sort[field]` | string | Sort direction (asc/desc) | - |
31+
| `filterQuery[field][operator]` | string | Filter conditions | - |
32+
| `confidentialityRequirements` | string | CIA - Confidentiality (low/medium/high) | medium |
33+
| `integrityRequirements` | string | CIA - Integrity (low/medium/high) | medium |
34+
| `availabilityRequirements` | string | CIA - Availability (low/medium/high) | medium |
35+
36+
#### Example Request
37+
```bash
38+
GET /api/v1/vulndb?page=1&limit=10&sort[cvss]=desc&filterQuery[cvss][is greater than]=7&confidentialityRequirements=high
39+
```
40+
41+
#### Example Response
42+
```json
43+
{
44+
"page": 1,
45+
"pageSize": 10,
46+
"total": 245,
47+
"data": [
48+
{
49+
"cve": "CVE-2024-1234",
50+
"datePublished": "2024-01-15T00:00:00Z",
51+
"dateLastModified": "2024-01-20T00:00:00Z",
52+
"description": "A critical vulnerability in...",
53+
"cvss": 9.8,
54+
"vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
55+
"epss": 0.95432,
56+
"percentile": 0.99876,
57+
"cisaExploitAdd": "2024-01-16",
58+
"cisaActionDue": "2024-02-16",
59+
"cisaRequiredAction": "Apply updates per vendor instructions",
60+
"cisaVulnerabilityName": "Critical Remote Code Execution",
61+
"risk": {
62+
"baseScore": 9.8,
63+
"withEnvironment": 9.5,
64+
"withThreatIntelligence": 10.0,
65+
"withEnvironmentAndThreatIntelligence": 9.8
66+
},
67+
"exploits": [
68+
{
69+
"id": "exploitdb:12345",
70+
"description": "Remote code execution exploit",
71+
"verified": true,
72+
"sourceURL": "https://exploit-db.com/exploits/12345"
73+
}
74+
],
75+
}
76+
]
77+
}
78+
````
79+
80+
### CVE Object
81+
82+
All API responses include CVE objects with the following structure:
83+
84+
| Field | Type | Description | Source |
85+
|-------|------|-------------|--------|
86+
| `cve` | string | CVE identifier | OSV/NVD |
87+
| `datePublished` | timestamp | Publication date | OSV/NVD |
88+
| `dateLastModified` | timestamp | Last modification date | OSV/NVD |
89+
| `description` | string | Vulnerability description | OSV/NVD |
90+
| `cvss` | float | Base CVSS score (0-10) | OSV/NVD |
91+
| `vector` | string | CVSS vector string (enhanced) | Calculated |
92+
| `references` | string (JSON) | Array of reference URLs | OSV/NVD |
93+
| `epss` | float | EPSS probability (0-1) | FIRST EPSS |
94+
| `percentile` | float | EPSS percentile ranking | FIRST EPSS |
95+
| `cisaExploitAdd` | date | Date added to CISA KEV | CISA KEV |
96+
| `cisaActionDue` | date | Remediation deadline | CISA KEV |
97+
| `cisaRequiredAction` | string | Required remediation action | CISA KEV |
98+
| `cisaVulnerabilityName` | string | CISA vulnerability name | CISA KEV |
99+
| `risk` | RiskMetrics | Enhanced risk calculations | Calculated |
100+
| `exploits` | array | Known exploits | ExploitDB + GitHub |
101+
| `weaknesses` | array | Associated CWEs | MITRE CWE |
102+
| `affectedComponents` | array | Vulnerable packages/versions | OSV + Debian |
103+
| `relationships` | array | Related CVEs | OSV |
104+
105+
### RiskMetrics Object
106+
107+
Enhanced risk calculation beyond base CVSS:
108+
109+
| Field | Type | Description |
110+
|-------|------|-------------|
111+
| `baseScore` | float | Original CVSS base score |
112+
| `withEnvironment` | float | Score adjusted for environment (CIA requirements) |
113+
| `withThreatIntelligence` | float | Score adjusted for EPSS + exploits |
114+
| `withEnvironmentAndThreatIntelligence` | float | Fully contextualized risk score |
115+
116+
### Exploit Object
117+
118+
| Field | Type | Description |
119+
|-------|------|-------------|
120+
| `id` | string | Exploit identifier (exploitdb:XXX or github:XXX) |
121+
| `description` | string | Exploit description |
122+
| `verified` | boolean | Whether exploit is verified |
123+
| `published` | timestamp | Publication date |
124+
| `updated` | timestamp | Last update date |
125+
| `author` | string | Exploit author |
126+
| `sourceURL` | string | Source URL |
127+
| `stars` | integer | GitHub stars (GitHub exploits only) |
128+
| `forks` | integer | GitHub forks (GitHub exploits only) |confidentialityRequirements` | string | Confidentiality requirement | medium |
129+
| `integrityRequirements` | string | Integrity requirement | medium |
130+
| `availabilityRequirements` | string | Availability requirement | medium |
131+
132+
#### Example Request
133+
```bash
134+
GET /api/v1/vulndb/CVE-2024-1234?confidentialityRequirements=high
135+
```
136+
137+
#### Example Response
138+
```json
139+
{
140+
"cve": "CVE-2024-1234",
141+
"datePublished": "2024-01-15T00:00:00Z",
142+
"dateLastModified": "2024-01-20T00:00:00Z",
143+
"description": "Detailed vulnerability description...",
144+
"cvss": 9.8,
145+
"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",
146+
"references": "[{\"url\":\"https://...\",\"source\":\"[email protected]\",\"tags\":[\"Vendor Advisory\"]}]",
147+
"epss": 0.95432,
148+
"percentile": 0.99876,
149+
"cisaExploitAdd": "2024-01-16",
150+
"cisaActionDue": "2024-02-16",
151+
"cisaRequiredAction": "Apply updates per vendor instructions",
152+
"cisaVulnerabilityName": "Critical Remote Code Execution",
153+
"risk": {
154+
"baseScore": 9.8,
155+
"withEnvironment": 9.5,
156+
"withThreatIntelligence": 10.0,
157+
"withEnvironmentAndThreatIntelligence": 9.8
158+
},
159+
"exploits": [...],
160+
"weaknesses": [...],
161+
"affectedComponents": [...],
162+
"relationships": [...]
163+
}
164+
```
165+
166+
---
167+
168+
### 3. Inspect Package URL (PURL)
169+
170+
**GET** `/api/v1/vulndb/purl-inspect/:purl`
171+
172+
Analyze a Package URL to discover vulnerabilities and malicious package information.
173+
174+
**Path Parameter**: `purl` (URL-encoded, e.g., `pkg:npm/[email protected]`)
175+
176+
#### Example
177+
```bash
178+
GET /api/v1/vulndb/purl-inspect/pkg%3Anpm%2Flodash%404.17.20
179+
```
180+
Returns: PURL details, affected components, vulnerabilities, and malicious package status.
181+
182+
### 4. List CVE IDs by Creation Date
183+
184+
**GET** `/api/v1/vulndb/list-ids-by-creation-date`
185+
186+
#### Query Parameters
187+
| Parameter | Type | Default |
188+
|-----------|------|---------|
189+
| `offset` | integer | 0 |
190+
| `limit` | integer | all |
191+
192+
### 5. Get Ecosystem Distribution
193+
194+
**GET** `/api/v1/vulndb/affected-package-distribution`
195+
196+
Returns package counts by ecosystem (npm, maven, pypi, go, cargo, nuget, etc.).
197+
198+
## Data Sources
199+
200+
| Source | Data Provided | Update Frequency |
201+
|--------|---------------|------------------|
202+
| **OSV** | CVE details, affected packages, version ranges (Go, npm, Maven, PyPI, etc.) | Continuous |
203+
| **EPSS** | Exploit prediction scores, percentile rankings | Daily |
204+
| **CISA KEV** | Known exploited CVEs, remediation deadlines, required actions | As published |
205+
| **ExploitDB** | Verified exploits, publication info | Continuous |
206+
| **GitHub POCs** | Proof-of-concept exploits, repository metrics | Continuous |
207+
| **MITRE CWE** | Weakness classifications and descriptions | Periodic |
208+
| **Debian Security** | Debian package vulnerability info | Continuous |
209+
210+
## Enhanced Risk Calculation
211+
212+
Risk scores are enhanced beyond base CVSS by incorporating:
213+
- **Threat Intelligence**: EPSS scores, exploit availability, verified exploits, CISA KEV status
214+
- **Environmental Context**: Confidentiality, Integrity, Availability requirements (CIA triad)
215+
- **CVSS Support**: Versions 2.0, 3.0, 3.1, 4.0
216+
217+
The API returns enhanced CVSS vectors with temporal and environmental metrics automatically populated.
218+
219+
## Use Cases
220+
221+
### 1. Vulnerability Assessment
222+
Query CVEs with specific CVSS thresholds and environmental context:
223+
```bash
224+
GET /api/v1/vulndb?filterQuery[cvss][is greater than]=7.0&confidentialityRequirements=high
225+
```
226+
227+
### 2. Package Vulnerability Scanning
228+
Check if a specific package version has known vulnerabilities:
229+
```bash
230+
GET /api/v1/vulndb/purl-inspect/pkg%3Anpm%2Fexpress%404.17.1
231+
```
232+
233+
### 3. Exploit Intelligence
234+
Find CVEs with active exploits in CISA KEV:
235+
```bash
236+
GET /api/v1/vulndb?filterQuery[cisaExploitAdd][is not null]=true&sort[cisaExploitAdd]=desc
237+
```
238+
239+
### 4. Ecosystem Analysis
240+
```bash
241+
GET /api/v1/vulndb/affected-package-distribution
242+
```
243+
244+
## Filtering and Sorting
245+
246+
### Filter Operators
247+
248+
The API supports sophisticated filtering on CVE fields:
249+
250+
| Operator | Example | Description |
251+
|----------|---------|-------------|
252+
| `is equal to` | `filterQuery[cvss][is equal to]=9.8` | Exact match |
253+
| `is greater than` | `filterQuery[cvss][is greater than]=7.0` | Greater than |
254+
| `is less than` | `filterQuery[cvss][is less than]=5.0` | Less than |
255+
| `is not null` | `filterQuery[epss][is not null]=true` | Field has value |
256+
| `contains` | `filterQuery[description][contains]=injection` | Text search |
257+
258+
### Sorting
259+
260+
Sort results by any field in ascending or descending order:
261+
262+
```bash
263+
# Sort by CVSS score (descending)
264+
GET /api/v1/vulndb?sort[cvss]=desc
265+
266+
# Sort by publication date (ascending)
267+
GET /api/v1/vulndb?sort[datePublished]=asc
268+
269+
# Sort by EPSS percentile (descending)
270+
GET /api/v1/vulndb?sort[percentile]=desc
271+
```
272+
273+
### Combining Filters and Sorts
274+
275+
```bash
276+
GET /api/v1/vulndb?filterQuery[cvss][is greater than]=8.0&filterQuery[epss][is not null]=true&sort[epss]=desc&limit=50
277+
```
278+
279+
---
280+
281+
282+
283+
## Database Synchronization
284+
285+
**Automatic**: Updates run via daemon using incremental diffs from `ghcr.io/l3montree-dev/devguard/vulndb/v1`
286+
287+
**Manual Sync**:
288+
```bash
289+
devguard-cli vulndb sync # Sync all
290+
devguard-cli vulndb sync --databases epss,cisa-kev,exploitdb # Specific sources
291+
```
292+
293+
**Available Sources**: `cwe`, `osv`, `epss`, `cisa-kev`, `exploitdb`, `github-poc`, `dsa`, `malicious-packages`
294+
295+
**Disable Auto-Updates**: `export DISABLE_VULNDB_UPDATE=true`
296+

0 commit comments

Comments
 (0)