codepathfinder 1.2.0__py3-none-manylinux_2_17_aarch64.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.2.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/cli/__init__.py

@@ -0,0 +1,204 @@
+"""CLI wrapper for pathfinder binary.
+
+This module provides the entry point for the `pathfinder` command.
+It locates and executes the bundled Go binary, passing through all arguments.
+"""
+
+import os
+import sys
+import subprocess
+import platform
+import urllib.request
+import tarfile
+import zipfile
+import tempfile
+from pathlib import Path
+
+from codepathfinder import __version__
+
+
+def get_binary_name() -> str:
+    """Get the binary name for the current platform."""
+    if sys.platform == "win32":
+        return "pathfinder.exe"
+    return "pathfinder"
+
+
+def get_binary_path() -> Path:
+    """Get path to the pathfinder binary.
+
+    Priority:
+    1. Bundled binary in package (platform wheels)
+    2. Binary in PATH (for development or manual install)
+    3. Download on first use (fallback for source installs)
+
+    Returns:
+        Path to the executable binary
+
+    Raises:
+        RuntimeError: If binary cannot be found or downloaded
+    """
+    binary_name = get_binary_name()
+
+    # 1. Check bundled binary (primary - from platform wheel)
+    package_dir = Path(__file__).parent.parent
+    bin_dir = package_dir / "bin"
+    bundled_binary = bin_dir / binary_name
+
+    if bundled_binary.exists() and os.access(bundled_binary, os.X_OK):
+        return bundled_binary
+
+    # 2. Check PATH (development mode or manual install)
+    import shutil
+
+    path_binary = shutil.which("pathfinder")
+    if path_binary:
+        return Path(path_binary)
+
+    # 3. Download on first use (source distribution fallback)
+    return _download_binary(bin_dir, binary_name)
+
+
+def _is_musl() -> bool:
+    """Detect if running on musl libc (Alpine Linux, etc.)."""
+    try:
+        result = subprocess.run(["ldd", "--version"], capture_output=True, text=True)
+        return "musl" in result.stderr.lower() or "musl" in result.stdout.lower()
+    except Exception:
+        try:
+            with open("/etc/os-release") as f:
+                content = f.read().lower()
+                return "alpine" in content
+        except Exception:
+            return False
+
+
+def _get_platform_string() -> str:
+    """Get platform string for binary download.
+
+    Supports 96%+ of worldwide architectures:
+    - Linux glibc: x86_64, aarch64
+    - Linux musl: x86_64, aarch64 (Alpine Docker)
+    - macOS: arm64 (M1/M2/M3), x86_64 (Intel)
+    - Windows: x86_64
+    """
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+
+    arch_map = {
+        "x86_64": "amd64",
+        "amd64": "amd64",
+        "aarch64": "arm64",
+        "arm64": "arm64",
+        "armv8l": "arm64",
+    }
+
+    arch = arch_map.get(machine)
+    if not arch:
+        raise RuntimeError(
+            f"Unsupported architecture: {machine}\n"
+            f"Supported: x86_64, aarch64/arm64\n"
+            f"Download manually from: https://github.com/shivasurya/code-pathfinder/releases"
+        )
+
+    os_map = {
+        "linux": "linux",
+        "darwin": "darwin",
+        "windows": "windows",
+    }
+
+    os_name = os_map.get(system)
+    if not os_name:
+        raise RuntimeError(
+            f"Unsupported operating system: {system}\n"
+            f"Supported: Linux, macOS, Windows\n"
+            f"Download manually from: https://github.com/shivasurya/code-pathfinder/releases"
+        )
+
+    if os_name == "linux" and _is_musl():
+        return f"{os_name}-{arch}-musl"
+
+    return f"{os_name}-{arch}"
+
+
+def _download_binary(bin_dir: Path, binary_name: str) -> Path:
+    """Download binary for current platform from GitHub releases.
+
+    Args:
+        bin_dir: Directory to store the binary
+        binary_name: Name of the binary file
+
+    Returns:
+        Path to the downloaded binary
+
+    Raises:
+        RuntimeError: If download fails
+    """
+    platform_str = _get_platform_string()
+
+    if sys.platform == "win32":
+        archive_ext = ".zip"
+    else:
+        archive_ext = ".tar.gz"
+
+    url = (
+        f"https://github.com/shivasurya/code-pathfinder/releases/download/"
+        f"v{__version__}/pathfinder-{platform_str}{archive_ext}"
+    )
+
+    print(f"Downloading pathfinder binary for {platform_str}...", file=sys.stderr)
+
+    bin_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        with tempfile.NamedTemporaryFile(suffix=archive_ext, delete=False) as tmp:
+            urllib.request.urlretrieve(url, tmp.name)
+
+            if archive_ext == ".tar.gz":
+                with tarfile.open(tmp.name, "r:gz") as tar:
+                    for member in tar.getmembers():
+                        if member.name == "pathfinder" or member.name.endswith(
+                            "/pathfinder"
+                        ):
+                            member.name = binary_name
+                            tar.extract(member, bin_dir)
+                            break
+            else:
+                with zipfile.ZipFile(tmp.name, "r") as zip_ref:
+                    for name in zip_ref.namelist():
+                        if name == "pathfinder.exe" or name.endswith("/pathfinder.exe"):
+                            with zip_ref.open(name) as src:
+                                (bin_dir / binary_name).write_bytes(src.read())
+                            break
+
+            os.unlink(tmp.name)
+    except Exception as e:
+        raise RuntimeError(
+            f"Failed to download pathfinder binary from {url}: {e}\n"
+            f"You can manually download from: "
+            f"https://github.com/shivasurya/code-pathfinder/releases"
+        ) from e
+
+    binary_path = bin_dir / binary_name
+
+    if sys.platform != "win32":
+        os.chmod(binary_path, 0o755)
+
+    print(f"Binary installed to: {binary_path}", file=sys.stderr)
+    return binary_path
+
+
+def main():
+    """Entry point - execute pathfinder binary with all arguments."""
+    try:
+        binary = get_binary_path()
+    except RuntimeError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    result = subprocess.run([str(binary)] + sys.argv[1:])
+    sys.exit(result.returncode)
+
+
+if __name__ == "__main__":
+    main()

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,158 @@
+"""
+Decorators for pathfinder rule definitions.
+
+The @rule decorator marks functions as security patterns.
+"""
+
+import atexit
+import json
+import sys
+from typing import Callable, Optional, List
+from .ir import serialize_ir
+
+
+# Global registry for auto-execution
+_rule_registry: List["Rule"] = []
+_auto_execute_enabled = False
+
+
+def _enable_auto_execute() -> None:
+    """
+    Enable automatic rule execution when script ends.
+
+    This should be called once when the first rule is registered
+    and the module is being executed as a script (not imported).
+    """
+    global _auto_execute_enabled
+    if _auto_execute_enabled:
+        return
+
+    _auto_execute_enabled = True
+
+    def _output_rules():
+        """Output all registered rules as JSON when script ends."""
+        if not _rule_registry:
+            return
+
+        # Execute all rules and collect their JSON IR
+        rules_json = [rule.execute() for rule in _rule_registry]
+
+        # Output to stdout for Go loader to capture
+        print(json.dumps(rules_json))
+
+    # Register cleanup handler
+    atexit.register(_output_rules)
+
+
+def _register_rule(rule_obj: "Rule") -> None:
+    """
+    Register a rule for auto-execution.
+
+    Args:
+        rule_obj: The Rule instance to register
+    """
+    _rule_registry.append(rule_obj)
+
+    # Enable auto-execution on first rule registration
+    # Check if module is being executed directly (not imported)
+    frame = sys._getframe(2)  # Get caller's frame (the module defining the rule)
+    if frame.f_globals.get("__name__") == "__main__":
+        _enable_auto_execute()
+
+
+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:
+        rule_obj = Rule(id=id, severity=severity, func=func, cwe=cwe, owasp=owasp)
+        _register_rule(rule_obj)
+        return rule_obj
+
+    return decorator