cobraphp 0.1.0.dev1__py3-none-any.whl

cobraphp/analysis/_records.py

@@ -0,0 +1,140 @@
+"""Plain-data records of the call graph and the data-flow graph.
+
+The call graph becomes CCG records of `GraphExport`; the cpg2py data-flow graph becomes the frozen
+`DataFlowGraph`. Node ids are php-parser-py AST node ids of the AST the caller passed in.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from php_parser_py import AST, Node
+
+from ..graphs import GraphEdge, GraphExport, GraphNode
+from . import _taint_graph
+from ._call_graph import CallGraph
+from ._callee_index import FUNCTION_CALL_TYPE, CalleeIndex, _enclosing_class_name
+from ._errors import StaticAnalysisError
+from ._taint_rules import TAINT_RULES
+
+CCG = "CCG"
+FUNC_ENTITY = "CCG_FUNC_ENTITY"
+CALL_SITE = "CCG_CALL_SITE"
+FUNC_CONTAIN = "CCG_FUNC_CONTAIN"
+SITE_CALL = "CCG_SITE_CALL"
+CALL_CERTAINTY = "ccg_call_certainty"
+# A callee named by the call itself: a free function, or a method of the class $this, self, static or a
+# literal class name denotes.
+STATIC = "STATIC"
+# A callee found by method name alone, because the receiver names no class or that class has no such method.
+SUSPICIOUS = "SUSPICIOUS"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DataFlowGraph:
+    """AST node ids reached by each Source kind, and each node's direct data-flow predecessors.
+
+    `tainted` maps every Source kind to its sorted node ids; `predecessors` maps every data-flow node to its
+    predecessor ids in edge insertion order.
+    """
+
+    tainted: Mapping[str, tuple[str, ...]]
+    predecessors: Mapping[str, tuple[str, ...]]
+
+
+def call_graph_export(project_ast: AST, call_graph: CallGraph) -> GraphExport:
+    """Convert `call_graph` into CCG records.
+
+    Top-level code is the function entity of its file, keyed by the file node id.
+    """
+    callee_index = CalleeIndex(project_ast)
+    entities: list[GraphNode] = []
+    sites: list[GraphNode] = []
+    edges: list[GraphEdge] = []
+    file_entities: set[str] = set()
+    storage = call_graph.storage
+    for node_id in storage.get_nodes():
+        node_type = storage.get_node_prop(node_id, "node_type")
+        if node_type == "function_declaration":
+            declaration = project_ast.node(node_id)
+            entities.append(_entity(node_id, call_graph.get_func_node(node_id).name, declaration, declaration.start_line))
+            continue
+        if node_type != "call_site":
+            continue
+        site = project_ast.node(node_id)
+        caller_id = call_graph.get_caller_of_callsite(node_id)
+        if storage.get_node_prop(caller_id, "node_type") != "function_declaration":
+            file_node = project_ast.get_file_node(node_id)
+            caller_id = file_node.id
+            if caller_id not in file_entities:
+                file_entities.add(caller_id)
+                entities.append(_entity(caller_id, _relative_file(file_node), file_node, None))
+        sites.append(
+            GraphNode(id=node_id, graph=CCG, type=CALL_SITE, state=None, path=None,
+                      props={"file": _relative_file(site), "line": site.start_line})
+        )
+        edges.append(GraphEdge(source=caller_id, target=node_id, type=FUNC_CONTAIN, labels=(), props={}))
+        for callee in call_graph.get_callees(node_id):
+            certainty = _call_certainty(project_ast, callee_index, site, project_ast.node(callee.node_id))
+            edges.append(
+                GraphEdge(source=node_id, target=callee.node_id, type=SITE_CALL, labels=(),
+                          props={CALL_CERTAINTY: certainty})
+            )
+    return GraphExport(header={}, nodes=(*entities, *sites), edges=tuple(edges), label_order=())
+
+
+def data_flow_graph(graph: _taint_graph.DataFlowGraph) -> DataFlowGraph:
+    """Copy the taints and predecessor lists of the cpg2py data-flow graph."""
+    storage = graph.storage
+    return DataFlowGraph(
+        tainted={kind: tuple(sorted(graph.get_sources_by_type(kind))) for kind in TAINT_RULES},
+        predecessors={node_id: tuple(storage.predecessors(node_id)) for node_id in storage.get_nodes()},
+    )
+
+
+def backward_slice(graph: DataFlowGraph, node_id: str, *, max_depth: int = 10) -> tuple[str, ...]:
+    """Predecessors of `node_id` within `max_depth` edges, breadth-first, excluding `node_id`."""
+    if node_id not in graph.predecessors:
+        return ()
+    visited: set[str] = set()
+    queue: deque[tuple[str, int]] = deque([(node_id, 0)])
+    result: list[str] = []
+    while queue:
+        current, depth = queue.popleft()
+        if current in visited:
+            continue
+        visited.add(current)
+        if current != node_id:
+            result.append(current)
+        if depth >= max_depth:
+            continue
+        for predecessor in graph.predecessors.get(current, ()):
+            if predecessor not in visited:
+                queue.append((predecessor, depth + 1))
+    return tuple(result)
+
+
+def _entity(node_id: str, name: str, node: Node, line: int | None) -> GraphNode:
+    return GraphNode(id=node_id, graph=CCG, type=FUNC_ENTITY, state=None, path=None,
+                     props={"name": name, "file": _relative_file(node), "line": line})
+
+
+# Project-relative POSIX path of the file that holds `node`.
+def _relative_file(node: Node) -> str:
+    relative = node.relative_path
+    if relative is None:
+        raise StaticAnalysisError(f"Node {node.id} has no file relativePath")
+    return Path(relative).as_posix()
+
+
+# STATIC when the resolution used the call's own name or receiver class, SUSPICIOUS for the name-only fallback.
+def _call_certainty(project_ast: AST, callee_index: CalleeIndex, site: Node, callee: Node) -> str:
+    if site.node_type == FUNCTION_CALL_TYPE:
+        return STATIC
+    receiver_class = callee_index._receiver_class_name(site)
+    if receiver_class is not None and _enclosing_class_name(project_ast, callee) == receiver_class:
+        return STATIC
+    return SUSPICIOUS

cobraphp/analysis/_semgrep_runner.py

@@ -0,0 +1,322 @@
+"""Semgrep process execution and AST offset mapping utilities."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from php_parser_py import AST, NodeNotInFileError
+
+from ..errors import DependencyUnavailableError
+from ._errors import AnalysisTimeoutError, StaticAnalysisError
+from ._file_filter import _EXCLUDED_DIRS, _EXCLUDED_FILES, framework_excluded_dirs
+from ._project_root import project_root_text
+
+logger = logging.getLogger(__name__)
+
+# Type alias for Semgrep JSON output structure.
+SemgrepResult = dict[str, object]
+SemgrepOutput = dict[str, list[SemgrepResult]]
+
+# Program the scan runs, looked up on PATH.
+_SEMGREP_PROGRAM = "semgrep"
+
+# Environment settings of the scan process that override the caller's values.
+# SEMGREP_ENABLE_VERSION_CHECK=0 stops the request to the Semgrep version-check
+# URL. It is set in the child environment rather than as --disable-version-check,
+# because Semgrep 1.85 exits with "mutually exclusive options" when that option
+# meets a SEMGREP_ENABLE_VERSION_CHECK value in the caller's environment.
+_SEMGREP_ENVIRONMENT = {"SEMGREP_ENABLE_VERSION_CHECK": "0"}
+
+# Per-(rule, file) wall-clock budget. On exceeding it Semgrep skips that file
+# and continues, returning partial results instead of hanging — the mechanism
+# that keeps pathological files from blocking the whole scan.
+_PER_FILE_TIMEOUT_SECONDS = 5
+# A file is dropped entirely after this many rules time out on it.
+_TIMEOUT_THRESHOLD = 3
+# Per-file memory ceiling (MiB); guards against OOM SIGKILL on huge files.
+_MAX_MEMORY_MB = 5000
+
+# Semgrep tags non-fatal, file-level problems (per-file timeout, partial parse,
+# out-of-memory on one file) with these levels. They leave the rest of the scan
+# intact, so they degrade to a warning rather than failing the whole analysis.
+_RECOVERABLE_ERROR_LEVELS = frozenset({"warn", "warning", "info"})
+
+
+def run_semgrep(
+    rule_yaml: str,
+    project_path: Path,
+    timeout: int | None,
+    target_files: set[str] | None = None,
+) -> SemgrepOutput:
+    """Execute Semgrep and return parsed JSON output.
+
+    When ``target_files`` (relative paths under ``project_path``) is given,
+    Semgrep scans only those that exist instead of the whole tree — keeping
+    analysis to the executed/covered files so large projects do not time out.
+    When none of them exists, Semgrep is not run and the output is empty.
+    """
+    targets = None if target_files is None else _existing_targets(project_path, target_files)
+    if targets == []:
+        logger.warning("Semgrep scan skipped: no target file exists: project=%s", project_path)
+        return {"results": [], "errors": []}
+    rule_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as rule_file:
+            rule_path = Path(rule_file.name)
+            rule_file.write(rule_yaml)
+        return _run_and_parse(rule_path, project_path, targets, timeout)
+    except subprocess.TimeoutExpired as exc:
+        # Only reachable when a non-None timeout was set; exc.timeout carries it.
+        raise AnalysisTimeoutError(int(exc.timeout)) from exc
+    except FileNotFoundError as exc:
+        if exc.filename != _SEMGREP_PROGRAM:
+            raise StaticAnalysisError(f"Semgrep input or process failed: {exc}") from exc
+        raise DependencyUnavailableError(f"The {_SEMGREP_PROGRAM} program is not on PATH") from exc
+    except OSError as exc:
+        raise StaticAnalysisError(f"Semgrep input or process failed: {exc}") from exc
+    finally:
+        if rule_path is not None:
+            rule_path.unlink(missing_ok=True)
+
+
+def _run_and_parse(
+    rule_path: Path,
+    project_path: Path,
+    targets: list[Path] | None,
+    timeout: int | None,
+) -> SemgrepOutput:
+    """Run Semgrep on the rule file and return its parsed, error-checked output."""
+    result = subprocess.run(
+        _build_semgrep_command(rule_path, project_path, targets),
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        check=False,
+        env=_semgrep_environment(),
+    )
+    output = _parse_semgrep_output(result.stdout)
+    _check_semgrep_errors(output, result.returncode, result.stderr)
+    return output
+
+
+def _semgrep_environment() -> dict[str, str]:
+    """The caller's environment with the scan's overrides; ``os.environ`` is unchanged."""
+    return {**os.environ, **_SEMGREP_ENVIRONMENT}
+
+
+def _existing_targets(project_path: Path, target_files: set[str]) -> list[Path]:
+    # Target files resolved under the project root, keeping only existing files.
+    candidates = (project_path / f for f in sorted(target_files))
+    return [p for p in candidates if p.is_file()]
+
+
+def _tree_exclude_args(project_path: Path) -> list[str]:
+    # Mirror the AST file filter: dependency dirs and monolith files match by
+    # name at any depth; framework subtrees are anchored at the scan root.
+    framework_dirs = framework_excluded_dirs(project_path)
+    anchored = sorted("/" + d.relative_to(project_path).as_posix() for d in framework_dirs)
+    patterns = [*sorted(_EXCLUDED_DIRS), *sorted(_EXCLUDED_FILES), *anchored]
+    return [arg for pattern in patterns for arg in ("--exclude", pattern)]
+
+
+def _build_semgrep_command(
+    rule_path: Path,
+    project_path: Path,
+    targets: list[Path] | None = None,
+) -> list[str]:
+    """Build the Semgrep argv.
+
+    With ``targets``, scan exactly those files; they are already the
+    covered/relevant set, so no directory traversal or exclude globs are
+    needed. Without it, scan the whole tree excluding what the AST file
+    filter excludes.
+    """
+    command = [
+        _SEMGREP_PROGRAM,
+        "--config",
+        str(rule_path),
+        "--json",
+        "--no-git-ignore",
+        "--timeout",
+        str(_PER_FILE_TIMEOUT_SECONDS),
+        "--timeout-threshold",
+        str(_TIMEOUT_THRESHOLD),
+        "--max-memory",
+        str(_MAX_MEMORY_MB),
+    ]
+    if targets is not None:
+        return [*command, *(str(p) for p in targets)]
+    return [*command, *_tree_exclude_args(project_path), str(project_path)]
+
+
+def _parse_semgrep_output(stdout: str) -> SemgrepOutput:
+    """Parse Semgrep JSON stdout into typed dict."""
+    try:
+        return json.loads(stdout)  # type: ignore[no-any-return]
+    except json.JSONDecodeError as exc:
+        raise StaticAnalysisError(f"Failed to parse Semgrep JSON output: {exc}") from exc
+
+
+def _check_semgrep_errors(
+    output: SemgrepOutput,
+    returncode: int,
+    stderr: str,
+) -> None:
+    """Raise StaticAnalysisError on fatal Semgrep errors only.
+
+    File-level problems (per-file timeout, partial parse, single-file OOM) are
+    recoverable: Semgrep skips the offending file and returns results for the
+    rest. Discarding those partial results would turn one slow file into a
+    whole-repo failure, so they are logged and tolerated. Only rule-execution
+    failures (level ``error``) or a crash with no structured error are fatal.
+    """
+    errors = output.get("errors", [])
+    fatal = [e for e in errors if not _is_recoverable_error(e)]
+    recoverable = len(errors) - len(fatal)
+    if recoverable:
+        logger.warning(
+            "Semgrep skipped %d target(s) (timeout/partial-parse); continuing with partial results",
+            recoverable,
+        )
+    if fatal:
+        messages = [e.get("message") or e.get("short_msg") or "Unknown error" for e in fatal]
+        raise StaticAnalysisError("Semgrep rule execution failed: " + "; ".join(str(m) for m in messages))
+    if returncode and not errors:
+        stderr_text = stderr.strip() if stderr else ""
+        raise StaticAnalysisError(f"Semgrep execution failed with code {returncode}. {stderr_text}")
+
+
+def _is_recoverable_error(error: SemgrepResult) -> bool:
+    """Whether a Semgrep error entry is a tolerable file-level problem."""
+    return str(error.get("level", "error")).lower() in _RECOVERABLE_ERROR_LEVELS
+
+
+# ── Path resolution ─────────────────────────────────────────────────
+
+
+def resolve_project_path(ast: AST) -> Path:
+    """Resolve project root path from the AST project node.
+
+    Raises:
+        ValueError: If the project node is missing or has no usable absolutePath.
+    """
+    return Path(project_root_text(ast)).resolve()
+
+
+def build_file_id_index(ast: AST) -> dict[str, str]:
+    """Build mapping from resolved absolute path to file node ID."""
+    index: dict[str, str] = {}
+    for file_node in ast.file_nodes():
+        abs_path = file_node.get("absolutePath")
+        if abs_path:
+            index[str(Path(str(abs_path)).resolve())] = file_node.id
+    return index
+
+
+def resolve_file_node_id(
+    semgrep_path: str,
+    project_path: Path,
+    file_id_by_path: dict[str, str],
+) -> str | None:
+    """Resolve Semgrep result path to a file node ID."""
+    if not semgrep_path:
+        return None
+    resolved = str((project_path / semgrep_path).resolve())
+    if resolved in file_id_by_path:
+        return file_id_by_path[resolved]
+    resolved_direct = str(Path(semgrep_path).resolve())
+    return file_id_by_path.get(resolved_direct)
+
+
+# ── Offset mapping ──────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class _BestNode:
+    """A span rank preferring expression nodes on ties."""
+
+    node_id: str
+    span: int
+    is_expr: bool
+
+    def better_than(self, other: _BestNode | None) -> bool:
+        """Whether this candidate beats the incumbent (None means no incumbent)."""
+        if other is None:
+            return True
+        if self.span != other.span:
+            return self.span < other.span
+        return self.is_expr and not other.is_expr
+
+
+@dataclass(frozen=True)
+class _IndexedNode:
+    """One indexed node and its containing file, independent of live wrappers."""
+
+    node_id: str
+    span: int
+    is_expr: bool
+    file_id: str | None
+    is_leaf: bool
+
+
+@dataclass(frozen=True)
+class OffsetIndex:
+    """Frozen AST start-offset buckets shared by point and span lookups."""
+
+    _by_offset: dict[int, list[_IndexedNode]]
+
+    def resolve(self, byte_offset: int, file_node_id: str | None = None) -> str | None:
+        """Resolve the most specific node at an optionally file-scoped offset."""
+        return self._resolve(byte_offset, file_node_id, end=None)
+
+    def resolve_source_span(self, start: int, end: int, file_node_id: str) -> str | None:
+        """Resolve only a leaf expression matching the trace's half-open span."""
+        return self._resolve(start, file_node_id, end=end)
+
+    def _resolve(self, byte_offset: int, file_node_id: str | None, end: int | None) -> str | None:
+        best: _BestNode | None = None
+        for indexed in self._by_offset.get(byte_offset, ()):
+            if file_node_id is not None and indexed.file_id != file_node_id:
+                continue
+            if end is not None and (
+                not indexed.is_expr or not indexed.is_leaf or indexed.span + 1 != end - byte_offset
+            ):
+                continue
+            candidate = _BestNode(indexed.node_id, indexed.span, indexed.is_expr)
+            if candidate.better_than(best):
+                best = candidate
+        return best.node_id if best is not None else None
+
+
+def build_offset_index(ast: AST) -> OffsetIndex:
+    """Index positioned nodes once, using the graph for containing-file identity."""
+    by_offset: dict[int, list[_IndexedNode]] = {}
+    for node in ast.nodes():
+        start_pos = node.start_file_pos
+        end_pos = node.end_file_pos
+        if start_pos is None or end_pos is None:
+            continue
+        by_offset.setdefault(start_pos, []).append(
+            _IndexedNode(
+                node_id=node.id,
+                span=end_pos - start_pos,
+                is_expr=node.node_type.startswith("Expr_"),
+                file_id=_containing_file_id(ast, node.id),
+                is_leaf=not any(ast.succ(node)),
+            )
+        )
+    return OffsetIndex(by_offset)
+
+
+def _containing_file_id(ast: AST, node_id: str) -> str | None:
+    """Return the ID of the File node containing ``node_id``, or None outside every file."""
+    try:
+        return ast.get_file_node(node_id).id
+    except NodeNotInFileError:
+        return None

cobraphp/analysis/_source_kinds.py

@@ -0,0 +1,6 @@
+"""Source kind values, one per Semgrep taint rule file."""
+
+from __future__ import annotations
+
+USER_INPUT = "user_input"
+DATABASE = "database"

cobraphp/analysis/_taint_graph.py

@@ -0,0 +1,200 @@
+"""Data flow graph for taint propagation tracking."""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Iterable, Iterator
+
+from cpg2py import AbcEdgeQuerier, AbcGraphQuerier, AbcNodeQuerier, Storage
+
+from ._errors import StaticAnalysisError
+
+
+class DataFlowNode(AbcNodeQuerier):  # type: ignore[misc]
+    """Storage wrapper for dataflow graph node taint metadata."""
+
+    def __init__(self, storage: Storage, node_id: str) -> None:
+        super().__init__(storage, node_id)
+        self._storage_ref = storage
+
+    @property
+    def taints(self) -> list[str]:
+        """List of Source kinds that have tainted this node."""
+        taints_list = self.get_property("taints") or []
+        return [str(t) for t in taints_list]
+
+    @taints.setter
+    def taints(self, value: list[str]) -> None:
+        """Set taints list."""
+        self._storage_ref.set_node_prop(self.node_id, "taints", list(value))
+
+    @property
+    def is_tainted(self) -> bool:
+        """Whether this node is tainted (computed from taints)."""
+        return len(self.taints) > 0
+
+
+class DataFlowEdge(AbcEdgeQuerier):  # type: ignore[misc]
+    """Storage wrapper for dataflow graph edge."""
+
+    def __init__(self, storage: Storage, f_nid: str, t_nid: str, e_type: str) -> None:
+        super().__init__(storage, f_nid, t_nid, e_type)
+        self._storage_ref = storage
+
+
+class DataFlowGraph(AbcGraphQuerier[DataFlowNode, DataFlowEdge]):  # type: ignore[misc]
+    """Data flow graph tracking taint propagation via cpg2py Storage."""
+
+    def __init__(self) -> None:
+        storage = Storage()
+        super().__init__(target=storage, maxdepth=-1)
+
+    def node(self, whose_id_is: str) -> DataFlowNode:
+        """Returns DataFlowNode by ID."""
+        if not self.storage.contains_node(whose_id_is):
+            raise StaticAnalysisError(f"Node {whose_id_is} does not exist in dataflow graph")
+        return DataFlowNode(self.storage, whose_id_is)
+
+    def edge(self, fid: str, tid: str, eid: str) -> DataFlowEdge:
+        """Returns DataFlowEdge by source, target, edge type."""
+        edge_id = (fid, tid, eid)
+        if not self.storage.contains_edge(edge_id):
+            raise StaticAnalysisError(f"Edge {edge_id} does not exist in dataflow graph")
+        return DataFlowEdge(self.storage, fid, tid, eid)
+
+    def add_dataflow_node(self, node_id: str) -> DataFlowNode:
+        """Add source or sink node."""
+        if not node_id:
+            raise ValueError("node_id must be non-empty")
+        if self.storage.contains_node(node_id):
+            msg = f"Node {node_id} already exists"
+            raise StaticAnalysisError(msg)
+
+        self.storage.add_node(node_id)
+        df_node = DataFlowNode(self.storage, node_id)
+        df_node.taints = []
+        return df_node
+
+    def add_dataflow_edge(
+        self,
+        from_nid: str,
+        to_nid: str,
+        source_type: str,
+    ) -> DataFlowEdge:
+        """Add data flow edge and taint both endpoints.
+
+        Raises:
+            ValueError: If an ID is empty.
+            StaticAnalysisError: If a node does not exist.
+        """
+        self._validate_edge_nodes(from_nid, to_nid)
+
+        edge_id = (from_nid, to_nid, "FLOWS_TO")
+        self.storage.add_edge(edge_id)
+
+        self._mark_tainted(from_nid, source_type)
+        self._mark_tainted(to_nid, source_type)
+
+        return DataFlowEdge(self.storage, from_nid, to_nid, "FLOWS_TO")
+
+    def _validate_edge_nodes(self, from_nid: str, to_nid: str) -> None:
+        """Validate that edge endpoint nodes exist."""
+        if not from_nid:
+            raise ValueError("from_nid must be non-empty")
+        if not to_nid:
+            raise ValueError("to_nid must be non-empty")
+        if not self.storage.contains_node(from_nid):
+            raise StaticAnalysisError(f"Source node {from_nid} does not exist")
+        if not self.storage.contains_node(to_nid):
+            raise StaticAnalysisError(f"Sink node {to_nid} does not exist")
+
+    def _mark_tainted(self, node_id: str, source_type: str) -> None:
+        """Add source_type to node's taint list if not already present."""
+        node = self.get_dataflow_node(node_id)
+        current = node.taints
+        if source_type not in current:
+            current.append(source_type)
+            node.taints = current
+
+    def add_structural_edge(self, from_nid: str, to_nid: str) -> None:
+        """Add a structural dataflow edge without marking taint.
+
+        Raises:
+            ValueError: If an ID is empty.
+            StaticAnalysisError: If a node does not exist.
+        """
+        self._validate_edge_nodes(from_nid, to_nid)
+        edge_id = (from_nid, to_nid, "FLOWS_TO")
+        if not self.storage.contains_edge(edge_id):
+            self.storage.add_edge(edge_id)
+
+    def get_sinks_reachable_from(self, source_node_id: str) -> list[str]:
+        """Get sink node IDs reachable from source via BFS.
+
+        Raises:
+            StaticAnalysisError: If source_node does not exist.
+        """
+        if not self.storage.contains_node(source_node_id):
+            raise StaticAnalysisError(f"Source node {source_node_id} does not exist")
+        return self._bfs_forward(source_node_id)
+
+    def get_dataflow_node(self, node_id: str) -> DataFlowNode:
+        """Retrieve DataFlowNode by ID (alias for node())."""
+        return self.node(whose_id_is=node_id)
+
+    def get_sources_by_type(self, source_type: str) -> set[str]:
+        """Get node IDs tainted by the given Source kind."""
+        source_ids = set()
+        for node_id in self.storage.get_nodes():
+            node = self.get_dataflow_node(node_id)
+            if node and source_type in node.taints:
+                source_ids.add(node_id)
+        return source_ids
+
+    def get_backward_slice(self, node_id: str, max_depth: int = 10) -> list[str]:
+        """Get predecessor node IDs reachable backward up to max_depth hops."""
+        if not self.storage.contains_node(node_id):
+            return []
+        return self._bfs_backward(node_id, max_depth)
+
+    def reachable_from(self, starts: Iterable[str]) -> Iterator[str]:
+        """Yield every node reachable forward from any start node, each once.
+
+        Start nodes are themselves yielded. Nodes absent from the graph are
+        skipped without traversal.
+        """
+        visited: set[str] = set()
+        queue: deque[str] = deque(starts)
+        while queue:
+            current = queue.popleft()
+            if current in visited:
+                continue
+            visited.add(current)
+            if not self.storage.contains_node(current):
+                continue
+            yield current
+            queue.extend(self.storage.successors(current))
+
+    def _bfs_forward(self, start: str) -> list[str]:
+        """BFS forward from start, returning all reachable nodes (excluding start)."""
+        return [node for node in self.reachable_from([start]) if node != start]
+
+    def _bfs_backward(self, start: str, max_depth: int) -> list[str]:
+        """BFS backward from start up to max_depth hops."""
+        visited: set[str] = set()
+        queue: deque[tuple[str, int]] = deque([(start, 0)])
+        result: list[str] = []
+
+        while queue:
+            current, depth = queue.popleft()
+            if current in visited:
+                continue
+            visited.add(current)
+            if current != start:
+                result.append(current)
+            if depth >= max_depth:
+                continue
+            for pred in self.storage.predecessors(current):
+                if pred not in visited:
+                    queue.append((pred, depth + 1))
+        return result