codepathfinder 1.2.0__py3-none-manylinux_2_17_aarch64.whl

rules/__init__.py

@@ -0,0 +1,36 @@
+"""Container security rules DSL for Dockerfile and docker-compose."""
+
+from .container_decorators import dockerfile_rule, compose_rule
+from .container_matchers import instruction, missing, service_has, service_missing
+from .container_ir import compile_all_rules, compile_to_json
+from .container_combinators import (
+    all_of,
+    any_of,
+    none_of,
+    instruction_after,
+    instruction_before,
+    stage,
+    final_stage_has,
+)
+from .container_programmatic import custom_check, DockerfileAccess, ComposeAccess
+
+__all__ = [
+    "dockerfile_rule",
+    "compose_rule",
+    "instruction",
+    "missing",
+    "service_has",
+    "service_missing",
+    "compile_all_rules",
+    "compile_to_json",
+    "all_of",
+    "any_of",
+    "none_of",
+    "instruction_after",
+    "instruction_before",
+    "stage",
+    "final_stage_has",
+    "custom_check",
+    "DockerfileAccess",
+    "ComposeAccess",
+]

rules/container_combinators.py

@@ -0,0 +1,209 @@
+"""
+Logic combinators for container rules.
+"""
+
+from typing import List, Dict, Any, Union, Callable
+from dataclasses import dataclass, field
+from .container_matchers import Matcher
+
+
+@dataclass
+class CombinatorMatcher:
+    """Represents a logic combinator (AND, OR, NOT)."""
+
+    combinator_type: str  # "all_of", "any_of", "none_of"
+    conditions: List[Union[Matcher, "CombinatorMatcher", Dict, Callable]]
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to JSON IR."""
+        serialized_conditions = []
+        for cond in self.conditions:
+            if hasattr(cond, "to_dict"):
+                serialized_conditions.append(cond.to_dict())
+            elif isinstance(cond, dict):
+                serialized_conditions.append(cond)
+            elif callable(cond):
+                serialized_conditions.append(
+                    {"type": "custom_function", "has_callable": True}
+                )
+            else:
+                serialized_conditions.append(cond)
+
+        return {"type": self.combinator_type, "conditions": serialized_conditions}
+
+
+def all_of(*conditions: Union[Matcher, Dict, Callable]) -> CombinatorMatcher:
+    """
+    Combine matchers with AND logic.
+    All conditions must match for the rule to trigger.
+
+    Example:
+        all_of(
+            instruction(type="FROM", image_tag="latest"),
+            missing(instruction="USER"),
+            instruction(type="RUN", contains="sudo")
+        )
+    """
+    return CombinatorMatcher(combinator_type="all_of", conditions=list(conditions))
+
+
+def any_of(*conditions: Union[Matcher, Dict, Callable]) -> CombinatorMatcher:
+    """
+    Combine matchers with OR logic.
+    Any condition can match for the rule to trigger.
+
+    Example:
+        any_of(
+            instruction(type="USER", user_name="root"),
+            missing(instruction="USER"),
+            instruction(type="FROM", base_image="scratch")
+        )
+    """
+    return CombinatorMatcher(combinator_type="any_of", conditions=list(conditions))
+
+
+def none_of(*conditions: Union[Matcher, Dict, Callable]) -> CombinatorMatcher:
+    """
+    Combine matchers with NOT logic.
+    None of the conditions should match for the rule to pass.
+    (Inverse: if any matches, rule triggers as violation)
+
+    Example:
+        none_of(
+            instruction(type="HEALTHCHECK"),
+            instruction(type="USER", user_name_not="root")
+        )
+    """
+    return CombinatorMatcher(combinator_type="none_of", conditions=list(conditions))
+
+
+@dataclass
+class SequenceMatcher:
+    """Represents instruction sequence validation."""
+
+    sequence_type: str  # "after" or "before"
+    instruction: Union[str, Matcher, Dict]
+    reference: Union[str, Matcher, Dict]
+    not_followed_by: bool = False
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to JSON IR."""
+
+        def serialize_ref(ref):
+            if isinstance(ref, str):
+                return {"instruction": ref}
+            elif hasattr(ref, "to_dict"):
+                return ref.to_dict()
+            elif isinstance(ref, dict):
+                return ref
+            return ref
+
+        return {
+            "type": f"instruction_{self.sequence_type}",
+            "instruction": serialize_ref(self.instruction),
+            "reference": serialize_ref(self.reference),
+            "not_followed_by": self.not_followed_by,
+        }
+
+
+def instruction_after(
+    instruction: Union[str, Matcher],
+    after: Union[str, Matcher],
+    not_followed_by: bool = False,
+) -> SequenceMatcher:
+    """
+    Check that an instruction appears after another.
+
+    Example:
+        # Ensure CMD comes after USER
+        instruction_after(instruction="CMD", after="USER")
+
+        # Ensure apt-get install follows apt-get update
+        instruction_after(
+            instruction=instruction(type="RUN", contains="apt-get install"),
+            after=instruction(type="RUN", contains="apt-get update")
+        )
+    """
+    return SequenceMatcher(
+        sequence_type="after",
+        instruction=instruction,
+        reference=after,
+        not_followed_by=not_followed_by,
+    )
+
+
+def instruction_before(
+    instruction: Union[str, Matcher],
+    before: Union[str, Matcher],
+    not_followed_by: bool = False,
+) -> SequenceMatcher:
+    """
+    Check that an instruction appears before another.
+
+    Example:
+        instruction_before(instruction="USER", before="CMD")
+    """
+    return SequenceMatcher(
+        sequence_type="before",
+        instruction=instruction,
+        reference=before,
+        not_followed_by=not_followed_by,
+    )
+
+
+@dataclass
+class StageMatcher:
+    """Matcher for multi-stage build stage queries."""
+
+    stage_type: str
+    params: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": f"stage_{self.stage_type}", **self.params}
+
+
+def stage(
+    alias: str = None,
+    base_image: str = None,
+    is_final: bool = None,
+) -> StageMatcher:
+    """
+    Query a specific build stage.
+
+    Example:
+        stage(alias="builder")
+        stage(is_final=True)
+        stage(base_image="alpine")
+    """
+    params = {}
+    if alias is not None:
+        params["alias"] = alias
+    if base_image is not None:
+        params["base_image"] = base_image
+    if is_final is not None:
+        params["is_final"] = is_final
+
+    return StageMatcher(stage_type="query", params=params)
+
+
+def final_stage_has(
+    instruction: Union[str, Matcher] = None,
+    missing_instruction: str = None,
+) -> StageMatcher:
+    """
+    Check properties of the final build stage.
+
+    Example:
+        final_stage_has(missing_instruction="USER")
+        final_stage_has(instruction=instruction(type="USER", user_name="root"))
+    """
+    params = {}
+    if instruction is not None:
+        if isinstance(instruction, str):
+            params["instruction"] = instruction
+        elif hasattr(instruction, "to_dict"):
+            params["instruction"] = instruction.to_dict()
+    if missing_instruction is not None:
+        params["missing_instruction"] = missing_instruction
+
+    return StageMatcher(stage_type="final_has", params=params)

rules/container_decorators.py

@@ -0,0 +1,223 @@
+"""
+Decorators for Dockerfile and docker-compose rules.
+"""
+
+import atexit
+import json
+import sys
+from typing import Callable, Dict, Any, List
+from dataclasses import dataclass
+
+
+@dataclass
+class RuleMetadata:
+    """Metadata for a container security rule."""
+
+    id: str
+    name: str = ""
+    severity: str = "MEDIUM"
+    category: str = "security"
+    cwe: str = ""
+    cve: str = ""
+    tags: str = ""
+    message: str = ""
+    file_pattern: str = ""
+
+
+@dataclass
+class DockerfileRuleDefinition:
+    """Complete definition of a Dockerfile rule."""
+
+    metadata: RuleMetadata
+    matcher: Dict[str, Any]
+    rule_function: Callable
+
+
+@dataclass
+class ComposeRuleDefinition:
+    """Complete definition of a docker-compose rule."""
+
+    metadata: RuleMetadata
+    matcher: Dict[str, Any]
+    rule_function: Callable
+
+
+# Global registries
+_dockerfile_rules: List[DockerfileRuleDefinition] = []
+_compose_rules: List[ComposeRuleDefinition] = []
+_auto_execute_enabled = False
+
+
+def _enable_auto_execute() -> None:
+    """
+    Enable automatic rule compilation and output when script ends.
+
+    This provides consistent behavior with code analysis rules -
+    no __main__ block needed.
+    """
+    global _auto_execute_enabled
+    if _auto_execute_enabled:
+        return
+
+    _auto_execute_enabled = True
+
+    def _output_rules():
+        """Output all container rules as JSON when script ends."""
+        if not _dockerfile_rules and not _compose_rules:
+            return
+
+        # Compile rules to JSON IR format
+        from . import container_ir
+
+        compiled = container_ir.compile_all_rules()
+
+        # Output to stdout for Go loader to capture
+        print(json.dumps(compiled))
+
+    # Register cleanup handler
+    atexit.register(_output_rules)
+
+
+def _register_rule() -> None:
+    """
+    Check if auto-execution should be enabled when a rule is registered.
+
+    Enables auto-execution if the module is being executed directly (not imported).
+    """
+    # Check if module is being executed directly
+    frame = sys._getframe(2)  # Get caller's frame (the module defining the rule)
+    if frame.f_globals.get("__name__") == "__main__":
+        _enable_auto_execute()
+
+
+def dockerfile_rule(
+    id: str,
+    name: str = "",
+    severity: str = "MEDIUM",
+    category: str = "security",
+    cwe: str = "",
+    cve: str = "",
+    tags: str = "",
+    message: str = "",
+) -> Callable:
+    """
+    Decorator for Dockerfile security rules.
+
+    Example:
+        @dockerfile_rule(id="DOCKER-001", severity="HIGH", cwe="CWE-250",
+                        tags="security,docker,privilege-escalation")
+        def container_runs_as_root():
+            return missing(instruction="USER")
+    """
+
+    def decorator(func: Callable) -> Callable:
+        # Get matcher from function
+        matcher_result = func()
+
+        # Convert to dict if it's a Matcher object
+        if hasattr(matcher_result, "to_dict"):
+            matcher_dict = matcher_result.to_dict()
+        elif isinstance(matcher_result, dict):
+            matcher_dict = matcher_result
+        else:
+            raise ValueError(f"Rule {id} must return a matcher or dict")
+
+        # Create rule definition
+        metadata = RuleMetadata(
+            id=id,
+            name=name or func.__name__.replace("_", " ").title(),
+            severity=severity,
+            category=category,
+            cwe=cwe,
+            cve=cve,
+            tags=tags,
+            message=message or f"Security issue detected by {id}",
+            file_pattern="Dockerfile*",
+        )
+
+        rule_def = DockerfileRuleDefinition(
+            metadata=metadata,
+            matcher=matcher_dict,
+            rule_function=func,
+        )
+
+        _dockerfile_rules.append(rule_def)
+        _register_rule()  # Enable auto-execution if running as script
+
+        # Return original function (can be called for testing)
+        return func
+
+    return decorator
+
+
+def compose_rule(
+    id: str,
+    name: str = "",
+    severity: str = "MEDIUM",
+    category: str = "security",
+    cwe: str = "",
+    cve: str = "",
+    tags: str = "",
+    message: str = "",
+) -> Callable:
+    """
+    Decorator for docker-compose security rules.
+
+    Example:
+        @compose_rule(id="COMPOSE-001", severity="HIGH", cwe="CWE-250",
+                     tags="security,docker-compose,privilege-escalation")
+        def privileged_service():
+            return service_has(key="privileged", equals=True)
+    """
+
+    def decorator(func: Callable) -> Callable:
+        matcher_result = func()
+
+        if hasattr(matcher_result, "to_dict"):
+            matcher_dict = matcher_result.to_dict()
+        elif isinstance(matcher_result, dict):
+            matcher_dict = matcher_result
+        else:
+            raise ValueError(f"Rule {id} must return a matcher or dict")
+
+        metadata = RuleMetadata(
+            id=id,
+            name=name or func.__name__.replace("_", " ").title(),
+            severity=severity,
+            category=category,
+            cwe=cwe,
+            cve=cve,
+            tags=tags,
+            message=message or f"Security issue detected by {id}",
+            file_pattern="**/docker-compose*.yml",
+        )
+
+        rule_def = ComposeRuleDefinition(
+            metadata=metadata,
+            matcher=matcher_dict,
+            rule_function=func,
+        )
+
+        _compose_rules.append(rule_def)
+        _register_rule()  # Enable auto-execution if running as script
+
+        return func
+
+    return decorator
+
+
+def get_dockerfile_rules() -> List[DockerfileRuleDefinition]:
+    """Get all registered Dockerfile rules."""
+    return _dockerfile_rules.copy()
+
+
+def get_compose_rules() -> List[ComposeRuleDefinition]:
+    """Get all registered docker-compose rules."""
+    return _compose_rules.copy()
+
+
+def clear_rules():
+    """Clear all registered rules (for testing)."""
+    global _dockerfile_rules, _compose_rules
+    _dockerfile_rules = []
+    _compose_rules = []

rules/container_ir.py

@@ -0,0 +1,104 @@
+"""
+JSON IR (Intermediate Representation) compiler for container rules.
+"""
+
+import json
+from typing import List, Dict, Any
+
+from .container_decorators import (
+    get_dockerfile_rules,
+    get_compose_rules,
+)
+
+
+def compile_dockerfile_rules() -> List[Dict[str, Any]]:
+    """
+    Compile all Dockerfile rules to JSON IR.
+
+    Returns list of rule definitions ready for Go executor.
+    """
+    rules = get_dockerfile_rules()
+    compiled = []
+
+    for rule in rules:
+        ir = {
+            "id": rule.metadata.id,
+            "name": rule.metadata.name,
+            "severity": rule.metadata.severity,
+            "category": rule.metadata.category,
+            "cwe": rule.metadata.cwe,
+            "message": rule.metadata.message,
+            "file_pattern": rule.metadata.file_pattern,
+            "rule_type": "dockerfile",
+            "matcher": rule.matcher,
+        }
+        compiled.append(ir)
+
+    return compiled
+
+
+def compile_compose_rules() -> List[Dict[str, Any]]:
+    """
+    Compile all docker-compose rules to JSON IR.
+
+    Returns list of rule definitions ready for Go executor.
+    """
+    rules = get_compose_rules()
+    compiled = []
+
+    for rule in rules:
+        ir = {
+            "id": rule.metadata.id,
+            "name": rule.metadata.name,
+            "severity": rule.metadata.severity,
+            "category": rule.metadata.category,
+            "cwe": rule.metadata.cwe,
+            "message": rule.metadata.message,
+            "file_pattern": rule.metadata.file_pattern,
+            "rule_type": "compose",
+            "matcher": rule.matcher,
+        }
+        compiled.append(ir)
+
+    return compiled
+
+
+def compile_all_rules() -> Dict[str, List[Dict[str, Any]]]:
+    """
+    Compile all container rules to JSON IR.
+
+    Returns dict with 'dockerfile' and 'compose' rule lists.
+    """
+    return {
+        "dockerfile": compile_dockerfile_rules(),
+        "compose": compile_compose_rules(),
+    }
+
+
+def compile_to_json(pretty: bool = True) -> str:
+    """
+    Compile all rules to JSON string.
+
+    Args:
+        pretty: If True, format with indentation.
+
+    Returns:
+        JSON string of all compiled rules.
+    """
+    compiled = compile_all_rules()
+    if pretty:
+        return json.dumps(compiled, indent=2)
+    return json.dumps(compiled)
+
+
+def write_ir_file(filepath: str, pretty: bool = True):
+    """
+    Write compiled rules to JSON file.
+
+    Args:
+        filepath: Output file path.
+        pretty: If True, format with indentation.
+    """
+    json_str = compile_to_json(pretty=pretty)
+    with open(filepath, "w") as f:
+        f.write(json_str)