codepathfinder 1.0.0__py3-none-any.whl

codepathfinder/__init__.py

@@ -0,0 +1,48 @@
+"""
+codepathfinder - Python DSL for static analysis security patterns
+
+Examples:
+    Basic matchers:
+        >>> from codepathfinder import calls, variable
+        >>> calls("eval")
+        >>> variable("user_input")
+
+    Rule definition:
+        >>> from codepathfinder import rule, calls
+        >>> @rule(id="test", severity="high")
+        >>> def detect_eval():
+        >>>     return calls("eval")
+
+    Dataflow analysis:
+        >>> from codepathfinder import flows, calls, propagates
+        >>> flows(
+        ...     from_sources=calls("request.GET"),
+        ...     to_sinks=calls("execute"),
+        ...     propagates_through=[propagates.assignment()]
+        ... )
+"""
+
+__version__ = "1.0.0"
+
+from .matchers import calls, variable
+from .decorators import rule
+from .dataflow import flows
+from .propagation import propagates
+from .presets import PropagationPresets
+from .config import set_default_propagation, set_default_scope
+from .logic import And, Or, Not
+
+__all__ = [
+    "calls",
+    "variable",
+    "rule",
+    "flows",
+    "propagates",
+    "PropagationPresets",
+    "set_default_propagation",
+    "set_default_scope",
+    "And",
+    "Or",
+    "Not",
+    "__version__",
+]

codepathfinder/config.py

@@ -0,0 +1,92 @@
+"""
+Global configuration for codepathfinder DSL.
+
+Allows setting default propagation, scope, etc.
+"""
+
+from typing import List, Optional
+from .propagation import PropagationPrimitive
+
+
+class PathfinderConfig:
+    """Singleton configuration for codepathfinder."""
+
+    _instance: Optional["PathfinderConfig"] = None
+    _default_propagation: List[PropagationPrimitive] = []
+    _default_scope: str = "global"
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    @property
+    def default_propagation(self) -> List[PropagationPrimitive]:
+        """Get default propagation primitives."""
+        return self._default_propagation
+
+    @default_propagation.setter
+    def default_propagation(self, value: List[PropagationPrimitive]):
+        """Set default propagation primitives."""
+        self._default_propagation = value
+
+    @property
+    def default_scope(self) -> str:
+        """Get default scope."""
+        return self._default_scope
+
+    @default_scope.setter
+    def default_scope(self, value: str):
+        """Set default scope."""
+        if value not in ["local", "global"]:
+            raise ValueError(f"scope must be 'local' or 'global', got '{value}'")
+        self._default_scope = value
+
+
+# Global config instance
+_config = PathfinderConfig()
+
+
+def set_default_propagation(primitives: List[PropagationPrimitive]) -> None:
+    """
+    Set global default propagation primitives.
+
+    All flows() calls without explicit propagates_through will use this default.
+
+    Args:
+        primitives: List of PropagationPrimitive objects
+
+    Example:
+        set_default_propagation(PropagationPresets.standard())
+
+        # Now all flows() without propagates_through use standard()
+        flows(
+            from_sources=calls("request.GET"),
+            to_sinks=calls("eval"),
+            # propagates_through defaults to standard()
+        )
+    """
+    _config.default_propagation = primitives
+
+
+def set_default_scope(scope: str) -> None:
+    """
+    Set global default scope.
+
+    Args:
+        scope: "local" or "global"
+
+    Example:
+        set_default_scope("local")
+    """
+    _config.default_scope = scope
+
+
+def get_default_propagation() -> List[PropagationPrimitive]:
+    """Get global default propagation primitives."""
+    return _config.default_propagation
+
+
+def get_default_scope() -> str:
+    """Get global default scope."""
+    return _config.default_scope

codepathfinder/dataflow.py

@@ -0,0 +1,193 @@
+"""
+Dataflow matcher for taint analysis.
+
+The flows() function is the core of OWASP Top 10 pattern detection.
+It describes how tainted data flows from sources to sinks.
+"""
+
+from typing import List, Optional, Union
+from .matchers import CallMatcher
+from .propagation import PropagationPrimitive, create_propagation_list
+from .ir import IRType
+from .config import get_default_propagation, get_default_scope
+
+
+class DataflowMatcher:
+    """
+    Matches tainted data flows from sources to sinks.
+
+    This is the primary matcher for security vulnerabilities like:
+    - SQL Injection (A03:2021)
+    - Command Injection (A03:2021)
+    - SSRF (A10:2021)
+    - Path Traversal (A01:2021)
+    - Insecure Deserialization (A08:2021)
+
+    Attributes:
+        sources: Matchers for taint sources (e.g., user input)
+        sinks: Matchers for dangerous sinks (e.g., eval, execute)
+        sanitizers: Optional matchers for sanitizer functions
+        propagates_through: List of propagation primitives (EXPLICIT!)
+        scope: "local" (same function) or "global" (cross-function)
+    """
+
+    def __init__(
+        self,
+        from_sources: Union[CallMatcher, List[CallMatcher]],
+        to_sinks: Union[CallMatcher, List[CallMatcher]],
+        sanitized_by: Optional[Union[CallMatcher, List[CallMatcher]]] = None,
+        propagates_through: Optional[List[PropagationPrimitive]] = None,
+        scope: Optional[str] = None,
+    ):
+        """
+        Args:
+            from_sources: Source matcher(s) - where taint originates
+            to_sinks: Sink matcher(s) - dangerous functions
+            sanitized_by: Optional sanitizer matcher(s)
+            propagates_through: EXPLICIT list of propagation primitives
+                                (default: None = no propagation!)
+            scope: "local" (intra-procedural) or "global" (inter-procedural)
+
+        Raises:
+            ValueError: If sources/sinks are empty, scope invalid, etc.
+
+        Examples:
+            # SQL Injection
+            flows(
+                from_sources=calls("request.GET", "request.POST"),
+                to_sinks=calls("execute", "executemany"),
+                sanitized_by=calls("quote_sql"),
+                propagates_through=[
+                    propagates.assignment(),
+                    propagates.function_args(),
+                ],
+                scope="global"
+            )
+        """
+        # Validate sources
+        if isinstance(from_sources, CallMatcher):
+            from_sources = [from_sources]
+        if not from_sources:
+            raise ValueError("flows() requires at least one source")
+        self.sources = from_sources
+
+        # Validate sinks
+        if isinstance(to_sinks, CallMatcher):
+            to_sinks = [to_sinks]
+        if not to_sinks:
+            raise ValueError("flows() requires at least one sink")
+        self.sinks = to_sinks
+
+        # Validate sanitizers
+        if sanitized_by is None:
+            sanitized_by = []
+        elif isinstance(sanitized_by, CallMatcher):
+            sanitized_by = [sanitized_by]
+        self.sanitizers = sanitized_by
+
+        # Validate propagation (use global default if not specified)
+        if propagates_through is None:
+            propagates_through = get_default_propagation()
+        self.propagates_through = propagates_through
+
+        # Validate scope (use global default if not specified)
+        if scope is None:
+            scope = get_default_scope()
+        if scope not in ["local", "global"]:
+            raise ValueError(f"scope must be 'local' or 'global', got '{scope}'")
+        self.scope = scope
+
+    def to_ir(self) -> dict:
+        """
+        Serialize to JSON IR for Go executor.
+
+        Returns:
+            {
+                "type": "dataflow",
+                "sources": [
+                    {"type": "call_matcher", "patterns": ["request.GET"], ...}
+                ],
+                "sinks": [
+                    {"type": "call_matcher", "patterns": ["execute"], ...}
+                ],
+                "sanitizers": [
+                    {"type": "call_matcher", "patterns": ["quote_sql"], ...}
+                ],
+                "propagation": [
+                    {"type": "assignment", "metadata": {}},
+                    {"type": "function_args", "metadata": {}}
+                ],
+                "scope": "global"
+            }
+        """
+        return {
+            "type": IRType.DATAFLOW.value,
+            "sources": [src.to_ir() for src in self.sources],
+            "sinks": [sink.to_ir() for sink in self.sinks],
+            "sanitizers": [san.to_ir() for san in self.sanitizers],
+            "propagation": create_propagation_list(self.propagates_through),
+            "scope": self.scope,
+        }
+
+    def __repr__(self) -> str:
+        src_count = len(self.sources)
+        sink_count = len(self.sinks)
+        prop_count = len(self.propagates_through)
+        return (
+            f"flows(sources={src_count}, sinks={sink_count}, "
+            f"propagation={prop_count}, scope='{self.scope}')"
+        )
+
+
+# Public API
+def flows(
+    from_sources: Union[CallMatcher, List[CallMatcher]],
+    to_sinks: Union[CallMatcher, List[CallMatcher]],
+    sanitized_by: Optional[Union[CallMatcher, List[CallMatcher]]] = None,
+    propagates_through: Optional[List[PropagationPrimitive]] = None,
+    scope: Optional[str] = None,
+) -> DataflowMatcher:
+    """
+    Create a dataflow matcher for taint analysis.
+
+    This is the PRIMARY matcher for OWASP Top 10 vulnerabilities.
+
+    Args:
+        from_sources: Where taint originates (e.g., user input)
+        to_sinks: Dangerous functions that consume tainted data
+        sanitized_by: Optional functions that neutralize taint
+        propagates_through: HOW taint flows (MUST be explicit!)
+        scope: "local" or "global" analysis
+
+    Returns:
+        DataflowMatcher instance
+
+    Examples:
+        >>> from codepathfinder import flows, calls, propagates
+        >>>
+        >>> # SQL Injection
+        >>> flows(
+        ...     from_sources=calls("request.GET"),
+        ...     to_sinks=calls("execute"),
+        ...     propagates_through=[propagates.assignment()]
+        ... )
+        >>>
+        >>> # Command Injection with sanitization
+        >>> flows(
+        ...     from_sources=calls("request.POST"),
+        ...     to_sinks=calls("os.system", "subprocess.call"),
+        ...     sanitized_by=calls("shlex.quote"),
+        ...     propagates_through=[
+        ...         propagates.assignment(),
+        ...         propagates.function_args()
+        ...     ],
+        ...     scope="global"
+        ... )
+    """
+    return DataflowMatcher(
+        from_sources=from_sources,
+        to_sinks=to_sinks,
+        sanitized_by=sanitized_by,
+        propagates_through=propagates_through,
+        scope=scope,
+    )

codepathfinder/decorators.py

@@ -0,0 +1,104 @@
+"""
+Decorators for pathfinder rule definitions.
+
+The @rule decorator marks functions as security patterns.
+"""
+
+from typing import Callable, Optional
+from .ir import serialize_ir
+
+
+class Rule:
+    """
+    Represents a security rule with metadata.
+
+    Attributes:
+        id: Unique rule identifier (e.g., "sqli-001")
+        name: Human-readable name (defaults to function name)
+        severity: critical | high | medium | low
+        cwe: CWE identifier (e.g., "CWE-89")
+        owasp: OWASP category (e.g., "A03:2021")
+        description: What this rule detects (from docstring)
+        matcher: The matcher/combinator returned by the rule function
+    """
+
+    def __init__(
+        self,
+        id: str,
+        severity: str,
+        func: Callable,
+        cwe: Optional[str] = None,
+        owasp: Optional[str] = None,
+    ):
+        self.id = id
+        self.name = func.__name__
+        self.severity = severity
+        self.cwe = cwe
+        self.owasp = owasp
+        self.description = func.__doc__ or ""
+        self.func = func
+
+    def execute(self) -> dict:
+        """
+        Execute the rule function and serialize to JSON IR.
+
+        Returns:
+            {
+                "rule": {
+                    "id": "sqli-001",
+                    "name": "detect_sql_injection",
+                    "severity": "critical",
+                    "cwe": "CWE-89",
+                    "owasp": "A03:2021",
+                    "description": "Detects SQL injection vulnerabilities"
+                },
+                "matcher": {
+                    "type": "call_matcher",
+                    "patterns": ["execute"],
+                    "wildcard": false
+                }
+            }
+        """
+        matcher = self.func()
+        return {
+            "rule": {
+                "id": self.id,
+                "name": self.name,
+                "severity": self.severity,
+                "cwe": self.cwe,
+                "owasp": self.owasp,
+                "description": self.description.strip(),
+            },
+            "matcher": serialize_ir(matcher),
+        }
+
+
+def rule(
+    id: str,
+    severity: str,
+    cwe: Optional[str] = None,
+    owasp: Optional[str] = None,
+) -> Callable[[Callable], Rule]:
+    """
+    Decorator to mark a function as a security rule.
+
+    Args:
+        id: Unique rule identifier
+        severity: critical | high | medium | low
+        cwe: Optional CWE identifier
+        owasp: Optional OWASP category
+
+    Returns:
+        Decorator function
+
+    Example:
+        @rule(id="code-injection", severity="critical", cwe="CWE-94")
+        def detect_code_injection():
+            '''Detects code injection via eval'''
+            return calls("eval", "exec")
+    """
+
+    def decorator(func: Callable) -> Rule:
+        return Rule(id=id, severity=severity, func=func, cwe=cwe, owasp=owasp)
+
+    return decorator

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)