codepathfinder 1.2.0__py3-none-manylinux_2_17_aarch64.whl

codepathfinder/ir.py

@@ -0,0 +1,107 @@
+"""
+JSON Intermediate Representation (IR) for pathfinder DSL.
+
+The Python DSL serializes to JSON IR, which the Go executor consumes.
+This enables language-agnostic pattern definitions (future: JS, Rust DSLs).
+"""
+
+from enum import Enum
+from typing import Any, Dict, Protocol
+
+
+class IRType(Enum):
+    """IR node types for different matchers and combinators."""
+
+    CALL_MATCHER = "call_matcher"
+    VARIABLE_MATCHER = "variable_matcher"
+    DATAFLOW = "dataflow"  # Coming in PR #3
+    LOGIC_AND = "logic_and"  # Coming in PR #5
+    LOGIC_OR = "logic_or"  # Coming in PR #5
+    LOGIC_NOT = "logic_not"  # Coming in PR #5
+
+
+class MatcherIR(Protocol):
+    """Protocol for all matcher types (duck typing)."""
+
+    def to_ir(self) -> Dict[str, Any]:
+        """Serialize to JSON IR dictionary."""
+        ...
+
+
+def serialize_ir(matcher: MatcherIR) -> Dict[str, Any]:
+    """
+    Serialize any matcher to JSON IR.
+
+    Args:
+        matcher: Any object implementing MatcherIR protocol
+
+    Returns:
+        JSON-serializable dictionary
+
+    Raises:
+        AttributeError: If matcher doesn't implement to_ir()
+    """
+    if not hasattr(matcher, "to_ir"):
+        raise AttributeError(f"{type(matcher).__name__} must implement to_ir() method")
+
+    return matcher.to_ir()
+
+
+def validate_ir(ir: Dict[str, Any]) -> bool:
+    """
+    Validate JSON IR structure.
+
+    Args:
+        ir: JSON IR dictionary
+
+    Returns:
+        True if valid, False otherwise
+
+    Validates:
+        - "type" field exists and is valid IRType
+        - Required fields present for each type
+    """
+    if "type" not in ir:
+        return False
+
+    try:
+        ir_type = IRType(ir["type"])
+    except ValueError:
+        return False
+
+    # Type-specific validation
+    if ir_type == IRType.CALL_MATCHER:
+        return (
+            "patterns" in ir
+            and isinstance(ir["patterns"], list)
+            and len(ir["patterns"]) > 0
+            and "wildcard" in ir
+            and isinstance(ir["wildcard"], bool)
+        )
+
+    if ir_type == IRType.VARIABLE_MATCHER:
+        return (
+            "pattern" in ir
+            and isinstance(ir["pattern"], str)
+            and len(ir["pattern"]) > 0
+            and "wildcard" in ir
+            and isinstance(ir["wildcard"], bool)
+        )
+
+    if ir_type == IRType.DATAFLOW:
+        return (
+            "sources" in ir
+            and isinstance(ir["sources"], list)
+            and len(ir["sources"]) > 0
+            and "sinks" in ir
+            and isinstance(ir["sinks"], list)
+            and len(ir["sinks"]) > 0
+            and "sanitizers" in ir
+            and isinstance(ir["sanitizers"], list)
+            and "propagation" in ir
+            and isinstance(ir["propagation"], list)
+            and "scope" in ir
+            and ir["scope"] in ["local", "global"]
+        )
+
+    return True

codepathfinder/logic.py

@@ -0,0 +1,101 @@
+"""Logic operators for combining matchers."""
+
+from typing import Union
+from .matchers import CallMatcher, VariableMatcher
+from .dataflow import DataflowMatcher
+from .ir import IRType
+
+MatcherType = Union[
+    CallMatcher,
+    VariableMatcher,
+    DataflowMatcher,
+    "AndOperator",
+    "OrOperator",
+    "NotOperator",
+]
+
+
+class AndOperator:
+    """
+    Logical AND - all matchers must match.
+
+    Example:
+        And(calls("eval"), variable("user_input"))
+        # Matches code that has BOTH eval calls AND user_input variable
+    """
+
+    def __init__(self, *matchers: MatcherType):
+        if len(matchers) < 2:
+            raise ValueError("And() requires at least 2 matchers")
+        self.matchers = list(matchers)
+
+    def to_ir(self) -> dict:
+        return {
+            "type": IRType.LOGIC_AND.value,
+            "matchers": [m.to_ir() for m in self.matchers],
+        }
+
+    def __repr__(self) -> str:
+        return f"And({len(self.matchers)} matchers)"
+
+
+class OrOperator:
+    """
+    Logical OR - at least one matcher must match.
+
+    Example:
+        Or(calls("eval"), calls("exec"))
+        # Matches code with eval OR exec
+    """
+
+    def __init__(self, *matchers: MatcherType):
+        if len(matchers) < 2:
+            raise ValueError("Or() requires at least 2 matchers")
+        self.matchers = list(matchers)
+
+    def to_ir(self) -> dict:
+        return {
+            "type": IRType.LOGIC_OR.value,
+            "matchers": [m.to_ir() for m in self.matchers],
+        }
+
+    def __repr__(self) -> str:
+        return f"Or({len(self.matchers)} matchers)"
+
+
+class NotOperator:
+    """
+    Logical NOT - matcher must NOT match.
+
+    Example:
+        Not(calls("test_*"))
+        # Matches code that does NOT call test_* functions
+    """
+
+    def __init__(self, matcher: MatcherType):
+        self.matcher = matcher
+
+    def to_ir(self) -> dict:
+        return {
+            "type": IRType.LOGIC_NOT.value,
+            "matcher": self.matcher.to_ir(),
+        }
+
+    def __repr__(self) -> str:
+        return f"Not({repr(self.matcher)})"
+
+
+# Public API
+def And(*matchers: MatcherType) -> AndOperator:
+    """Create AND combinator."""
+    return AndOperator(*matchers)
+
+
+def Or(*matchers: MatcherType) -> OrOperator:
+    """Create OR combinator."""
+    return OrOperator(*matchers)
+
+
+def Not(matcher: MatcherType) -> NotOperator:
+    """Create NOT combinator."""
+    return NotOperator(matcher)

codepathfinder/matchers.py

@@ -0,0 +1,243 @@
+"""
+Core matchers for the pathfinder Python DSL.
+
+These matchers generate JSON IR for the Go executor.
+"""
+
+from typing import Dict, Optional, Union, List, Any
+from .ir import IRType
+
+ArgumentValue = Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+
+
+class CallMatcher:
+    """
+    Matches function/method calls with optional argument constraints.
+
+    Examples:
+        calls("eval")                    # Exact match
+        calls("eval", "exec")            # Multiple patterns
+        calls("request.*")               # Wildcard (any request.* call)
+        calls("*.json")                  # Wildcard (any *.json call)
+        calls("app.run", match_name={"debug": True})  # Keyword argument matching
+        calls("open", match_position={1: "w"})  # Positional argument matching
+        calls("socket.bind", match_position={"0[0]": "0.0.0.0"})  # Tuple indexing
+        calls("connect", match_position={"0[0]": "192.168.*"})  # Wildcard + tuple
+    """
+
+    def __init__(
+        self,
+        *patterns: str,
+        match_position: Optional[Dict[int, ArgumentValue]] = None,
+        match_name: Optional[Dict[str, ArgumentValue]] = None,
+    ):
+        """
+        Args:
+            *patterns: Function names to match. Supports wildcards (*).
+            match_position: Match positional arguments by index or tuple index.
+                           Examples: {0: "value"}, {1: ["a", "b"]}, {"0[0]": "0.0.0.0"}
+            match_name: Match named/keyword arguments {name: value}
+
+        Position indexing:
+            - Simple: {0: "value"} matches first argument
+            - Tuple: {"0[0]": "value"} matches first element of first argument tuple
+            - Wildcard: {"0[0]": "192.168.*"} matches with wildcard pattern
+
+        Raises:
+            ValueError: If no patterns provided or pattern is empty
+        """
+        if not patterns:
+            raise ValueError("calls() requires at least one pattern")
+
+        if any(not p or not isinstance(p, str) for p in patterns):
+            raise ValueError("All patterns must be non-empty strings")
+
+        self.patterns = list(patterns)
+        self.wildcard = any("*" in p for p in patterns)
+        self.match_position = match_position or {}
+        self.match_name = match_name or {}
+
+    def _make_constraint(self, value: ArgumentValue) -> Dict[str, Any]:
+        """
+        Create an argument constraint from a value.
+
+        Automatically detects wildcard characters in string values.
+
+        Args:
+            value: The argument value or list of values
+
+        Returns:
+            Dictionary with 'value' and 'wildcard' keys
+        """
+        # Check if wildcard characters are present in string values
+        # NOTE: Argument wildcard is independent of pattern wildcard (self.wildcard)
+        # Pattern wildcard applies to function name matching (e.g., "*.bind")
+        # Argument wildcard applies to argument value matching (e.g., "192.168.*")
+        has_wildcard = False
+        if isinstance(value, str) and ("*" in value or "?" in value):
+            has_wildcard = True
+        elif isinstance(value, list):
+            has_wildcard = any(
+                isinstance(v, str) and ("*" in v or "?" in v) for v in value
+            )
+
+        return {"value": value, "wildcard": has_wildcard}
+
+    def to_ir(self) -> dict:
+        """
+        Serialize to JSON IR for Go executor.
+
+        Returns:
+            {
+                "type": "call_matcher",
+                "patterns": ["eval", "exec"],
+                "wildcard": false,
+                "matchMode": "any",
+                "keywordArgs": { "debug": {"value": true, "wildcard": false} },
+                "positionalArgs": { "0": {"value": "0.0.0.0", "wildcard": false} }
+            }
+        """
+        ir = {
+            "type": IRType.CALL_MATCHER.value,
+            "patterns": self.patterns,
+            "wildcard": self.wildcard,
+            "matchMode": "any",
+        }
+
+        # Add positional argument constraints
+        if self.match_position:
+            positional_args = {}
+            for pos, value in self.match_position.items():
+                constraint = self._make_constraint(value)
+                # Propagate wildcard flag from pattern to argument constraints
+                if self.wildcard:
+                    constraint["wildcard"] = True
+                positional_args[str(pos)] = constraint
+            ir["positionalArgs"] = positional_args
+
+        # Add keyword argument constraints
+        if self.match_name:
+            keyword_args = {}
+            for name, value in self.match_name.items():
+                constraint = self._make_constraint(value)
+                # Propagate wildcard flag from pattern to argument constraints
+                if self.wildcard:
+                    constraint["wildcard"] = True
+                keyword_args[name] = constraint
+            ir["keywordArgs"] = keyword_args
+
+        return ir
+
+    def __repr__(self) -> str:
+        patterns_str = ", ".join(f'"{p}"' for p in self.patterns)
+        return f"calls({patterns_str})"
+
+
+class VariableMatcher:
+    """
+    Matches variable references by name.
+
+    Examples:
+        variable("user_input")           # Exact match
+        variable("user_*")               # Wildcard prefix
+        variable("*_id")                 # Wildcard suffix
+    """
+
+    def __init__(self, pattern: str):
+        """
+        Args:
+            pattern: Variable name pattern. Supports wildcards (*).
+
+        Raises:
+            ValueError: If pattern is empty
+        """
+        if not pattern or not isinstance(pattern, str):
+            raise ValueError("variable() requires a non-empty string pattern")
+
+        self.pattern = pattern
+        self.wildcard = "*" in pattern
+
+    def to_ir(self) -> dict:
+        """
+        Serialize to JSON IR for Go executor.
+
+        Returns:
+            {
+                "type": "variable_matcher",
+                "pattern": "user_input",
+                "wildcard": false
+            }
+        """
+        return {
+            "type": IRType.VARIABLE_MATCHER.value,
+            "pattern": self.pattern,
+            "wildcard": self.wildcard,
+        }
+
+    def __repr__(self) -> str:
+        return f'variable("{self.pattern}")'
+
+
+# Public API
+def calls(
+    *patterns: str,
+    match_position: Optional[Dict[int, ArgumentValue]] = None,
+    match_name: Optional[Dict[str, ArgumentValue]] = None,
+) -> CallMatcher:
+    """
+    Create a matcher for function/method calls with optional argument constraints.
+
+    Args:
+        *patterns: Function names to match (supports wildcards)
+        match_position: Match positional arguments by index {position: value}
+        match_name: Match named/keyword arguments {name: value}
+
+    Returns:
+        CallMatcher instance
+
+    Examples:
+        >>> calls("eval")
+        calls("eval")
+
+        >>> calls("request.GET", "request.POST")
+        calls("request.GET", "request.POST")
+
+        >>> calls("urllib.*")
+        calls("urllib.*")
+
+        >>> calls("app.run", match_name={"debug": True})
+        calls("app.run")
+
+        >>> calls("socket.bind", match_position={0: "0.0.0.0"})
+        calls("socket.bind")
+
+        >>> calls("yaml.load", match_position={1: ["Loader", "UnsafeLoader"]})
+        calls("yaml.load")
+
+        >>> calls("chmod", match_position={1: "0o7*"})
+        calls("chmod")
+
+        >>> calls("app.run", match_position={0: "localhost"}, match_name={"debug": True})
+        calls("app.run")
+    """
+    return CallMatcher(*patterns, match_position=match_position, match_name=match_name)
+
+
+def variable(pattern: str) -> VariableMatcher:
+    """
+    Create a matcher for variable references.
+
+    Args:
+        pattern: Variable name pattern (supports wildcards)
+
+    Returns:
+        VariableMatcher instance
+
+    Examples:
+        >>> variable("user_input")
+        variable("user_input")
+
+        >>> variable("*_id")
+        variable("*_id")
+    """
+    return VariableMatcher(pattern)

codepathfinder/presets.py

@@ -0,0 +1,135 @@
+"""
+Propagation presets for common use cases.
+
+Presets bundle propagation primitives for convenience.
+"""
+
+from typing import List
+from .propagation import propagates, PropagationPrimitive
+
+
+class PropagationPresets:
+    """
+    Common propagation bundles.
+
+    Developers can use presets instead of manually listing primitives.
+    """
+
+    @staticmethod
+    def minimal() -> List[PropagationPrimitive]:
+        """
+        Bare minimum propagation (fastest, least false negatives).
+
+        Covers:
+            - Variable assignments
+            - Function arguments
+
+        Coverage: ~40% of real-world flows
+        Performance: Fastest (minimal overhead)
+        False negatives: Higher (misses return values, strings)
+
+        Use when:
+            - Performance is critical
+            - You only care about direct variable flows
+
+        Example:
+            flows(
+                from_sources=calls("request.GET"),
+                to_sinks=calls("eval"),
+                propagates_through=PropagationPresets.minimal(),
+                scope="local"
+            )
+        """
+        return [
+            propagates.assignment(),
+            propagates.function_args(),
+        ]
+
+    @staticmethod
+    def standard() -> List[PropagationPrimitive]:
+        """
+        Recommended default (good balance).
+
+        Covers:
+            - Phase 1: assignment, function_args, function_returns
+            - Phase 2: string_concat, string_format
+
+        Coverage: ~75-80% of real-world flows
+        Performance: Good (moderate overhead)
+        False negatives: Lower
+
+        Use when:
+            - General-purpose taint analysis
+            - OWASP Top 10 detection
+            - Good balance of coverage and performance
+
+        Example:
+            flows(
+                from_sources=calls("request.*"),
+                to_sinks=calls("execute"),
+                propagates_through=PropagationPresets.standard(),
+                scope="global"
+            )
+        """
+        return [
+            propagates.assignment(),
+            propagates.function_args(),
+            propagates.function_returns(),
+            propagates.string_concat(),
+            propagates.string_format(),
+        ]
+
+    @staticmethod
+    def comprehensive() -> List[PropagationPrimitive]:
+        """
+        All MVP primitives (Phase 1 + Phase 2).
+
+        Covers:
+            - All standard() primitives
+
+        Coverage: ~80% of real-world flows
+        Performance: Moderate
+        False negatives: Low
+
+        Use when:
+            - Maximum coverage within MVP scope
+            - Willing to accept moderate performance overhead
+
+        Example:
+            flows(
+                from_sources=calls("request.*"),
+                to_sinks=calls("eval"),
+                propagates_through=PropagationPresets.comprehensive(),
+                scope="global"
+            )
+        """
+        return PropagationPresets.standard()  # For MVP, comprehensive = standard
+
+    @staticmethod
+    def exhaustive() -> List[PropagationPrimitive]:
+        """
+        All primitives (Phase 1-6, POST-MVP).
+
+        NOTE: For MVP, this is same as comprehensive().
+        Post-MVP will include collections, control flow, OOP, advanced.
+
+        Coverage: ~95% of real-world flows (POST-MVP)
+        Performance: Slower (comprehensive analysis)
+        False negatives: Minimal
+
+        Use when:
+            - Maximum security coverage required
+            - Performance is not a concern
+            - Production-critical code
+
+        Example:
+            flows(
+                from_sources=calls("request.*"),
+                to_sinks=calls("execute"),
+                propagates_through=PropagationPresets.exhaustive(),
+                scope="global"
+            )
+        """
+        # MVP: same as comprehensive
+        # POST-MVP: will include Phase 3-6 primitives
+        return PropagationPresets.comprehensive()