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

kekkai/compliance/owasp_agentic.py

@@ -0,0 +1,267 @@
+"""OWASP Top 10 for Agentic AI mapping for security findings.
+
+Maps findings to OWASP Agentic AI Top 10 categories based on rule patterns.
+Reference: https://genai.owasp.org/initiatives/agentic-security-initiative/
+
+Released: December 2025 at Black Hat Europe
+
+This framework addresses security risks specific to autonomous AI agents
+that make decisions and take actions in real-world environments.
+"""
+
+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 OWASPAgenticCategory:
+    """OWASP Agentic AI Top 10 category definition."""
+
+    id: str
+    name: str
+    description: str
+    rule_patterns: tuple[str, ...]
+    scanner_types: tuple[str, ...]  # Only apply to these scanner types
+
+
+# OWASP Top 10 for Agentic AI (December 2025)
+OWASP_AGENTIC_TOP_10: dict[str, OWASPAgenticCategory] = {
+    "AA01": OWASPAgenticCategory(
+        id="AA01:2025",
+        name="Agent Goal Hijack",
+        description=(
+            "Attackers alter an agent's objectives through malicious content, "
+            "prompt injection, or manipulated inputs causing the agent to "
+            "act against the user's intent."
+        ),
+        rule_patterns=(
+            "goal-hijack",
+            "prompt-injection",
+            "jailbreak",
+            "objective-manipulation",
+            "instruction-override",
+            "system-prompt",
+        ),
+        scanner_types=("llm", "ai", "genai", "agent", "semgrep"),
+    ),
+    "AA02": OWASPAgenticCategory(
+        id="AA02:2025",
+        name="Tool Misuse and Exploitation",
+        description=(
+            "Agents use legitimate tools in unsafe or unintended ways, "
+            "potentially causing harmful actions through manipulation "
+            "of tool parameters or abuse of tool capabilities."
+        ),
+        rule_patterns=(
+            "tool-misuse",
+            "tool-abuse",
+            "function-call",
+            "api-abuse",
+            "unsafe-tool",
+            "tool-injection",
+        ),
+        scanner_types=("llm", "ai", "genai", "agent", "semgrep"),
+    ),
+    "AA03": OWASPAgenticCategory(
+        id="AA03:2025",
+        name="Identity and Privilege Abuse",
+        description=(
+            "Agents inherit or escalate high-privilege credentials, "
+            "risking unauthorized access to sensitive systems, data, "
+            "or operations beyond their intended scope."
+        ),
+        rule_patterns=(
+            "privilege-escalation",
+            "identity-abuse",
+            "credential-inheritance",
+            "over-privileged",
+            "least-privilege",
+            "agent-permission",
+        ),
+        scanner_types=("llm", "ai", "genai", "agent", "semgrep"),
+    ),
+    "AA04": OWASPAgenticCategory(
+        id="AA04:2025",
+        name="Agentic Supply Chain Vulnerabilities",
+        description=(
+            "Compromised external components, plugins, or third-party "
+            "agents can affect the security and behavior of the entire "
+            "agentic system."
+        ),
+        rule_patterns=(
+            "agent-supply-chain",
+            "plugin-vulnerability",
+            "external-agent",
+            "third-party-agent",
+            "model-supply-chain",
+            "compromised-plugin",
+        ),
+        scanner_types=("llm", "ai", "genai", "agent", "semgrep", "trivy"),
+    ),
+    "AA05": OWASPAgenticCategory(
+        id="AA05:2025",
+        name="Unexpected Code Execution",
+        description=(
+            "Agents generate or execute code unsafely, potentially "
+            "running malicious code, accessing unauthorized resources, "
+            "or causing system compromise."
+        ),
+        rule_patterns=(
+            "code-execution",
+            "code-generation",
+            "unsafe-eval",
+            "dynamic-execution",
+            "sandbox-escape",
+            "code-injection",
+        ),
+        scanner_types=("llm", "ai", "genai", "agent", "semgrep"),
+    ),
+    "AA06": OWASPAgenticCategory(
+        id="AA06:2025",
+        name="Memory and Context Poisoning",
+        description=(
+            "Attackers corrupt an agent's memory systems or context "
+            "window to influence future behavior, decisions, or outputs "
+            "across sessions."
+        ),
+        rule_patterns=(
+            "memory-poisoning",
+            "context-poisoning",
+            "context-manipulation",
+            "memory-injection",
+            "persistent-attack",
+            "rag-poisoning",
+        ),
+        scanner_types=("llm", "ai", "genai", "agent"),
+    ),
+    "AA07": OWASPAgenticCategory(
+        id="AA07:2025",
+        name="Insecure Inter-Agent Communication",
+        description=(
+            "Risks of spoofing, tampering, and man-in-the-middle attacks "
+            "in multi-agent systems due to weak authentication or "
+            "encryption between agents."
+        ),
+        rule_patterns=(
+            "inter-agent",
+            "multi-agent",
+            "agent-communication",
+            "agent-spoofing",
+            "agent-tampering",
+            "agent-auth",
+        ),
+        scanner_types=("llm", "ai", "genai", "agent"),
+    ),
+    "AA08": OWASPAgenticCategory(
+        id="AA08:2025",
+        name="Cascading Failures",
+        description=(
+            "Small errors or failures in one part of an agentic system "
+            "can propagate and cause larger, widespread failures across "
+            "the entire system."
+        ),
+        rule_patterns=(
+            "cascading-failure",
+            "error-propagation",
+            "fault-tolerance",
+            "failure-isolation",
+            "circuit-breaker",
+            "retry-storm",
+        ),
+        scanner_types=("llm", "ai", "genai", "agent", "semgrep"),
+    ),
+    "AA09": OWASPAgenticCategory(
+        id="AA09:2025",
+        name="Human-Agent Trust Exploitation",
+        description=(
+            "Users place excessive trust in agent recommendations, "
+            "leading to social engineering attacks, manipulation, "
+            "or harmful decisions based on agent outputs."
+        ),
+        rule_patterns=(
+            "trust-exploitation",
+            "over-trust",
+            "social-engineering",
+            "manipulation",
+            "deception",
+            "human-override",
+        ),
+        scanner_types=("llm", "ai", "genai", "agent"),
+    ),
+    "AA10": OWASPAgenticCategory(
+        id="AA10:2025",
+        name="Rogue Agents",
+        description=(
+            "Compromised agents act maliciously while appearing legitimate, "
+            "potentially exfiltrating data, causing damage, or subverting "
+            "system controls."
+        ),
+        rule_patterns=(
+            "rogue-agent",
+            "compromised-agent",
+            "malicious-agent",
+            "agent-takeover",
+            "agent-backdoor",
+            "agent-exfiltration",
+        ),
+        scanner_types=("llm", "ai", "genai", "agent"),
+    ),
+}
+
+
+def map_to_owasp_agentic(finding: Finding) -> list[FrameworkControl]:
+    """Map a finding to OWASP Agentic AI Top 10 categories.
+
+    Agentic AI mappings are primarily pattern-based since there are
+    few established CWEs for these emerging risks. Mappings are also
+    filtered by scanner type to avoid false positives.
+    """
+    controls: list[FrameworkControl] = []
+
+    # Check rule_id patterns
+    rule_id_lower = (finding.rule_id or "").lower()
+    title_lower = finding.title.lower()
+    description_lower = finding.description.lower()
+    scanner_lower = finding.scanner.lower()
+
+    for category in OWASP_AGENTIC_TOP_10.values():
+        matched = False
+
+        # Check if scanner type is relevant for this category
+        scanner_relevant = any(st in scanner_lower for st in category.scanner_types)
+
+        # For generic scanners like semgrep, also check if the finding
+        # is related to AI/LLM based on content
+        if not scanner_relevant:
+            ai_keywords = ("llm", "agent", "ai", "model", "prompt", "genai")
+            if any(kw in title_lower or kw in description_lower for kw in ai_keywords):
+                scanner_relevant = True
+
+        if not scanner_relevant:
+            continue
+
+        # Match by rule pattern
+        for pattern in category.rule_patterns:
+            if pattern in rule_id_lower or pattern in title_lower or pattern in description_lower:
+                matched = True
+                break
+
+        if matched:
+            controls.append(
+                FrameworkControl(
+                    framework="OWASP-Agentic",
+                    control_id=category.id,
+                    title=category.name,
+                    description=category.description,
+                    requirement_level="required",
+                )
+            )
+
+    return controls

kekkai/compliance/pci_dss.py

@@ -0,0 +1,205 @@
+"""PCI-DSS v4.0 control mapping for security findings.
+
+Maps findings to PCI-DSS requirements based on CWE IDs and rule patterns.
+Reference: https://docs-prv.pcisecuritystandards.org/PCI%20DSS/Standard/PCI-DSS-v4_0.pdf
+"""
+
+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 PCIDSSControl:
+    """PCI-DSS v4.0 control definition."""
+
+    id: str
+    title: str
+    description: str
+    cwes: frozenset[int]
+    rule_patterns: tuple[str, ...]
+
+
+# PCI-DSS v4.0 Requirements relevant to application security
+PCI_DSS_CONTROLS: dict[str, PCIDSSControl] = {
+    "1.4": PCIDSSControl(
+        id="1.4",
+        title="Network connections between trusted and untrusted networks are controlled",
+        description=(
+            "System components that store, process, or transmit CHD are not "
+            "directly accessible from untrusted networks"
+        ),
+        cwes=frozenset({918, 441}),  # SSRF, open redirect
+        rule_patterns=("ssrf", "network", "firewall"),
+    ),
+    "2.2.6": PCIDSSControl(
+        id="2.2.6",
+        title="System security parameters prevent misuse",
+        description="Common security parameter settings are correctly configured",
+        cwes=frozenset({16, 260, 315, 520, 756}),
+        rule_patterns=("misconfiguration", "config", "security-parameter", "hardcoded"),
+    ),
+    "3.5": PCIDSSControl(
+        id="3.5",
+        title="Primary account number (PAN) is secured wherever stored",
+        description="PAN is rendered unreadable using strong cryptography",
+        cwes=frozenset({311, 312, 319, 327, 328}),
+        rule_patterns=("encryption", "crypto", "storage", "pan", "card"),
+    ),
+    "4.2": PCIDSSControl(
+        id="4.2",
+        title="PAN is protected during transmission",
+        description=(
+            "Strong cryptography protects PAN during transmission over open, public networks"
+        ),
+        cwes=frozenset({319, 523, 757}),
+        rule_patterns=("tls", "ssl", "transmission", "transport"),
+    ),
+    "5.2": PCIDSSControl(
+        id="5.2",
+        title="Malicious software is prevented or detected and addressed",
+        description="Anti-malware solutions detect and address malicious software",
+        cwes=frozenset({94, 502, 829}),  # code injection, deserialization, untrusted code
+        rule_patterns=("malware", "code-injection", "deserialization"),
+    ),
+    "6.2.4": PCIDSSControl(
+        id="6.2.4",
+        title="Software engineering techniques prevent or mitigate common attacks",
+        description=(
+            "Injection attacks, buffer overflows, insecure cryptographic "
+            "storage, etc. are prevented"
+        ),
+        cwes=frozenset({20, 74, 77, 78, 79, 89, 90, 91, 94, 120, 134, 190}),
+        rule_patterns=("injection", "sqli", "xss", "buffer", "overflow"),
+    ),
+    "6.3.1": PCIDSSControl(
+        id="6.3.1",
+        title="Security vulnerabilities are identified and managed",
+        description=(
+            "A process is defined for identifying security vulnerabilities "
+            "using reputable external sources"
+        ),
+        cwes=frozenset({937, 1035, 1104}),
+        rule_patterns=("cve-", "vulnerability", "outdated", "component"),
+    ),
+    "6.3.2": PCIDSSControl(
+        id="6.3.2",
+        title="An inventory of custom and third-party software is maintained",
+        description="Software inventory including components and dependencies",
+        cwes=frozenset({1104}),
+        rule_patterns=("dependency", "component", "sbom"),
+    ),
+    "6.5.1": PCIDSSControl(
+        id="6.5.1",
+        title="Changes to production systems follow change control procedures",
+        description="Development and test environments are separate from production",
+        cwes=frozenset({489, 540}),  # debug code, sensitive info exposure
+        rule_patterns=("debug", "development", "test-code"),
+    ),
+    "6.5.2": PCIDSSControl(
+        id="6.5.2",
+        title="Live PANs are not used in pre-production environments",
+        description="Test data does not contain live PAN or sensitive auth data",
+        cwes=frozenset({200, 312}),
+        rule_patterns=("test-data", "sensitive-data", "pii"),
+    ),
+    "6.5.4": PCIDSSControl(
+        id="6.5.4",
+        title="Roles and functions are separated between production and pre-production",
+        description="Separation of duties between environments",
+        cwes=frozenset({269, 284}),
+        rule_patterns=("privilege", "separation", "access-control"),
+    ),
+    "7.2": PCIDSSControl(
+        id="7.2",
+        title="Access to system components and data is appropriately defined",
+        description="Role-based access control limits access based on need-to-know",
+        cwes=frozenset({264, 284, 285, 639, 862, 863}),
+        rule_patterns=("access-control", "authorization", "rbac", "idor"),
+    ),
+    "8.3": PCIDSSControl(
+        id="8.3",
+        title="Strong authentication for users and administrators",
+        description="MFA and strong password requirements",
+        cwes=frozenset({255, 259, 287, 307, 521, 640, 798}),
+        rule_patterns=("authentication", "password", "credential", "mfa", "hardcoded-password"),
+    ),
+    "8.6": PCIDSSControl(
+        id="8.6",
+        title="Use of application and system accounts is strictly managed",
+        description="Shared and service accounts are managed securely",
+        cwes=frozenset({250, 269, 522}),
+        rule_patterns=("service-account", "shared-credential", "privilege"),
+    ),
+    "10.3": PCIDSSControl(
+        id="10.3",
+        title="Audit logs are protected from destruction and unauthorized modifications",
+        description="Audit trail records cannot be altered",
+        cwes=frozenset({117, 532, 778}),
+        rule_patterns=("logging", "audit", "log-injection", "log-tampering"),
+    ),
+    "11.3.1": PCIDSSControl(
+        id="11.3.1",
+        title="External and internal vulnerabilities are managed",
+        description="Vulnerability scans performed at least quarterly",
+        cwes=frozenset({937}),
+        rule_patterns=("vulnerability", "scan"),
+    ),
+}
+
+
+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_pci_dss(finding: Finding) -> list[FrameworkControl]:
+    """Map a finding to PCI-DSS v4.0 controls."""
+    controls: list[FrameworkControl] = []
+
+    cwe_id = _extract_cwe_id(finding.cwe)
+    rule_id_lower = (finding.rule_id or "").lower()
+    title_lower = finding.title.lower()
+
+    for control in PCI_DSS_CONTROLS.values():
+        matched = False
+
+        # Match by CWE
+        if cwe_id and cwe_id in control.cwes:
+            matched = True
+
+        # Match by rule pattern
+        if not matched:
+            for pattern in control.rule_patterns:
+                if pattern in rule_id_lower or pattern in title_lower:
+                    matched = True
+                    break
+
+        # Special case: CVEs map to 6.3.1 (vulnerability management)
+        if not matched and control.id == "6.3.1" and finding.cve:
+            matched = True
+
+        if matched:
+            controls.append(
+                FrameworkControl(
+                    framework="PCI-DSS",
+                    control_id=control.id,
+                    title=control.title,
+                    description=control.description,
+                    requirement_level="required",
+                )
+            )
+
+    return controls

kekkai/compliance/soc2.py

@@ -0,0 +1,209 @@
+"""SOC 2 Type II criteria mapping for security findings.
+
+Maps findings to SOC 2 Trust Services Criteria based on CWE IDs and rule patterns.
+Reference: https://www.aicpa.org/resources/landing/trust-services-criteria
+"""
+
+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 SOC2Criterion:
+    """SOC 2 Trust Services Criterion definition."""
+
+    id: str
+    title: str
+    description: str
+    category: str  # Security, Availability, Processing Integrity, Confidentiality, Privacy
+    cwes: frozenset[int]
+    rule_patterns: tuple[str, ...]
+
+
+# SOC 2 Trust Services Criteria relevant to application security
+SOC2_CRITERIA: dict[str, SOC2Criterion] = {
+    # Security (Common Criteria)
+    "CC6.1": SOC2Criterion(
+        id="CC6.1",
+        title="Logical and Physical Access Controls",
+        description=(
+            "The entity implements logical access security software, "
+            "infrastructure, and architectures to protect against threats"
+        ),
+        category="Security",
+        cwes=frozenset({264, 284, 285, 287, 306, 639, 862, 863}),
+        rule_patterns=("access-control", "authorization", "authentication", "idor"),
+    ),
+    "CC6.2": SOC2Criterion(
+        id="CC6.2",
+        title="User Registration and Authorization",
+        description="Prior to issuing system credentials, users are registered and authorized",
+        category="Security",
+        cwes=frozenset({287, 288, 302, 307, 521}),
+        rule_patterns=("registration", "user-management", "credential"),
+    ),
+    "CC6.3": SOC2Criterion(
+        id="CC6.3",
+        title="Credential Lifecycle Management",
+        description="The entity authorizes, modifies, or removes access based on roles",
+        category="Security",
+        cwes=frozenset({255, 259, 269, 522, 613, 640, 798}),
+        rule_patterns=("credential", "password", "session", "privilege"),
+    ),
+    "CC6.6": SOC2Criterion(
+        id="CC6.6",
+        title="Security Events Detection",
+        description="The entity implements controls to prevent, detect, and act on security events",
+        category="Security",
+        cwes=frozenset({117, 223, 532, 778}),
+        rule_patterns=("logging", "monitoring", "detection", "audit"),
+    ),
+    "CC6.7": SOC2Criterion(
+        id="CC6.7",
+        title="Transmission Protection",
+        description=(
+            "The entity restricts transmission of confidential information "
+            "over communication channels"
+        ),
+        category="Security",
+        cwes=frozenset({319, 523, 757}),
+        rule_patterns=("tls", "ssl", "encryption", "transmission"),
+    ),
+    "CC6.8": SOC2Criterion(
+        id="CC6.8",
+        title="Malicious Software Prevention",
+        description="The entity implements controls to prevent or detect malicious software",
+        category="Security",
+        cwes=frozenset({94, 502, 829}),
+        rule_patterns=("malware", "injection", "deserialization"),
+    ),
+    "CC7.1": SOC2Criterion(
+        id="CC7.1",
+        title="Vulnerability Management",
+        description=(
+            "The entity uses detection and monitoring procedures to identify vulnerabilities"
+        ),
+        category="Security",
+        cwes=frozenset({937, 1035, 1104}),
+        rule_patterns=("vulnerability", "cve-", "outdated", "component"),
+    ),
+    "CC7.2": SOC2Criterion(
+        id="CC7.2",
+        title="Security Incident Response",
+        description=(
+            "The entity monitors system components for anomalies indicative of malicious acts"
+        ),
+        category="Security",
+        cwes=frozenset({778, 779}),
+        rule_patterns=("incident", "response", "anomaly"),
+    ),
+    "CC8.1": SOC2Criterion(
+        id="CC8.1",
+        title="Change Management",
+        description="The entity authorizes, designs, develops, configures, and implements changes",
+        category="Security",
+        cwes=frozenset({489, 540}),
+        rule_patterns=("change-management", "deployment", "debug"),
+    ),
+    # Confidentiality
+    "C1.1": SOC2Criterion(
+        id="C1.1",
+        title="Confidential Information Identification",
+        description="The entity identifies and maintains confidential information",
+        category="Confidentiality",
+        cwes=frozenset({200, 201, 312, 319, 359}),
+        rule_patterns=("sensitive-data", "pii", "secret", "confidential"),
+    ),
+    "C1.2": SOC2Criterion(
+        id="C1.2",
+        title="Confidential Information Disposal",
+        description="The entity disposes of confidential information to meet objectives",
+        category="Confidentiality",
+        cwes=frozenset({226, 312, 459}),
+        rule_patterns=("disposal", "cleanup", "retention"),
+    ),
+    # Processing Integrity
+    "PI1.2": SOC2Criterion(
+        id="PI1.2",
+        title="Input Validation",
+        description="The entity implements policies to verify input is complete and accurate",
+        category="Processing Integrity",
+        cwes=frozenset({20, 74, 77, 78, 79, 89, 91, 94}),
+        rule_patterns=("validation", "input", "injection", "xss", "sqli"),
+    ),
+    "PI1.4": SOC2Criterion(
+        id="PI1.4",
+        title="Output Validation",
+        description="The entity implements policies to verify output is complete and accurate",
+        category="Processing Integrity",
+        cwes=frozenset({79, 116}),
+        rule_patterns=("output", "encoding", "xss"),
+    ),
+    # Availability
+    "A1.2": SOC2Criterion(
+        id="A1.2",
+        title="System Recovery",
+        description="The entity implements policies to support system recovery",
+        category="Availability",
+        cwes=frozenset({400, 770}),  # resource exhaustion
+        rule_patterns=("dos", "resource", "availability", "recovery"),
+    ),
+}
+
+
+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_soc2(finding: Finding) -> list[FrameworkControl]:
+    """Map a finding to SOC 2 criteria."""
+    controls: list[FrameworkControl] = []
+
+    cwe_id = _extract_cwe_id(finding.cwe)
+    rule_id_lower = (finding.rule_id or "").lower()
+    title_lower = finding.title.lower()
+
+    for criterion in SOC2_CRITERIA.values():
+        matched = False
+
+        # Match by CWE
+        if cwe_id and cwe_id in criterion.cwes:
+            matched = True
+
+        # Match by rule pattern
+        if not matched:
+            for pattern in criterion.rule_patterns:
+                if pattern in rule_id_lower or pattern in title_lower:
+                    matched = True
+                    break
+
+        # CVEs map to CC7.1 (vulnerability management)
+        if not matched and criterion.id == "CC7.1" and finding.cve:
+            matched = True
+
+        if matched:
+            controls.append(
+                FrameworkControl(
+                    framework="SOC2",
+                    control_id=criterion.id,
+                    title=criterion.title,
+                    description=criterion.description,
+                    requirement_level="required",
+                )
+            )
+
+    return controls