opencra-shared 0.1.0__tar.gz

opencra_shared-0.1.0/.gitignore

@@ -0,0 +1,249 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Environment variables & secrets (CRITICAL)
+.env
+.env.*
+!.env.example
+
+# IDEs & Editor settings
+.vscode/
+.idea/
+
+# Local OS metadata
+.DS_Store
+Thumbs.db
+
+# SQLite / Local Databases
+*.db
+*.sqlite3
+crashield.db
+
+# OpenCRA CLI output test files
+*.cyclonedx.json
+*.spdx.json
+cra-report.pdf
+*.pdf-fallback.txt
+
+# Node / frontend
+node_modules/
+apps/web/dist/
+
+# uv
+.python-version

opencra_shared-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.5
+Name: opencra-shared
+Version: 0.1.0
+Summary: Shared Pydantic models, CycloneDX subset, and CRA clock calculators.
+License: Apache-2.0
+Requires-Python: >=3.12
+Requires-Dist: packageurl-python>=0.16
+Requires-Dist: pydantic>=2.9

opencra_shared-0.1.0/opencra_shared/__init__.py

@@ -0,0 +1,59 @@
+"""Shared OpenCRA models, SBOM helpers, and CRA Article 14 clock calculators."""
+
+from opencra_shared.clocks import (
+    CaseStatus,
+    CaseType,
+    ClockSet,
+    add_one_calendar_month,
+    compute_clocks,
+    early_warning_due_at,
+    final_report_due_at,
+    notification_due_at,
+)
+from opencra_shared.kev import KevEntry, index_kev_by_cve, parse_kev_catalog
+from opencra_shared.models import (
+    Component,
+    FailOn,
+    OutputFormat,
+    SbomDocument,
+    SbomMetadata,
+    SbomTool,
+    ScanResult,
+    VulnMatch,
+)
+from opencra_shared.sbom import (
+    cyclonedx_to_spdx,
+    normalize_component,
+    normalize_purl,
+    parse_cyclonedx,
+    serialize_cyclonedx,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CaseStatus",
+    "CaseType",
+    "ClockSet",
+    "Component",
+    "FailOn",
+    "KevEntry",
+    "OutputFormat",
+    "ScanResult",
+    "SbomDocument",
+    "SbomMetadata",
+    "SbomTool",
+    "VulnMatch",
+    "add_one_calendar_month",
+    "compute_clocks",
+    "cyclonedx_to_spdx",
+    "early_warning_due_at",
+    "final_report_due_at",
+    "index_kev_by_cve",
+    "normalize_component",
+    "normalize_purl",
+    "notification_due_at",
+    "parse_cyclonedx",
+    "parse_kev_catalog",
+    "serialize_cyclonedx",
+]

opencra_shared-0.1.0/opencra_shared/clocks.py

@@ -0,0 +1,128 @@
+"""Pure CRA Article 14 clock calculators.
+
+A scanner hit is a candidate. Clocks start only when a human sets awareness_at.
+The 14-day final report is measured from fix_available_at for vulnerabilities,
+not from awareness. Severe incidents use one calendar month after notification.
+"""
+
+from __future__ import annotations
+
+import calendar
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class CaseType(str, Enum):
+    ACTIVELY_EXPLOITED_VULN = "actively_exploited_vuln"
+    SEVERE_INCIDENT = "severe_incident"
+
+
+class CaseStatus(str, Enum):
+    CANDIDATE = "candidate"
+    ACKNOWLEDGED = "acknowledged"
+    EARLY_WARNING_SUBMITTED = "early_warning_submitted"
+    NOTIFICATION_SUBMITTED = "notification_submitted"
+    AWAITING_FIX = "awaiting_fix"
+    FINAL_SUBMITTED = "final_submitted"
+    CLOSED = "closed"
+    DISMISSED = "dismissed"
+    OVERDUE_EARLY_WARNING = "overdue_early_warning"
+    OVERDUE_NOTIFICATION = "overdue_notification"
+    OVERDUE_FINAL = "overdue_final"
+
+
+class ClockSet(BaseModel):
+    awareness_at: datetime | None = None
+    early_warning_due_at: datetime | None = None
+    notification_due_at: datetime | None = None
+    fix_available_at: datetime | None = None
+    notification_submitted_at: datetime | None = None
+    final_report_due_at: datetime | None = None
+    overdue: list[str] = Field(default_factory=list)
+
+
+def _ensure_aware(dt: datetime) -> datetime:
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+def add_one_calendar_month(dt: datetime) -> datetime:
+    """Add one calendar month, clamping the day to the last valid day."""
+    dt = _ensure_aware(dt)
+    month = dt.month + 1
+    year = dt.year
+    if month > 12:
+        month = 1
+        year += 1
+    last_day = calendar.monthrange(year, month)[1]
+    return dt.replace(year=year, month=month, day=min(dt.day, last_day))
+
+
+def early_warning_due_at(awareness_at: datetime) -> datetime:
+    return _ensure_aware(awareness_at) + timedelta(hours=24)
+
+
+def notification_due_at(awareness_at: datetime) -> datetime:
+    return _ensure_aware(awareness_at) + timedelta(hours=72)
+
+
+def final_report_due_at(
+    case_type: CaseType,
+    *,
+    fix_available_at: datetime | None = None,
+    notification_submitted_at: datetime | None = None,
+) -> datetime | None:
+    if case_type is CaseType.ACTIVELY_EXPLOITED_VULN:
+        if fix_available_at is None:
+            return None
+        return _ensure_aware(fix_available_at) + timedelta(days=14)
+    if notification_submitted_at is None:
+        return None
+    return add_one_calendar_month(_ensure_aware(notification_submitted_at))
+
+
+def compute_clocks(
+    case_type: CaseType,
+    *,
+    awareness_at: datetime | None = None,
+    fix_available_at: datetime | None = None,
+    notification_submitted_at: datetime | None = None,
+    now: datetime | None = None,
+    early_warning_submitted: bool = False,
+    notification_submitted: bool = False,
+    final_submitted: bool = False,
+) -> ClockSet:
+    """Compute due dates. Does nothing if awareness_at is unset (candidate)."""
+    now = _ensure_aware(now or datetime.now(timezone.utc))
+    clocks = ClockSet(
+        awareness_at=_ensure_aware(awareness_at) if awareness_at else None,
+        fix_available_at=_ensure_aware(fix_available_at) if fix_available_at else None,
+        notification_submitted_at=(
+            _ensure_aware(notification_submitted_at) if notification_submitted_at else None
+        ),
+    )
+    if awareness_at is None:
+        return clocks
+
+    clocks.early_warning_due_at = early_warning_due_at(awareness_at)
+    clocks.notification_due_at = notification_due_at(awareness_at)
+    clocks.final_report_due_at = final_report_due_at(
+        case_type,
+        fix_available_at=fix_available_at,
+        notification_submitted_at=notification_submitted_at,
+    )
+
+    if not early_warning_submitted and now > clocks.early_warning_due_at:
+        clocks.overdue.append("early_warning")
+    if not notification_submitted and now > clocks.notification_due_at:
+        clocks.overdue.append("notification")
+    if (
+        clocks.final_report_due_at is not None
+        and not final_submitted
+        and now > clocks.final_report_due_at
+    ):
+        clocks.overdue.append("final_report")
+    return clocks

opencra_shared-0.1.0/opencra_shared/kev.py

@@ -0,0 +1,74 @@
+"""CISA Known Exploited Vulnerabilities catalog helpers."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class KevEntry(BaseModel):
+    cve_id: str
+    vendor: str | None = None
+    product: str | None = None
+    vulnerability_name: str | None = None
+    date_added: datetime | None = None
+    short_description: str | None = None
+    required_action: str | None = None
+    due_date: datetime | None = None
+    known_ransomware: str | None = None
+    notes: str | None = None
+
+
+def _parse_date(value: Any) -> datetime | None:
+    if not value or not isinstance(value, str):
+        return None
+    for fmt in ("%Y-%m-%d", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%dT%H:%M:%SZ"):
+        try:
+            return datetime.strptime(value[:19] if "T" in value else value, fmt.replace("Z", ""))
+        except ValueError:
+            continue
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def parse_kev_catalog(payload: dict[str, Any]) -> list[KevEntry]:
+    entries: list[KevEntry] = []
+    for raw in payload.get("vulnerabilities") or []:
+        if not isinstance(raw, dict):
+            continue
+        cve = raw.get("cveID") or raw.get("cve_id")
+        if not cve:
+            continue
+        entries.append(
+            KevEntry(
+                cve_id=str(cve).upper(),
+                vendor=raw.get("vendorProject"),
+                product=raw.get("product"),
+                vulnerability_name=raw.get("vulnerabilityName"),
+                date_added=_parse_date(raw.get("dateAdded")),
+                short_description=raw.get("shortDescription"),
+                required_action=raw.get("requiredAction"),
+                due_date=_parse_date(raw.get("dueDate")),
+                known_ransomware=raw.get("knownRansomwareCampaignUse"),
+                notes=raw.get("notes"),
+            )
+        )
+    return entries
+
+
+def index_kev_by_cve(entries: list[KevEntry]) -> dict[str, KevEntry]:
+    return {entry.cve_id.upper(): entry for entry in entries}
+
+
+def extract_cves(aliases: list[str], osv_id: str | None = None) -> list[str]:
+    """Collect CVE-IDs from OSV aliases and the primary id."""
+    found: list[str] = []
+    for value in [*aliases, osv_id or ""]:
+        upper = value.upper()
+        if upper.startswith("CVE-") and upper not in found:
+            found.append(upper)
+    return found

opencra_shared-0.1.0/opencra_shared/models.py

@@ -0,0 +1,102 @@
+"""Canonical OpenCRA scan and SBOM models shared by CLI and SaaS."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+class OutputFormat(str, Enum):
+    TABLE = "table"
+    JSON = "json"
+    CYCLONEDX = "cyclonedx"
+    SPDX = "spdx"
+
+
+class FailOn(str, Enum):
+    NONE = "none"
+    KEV = "kev"
+    CRITICAL = "critical"
+    HIGH = "high"
+
+
+class SbomTool(BaseModel):
+    name: str
+    version: str | None = None
+
+
+class SbomMetadata(BaseModel):
+    timestamp: datetime | None = None
+    name: str | None = None
+    version: str | None = None
+    component_type: str = "application"
+    tools: list[SbomTool] = Field(default_factory=list)
+
+
+class Component(BaseModel):
+    type: str = "library"
+    name: str
+    version: str | None = None
+    purl: str | None = None
+    licenses: list[str] = Field(default_factory=list)
+    hashes: dict[str, str] = Field(default_factory=dict)
+    skipped_reason: str | None = None
+
+
+class VulnMatch(BaseModel):
+    purl: str
+    component_name: str | None = None
+    component_version: str | None = None
+    osv_id: str | None = None
+    cve_id: str | None = None
+    severity: str | None = None
+    cvss_v3: float | None = None
+    epss: float | None = None
+    in_kev: bool = False
+    kev_added_at: datetime | None = None
+    kev_ransomware: str | None = None
+    aliases: list[str] = Field(default_factory=list)
+    status: str = "open"
+    vex_status: str | None = None
+    summary: str | None = None
+
+
+class SbomDocument(BaseModel):
+    bom_format: str = "CycloneDX"
+    spec_version: str = "1.6"
+    serial_number: str = Field(default_factory=lambda: f"urn:uuid:{uuid4()}")
+    version: int = 1
+    metadata: SbomMetadata = Field(default_factory=SbomMetadata)
+    components: list[Component] = Field(default_factory=list)
+    raw: dict[str, Any] = Field(default_factory=dict)
+
+
+class ScanResult(BaseModel):
+    target: str
+    scanned_at: datetime
+    sbom: SbomDocument
+    matches: list[VulnMatch] = Field(default_factory=list)
+    skipped_components: list[Component] = Field(default_factory=list)
+    offline: bool = False
+    warnings: list[str] = Field(default_factory=list)
+
+    @property
+    def kev_hits(self) -> list[VulnMatch]:
+        return [m for m in self.matches if m.in_kev]
+
+    def fails(self, threshold: FailOn) -> bool:
+        if threshold is FailOn.NONE:
+            return False
+        if threshold is FailOn.KEV:
+            return any(m.in_kev for m in self.matches)
+        ranks = {"NONE": 0, "LOW": 1, "MEDIUM": 2, "HIGH": 3, "CRITICAL": 4}
+        cutoff = 4 if threshold is FailOn.CRITICAL else 3
+        for match in self.matches:
+            rank = ranks.get((match.severity or "NONE").upper(), 0)
+            if rank >= cutoff:
+                return True
+        return False

opencra_shared-0.1.0/opencra_shared/py.typed

@@ -0,0 +1 @@
+

opencra_shared-0.1.0/opencra_shared/sbom.py

@@ -0,0 +1,291 @@
+"""CycloneDX 1.6 subset parser and PURL normalization."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+from packageurl import PackageURL
+from pydantic import ValidationError
+
+from opencra_shared.models import Component, SbomDocument, SbomMetadata, SbomTool
+
+logger = logging.getLogger("opencra.sbom")
+
+# Map common Syft/CycloneDX purl types we synthesize when purl is missing.
+_TYPE_TO_ECOSYSTEM = {
+    "pypi": "pypi",
+    "npm": "npm",
+    "golang": "golang",
+    "go": "golang",
+    "maven": "maven",
+    "cargo": "cargo",
+    "nuget": "nuget",
+    "gem": "gem",
+    "composer": "composer",
+    "hex": "hex",
+    "pub": "pub",
+    "swift": "swift",
+    "apk": "apk",
+    "deb": "deb",
+    "rpm": "rpm",
+}
+
+
+def _has_broken_percent_encoding(text: str) -> bool:
+    i = 0
+    while i < len(text):
+        if text[i] == "%":
+            hexpart = text[i + 1 : i + 3]
+            if len(hexpart) < 2 or any(c not in "0123456789abcdefABCDEF" for c in hexpart):
+                return True
+            i += 3
+        else:
+            i += 1
+    return False
+
+
+def normalize_purl(value: str | None) -> str | None:
+    """Parse and re-serialize a PURL, dropping invalid/unencodable qualifiers.
+
+    Returns None if the value cannot be made into a valid Package URL.
+    """
+    if not value or not value.strip():
+        return None
+    raw = value.strip()
+    if "?" in raw and _has_broken_percent_encoding(raw.split("?", 1)[1]):
+        raw = raw.split("?", 1)[0].split("#", 1)[0]
+    try:
+        parsed = PackageURL.from_string(raw)
+        return str(parsed)
+    except (ValueError, TypeError):
+        pass
+
+    base = raw.split("?", 1)[0].split("#", 1)[0]
+    try:
+        parsed = PackageURL.from_string(base)
+        return str(parsed)
+    except (ValueError, TypeError):
+        logger.warning("Dropping invalid PURL: %s", value)
+        return None
+
+
+def _licenses_from_cdx(raw: Any) -> list[str]:
+    if not raw:
+        return []
+    out: list[str] = []
+    if not isinstance(raw, list):
+        return out
+    for item in raw:
+        if isinstance(item, str):
+            out.append(item)
+            continue
+        if not isinstance(item, dict):
+            continue
+        license_obj = item.get("license") or item
+        if isinstance(license_obj, dict):
+            ident = license_obj.get("id") or license_obj.get("name")
+            if ident:
+                out.append(str(ident))
+        expression = item.get("expression")
+        if expression:
+            out.append(str(expression))
+    return out
+
+
+def _hashes_from_cdx(raw: Any) -> dict[str, str]:
+    hashes: dict[str, str] = {}
+    if not isinstance(raw, list):
+        return hashes
+    for item in raw:
+        if isinstance(item, dict) and item.get("alg") and item.get("content"):
+            hashes[str(item["alg"])] = str(item["content"])
+    return hashes
+
+
+def _synthesize_purl(component: dict[str, Any]) -> str | None:
+    name = component.get("name")
+    version = component.get("version")
+    if not name or not version:
+        return None
+    cdx_type = str(component.get("type") or "library").lower()
+    purl_type = component.get("purl-type") or _TYPE_TO_ECOSYSTEM.get(cdx_type)
+    # Prefer bom-ref hints like pkg:pypi/...
+    bom_ref = str(component.get("bom-ref") or "")
+    if bom_ref.startswith("pkg:"):
+        return normalize_purl(bom_ref)
+    if not purl_type:
+        # Last resort: generic generic type is invalid; skip synthesis.
+        return None
+    try:
+        return str(PackageURL(type=purl_type, name=str(name), version=str(version)))
+    except (ValueError, TypeError):
+        return None
+
+
+def normalize_component(raw: dict[str, Any]) -> Component | None:
+    name = raw.get("name")
+    if not name:
+        return None
+    purl = normalize_purl(raw.get("purl")) or _synthesize_purl(raw)
+    skipped = None if purl else "invalid or missing PURL"
+    try:
+        return Component(
+            type=str(raw.get("type") or "library"),
+            name=str(name),
+            version=str(raw["version"]) if raw.get("version") is not None else None,
+            purl=purl,
+            licenses=_licenses_from_cdx(raw.get("licenses")),
+            hashes=_hashes_from_cdx(raw.get("hashes")),
+            skipped_reason=skipped,
+        )
+    except ValidationError:
+        return None
+
+
+def parse_cyclonedx(payload: dict[str, Any]) -> SbomDocument:
+    """Parse a CycloneDX JSON document, dropping unknown fields and bad components."""
+    metadata_raw = payload.get("metadata") or {}
+    component_raw = metadata_raw.get("component") or {}
+    tools: list[SbomTool] = []
+    tools_raw = metadata_raw.get("tools")
+    # CycloneDX 1.5+ uses tools.components; 1.4 uses a list.
+    if isinstance(tools_raw, dict):
+        for item in tools_raw.get("components") or tools_raw.get("services") or []:
+            if isinstance(item, dict) and item.get("name"):
+                tools.append(SbomTool(name=str(item["name"]), version=item.get("version")))
+    elif isinstance(tools_raw, list):
+        for item in tools_raw:
+            if isinstance(item, dict) and item.get("name"):
+                tools.append(SbomTool(name=str(item["name"]), version=item.get("version")))
+
+    timestamp = metadata_raw.get("timestamp")
+    parsed_ts: datetime | None = None
+    if isinstance(timestamp, str):
+        try:
+            parsed_ts = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+        except ValueError:
+            parsed_ts = None
+
+    components: list[Component] = []
+    for raw in payload.get("components") or []:
+        if not isinstance(raw, dict):
+            continue
+        component = normalize_component(raw)
+        if component is not None:
+            components.append(component)
+
+    serial = payload.get("serialNumber") or f"urn:uuid:{uuid4()}"
+    return SbomDocument(
+        bom_format=str(payload.get("bomFormat") or "CycloneDX"),
+        spec_version=str(payload.get("specVersion") or "1.6"),
+        serial_number=str(serial),
+        version=int(payload.get("version") or 1),
+        metadata=SbomMetadata(
+            timestamp=parsed_ts or datetime.now(timezone.utc),
+            name=component_raw.get("name"),
+            version=component_raw.get("version"),
+            component_type=str(component_raw.get("type") or "application"),
+            tools=tools,
+        ),
+        components=components,
+        raw=payload,
+    )
+
+
+def serialize_cyclonedx(document: SbomDocument) -> dict[str, Any]:
+    """Rebuild a CycloneDX-shaped dict from the normalized document."""
+    if document.raw:
+        # Preserve original Syft document when present; overlay serial if missing.
+        out = dict(document.raw)
+        out.setdefault("bomFormat", "CycloneDX")
+        out.setdefault("specVersion", document.spec_version)
+        out.setdefault("serialNumber", document.serial_number)
+        return out
+
+    components = []
+    for component in document.components:
+        item: dict[str, Any] = {
+            "type": component.type,
+            "name": component.name,
+        }
+        if component.version:
+            item["version"] = component.version
+        if component.purl:
+            item["purl"] = component.purl
+        if component.licenses:
+            item["licenses"] = [{"license": {"id": lic}} for lic in component.licenses]
+        if component.hashes:
+            item["hashes"] = [{"alg": k, "content": v} for k, v in component.hashes.items()]
+        components.append(item)
+
+    ts = document.metadata.timestamp or datetime.now(timezone.utc)
+    return {
+        "bomFormat": "CycloneDX",
+        "specVersion": document.spec_version,
+        "serialNumber": document.serial_number,
+        "version": document.version,
+        "metadata": {
+            "timestamp": ts.isoformat(),
+            "component": {
+                "type": document.metadata.component_type,
+                "name": document.metadata.name or "unknown",
+                "version": document.metadata.version or "0.0.0",
+            },
+            "tools": {
+                "components": [
+                    {"name": t.name, **({"version": t.version} if t.version else {})}
+                    for t in document.metadata.tools
+                ]
+            },
+        },
+        "components": components,
+    }
+
+
+def cyclonedx_to_spdx(document: SbomDocument) -> dict[str, Any]:
+    """Minimal SPDX 2.3 JSON adapter. Not a full SPDX implementation."""
+    packages = []
+    for component in document.components:
+        pkg: dict[str, Any] = {
+            "name": component.name,
+            "SPDXID": f"SPDXRef-{_spdx_id(component.name, component.version)}",
+            "downloadLocation": "NOASSERTION",
+            "filesAnalyzed": False,
+        }
+        if component.version:
+            pkg["versionInfo"] = component.version
+        if component.purl:
+            pkg["externalRefs"] = [
+                {
+                    "referenceCategory": "PACKAGE-MANAGER",
+                    "referenceType": "purl",
+                    "referenceLocator": component.purl,
+                }
+            ]
+        if component.licenses:
+            pkg["licenseConcluded"] = component.licenses[0]
+        packages.append(pkg)
+
+    created = (document.metadata.timestamp or datetime.now(timezone.utc)).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    )
+    return {
+        "spdxVersion": "SPDX-2.3",
+        "dataLicense": "CC0-1.0",
+        "SPDXID": "SPDXRef-DOCUMENT",
+        "name": document.metadata.name or document.serial_number,
+        "documentNamespace": document.serial_number,
+        "creationInfo": {
+            "created": created,
+            "creators": ["Tool: opencra-0.1.0"],
+        },
+        "packages": packages,
+    }
+
+
+def _spdx_id(name: str, version: str | None) -> str:
+    base = f"{name}-{version or 'unknown'}"
+    return "".join(ch if ch.isalnum() else "-" for ch in base)

opencra_shared-0.1.0/opencra_shared/vex.py

@@ -0,0 +1,112 @@
+"""OpenVEX document models and candidate-dismissal policy."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, Field, model_validator
+
+from opencra_shared.clocks import CaseStatus
+
+
+class VexStatus(str, Enum):
+    NOT_AFFECTED = "not_affected"
+    AFFECTED = "affected"
+    FIXED = "fixed"
+    UNDER_INVESTIGATION = "under_investigation"
+
+
+class VexJustification(str, Enum):
+    COMPONENT_NOT_PRESENT = "component_not_present"
+    VULNERABLE_CODE_NOT_PRESENT = "vulnerable_code_not_present"
+    VULNERABLE_CODE_NOT_IN_EXECUTE_PATH = "vulnerable_code_not_in_execute_path"
+    VULNERABLE_CODE_CANNOT_BE_CONTROLLED_BY_ADVERSARY = (
+        "vulnerable_code_cannot_be_controlled_by_adversary"
+    )
+    INLINE_MITIGATIONS_ALREADY_EXIST = "inline_mitigations_already_exist"
+
+
+ACKNOWLEDGED_STATUSES = {
+    CaseStatus.ACKNOWLEDGED,
+    CaseStatus.EARLY_WARNING_SUBMITTED,
+    CaseStatus.NOTIFICATION_SUBMITTED,
+    CaseStatus.AWAITING_FIX,
+    CaseStatus.OVERDUE_EARLY_WARNING,
+    CaseStatus.OVERDUE_NOTIFICATION,
+    CaseStatus.OVERDUE_FINAL,
+}
+
+
+class VexProduct(BaseModel):
+    id: str = Field(alias="@id")
+
+    model_config = {"populate_by_name": True}
+
+
+class VexVulnerability(BaseModel):
+    name: str
+
+
+class VexStatement(BaseModel):
+    vulnerability: VexVulnerability
+    products: list[VexProduct] = Field(default_factory=list)
+    status: VexStatus
+    justification: VexJustification | None = None
+    impact_statement: str | None = None
+    action_statement: str | None = None
+    status_notes: str | None = None
+
+    @model_validator(mode="after")
+    def require_not_affected_evidence(self) -> VexStatement:
+        if self.status is VexStatus.NOT_AFFECTED:
+            if self.justification is None and not self.impact_statement:
+                raise ValueError(
+                    "not_affected requires a justification label or an impact_statement"
+                )
+        return self
+
+
+class OpenVexDocument(BaseModel):
+    context: str = Field(
+        default="https://openvex.dev/ns/v0.2.0",
+        alias="@context",
+    )
+    id: str = Field(default_factory=lambda: f"https://open.cra/vex/{uuid4()}", alias="@id")
+    author: str = "OpenCRA"
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    version: int = 1
+    statements: list[VexStatement] = Field(default_factory=list)
+
+    model_config = {"populate_by_name": True}
+
+
+class VexApplyResult(BaseModel):
+    applied: bool
+    requires_override: bool = False
+    reason: str
+
+
+def can_dismiss_case(case_status: CaseStatus) -> VexApplyResult:
+    """VEX may dismiss candidates. Acknowledged Art. 14 cases need an override."""
+    if case_status is CaseStatus.CANDIDATE:
+        return VexApplyResult(applied=True, reason="candidate_dismissed")
+    if case_status is CaseStatus.DISMISSED:
+        return VexApplyResult(applied=False, reason="already_dismissed")
+    if case_status in ACKNOWLEDGED_STATUSES:
+        return VexApplyResult(
+            applied=False,
+            requires_override=True,
+            reason="acknowledged_case_requires_compliance_officer_override",
+        )
+    return VexApplyResult(applied=False, reason=f"status_{case_status.value}_not_dismissable")
+
+
+def parse_openvex(payload: dict[str, Any]) -> OpenVexDocument:
+    return OpenVexDocument.model_validate(payload)
+
+
+def serialize_openvex(document: OpenVexDocument) -> dict[str, Any]:
+    return document.model_dump(by_alias=True, mode="json")

opencra_shared-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "opencra-shared"
+version = "0.1.0"
+description = "Shared Pydantic models, CycloneDX subset, and CRA clock calculators."
+requires-python = ">=3.12"
+license = { text = "Apache-2.0" }
+dependencies = [
+  "pydantic>=2.9",
+  "packageurl-python>=0.16",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["opencra_shared"]