cobraphp 0.1.0.dev1__py3-none-any.whl

cobraphp/analysis/_defuse_builder.py

@@ -0,0 +1,402 @@
+"""Intra-procedural def-use chain and inter-procedural edge construction.
+
+Phase 2: AST-based def-use chains create cross-statement edges within functions.
+Phase 3: CallGraph creates cross-function edges (argument->parameter, return->callsite).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import cast
+
+from php_parser_py import AST, Node
+
+from ._ast_types import load_php_ast_types
+from ._call_graph import CallGraph
+from ._taint_graph import DataFlowGraph
+from ._taint_rules import CALLABLE_TYPES
+
+# Accessor nodes whose taint is inherited from the base Expr_Variable.
+_ACCESSOR_NODE_TYPES = frozenset({"Expr_ArrayDimFetch", "Expr_PropertyFetch"})
+
+# Compound assignments (`+=`, `.=`, ...): the target keeps its old value and
+# folds in the RHS, so the target variable node itself becomes the definition.
+_COMPOUND_ASSIGN_TYPES = load_php_ast_types()[2] - {"Expr_Assign"}
+
+# Callables with their own variable scope. An arrow function is absent: PHP
+# gives it read access to the enclosing scope's variables.
+_NESTED_SCOPE_TYPES = frozenset({"Stmt_Function", "Stmt_ClassMethod", "Expr_Closure"})
+
+
+def build_intraproc_edges(ast: AST, dataflow_graph: DataFlowGraph) -> None:
+    """Build variable def-use chain edges for all functions and file-level code."""
+    for func_node in ast.nodes(lambda n: n.node_type in CALLABLE_TYPES):
+        param_defs = _extract_param_defs(ast, func_node)
+        body_stmts = _get_body_statements(ast, func_node)
+        _build_defuse_for_stmts(ast, body_stmts, dataflow_graph, initial_defs=param_defs)
+
+    for file_node in ast.file_nodes():
+        top_stmts = [c for c in ast.succ(file_node) if c.node_type.startswith("Stmt_")]
+        _build_defuse_for_stmts(ast, top_stmts, dataflow_graph)
+
+    _build_accessor_chain_edges(ast, dataflow_graph)
+
+
+def build_interproc_edges(
+    ast: AST,
+    call_graph: CallGraph,
+    dataflow_graph: DataFlowGraph,
+) -> None:
+    """Build argument->parameter and return->callsite edges via CallGraph."""
+    for cg_node_id in call_graph.storage.get_nodes():
+        node_type = call_graph.storage.get_node_prop(cg_node_id, "node_type")
+        if node_type != "call_site":
+            continue
+
+        site_node = call_graph.get_site_node(cg_node_id)
+        callees = call_graph.get_callees(cg_node_id)
+
+        if not callees:
+            _build_overapprox_edges(ast, site_node.argument_ids, cg_node_id, dataflow_graph)
+            continue
+
+        for callee in callees:
+            _build_arg_to_param_edges(
+                ast,
+                site_node.argument_ids,
+                callee.parameter_ids,
+                dataflow_graph,
+            )
+            _build_return_to_callsite_edges(
+                ast,
+                callee.node_id,
+                cg_node_id,
+                dataflow_graph,
+            )
+
+
+def _extract_param_defs(ast: AST, func_node: Node) -> dict[str, str]:
+    """Extract parameter variable definitions: var_name -> param_var_node_id."""
+    param_defs: dict[str, str] = {}
+    for child in ast.succ(func_node):
+        if child.node_type != "Param":
+            continue
+        for param_child in ast.succ(child):
+            if param_child.node_type != "Expr_Variable":
+                continue
+            var_name = param_child.all_properties.get("name", "")
+            if var_name:
+                param_defs[cast(str, var_name)] = param_child.id
+    return param_defs
+
+
+def _get_body_statements(ast: AST, func_node: Node) -> list[Node]:
+    """Extract ordered statement children from a callable node."""
+    return [child for child in ast.succ(func_node) if child.node_type.startswith("Stmt_")]
+
+
+def _build_defuse_for_stmts(
+    ast: AST,
+    stmts: list[Node],
+    dataflow_graph: DataFlowGraph,
+    initial_defs: dict[str, str] | None = None,
+) -> None:
+    """Build reaching-definition def-use chains across statements."""
+    var_defs: dict[str, str] = dict(initial_defs) if initial_defs else {}
+
+    for stmt in stmts:
+        _connect_uses_to_defs(ast, stmt, var_defs, dataflow_graph)
+        for var_def in _find_variable_defs(ast, stmt):
+            _link_compound_rhs(var_def, dataflow_graph)
+            var_defs[var_def.name] = var_def.node_id
+
+
+def _connect_uses_to_defs(
+    ast: AST,
+    stmt: Node,
+    var_defs: dict[str, str],
+    dataflow_graph: DataFlowGraph,
+) -> None:
+    """Connect variable uses in a statement to their definitions."""
+    uses = _find_variable_uses(ast, stmt)
+    for use_node_id, var_name in uses:
+        if var_name not in var_defs:
+            continue
+        def_node_id = var_defs[var_name]
+        if def_node_id == use_node_id:
+            continue
+        _ensure_node(dataflow_graph, def_node_id)
+        _ensure_node(dataflow_graph, use_node_id)
+        dataflow_graph.add_structural_edge(def_node_id, use_node_id)
+
+
+@dataclass(frozen=True)
+class _VarDef:
+    """One variable definition inside a statement.
+
+    ``node_id`` carries the assigned value. ``rhs_id`` is set for a compound
+    assignment, whose RHS feeds the target variable node.
+    """
+
+    name: str
+    node_id: str
+    rhs_id: str | None = None
+
+
+def _link_compound_rhs(var_def: _VarDef, dataflow_graph: DataFlowGraph) -> None:
+    # A compound assignment's RHS flows into the target it updates.
+    if var_def.rhs_id is None:
+        return
+    _ensure_node(dataflow_graph, var_def.rhs_id)
+    _ensure_node(dataflow_graph, var_def.node_id)
+    dataflow_graph.add_structural_edge(var_def.rhs_id, var_def.node_id)
+
+
+def _find_variable_defs(ast: AST, stmt: Node) -> list[_VarDef]:
+    """Find variable definitions in a statement, outside nested scopes."""
+    # Post-order over an explicit stack of child iterators: children before
+    # their parent, which is evaluation order. A nested scope is skipped with
+    # its subtree. No recursion, so a deeply nested expression fits.
+    result: list[_VarDef] = []
+    if stmt.node_type in _NESTED_SCOPE_TYPES:
+        return result
+    pending: list[tuple[Node, Iterator[Node]]] = [(stmt, iter(ast.succ(stmt)))]
+    while pending:
+        node, children = pending[-1]
+        child = next(children, None)
+        if child is None:
+            pending.pop()
+            var_def = _assignment_def(ast, node)
+            if var_def is not None:
+                result.append(var_def)
+            continue
+        if child.node_type not in _NESTED_SCOPE_TYPES:
+            pending.append((child, iter(ast.succ(child))))
+    return result
+
+
+def _assignment_def(ast: AST, node: Node) -> _VarDef | None:
+    # The definition an assignment to a plain variable makes, else None.
+    target = _assignment_target(ast, node)
+    if target is None:
+        return None
+    var_name, lhs, rhs = target
+    if node.node_type == "Expr_Assign":
+        return _VarDef(var_name, _assigned_value_id(ast, rhs))
+    return _VarDef(var_name, lhs.id, rhs_id=rhs.id)
+
+
+def _assignment_target(ast: AST, node: Node) -> tuple[str, Node, Node] | None:
+    # (variable name, LHS, RHS) of an assignment to a plain variable, else None.
+    if node.node_type != "Expr_Assign" and node.node_type not in _COMPOUND_ASSIGN_TYPES:
+        return None
+    children = list(ast.succ(node))
+    if len(children) < 2 or children[0].node_type != "Expr_Variable":
+        return None
+    lhs, rhs = children[0], children[1]
+    var_name = cast(str, lhs.all_properties.get("name", ""))
+    if not var_name:
+        return None
+    return var_name, lhs, rhs
+
+
+def _assigned_value_id(ast: AST, expr: Node) -> str:
+    # The node holding an expression's value: a nested assignment yields the
+    # definition node it makes, so `$a = $b = x` gives both the same value.
+    # A plain assignment passes its RHS's value on; a loop follows the chain.
+    while True:
+        target = _assignment_target(ast, expr)
+        if target is None:
+            return expr.id
+        _, lhs, rhs = target
+        if expr.node_type != "Expr_Assign":
+            return lhs.id
+        expr = rhs
+
+
+def _find_variable_uses(ast: AST, stmt: Node) -> list[tuple[str, str]]:
+    """Find variable uses excluding assignment LHS: list of (node_id, var_name)."""
+    # Pre-order over an explicit stack: children are pushed reversed so they
+    # pop in source order. No recursion, so a deeply nested expression fits.
+    result: list[tuple[str, str]] = []
+    lhs_ids: set[str] = set()
+    pending: list[Node] = [stmt]
+    while pending:
+        node = pending.pop()
+        pending.extend(reversed(_use_scan_children(ast, node, result, lhs_ids)))
+    return result
+
+
+def _use_scan_children(
+    ast: AST,
+    node: Node,
+    result: list[tuple[str, str]],
+    lhs_ids: set[str],
+) -> list[Node]:
+    """Record node if it is a variable use; return the children to scan next, in order."""
+    if node.node_type == "Expr_Assign":
+        # Only the RHS is read; the LHS is a definition.
+        children = list(ast.succ(node))
+        if len(children) < 2:
+            return []
+        lhs_ids.add(children[0].id)
+        return [children[1]]
+    if node.node_type in _NESTED_SCOPE_TYPES:
+        # Only a closure's `use (...)` list reads the enclosing scope.
+        return _closure_use_children(ast, node)
+
+    if node.node_type == "Expr_Variable" and node.id not in lhs_ids:
+        var_name = node.all_properties.get("name", "")
+        # Skip superglobals — they are sources, not def-use targets
+        if var_name and not str(var_name).startswith("_"):
+            result.append((node.id, cast(str, var_name)))
+
+    return list(ast.succ(node))
+
+
+def _closure_use_children(ast: AST, node: Node) -> list[Node]:
+    # A closure's captured-variable list; empty for any other callable.
+    return [child for child in ast.succ(node) if child.node_type == "ClosureUse"]
+
+
+def _build_accessor_chain_edges(ast: AST, dataflow_graph: DataFlowGraph) -> None:
+    """Create edges from Expr_Variable to its enclosing accessor chain.
+
+    A tainted object/array variable must propagate taint to its element and
+    property reads. Semgrep only flags these intraprocedurally; when the
+    variable is tainted via a call-graph return edge, the enclosing
+    ArrayDimFetch/PropertyFetch nodes have no incoming edge and stay untainted.
+    """
+    for node in ast.nodes():
+        if node.node_type != "Expr_Variable":
+            continue
+        if not dataflow_graph.storage.contains_node(node.id):
+            continue
+        _walk_accessor_parents(ast, node, dataflow_graph)
+
+
+def _walk_accessor_parents(
+    ast: AST,
+    node: Node,
+    dataflow_graph: DataFlowGraph,
+) -> None:
+    """Walk up from variable through accessor parents, adding edges."""
+    current = node
+    while True:
+        parents = list(ast.prev(current))
+        parent = next(
+            (p for p in parents if p.node_type in _ACCESSOR_NODE_TYPES),
+            None,
+        )
+        if parent is None:
+            break
+        _ensure_node(dataflow_graph, parent.id)
+        dataflow_graph.add_structural_edge(current.id, parent.id)
+        current = parent
+
+
+def _build_arg_to_param_edges(
+    ast: AST,
+    argument_ids: list[str],
+    parameter_ids: list[str],
+    dataflow_graph: DataFlowGraph,
+) -> None:
+    """Create edges from call site arguments to callee parameters by position."""
+    min_len = min(len(argument_ids), len(parameter_ids))
+    for i in range(min_len):
+        arg_expr_id = _get_arg_expression_id(ast, argument_ids[i])
+        if not arg_expr_id:
+            continue
+        param_var_id = _get_param_variable_id(ast, parameter_ids[i])
+        if not param_var_id:
+            continue
+        _ensure_node(dataflow_graph, arg_expr_id)
+        _ensure_node(dataflow_graph, param_var_id)
+        dataflow_graph.add_structural_edge(arg_expr_id, param_var_id)
+
+
+def _build_overapprox_edges(
+    ast: AST,
+    argument_ids: list[str],
+    callsite_id: str,
+    dataflow_graph: DataFlowGraph,
+) -> None:
+    """Over-approximate taint through an unresolved call.
+
+    For a call site with no resolved callee (library, builtin, or dynamic
+    dispatch), connect each argument expression to the call-site node so a
+    tainted argument taints the call's result. Semgrep OSS provides no
+    interprocedural taint to fall back on.
+    """
+    for arg_node_id in argument_ids:
+        arg_expr_id = _get_arg_expression_id(ast, arg_node_id)
+        if not arg_expr_id:
+            continue
+        _ensure_node(dataflow_graph, arg_expr_id)
+        _ensure_node(dataflow_graph, callsite_id)
+        dataflow_graph.add_structural_edge(arg_expr_id, callsite_id)
+
+
+def _build_return_to_callsite_edges(
+    ast: AST,
+    callee_func_id: str,
+    callsite_id: str,
+    dataflow_graph: DataFlowGraph,
+) -> None:
+    """Create edges from callee return expressions to call site node."""
+    func_node = ast.node(callee_func_id)
+    if func_node is None:
+        return
+
+    for return_stmt in _own_return_statements(ast, func_node):
+        return_children = list(ast.succ(return_stmt))
+        if not return_children:
+            continue
+        return_expr = return_children[0]
+        _ensure_node(dataflow_graph, return_expr.id)
+        _ensure_node(dataflow_graph, callsite_id)
+        dataflow_graph.add_structural_edge(return_expr.id, callsite_id)
+
+
+def _own_return_statements(ast: AST, func_node: Node) -> list[Node]:
+    # Stmt_Return nodes at any depth in a callable's body, excluding those of
+    # callables nested inside it.
+    found: list[Node] = []
+    pending = list(ast.succ(func_node))
+    while pending:
+        node = pending.pop()
+        if node.node_type in CALLABLE_TYPES:
+            continue
+        if node.node_type == "Stmt_Return":
+            found.append(node)
+        pending.extend(ast.succ(node))
+    return found
+
+
+def _get_arg_expression_id(ast: AST, arg_node_id: str) -> str | None:
+    """Get the expression node ID inside an Arg wrapper node."""
+    arg_node = ast.node(arg_node_id)
+    if arg_node is None:
+        return None
+    children = list(ast.succ(arg_node))
+    if not children:
+        return None
+    return cast(str, children[0].id)
+
+
+def _get_param_variable_id(ast: AST, param_node_id: str) -> str | None:
+    """Get the Expr_Variable node ID inside a Param wrapper node."""
+    param_node = ast.node(param_node_id)
+    if param_node is None:
+        return None
+    for child in ast.succ(param_node):
+        if child.node_type == "Expr_Variable":
+            return cast(str, child.id)
+    return None
+
+
+def _ensure_node(dataflow_graph: DataFlowGraph, node_id: str) -> None:
+    """Ensure node exists in graph."""
+    if not dataflow_graph.storage.contains_node(node_id):
+        dataflow_graph.add_dataflow_node(node_id)

cobraphp/analysis/_errors.py

@@ -0,0 +1,17 @@
+"""Errors of the static analysis."""
+
+from __future__ import annotations
+
+from ..errors import CobraPhpError
+
+
+class StaticAnalysisError(CobraPhpError):
+    """Semgrep failed, its output was malformed, or the AST is malformed."""
+
+
+class AnalysisTimeoutError(StaticAnalysisError):
+    """A Semgrep run exceeded the time limit; carries `timeout_seconds`."""
+
+    def __init__(self, timeout_seconds: int):
+        super().__init__(f"Analysis timed out after {timeout_seconds} seconds")
+        self.timeout_seconds = timeout_seconds

cobraphp/analysis/_file_filter.py

@@ -0,0 +1,172 @@
+"""Shared file filter for parse_project calls.
+
+Excludes third-party and generated code from PHP AST parsing via three layers:
+convention directories (vendor/, node_modules/), named bundle files
+(yiilite.php), and framework code detected by an identity-marker file — either
+the whole marker subtree or only named subpaths under it (for monorepo
+frameworks that also hold application code).
+"""
+
+from __future__ import annotations
+
+import logging
+import tomllib
+from collections.abc import Callable
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_EXCLUDED_DIRS = frozenset(
+    {
+        "vendor",
+        "vendors",
+        "node_modules",
+        "generated",
+        ".git",
+        "patches",
+        ".porifera_backup",
+    }
+)
+
+# yiilite.php is the whole framework concatenated into one file: not business
+# logic, it duplicates class definitions from the separate framework files, and
+# its size makes format-preserving instrumentation exhaust the printer's memory.
+_EXCLUDED_FILES = frozenset({"yiilite.php"})
+
+_REGISTRY_PATH = resources.files("cobraphp.analysis") / "frameworks.toml"
+# Bytes of a marker file head scanned for its signature substring; a bootstrap
+# class declaration always appears near the top.
+_MARKER_SCAN_BYTES = 8192
+
+
+@dataclass(frozen=True)
+class _FrameworkSignature:
+    """Identity marker locating one vendored framework's subtree root.
+
+    Attributes:
+        name: Framework identifier, logged on exclusion.
+        marker: POSIX relative-path suffix of the identity bootstrap file.
+        contains: Substring required in the marker file head.
+        exclude_subpaths: Subpaths under the detected root to exclude. Empty
+            excludes the whole subtree; non-empty keeps the rest as business
+            logic (e.g. a monorepo framework that also holds application code).
+    """
+
+    name: str
+    marker: str
+    contains: str
+    exclude_subpaths: tuple[str, ...] = ()
+
+
+def _load_signatures() -> tuple[_FrameworkSignature, ...]:
+    """Load framework identity markers from the TOML registry."""
+    raw = tomllib.loads(_REGISTRY_PATH.read_text(encoding="utf-8"))
+    return tuple(
+        _FrameworkSignature(
+            name=e["name"],
+            marker=e["marker"],
+            contains=e["contains"],
+            exclude_subpaths=tuple(e.get("exclude_subpaths", ())),
+        )
+        for e in raw["framework"]
+    )
+
+
+_SIGNATURES = _load_signatures()
+
+
+def app_file_filter(path: Path) -> bool:
+    """Return True for application PHP files, excluding vendor/generated dirs."""
+    if path.suffix != ".php":
+        return False
+    if path.name in _EXCLUDED_FILES:
+        return False
+    return not any(part in _EXCLUDED_DIRS for part in path.parts)
+
+
+def _marker_root(candidate: Path, signature: _FrameworkSignature) -> Path | None:
+    """Return the subtree root if candidate is signature's identity marker.
+
+    An unreadable candidate is not a marker: it is skipped with a warning.
+    """
+    marker_parts = Path(signature.marker).parts
+    if candidate.parts[-len(marker_parts) :] != marker_parts:
+        return None
+    try:
+        head = candidate.read_bytes()[:_MARKER_SCAN_BYTES].decode("latin-1")
+    except OSError as exc:
+        logger.warning("skipping unreadable framework marker: name=%s path=%s error=%s", signature.name, candidate, exc)
+        return None
+    if signature.contains not in head:
+        return None
+    depth = len(marker_parts)
+    return candidate.parents[depth - 1]
+
+
+def _excluded_dirs_for(root: Path, signature: _FrameworkSignature) -> list[Path]:
+    """Absolute dirs to exclude for one detected framework root.
+
+    Empty ``exclude_subpaths`` excludes the whole subtree; otherwise only the
+    named subpaths under the root, keeping the rest as application code.
+    """
+    if not signature.exclude_subpaths:
+        return [root]
+    return [root / sub for sub in signature.exclude_subpaths]
+
+
+def framework_excluded_dirs(project_root: Path) -> frozenset[Path]:
+    """Resolve registry signatures to excluded framework directories.
+
+    Detects every vendored-framework subtree under project_root and returns
+    the directories to exclude from PHP source processing. Shared by AST
+    parsing (make_app_file_filter) and source normalization so both apply one
+    framework-exclusion set and keep their line numbers consistent.
+
+    Args:
+        project_root: Project directory to scan for framework markers. Returned
+            paths are anchored to it; the caller resolves it when its consumers
+            supply resolved paths.
+
+    Returns:
+        Directories under project_root to exclude as framework code.
+    """
+    excluded: set[Path] = set()
+    for signature in _SIGNATURES:
+        basename = Path(signature.marker).name
+        for candidate in project_root.rglob(basename):
+            root = _marker_root(candidate, signature)
+            if root is None:
+                continue
+            dirs = _excluded_dirs_for(root, signature)
+            excluded.update(dirs)
+            logger.info(
+                "excluding framework dirs: name=%s root=%s dirs=%s",
+                signature.name,
+                root,
+                dirs,
+            )
+    return frozenset(excluded)
+
+
+def make_app_file_filter(project_root: Path) -> Callable[[Path], bool]:
+    """Build a filter excluding vendor/generated dirs and framework subtrees.
+
+    Detects framework subtree roots under project_root once, then returns a
+    predicate over the absolute paths parse_project supplies.
+
+    Args:
+        project_root: Project directory passed to parse_project.
+
+    Returns:
+        Predicate returning True for application PHP files.
+    """
+    excluded_dirs = framework_excluded_dirs(project_root.resolve())
+
+    def _filter(path: Path) -> bool:
+        if not app_file_filter(path):
+            return False
+        return not any(path.is_relative_to(excluded) for excluded in excluded_dirs)
+
+    return _filter

cobraphp/analysis/_project_root.py

@@ -0,0 +1,29 @@
+"""Project root path of a parsed project AST.
+
+The Semgrep runner reads its scan root here: the project node's
+``absolutePath`` is required, with no fallback to file nodes.
+"""
+
+from __future__ import annotations
+
+from php_parser_py import AST
+
+
+def project_root_text(project_ast: AST) -> str:
+    """Return the project node's ``absolutePath`` unchanged.
+
+    A directory name may begin or end with a space, so the path is never
+    stripped; only a value that is blank is rejected.
+
+    Raises:
+        ValueError: If the AST has no project node, or the project node has no
+            path, an empty path, or a whitespace-only path.
+    """
+    try:
+        project_node = project_ast.project_node()
+    except KeyError as exc:
+        raise ValueError("Cannot resolve project root from AST: no project node") from exc
+    path_val = project_node.get("absolutePath")
+    if not isinstance(path_val, str) or not path_val.strip():
+        raise ValueError("Cannot resolve project root from AST: project node has no absolutePath")
+    return path_val