aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
blob: 867d50ec56b76d446c3c5c1c955c30209450032b (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
# nvdb-py

A comprehensive Python library and CLI for querying the [US National Vulnerability Database (NVD) API 2.0](https://nvd.nist.gov/developers).

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- **Full API Coverage**: All 5 NVD API 2.0 endpoints (CVE, CPE, CPE Match, Source, CVE History)
- 🚀 **Async-First**: Built with `httpx` for high-performance async operations
- 🔒 **Type-Safe**: Comprehensive Pydantic models with full type hints
- 🎨 **Rich CLI**: Beautiful table output, JSON, and YAML formats
- **Smart Rate Limiting**: Automatic rate limiting with support for API keys
- 🔍 **30+ Search Parameters**: Extensive CVE filtering options
- 📦 **Zero Config**: Works out of the box, configure only if needed
- 💡 **Helpful CLI**: Contextual help and examples at every level

## Installation

```bash
# Using uv (recommended)
uv pip install nvdb-py

# Using pip
pip install nvdb-py
```

## Quick Start

### Just Installed? Start Here

```bash
# See examples and common commands
nvdb

# Get help for specific commands
nvdb cve --help
nvdb cpe --help
```

### Library Usage

```python
import asyncio
from nvd import NVDClient

async def main():
    async with NVDClient() as client:
        # Get a specific CVE
        cve = await client.cve.get_cve("CVE-2021-44228")
        print(f"{cve.id}: {cve.description}")
        print(f"CVSS Score: {cve.cvss_v3_score}")

        # Search for critical CVEs
        async for cve in client.cve.search_cves(
            keyword="remote code execution",
            cvss_v3_severity="CRITICAL",
            has_kev=True
        ):
            print(f"{cve.id} - Score: {cve.cvss_v3_score}")

asyncio.run(main())
```

### CLI Usage

```bash
# Run without arguments to see helpful examples
nvdb

# CVE Commands
nvdb cve get CVE-2021-44228                                    # Get specific CVE
nvdb cve search --keyword "sql injection" --severity HIGH      # Search with filters
nvdb cve search --cpe "cpe:2.3:a:apache:log4j:*"              # Search by CPE
nvdb cve search --has-kev --severity CRITICAL                  # CISA KEV catalog
nvdb cve history CVE-2021-44228                                # Get change history

# CPE Commands (Product Search)
nvdb cpe search --keyword "windows 10"                         # Keyword search (recommended)
nvdb cpe search --keyword "apache tomcat"                      # Search by product name
nvdb cpe search --match-string "cpe:2.3:a:microsoft:*"        # CPE format search
nvdb cpe matches --cve CVE-2021-44228                          # Get match criteria

# Configuration
nvdb config set-api-key YOUR_API_KEY                           # Configure API key
nvdb config show                                               # Show current config

# Output Formats
nvdb cve get CVE-2021-44228 --format table                     # Table (default)
nvdb cve get CVE-2021-44228 --format json                      # JSON
nvdb cve get CVE-2021-44228 --format yaml                      # YAML
```

> **💡 Tip**: Run any command without arguments to see usage examples:
> - `nvdb cve` - Shows CVE command examples
> - `nvdb cpe` - Shows CPE command examples
> - `nvdb config` - Shows config command examples
```

## Getting Help

The CLI provides contextual help at every level:

```bash
# Show examples and common commands
$ nvdb
╭───────────────── nvdb - NVD API CLI ─────────────────╮
│ Quick Examples:                                      │
│   nvdb cve get CVE-2021-44228                        │
│   nvdb cve search --severity CRITICAL --limit 10     │
│   nvdb cpe search --keyword 'windows 10'             │
│ ...                                                  │
╰──────────────────────────────────────────────────────╯

# Show standard help
nvdb --help

# Show command-specific examples
nvdb cve                    # Shows CVE examples
nvdb cpe                    # Shows CPE examples

# Show detailed command help
nvdb cve search --help      # All search options
nvdb cpe search --help      # CPE search options

# Missing arguments? Get helpful errors
$ nvdb cve get
Error: Missing argument 'CVE_ID'.
Try 'nvdb cve get --help' for help.
```

## API Key Configuration

Get higher rate limits (50 requests/30 seconds) with an API key from [NVD](https://nvd.nist.gov/developers/request-an-api-key).

```bash
# Set via CLI
nvdb config set-api-key YOUR_API_KEY

# Or set environment variable
export NVD_API_KEY=YOUR_API_KEY

# Or pass directly to client
client = NVDClient(api_key="YOUR_API_KEY")
```

## Library API

### NVDClient

Main async client for NVD API operations.

```python
async with NVDClient(api_key="optional") as client:
    # CVE operations
    cve = await client.cve.get_cve("CVE-2021-44228")
    async for cve in client.cve.search_cves(...):
        print(cve.id)

    # CPE operations
    cpe = await client.cpe.get_cpe("uuid")
    async for cpe in client.cpe.search_cpes(keyword="apache"):
        print(cpe.cpeName)

    # CPE Match operations
    async for match in client.cpematch.search_match_criteria(cve_id="CVE-2021-44228"):
        print(match.criteria)

    # Source operations
    async for source in client.source.list_sources():
        print(source.name)

    # CVE History operations
    history = await client.history.get_cve_history("CVE-2021-44228")
```

### CVE Search Parameters

The CVE endpoint supports 30+ parameters:

```python
async for cve in client.cve.search_cves(
    # Identification
    cve_id="CVE-2021-44228",
    cpe_name="cpe:2.3:a:apache:log4j:*",

    # Date ranges (ISO-8601, max 120 days)
    pub_start_date="2021-12-01T00:00:00.000",
    pub_end_date="2021-12-31T23:59:59.999",
    last_mod_start_date="2024-01-01T00:00:00.000",
    last_mod_end_date="2024-12-31T23:59:59.999",

    # CVSS filtering
    cvss_v2_severity="HIGH",
    cvss_v3_severity="CRITICAL",
    cvss_v3_metrics="AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",

    # CWE filtering
    cwe_id="CWE-79",

    # Boolean filters
    has_cert_alerts=True,
    has_cert_notes=True,
    has_kev=True,  # CISA Known Exploited Vulnerabilities
    has_oval=True,
    is_vulnerable=True,
    no_rejected=True,

    # Keyword search
    keyword_search="remote code execution",
    keyword_exact_match=False,

    # Version filtering (with cpe_name)
    version_start="2.0",
    version_start_type="including",
    version_end="2.17.0",
    version_end_type="excluding",

    # Pagination
    results_per_page=100,
    start_index=0,
):
    print(f"{cve.id}: {cve.description}")
```

### CPE Search Parameters

Search for products in two ways:

```python
# 1. Keyword search (recommended) - searches titles and metadata
async for cpe in client.cpe.search_cpes(
    keyword_search="windows",           # Simple text search
    keyword_exact_match=False,          # Partial match (default)
    results_per_page=100
):
    print(f"{cpe.cpeName}: {cpe.title}")

# 2. CPE match string - requires CPE 2.3 format
async for cpe in client.cpe.search_cpes(
    cpe_match_string="cpe:2.3:a:microsoft:*",  # Must be valid CPE format
    results_per_page=100
):
    print(f"{cpe.cpeName}: {cpe.title}")

# Other CPE operations
cpe = await client.cpe.get_cpe("UUID")                        # Get by UUID
matches = await client.cpematch.get_cve_match_criteria("CVE-2021-44228")  # Get match criteria
```

**Important**: `cpe_match_string` requires valid CPE 2.3 format (e.g., `cpe:2.3:a:vendor:product:*`). For simple text searches, use `keyword_search` instead.

## CLI Commands

### CVE Commands

```bash
# Get specific CVE
nvdb cve get CVE-2021-44228

# Search CVEs
nvdb cve search [OPTIONS]
  --keyword, -k TEXT           Keyword to search
  --cpe TEXT                   CPE name filter
  --severity, -s TEXT          CVSS v3 severity (LOW, MEDIUM, HIGH, CRITICAL)
  --cvss-v2-severity TEXT      CVSS v2 severity
  --cvss-v3-severity TEXT      CVSS v3 severity
  --cwe TEXT                   CWE ID (e.g., CWE-79)
  --has-kev                    Only KEV catalog CVEs
  --pub-start TEXT             Publication start date
  --pub-end TEXT               Publication end date
  --mod-start TEXT             Last modified start date
  --mod-end TEXT               Last modified end date
  --limit, -l INTEGER          Max results (default: 20)
  --format, -f TEXT            Output format (table, json, yaml)

# Get CVE history
nvdb cve history CVE-2021-44228
```

### CPE Commands

```bash
# Get specific CPE by UUID
nvdb cpe get <UUID>

# Search CPEs - Two methods:

# 1. Keyword search (recommended for most searches)
nvdb cpe search --keyword "windows"          # Search by product name
nvdb cpe search --keyword "apache tomcat"    # Search by vendor/product
nvdb cpe search -k "mysql" --limit 10        # Limit results

# 2. CPE match string (requires cpe:2.3 format)
nvdb cpe search --match-string "cpe:2.3:a:microsoft:*"     # All Microsoft products
nvdb cpe search -m "cpe:2.3:o:linux:*"                     # All Linux OS entries
nvdb cpe search -m "cpe:2.3:a:*:soft*"                     # Products starting with "soft"

# ⚠️  Note: Use --keyword for plain text, --match-string requires CPE format
# Wrong:  nvdb cpe search -m "apache"           (will fail - not CPE format)
# Right:  nvdb cpe search --keyword "apache"    (correct for text search)
# Right:  nvdb cpe search -m "cpe:2.3:a:apache:*"  (correct for CPE format)

# Get CPE match criteria for a CVE
nvdb cpe matches --cve CVE-2021-44228        # Get all match criteria for CVE
nvdb cpe matches --id <UUID>                  # Get specific match criteria

# Options for all commands:
  --limit, -l INTEGER          Max results (default: 20)
  --format, -f TEXT            Output format (table, json, yaml)
  --api-key TEXT               NVD API key
```

### Config Commands

```bash
# Set API key
nvdb config set-api-key YOUR_API_KEY

# Show configuration
nvdb config show

# Clear configuration
nvdb config clear
```

## API Endpoints

| Endpoint | Description | Base URL |
|----------|-------------|----------|
| CVE | Vulnerability data | `/cves/2.0` |
| CVE History | Change tracking | `/cvehistory/2.0` |
| CPE | Product data | `/cpes/2.0` |
| CPE Match | Match criteria | `/cpematch/2.0` |
| Source | Data sources | `/source/2.0` |

## Rate Limits

- **Without API Key**: 5 requests per 30 seconds
- **With API Key**: 50 requests per 30 seconds

The library automatically handles rate limiting and retries.

## Examples

See the [examples](./examples) directory for more usage examples:

- `basic_usage.py` - Simple CVE and CPE queries
- `advanced_queries.py` - Complex filtering and pagination

## Troubleshooting

### CPE Search Issues

**Problem**: `nvdb cpe search -m "apache"` returns error
```
Error: Invalid CPE match string: apache. CPE match strings must use the format 'cpe:2.3:...'
```

**Solution**: Use `--keyword` for text search or proper CPE format for `--match-string`:
```bash
# Option 1: Use keyword search (recommended)
nvdb cpe search --keyword "apache"

# Option 2: Use proper CPE format
nvdb cpe search --match-string "cpe:2.3:a:apache:*"
```

### Rate Limiting

**Problem**: Getting rate limit errors

**Solutions**:
1. **Get an API key** for higher limits (50 req/30s vs 5 req/30s):
   ```bash
   nvdb config set-api-key YOUR_API_KEY
   ```
2. The library automatically retries with backoff - just wait
3. Reduce request frequency in your code

### No Results Found

**Problem**: Search returns no results

**Debugging steps**:
1. Try broader keywords: `--keyword "windows"` instead of `--keyword "windows 10 pro"`
2. Check date ranges aren't too restrictive
3. Verify CVE IDs are correct format: `CVE-YYYY-NNNNN`
4. For CPE searches, try keyword search first before match strings

### API Connectivity

**Problem**: Connection errors or timeouts

**Solutions**:
1. Check internet connection
2. Verify NVD API is accessible:
   ```bash
   curl -I https://services.nvd.nist.gov/rest/json/cves/2.0
   ```
3. Check if you're behind a proxy (set HTTP_PROXY/HTTPS_PROXY env vars)

## Development

```bash
# Clone repository
git clone https://github.com/nvdb-py/nvdb-py.git
cd nvdb-py

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/
ruff check src/

# Type checking
mypy src/
```

## Requirements

- Python 3.9+
- httpx
- pydantic >= 2.0
- typer
- rich
- pyyaml
- python-dateutil

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Credits

Data provided by the [National Vulnerability Database (NVD)](https://nvd.nist.gov/) by NIST.

## Links

- [NVD API Documentation](https://nvd.nist.gov/developers)
- [NVD Website](https://nvd.nist.gov/)
- [Request an API Key](https://nvd.nist.gov/developers/request-an-api-key)

---

**Note**: This project is not affiliated with or endorsed by NIST or the NVD.