cobraphp 0.1.0.dev1__py3-none-any.whl

cobraphp/__init__.py

@@ -0,0 +1,60 @@
+"""Python interface of CobraPHP. The implementation waits for the CobraPHP jar; see docs/design.md."""
+
+from cobraphp.config import AnalysisConfig, StorageImplementation, TargetFileSystem
+from cobraphp.entries import analyze_project, build_project, diff_results, validate_document_sets
+from cobraphp.errors import (
+    CobraPhpError,
+    DependencyUnavailableError,
+    DocumentSetInvalidError,
+    GraphExportError,
+    ParsingFailedError,
+    ProjectNotFoundError,
+)
+from cobraphp.graphs import GraphEdge, GraphExport, GraphNode, LabelOrder, read_graph_export
+from cobraphp.project import BuiltProject
+from cobraphp.results import (
+    CallSite,
+    Diagnostic,
+    DiffReport,
+    Finding,
+    Location,
+    Output,
+    TaintSource,
+    Unanalyzed,
+    UnanalyzedReason,
+    ValidationReport,
+    VulnerableCallPath,
+)
+
+__all__ = [
+    "AnalysisConfig",
+    "BuiltProject",
+    "CallSite",
+    "CobraPhpError",
+    "DependencyUnavailableError",
+    "Diagnostic",
+    "DiffReport",
+    "DocumentSetInvalidError",
+    "Finding",
+    "GraphEdge",
+    "GraphExport",
+    "GraphExportError",
+    "GraphNode",
+    "LabelOrder",
+    "Location",
+    "Output",
+    "ParsingFailedError",
+    "ProjectNotFoundError",
+    "StorageImplementation",
+    "TaintSource",
+    "TargetFileSystem",
+    "Unanalyzed",
+    "UnanalyzedReason",
+    "ValidationReport",
+    "VulnerableCallPath",
+    "analyze_project",
+    "build_project",
+    "diff_results",
+    "read_graph_export",
+    "validate_document_sets",
+]

cobraphp/_backend.py

@@ -0,0 +1,47 @@
+"""The internal backend protocol (docs/design.md, Backend Boundary).
+
+Every public function and `BuiltProject` method calls one operation of this protocol. A backend that runs the
+CobraPHP jar in a JVM and a backend that calls a native shared library both implement it. No implementation exists.
+"""
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import NewType, Protocol
+
+from cobraphp.config import AnalysisConfig
+from cobraphp.results import DiffReport, Output, ValidationReport
+
+BuiltHandle = NewType("BuiltHandle", int)
+"""An opaque handle of a built project; its value means nothing to the caller."""
+
+
+class Backend(Protocol):
+    """The operations a backend provides. A failure raises the `*Error` class its code names."""
+
+    def analyze_project(self, project_dir: Path, config: AnalysisConfig) -> list[Output]:
+        """Run the one-shot analysis."""
+        ...
+
+    def build_project(self, project_dir: Path, config: AnalysisConfig) -> BuiltHandle:
+        """Build and freeze a project and return its handle."""
+        ...
+
+    def analyze_built(self, handle: BuiltHandle, config: AnalysisConfig) -> list[Output]:
+        """Analyze a built project; `config` carries the `build` fields of the build configuration."""
+        ...
+
+    def export_graphs(self, handle: BuiltHandle, output_file: Path) -> None:
+        """Write the graph export of a built project."""
+        ...
+
+    def close(self, handle: BuiltHandle) -> None:
+        """Release a built project; a second call has no effect."""
+        ...
+
+    def validate_document_sets(self, document_sets: Sequence[Path]) -> ValidationReport:
+        """Verify Document Sets."""
+        ...
+
+    def diff_results(self, before: Sequence[Output], after: Sequence[Output]) -> DiffReport:
+        """Compare two output lists by `Finding.id`."""
+        ...

cobraphp/_placeholder.py

@@ -0,0 +1,10 @@
+"""The body shared by every entry while the implementation does not exist."""
+
+from typing import NoReturn
+
+PLACEHOLDER_MESSAGE = "cobraphp declares its interface only: the implementation waits for the CobraPHP jar."
+
+
+def not_implemented() -> NoReturn:
+    """Raise `NotImplementedError` with `PLACEHOLDER_MESSAGE`."""
+    raise NotImplementedError(PLACEHOLDER_MESSAGE)

cobraphp/analysis/__init__.py

@@ -0,0 +1,60 @@
+"""Static analysis of a php-parser-py AST in Python: call graph, data-flow graph, backward slice.
+
+The call graph comes back as CCG records of `cobraphp.GraphExport`; Semgrep runs as the `semgrep` program
+to find the expressions each Source kind's rule matches. See docs/design-analysis-subpackage.md.
+"""
+
+from __future__ import annotations
+
+from php_parser_py import AST
+
+from ._call_builder import CallBuilder
+from ._errors import AnalysisTimeoutError, StaticAnalysisError
+from ._file_filter import make_app_file_filter
+from ._records import DataFlowGraph, backward_slice, call_graph_export, data_flow_graph
+from ._source_kinds import DATABASE, USER_INPUT
+from ._taint_propagator import TaintPropagator
+from ..graphs import GraphExport
+
+
+def build_call_graph(project_ast: AST) -> GraphExport:
+    """The call graph of `project_ast` as CCG records; runs no Semgrep.
+
+    Raises `StaticAnalysisError` when the AST is malformed.
+    """
+    return call_graph_export(project_ast, CallBuilder(project_ast).build())
+
+
+def build_data_flow(
+    project_ast: AST,
+    *,
+    timeout_seconds: int | None = None,
+    target_files: frozenset[str] | None = None,
+) -> DataFlowGraph:
+    """The data-flow graph of `project_ast` with the AST node ids each Source kind reaches.
+
+    Semgrep finds the expressions each Source kind's rule matches; def-use edges inside each function,
+    argument and return edges over the call graph, then a breadth-first walk from those expressions mark the
+    reached nodes. `timeout_seconds` bounds each Semgrep run; `target_files` (project-relative) restricts
+    Semgrep to those files, and when none of them exists Semgrep does not run.
+
+    Raises `DependencyUnavailableError` when the `semgrep` program is not on PATH, `AnalysisTimeoutError`
+    when a Semgrep run exceeds `timeout_seconds`, and `StaticAnalysisError` when Semgrep fails, its output is
+    malformed or the AST is malformed.
+    """
+    call_graph = CallBuilder(project_ast).build()
+    targets = None if target_files is None else set(target_files)
+    return data_flow_graph(TaintPropagator(project_ast, call_graph, timeout_seconds, targets).propagate())
+
+
+__all__ = [
+    "DATABASE",
+    "USER_INPUT",
+    "AnalysisTimeoutError",
+    "DataFlowGraph",
+    "StaticAnalysisError",
+    "backward_slice",
+    "build_call_graph",
+    "build_data_flow",
+    "make_app_file_filter",
+]

cobraphp/analysis/_ast_types.py

@@ -0,0 +1,17 @@
+"""Load the PHP AST node type sets of php_ast_types.toml."""
+
+from __future__ import annotations
+
+import functools
+import tomllib
+from importlib import resources
+
+
+@functools.cache
+def load_php_ast_types() -> tuple[frozenset[str], frozenset[str], frozenset[str]]:
+    """Return (constant, callable, assign) node type sets."""
+    raw = tomllib.loads((resources.files("cobraphp.analysis") / "php_ast_types.toml").read_text(encoding="utf-8"))
+    constant = frozenset(raw["constant_node_types"]["values"])
+    callable_ = frozenset(raw["callable_types"]["values"])
+    assign = frozenset(raw["assign_node_types"]["values"])
+    return constant, callable_, assign

cobraphp/analysis/_call_builder.py

@@ -0,0 +1,135 @@
+"""Build CallGraph from PHP AST by extracting function and method declarations and call sites."""
+
+from __future__ import annotations
+
+from php_parser_py import AST, Node, NodeNotInFileError
+
+from ._errors import StaticAnalysisError
+from ._call_graph import CallGraph
+from ._callee_index import CALL_SITE_TYPES, NAMED_CALLABLE_TYPES, CalleeIndex
+
+# PHP AST node types of anonymous callables; with the named ones, every callable declaration.
+CLOSURE_TYPE = "Expr_Closure"
+ARROW_FUNCTION_TYPE = "Expr_ArrowFunction"
+CALLABLE_DECL_TYPES = (*NAMED_CALLABLE_TYPES, CLOSURE_TYPE, ARROW_FUNCTION_TYPE)
+
+
+class CallBuilder:
+    """Builds CallGraph from PHP AST.
+
+    Attributes:
+        _ast: PHP project AST.
+    """
+
+    def __init__(self, ast: AST) -> None:
+        self._ast = ast
+
+    def build(self) -> CallGraph:
+        """Build and return populated CallGraph from PHP AST.
+
+        Returns:
+            Populated CallGraph instance.
+
+        Raises:
+            StaticAnalysisError: Invalid AST structure or missing required properties.
+        """
+        call_graph = CallGraph()
+        callee_index = self._build_callables(call_graph)
+        self._build_call_sites(call_graph, callee_index)
+        return call_graph
+
+    def _build_callables(self, call_graph: CallGraph) -> CalleeIndex:
+        """Register every callable declaration; index the named ones as callees.
+
+        Closures and arrow functions carry synthetic names and are never
+        resolution targets.
+        """
+        callee_index = CalleeIndex(self._ast)
+        for callable_node in self._ast.nodes(lambda n: n.node_type in CALLABLE_DECL_TYPES):
+            callable_name = self._register_callable(call_graph, callable_node)
+            if callable_node.node_type in NAMED_CALLABLE_TYPES:
+                callee_index.add(callable_node, callable_name)
+        return callee_index
+
+    def _register_callable(self, call_graph: CallGraph, callable_node: Node) -> str:
+        """Register a single callable declaration in the call graph; return its name."""
+        callable_id = callable_node.id
+        callable_name = self._extract_callable_name(callable_node)
+
+        param_nodes = [child for child in self._ast.succ(callable_node) if child.node_type == "Param"]
+        parameter_ids = [param.id for param in param_nodes]
+
+        func_node = call_graph.add_func_decl(node_id=callable_id)
+        func_node.name = callable_name
+        func_node.parameter_ids = parameter_ids
+
+        return_type = self._extract_return_type(callable_node)
+        if return_type:
+            func_node.return_type_hint = return_type
+        return callable_name
+
+    def _extract_callable_name(self, callable_node: Node) -> str:
+        """Extract name from a callable declaration node."""
+        if callable_node.node_type in NAMED_CALLABLE_TYPES:
+            identifier_node = next(
+                (child for child in self._ast.succ(callable_node) if child.node_type == "Identifier"), None
+            )
+            if not identifier_node:
+                raise StaticAnalysisError(f"Callable node {callable_node.id} missing Identifier child for name")
+            callable_name = identifier_node.all_properties.get("name", "")
+            if not callable_name:
+                raise StaticAnalysisError(f"Callable {callable_node.id} Identifier missing 'name' property")
+            return str(callable_name)
+        if callable_node.node_type == CLOSURE_TYPE:
+            return "{closure}"
+        if callable_node.node_type == ARROW_FUNCTION_TYPE:
+            return "{arrow}"
+        return "{unknown}"
+
+    def _extract_return_type(self, callable_node: Node) -> str:
+        """Extract return type hint from a callable node, if present."""
+        identifier_children = [child for child in self._ast.succ(callable_node) if child.node_type == "Identifier"]
+
+        if callable_node.node_type in NAMED_CALLABLE_TYPES:
+            if len(identifier_children) >= 2:
+                return str(identifier_children[1].all_properties.get("name", ""))
+        elif callable_node.node_type in (CLOSURE_TYPE, ARROW_FUNCTION_TYPE):
+            if len(identifier_children) >= 1:
+                return str(identifier_children[0].all_properties.get("name", ""))
+        return ""
+
+    def _build_call_sites(self, call_graph: CallGraph, callee_index: CalleeIndex) -> None:
+        """Extract call sites and link to callees."""
+        call_site_nodes = list(self._ast.nodes(lambda n: n.node_type in CALL_SITE_TYPES))
+
+        for call_site_node in call_site_nodes:
+            try:
+                self._register_call_site(call_graph, call_site_node, callee_index)
+            except (KeyError, NodeNotInFileError) as e:
+                raise StaticAnalysisError(
+                    f"Failed to extract call site metadata from node {call_site_node.id}: {e}"
+                ) from e
+
+    def _register_call_site(self, call_graph: CallGraph, call_site_node: Node, callee_index: CalleeIndex) -> None:
+        """Register a call site, including one with a dynamic name, and link its callee when resolved."""
+        call_site_id = call_site_node.id
+        site_node = call_graph.add_call_site(node_id=call_site_id)
+        site_node.argument_ids = [child.id for child in self._ast.succ(call_site_node) if child.node_type == "Arg"]
+        site_node.caller_id = self._resolve_caller(call_site_id)
+
+        callee_func = callee_index.resolve(call_site_node)
+        if callee_func is not None:
+            call_graph.add_call_edge(callsite_node_id=call_site_id, callee_node_id=callee_func.id)
+
+    def _resolve_caller(self, call_site_id: str) -> str:
+        """Find the enclosing callable for a call site, or use file node."""
+        call_site_node = self._ast.node(call_site_id)
+        for ancestor in self._ast.ancestors(call_site_node):
+            if ancestor.node_type in CALLABLE_DECL_TYPES:
+                return str(ancestor.id)
+
+        containing_file = self._ast.get_file_node(call_site_id)
+        file_path = containing_file.get("absolutePath")
+        if not file_path:
+            raise StaticAnalysisError(f"File node for call site {call_site_id} has no absolutePath property")
+        return str(file_path)

cobraphp/analysis/_call_graph.py

@@ -0,0 +1,211 @@
+"""Call graph with function declarations, call sites, and edges."""
+
+from __future__ import annotations
+
+from typing import cast
+
+from cpg2py import AbcGraphQuerier, Storage
+
+from ._errors import StaticAnalysisError
+from ._call_graph_nodes import CallEdge, CallNode, FuncNode, SiteNode
+
+__all__ = ["CallGraph", "CallNode", "FuncNode", "SiteNode", "CallEdge"]
+
+
+class CallGraph(AbcGraphQuerier[CallNode, CallEdge]):  # type: ignore[misc]
+    """Call graph tracking function declarations and call sites.
+
+    Uses cpg2py.Storage backend for directed multigraph representation.
+    Each node stores CallNode metadata; edges store CallEdge metadata.
+
+    Attributes:
+        storage: Underlying cpg2py Storage instance.
+
+    """
+
+    def __init__(self) -> None:
+        """Initialize CallGraph with separate Storage instance."""
+        storage = Storage()
+        super().__init__(target=storage, maxdepth=-1)
+
+    def node(self, whose_id_is: str) -> CallNode | None:
+        """Returns FuncNode or SiteNode by ID, None if not found."""
+        if not self.storage.contains_node(whose_id_is):
+            return None
+        node_type = self.storage.get_node_prop(whose_id_is, "node_type")
+        if node_type == "function_declaration":
+            return FuncNode(self.storage, whose_id_is)
+        if node_type == "call_site":
+            return SiteNode(self.storage, whose_id_is)
+        return None
+
+    def edge(self, fid: str, tid: str, eid: str) -> CallEdge | None:
+        """Returns CallEdge by source, target, edge type, None if not found."""
+        edge_id = (fid, tid, eid)
+        if not self.storage.contains_edge(edge_id):
+            return None
+        return CallEdge(self.storage, fid, tid, eid)
+
+    # -- Mutation: add nodes and edges --
+
+    def add_func_decl(self, node_id: str) -> FuncNode:
+        """Add function declaration node.
+
+        Raises:
+            ValueError: If node_id is empty.
+            StaticAnalysisError: If node_id already exists.
+
+        """
+        self._validate_new_node(node_id)
+        self.storage.add_node(node_id)
+        return self._init_func_node(node_id, is_file=False)
+
+    def add_file_node(self, file_path: str) -> FuncNode:
+        """Add file-level container node for top-level code.
+
+        Raises:
+            ValueError: If file_path is empty.
+            StaticAnalysisError: If file_path already exists.
+
+        """
+        if not file_path:
+            raise ValueError("file_path must be non-empty")
+        if self.storage.contains_node(file_path):
+            msg = f"File node {file_path} already exists"
+            raise StaticAnalysisError(msg)
+        self.storage.add_node(file_path)
+        func_node = self._init_func_node(file_path, is_file=True)
+        func_node.name = file_path
+        return func_node
+
+    def add_call_site(self, node_id: str) -> SiteNode:
+        """Add call site node.
+
+        Raises:
+            ValueError: If node_id is empty.
+            StaticAnalysisError: If node_id already exists.
+
+        """
+        self._validate_new_node(node_id)
+        self.storage.add_node(node_id)
+        site_node = SiteNode(self.storage, node_id)
+        site_node.argument_ids = []
+        return site_node
+
+    def add_call_edge(self, callsite_node_id: str, callee_node_id: str) -> CallEdge:
+        """Add call edge from callsite to callee.
+
+        Raises:
+            ValueError: If an ID is empty.
+            StaticAnalysisError: If a node doesn't exist.
+
+        """
+        self._validate_edge_endpoints(callsite_node_id, callee_node_id)
+        edge_id = (callsite_node_id, callee_node_id, "CALLS")
+        self.storage.add_edge(edge_id)
+        return CallEdge(self.storage, callsite_node_id, callee_node_id, "CALLS")
+
+    # -- Query: traverse graph --
+
+    def get_callees(self, callsite_node_id: str) -> list[FuncNode]:
+        """Get callee function nodes for a callsite.
+
+        Raises:
+            StaticAnalysisError: If callsite_node does not exist.
+
+        """
+        self._require_node_exists(callsite_node_id, "Callsite")
+        callee_ids = list(self.storage.successors(callsite_node_id))
+        return [FuncNode(self.storage, cid) for cid in callee_ids]
+
+    def get_callsites(self, function_id: str) -> list[SiteNode]:
+        """Get callsite nodes that call this function.
+
+        Raises:
+            StaticAnalysisError: If function_id does not exist.
+
+        """
+        self._require_node_exists(function_id, "Function")
+        callsite_ids = list(self.storage.predecessors(function_id))
+        return [SiteNode(self.storage, sid) for sid in callsite_ids]
+
+    def get_caller_of_callsite(self, callsite_node_id: str) -> str:
+        """Get function or file containing this callsite.
+
+        Raises:
+            StaticAnalysisError: If callsite doesn't exist or
+                caller_id not set.
+
+        """
+        self._require_node_exists(callsite_node_id, "Callsite")
+        value = self.storage.get_node_prop(callsite_node_id, "caller_id")
+        if value is None:
+            raise StaticAnalysisError(f"Property 'caller_id' not found for callsite {callsite_node_id}")
+        return cast(str, value)
+
+    def get_func_node(self, node_id: str) -> FuncNode:
+        """Retrieve FuncNode wrapper by ID.
+
+        Raises:
+            StaticAnalysisError: If node doesn't exist or isn't
+                a function declaration.
+
+        """
+        self._require_node_exists(node_id, "Node")
+        node_type_str = self.storage.get_node_prop(node_id, "node_type")
+        if node_type_str != "function_declaration":
+            raise StaticAnalysisError(f"Node {node_id} is not a function declaration (type: {node_type_str})")
+        return FuncNode(self.storage, node_id)
+
+    def get_or_create_file_node(self, file_path: str) -> FuncNode:
+        """Get existing file node or create if not exists."""
+        if self.storage.contains_node(file_path):
+            return self.get_func_node(file_path)
+        return self.add_file_node(file_path)
+
+    def get_site_node(self, node_id: str) -> SiteNode:
+        """Retrieve SiteNode wrapper by ID.
+
+        Raises:
+            StaticAnalysisError: If node doesn't exist or isn't
+                a call site.
+
+        """
+        self._require_node_exists(node_id, "Node")
+        node_type_str = self.storage.get_node_prop(node_id, "node_type")
+        if node_type_str != "call_site":
+            raise StaticAnalysisError(f"Node {node_id} is not a call site (type: {node_type_str})")
+        return SiteNode(self.storage, node_id)
+
+    # -- Private helpers --
+
+    def _validate_new_node(self, node_id: str) -> None:
+        """Raise if node_id is empty or already exists."""
+        if not node_id:
+            raise ValueError("node_id must be non-empty")
+        if self.storage.contains_node(node_id):
+            raise StaticAnalysisError(f"Node {node_id} already exists")
+
+    def _validate_edge_endpoints(self, callsite_id: str, callee_id: str) -> None:
+        """Raise if edge endpoint IDs are empty or missing."""
+        if not callsite_id:
+            raise ValueError("callsite_node_id must be non-empty")
+        if not callee_id:
+            raise ValueError("callee_node_id must be non-empty")
+        if not self.storage.contains_node(callsite_id):
+            raise StaticAnalysisError(f"Callsite node {callsite_id} does not exist")
+        if not self.storage.contains_node(callee_id):
+            raise StaticAnalysisError(f"Callee node {callee_id} does not exist")
+
+    def _require_node_exists(self, node_id: str, label: str) -> None:
+        """Raise if node_id is not in storage."""
+        if not self.storage.contains_node(node_id):
+            raise StaticAnalysisError(f"{label} node {node_id} does not exist")
+
+    def _init_func_node(self, node_id: str, *, is_file: bool) -> FuncNode:
+        """Initialize a FuncNode with default property values."""
+        func_node = FuncNode(self.storage, node_id)
+        func_node.name = ""
+        func_node.parameter_ids = []
+        self.storage.set_node_prop(node_id, "is_file", is_file)
+        return func_node