kekkai-cli 1.0.0__py3-none-any.whl

kekkai_core/ci/metadata.py

@@ -0,0 +1,104 @@
+"""Metadata extraction utilities for CI/CD distribution triggers."""
+
+import hashlib
+import re
+from pathlib import Path
+
+
+def extract_version_from_tag(tag: str) -> str:
+    """
+    Extract semantic version from Git tag.
+
+    Args:
+        tag: Git tag string (e.g., "v0.0.1", "v0.0.1-rc1")
+
+    Returns:
+        Version string without 'v' prefix (e.g., "0.0.1", "0.0.1-rc1")
+
+    Raises:
+        ValueError: If tag format is invalid
+    """
+    if not tag:
+        raise ValueError("Tag cannot be empty")
+
+    # Remove 'v' prefix if present
+    version = tag[1:] if tag.startswith("v") else tag
+
+    # Validate basic semver pattern (with optional pre-release and build metadata)
+    pattern = r"^\d+\.\d+\.\d+(-[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*)?(\+[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*)?$"
+    if not re.match(pattern, version):
+        raise ValueError(f"Invalid tag format: {tag}. Expected format: v0.0.1 or v0.0.1-rc1")
+
+    return version
+
+
+def calculate_sha256(file_path: Path) -> str:
+    """
+    Calculate SHA256 checksum of a file.
+
+    Args:
+        file_path: Path to file to checksum
+
+    Returns:
+        SHA256 hex digest string
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        OSError: If file cannot be read
+    """
+    if not file_path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    sha256_hash = hashlib.sha256()
+    with file_path.open("rb") as f:
+        # Read in 64KB chunks for memory efficiency
+        for chunk in iter(lambda: f.read(65536), b""):
+            sha256_hash.update(chunk)
+
+    return sha256_hash.hexdigest()
+
+
+def extract_tarball_url(repo: str, version: str) -> str:
+    """
+    Generate GitHub release tarball URL.
+
+    Args:
+        repo: Repository name (e.g., "kademoslabs/kekkai")
+        version: Version string (e.g., "0.0.1")
+
+    Returns:
+        GitHub release tarball URL
+    """
+    # Remove 'v' prefix if present for URL consistency
+    clean_version = version[1:] if version.startswith("v") else version
+    return f"https://github.com/{repo}/archive/refs/tags/v{clean_version}.tar.gz"
+
+
+def format_dispatch_payload(
+    event_type: str,
+    version: str,
+    sha256: str | None = None,
+) -> dict[str, object]:
+    """
+    Format repository_dispatch payload for distribution updates.
+
+    Args:
+        event_type: Dispatch event type (e.g., "kekkai-release")
+        version: Version string
+        sha256: Optional SHA256 checksum
+
+    Returns:
+        JSON-serializable dispatch payload
+    """
+    payload: dict[str, object] = {
+        "event_type": event_type,
+        "client_payload": {
+            "version": version,
+        },
+    }
+
+    if sha256:
+        assert isinstance(payload["client_payload"], dict)  # nosec B101
+        payload["client_payload"]["sha256"] = sha256
+
+    return payload

kekkai_core/ci/validators.py

@@ -0,0 +1,92 @@
+"""Validation utilities for CI/CD distribution triggers."""
+
+import re
+from pathlib import Path
+
+
+def validate_semver(version: str) -> bool:
+    """
+    Validate semantic versioning format.
+
+    Args:
+        version: Version string to validate
+
+    Returns:
+        True if valid semver, False otherwise
+
+    Examples:
+        >>> validate_semver("0.0.1")
+        True
+        >>> validate_semver("0.0.1-rc1")
+        True
+        >>> validate_semver("v0.0.1")
+        False
+        >>> validate_semver("1.2")
+        False
+    """
+    # Strict semver: MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
+    pattern = r"^\d+\.\d+\.\d+(-[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*)?(\+[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*)?$"
+    return bool(re.match(pattern, version))
+
+
+def verify_checksum(file_path: Path, expected_sha256: str) -> bool:
+    """
+    Verify file SHA256 checksum matches expected value.
+
+    Args:
+        file_path: Path to file to verify
+        expected_sha256: Expected SHA256 hex digest
+
+    Returns:
+        True if checksums match, False otherwise
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+    """
+    from kekkai_core.ci.metadata import calculate_sha256
+
+    actual_sha256 = calculate_sha256(file_path)
+    return actual_sha256.lower() == expected_sha256.lower()
+
+
+def validate_repo_format(repo: str) -> bool:
+    """
+    Validate GitHub repository format.
+
+    Args:
+        repo: Repository string (e.g., "kademoslabs/kekkai")
+
+    Returns:
+        True if valid format, False otherwise
+
+    Examples:
+        >>> validate_repo_format("kademoslabs/kekkai")
+        True
+        >>> validate_repo_format("kademoslabs")
+        False
+        >>> validate_repo_format("kademoslabs/kekkai/extra")
+        False
+    """
+    pattern = r"^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$"
+    return bool(re.match(pattern, repo))
+
+
+def validate_github_token(token: str) -> bool:
+    """
+    Validate GitHub token format (basic check).
+
+    Args:
+        token: GitHub token string
+
+    Returns:
+        True if format looks valid, False otherwise
+
+    Note:
+        This only validates format, not token validity or permissions.
+    """
+    if not token:
+        return False
+
+    # GitHub personal access tokens are typically 40+ characters
+    # Classic tokens start with ghp_, fine-grained with github_pat_
+    return not len(token) < 20

kekkai_core/docker/__init__.py

@@ -0,0 +1,17 @@
+"""Docker security utilities for scanning, signing, and SBOM generation."""
+
+from kekkai_core.docker.metadata import extract_image_metadata, parse_manifest
+from kekkai_core.docker.sbom import generate_sbom, validate_sbom_format
+from kekkai_core.docker.security import filter_vulnerabilities, run_trivy_scan
+from kekkai_core.docker.signing import sign_image, verify_signature
+
+__all__ = [
+    "run_trivy_scan",
+    "filter_vulnerabilities",
+    "sign_image",
+    "verify_signature",
+    "generate_sbom",
+    "validate_sbom_format",
+    "extract_image_metadata",
+    "parse_manifest",
+]

kekkai_core/docker/metadata.py

@@ -0,0 +1,153 @@
+"""Docker image metadata extraction and validation."""
+
+import json
+import subprocess
+from typing import Any
+
+
+class DockerMetadataError(Exception):
+    """Raised when metadata extraction fails."""
+
+
+def extract_image_metadata(image: str) -> dict[str, Any]:
+    """
+    Extract metadata from Docker image.
+
+    Args:
+        image: Docker image (e.g., 'kademoslabs/kekkai:latest')
+
+    Returns:
+        Image metadata as dictionary
+
+    Raises:
+        DockerMetadataError: If extraction fails
+    """
+    cmd = ["docker", "inspect", image]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=30,
+        )
+
+        metadata = json.loads(result.stdout)
+
+        if not metadata or not isinstance(metadata, list):
+            raise DockerMetadataError(f"Invalid metadata format for image: {image}")
+
+        return metadata[0] if metadata else {}
+
+    except subprocess.CalledProcessError as e:
+        raise DockerMetadataError(f"Failed to extract metadata: {e.stderr}") from e
+    except subprocess.TimeoutExpired as e:
+        raise DockerMetadataError("Metadata extraction timed out after 30s") from e
+    except json.JSONDecodeError as e:
+        raise DockerMetadataError(f"Failed to parse metadata: {e}") from e
+
+
+def get_oci_labels(metadata: dict[str, Any]) -> dict[str, str]:
+    """
+    Extract OCI labels from image metadata.
+
+    Args:
+        metadata: Image metadata dictionary
+
+    Returns:
+        Dictionary of OCI labels
+    """
+    config = metadata.get("Config", {})
+    labels = config.get("Labels") or {}
+
+    # Filter for OCI labels (org.opencontainers.image.*)
+    oci_labels = {
+        key: value for key, value in labels.items() if key.startswith("org.opencontainers.image.")
+    }
+
+    return oci_labels
+
+
+def parse_manifest(image: str) -> dict[str, Any]:
+    """
+    Parse Docker image manifest.
+
+    Args:
+        image: Docker image (e.g., 'kademoslabs/kekkai:latest')
+
+    Returns:
+        Manifest as dictionary
+
+    Raises:
+        DockerMetadataError: If parsing fails
+    """
+    cmd = ["docker", "manifest", "inspect", image]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=30,
+        )
+
+        manifest: dict[str, Any] = json.loads(result.stdout)
+        return manifest
+
+    except subprocess.CalledProcessError as e:
+        raise DockerMetadataError(f"Failed to parse manifest: {e.stderr}") from e
+    except subprocess.TimeoutExpired as e:
+        raise DockerMetadataError("Manifest parsing timed out after 30s") from e
+    except json.JSONDecodeError as e:
+        raise DockerMetadataError(f"Failed to parse manifest JSON: {e}") from e
+
+
+def get_supported_architectures(manifest: dict[str, Any]) -> list[str]:
+    """
+    Extract supported architectures from manifest.
+
+    Args:
+        manifest: Image manifest dictionary
+
+    Returns:
+        List of supported architectures (e.g., ['amd64', 'arm64'])
+    """
+    architectures: list[str] = []
+
+    # Multi-arch manifests have a "manifests" array
+    manifests = manifest.get("manifests", [])
+
+    if manifests:
+        for m in manifests:
+            platform = m.get("platform", {})
+            arch = platform.get("architecture", "")
+            if arch:
+                architectures.append(arch)
+    else:
+        # Single-arch image
+        platform = manifest.get("platform", {})
+        arch = platform.get("architecture", "")
+        if arch:
+            architectures.append(arch)
+
+    return architectures
+
+
+def verify_multi_arch_support(
+    manifest: dict[str, Any],
+    required_archs: list[str],
+) -> bool:
+    """
+    Verify image supports required architectures.
+
+    Args:
+        manifest: Image manifest dictionary
+        required_archs: List of required architectures
+
+    Returns:
+        True if all required architectures are supported
+    """
+    supported = get_supported_architectures(manifest)
+    return all(arch in supported for arch in required_archs)

kekkai_core/docker/sbom.py

@@ -0,0 +1,173 @@
+"""SBOM (Software Bill of Materials) generation for Docker images."""
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Any, Literal
+
+SBOMFormat = Literal["spdx", "spdx-json", "cyclonedx", "cyclonedx-json"]
+
+
+class SBOMError(Exception):
+    """Raised when SBOM generation fails."""
+
+
+def generate_sbom(
+    image: str,
+    output_format: SBOMFormat = "spdx-json",
+    output_file: Path | None = None,
+) -> dict[str, Any]:
+    """
+    Generate SBOM for Docker image using Trivy.
+
+    Args:
+        image: Docker image to analyze (e.g., 'kademoslabs/kekkai:latest')
+        output_format: SBOM format (spdx-json, cyclonedx-json, etc.)
+        output_file: Path to write SBOM (optional)
+
+    Returns:
+        SBOM as dictionary
+
+    Raises:
+        SBOMError: If SBOM generation fails
+    """
+    # Map our format to Trivy's format argument
+    format_map = {
+        "spdx": "spdx",
+        "spdx-json": "spdx-json",
+        "cyclonedx": "cyclonedx",
+        "cyclonedx-json": "cyclonedx-json",
+    }
+
+    trivy_format = format_map.get(output_format, "spdx-json")
+
+    cmd = ["trivy", "image", "--format", trivy_format]
+
+    if output_file:
+        cmd.extend(["--output", str(output_file)])
+
+    cmd.append(image)
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=300,
+        )
+
+        # Parse JSON output
+        if output_format.endswith("-json"):
+            return json.loads(result.stdout) if result.stdout else {}
+        else:
+            # For non-JSON formats, return raw output
+            return {"sbom": result.stdout}
+
+    except subprocess.CalledProcessError as e:
+        raise SBOMError(f"SBOM generation failed: {e.stderr}") from e
+    except subprocess.TimeoutExpired as e:
+        raise SBOMError("SBOM generation timed out after 300s") from e
+    except json.JSONDecodeError as e:
+        raise SBOMError(f"Failed to parse SBOM output: {e}") from e
+
+
+def validate_sbom_format(sbom_data: dict[str, Any], expected_format: SBOMFormat) -> bool:
+    """
+    Validate SBOM data structure matches expected format.
+
+    Args:
+        sbom_data: SBOM dictionary
+        expected_format: Expected SBOM format
+
+    Returns:
+        True if SBOM structure is valid
+    """
+    if expected_format == "spdx-json":
+        # SPDX must have these fields
+        required_fields = ["spdxVersion", "dataLicense", "name", "documentNamespace"]
+        return all(field in sbom_data for field in required_fields)
+
+    elif expected_format == "cyclonedx-json":
+        # CycloneDX must have these fields
+        required_fields = ["bomFormat", "specVersion", "version"]
+        return all(field in sbom_data for field in required_fields)
+
+    return False
+
+
+def extract_dependencies(sbom_data: dict[str, Any], sbom_format: SBOMFormat) -> list[str]:
+    """
+    Extract package dependencies from SBOM.
+
+    Args:
+        sbom_data: SBOM dictionary
+        sbom_format: SBOM format
+
+    Returns:
+        List of package names
+    """
+    dependencies: list[str] = []
+
+    if sbom_format == "spdx-json":
+        # SPDX packages
+        packages = sbom_data.get("packages", [])
+        for pkg in packages:
+            name = pkg.get("name", "")
+            if name:
+                dependencies.append(name)
+
+    elif sbom_format == "cyclonedx-json":
+        # CycloneDX components
+        components = sbom_data.get("components", [])
+        for comp in components:
+            name = comp.get("name", "")
+            if name:
+                dependencies.append(name)
+
+    return dependencies
+
+
+def attach_sbom_to_image(
+    image: str,
+    sbom_file: Path,
+) -> bool:
+    """
+    Attach SBOM to Docker image using Cosign.
+
+    Args:
+        image: Docker image (e.g., 'kademoslabs/kekkai:latest')
+        sbom_file: Path to SBOM file
+
+    Returns:
+        True if attachment succeeded
+
+    Raises:
+        SBOMError: If attachment fails
+    """
+    if not sbom_file.exists():
+        raise SBOMError(f"SBOM file not found: {sbom_file}")
+
+    cmd = [
+        "cosign",
+        "attach",
+        "sbom",
+        "--sbom",
+        str(sbom_file),
+        image,
+    ]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=120,
+        )
+        return result.returncode == 0
+
+    except subprocess.CalledProcessError as e:
+        raise SBOMError(f"SBOM attachment failed: {e.stderr}") from e
+    except subprocess.TimeoutExpired as e:
+        raise SBOMError("SBOM attachment timed out after 120s") from e

kekkai_core/docker/security.py

@@ -0,0 +1,158 @@
+"""Docker image security scanning with Trivy."""
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Any, Literal, cast
+
+SeverityLevel = Literal["CRITICAL", "HIGH", "MEDIUM", "LOW", "UNKNOWN"]
+
+
+class TrivyScanError(Exception):
+    """Raised when Trivy scan fails."""
+
+
+def run_trivy_scan(
+    image: str,
+    output_format: Literal["json", "sarif", "table"] = "json",
+    severity: list[SeverityLevel] | None = None,
+    output_file: Path | None = None,
+) -> dict[str, Any]:
+    """
+    Run Trivy security scan on Docker image.
+
+    Args:
+        image: Docker image to scan (e.g., 'kademoslabs/kekkai:latest')
+        output_format: Output format (json, sarif, table)
+        severity: List of severity levels to include (default: all)
+        output_file: Path to write scan results (optional)
+
+    Returns:
+        Scan results as dictionary
+
+    Raises:
+        TrivyScanError: If scan fails
+    """
+    cmd = ["trivy", "image", "--format", output_format]
+
+    if severity:
+        cmd.extend(["--severity", ",".join(severity)])
+
+    if output_file:
+        cmd.extend(["--output", str(output_file)])
+
+    cmd.append(image)
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=300,
+        )
+
+        if output_format == "json" or output_format == "sarif":
+            return json.loads(result.stdout) if result.stdout else {}
+        else:
+            # For table format, return raw output
+            return {"output": result.stdout}
+
+    except subprocess.CalledProcessError as e:
+        raise TrivyScanError(f"Trivy scan failed: {e.stderr}") from e
+    except subprocess.TimeoutExpired as e:
+        raise TrivyScanError("Trivy scan timed out after 300s") from e
+    except json.JSONDecodeError as e:
+        raise TrivyScanError(f"Failed to parse Trivy output: {e}") from e
+    except Exception as e:
+        raise TrivyScanError(f"Trivy scan failed: {e}") from e
+
+
+def filter_vulnerabilities(
+    scan_results: dict[str, Any],
+    severity_threshold: SeverityLevel = "HIGH",
+) -> list[dict[str, Any]]:
+    """
+    Filter vulnerabilities by severity threshold.
+
+    Args:
+        scan_results: Trivy scan results (JSON format)
+        severity_threshold: Minimum severity to include
+
+    Returns:
+        List of vulnerabilities meeting threshold
+    """
+    severity_order: dict[SeverityLevel, int] = {
+        "CRITICAL": 4,
+        "HIGH": 3,
+        "MEDIUM": 2,
+        "LOW": 1,
+        "UNKNOWN": 0,
+    }
+
+    threshold_level = severity_order.get(severity_threshold, 0)
+    filtered: list[dict[str, Any]] = []
+
+    # Trivy JSON format has "Results" array
+    results = scan_results.get("Results", [])
+
+    for result in results:
+        vulnerabilities = result.get("Vulnerabilities", [])
+        for vuln in vulnerabilities:
+            severity = vuln.get("Severity", "UNKNOWN")
+            severity_value = severity_order.get(severity, 0)
+            if severity_value >= threshold_level:
+                filtered.append(vuln)
+
+    return filtered
+
+
+def count_vulnerabilities_by_severity(
+    scan_results: dict[str, Any],
+) -> dict[SeverityLevel, int]:
+    """
+    Count vulnerabilities by severity level.
+
+    Args:
+        scan_results: Trivy scan results (JSON format)
+
+    Returns:
+        Dictionary mapping severity to count
+    """
+    counts: dict[SeverityLevel, int] = {
+        "CRITICAL": 0,
+        "HIGH": 0,
+        "MEDIUM": 0,
+        "LOW": 0,
+        "UNKNOWN": 0,
+    }
+
+    results = scan_results.get("Results", [])
+
+    for result in results:
+        vulnerabilities = result.get("Vulnerabilities", [])
+        for vuln in vulnerabilities:
+            severity = vuln.get("Severity", "UNKNOWN")
+            if severity in counts:
+                severity_key = cast(SeverityLevel, severity)
+                counts[severity_key] += 1
+
+    return counts
+
+
+def has_critical_vulnerabilities(
+    scan_results: dict[str, Any],
+    severity_threshold: SeverityLevel = "HIGH",
+) -> bool:
+    """
+    Check if scan results contain vulnerabilities at or above threshold.
+
+    Args:
+        scan_results: Trivy scan results (JSON format)
+        severity_threshold: Minimum severity to check
+
+    Returns:
+        True if vulnerabilities found at or above threshold
+    """
+    filtered = filter_vulnerabilities(scan_results, severity_threshold)
+    return len(filtered) > 0