codepathfinder 1.1.0__py3-none-any.whl

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()

codepathfinder/propagation.py

@@ -0,0 +1,250 @@
+"""
+Taint propagation primitives for dataflow analysis.
+
+These primitives define HOW taint propagates through code constructs.
+Developers specify which primitives to enable via propagates_through parameter.
+"""
+
+from typing import Dict, Any, List, Optional
+from enum import Enum
+
+
+class PropagationType(Enum):
+    """
+    Enum of all propagation primitive types.
+
+    Phase 1 (MVP - This PR):
+        ASSIGNMENT, FUNCTION_ARGS, FUNCTION_RETURNS
+
+    Phase 2 (MVP - Future PR):
+        STRING_CONCAT, STRING_FORMAT
+
+    Phase 3-6 (Post-MVP):
+        Collections, control flow, OOP, advanced
+    """
+
+    # ===== PHASE 1: BARE MINIMUM (MVP) =====
+    ASSIGNMENT = "assignment"
+    FUNCTION_ARGS = "function_args"
+    FUNCTION_RETURNS = "function_returns"
+
+    # ===== PHASE 2: STRING OPERATIONS (MVP - Future PR) =====
+    STRING_CONCAT = "string_concat"
+    STRING_FORMAT = "string_format"
+
+    # ===== PHASE 3: COLLECTIONS (POST-MVP) =====
+    LIST_APPEND = "list_append"
+    LIST_EXTEND = "list_extend"
+    DICT_VALUES = "dict_values"
+    DICT_UPDATE = "dict_update"
+    SET_ADD = "set_add"
+
+    # ===== PHASE 4: CONTROL FLOW (POST-MVP) =====
+    IF_CONDITION = "if_condition"
+    FOR_ITERATION = "for_iteration"
+    WHILE_CONDITION = "while_condition"
+    SWITCH_CASE = "switch_case"
+
+    # ===== PHASE 5: OOP (POST-MVP) =====
+    ATTRIBUTE_ASSIGNMENT = "attribute_assignment"
+    METHOD_CALL = "method_call"
+    CONSTRUCTOR = "constructor"
+
+    # ===== PHASE 6: ADVANCED (POST-MVP) =====
+    COMPREHENSION = "comprehension"
+    LAMBDA_CAPTURE = "lambda_capture"
+    YIELD_STMT = "yield_stmt"
+
+
+class PropagationPrimitive:
+    """
+    Base class for propagation primitives.
+
+    Each primitive describes ONE way taint can flow through code.
+    """
+
+    def __init__(
+        self, prim_type: PropagationType, metadata: Optional[Dict[str, Any]] = None
+    ):
+        """
+        Args:
+            prim_type: The type of propagation
+            metadata: Optional additional configuration
+        """
+        self.type = prim_type
+        self.metadata = metadata or {}
+
+    def to_ir(self) -> Dict[str, Any]:
+        """
+        Serialize to JSON IR.
+
+        Returns:
+            {
+                "type": "assignment",
+                "metadata": {}
+            }
+        """
+        return {
+            "type": self.type.value,
+            "metadata": self.metadata,
+        }
+
+    def __repr__(self) -> str:
+        return f"propagates.{self.type.value}()"
+
+
+class propagates:
+    """
+    Namespace for taint propagation primitives.
+
+    Usage:
+        propagates.assignment()
+        propagates.function_args()
+        propagates.function_returns()
+    """
+
+    # ===== PHASE 1: BARE MINIMUM (MVP - THIS PR) =====
+
+    @staticmethod
+    def assignment() -> PropagationPrimitive:
+        """
+        Taint propagates through variable assignment.
+
+        Patterns matched:
+            x = tainted           # Simple assignment
+            a = b = tainted       # Chained assignment
+            x, y = tainted, safe  # Tuple unpacking (x is tainted)
+
+        This is the MOST COMMON propagation pattern (~40% of all flows).
+
+        Examples:
+            user_input = request.GET.get("id")  # source
+            query = user_input                  # PROPAGATES via assignment
+            cursor.execute(query)               # sink
+
+        Returns:
+            PropagationPrimitive for assignment
+        """
+        return PropagationPrimitive(PropagationType.ASSIGNMENT)
+
+    @staticmethod
+    def function_args() -> PropagationPrimitive:
+        """
+        Taint propagates through function arguments.
+
+        Patterns matched:
+            func(tainted)              # Positional argument
+            func(arg=tainted)          # Keyword argument
+            func(*tainted)             # Args unpacking
+            func(**tainted)            # Kwargs unpacking
+
+        Critical for inter-procedural analysis (~30% of flows).
+
+        Examples:
+            user_input = request.GET.get("id")  # source
+            process_data(user_input)            # PROPAGATES via function_args
+            def process_data(data):
+                execute(data)                   # sink (data is tainted)
+
+        Returns:
+            PropagationPrimitive for function arguments
+        """
+        return PropagationPrimitive(PropagationType.FUNCTION_ARGS)
+
+    @staticmethod
+    def function_returns() -> PropagationPrimitive:
+        """
+        Taint propagates through return values.
+
+        Patterns matched:
+            return tainted                # Direct return
+            return tainted if cond else safe  # Conditional return
+            return [tainted, safe]        # Return list containing tainted
+
+        Essential for functions that transform tainted data (~20% of flows).
+
+        Examples:
+            def get_user_id():
+                user_input = request.GET.get("id")  # source
+                return user_input                   # PROPAGATES via return
+
+            query = get_user_id()           # query is now tainted
+            execute(query)                  # sink
+
+        Returns:
+            PropagationPrimitive for function returns
+        """
+        return PropagationPrimitive(PropagationType.FUNCTION_RETURNS)
+
+    # ===== PHASE 2: STRING OPERATIONS (MVP - THIS PR) =====
+
+    @staticmethod
+    def string_concat() -> PropagationPrimitive:
+        """
+        Taint propagates through string concatenation.
+
+        Patterns matched:
+            result = tainted + "suffix"      # Right concat
+            result = "prefix" + tainted      # Left concat
+            result = tainted + safe + more   # Mixed concat
+
+        Critical for SQL/Command injection where queries are built via concat (~10% of flows).
+
+        Examples:
+            user_id = request.GET.get("id")           # source
+            query = "SELECT * FROM users WHERE id = " + user_id  # PROPAGATES via string_concat
+            cursor.execute(query)                     # sink
+
+        Returns:
+            PropagationPrimitive for string concatenation
+        """
+        return PropagationPrimitive(PropagationType.STRING_CONCAT)
+
+    @staticmethod
+    def string_format() -> PropagationPrimitive:
+        """
+        Taint propagates through string formatting.
+
+        Patterns matched:
+            f"{tainted}"                    # f-string
+            "{}".format(tainted)            # str.format()
+            "%s" % tainted                  # % formatting
+            "{name}".format(name=tainted)   # Named placeholders
+
+        Critical for SQL injection where ORM methods use format() (~8% of flows).
+
+        Examples:
+            user_id = request.GET.get("id")           # source
+            query = f"SELECT * FROM users WHERE id = {user_id}"  # PROPAGATES via string_format
+            cursor.execute(query)                     # sink
+
+        Returns:
+            PropagationPrimitive for string formatting
+        """
+        return PropagationPrimitive(PropagationType.STRING_FORMAT)
+
+    # ===== PHASE 3-6: POST-MVP =====
+    # Will be implemented in post-MVP PRs
+
+
+def create_propagation_list(
+    primitives: List[PropagationPrimitive],
+) -> List[Dict[str, Any]]:
+    """
+    Convert a list of propagation primitives to JSON IR.
+
+    Args:
+        primitives: List of PropagationPrimitive objects
+
+    Returns:
+        List of JSON IR dictionaries
+
+    Example:
+        >>> prims = [propagates.assignment(), propagates.function_args()]
+        >>> create_propagation_list(prims)
+        [
+            {"type": "assignment", "metadata": {}},
+            {"type": "function_args", "metadata": {}}
+        ]
+    """
+    return [prim.to_ir() for prim in primitives]