Skip to main content

Open Exposure Baseline Catalog (OEBC)

Machine-Readable CVE Exposure Baseline enriched with EPSS, KEV, and Derived Exposure Tiers

CI Python License Catalog Schema

Catalog · Quick Start · CLI · Schema · Automation


What is OEBC?

OEBC is a daily, machine-readable, cloud-agnostic exposure baseline catalog derived from three authoritative sources:

  • NVD — CVE descriptions, CVSS scores, CWE IDs, published/modified dates
  • FIRST.org EPSS — Exploitation probability score and percentile per CVE
  • CISA KEV — Known Exploited Vulnerabilities with ransomware use flags

Every CVE is enriched with derived fields (exposure_tier, actionable) and published as a gzip-compressed JSON catalog at:

https://openastra.org/oebc/catalog/v0.1/latest.json.gz

OEBC is consumed by ExposureGate, a CTEM (Continuous Threat Exposure Management) platform built on exposure baselines.


How It Works

NVD CVE API         FIRST.org EPSS       CISA KEV
(250k+ CVEs)        (EPSS scores)        (Known exploited)
     │                    │                    │
     └────────────────────┴────────────────────┘
                          │
                    oebc generate
                          │
                   Join by CVE ID
                          │
              Enrich: exposure_tier + actionable
                          │
               ┌────────────────┴──────────────────┐
               │                                   │
         latest.json.gz               GitHub Release asset
         (openastra.org repo)     oebc-catalog-YYYY-MM-DD.json.gz
               │
         openastra.org/oebc/catalog/v0.1/

Catalog

Artifact URL
Latest catalog (gzip) https://openastra.org/oebc/catalog/v0.1/latest.json.gz
Historical snapshots GitHub Release assets on each baseline-YYYY-MM-DD release
JSON Schema https://openastra.org/oebc/schema/v0.1/oebc.json
YAML Schema https://openastra.org/oebc/schema/v0.1/oebc.yaml

The catalog is gzip-compressed to stay under GitHub's 100 MB file size limit (raw JSON is ~290 MB; compressed is ~25–30 MB). Historical daily snapshots are attached as release assets rather than committed to the repo, keeping repo size stable.


Quick Start

Download the pre-built catalog (fastest):

# Download and decompress in one step
curl -L https://openastra.org/oebc/catalog/v0.1/latest.json.gz | gunzip > oebc_catalog.json

Or use the CLI:

pip install oebc

# Download pre-built catalog from openastra.org
oebc fetch

# Generate catalog from scratch (fetches all live sources)
oebc generate

Or run from source:

git clone https://github.com/sadayamuthu/oebc.git
cd oebc
make install-dev
make generate

Features

  • 250k+ CVEs — full NVD catalog, updated daily
  • Three authoritative sources — NVD, EPSS, CISA KEV joined by CVE ID
  • Derived exposure tiers — CRITICAL / HIGH / MEDIUM / LOW from KEV, EPSS and CVSS
  • Actionable flag — boolean shortcut for tiers at or above a configurable minimum
  • Null-safe enrichment — missing CVSS or EPSS scores handled gracefully
  • Configurable thresholds — EPSS cutoffs exposed as CLI flags (CVSS bands are fixed at 9.0 and 7.0)
  • Retry-resilient — exponential backoff on NVD / EPSS / KEV HTTP failures
  • Versioned schema — JSON Schema Draft 2020-12 with additionalProperties: false, checked by the test suite
  • PyPI package — pip install oebc

CLI Usage

oebc fetch

Download the pre-built catalog from openastra.org (fast, no live API calls).

oebc fetch
oebc fetch --out my-catalog.json
Flag Default Description
--out oebc_full_catalog_enriched.json Output file path

oebc generate

Fetch NVD + EPSS + CISA KEV live and generate the full enriched catalog.

oebc generate
oebc generate --out catalog.json \
              --actionable_min_tier high \
              --epss_high_threshold 0.10 \
              --epss_medium_threshold 0.01 \
              --nvd_api_key YOUR_KEY
Flag Default Description
--out oebc_full_catalog_enriched.json Output file path
--actionable_min_tier medium Minimum tier for actionable=true (low, medium, high, critical)
--epss_high_threshold 0.10 EPSS score threshold for HIGH tier
--epss_medium_threshold 0.01 EPSS score threshold for MEDIUM tier
--nvd_url NVD API URL Override NVD source URL
--epss_url FIRST.org EPSS URL Override EPSS source URL
--kev_url CISA KEV JSON URL Override KEV source URL
--nvd_api_key (none) NVD API key for higher rate limits (optional)

Output Schema

Top-Level Structure

{
  "project": "Open Exposure Baseline Catalog (OEBC)",
  "project_version": "0.1.0",
  "generated_at_utc": "2026-03-16T06:00:00Z",
  "sources": {
    "nvd": "https://services.nvd.nist.gov/rest/json/cves/2.0",
    "epss": "https://api.first.org/data/v1/epss",
    "kev": "https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json"
  },
  "rules": { ... },
  "count": 250000,
  "vulnerabilities": [ ... ]
}

Per-CVE Record

{
  "cve_id": "CVE-2021-44228",
  "description": "Apache Log4j2 JNDI...",
  "published_date": "2021-12-10",
  "last_modified_date": "2023-03-17",
  "cwe_ids": ["CWE-917", "CWE-20"],
  "cvss_score": 10.0,
  "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H",
  "cvss_version": "3.1",
  "cvss_severity": "CRITICAL",
  "epss_score": 0.97566,
  "epss_percentile": 0.99983,
  "kev_listed": true,
  "kev_date_added": "2021-12-10",
  "kev_due_date": "2021-12-24",
  "kev_ransomware_use": "Known",
  "exposure_tier": "CRITICAL",
  "actionable": true
}

Field Reference

Field Type Description
cve_id string CVE identifier (e.g., CVE-2021-44228)
description string English description from NVD
published_date string ISO 8601 date first published
last_modified_date string ISO 8601 date last modified
cwe_ids array CWE identifiers (empty array if none)
cvss_score number | null CVSS base score (prefers v3.1 > v3.0)
cvss_vector string | null CVSS vector string
cvss_version string | null CVSS version (3.1, 3.0)
cvss_severity string | null CVSS severity label
epss_score number | null EPSS probability (0–1); null if not yet scored
epss_percentile number | null EPSS percentile (0–1); null if not yet scored
kev_listed boolean true if in CISA KEV
kev_date_added string | null Date added to KEV; null if not listed
kev_due_date string | null CISA remediation due date; null if not listed
kev_ransomware_use string | null Ransomware use flag from KEV; null if not listed
exposure_tier string Derived tier: LOW, MEDIUM, HIGH, CRITICAL
actionable boolean true if tier ≥ actionable_min_tier

Exposure Tier Rules

Tiers are evaluated in priority order; first match wins.

Tier Condition
CRITICAL kev_listed = true
HIGH epss_score >= 0.10 OR cvss_score >= 9.0
MEDIUM epss_score >= 0.01 OR cvss_score >= 7.0
LOW everything else

Null handling: null CVSS or EPSS scores evaluate as false in threshold comparisons — they never qualify for a higher tier.

actionable: true when exposure_tier ≥ actionable_min_tier (default: medium), so tiers {MEDIUM, HIGH, CRITICAL} are actionable by default.

Threshold ordering: LOW < MEDIUM < HIGH < CRITICAL


Code Flow

flowchart TD
    A[oebc generate] --> B[fetch_nvd_cves\nPaginated NVD API]
    A --> C[fetch_epss_scores\nPaginated EPSS API]
    A --> D[fetch_kev\nCISA KEV JSON]
    B --> E[build_catalog\nJoin by CVE ID]
    C --> E
    D --> E
    E --> F[compute_exposure_tier\nKEV → CRITICAL\nEPSS/CVSS → HIGH/MEDIUM\nelse → LOW]
    F --> G[compute_actionable\ntier >= actionable_min_tier]
    G --> H[Write JSON\nindent=2]
    H --> I[oebc_full_catalog_enriched.json]

Project Structure

oebc/
├── .github/
│   ├── dependabot.yml          # Weekly grouped pip and Actions updates
│   └── workflows/
│       ├── main-release.yml    # Daily catalog generation → publish to openastra.org
│       ├── schema-release.yml  # Schema versioning → publish schema to openastra.org
│       ├── pypi-publish.yml    # Publish to PyPI on v*.*.* tags
│       └── develop.yml         # CI on PRs and pushes to develop branch
├── spec/
│   ├── VERSION                 # Semver schema version (e.g., 0.1.0)
│   └── schemas/
│       ├── oebc-v0.1.json      # JSON Schema Draft 2020-12
│       └── oebc-v0.1.yaml      # YAML equivalent
├── src/oebc/
│   ├── __init__.py             # Package version
│   ├── __main__.py             # Entry point
│   ├── cli.py                  # CLI dispatcher (fetch/generate)
│   ├── fetch.py                # Download pre-built catalog from openastra.org
│   ├── generate.py             # Core: fetch NVD+EPSS+KEV, join, enrich, output
│   └── urls.py                 # Default source URLs
├── tests/
│   ├── test_cli.py
│   ├── test_fetch.py
│   ├── test_generate.py
│   ├── test_schema_validation.py
│   └── test_version.py
├── CITATION.cff
├── CONTRIBUTING.md
├── LICENSE
├── Makefile
├── pyproject.toml
├── README.md
└── SECURITY.md

Note: No baseline/ or historical/ directory. Catalog artifacts are generated ephemerally in CI and pushed directly to openastra.org — the repo stays clean.


Automation

OEBC ships four GitHub Actions workflows:

develop.yml — Development CI

Triggered on push to develop and pull requests targeting develop or main.

  • make check: lint with ruff, then the full test suite with 100% coverage enforced
  • Runs on Python 3.11, 3.12, 3.13

main-release.yml — Daily Catalog Generation

Triggered on schedule (daily 06:00 UTC), push to main, and manual dispatch.

  1. Test across Python 3.11, 3.12, 3.13
  2. oebc generate --out oebc_full_catalog_enriched.json (ephemeral)
  3. gzip the catalog and push it as public/oebc/catalog/v0.1/latest.json.gz to the openastra.org site repository (served at openastra.org/oebc/catalog/v0.1/latest.json.gz)
  4. If the catalog changed, create a GitHub Release tagged baseline-YYYY-MM-DD with the snapshot attached as oebc-catalog-YYYY-MM-DD.json.gz

Requires secret: OEBC_DEPLOY_TOKEN

schema-release.yml — Schema Publishing

Triggered on push to main affecting spec/**.

  1. Validate spec/VERSION (semver); abort if tag already exists
  2. Publish schema files to openastra.org/oebc/schema/v{MAJOR.MINOR}/
  3. Create GitHub Release tagged spec-v{VERSION} with schema files attached

Requires secret: OEBC_DEPLOY_TOKEN

pypi-publish.yml — PyPI Publishing

Triggered on push of any v*.*.* tag.

  1. Build Python package
  2. Publish to PyPI via OIDC Trusted Publishing (no API token required)

Development

# Install with dev dependencies + pre-commit hooks
make install-dev

# Run tests
make test

# Run tests with 100% coverage report
make test-cov

# Lint
make lint

# Auto-format
make format

# Lint + test-cov
make check

# Generate catalog locally
make generate

Data Sources

Source URL What it provides
NVD CVE API https://services.nvd.nist.gov/rest/json/cves/2.0 All CVEs: description, CVSS score/vector/version/severity, CWE IDs, dates
EPSS API https://api.first.org/data/v1/epss Exploitation probability score (0–1) + percentile per CVE
CISA KEV https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json Known exploited CVEs with dateAdded, dueDate, ransomware use

All sources are fetched live at generation time. No local data files committed to the repo.


Contributing

To report a wrong tier, a wrong EPSS or KEV join or a missing CVE, or to send a change, see CONTRIBUTING.md. It covers the dev setup, the 100% coverage rule, how tier rules change and how the schema is versioned.


Security

Please don't report security problems in a public issue. Use Report a vulnerability on the Security tab; see SECURITY.md for what's in scope.


License

MIT License

The license covers the code in this repository. The catalog republishes NVD, FIRST EPSS and CISA KEV data, which stays under its providers' terms; see Upstream data.


Metadata

Release files for oebc 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for oebc 0.1.0
File Size Uploaded Provenance Actions
oebc-0.1.0.tar.gz 23.1 kB With provenance Details for oebc-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for oebc 0.1.0
File Interpreter ABI Platform Actions
oebc-0.1.0-py3-none-any.whl Python 3 none any Details for oebc-0.1.0-py3-none-any.whl

Total release size: 36.8 kB

Release files / oebc-0.1.0.tar.gz

Download URL oebc-0.1.0.tar.gz
Size 23.1 kB
Tags Source
SHA-256 checksum
How to use checksums
641032e1c0b5b72f4365d1f321e9c1df8d8decd27d6ae4017320607ca3b3d65a
BLAKE2b-256 checksum
How to use checksums
b246614c56b061eabdcfccf9a48d7b89a8e68cc7e67a7bcb46054e7b25176bef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / oebc-0.1.0-py3-none-any.whl

Download URL oebc-0.1.0-py3-none-any.whl
Size 13.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a6113f5742ac9b6cf8269ae4d64c72558c2b64c96a706ab42e369b3bff208013
BLAKE2b-256 checksum
How to use checksums
a9437c972fa62de630da1cfee09949ab4ac7966209bfdebc3888d3199dd7e305
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for oebc 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for oebc-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page