# 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
Raw data
{
"_id": null,
"home_page": null,
"name": "epss-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "EPSS, FIRST, CVE, security, vulnerabilities, api, client",
"author": null,
"author_email": "Roshan Kumar <roshaen09@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/df/84/1e8f9e7aef217aa976a78076fbe0d94134dde5654fe911a3920daad8aa2d/epss_client-0.1.0.tar.gz",
"platform": null,
"description": "# EPSS Client\n\nTyped Python client and CLI for the FIRST EPSS (Exploit Prediction Scoring System) API.\n\n## Installation\n\n```bash\npip install epss-client\n```\n\n## Quick start\n\n```python\nfrom epss_client import EpssClient\n\nclient = EpssClient()\n# Single CVE\nresp = client.query(cves=[\"CVE-2022-27225\"]) # returns dict with data list\nprint(resp[\"data\"][0])\n\n# Batch\nresp = client.query(cves=[\"CVE-2022-27225\",\"CVE-2022-27223\",\"CVE-2022-27218\"]) \n\n# Time series (30 days)\nresp = client.query(cves=[\"CVE-2022-25204\"], scope=\"time-series\")\n\n# Top N by EPSS\nresp = client.query(order=\"!epss\", limit=100)\n\n# Thresholds\nresp = client.query(epss_gt=0.95)\nresp = client.query(percentile_gt=0.95)\n\n# Historic by date\nresp = client.query(cves=[\"CVE-2022-26332\"], date=\"2022-03-05\")\n```\n\n### CLI\n\n```bash\n# Show first 100 CVEs\nepss query --limit 100\n\n# Single CVE\nepss get CVE-2022-27225\n\n# Batch\nepss batch CVE-2022-27225 CVE-2022-27223 CVE-2022-27218\n\n# Time series for 30 days\nepss get CVE-2022-25204 --scope time-series\n\n# Top 100\nepss top --limit 100 --order !epss\n\n# Above thresholds\nepss query --epss-gt 0.95\nepss query --percentile-gt 0.95\n\n# Specific date\nepss get CVE-2022-26332 --date 2022-03-05\n\n# Output formats\nepss query --limit 5 --format json\nepss query --limit 5 --format csv > out.csv\n```\n\n## API coverage\n\nThis client wraps `https://api.first.org/data/v1/epss` including:\n- single and batch CVE queries\n- pagination with `offset` and `limit`\n- filters: `date`, `scope=time-series`, `order`, `epss-gt`, `percentile-gt`\n- optional `envelope` and `pretty`\n\nSee the official docs: `https://api.first.org/epss`.\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Typed Python client and CLI for FIRST EPSS (Exploit Prediction Scoring System) API",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://api.first.org/epss",
"Homepage": "https://github.com/youhaveme9/epss-client",
"Issues": "https://github.com/youhaveme9/epss-client/issues",
"Repository": "https://github.com/youhaveme9/epss-client"
},
"split_keywords": [
"epss",
" first",
" cve",
" security",
" vulnerabilities",
" api",
" client"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5055d8dadf1a8cb94649b845eee79465748536d1042c3b0bd754df2a19c23ad5",
"md5": "504d1043a304364ddc83224efbc33679",
"sha256": "1b21363f1dd7d5c3dbe898eeafc4e68c96faafd8d81d74c0bfd15c6fea20449c"
},
"downloads": -1,
"filename": "epss_client-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "504d1043a304364ddc83224efbc33679",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6880,
"upload_time": "2025-08-18T14:19:23",
"upload_time_iso_8601": "2025-08-18T14:19:23.350925Z",
"url": "https://files.pythonhosted.org/packages/50/55/d8dadf1a8cb94649b845eee79465748536d1042c3b0bd754df2a19c23ad5/epss_client-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "df841e8f9e7aef217aa976a78076fbe0d94134dde5654fe911a3920daad8aa2d",
"md5": "69842167a3415740333e83631bac6005",
"sha256": "7255c2cc959a39a42480f6b3d416aa72d9a3cd4d911dc4d8bb5083d3936121ec"
},
"downloads": -1,
"filename": "epss_client-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "69842167a3415740333e83631bac6005",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6261,
"upload_time": "2025-08-18T14:19:24",
"upload_time_iso_8601": "2025-08-18T14:19:24.829919Z",
"url": "https://files.pythonhosted.org/packages/df/84/1e8f9e7aef217aa976a78076fbe0d94134dde5654fe911a3920daad8aa2d/epss_client-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 14:19:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "youhaveme9",
"github_project": "epss-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "epss-client"
}
JSON
