flagrante 0.0.1__py3-none-any.whl

flagrante/sbom.py

@@ -0,0 +1,207 @@
+"""SBOM parsing: CycloneDX and SPDX JSON -> a normalised component list.
+
+Deliberately dependency-free. Both formats are read leniently: a malformed or
+partially-populated SBOM should still yield whatever components it does carry,
+because a manufacturer under time pressure is exactly who produces one.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any, Iterable
+
+
+class SBOMError(ValueError):
+    """The input could not be read as a supported SBOM."""
+
+
+@dataclass(frozen=True)
+class Component:
+    """One software component as named by the SBOM."""
+
+    name: str
+    version: str | None
+    purl: str | None
+    ecosystem: str | None = None
+    licenses: tuple[str, ...] = field(default=())
+
+    @property
+    def label(self) -> str:
+        return f"{self.name}@{self.version}" if self.version else self.name
+
+    @property
+    def identifiable(self) -> bool:
+        """Whether this component can be looked up against a vulnerability feed.
+
+        Without a purl we cannot query OSV reliably, and guessing an ecosystem
+        from a bare name invites false negatives -- the one direction this tool
+        must never fail in. Such components are reported as unresolvable rather
+        than silently dropped.
+        """
+        return bool(self.purl)
+
+
+@dataclass
+class SBOMDocument:
+    format: str
+    spec_version: str | None
+    components: list[Component]
+    subject: str | None = None
+
+    @property
+    def identifiable(self) -> list[Component]:
+        return [c for c in self.components if c.identifiable]
+
+    @property
+    def unresolvable(self) -> list[Component]:
+        return [c for c in self.components if not c.identifiable]
+
+
+_PURL_ECOSYSTEM = re.compile(r"^pkg:([a-zA-Z0-9._-]+)/")
+
+
+def _ecosystem_from_purl(purl: str | None) -> str | None:
+    if not purl:
+        return None
+    match = _PURL_ECOSYSTEM.match(purl)
+    return match.group(1).lower() if match else None
+
+
+def _clean(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _cyclonedx_licenses(entry: dict) -> tuple[str, ...]:
+    out: list[str] = []
+    for item in entry.get("licenses") or []:
+        if not isinstance(item, dict):
+            continue
+        lic = item.get("license")
+        if isinstance(lic, dict):
+            name = _clean(lic.get("id") or lic.get("name"))
+            if name:
+                out.append(name)
+        expression = _clean(item.get("expression"))
+        if expression:
+            out.append(expression)
+    return tuple(dict.fromkeys(out))
+
+
+def _walk_cyclonedx(entries: Iterable[dict]) -> Iterable[dict]:
+    """Yield components including nested ones, which CycloneDX permits."""
+    for entry in entries or []:
+        if not isinstance(entry, dict):
+            continue
+        yield entry
+        nested = entry.get("components")
+        if isinstance(nested, list):
+            yield from _walk_cyclonedx(nested)
+
+
+def _parse_cyclonedx(doc: dict) -> SBOMDocument:
+    components: list[Component] = []
+    for entry in _walk_cyclonedx(doc.get("components") or []):
+        name = _clean(entry.get("name"))
+        if not name:
+            continue
+        group = _clean(entry.get("group"))
+        if group and not name.startswith(group):
+            name = f"{group}/{name}"
+        purl = _clean(entry.get("purl"))
+        components.append(
+            Component(
+                name=name,
+                version=_clean(entry.get("version")),
+                purl=purl,
+                ecosystem=_ecosystem_from_purl(purl),
+                licenses=_cyclonedx_licenses(entry),
+            )
+        )
+
+    metadata = doc.get("metadata") or {}
+    target = metadata.get("component") or {}
+    subject = _clean(target.get("name")) if isinstance(target, dict) else None
+
+    return SBOMDocument(
+        format="CycloneDX",
+        spec_version=_clean(doc.get("specVersion")),
+        components=components,
+        subject=subject,
+    )
+
+
+def _spdx_purl(entry: dict) -> str | None:
+    for ref in entry.get("externalRefs") or []:
+        if not isinstance(ref, dict):
+            continue
+        if str(ref.get("referenceType", "")).lower() == "purl":
+            return _clean(ref.get("referenceLocator"))
+    return None
+
+
+def _parse_spdx(doc: dict) -> SBOMDocument:
+    components: list[Component] = []
+    for entry in doc.get("packages") or []:
+        if not isinstance(entry, dict):
+            continue
+        name = _clean(entry.get("name"))
+        if not name:
+            continue
+        version = _clean(entry.get("versionInfo"))
+        purl = _spdx_purl(entry)
+        declared = _clean(entry.get("licenseDeclared"))
+        licenses = (declared,) if declared and declared != "NOASSERTION" else ()
+        components.append(
+            Component(
+                name=name,
+                version=version,
+                purl=purl,
+                ecosystem=_ecosystem_from_purl(purl),
+                licenses=licenses,  # type: ignore[arg-type]
+            )
+        )
+
+    return SBOMDocument(
+        format="SPDX",
+        spec_version=_clean(doc.get("spdxVersion")),
+        components=components,
+        subject=_clean(doc.get("name")),
+    )
+
+
+def parse(raw: str | bytes) -> SBOMDocument:
+    """Read a CycloneDX or SPDX JSON SBOM.
+
+    Raises SBOMError when the input is not JSON or carries no recognisable
+    format marker, so the caller can tell the user what to hand us instead.
+    """
+    if isinstance(raw, bytes):
+        raw = raw.decode("utf-8-sig", errors="replace")
+
+    try:
+        doc = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise SBOMError(f"not valid JSON ({exc.msg} at line {exc.lineno})") from exc
+
+    if not isinstance(doc, dict):
+        raise SBOMError("expected a JSON object at the top level")
+
+    if doc.get("bomFormat") == "CycloneDX" or "specVersion" in doc:
+        return _parse_cyclonedx(doc)
+    if "spdxVersion" in doc or "SPDXID" in doc:
+        return _parse_spdx(doc)
+
+    raise SBOMError(
+        "unrecognised SBOM format -- expected CycloneDX JSON (bomFormat) "
+        "or SPDX JSON (spdxVersion). Generate one with syft or cdxgen."
+    )
+
+
+def parse_file(path: str) -> SBOMDocument:
+    with open(path, "rb") as handle:
+        return parse(handle.read())

flagrante/scan.py

@@ -0,0 +1,62 @@
+"""Orchestration: SBOM in, Assessment out.
+
+Kept separate from the CLI so the web service and the GitHub Action can share
+exactly the same path. Any divergence between what the CLI says and what the
+hosted tool says would be a correctness bug, not a cosmetic one.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from .classify import Assessment, assess
+from .sbom import SBOMDocument, parse, parse_file
+from .sources import fetch_epss, fetch_kev, query_osv
+
+Progress = Callable[[str], None]
+
+
+def _noop(_message: str) -> None:
+    pass
+
+
+def scan_document(
+    document: SBOMDocument,
+    progress: Progress = _noop,
+    refresh_feeds: bool = False,
+) -> Assessment:
+    identifiable = document.identifiable
+    progress(
+        f"{len(document.components)} components read, "
+        f"{len(identifiable)} with a package URL"
+    )
+
+    if not identifiable:
+        # Nothing queryable. We still return an assessment so the caller can
+        # report the unresolvable components, which is the whole story here.
+        return assess(document, {}, {}, {}, {})
+
+    purls = [c.purl for c in identifiable if c.purl]
+    progress("querying OSV for known vulnerabilities")
+    osv_by_purl, vulnerabilities = query_osv(purls)
+
+    cves = sorted({cve for v in vulnerabilities.values() for cve in v.cves})
+    progress(f"{len(vulnerabilities)} advisories, {len(cves)} distinct CVEs")
+
+    progress("fetching CISA KEV (confirmed exploited)")
+    kev = fetch_kev(refresh=refresh_feeds)
+
+    epss: dict[str, float] = {}
+    if cves:
+        progress("fetching EPSS exploitation probabilities")
+        epss = fetch_epss(cves)
+
+    return assess(document, osv_by_purl, vulnerabilities, kev, epss)
+
+
+def scan_file(path: str, progress: Progress = _noop, refresh_feeds: bool = False) -> Assessment:
+    return scan_document(parse_file(path), progress, refresh_feeds)
+
+
+def scan_text(raw: str | bytes, progress: Progress = _noop, refresh_feeds: bool = False) -> Assessment:
+    return scan_document(parse(raw), progress, refresh_feeds)

flagrante/sources.py

@@ -0,0 +1,273 @@
+"""Vulnerability and exploitation feeds.
+
+Three public sources, no API keys, no dependencies:
+
+  OSV (osv.dev)          component  -> known vulnerabilities
+  CISA KEV               CVE        -> confirmed exploited in the wild
+  FIRST EPSS             CVE        -> probability of exploitation in 30 days
+
+A note on failure handling, which matters more here than in most clients:
+when a feed cannot be reached we raise. We never degrade to "nothing found".
+An empty result and an unreachable exploitation feed look identical to a user
+and mean opposite things, and only one of them is safe to act on.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Sequence
+
+OSV_BATCH_URL = "https://api.osv.dev/v1/querybatch"
+OSV_QUERY_URL = "https://api.osv.dev/v1/query"
+KEV_URL = (
+    "https://www.cisa.gov/sites/default/files/feeds/"
+    "known_exploited_vulnerabilities.json"
+)
+EPSS_URL = "https://api.first.org/data/v1/epss"
+
+# Derived rather than written out, so the string the feeds see can never
+# drift from the version actually shipped.
+from . import __version__ as _version
+
+USER_AGENT = f"flagrante/{_version} (CRA Article 14 exposure checker; +https://flagrante.dev)"
+CACHE_TTL_SECONDS = 6 * 3600
+
+
+class FeedError(RuntimeError):
+    """A required feed could not be reached or returned something unusable."""
+
+
+def _cache_dir() -> Path:
+    root = os.environ.get("FLAGRANTE_CACHE") or (Path.home() / ".cache" / "flagrante")
+    path = Path(root)
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _cached(name: str, ttl: int = CACHE_TTL_SECONDS) -> Any | None:
+    path = _cache_dir() / name
+    if not path.exists():
+        return None
+    if time.time() - path.stat().st_mtime > ttl:
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def _store(name: str, payload: Any) -> None:
+    try:
+        (_cache_dir() / name).write_text(json.dumps(payload), encoding="utf-8")
+    except OSError:
+        pass  # a cache miss is never worth failing a scan over
+
+
+def _request(url: str, body: bytes | None = None, timeout: int = 45) -> Any:
+    headers = {"User-Agent": USER_AGENT, "Accept": "application/json"}
+    if body is not None:
+        headers["Content-Type"] = "application/json"
+    request = urllib.request.Request(url, data=body, headers=headers)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        raise FeedError(f"{url} returned HTTP {exc.code}") from exc
+    except urllib.error.URLError as exc:
+        raise FeedError(f"could not reach {url}: {exc.reason}") from exc
+    except json.JSONDecodeError as exc:
+        raise FeedError(f"{url} returned malformed JSON") from exc
+
+
+def _retrying(url: str, body: bytes | None = None, attempts: int = 3) -> Any:
+    delay = 1.0
+    last: FeedError | None = None
+    for _ in range(attempts):
+        try:
+            return _request(url, body)
+        except FeedError as exc:
+            last = exc
+            time.sleep(delay)
+            delay *= 2
+    raise last  # type: ignore[misc]
+
+
+# --------------------------------------------------------------------------
+# CISA KEV -- the authoritative "confirmed exploited" list
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class KevEntry:
+    cve: str
+    vendor: str
+    product: str
+    name: str
+    date_added: str
+    due_date: str
+    ransomware: bool
+
+
+def fetch_kev(refresh: bool = False) -> dict[str, KevEntry]:
+    payload = None if refresh else _cached("kev.json")
+    if payload is None:
+        payload = _retrying(KEV_URL)
+        _store("kev.json", payload)
+
+    entries: dict[str, KevEntry] = {}
+    for item in payload.get("vulnerabilities") or []:
+        cve = str(item.get("cveID", "")).upper().strip()
+        if not cve:
+            continue
+        entries[cve] = KevEntry(
+            cve=cve,
+            vendor=str(item.get("vendorProject", "")),
+            product=str(item.get("product", "")),
+            name=str(
+                item.get("shortDescription", "") or item.get("vulnerabilityName", "")
+            ),
+            date_added=str(item.get("dateAdded", "")),
+            due_date=str(item.get("dueDate", "")),
+            ransomware=str(item.get("knownRansomwareCampaignUse", "")).lower()
+            == "known",
+        )
+
+    if not entries:
+        raise FeedError("CISA KEV feed parsed but contained no entries")
+    return entries
+
+
+# --------------------------------------------------------------------------
+# EPSS -- probability that a CVE is exploited in the next 30 days
+# --------------------------------------------------------------------------
+
+
+def fetch_epss(cves: Sequence[str], batch_size: int = 100) -> dict[str, float]:
+    unique = sorted({c.upper() for c in cves if c.upper().startswith("CVE-")})
+    if not unique:
+        return {}
+
+    scores: dict[str, float] = {}
+    for start in range(0, len(unique), batch_size):
+        chunk = unique[start : start + batch_size]
+        url = f"{EPSS_URL}?cve={','.join(chunk)}"
+        payload = _retrying(url)
+        for row in payload.get("data") or []:
+            cve = str(row.get("cve", "")).upper()
+            try:
+                scores[cve] = float(row.get("epss", 0.0))
+            except (TypeError, ValueError):
+                continue
+    return scores
+
+
+# --------------------------------------------------------------------------
+# OSV -- component to vulnerability
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Vulnerability:
+    id: str
+    aliases: tuple[str, ...]
+    summary: str
+    severity: str | None
+
+    @property
+    def cves(self) -> tuple[str, ...]:
+        found = [a.upper() for a in self.aliases if a.upper().startswith("CVE-")]
+        if self.id.upper().startswith("CVE-"):
+            found.append(self.id.upper())
+        return tuple(dict.fromkeys(found))
+
+
+def _osv_batch(purls: Sequence[str]) -> list[list[str]]:
+    """Cheap first pass: which purls have anything at all against them."""
+    queries = [{"package": {"purl": purl}} for purl in purls]
+    body = json.dumps({"queries": queries}).encode("utf-8")
+    payload = _retrying(OSV_BATCH_URL, body)
+
+    results: list[list[str]] = []
+    for entry in payload.get("results") or []:
+        ids = [str(v.get("id")) for v in (entry.get("vulns") or []) if v.get("id")]
+        results.append(ids)
+
+    while len(results) < len(purls):
+        results.append([])
+    return results
+
+
+def _osv_full(purl: str) -> tuple[str, list[dict]]:
+    """Full advisory records for one package.
+
+    /v1/query returns complete records, where /v1/querybatch returns bare ids.
+    Fetching details id-by-id turns one slow package into a hundred requests --
+    a five-component SBOM measured 56 seconds that way. Querying per package
+    instead makes the cost scale with packages that have findings, which is a
+    small minority, rather than with the number of advisories.
+    """
+    body = json.dumps({"package": {"purl": purl}}).encode("utf-8")
+    try:
+        payload = _retrying(OSV_QUERY_URL, body, attempts=2)
+    except FeedError:
+        return purl, []
+    return purl, [v for v in (payload.get("vulns") or []) if isinstance(v, dict)]
+
+
+def _severity_of(record: dict) -> str | None:
+    for item in record.get("severity") or []:
+        if isinstance(item, dict) and item.get("score"):
+            return str(item["score"])
+    database = record.get("database_specific") or {}
+    if isinstance(database, dict) and database.get("severity"):
+        return str(database["severity"])
+    return None
+
+
+def _to_vulnerability(record: dict) -> Vulnerability:
+    aliases = tuple(str(a) for a in (record.get("aliases") or []))
+    return Vulnerability(
+        id=str(record.get("id", "")),
+        aliases=aliases,
+        summary=str(record.get("summary") or "").strip(),
+        severity=_severity_of(record),
+    )
+
+
+def query_osv(
+    purls: Sequence[str], batch_size: int = 200, workers: int = 16
+) -> tuple[dict[str, list[str]], dict[str, Vulnerability]]:
+    """Map each purl to its OSV advisory ids, plus a detail lookup."""
+    # Pass one: find the packages worth asking about in detail.
+    flagged: list[str] = []
+    for start in range(0, len(purls), batch_size):
+        chunk = list(purls[start : start + batch_size])
+        for purl, ids in zip(chunk, _osv_batch(chunk)):
+            if ids:
+                flagged.append(purl)
+
+    by_purl: dict[str, list[str]] = {purl: [] for purl in purls}
+    details: dict[str, Vulnerability] = {}
+    if not flagged:
+        return by_purl, details
+
+    # Pass two: full records, only for those.
+    with ThreadPoolExecutor(max_workers=workers) as pool:
+        for purl, records in pool.map(_osv_full, flagged):
+            ids = []
+            for record in records:
+                vuln = _to_vulnerability(record)
+                if not vuln.id:
+                    continue
+                details[vuln.id] = vuln
+                ids.append(vuln.id)
+            by_purl[purl] = ids
+
+    return by_purl, details

flagrante-0.0.1.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: flagrante
+Version: 0.0.1
+Summary: Which of your components carry vulnerabilities confirmed exploited in the wild -- the ones that start a CRA Article 14 24-hour reporting clock
+Author: Flagrante
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://flagrante.dev
+Project-URL: Source, https://github.com/pacordelcw/flagrante
+Project-URL: Issues, https://github.com/pacordelcw/flagrante/issues
+Project-URL: Changelog, https://github.com/pacordelcw/flagrante/commits/main
+Keywords: cra,cyber-resilience-act,article-14,sbom,cyclonedx,spdx,kev,epss,osv,vulnerability,compliance,eu
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Legal Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# flagrante
+
+**Which of your components start a CRA Article 14 24-hour clock.**
+
+Since 11 September 2026, a manufacturer placing a product with digital elements
+on the EU market must send an early warning within **24 hours** of becoming
+aware that a vulnerability in that product is **actively exploited**.
+
+Every SBOM scanner on the market tells you which components are *vulnerable*.
+That is not the question Article 14 asks. Thousands of CVEs are vulnerabilities;
+a few hundred are being exploited. Only the second group starts a clock.
+
+`flagrante` makes that distinction the whole output.
+
+```
+24-HOUR CLOCK LIKELY RUNNING  (2)
+  Confirmed exploited in the wild -- CISA KEV
+
+  CVE-2021-44228  org.apache.logging.log4j/log4j-core@2.14.1
+      listed in CISA KEV since 2021-12-10 as exploited in the wild, linked to ransomware campaigns
+
+ASSESS TODAY  (16)
+  Elevated exploitation probability, not yet confirmed
+  ...
+
+VERDICT
+  1 component carries 2 vulnerabilities confirmed exploited in the wild. If any
+  of these ship in a product you place on the EU market, assess Article 14
+  reporting now.
+
+ARTICLE 14 CASCADE
+  Early warning     2026-09-04 17:10 UTC   (24h)
+  Notification      2026-09-06 17:10 UTC   (72h)
+  Final report      2026-09-17 17:10 UTC   (14d)
+```
+
+## Use it
+
+You need an SBOM. If you do not have one, generate it free — `flagrante` does not
+duplicate that job, because [syft](https://github.com/anchore/syft) and
+[cdxgen](https://github.com/CycloneDX/cdxgen) already do it well.
+
+```bash
+pip install flagrante
+syft dir:. -o cyclonedx-json | flagrante
+```
+
+Or against a file, in CI, or as JSON:
+
+```bash
+flagrante sbom.json
+flagrante sbom.json --json > result.json
+flagrante sbom.json --all          # include findings with no exploitation signal
+flagrante sbom.json --fail-on urgent
+```
+
+Exit codes: `0` nothing at the chosen level, `1` confirmed exploited,
+`2` urgent (with `--fail-on urgent`), `3` the scan could not complete.
+
+### GitHub Action
+
+```yaml
+- uses: actions/checkout@v4
+- run: syft dir:. -o cyclonedx-json > sbom.json
+- uses: pacordelcw/flagrante@v1
+  with:
+    sbom: sbom.json
+    fail-on: exploited
+```
+
+## How it decides
+
+Three public feeds, no API keys:
+
+| Feed | Answers |
+|---|---|
+| [OSV](https://osv.dev) | which components carry known vulnerabilities |
+| [CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) | which CVEs are **confirmed exploited in the wild** |
+| [FIRST EPSS](https://www.first.org/epss/) | probability of exploitation within 30 days |
+
+| Tier | Trigger |
+|---|---|
+| **24-hour clock likely running** | CVE listed in CISA KEV |
+| **Assess today** | EPSS ≥ 10%, not in KEV |
+| **Track** | known vulnerability, no exploitation signal |
+| **Cannot be checked** | no package URL in the SBOM |
+
+## What this is not
+
+`flagrante` is an **exposure indicator**. It is not a conformity assessment, not
+legal advice, and not a determination that no reporting obligation exists.
+
+Three limits worth stating plainly, because a tool in this space that hides
+them is not worth trusting:
+
+1. **It cannot tell whether vulnerable code is reachable in your product.**
+   A KEV match means the CVE is exploited somewhere in the world, not that
+   *your* product is being attacked. Article 14 turns on the vulnerability
+   being in the product and actively exploited. That judgement is yours.
+
+2. **"Actively exploited" is not perfectly determinable from public data.**
+   KEV lags real-world exploitation, and EPSS is a model, not an observation.
+   Absence of a signal here is not evidence of absence in the world.
+
+3. **There is deliberately no "you are compliant" outcome.** Over-flagging
+   costs you an afternoon; under-flagging costs up to €15 million or 2.5% of
+   global turnover. Every threshold in this tool is set by that asymmetry, and
+   there is a test suite that fails the build if a future change ever softens
+   the wording into reassurance.
+
+If a feed is unreachable, `flagrante` refuses to print a result rather than
+printing an empty one — an unreachable exploitation feed and a clean scan look
+identical and mean opposite things.
+
+## Development
+
+No dependencies, no network in the test suite:
+
+```bash
+python -m unittest discover -s tests
+```
+
+Apache-2.0.