oebc 0.1.0__py3-none-any.whl

oebc/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("oebc")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"

oebc/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

oebc/cli.py

@@ -0,0 +1,48 @@
+"""CLI dispatcher for the oebc command."""
+
+from __future__ import annotations
+
+import argparse
+
+from . import __version__
+from .fetch import main as fetch_main
+from .generate import _generate_parser
+from .generate import main as generate_main
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="oebc",
+        description="Open Exposure Baseline Catalog (OEBC) CLI",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # fetch subcommand
+    fetch_p = subparsers.add_parser(
+        "fetch",
+        help="Download the pre-built catalog from openastra.org (fast)",
+    )
+    fetch_p.add_argument(
+        "--out",
+        default="oebc_full_catalog_enriched.json",
+        help="Output file path (default: oebc_full_catalog_enriched.json)",
+    )
+
+    # generate subcommand — inherits all flags from _generate_parser
+    subparsers.add_parser(
+        "generate",
+        help="Generate the catalog from scratch from NVD, EPSS, and CISA KEV sources",
+        parents=[_generate_parser(add_help=False)],
+    )
+
+    args = parser.parse_args()
+    if args.command == "fetch":
+        fetch_main(args)
+    else:
+        generate_main(args)

oebc/fetch.py

@@ -0,0 +1,24 @@
+"""Download the pre-built OEBC catalog from openastra.org."""
+
+from __future__ import annotations
+
+import argparse
+import gzip
+import json
+
+import requests
+
+from .urls import OEBC_CATALOG_URL
+
+
+def main(args: argparse.Namespace) -> None:
+    print(f"Fetching catalog from {OEBC_CATALOG_URL} ...")
+    r = requests.get(OEBC_CATALOG_URL, timeout=60)
+    r.raise_for_status()
+    # Catalog is gzip-compressed. Decompress regardless of Content-Encoding header
+    # (GitHub Pages does not automatically set Content-Encoding for .gz files).
+    raw = gzip.decompress(r.content)
+    data = json.loads(raw)
+    with open(args.out, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+    print(f"Wrote {data.get('count', '?')} vulnerabilities to {args.out}")

oebc/generate.py

@@ -0,0 +1,305 @@
+"""Core catalog generation logic for OEBC.
+
+Fetches CVE data from NVD, EPSS scores from FIRST.org, and KEV list from CISA.
+Joins all three by CVE ID, computes exposure_tier and actionable, writes JSON.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from datetime import UTC, datetime
+from typing import Any
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from .urls import EPSS_URL, KEV_URL, NVD_URL
+
+# NVD API returns at most 2000 results per page
+_NVD_PAGE_SIZE = 2000
+
+# EPSS API page size — fetch in large batches
+_EPSS_PAGE_SIZE = 10000
+
+# Tier ordering for actionable comparison
+_TIER_ORDER = {"LOW": 0, "MEDIUM": 1, "HIGH": 2, "CRITICAL": 3}
+
+
+# ─── Data fetching ───────────────────────────────────────────────────────────
+
+def _make_session() -> requests.Session:
+    """Return a requests Session with automatic retry on transient errors."""
+    session = requests.Session()
+    retry = Retry(
+        total=5,
+        backoff_factor=2,
+        status_forcelist=[429, 500, 502, 503, 504],
+        allowed_methods=["GET"],
+        raise_on_status=False,
+    )
+    adapter = HTTPAdapter(max_retries=retry)
+    session.mount("https://", adapter)
+    session.mount("http://", adapter)
+    return session
+
+
+def fetch_nvd_cves(nvd_url: str, api_key: str | None = None) -> list[dict]:
+    """Fetch all CVEs from the NVD API (paginated). Returns list of raw CVE dicts."""
+    cves: list[dict] = []
+    start = 0
+    total = None
+
+    while total is None or start < total:
+        params: dict = {"startIndex": start, "resultsPerPage": _NVD_PAGE_SIZE}
+        if api_key:
+            params["apiKey"] = api_key
+        r = _make_session().get(
+            nvd_url,
+            params=params,
+            timeout=60,
+        )
+        r.raise_for_status()
+        data = r.json()
+        total = data["totalResults"]
+        page_cves = [v["cve"] for v in data.get("vulnerabilities", [])]
+        cves.extend(page_cves)
+        start += len(page_cves)
+        if len(page_cves) == 0:
+            break
+
+    return cves
+
+
+def fetch_epss_scores(epss_url: str) -> dict[str, dict]:
+    """Fetch all EPSS scores (paginated). Returns dict keyed by CVE ID."""
+    scores: dict[str, dict] = {}
+    offset = 0
+    total = None
+
+    while total is None or offset < total:
+        r = _make_session().get(
+            epss_url,
+            params={"offset": offset, "limit": _EPSS_PAGE_SIZE},
+            timeout=60,
+        )
+        r.raise_for_status()
+        data = r.json()
+        total = data["total"]
+        page_data = data.get("data", [])
+        for record in page_data:
+            scores[record["cve"]] = {
+                "epss": float(record["epss"]),
+                "percentile": float(record["percentile"]),
+            }
+        offset += len(page_data)
+        if len(page_data) == 0:
+            break
+
+    return scores
+
+
+def fetch_kev(kev_url: str) -> dict[str, dict]:
+    """Fetch CISA KEV list. Returns dict keyed by CVE ID."""
+    r = _make_session().get(kev_url, timeout=30)
+    r.raise_for_status()
+    data = r.json()
+    return {
+        v["cveID"]: {
+            "date_added": v.get("dateAdded"),
+            "due_date": v.get("dueDate"),
+            "ransomware_use": v.get("knownRansomwareCampaignUse"),
+        }
+        for v in data.get("vulnerabilities", [])
+    }
+
+
+# ─── CVE field extraction ────────────────────────────────────────────────────
+
+def extract_cvss(cve: dict) -> tuple[float | None, str | None, str | None, str | None]:
+    """Extract (score, vector, version, severity) from a NVD CVE dict.
+
+    Prefers CVSS v3.1, then v3.0. Returns (None, None, None, None) if no score assigned.
+    """
+    metrics = cve.get("metrics", {})
+    for key in ("cvssMetricV31", "cvssMetricV30"):
+        entries = metrics.get(key, [])
+        if entries:
+            d = entries[0]["cvssData"]
+            return (
+                d.get("baseScore"),
+                d.get("vectorString"),
+                d.get("version"),
+                d.get("baseSeverity"),
+            )
+    return None, None, None, None
+
+
+def extract_cwes(cve: dict) -> list[str]:
+    """Extract CWE IDs from a NVD CVE dict, excluding NVD placeholder values."""
+    _PLACEHOLDERS = {"NVD-CWE-noinfo", "NVD-CWE-Other"}
+    result = []
+    for weakness in cve.get("weaknesses", []):
+        for desc in weakness.get("description", []):
+            val = desc.get("value", "")
+            if desc.get("lang") == "en" and val not in _PLACEHOLDERS:
+                result.append(val)
+    return result
+
+
+def extract_description(cve: dict) -> str:
+    """Return the English description for a NVD CVE, or empty string if none."""
+    for desc in cve.get("descriptions", []):
+        if desc.get("lang") == "en":
+            return desc.get("value", "")
+    return ""
+
+
+# ─── Enrichment ──────────────────────────────────────────────────────────────
+
+def compute_exposure_tier(
+    kev_listed: bool,
+    epss_score: float | None,
+    cvss_score: float | None,
+    epss_high_threshold: float,
+    epss_medium_threshold: float,
+) -> str:
+    """Compute exposure tier. Rules evaluated in priority order; first match wins.
+
+    Tier ordering: LOW < MEDIUM < HIGH < CRITICAL
+    Null scores do not qualify any threshold comparison.
+    """
+    if kev_listed:
+        return "CRITICAL"
+    epss_ok = epss_score is not None
+    cvss_ok = cvss_score is not None
+    if (epss_ok and epss_score >= epss_high_threshold) or (cvss_ok and cvss_score >= 9.0):
+        return "HIGH"
+    if (epss_ok and epss_score >= epss_medium_threshold) or (cvss_ok and cvss_score >= 7.0):
+        return "MEDIUM"
+    return "LOW"
+
+
+def compute_actionable(exposure_tier: str, actionable_min_tier: str) -> bool:
+    """Return True if exposure_tier >= actionable_min_tier (LOW < MEDIUM < HIGH < CRITICAL)."""
+    return _TIER_ORDER[exposure_tier] >= _TIER_ORDER[actionable_min_tier.upper()]
+
+
+# ─── Catalog assembly ────────────────────────────────────────────────────────
+
+def build_catalog(
+    nvd_cves: list[dict],
+    epss_scores: dict[str, dict],
+    kev_data: dict[str, dict],
+    args: argparse.Namespace,
+) -> dict[str, Any]:
+    """Join NVD + EPSS + KEV, compute derived fields, return catalog dict."""
+    vulnerabilities = []
+    for cve in nvd_cves:
+        cve_id = cve["id"]
+        cvss_score, cvss_vector, cvss_version, cvss_severity = extract_cvss(cve)
+        epss = epss_scores.get(cve_id)
+        epss_score = epss["epss"] if epss else None
+        epss_percentile = epss["percentile"] if epss else None
+        kev = kev_data.get(cve_id)
+        kev_listed = kev is not None
+        exposure_tier = compute_exposure_tier(
+            kev_listed, epss_score, cvss_score,
+            args.epss_high_threshold, args.epss_medium_threshold,
+        )
+        vulnerabilities.append({
+            "cve_id": cve_id,
+            "description": extract_description(cve),
+            "published_date": cve.get("published", "")[:10],
+            "last_modified_date": cve.get("lastModified", "")[:10],
+            "cwe_ids": extract_cwes(cve),
+            "cvss_score": cvss_score,
+            "cvss_vector": cvss_vector,
+            "cvss_version": cvss_version,
+            "cvss_severity": cvss_severity,
+            "epss_score": epss_score,
+            "epss_percentile": epss_percentile,
+            "kev_listed": kev_listed,
+            "kev_date_added": kev["date_added"] if kev else None,
+            "kev_due_date": kev["due_date"] if kev else None,
+            "kev_ransomware_use": kev["ransomware_use"] if kev else None,
+            "exposure_tier": exposure_tier,
+            "actionable": compute_actionable(exposure_tier, args.actionable_min_tier),
+        })
+
+    return {
+        "project": "Open Exposure Baseline Catalog (OEBC)",
+        "project_version": _package_version(),
+        "generated_at_utc": datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "sources": {
+            "nvd": args.nvd_url,
+            "epss": args.epss_url,
+            "kev": args.kev_url,
+        },
+        "rules": {
+            "exposure_tier_definition": {
+                "critical": "kev_listed = true",
+                "high": f"epss_score >= {args.epss_high_threshold} OR cvss_score >= 9.0",
+                "medium": f"epss_score >= {args.epss_medium_threshold} OR cvss_score >= 7.0",
+                "low": "everything else",
+            },
+            "tier_order": "LOW < MEDIUM < HIGH < CRITICAL",
+            "actionable_min_tier": args.actionable_min_tier,
+        },
+        "count": len(vulnerabilities),
+        "vulnerabilities": vulnerabilities,
+    }
+
+
+def _package_version() -> str:
+    from . import __version__
+    return __version__
+
+
+# ─── CLI entry point ─────────────────────────────────────────────────────────
+
+def _generate_parser(add_help: bool = True) -> argparse.ArgumentParser:
+    """Return the ArgumentParser for the generate subcommand."""
+    p = argparse.ArgumentParser(
+        prog="oebc generate",
+        description="Generate the OEBC catalog from NVD, EPSS, and CISA KEV sources.",
+        add_help=add_help,
+    )
+    p.add_argument("--out", default="oebc_full_catalog_enriched.json",
+                   help="Output file path (default: oebc_full_catalog_enriched.json)")
+    p.add_argument("--actionable_min_tier", default="medium",
+                   choices=["low", "medium", "high", "critical"],
+                   help="Minimum tier for actionable=true (default: medium)")
+    p.add_argument("--epss_high_threshold", type=float, default=0.10,
+                   help="EPSS score threshold for HIGH tier (default: 0.10)")
+    p.add_argument("--epss_medium_threshold", type=float, default=0.01,
+                   help="EPSS score threshold for MEDIUM tier (default: 0.01)")
+    p.add_argument("--nvd_url", default=NVD_URL, help="Override NVD source URL")
+    p.add_argument("--epss_url", default=EPSS_URL, help="Override EPSS source URL")
+    p.add_argument("--kev_url", default=KEV_URL, help="Override CISA KEV source URL")
+    p.add_argument("--nvd_api_key", default=None,
+                   help="NVD API key for higher rate limits (optional)")
+    return p
+
+
+def main(args: argparse.Namespace) -> None:
+    """Generate the catalog from live sources and write to args.out."""
+    print(f"Fetching CVEs from NVD: {args.nvd_url}")
+    nvd_cves = fetch_nvd_cves(args.nvd_url, api_key=getattr(args, "nvd_api_key", None))
+    print(f"  → {len(nvd_cves)} CVEs fetched")
+
+    print(f"Fetching EPSS scores: {args.epss_url}")
+    epss_scores = fetch_epss_scores(args.epss_url)
+    print(f"  → {len(epss_scores)} EPSS records fetched")
+
+    print(f"Fetching CISA KEV: {args.kev_url}")
+    kev_data = fetch_kev(args.kev_url)
+    print(f"  → {len(kev_data)} KEV entries fetched")
+
+    print("Building catalog...")
+    catalog = build_catalog(nvd_cves, epss_scores, kev_data, args)
+
+    with open(args.out, "w", encoding="utf-8") as f:
+        json.dump(catalog, f, ensure_ascii=False, indent=2)
+    print(f"Wrote {catalog['count']} vulnerabilities to {args.out}")

oebc/urls.py

@@ -0,0 +1,17 @@
+"""Default source URLs for OEBC data sources and published catalog.
+
+Override any URL via CLI flags or by setting OEBC_*_URL environment variables.
+"""
+
+# NVD CVE 2.0 API — paginated, max 2000 results per page
+NVD_URL = "https://services.nvd.nist.gov/rest/json/cves/2.0"
+
+# FIRST.org EPSS API — exploitation probability scores for all CVEs
+EPSS_URL = "https://api.first.org/data/v1/epss"
+
+# CISA Known Exploited Vulnerabilities catalog
+KEV_URL = "https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json"
+
+# Pre-built OEBC catalog published daily to openastra.org (gzip-compressed JSON)
+# Update this constant when the schema major/minor version changes (e.g., v0.1 → v0.2)
+OEBC_CATALOG_URL = "https://openastra.org/oebc/catalog/v0.1/latest.json.gz"

oebc-0.1.0.dist-info/METADATA

@@ -0,0 +1,451 @@
+Metadata-Version: 2.4
+Name: oebc
+Version: 0.1.0
+Summary: Open Exposure Baseline Catalog — daily CVE exposure baseline enriched with EPSS, KEV, and derived exposure tiers.
+Author: Karthikeyan Sadayamuthu
+License-Expression: MIT
+Project-URL: Homepage, https://openastra.org
+Project-URL: Source, https://github.com/sadayamuthu/oebc
+Project-URL: Issues, https://github.com/sadayamuthu/oebc/issues
+Project-URL: Catalog, https://openastra.org/oebc/catalog/v0.1/latest.json.gz
+Keywords: cve,epss,kev,vulnerability,exposure,security,nvd
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: pre-commit>=4.0; extra == "dev"
+Requires-Dist: jsonschema>=4.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# Open Exposure Baseline Catalog (OEBC)
+
+**Machine-Readable CVE Exposure Baseline enriched with EPSS, KEV, and Derived Exposure Tiers**
+
+[![CI](https://github.com/sadayamuthu/oebc/actions/workflows/develop.yml/badge.svg)](https://github.com/sadayamuthu/oebc/actions/workflows/develop.yml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/github/license/sadayamuthu/oebc)](LICENSE)
+[![Catalog](https://img.shields.io/badge/catalog-latest-green)](https://openastra.org/oebc/catalog/v0.1/latest.json.gz)
+[![Schema](https://img.shields.io/badge/schema-v0.1-blue)](https://openastra.org/oebc/schema/v0.1/oebc.json)
+
+[Catalog](#catalog) · [Quick Start](#quick-start) · [CLI](#cli-usage) · [Schema](#output-schema) · [Automation](#automation)
+
+</div>
+
+---
+
+## What is OEBC?
+
+OEBC is a daily, machine-readable, cloud-agnostic **exposure baseline catalog** derived from three authoritative sources:
+
+- **[NVD](https://nvd.nist.gov/)** — CVE descriptions, CVSS scores, CWE IDs, published/modified dates
+- **[FIRST.org EPSS](https://www.first.org/epss/)** — Exploitation probability score and percentile per CVE
+- **[CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)** — 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):**
+
+```bash
+# 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:**
+
+```bash
+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:**
+
+```bash
+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).
+
+```bash
+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.
+
+```bash
+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
+
+```json
+{
+  "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
+
+```json
+{
+  "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
+
+```mermaid
+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
+
+```bash
+# 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](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**](https://github.com/sadayamuthu/oebc/security/advisories/new)
+on the Security tab; see **[SECURITY.md](SECURITY.md)** for what's in scope.
+
+---
+
+## License
+
+[MIT License](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](CONTRIBUTING.md#upstream-data).
+
+---
+
+<div align="center">
+
+[Catalog](https://openastra.org/oebc/catalog/v0.1/latest.json.gz) · [Schema](https://openastra.org/oebc/schema/v0.1/oebc.json) · [PyPI](https://pypi.org/project/oebc/) · [openastra.org](https://openastra.org)
+
+</div>

oebc-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+oebc/__init__.py,sha256=cpF0Dixb94fOpfg8uXerg-k_pShDx-Kbdtsr5w2HRBo,176
+oebc/__main__.py,sha256=jUDiCGRIhJvfwEslxaIxuuBq7RQwE_t_z0CFJRVfNl8,81
+oebc/cli.py,sha256=BZ28pYNVRqg8uh9fCJRswt_opXpQ6nnqCQp1wIPAWpw,1312
+oebc/fetch.py,sha256=I6juIlNEFKG2_RWc9S28nVdCPXGb8dE_6h8FUzpHVJ4,785
+oebc/generate.py,sha256=811hq43RWjzc0Sc615J_eFvL8z3ZuRw9bgT2Nro7t0E,11664
+oebc/urls.py,sha256=8Grp92uxWJ_rwdm2Ix1ClEFBfwBrSn87rkdKwDwJT14,783
+oebc-0.1.0.dist-info/licenses/LICENSE,sha256=Rmq4mhzHm3g4XKkcf_IFAbiW9FPkQ2zeBx0yomCC7CY,1080
+oebc-0.1.0.dist-info/METADATA,sha256=yh4g8qMcO9zldI8A5uCV9pbJupl0yfhRuCL79lY6D08,15813
+oebc-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+oebc-0.1.0.dist-info/entry_points.txt,sha256=eCalFxww6KksZLKnWvDTC9ajXkwJyJ12pJnrxbeFAWY,39
+oebc-0.1.0.dist-info/top_level.txt,sha256=8GXueB-P_e5IEnbqJTboNg3Tydzkr_VgVnruLzmH244,5
+oebc-0.1.0.dist-info/RECORD,,

oebc-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

oebc-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+oebc = oebc.cli:main

oebc-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karthikeyan Sadayamuthu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oebc-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+oebc