ecdat 0.2.0__py3-none-any.whl

ecdat_core/models.py

@@ -0,0 +1,145 @@
+"""Pydantic v2 data models for ECDAT CBOM scanner.
+
+Defines the core domain models: Detection, RiskAssessment, Recommendation,
+and ScanResult. These models form the contract for the rest of the system.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, field_validator
+
+
+class Detection(BaseModel):
+    """A single cryptographic artefact discovered during scanning.
+
+    Attributes:
+        id: Unique identifier, auto-generated via uuid4 if not provided.
+        file_path: Path to the file where the artefact was found.
+        line_number: 1-based line number of the match.
+        matched_text: The exact text that triggered detection.
+        asset_type: CycloneDX-aligned asset classification.
+        algorithm_family: Broad algorithm family (e.g. RSA, AES, SHA).
+        key_size_bits: Key size in bits, if determinable.
+        quantum_vulnerable: Whether the artefact is vulnerable to quantum attacks.
+        classically_broken: Whether the artefact is already broken or deprecated
+            today, independent of quantum computing entirely (e.g. MD5, SHA-1,
+            DES, 3DES, RC4).
+        confidence: Detection confidence score in [0.0, 1.0].
+        language: Programming language of the source file.
+        detection_method: How the artefact was detected.
+    """
+
+    id: str = ""
+    file_path: str
+    line_number: int
+    matched_text: str
+    asset_type: Literal["algorithm", "certificate", "protocol", "related-crypto-material"]
+    algorithm_family: str
+    key_size_bits: int | None = None
+    quantum_vulnerable: bool
+    classically_broken: bool = False
+    confidence: float
+    language: str
+    detection_method: Literal["regex", "manifest", "certificate-parse"]
+
+    def model_post_init(self, __context: object) -> None:
+        """Generate a UUID4 id if one was not provided."""
+        if not self.id:
+            object.__setattr__(self, "id", str(uuid4()))
+
+    @field_validator("confidence")
+    @classmethod
+    def validate_confidence(cls, v: float) -> float:
+        """Ensure confidence is in the range [0.0, 1.0]."""
+        if not 0.0 <= v <= 1.0:
+            raise ValueError(f"confidence must be between 0.0 and 1.0, got {v}")
+        return v
+
+
+class RiskAssessment(BaseModel):
+    """Risk assessment derived from Mosca's inequality.
+
+    Attributes:
+        detection_id: Reference to the Detection being assessed.
+        migration_time_years: Estimated migration time in years (X).
+        shelf_life_years: How long the data must remain secret (Y).
+        threat_horizon_years: Quantum threat horizon in years (Z).
+        urgency_ratio: (X + Y) / Z — values >= 1.0 indicate immediate risk.
+        risk_level: Classified risk severity.
+        mosca_violation: Whether Mosca's inequality is violated (X+Y > Z).
+    """
+
+    detection_id: str
+    migration_time_years: float
+    shelf_life_years: float
+    threat_horizon_years: float
+    urgency_ratio: float
+    risk_level: Literal["critical", "high", "medium", "low", "quantum-safe"]
+    mosca_violation: bool
+
+    @field_validator("urgency_ratio", mode="after")
+    def validate_urgency_ratio(cls, v: float) -> float:
+        """Ensure urgency_ratio is non-negative."""
+        if v < 0:
+            raise ValueError(f"urgency_ratio must be non-negative, got {v}")
+        return v
+
+    def model_post_init(self, __context: object) -> None:
+        """Check consistency between urgency_ratio and mosca_violation.
+
+        Mosca's inequality states that if X + Y > Z (i.e. urgency_ratio >= 1.0),
+        then the artefact is at risk. The mosca_violation flag must be consistent
+        with the urgency_ratio.
+        """
+        expected_violation = self.urgency_ratio >= 1.0
+        if self.mosca_violation != expected_violation:
+            raise ValueError(
+                f"mosca_violation ({self.mosca_violation}) contradicts "
+                f"urgency_ratio ({self.urgency_ratio}). "
+                f"Expected mosca_violation={expected_violation} "
+                f"(urgency_ratio {'>=' if expected_violation else '<'} 1.0)"
+            )
+
+
+class Recommendation(BaseModel):
+    """Post-quantum migration recommendation for a detected artefact.
+
+    Attributes:
+        detection_id: Reference to the Detection being recommended for.
+        recommended_algorithm: NIST-approved post-quantum algorithm.
+        fips_reference: FIPS standard reference for the algorithm.
+        rationale: Why this algorithm is recommended.
+        latency_note: Performance impact advisory.
+        migration_note: Migration complexity advisory.
+    """
+
+    detection_id: str
+    recommended_algorithm: str
+    fips_reference: str
+    rationale: str
+    latency_note: str
+    migration_note: str
+
+
+class ScanResult(BaseModel):
+    """Complete result of a CBOM scan operation.
+
+    Attributes:
+        scan_id: Unique identifier for this scan.
+        target: Path or URL that was scanned.
+        detections: All cryptographic artefacts discovered.
+        risk_assessments: Risk assessments for each detection.
+        recommendations: Migration recommendations for each detection.
+        scanned_at: ISO 8601 timestamp of when the scan was performed.
+    """
+
+    scan_id: str
+    target: str
+    detections: list[Detection]
+    risk_assessments: list[RiskAssessment]
+    recommendations: list[Recommendation]
+    scanned_at: str  # ISO timestamp
+    files_scanned: int = 0

ecdat_core/recommender.py

@@ -0,0 +1,74 @@
+"""Post-quantum recommendation engine for ECDAT.
+
+Produces a :class:`Recommendation` for each detected cryptographic artefact.
+For ordinary algorithms the recommendation is a direct pass-through of the
+signature's ``pqc_recommendation``. The one special case is an artefact that
+*already* uses a NIST-standardized post-quantum algorithm — those get a
+"no migration needed" recommendation instead of a migration directive.
+
+Public API:
+    - :func:`recommend` -> build a :class:`Recommendation` for a single
+      detection against a signature entry.
+"""
+
+from __future__ import annotations
+
+from ecdat_core.models import Detection, Recommendation
+from ecdat_core.signature_loader import SignatureEntry
+
+# Signature families that are *already* NIST-standardized post-quantum
+# schemes. These are quantum-safe, so instead of recommending a migration we
+# only note that no migration is required.
+_PQC_FAMILIES = frozenset({"pqc-kem", "pqc-signature"})
+
+# Fixed text for the already-quantum-safe recommendation.
+_NO_MIGRATION_RATIONALE = (
+    "Already using a NIST-standardized post-quantum algorithm; no migration needed."
+)
+_NO_MIGRATION_MIGRATION_NOTE = "Monitor for future FIPS updates."
+
+
+def recommend(
+    detection: Detection, signature_entry: SignatureEntry
+) -> Recommendation:
+    """Build a post-quantum migration recommendation for a detection.
+
+    The normal path copies the signature's ``pqc_recommendation`` verbatim
+    into a new :class:`Recommendation` keyed to ``detection.id``. The
+    exception is an artefact that already uses a NIST-standardized post-quantum
+    algorithm (a PQC KEM or signature family that is not quantum-vulnerable) —
+    for those, a lightweight "no migration needed" recommendation is returned
+    that keeps the signature's FIPS reference but replaces the migration
+    guidance with monitoring advice.
+
+    Args:
+        detection: The detected cryptographic artefact to recommend for.
+        signature_entry: The knowledge-base entry describing this artefact and
+            its post-quantum replacement.
+
+    Returns:
+        A fully populated :class:`Recommendation`.
+    """
+    already_pqc = (
+        not detection.quantum_vulnerable
+        and signature_entry.family in _PQC_FAMILIES
+    )
+    if already_pqc:
+        return Recommendation(
+            detection_id=detection.id,
+            recommended_algorithm=detection.algorithm_family,
+            fips_reference=signature_entry.pqc_recommendation.fips_reference,
+            rationale=_NO_MIGRATION_RATIONALE,
+            latency_note="",
+            migration_note=_NO_MIGRATION_MIGRATION_NOTE,
+        )
+
+    rec = signature_entry.pqc_recommendation
+    return Recommendation(
+        detection_id=detection.id,
+        recommended_algorithm=rec.algorithm,
+        fips_reference=rec.fips_reference,
+        rationale=rec.rationale,
+        latency_note=rec.latency_note,
+        migration_note=rec.migration_note,
+    )

ecdat_core/risk_engine.py

@@ -0,0 +1,264 @@
+"""Mosca's inequality risk engine for ECDAT.
+
+Evaluates post-quantum risk for detected cryptographic artefacts by computing
+Mosca's inequality: ``X + Y > Z`` where X is migration time, Y is data
+shelf life, and Z is the quantum threat horizon. When the inequality holds
+(urgency_ratio >= 1.0), the artefact is at immediate risk.
+
+Public API:
+    - :func:`assess_risk` -> compute a :class:`RiskAssessment` for a single
+      detection against a signature entry.
+"""
+
+from __future__ import annotations
+
+from ecdat_core.models import Detection, RiskAssessment
+from ecdat_core.signature_loader import SignatureEntry
+
+# ---------------------------------------------------------------------------
+# Sensitive-path keywords for shelf-life heuristic (Y).
+# If any of these appear case-insensitively in the file path, the artefact
+# is assumed to protect high-sensitivity data with a longer shelf life.
+# ---------------------------------------------------------------------------
+_SENSITIVE_PATH_KEYWORDS = ("payment", "auth", "pii", "secret", "key")
+
+# ---------------------------------------------------------------------------
+# Asset-type → default migration time (X) mapping.
+# Different asset types have very different migration complexity: swapping an
+# algorithm in a library is fast; rotating certificates or crypto material
+# across an enterprise is much slower.
+# ---------------------------------------------------------------------------
+_MIGRATION_TIME_BY_ASSET: dict[str, float] = {
+    "algorithm": 0.5,
+    "protocol": 2.0,
+    "certificate": 1.0,
+    "related-crypto-material": 5.0,
+}
+
+
+def assess_risk(
+    detection: Detection,
+    signature_entry: SignatureEntry,
+    shelf_life_override: float | None = None,
+    migration_time_override: float | None = None,
+) -> RiskAssessment:
+    """Evaluate post-quantum risk for a single detection via Mosca's inequality.
+
+    Mosca's inequality states that a cryptographic artefact is at risk when::
+
+        X + Y > Z
+
+    where:
+        - **X** (`migration_time_years`): estimated time to migrate away from
+          the artefact to a post-quantum alternative.
+        - **Y** (`shelf_life_years`): how long the data protected by the
+          artefact must remain confidential.
+        - **Z** (`threat_horizon_years`): estimated time before a cryptographically
+          relevant quantum computer exists.
+
+    The urgency ratio ``(X + Y) / Z`` quantifies the severity: values >= 1.0
+    indicate that migration must already be underway.
+
+    Classically-broken artefacts (MD5, SHA-1, DES, 3DES, RC4) are broken today
+    by classical attacks, independent of quantum computing. They always resolve
+    to ``risk_level="critical"`` with ``mosca_violation=True`` and an urgency
+    ratio floored at 1.0 — this represents a classical break, **not** a
+    quantum-specific one, and such artefacts are never reported as
+    "quantum-safe". X/Y/Z are still computed via the normal heuristics so the
+    numbers remain visible for transparency.
+
+    Args:
+        detection: The detected cryptographic artefact to assess.
+        signature_entry: The knowledge-base entry for this artefact's family,
+            providing the default threat horizon.
+        shelf_life_override: Explicit shelf life in years (Y). When ``None``,
+            a default is chosen based on file-path heuristics.
+        migration_time_override: Explicit migration time in years (X). When
+            ``None``, a default is chosen based on asset type.
+
+    Returns:
+        A fully populated :class:`RiskAssessment` with consistent risk_level,
+        urgency_ratio, and mosca_violation fields.
+
+    Raises:
+        pydantic.ValidationError: If the computed fields are internally
+            inconsistent (e.g. mosca_violation disagrees with urgency_ratio).
+    """
+    # ------------------------------------------------------------------
+    # 1. Classically-broken — critical, unconditionally.
+    #    MD5, SHA-1, DES, 3DES, RC4 are broken *today* by classical
+    #    attacks, independent of any quantum computer, so they must never
+    #    fall through to the quantum-safe short-circuit below. X/Y/Z are
+    #    still computed via the normal heuristics/overrides so the numbers
+    #    are visible for transparency, and the naive urgency ratio is
+    #    floored at 1.0 so the Pydantic consistency validator
+    #    (mosca_violation == urgency_ratio >= 1.0) holds with the forced
+    #    critical / mosca_violation=True classification.
+    # ------------------------------------------------------------------
+    if detection.classically_broken:
+        z = _adjusted_threat_horizon(detection, signature_entry)
+        if shelf_life_override is not None:
+            y = shelf_life_override
+        else:
+            y = _default_shelf_life(detection.file_path)
+        if migration_time_override is not None:
+            x = migration_time_override
+        else:
+            x = _default_migration_time(detection.asset_type)
+        naive_urgency_ratio = (x + y) / z
+        urgency_ratio = max(naive_urgency_ratio, 1.0)
+        return RiskAssessment(
+            detection_id=detection.id,
+            migration_time_years=x,
+            shelf_life_years=y,
+            threat_horizon_years=z,
+            urgency_ratio=urgency_ratio,
+            risk_level="critical",
+            mosca_violation=True,
+        )
+
+    # ------------------------------------------------------------------
+    # 2. Quantum-safe short-circuit — no formula needed. Only reachable
+    #    when classically_broken is False (branch 1 above already
+    #    returned), so a classically-broken-but-not-quantum-vulnerable
+    #    artefact can never be mislabelled "quantum-safe".
+    # ------------------------------------------------------------------
+    if not detection.quantum_vulnerable:
+        return RiskAssessment(
+            detection_id=detection.id,
+            migration_time_years=0.0,
+            shelf_life_years=0.0,
+            threat_horizon_years=0.0,
+            urgency_ratio=0.0,
+            risk_level="quantum-safe",
+            mosca_violation=False,
+        )
+
+    # ------------------------------------------------------------------
+    # Z — Threat horizon (years) with key-size adjustment.
+    # ------------------------------------------------------------------
+    z = _adjusted_threat_horizon(detection, signature_entry)
+
+    # ------------------------------------------------------------------
+    # Y — Shelf life (years).
+    # ------------------------------------------------------------------
+    if shelf_life_override is not None:
+        y = shelf_life_override
+    else:
+        y = _default_shelf_life(detection.file_path)
+
+    # ------------------------------------------------------------------
+    # X — Migration time (years).
+    # ------------------------------------------------------------------
+    if migration_time_override is not None:
+        x = migration_time_override
+    else:
+        x = _default_migration_time(detection.asset_type)
+
+    # ------------------------------------------------------------------
+    # 4. Urgency ratio, risk level, Mosca violation.
+    # ------------------------------------------------------------------
+    urgency_ratio = (x + y) / z
+    risk_level = _classify_risk(urgency_ratio)
+    mosca_violation = urgency_ratio >= 1.0
+
+    return RiskAssessment(
+        detection_id=detection.id,
+        migration_time_years=x,
+        shelf_life_years=y,
+        threat_horizon_years=z,
+        urgency_ratio=urgency_ratio,
+        risk_level=risk_level,
+        mosca_violation=mosca_violation,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+
+def _adjusted_threat_horizon(
+    detection: Detection, signature_entry: SignatureEntry
+) -> float:
+    """Compute the threat horizon (Z) with key-size-based adjustments.
+
+    Smaller keys are vulnerable to brute-force sooner, even before a full
+    cryptographically relevant quantum computer materialises — an attacker
+    with limited quantum resources could still break them.  Conversely,
+    very large classical keys buy extra time.
+
+    Adjustment thresholds (documented here and in the caller's docstring):
+
+    **RSA** (algorithm_family contains "RSA"):
+        - key_size <= 1024: scale Z by 0.3  (breakable with near-term QC)
+        - key_size < 2048:  scale Z by 0.5  (weakened but not trivially breakable)
+        - key_size >= 4096: scale Z by 1.2  (extra breathing room)
+        - otherwise:        use default unchanged
+
+    **EC / ECC** (algorithm_family contains "EC"):
+        - key_size < 256:   scale Z by 0.5  (below NIST P-256 minimum)
+
+    **DSA** (algorithm_family contains "DSA"):
+        - key_size < 2048:  scale Z by 0.5  (below NIST minimum)
+
+    All other families or missing key sizes use the default unchanged.
+    """
+    z = signature_entry.threat_horizon_years_default
+    key_size = detection.key_size_bits
+    family_upper = detection.algorithm_family.upper()
+
+    if key_size is not None:
+        if "RSA" in family_upper:
+            if key_size <= 1024:
+                z *= 0.3
+            elif key_size < 2048:
+                z *= 0.5
+            elif key_size >= 4096:
+                z *= 1.2
+            # 2048 <= key < 4096: no adjustment — use default
+
+        elif "EC" in family_upper:
+            if key_size < 256:
+                z *= 0.5
+
+        elif "DSA" in family_upper:
+            if key_size < 2048:
+                z *= 0.5
+
+    return z
+
+
+def _default_shelf_life(file_path: str) -> float:
+    """Choose a default shelf life (Y) based on file-path heuristics.
+
+    Paths containing sensitive keywords (payment, auth, pii, secret, key)
+    are assumed to handle data that must remain secret longer.
+    """
+    path_lower = file_path.lower()
+    if any(kw in path_lower for kw in _SENSITIVE_PATH_KEYWORDS):
+        return 10.0
+    return 5.0
+
+
+def _default_migration_time(asset_type: str) -> float:
+    """Choose a default migration time (X) based on the CycloneDX asset type."""
+    return _MIGRATION_TIME_BY_ASSET.get(asset_type, 0.5)
+
+
+def _classify_risk(urgency_ratio: float) -> str:
+    """Classify risk level from the urgency ratio.
+
+    Thresholds:
+        - >= 1.0  → critical  (Mosca violated — migration needed now)
+        - >= 0.8  → high
+        - >= 0.5  → medium
+        - <  0.5  → low
+    """
+    if urgency_ratio >= 1.0:
+        return "critical"
+    if urgency_ratio >= 0.8:
+        return "high"
+    if urgency_ratio >= 0.5:
+        return "medium"
+    return "low"

ecdat_core/signature_loader.py

@@ -0,0 +1,204 @@
+"""Loader and validation for the ECDAT cryptographic signature knowledge base.
+
+Loads ``signatures.json`` and validates it against the :class:`SignatureEntry`
+Pydantic model at import time. A malformed JSON document raises a clear error
+immediately, so downstream code can rely on the in-memory signature list being
+valid.
+
+Public API:
+    - :func:`get_all_signatures` -> list of all signature entries.
+    - :func:`get_signatures_for_language` -> entries that define patterns for a
+      given language.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+# Languages supported by the signature knowledge base. The JSON payload uses
+# these exact keys for each entry's ``patterns`` mapping.
+SUPPORTED_LANGUAGES = frozenset({"python", "javascript", "java", "go", "c_cpp"})
+
+_SIGNATURES_PATH = Path(__file__).with_name("signatures.json")
+
+
+class PqcRecommendation(BaseModel):
+    """Post-quantum migration recommendation attached to a signature entry.
+
+    Attributes:
+        algorithm: Recommended NIST post-quantum algorithm name.
+        fips_reference: FIPS standard reference (e.g. "FIPS 203"), or "N/A" for
+            non-quantum-specific fixes (e.g. classical hash weaknesses).
+        rationale: Why this algorithm is the recommended replacement.
+        latency_note: Performance impact advisory.
+        migration_note: Migration complexity and steps advisory.
+    """
+
+    algorithm: str
+    fips_reference: str
+    rationale: str
+    latency_note: str
+    migration_note: str
+
+    @field_validator("fips_reference")
+    @classmethod
+    def fips_reference_non_empty(cls, v: str) -> str:
+        """Require fips_reference to be a non-empty string."""
+        v = v.strip()
+        if not v:
+            raise ValueError("fips_reference must be a non-empty string")
+        return v
+
+
+class SignatureEntry(BaseModel):
+    """A single detection signature for one algorithm/family.
+
+    Attributes:
+        name: Human-readable algorithm name (e.g. "RSA").
+        family: Broad algorithm family classification.
+        quantum_vulnerable: Whether the algorithm is vulnerable to quantum
+            attacks. For symmetric ciphers with a
+            ``min_quantum_safe_key_bits`` threshold this is the conservative
+            static default used when the extracted key size is unavailable;
+            per-detection it should be recomputed from the extracted key size
+            (see :data:`min_quantum_safe_key_bits`).
+        classically_broken: Whether the algorithm is already broken/deprecated
+            today, independent of quantum computing entirely (e.g. MD5, SHA-1,
+            DES, 3DES, RC4). Must be set explicitly on every entry — there is
+            no default.
+        min_quantum_safe_key_bits: Minimum key size (in bits) at which the
+            algorithm's post-quantum security is acceptable; only meaningful
+            for symmetric ciphers whose ``quantum_vulnerable`` should depend on
+            the extracted key size rather than being static. ``None`` elsewhere.
+        threat_horizon_years_default: Default Mosca threat horizon (Z) in years.
+        patterns: Map of language -> list of regex patterns used to detect this
+            algorithm in source code of that language.
+        key_size_pattern: Optional regex (with a capture group) used to extract
+            key size from matched source; ``None`` when key size is not relevant.
+        pqc_recommendation: Post-quantum migration recommendation.
+    """
+
+    name: str
+    family: Literal[
+        "asymmetric-encryption",
+        "signature",
+        "hash",
+        "symmetric-encryption",
+        "pqc-kem",
+        "pqc-signature",
+    ]
+    quantum_vulnerable: bool
+    classically_broken: bool
+    min_quantum_safe_key_bits: int | None = None
+    threat_horizon_years_default: float = Field(ge=0)
+    patterns: dict[str, list[str]]
+    key_size_pattern: str | None = None
+    pqc_recommendation: PqcRecommendation
+
+    @field_validator("name")
+    @classmethod
+    def name_non_empty(cls, v: str) -> str:
+        """Require name to be a non-empty string."""
+        v = v.strip()
+        if not v:
+            raise ValueError("name must be a non-empty string")
+        return v
+
+    @field_validator("patterns")
+    @classmethod
+    def patterns_have_at_least_one_language(
+        cls, v: dict[str, list[str]]
+    ) -> dict[str, list[str]]:
+        """Require patterns for at least one supported language.
+
+        Each supported language key must map to a non-empty list of non-empty
+        regex strings. Unknown language keys are rejected.
+        """
+        if not v:
+            raise ValueError("patterns must contain at least one language")
+
+        unknown = set(v.keys()) - SUPPORTED_LANGUAGES
+        if unknown:
+            raise ValueError(
+                f"patterns contains unsupported language(s): {sorted(unknown)}"
+            )
+
+        for lang, regexes in v.items():
+            if not regexes:
+                raise ValueError(f"patterns[{lang!r}] must be a non-empty list")
+            if any(not isinstance(r, str) or not r.strip() for r in regexes):
+                raise ValueError(f"patterns[{lang!r}] contains an empty pattern")
+
+        return v
+
+
+def _load_signatures() -> list[SignatureEntry]:
+    """Load and validate ``signatures.json`` into SignatureEntry instances."""
+    try:
+        raw = json.loads(_SIGNATURES_PATH.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise FileNotFoundError(
+            f"Cannot find cryptographic signature knowledge base at "
+            f"{_SIGNATURES_PATH}. Ensure ecdat_core/signatures.json is present."
+        ) from exc
+    except json.JSONDecodeError as exc:
+        raise ValueError(
+            f"signatures.json is not valid JSON: {exc.msg} "
+            f"(line {exc.lineno}, column {exc.colno})"
+        ) from exc
+
+    if not isinstance(raw, list):
+        raise ValueError(
+            f"signatures.json must be a JSON array of entries, "
+            f"got {type(raw).__name__}"
+        )
+
+    entries: list[SignatureEntry] = []
+    for idx, item in enumerate(raw):
+        try:
+            entries.append(SignatureEntry.model_validate(item))
+        except Exception as exc:  # noqa: BLE001 - surface any validation failure
+            raise ValueError(
+                f"signatures.json entry #{idx} failed validation: {exc}"
+            ) from exc
+
+    return entries
+
+
+# Load and validate once at import time. Any malformed entry aborts the import
+# with a descriptive error rather than surfacing later during a scan.
+_SIGNATURES: list[SignatureEntry] = _load_signatures()
+
+
+def get_all_signatures() -> list[SignatureEntry]:
+    """Return all validated signature entries from the knowledge base.
+
+    Returns:
+        list[SignatureEntry]: Every signature entry defined in signatures.json.
+    """
+    return list(_SIGNATURES)
+
+
+def get_signatures_for_language(lang: str) -> list[SignatureEntry]:
+    """Return signature entries that define patterns for the given language.
+
+    Args:
+        lang: A supported language name (e.g. "python", "go").
+
+    Returns:
+        list[SignatureEntry]: Entries with at least one detection pattern for
+        the requested language.
+
+    Raises:
+        ValueError: If ``lang`` is not a supported language.
+    """
+    if lang not in SUPPORTED_LANGUAGES:
+        raise ValueError(
+            f"Unsupported language {lang!r}; expected one of "
+            f"{sorted(SUPPORTED_LANGUAGES)}"
+        )
+    return [entry for entry in _SIGNATURES if lang in entry.patterns]