Bringing together vulnerability intelligence from multiple sources into a single, harmonious API.
ELF (Exposure Lookup Framework) is a modern Python library that streamlines the aggregation, parsing, and analysis of vulnerability data from multiple trusted sources, including:
- CISA KEV – Authoritative catalog of actively exploited vulnerabilities
- FIRST EPSS – Predictive scoring system to gauge exploitation likelihood
- NIST NVD – Comprehensive CVE database maintained by the National Institute of Standards and Technology
Supported Python Versions: 3.10 and above
ELF helps you:
- Effortlessly query and consolidate vulnerability information
- Apply advanced filters, searches, and scoring systems
- Validate structured data using Pydantic models
- Integrate insights into dashboards, CI/CD pipelines, and data-driven security workflows
All with a clean, Pythonic, async-first interface. If you’re new to asynchronous programming in Python, check out the asyncio documentation.
- Features
- Installation
- Supported Data Sources
- Usage
- Attribution and Usage Guidelines
- Special Thanks to Solos
- Contributing
- License
✅ Query vulnerability data from multiple sources
- CISA KEV: Known Exploited Vulnerabilities catalog
- FIRST EPSS: Exploit Prediction Scoring System for prioritization
- NIST NVD: National Vulnerability Database for comprehensive CVE details
🔍 Advanced filtering and searching
- Filter by date, CVE IDs, scores, severity, and more
🛠️ Pydantic-based data validation
- Robust validation for structured data handling
📈 Pagination and bulk data fetching
- Efficiently process large datasets
🚀 Integration-ready
- Seamlessly integrate into dashboards, CI/CD pipelines, or analytics workflows
pip install elfIf you use uv for package management:
uv add elfThe CISA Known Exploited Vulnerabilities (KEV) catalog provides an authoritative list of vulnerabilities actively exploited in the wild. ELF enables seamless programmatic access to these datasets.
The Exploit Prediction Scoring System (EPSS) predicts the likelihood of a CVE being exploited. ELF offers interfaces for JSON and CSV retrievals, along with time-series data.
The National Vulnerability Database (NVD) from NIST is among the most comprehensive CVE data sources. ELF integrates with NVD for CVE details, search functionality, and change history.
importasynciofromelfimportCisaKevApiClient# Fetch all vulnerabilities in JSON formatasyncdeffetch_all_vulnerabilities():
asyncwithCisaKevApiClient() asclient:
kev_data=awaitclient.get_kev_json()
print(f"Catalog Title: {kev_data.catalog_version}")
print(f"Total Vulnerabilities: {kev_data.count}")
# Fetch vulnerabilities as raw CSVasyncdeffetch_vulnerabilities_csv():
asyncwithCisaKevApiClient() asclient:
kev_csv=awaitclient.get_kev_csv()
withopen("kev_data.csv", "wb") asfile:
file.write(kev_csv)
print("CSV data saved as kev_data.csv")
# Fetch paginated dataasyncdeffetch_paginated_vulnerabilities():
asyncwithCisaKevApiClient() asclient:
asyncforchunkinclient.get_kev_json_paginated(chunk_size=500):
print(f"Fetched {len(chunk.vulnerabilities)} vulnerabilities in this chunk.")
# Run examplesasyncdefmain():
awaitfetch_all_vulnerabilities()
awaitfetch_vulnerabilities_csv()
awaitfetch_paginated_vulnerabilities()
asyncio.run(main())importasynciofromelfimportFirstEpssApiClient, FirstEpssOrderOption# Retrieve EPSS scores for specific CVEsasyncdeffetch_epss_scores():
asyncwithFirstEpssApiClient() asclient:
scores=awaitclient.get_scores_json(["CVE-2023-1234", "CVE-2023-5678"])
forscoreinscores.data:
print(f"CVE: {score.cve}, Score: {score.epss}, Percentile: {score.percentile}")
# Download full EPSS CSV for a specific dateasyncdefdownload_full_csv():
asyncwithFirstEpssApiClient() asclient:
csv_data=awaitclient.download_and_decompress_full_csv_for_date("2023-12-01")
withopen("epss_data.csv", "w") asfile:
file.write(csv_data)
print("Decompressed CSV saved as epss_data.csv")
# Fetch the highest EPSS scoresasyncdeffetch_highest_epss_scores():
asyncwithFirstEpssApiClient() asclient:
response=awaitclient.get_cves(order=FirstEpssOrderOption.EPSS_DESC, limit=5)
print("Top 5 CVEs with the highest EPSS scores:")
foriteminresponse.data:
print(f"CVE: {item.cve}, EPSS: {item.epss}, Percentile: {item.percentile}")
# Paginate EPSS dataasyncdeffetch_paginated_epss_scores():
asyncwithFirstEpssApiClient() asclient:
asyncforpageinclient.get_scores_paginated_json(limit_per_request=100, max_records=500):
forrecordinpage.data:
print(f"CVE: {record.cve}, Score: {record.epss}")
# Run examplesasyncdefmain():
awaitfetch_epss_scores()
awaitdownload_full_csv()
awaitfetch_highest_epss_scores()
awaitfetch_paginated_epss_scores()
asyncio.run(main())importasyncioimportosfromdatetimeimportdatetimefromelf.core.exceptionsimportApiClientErrorfromelf.sources.nist_nvd.clientimportNistNvdApiClientNIST_NVD_API_KEY=os.getenv("NIST_NVD_API_KEY")
# Fetch details for a specific CVEasyncdeffetch_cve_details():
asyncwithNistNvdApiClient(api_key=NIST_NVD_API_KEY) asclient:
cve_data=awaitclient.get_cve("CVE-2021-34527")
print(f"CVE ID: {cve_data.vulnerabilities[0].cve.id}")
print(f"Description: {cve_data.vulnerabilities[0].cve.descriptions[0].value}")
# Search CVEs with filtersasyncdefsearch_cves():
try:
asyncwithNistNvdApiClient(api_key=NIST_NVD_API_KEY) asclient:
asyncforpageinclient.search_cves(
cpe_name="cpe:2.3:o:microsoft:windows:-:*:*:*:*:*:*:*",
cvss_v3_severity="HIGH",
pub_start_date=datetime(2016, 3, 1),
pub_end_date=datetime(2016, 3, 12),
):
ifnotpage.vulnerabilities:
print("No vulnerabilities found for this query.")
returnforvulninpage.vulnerabilities:
print(f"CVE ID: {vuln.cve.id}, Published: {vuln.cve.published}")
exceptApiClientErrorase:
print(f"Error during CVE search: {e}")
# Retrieve CVE change historyasyncdeffetch_cve_history():
try:
asyncwithNistNvdApiClient(api_key=NIST_NVD_API_KEY) asclient:
asyncforpageinclient.get_cve_history_paginated(
cve_id="CVE-2021-34527",
change_start_date=datetime(2023, 1, 1),
change_end_date=datetime(2023, 6, 1),
):
ifnotpage.cve_changes:
print("No changes found for this CVE.")
returnprint(page.cve_changes)
exceptApiClientErrorase:
print(f"Error during CVE history fetch: {e}")
# Run examplesasyncdefmain():
awaitfetch_cve_details()
awaitsearch_cves()
awaitfetch_cve_history()
asyncio.run(main())Data provided under the Creative Commons 0 1.0 License (CC0).
Usage must adhere to the FIRST EPSS Usage Guidelines.
Data usage is governed by the NIST Terms of Use.
Special thanks to Solos for donating the elf package name on PyPI.
Contributions are welcome! Please open an issue or submit a pull request for new features or bug fixes.
This project is licensed under the MIT License.