cobraphp 0.1.0.dev1__py3-none-any.whl

cobraphp/analysis/_taint_propagator.py

@@ -0,0 +1,295 @@
+"""Build DataFlowGraph via Semgrep source identification + AST def-use chains + CallGraph inter-proc edges.
+
+Four-phase pipeline:
+1. Semgrep identifies tainted expressions per Source kind (intraprocedural)
+2. AST-based def-use chains create cross-statement edges within functions
+3. CallGraph creates cross-function edges (argument->parameter, return->callsite)
+4. BFS propagates taint from Semgrep seeds through the combined graph
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+from php_parser_py import AST, Node
+
+from ._errors import StaticAnalysisError
+from ._call_graph import CallGraph
+from ._defuse_builder import build_interproc_edges, build_intraproc_edges
+from ._semgrep_runner import (
+    OffsetIndex,
+    SemgrepResult,
+    build_file_id_index,
+    build_offset_index,
+    resolve_file_node_id,
+    resolve_project_path,
+    run_semgrep,
+)
+from ._taint_graph import DataFlowGraph
+from ._taint_rules import CONSTANT_NODE_TYPES, TAINT_RULES, select_seed_locations
+
+
+@dataclass(frozen=True)
+class _SeedExpansion:
+    """Shared context for the seed-expansion pass.
+
+    Bundles the AST, the dataflow graph being populated, and the accumulator
+    of newly discovered seeds so expansion helpers take one workspace rather
+    than threading four positional arguments each.
+    """
+
+    ast: AST
+    dataflow_graph: DataFlowGraph
+    expanded: dict[str, set[str]]
+
+    def record(self, node_id: str, source_types: set[str]) -> None:
+        """Ensure node exists and merge source_types into its expanded seeds."""
+        _ensure_node(self.dataflow_graph, node_id)
+        self.expanded.setdefault(node_id, set()).update(source_types)
+
+
+@dataclass(frozen=True)
+class _SeedCollection:
+    """Shared context for mapping Semgrep results into seed nodes.
+
+    Bundles the project path, file-id index, offset index, and graph so
+    result processing takes one workspace rather than threading positionally.
+    """
+
+    project_path: Path
+    file_id_by_path: dict[str, str]
+    offset_index: OffsetIndex
+    dataflow_graph: DataFlowGraph
+
+
+class TaintPropagator:
+    """Combines Semgrep intraprocedural taint identification with AST def-use chains and CallGraph inter-proc edges.
+
+    Attributes:
+        _ast: PHP project AST.
+        _call_graph: Populated CallGraph for inter-procedural analysis.
+        _timeout: Maximum execution time in seconds.
+    """
+
+    def __init__(
+        self,
+        ast: AST,
+        call_graph: CallGraph,
+        timeout: int | None,
+        target_files: set[str] | None = None,
+    ) -> None:
+        self._ast: AST = ast
+        self._call_graph: CallGraph = call_graph
+        self._timeout: int | None = timeout
+        self._target_files: set[str] | None = target_files
+
+    def propagate(self) -> DataFlowGraph:
+        """Run 4-phase taint analysis pipeline.
+
+        Returns:
+            Populated DataFlowGraph with connected taint paths.
+
+        Raises:
+            StaticAnalysisError: Semgrep execution failure or invalid AST structure.
+        """
+        dataflow_graph = DataFlowGraph()
+        project_path = resolve_project_path(self._ast)
+        if not project_path.is_dir():
+            raise StaticAnalysisError(f"Project path is not a directory: {project_path}")
+
+        collection = _SeedCollection(
+            project_path=project_path,
+            file_id_by_path=build_file_id_index(self._ast),
+            offset_index=build_offset_index(self._ast),
+            dataflow_graph=dataflow_graph,
+        )
+        seeds: dict[str, set[str]] = {}
+        for source_type in TAINT_RULES:
+            self._collect_semgrep_seeds(collection, source_type, seeds)
+
+        _expand_seeds_to_subexpressions(self._ast, seeds, dataflow_graph)
+        build_intraproc_edges(self._ast, dataflow_graph)
+        build_interproc_edges(self._ast, self._call_graph, dataflow_graph)
+        _propagate_taint(seeds, dataflow_graph)
+
+        return dataflow_graph
+
+    # ── Phase 1: Semgrep seed collection ─────────────────────────────
+
+    def _collect_semgrep_seeds(
+        self,
+        collection: _SeedCollection,
+        source_type: str,
+        seeds: dict[str, set[str]],
+    ) -> None:
+        """Run Semgrep for source_type, map results to AST nodes, populate seeds."""
+        rule_yaml = TAINT_RULES.get(source_type)
+        if not rule_yaml:
+            return
+
+        semgrep_output = run_semgrep(rule_yaml, collection.project_path, self._timeout, self._target_files)
+
+        for result in semgrep_output.get("results", []):
+            _process_semgrep_result(collection, result, source_type, seeds)
+
+
+# ── Phase 1: Semgrep result processing ──────────────────────────────
+
+
+def _process_semgrep_result(
+    collection: _SeedCollection,
+    result: SemgrepResult,
+    source_type: str,
+    seeds: dict[str, set[str]],
+) -> None:
+    """Map a single Semgrep result to an AST node and register as seed."""
+    locations = select_seed_locations(result, collection.project_path, collection.file_id_by_path)
+    for location in locations:
+        file_node_id = resolve_file_node_id(location.path, collection.project_path, collection.file_id_by_path)
+        if location.end_offset is None:
+            node_id = collection.offset_index.resolve(location.offset, file_node_id)
+        elif file_node_id is not None:
+            node_id = collection.offset_index.resolve_source_span(location.offset, location.end_offset, file_node_id)
+        else:
+            continue
+        if node_id:
+            seeds.setdefault(node_id, set()).add(source_type)
+            _ensure_node(collection.dataflow_graph, node_id, source_type)
+
+
+# ── Phase 1b: Seed expansion ────────────────────────────────────────
+
+
+def _expand_seeds_to_subexpressions(
+    ast: AST,
+    seeds: dict[str, set[str]],
+    dataflow_graph: DataFlowGraph,
+) -> None:
+    """Expand Semgrep seed nodes to their child expressions via AST edges.
+
+    Bridges statement-level Semgrep results to expression-level
+    nodes that Phase 2/3 edges connect at.
+    """
+    ctx = _SeedExpansion(ast=ast, dataflow_graph=dataflow_graph, expanded={})
+
+    for node_id, source_types in list(seeds.items()):
+        _expand_assignment_context(ctx, node_id, source_types)
+        _expand_node(ctx, node_id, source_types)
+
+    for node_id, source_types in ctx.expanded.items():
+        seeds.setdefault(node_id, set()).update(source_types)
+
+
+def _expand_assignment_context(
+    ctx: _SeedExpansion,
+    node_id: str,
+    source_types: set[str],
+) -> None:
+    """If node is LHS of an assignment, also expand the assignment RHS as seed."""
+    node = ctx.ast.node(node_id)
+    if node is None:
+        return
+
+    for parent in ctx.ast.prev(node):
+        if parent.node_type != "Expr_Assign":
+            continue
+        children = list(ctx.ast.succ(parent))
+        if len(children) < 2:
+            continue
+        if children[0].id != node_id:
+            continue
+        _seed_assignment_and_rhs(ctx, parent, children[1], source_types)
+
+
+def _seed_assignment_and_rhs(
+    ctx: _SeedExpansion,
+    parent: Node,
+    rhs: Node,
+    source_types: set[str],
+) -> None:
+    """Seed an assignment node and its RHS subexpressions."""
+    ctx.record(parent.id, source_types)
+
+    if rhs.node_type not in CONSTANT_NODE_TYPES:
+        ctx.record(rhs.id, source_types)
+        ctx.dataflow_graph.add_structural_edge(parent.id, rhs.id)
+        _expand_node(ctx, rhs.id, source_types)
+
+
+def _expand_node(
+    ctx: _SeedExpansion,
+    node_id: str,
+    source_types: set[str],
+) -> None:
+    """Expand a node to its AST descendants in pre-order, creating structural edges.
+
+    Walks with an explicit stack of child iterators, so a deeply nested
+    expression (a long generated concatenation) does not exhaust the Python
+    call stack. Constant children are skipped together with their subtrees.
+    """
+    node = ctx.ast.node(node_id)
+    if node is None:
+        return
+
+    pending: list[tuple[str, Iterator[Node]]] = [(node_id, iter(ctx.ast.succ(node)))]
+    while pending:
+        parent_id, children = pending[-1]
+        child = next(children, None)
+        if child is None:
+            pending.pop()
+            continue
+        if child.node_type in CONSTANT_NODE_TYPES:
+            continue
+        ctx.record(child.id, source_types)
+        ctx.dataflow_graph.add_structural_edge(parent_id, child.id)
+        child_node = ctx.ast.node(child.id)
+        if child_node is not None:
+            pending.append((child.id, iter(ctx.ast.succ(child_node))))
+
+
+# ── Phase 4: BFS taint propagation ──────────────────────────────────
+
+
+def _propagate_taint(
+    seeds: dict[str, set[str]],
+    dataflow_graph: DataFlowGraph,
+) -> None:
+    """BFS from seed nodes, propagating taint through graph edges."""
+    for source_type in TAINT_RULES:
+        seed_ids = [nid for nid, types in seeds.items() if source_type in types]
+        for current in dataflow_graph.reachable_from(seed_ids):
+            _mark_taint(dataflow_graph, current, source_type)
+
+
+def _mark_taint(
+    dataflow_graph: DataFlowGraph,
+    node_id: str,
+    source_type: str,
+) -> None:
+    """Mark a node with a taint source if not already present."""
+    df_node = dataflow_graph.get_dataflow_node(node_id)
+    if source_type not in df_node.taints:
+        current_taints = df_node.taints.copy()
+        current_taints.append(source_type)
+        df_node.taints = current_taints
+
+
+# ── Node helpers ─────────────────────────────────────────────────────
+
+
+def _ensure_node(
+    dataflow_graph: DataFlowGraph,
+    node_id: str,
+    source_type: str | None = None,
+) -> None:
+    """Ensure node exists in graph; optionally set initial taint."""
+    if not dataflow_graph.storage.contains_node(node_id):
+        df_node = dataflow_graph.add_dataflow_node(node_id)
+        if source_type is not None:
+            df_node.taints = [source_type]
+        return
+
+    if source_type is not None:
+        _mark_taint(dataflow_graph, node_id, source_type)

cobraphp/analysis/_taint_rules.py

@@ -0,0 +1,123 @@
+"""Semgrep taint rule loading and AST node type constants.
+
+Loads taint rules from YAML files in the rules/ directory.
+Node type sets loaded from php_ast_types.toml.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+from ._ast_types import load_php_ast_types
+from ._semgrep_runner import SemgrepResult
+from ._source_kinds import DATABASE, USER_INPUT
+
+_RULES_DIR = Path(__file__).parent / "rules"
+
+# Insertion order is the order of the Semgrep runs and of each node's taints list.
+_RULE_FILES: dict[str, str] = {
+    USER_INPUT: "user_input_taint.yaml",
+    DATABASE: "database_taint.yaml",
+}
+
+
+def _load_rule(filename: str) -> str:
+    """Load a YAML rule file from the rules directory."""
+    path = _RULES_DIR / filename
+    return path.read_text(encoding="utf-8")
+
+
+TAINT_RULES: dict[str, str] = {source: _load_rule(filename) for source, filename in _RULE_FILES.items()}
+
+CONSTANT_NODE_TYPES, CALLABLE_TYPES, _ = load_php_ast_types()
+
+
+# Identity and metadata are the contract of the call-argument rule in the YAML.
+_CALL_ARGUMENT_RULE = "user-input-call-argument-reachability"
+_INPUT_OUTPUT_RULE = "user-input-pollution-reachability"
+_TRACE_SEED_METADATA = "seed_from_source_trace"
+
+
+@dataclass(frozen=True)
+class SeedLocation:
+    """An offset seed or an exact expression span from a source trace."""
+
+    path: str
+    offset: int
+    end_offset: int | None = None
+
+
+def select_seed_locations(
+    result: SemgrepResult, project_path: Path, file_id_by_path: dict[str, str]
+) -> list[SeedLocation]:
+    """Keep the rule's seed and supplement input/output matches with a source."""
+    seed = select_seed_result(result, project_path, file_id_by_path)
+    path, offset = _field(seed, "path"), _field(_field(seed, "start"), "offset")
+    if not isinstance(path, str) or not isinstance(offset, int):
+        return []
+    selected = [SeedLocation(path, offset)]
+    check_id = result.get("check_id")
+    if isinstance(check_id, str) and check_id.rsplit(".", 1)[-1] == _INPUT_OUTPUT_RULE:
+        source = _trace_seed_location(result, project_path, file_id_by_path)
+        if source is not None:
+            selected.append(source)
+    return selected
+
+
+def select_seed_result(
+    result: SemgrepResult, project_path: Path, file_id_by_path: dict[str, str]
+) -> SemgrepResult | None:
+    """Select a validated source location for the call-argument rule.
+
+    Existing rules retain their result location. Unsupported or missing source
+    traces on the call rule produce no seed, rather than a whole-argument seed.
+    """
+    check_id = result.get("check_id")
+    if not isinstance(check_id, str) or check_id.rsplit(".", 1)[-1] != _CALL_ARGUMENT_RULE:
+        return result
+    extra = result.get("extra")
+    if _field(_field(extra, "metadata"), _TRACE_SEED_METADATA) is not True:
+        return None
+    source = _trace_seed_location(result, project_path, file_id_by_path)
+    return {"path": source.path, "start": {"offset": source.offset}} if source is not None else None
+
+
+def _trace_seed_location(
+    result: SemgrepResult, project_path: Path, file_id_by_path: dict[str, str]
+) -> SeedLocation | None:
+    extra = result.get("extra")
+    location = _source_location(_field(_field(extra, "dataflow_trace"), "taint_source"))
+    seed = _local_source_result(location, result, project_path)
+    if seed is None or str(seed["path"]) not in file_id_by_path:
+        return None
+    offset = cast(int, _field(seed["start"], "offset"))
+    end = cast(int, _field(_field(location, "end"), "offset"))
+    return SeedLocation(str(seed["path"]), offset, end)
+
+
+def _field(value: object, name: str) -> object:
+    # Semgrep's optional trace payload is validated at this JSON boundary.
+    return cast(object, value.get(name)) if isinstance(value, dict) else None
+
+
+def _source_location(source: object) -> object:
+    if not isinstance(source, list) or len(source) != 2 or source[0] != "CliLoc":
+        return None
+    payload = source[1]
+    return payload[0] if isinstance(payload, list) and len(payload) == 2 else None
+
+
+def _local_source_result(location: object, result: SemgrepResult, project_path: Path) -> SemgrepResult | None:
+    source_path, sink_path = _field(location, "path"), result.get("path")
+    if not isinstance(source_path, str) or not isinstance(sink_path, str):
+        return None
+    source = (project_path / source_path).resolve()
+    if source != (project_path / sink_path).resolve() or not source.is_relative_to(project_path.resolve()):
+        return None
+    start = _field(_field(location, "start"), "offset")
+    end = _field(_field(location, "end"), "offset")
+    if type(start) is not int or type(end) is not int or not 0 <= start < end:
+        return None
+    return {"path": str(source), "start": {"offset": start}}

cobraphp/analysis/frameworks.toml

@@ -0,0 +1,38 @@
+# Framework identity-marker registry for in-tree (vendored, no-vendor/no-namespace)
+# framework detection. Each entry names ONE framework by a UNIQUE identity
+# bootstrap file, never a role-generic name (e.g. Kernel.php). When the marker
+# file is found AND its head contains the signature string, the marker's subtree
+# root (or only its exclude_subpaths) is excluded from the parsed files and the Semgrep scan.
+#
+# Fields:
+#   name     framework identifier (logged on exclusion).
+#   marker   POSIX relative-path suffix of the identity bootstrap file. Its
+#            component count fixes how many path levels to strip to the root.
+#   contains substring that must appear in the marker file head; disambiguates
+#            name collisions. Empty match = no exclusion (conservative bias).
+#   exclude_subpaths (optional) subpaths under the detected root to exclude.
+#            Omitted/empty = exclude the whole subtree. Set it for a monorepo
+#            framework that also ships application code under the same root, so
+#            only the framework dirs drop and business code is kept.
+
+[[framework]]
+name = "yii1"
+marker = "YiiBase.php"
+contains = "class YiiBase"
+
+# Magento 2 ships framework, tooling, and application code under one root. Drop
+# the non-business dirs (dev tooling/tests, low-level lib internals, the setup
+# installer) and keep app/code (e.g. Magento/Sales, Checkout, Quote).
+[[framework]]
+name = "magento2"
+marker = "app/etc/NonComposerComponentRegistration.php"
+contains = 'namespace Magento\NonComposerComponentRegistration;'
+exclude_subpaths = ["dev", "lib/internal", "setup"]
+
+# ThinkPHP deployments can write generated PHP below runtime/cache.
+# Keep application and framework source under the same server root in scope.
+[[framework]]
+name = "thinkphp"
+marker = "thinkphp/base.php"
+contains = "namespace think;"
+exclude_subpaths = ["runtime/cache"]

cobraphp/analysis/php_ast_types.toml

@@ -0,0 +1,29 @@
+# PHP AST node type classifications read by the data-flow analysis.
+
+[constant_node_types]
+# Scalar literals and magic constants — not taintable
+values = [
+    "Scalar_String", "Scalar_Int", "Scalar_Float",
+    "Scalar_MagicConst_Line", "Scalar_MagicConst_File",
+    "Scalar_MagicConst_Dir", "Scalar_MagicConst_Class",
+    "Scalar_MagicConst_Trait", "Scalar_MagicConst_Method",
+    "Scalar_MagicConst_Function", "Scalar_MagicConst_Namespace",
+    "Scalar_MagicConst_Property",
+    "Expr_ConstFetch", "Expr_ClassConstFetch",
+]
+
+[callable_types]
+values = [
+    "Stmt_Function", "Stmt_ClassMethod", "Expr_Closure", "Expr_ArrowFunction",
+]
+
+[assign_node_types]
+values = [
+    "Expr_Assign",
+    "Expr_AssignOp_Plus", "Expr_AssignOp_Minus",
+    "Expr_AssignOp_Mul", "Expr_AssignOp_Div", "Expr_AssignOp_Mod",
+    "Expr_AssignOp_Concat",
+    "Expr_AssignOp_BitwiseAnd", "Expr_AssignOp_BitwiseOr", "Expr_AssignOp_BitwiseXor",
+    "Expr_AssignOp_ShiftLeft", "Expr_AssignOp_ShiftRight",
+    "Expr_AssignOp_Pow", "Expr_AssignOp_Coalesce",
+]

cobraphp/analysis/rules/database_taint.yaml

@@ -0,0 +1,94 @@
+rules:
+  - id: database-pollution-reachability
+    message: "Database pollution reachability analysis"
+    severity: WARNING
+    languages: [php]
+    mode: taint
+    pattern-sources:
+      # ── Bare PHP database functions ──
+      - pattern: mysqli_query(...)
+      - pattern: mysql_query(...)
+      - pattern: $PDO->query(...)
+      - pattern: $PDO->prepare(...)
+      - pattern: $STMT->execute(...)
+      - pattern: $PDO->exec(...)
+      - pattern: pg_query(...)
+      - pattern: pg_fetch_assoc(...)
+      - pattern: pg_fetch_row(...)
+      - pattern: pg_fetch_array(...)
+      # ── MySQLi fetch ──
+      - pattern: mysqli_fetch_assoc(...)
+      - pattern: mysqli_fetch_array(...)
+      - pattern: mysqli_fetch_row(...)
+      - pattern: $STMT->fetch(...)
+      - pattern: $STMT->fetchAll(...)
+      - pattern: $RESULT->fetch_assoc()
+      - pattern: $RESULT->fetch_array()
+      # ── SQLite3 ──
+      - pattern: $DB->querySingle(...)
+      - pattern: $RESULT->fetchArray(...)
+      # ── CodeIgniter query builder ──
+      - pattern: $this->db->query(...)
+      - pattern: $this->db->get(...)
+      - pattern: $this->db->get_where(...)
+      - pattern: $QUERY->result()
+      - pattern: $QUERY->result_array()
+      - pattern: $QUERY->row()
+      - pattern: $QUERY->row_array()
+      - pattern: $QUERY->num_rows()
+      # ── Laravel / Eloquent ──
+      - pattern: $MODEL::find(...)
+      - pattern: $MODEL::findOrFail(...)
+      - pattern: $MODEL::where(...)->get()
+      - pattern: $MODEL::where(...)->first()
+      - pattern: $MODEL::all()
+      - pattern: $QUERY->get()
+      - pattern: $QUERY->first()
+      - pattern: $QUERY->pluck(...)
+      - pattern: $QUERY->value(...)
+      - pattern: DB::table(...)->get()
+      - pattern: DB::table(...)->first()
+      - pattern: DB::select(...)
+      - pattern: DB::table(...)->where(...)->get()
+      - pattern: DB::table(...)->where(...)->first()
+      # ── WordPress ──
+      - pattern: $wpdb->get_results(...)
+      - pattern: $wpdb->get_row(...)
+      - pattern: $wpdb->get_var(...)
+      - pattern: $wpdb->get_col(...)
+      - pattern: get_post_meta(...)
+      - pattern: get_option(...)
+      - pattern: get_user_meta(...)
+      # ── Doctrine ORM (Symfony, PrestaShop, Sylius, Shopware) ──
+      - pattern: $REPO->find(...)
+      - pattern: $REPO->findOneBy(...)
+      - pattern: $REPO->findBy(...)
+      - pattern: $REPO->findAll()
+      - pattern: $EM->getRepository(...)->find(...)
+      - pattern: $EM->getRepository(...)->findOneBy(...)
+      - pattern: $this->getDoctrine()->getRepository(...)
+      # ── Yii ActiveRecord (Yii1 + Yii2) ──
+      - pattern: $MODEL::findOne(...)
+      - pattern: $MODEL::findAll(...)
+      - pattern: $MODEL::find()->one()
+      - pattern: $MODEL::find()->all()
+      - pattern: $MODEL::find()->where(...)->one()
+      - pattern: $MODEL::find()->where(...)->all()
+      - pattern: $MODEL::model()->findByPk(...)
+      - pattern: $MODEL::model()->find(...)
+      # ── CakePHP ORM ──
+      - pattern: $TABLE->get(...)
+      - pattern: $TABLE->find(...)->first()
+      - pattern: $TABLE->find(...)->all()
+      # ── Magento ──
+      - pattern: $COLLECTION->getItems()
+      - pattern: $MODEL->load(...)->getData(...)
+    pattern-sinks:
+      - pattern: return $X;
+        exact: false
+      - pattern: echo $X;
+        exact: false
+      - pattern: print $X;
+        exact: false
+      - pattern: $X = $Y;
+        exact: false