Metadata-Version: 2.4
Name: epss-client
Version: 0.1.0
Summary: Typed Python client and CLI for FIRST EPSS (Exploit Prediction Scoring System) API
Author-email: Roshan Kumar <roshaen09@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/youhaveme9/epss-client
Project-URL: Repository, https://github.com/youhaveme9/epss-client
Project-URL: Issues, https://github.com/youhaveme9/epss-client/issues
Project-URL: Documentation, https://api.first.org/epss
Keywords: EPSS,FIRST,CVE,security,vulnerabilities,api,client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3.0.0,>=2.28.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# EPSS Client

Typed Python client and CLI for the FIRST EPSS (Exploit Prediction Scoring System) API.

## Installation

```bash
pip install epss-client
```

## Quick start

```python
from epss_client import EpssClient

client = EpssClient()
# Single CVE
resp = client.query(cves=["CVE-2022-27225"])  # returns dict with data list
print(resp["data"][0])

# Batch
resp = client.query(cves=["CVE-2022-27225","CVE-2022-27223","CVE-2022-27218"]) 

# Time series (30 days)
resp = client.query(cves=["CVE-2022-25204"], scope="time-series")

# Top N by EPSS
resp = client.query(order="!epss", limit=100)

# Thresholds
resp = client.query(epss_gt=0.95)
resp = client.query(percentile_gt=0.95)

# Historic by date
resp = client.query(cves=["CVE-2022-26332"], date="2022-03-05")
```

### CLI

```bash
# Show first 100 CVEs
epss query --limit 100

# Single CVE
epss get CVE-2022-27225

# Batch
epss batch CVE-2022-27225 CVE-2022-27223 CVE-2022-27218

# Time series for 30 days
epss get CVE-2022-25204 --scope time-series

# Top 100
epss top --limit 100 --order !epss

# Above thresholds
epss query --epss-gt 0.95
epss query --percentile-gt 0.95

# Specific date
epss get CVE-2022-26332 --date 2022-03-05

# Output formats
epss query --limit 5 --format json
epss query --limit 5 --format csv > out.csv
```

## API coverage

This client wraps `https://api.first.org/data/v1/epss` including:
- single and batch CVE queries
- pagination with `offset` and `limit`
- filters: `date`, `scope=time-series`, `order`, `epss-gt`, `percentile-gt`
- optional `envelope` and `pretty`

See the official docs: `https://api.first.org/epss`.

## License

MIT
