kekkai-cli 1.0.5__py3-none-any.whl → 1.1.1__py3-none-any.whl

kekkai/compliance/__init__.py

@@ -0,0 +1,68 @@
+"""Compliance framework mapping for security findings.
+
+Maps security findings to compliance framework controls for audit reporting.
+
+Supported frameworks:
+- PCI-DSS v4.0 (Payment Card Industry)
+- SOC 2 Type II (Service Organization Controls)
+- OWASP Top 10 2025 (Web Application Security)
+- OWASP Agentic AI Top 10 (Autonomous AI Agent Security)
+- HIPAA (Health Insurance Portability and Accountability)
+
+Security considerations:
+- Mappings are advisory, not compliance certifications
+- Always include disclaimer in generated reports
+- Raw finding data shown, no compliance assessments
+
+ASVS Requirements:
+- V5.3.1: Output encoding for reports
+- V8.1.1: Reports stored in user-specified paths only
+"""
+
+from __future__ import annotations
+
+from .hipaa import HIPAA_SAFEGUARDS, HIPAASafeguard, map_to_hipaa
+from .mappings import (
+    ComplianceMapping,
+    ComplianceMappingResult,
+    FrameworkControl,
+    map_finding_to_frameworks,
+    map_findings_to_all_frameworks,
+)
+from .owasp import OWASP_TOP_10, OWASPCategory, map_to_owasp
+from .owasp_agentic import (
+    OWASP_AGENTIC_TOP_10,
+    OWASPAgenticCategory,
+    map_to_owasp_agentic,
+)
+from .pci_dss import PCI_DSS_CONTROLS, PCIDSSControl, map_to_pci_dss
+from .soc2 import SOC2_CRITERIA, SOC2Criterion, map_to_soc2
+
+__all__ = [
+    # Core mapping
+    "ComplianceMapping",
+    "ComplianceMappingResult",
+    "FrameworkControl",
+    "map_finding_to_frameworks",
+    "map_findings_to_all_frameworks",
+    # PCI-DSS
+    "PCIDSSControl",
+    "PCI_DSS_CONTROLS",
+    "map_to_pci_dss",
+    # SOC 2
+    "SOC2Criterion",
+    "SOC2_CRITERIA",
+    "map_to_soc2",
+    # OWASP Top 10 2025
+    "OWASPCategory",
+    "OWASP_TOP_10",
+    "map_to_owasp",
+    # OWASP Agentic AI Top 10
+    "OWASPAgenticCategory",
+    "OWASP_AGENTIC_TOP_10",
+    "map_to_owasp_agentic",
+    # HIPAA
+    "HIPAASafeguard",
+    "HIPAA_SAFEGUARDS",
+    "map_to_hipaa",
+]

kekkai/compliance/hipaa.py

@@ -0,0 +1,235 @@
+"""HIPAA Security Rule safeguard mapping for security findings.
+
+Maps findings to HIPAA Security Rule safeguards based on CWE IDs and rule patterns.
+Reference: https://www.hhs.gov/hipaa/for-professionals/security/index.html
+
+Note: HIPAA mappings are advisory and apply primarily to healthcare-related
+applications handling Protected Health Information (PHI).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .mappings import FrameworkControl
+
+if TYPE_CHECKING:
+    from kekkai.scanners.base import Finding
+
+
+@dataclass(frozen=True)
+class HIPAASafeguard:
+    """HIPAA Security Rule safeguard definition."""
+
+    id: str
+    title: str
+    description: str
+    category: str  # Administrative, Physical, Technical
+    implementation: str  # Required, Addressable
+    cwes: frozenset[int]
+    rule_patterns: tuple[str, ...]
+
+
+# HIPAA Security Rule safeguards relevant to application security
+HIPAA_SAFEGUARDS: dict[str, HIPAASafeguard] = {
+    # Technical Safeguards
+    "164.312(a)(1)": HIPAASafeguard(
+        id="164.312(a)(1)",
+        title="Access Control",
+        description=(
+            "Implement technical policies and procedures for electronic "
+            "information systems that maintain ePHI"
+        ),
+        category="Technical",
+        implementation="Required",
+        cwes=frozenset({264, 284, 285, 287, 306, 639, 862, 863}),
+        rule_patterns=("access-control", "authorization", "authentication"),
+    ),
+    "164.312(a)(2)(i)": HIPAASafeguard(
+        id="164.312(a)(2)(i)",
+        title="Unique User Identification",
+        description="Assign a unique name and/or number for identifying and tracking user identity",
+        category="Technical",
+        implementation="Required",
+        cwes=frozenset({287, 288, 521}),
+        rule_patterns=("user-identification", "identity", "authentication"),
+    ),
+    "164.312(a)(2)(ii)": HIPAASafeguard(
+        id="164.312(a)(2)(ii)",
+        title="Emergency Access Procedure",
+        description="Establish procedures for obtaining necessary ePHI during an emergency",
+        category="Technical",
+        implementation="Required",
+        cwes=frozenset({269}),
+        rule_patterns=("emergency-access", "break-glass"),
+    ),
+    "164.312(a)(2)(iii)": HIPAASafeguard(
+        id="164.312(a)(2)(iii)",
+        title="Automatic Logoff",
+        description=(
+            "Implement electronic procedures that terminate an electronic session after inactivity"
+        ),
+        category="Technical",
+        implementation="Addressable",
+        cwes=frozenset({613}),
+        rule_patterns=("session", "timeout", "logoff", "idle"),
+    ),
+    "164.312(a)(2)(iv)": HIPAASafeguard(
+        id="164.312(a)(2)(iv)",
+        title="Encryption and Decryption",
+        description="Implement a mechanism to encrypt and decrypt ePHI",
+        category="Technical",
+        implementation="Addressable",
+        cwes=frozenset({311, 312, 319, 326, 327, 328}),
+        rule_patterns=("encryption", "crypto", "decrypt"),
+    ),
+    "164.312(b)": HIPAASafeguard(
+        id="164.312(b)",
+        title="Audit Controls",
+        description=(
+            "Implement hardware, software, and/or procedures to record and examine activity"
+        ),
+        category="Technical",
+        implementation="Required",
+        cwes=frozenset({117, 223, 532, 778}),
+        rule_patterns=("audit", "logging", "monitoring", "log-injection"),
+    ),
+    "164.312(c)(1)": HIPAASafeguard(
+        id="164.312(c)(1)",
+        title="Integrity",
+        description=(
+            "Implement policies and procedures to protect ePHI from "
+            "improper alteration or destruction"
+        ),
+        category="Technical",
+        implementation="Required",
+        cwes=frozenset({345, 353, 494, 502}),
+        rule_patterns=("integrity", "tampering", "modification"),
+    ),
+    "164.312(c)(2)": HIPAASafeguard(
+        id="164.312(c)(2)",
+        title="Mechanism to Authenticate ePHI",
+        description="Implement electronic mechanisms to corroborate that ePHI has not been altered",
+        category="Technical",
+        implementation="Addressable",
+        cwes=frozenset({345, 347, 354}),
+        rule_patterns=("authentication", "signature", "hash", "checksum"),
+    ),
+    "164.312(d)": HIPAASafeguard(
+        id="164.312(d)",
+        title="Person or Entity Authentication",
+        description=(
+            "Implement procedures to verify that a person or entity seeking "
+            "access is the one claimed"
+        ),
+        category="Technical",
+        implementation="Required",
+        cwes=frozenset({287, 290, 294, 295, 302, 306, 307}),
+        rule_patterns=("authentication", "verify", "identity", "credential"),
+    ),
+    "164.312(e)(1)": HIPAASafeguard(
+        id="164.312(e)(1)",
+        title="Transmission Security",
+        description=(
+            "Implement technical security measures to guard against unauthorized access to ePHI"
+        ),
+        category="Technical",
+        implementation="Required",
+        cwes=frozenset({319, 523, 757}),
+        rule_patterns=("transmission", "tls", "ssl", "transport"),
+    ),
+    "164.312(e)(2)(i)": HIPAASafeguard(
+        id="164.312(e)(2)(i)",
+        title="Integrity Controls",
+        description=(
+            "Implement security measures to ensure electronically transmitted "
+            "ePHI is not improperly modified"
+        ),
+        category="Technical",
+        implementation="Addressable",
+        cwes=frozenset({319, 345}),
+        rule_patterns=("integrity", "transmission", "modification"),
+    ),
+    "164.312(e)(2)(ii)": HIPAASafeguard(
+        id="164.312(e)(2)(ii)",
+        title="Encryption",
+        description="Implement mechanism to encrypt ePHI whenever deemed appropriate",
+        category="Technical",
+        implementation="Addressable",
+        cwes=frozenset({311, 319, 326, 327}),
+        rule_patterns=("encryption", "tls", "ssl"),
+    ),
+    # Administrative Safeguards (security-relevant)
+    "164.308(a)(1)(ii)(A)": HIPAASafeguard(
+        id="164.308(a)(1)(ii)(A)",
+        title="Risk Analysis",
+        description=(
+            "Conduct an accurate and thorough assessment of potential risks and vulnerabilities"
+        ),
+        category="Administrative",
+        implementation="Required",
+        cwes=frozenset({937, 1035, 1104}),
+        rule_patterns=("vulnerability", "risk", "cve-", "scan"),
+    ),
+    "164.308(a)(5)(ii)(B)": HIPAASafeguard(
+        id="164.308(a)(5)(ii)(B)",
+        title="Protection from Malicious Software",
+        description="Procedures for guarding against, detecting, and reporting malicious software",
+        category="Administrative",
+        implementation="Addressable",
+        cwes=frozenset({94, 502, 829}),
+        rule_patterns=("malware", "malicious", "injection"),
+    ),
+}
+
+
+def _extract_cwe_id(cwe_str: str | None) -> int | None:
+    """Extract numeric CWE ID from string."""
+    if not cwe_str:
+        return None
+    cwe_str = cwe_str.upper().replace("CWE-", "").replace("CWE", "")
+    try:
+        return int(cwe_str.strip())
+    except ValueError:
+        return None
+
+
+def map_to_hipaa(finding: Finding) -> list[FrameworkControl]:
+    """Map a finding to HIPAA Security Rule safeguards."""
+    controls: list[FrameworkControl] = []
+
+    cwe_id = _extract_cwe_id(finding.cwe)
+    rule_id_lower = (finding.rule_id or "").lower()
+    title_lower = finding.title.lower()
+
+    for safeguard in HIPAA_SAFEGUARDS.values():
+        matched = False
+
+        # Match by CWE
+        if cwe_id and cwe_id in safeguard.cwes:
+            matched = True
+
+        # Match by rule pattern
+        if not matched:
+            for pattern in safeguard.rule_patterns:
+                if pattern in rule_id_lower or pattern in title_lower:
+                    matched = True
+                    break
+
+        # CVEs map to 164.308(a)(1)(ii)(A) (risk analysis)
+        if not matched and safeguard.id == "164.308(a)(1)(ii)(A)" and finding.cve:
+            matched = True
+
+        if matched:
+            controls.append(
+                FrameworkControl(
+                    framework="HIPAA",
+                    control_id=safeguard.id,
+                    title=safeguard.title,
+                    description=safeguard.description,
+                    requirement_level=safeguard.implementation.lower(),
+                )
+            )
+
+    return controls

kekkai/compliance/mappings.py

@@ -0,0 +1,136 @@
+"""Core compliance mapping engine.
+
+Maps security findings to compliance framework controls using CWE IDs,
+rule patterns, and severity levels.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from kekkai.scanners.base import Finding
+
+
+@dataclass(frozen=True)
+class FrameworkControl:
+    """A single compliance framework control."""
+
+    framework: str
+    control_id: str
+    title: str
+    description: str
+    requirement_level: str = "required"  # required, recommended, optional
+
+
+@dataclass
+class ComplianceMapping:
+    """Mapping of a finding to compliance controls."""
+
+    finding_hash: str
+    finding_title: str
+    finding_severity: str
+    controls: list[FrameworkControl] = field(default_factory=list)
+
+    def add_control(self, control: FrameworkControl) -> None:
+        """Add a control to this mapping."""
+        self.controls.append(control)
+
+    def has_framework(self, framework: str) -> bool:
+        """Check if any control from a framework is mapped."""
+        return any(c.framework == framework for c in self.controls)
+
+
+@dataclass
+class ComplianceMappingResult:
+    """Result of mapping findings to all frameworks."""
+
+    mappings: list[ComplianceMapping] = field(default_factory=list)
+    framework_summary: dict[str, int] = field(default_factory=dict)
+    unmapped_count: int = 0
+    total_findings: int = 0
+
+    def get_controls_by_framework(self, framework: str) -> list[FrameworkControl]:
+        """Get all unique controls for a framework."""
+        seen: set[str] = set()
+        result: list[FrameworkControl] = []
+        for mapping in self.mappings:
+            for control in mapping.controls:
+                if control.framework == framework and control.control_id not in seen:
+                    seen.add(control.control_id)
+                    result.append(control)
+        return sorted(result, key=lambda c: c.control_id)
+
+    def get_findings_for_control(self, framework: str, control_id: str) -> list[ComplianceMapping]:
+        """Get all findings mapped to a specific control."""
+        return [
+            m
+            for m in self.mappings
+            if any(c.framework == framework and c.control_id == control_id for c in m.controls)
+        ]
+
+
+def map_finding_to_frameworks(finding: Finding) -> ComplianceMapping:
+    """Map a single finding to all applicable compliance frameworks."""
+    from .hipaa import map_to_hipaa
+    from .owasp import map_to_owasp
+    from .owasp_agentic import map_to_owasp_agentic
+    from .pci_dss import map_to_pci_dss
+    from .soc2 import map_to_soc2
+
+    mapping = ComplianceMapping(
+        finding_hash=finding.dedupe_hash(),
+        finding_title=finding.title,
+        finding_severity=finding.severity.value,
+    )
+
+    # Map to each framework
+    for control in map_to_pci_dss(finding):
+        mapping.add_control(control)
+
+    for control in map_to_soc2(finding):
+        mapping.add_control(control)
+
+    for control in map_to_owasp(finding):
+        mapping.add_control(control)
+
+    for control in map_to_owasp_agentic(finding):
+        mapping.add_control(control)
+
+    for control in map_to_hipaa(finding):
+        mapping.add_control(control)
+
+    return mapping
+
+
+def map_findings_to_all_frameworks(
+    findings: Sequence[Finding],
+) -> ComplianceMappingResult:
+    """Map all findings to compliance frameworks."""
+    result = ComplianceMappingResult(total_findings=len(findings))
+
+    framework_counts: dict[str, set[str]] = {
+        "PCI-DSS": set(),
+        "SOC2": set(),
+        "OWASP": set(),
+        "OWASP-Agentic": set(),
+        "HIPAA": set(),
+    }
+
+    for finding in findings:
+        mapping = map_finding_to_frameworks(finding)
+        result.mappings.append(mapping)
+
+        if not mapping.controls:
+            result.unmapped_count += 1
+        else:
+            for control in mapping.controls:
+                if control.framework in framework_counts:
+                    framework_counts[control.framework].add(control.control_id)
+
+    result.framework_summary = {k: len(v) for k, v in framework_counts.items()}
+
+    return result