complyroll 0.2.0a0__py3-none-any.whl

complyroll/__init__.py

@@ -0,0 +1,31 @@
+"""ComplyRoll domain package."""
+
+from .models import (
+    CaseStatus,
+    Evaluation,
+    EvidenceArtifact,
+    Observation,
+    ObservationDisposition,
+    ObservationOrigin,
+    PainRating,
+    ResourceRef,
+    Sensitivity,
+    SourceSeverity,
+    VulnerabilityCase,
+)
+
+__all__ = [
+    "CaseStatus",
+    "Evaluation",
+    "EvidenceArtifact",
+    "Observation",
+    "ObservationDisposition",
+    "ObservationOrigin",
+    "PainRating",
+    "ResourceRef",
+    "Sensitivity",
+    "SourceSeverity",
+    "VulnerabilityCase",
+]
+
+__version__ = "0.2.0a0"

complyroll/__main__.py

@@ -0,0 +1,6 @@
+"""Run ComplyRoll with ``python -m complyroll``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

complyroll/adapters/__init__.py

@@ -0,0 +1,42 @@
+"""Source adapters and hardened ingestion entry points."""
+
+from .base import (
+    AdapterOutput,
+    ArtifactProvenance,
+    ControlMapping,
+    DiagnosticLevel,
+    IngestDiagnostic,
+    IngestResult,
+    SourceAdapter,
+)
+from .safeio import DEFAULT_LIMITS, IngestLimits, InputLimitError, UnsafeXmlError
+from .stig import (
+    CciControlMap,
+    CciMapResult,
+    CklAdapter,
+    CklbAdapter,
+    XccdfAdapter,
+    ingest_stig_artifact,
+    load_cci_control_map,
+)
+
+__all__ = [
+    "AdapterOutput",
+    "ArtifactProvenance",
+    "CciControlMap",
+    "CciMapResult",
+    "CklAdapter",
+    "CklbAdapter",
+    "ControlMapping",
+    "DEFAULT_LIMITS",
+    "DiagnosticLevel",
+    "IngestDiagnostic",
+    "IngestLimits",
+    "IngestResult",
+    "InputLimitError",
+    "SourceAdapter",
+    "UnsafeXmlError",
+    "XccdfAdapter",
+    "ingest_stig_artifact",
+    "load_cci_control_map",
+]

complyroll/adapters/base.py

@@ -0,0 +1,172 @@
+"""Adapter contracts and immutable ingestion result types."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any, Protocol
+
+from complyroll.models import Observation
+
+
+class DiagnosticLevel(str, Enum):
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+@dataclass(frozen=True, slots=True)
+class IngestDiagnostic:
+    level: DiagnosticLevel
+    code: str
+    message: str
+    location: str | None = None
+
+    def to_dict(self) -> dict[str, str]:
+        value = {
+            "level": self.level.value,
+            "code": self.code,
+            "message": self.message,
+        }
+        if self.location:
+            value["location"] = self.location
+        return value
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactProvenance:
+    artifact_id: str
+    name: str
+    source_path: str
+    digest_sha256: str
+    size_bytes: int
+    media_type: str
+    parser_name: str
+    parser_version: str
+    ingested_at: datetime
+
+    def __post_init__(self) -> None:
+        for value, field_name in (
+            (self.artifact_id, "artifact_id"),
+            (self.name, "name"),
+            (self.source_path, "source_path"),
+            (self.media_type, "media_type"),
+            (self.parser_name, "parser_name"),
+            (self.parser_version, "parser_version"),
+        ):
+            if not value or not value.strip():
+                raise ValueError(f"{field_name} must not be blank")
+        if self.size_bytes < 0:
+            raise ValueError("size_bytes must not be negative")
+        digest = self.digest_sha256.lower()
+        if len(digest) != 64 or any(char not in "0123456789abcdef" for char in digest):
+            raise ValueError("digest_sha256 must be a SHA-256 digest")
+        if self.ingested_at.tzinfo is None or self.ingested_at.utcoffset() is None:
+            raise ValueError("ingested_at must include a timezone")
+
+    @classmethod
+    def from_bytes(
+        cls,
+        *,
+        path: Path,
+        content: bytes,
+        media_type: str,
+        parser_name: str,
+        parser_version: str,
+        ingested_at: datetime,
+    ) -> ArtifactProvenance:
+        digest = hashlib.sha256(content).hexdigest()
+        return cls(
+            artifact_id=f"artifact-sha256-{digest}",
+            name=path.name,
+            source_path=str(path),
+            digest_sha256=digest,
+            size_bytes=len(content),
+            media_type=media_type,
+            parser_name=parser_name,
+            parser_version=parser_version,
+            ingested_at=ingested_at,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "artifact_id": self.artifact_id,
+            "name": self.name,
+            "source_path": self.source_path,
+            "digest_sha256": self.digest_sha256,
+            "size_bytes": self.size_bytes,
+            "media_type": self.media_type,
+            "parser_name": self.parser_name,
+            "parser_version": self.parser_version,
+            "ingested_at": self.ingested_at.isoformat(),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedDocument:
+    kind: str
+    value: Any
+
+
+@dataclass(frozen=True, slots=True)
+class AdapterOutput:
+    observations: tuple[Observation, ...]
+    diagnostics: tuple[IngestDiagnostic, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True, slots=True)
+class IngestResult:
+    artifact: ArtifactProvenance | None
+    observations: tuple[Observation, ...]
+    diagnostics: tuple[IngestDiagnostic, ...]
+
+    @property
+    def errors(self) -> tuple[IngestDiagnostic, ...]:
+        return tuple(item for item in self.diagnostics if item.level is DiagnosticLevel.ERROR)
+
+    @property
+    def warnings(self) -> tuple[IngestDiagnostic, ...]:
+        return tuple(item for item in self.diagnostics if item.level is DiagnosticLevel.WARNING)
+
+    @property
+    def successful(self) -> bool:
+        return self.artifact is not None and bool(self.observations) and not self.errors
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "successful": self.successful,
+            "artifact": self.artifact.to_dict() if self.artifact else None,
+            "diagnostics": [diagnostic.to_dict() for diagnostic in self.diagnostics],
+            "observations": [observation.to_canonical_dict() for observation in self.observations],
+        }
+
+    def to_canonical_json(self) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, separators=(",", ":"), sort_keys=True)
+
+
+class SourceAdapter(Protocol):
+    """A parser that turns one already-bounded document into observations."""
+
+    name: str
+    version: str
+    media_type: str
+
+    def parse(
+        self,
+        document: ParsedDocument,
+        artifact: ArtifactProvenance,
+        *,
+        ingested_at: datetime,
+    ) -> AdapterOutput: ...
+
+
+class ControlMapping(Protocol):
+    def controls_for(self, identifier: str) -> tuple[str, ...]: ...
+
+
+class AdapterParseError(ValueError):
+    """Raised when a supported document is not a usable source artifact."""

complyroll/adapters/safeio.py

@@ -0,0 +1,180 @@
+"""Bounded, network-free parsing helpers for untrusted source artifacts."""
+
+from __future__ import annotations
+
+import json
+import stat
+import xml.etree.ElementTree as ET
+import xml.parsers.expat as expat
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class IngestLimits:
+    max_artifact_bytes: int = 32 * 1024 * 1024
+    max_json_depth: int = 128
+    max_json_nodes: int = 500_000
+    max_xml_depth: int = 128
+    max_xml_elements: int = 500_000
+
+
+DEFAULT_LIMITS = IngestLimits()
+
+
+class InputLimitError(ValueError):
+    """An input exceeded an explicit resource bound."""
+
+
+class UnsafeXmlError(ValueError):
+    """XML contained a prohibited declaration."""
+
+
+def read_bounded(path: Path, limits: IngestLimits = DEFAULT_LIMITS) -> bytes:
+    """Read a regular file into memory, refusing anything larger than the artifact bound."""
+
+    limit = limits.max_artifact_bytes
+    status = path.stat()
+    if not stat.S_ISREG(status.st_mode):
+        raise ValueError(f"artifact is not a regular file: {path}")
+    if status.st_size > limit:
+        raise InputLimitError(f"artifact is {status.st_size} bytes; maximum is {limit} bytes")
+
+    chunks: list[bytes] = []
+    total = 0
+    with path.open("rb") as handle:
+        while total <= limit:
+            chunk = handle.read(limit + 1 - total)
+            if not chunk:
+                break
+            chunks.append(chunk)
+            total += len(chunk)
+    if total > limit:
+        raise InputLimitError(f"artifact is larger than {limit} bytes; maximum is {limit} bytes")
+    return b"".join(chunks)
+
+
+def parse_json_bounded(content: bytes, limits: IngestLimits = DEFAULT_LIMITS) -> Any:
+    def reject_nonstandard_constant(value: str) -> None:
+        raise ValueError(f"non-standard JSON constant is prohibited: {value}")
+
+    def reject_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+        value: dict[str, Any] = {}
+        for key, item in pairs:
+            if key in value:
+                raise ValueError(f"duplicate JSON object key is prohibited: {key}")
+            value[key] = item
+        return value
+
+    try:
+        value = json.loads(
+            content.decode("utf-8-sig"),
+            parse_constant=reject_nonstandard_constant,
+            object_pairs_hook=reject_duplicate_keys,
+        )
+    except UnicodeDecodeError as exc:
+        raise ValueError(f"JSON must be UTF-8: {exc}") from exc
+    except RecursionError as exc:
+        raise InputLimitError("JSON nesting exceeds the parser's safe recursion limit") from exc
+
+    nodes = 0
+    stack: list[tuple[Any, int]] = [(value, 1)]
+    while stack:
+        current, depth = stack.pop()
+        nodes += 1
+        if nodes > limits.max_json_nodes:
+            raise InputLimitError(f"JSON contains more than {limits.max_json_nodes} values")
+        if depth > limits.max_json_depth:
+            raise InputLimitError(f"JSON nesting exceeds {limits.max_json_depth} levels")
+        if isinstance(current, dict):
+            stack.extend((item, depth + 1) for item in current.values())
+        elif isinstance(current, list):
+            stack.extend((item, depth + 1) for item in current)
+    return value
+
+
+def _qualified_name(name: str) -> str:
+    """Convert expat's ``uri}local`` name to ElementTree's ``{uri}local`` convention."""
+
+    return f"{{{name}" if "}" in name else name
+
+
+def parse_xml_bounded(content: bytes, limits: IngestLimits = DEFAULT_LIMITS) -> ET.Element:
+    """Parse XML with declaration rejection and bounds enforced inside the parser.
+
+    Prohibited declarations are refused by expat's own handlers rather than by scanning the
+    source bytes, so the guard holds for every encoding expat auto-detects and never rejects a
+    document that merely quotes ``<!DOCTYPE`` inside character data or a comment.
+    """
+
+    builder = ET.TreeBuilder()
+    root: ET.Element | None = None
+    depth = 0
+    elements = 0
+
+    def reject_doctype(
+        name: str,
+        system_id: str | None,
+        public_id: str | None,
+        has_internal_subset: bool,
+    ) -> None:
+        raise UnsafeXmlError("DOCTYPE declarations are prohibited")
+
+    def reject_entity(
+        name: str,
+        is_parameter_entity: bool,
+        value: str | None,
+        base: str | None,
+        system_id: str | None,
+        public_id: str | None,
+        notation_name: str | None,
+    ) -> None:
+        raise UnsafeXmlError("ENTITY declarations are prohibited")
+
+    def reject_external_entity(
+        context: str | None,
+        base: str | None,
+        system_id: str | None,
+        public_id: str | None,
+    ) -> bool:
+        raise UnsafeXmlError("external entity references are prohibited")
+
+    def start_element(name: str, attributes: dict[str, str]) -> None:
+        nonlocal root, depth, elements
+        elements += 1
+        depth += 1
+        if elements > limits.max_xml_elements:
+            raise InputLimitError(f"XML contains more than {limits.max_xml_elements} elements")
+        if depth > limits.max_xml_depth:
+            raise InputLimitError(f"XML nesting exceeds {limits.max_xml_depth} levels")
+        element = builder.start(
+            _qualified_name(name),
+            {_qualified_name(key): value for key, value in attributes.items()},
+        )
+        if root is None:
+            root = element
+
+    def end_element(name: str) -> None:
+        nonlocal depth
+        depth -= 1
+        builder.end(_qualified_name(name))
+
+    parser = expat.ParserCreate(namespace_separator="}")
+    parser.buffer_text = True
+    parser.StartDoctypeDeclHandler = reject_doctype
+    parser.EntityDeclHandler = reject_entity
+    parser.ExternalEntityRefHandler = reject_external_entity
+    parser.StartElementHandler = start_element
+    parser.EndElementHandler = end_element
+    parser.CharacterDataHandler = builder.data
+
+    try:
+        parser.Parse(content, True)
+        builder.close()
+    except (expat.ExpatError, ET.ParseError) as exc:
+        raise ValueError(f"malformed XML: {exc}") from exc
+
+    if root is None:
+        raise ValueError("XML document has no root element")
+    return root