snikrflow 0.1.0__py3-none-any.whl

snikrflow/analysis/backends/angr/audit.py

@@ -0,0 +1,145 @@
+"""
+SnikrFlow angr backend -- audit orchestration.
+
+Combines every prior analysis stage into one pipeline, per the doc's
+performance philosophy: cheap triage on everything, expensive symbolic/
+data-flow analysis only on the most promising candidates.
+
+Pipeline:
+  1. Discover functions, JNI candidates, sinks (cheap -- one CFGFast run,
+     reused across all three thanks to the caching guard in functions.py).
+  2. For every (JNI entry, sink) pair, check STATIC call-graph
+     reachability (cheap -- no symbolic execution).
+  3. Rank the statically-reachable pairs by call-chain length (shorter =
+     more direct = higher priority) and take the top N for deep analysis.
+  4. Run data-flow analysis (symbolic, bounded by a short per-pair
+     timeout) ONLY on that top-N subset.
+  5. Score risk transparently (see _score_risk) and sort findings by risk.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from snikrflow.analysis.backends.angr.dataflow import check_data_flow
+from snikrflow.analysis.backends.angr.functions import discover_functions
+from snikrflow.analysis.backends.angr.jni import discover_jni_functions
+from snikrflow.analysis.backends.angr.reachability import check_static_reachability
+from snikrflow.analysis.backends.angr.sinks import discover_sinks
+from snikrflow.core.models import (
+    AnalysisFinding,
+    AuditResult,
+    DataFlowStatus,
+    ReachabilityType,
+    RiskLevel,
+)
+from snikrflow.elf.loader import LoadedBinary
+from snikrflow.elf.metadata import extract_binary_info
+
+# Cap on how many statically-reachable pairs get the expensive data-flow
+# treatment. Keeps `audit` bounded on binaries with many JNI x sink
+# combinations -- deep analysis is a scarce resource, spent on the most
+# direct (shortest) paths first.
+MAX_DEEP_ANALYSIS_PAIRS = 5
+DEFAULT_DEEP_TIMEOUT_SECONDS = 30
+
+# Rough, documented, and DELIBERATELY simple severity weighting per sink
+# category. This is a transparent prioritization heuristic, not a
+# vulnerability database -- edit freely.
+_CATEGORY_SEVERITY = {
+    "process_execution": 3,
+    "dynamic_loading": 3,
+    "memory": 2,
+    "networking": 2,
+    "filesystem": 1,
+}
+
+
+def _score_risk(
+    reachability_type: ReachabilityType,
+    data_flow_status: Optional[DataFlowStatus],
+    category: str,
+) -> RiskLevel:
+    severity = _CATEGORY_SEVERITY.get(category, 1)
+
+    if reachability_type != ReachabilityType.STATICALLY_REACHABLE:
+        return RiskLevel.LOW
+
+    if data_flow_status == DataFlowStatus.POSSIBLE:
+        return RiskLevel.CRITICAL if severity >= 3 else RiskLevel.HIGH
+
+    # Reachable via call graph, but data flow wasn't confirmed possible
+    # (either not checked, or checked and came back inconclusive).
+    return RiskLevel.HIGH if severity >= 3 else RiskLevel.MEDIUM
+
+
+def run_audit(binary: LoadedBinary, deep_timeout_seconds: int = DEFAULT_DEEP_TIMEOUT_SECONDS) -> AuditResult:
+    binary_info = extract_binary_info(binary)
+
+    all_functions = discover_functions(binary)      # runs CFGFast once
+    jni_functions = discover_jni_functions(binary)   # reuses it
+    sinks = discover_sinks(binary)                   # reuses it
+
+    # Step 1: cheap static reachability across every JNI x sink pair.
+    reachable_pairs = []
+    for jni_func in jni_functions:
+        for sink in sinks:
+            path = check_static_reachability(binary, jni_func.address, sink.address)
+            if path.reachable and path.reachability_type == ReachabilityType.STATICALLY_REACHABLE:
+                reachable_pairs.append((jni_func, sink, path))
+
+    # Step 2: prioritize shortest (most direct) call chains for deep analysis.
+    reachable_pairs.sort(key=lambda item: len(item[2].function_path))
+    deep_pairs = reachable_pairs[:MAX_DEEP_ANALYSIS_PAIRS]
+    deep_keys = {(j.address, s.address) for j, s, _ in deep_pairs}
+
+    # Step 3: build findings, running data-flow only on the selected subset.
+    findings: list[AnalysisFinding] = []
+    for jni_func, sink, path in reachable_pairs:
+        data_flow_status: Optional[DataFlowStatus] = None
+        confidence = path.confidence
+        notes: list[str] = [path.note] if path.note else []
+
+        if (jni_func.address, sink.address) in deep_keys:
+            try:
+                df_result = check_data_flow(
+                    binary, jni_func.address, sink.address,
+                    timeout_seconds=deep_timeout_seconds,
+                )
+                data_flow_status = df_result.status
+                confidence = df_result.confidence
+                if df_result.note:
+                    notes.append(df_result.note)
+            except Exception as e:
+                notes.append(f"Data-flow analysis failed: {e}")
+
+        risk = _score_risk(path.reachability_type, data_flow_status, sink.category)
+
+        findings.append(
+            AnalysisFinding(
+                title=f"JNI -> {sink.category}",
+                source_address=jni_func.address,
+                source_name=jni_func.name,
+                sink_address=sink.address,
+                sink_name=sink.name,
+                sink_category=sink.category,
+                reachability_type=path.reachability_type,
+                data_flow_status=data_flow_status,
+                risk_level=risk,
+                confidence=confidence,
+                notes=notes,
+            )
+        )
+
+    risk_order = {RiskLevel.CRITICAL: 0, RiskLevel.HIGH: 1, RiskLevel.MEDIUM: 2, RiskLevel.LOW: 3}
+    findings.sort(key=lambda f: risk_order.get(f.risk_level, 4))
+
+    return AuditResult(
+        binary_info=binary_info,
+        function_count=len(all_functions),
+        jni_count=len(jni_functions),
+        sink_count=len(sinks),
+        interesting_path_count=len(reachable_pairs),
+        symbolic_analysis_count=len(deep_pairs),
+        findings=findings,
+    )

snikrflow/analysis/backends/angr/callgraph.py

@@ -0,0 +1,40 @@
+"""
+SnikrFlow angr backend -- callers/callees lookup.
+
+Reuses discover_functions() (runs CFGFast, builds kb.callgraph) so
+callers/callees work off the same function set as `functions`/`jni`/
+`sinks` -- no separate, possibly-inconsistent analysis pass.
+"""
+
+from __future__ import annotations
+
+from snikrflow.analysis.backends.angr.functions import discover_functions
+from snikrflow.core.models import Function
+from snikrflow.elf.loader import LoadedBinary
+
+
+def _resolve(binary: LoadedBinary):
+    all_functions = discover_functions(binary)
+    by_addr = {f.address: f for f in all_functions}
+    callgraph = binary.project.kb.callgraph
+    return by_addr, callgraph
+
+
+def find_callers(binary: LoadedBinary, address: int) -> list[Function]:
+    """Direct callers of the function at `address`. Indirect/unresolved calls are not included."""
+    by_addr, callgraph = _resolve(binary)
+    try:
+        caller_addrs = sorted(callgraph.predecessors(address))
+    except Exception:
+        caller_addrs = []
+    return [by_addr[a] for a in caller_addrs if a in by_addr]
+
+
+def find_callees(binary: LoadedBinary, address: int) -> list[Function]:
+    """Direct callees of the function at `address`. Indirect/unresolved calls are not included."""
+    by_addr, callgraph = _resolve(binary)
+    try:
+        callee_addrs = sorted(callgraph.successors(address))
+    except Exception:
+        callee_addrs = []
+    return [by_addr[a] for a in callee_addrs if a in by_addr]

snikrflow/analysis/backends/angr/cfg.py

@@ -0,0 +1,49 @@
+"""
+SnikrFlow angr backend -- CFG analysis.
+
+Supports CFGFast (default, scalable) and CFGEmulated (deeper, slower).
+CFGEmulated has been deprecated/removed in some recent angr versions --
+if it's unavailable here, we fail gracefully with a clear message rather
+than crashing, per SnikrFlow's error-handling philosophy.
+"""
+
+from __future__ import annotations
+
+from snikrflow.core.exceptions import AnalysisIncompleteError
+from snikrflow.core.models import CFGSummary
+from snikrflow.elf.loader import LoadedBinary
+
+
+def build_cfg_summary(binary: LoadedBinary, mode: str = "fast") -> CFGSummary:
+    project = binary.project
+
+    if mode == "fast":
+        try:
+            cfg = project.analyses.CFGFast(normalize=True)
+        except Exception as e:
+            raise AnalysisIncompleteError(f"CFGFast failed: {e}") from e
+
+    elif mode == "emulated":
+        try:
+            cfg = project.analyses.CFGEmulated(keep_state=False)
+        except AttributeError as e:
+            raise AnalysisIncompleteError(
+                "CFGEmulated is not available in this angr version. "
+                "Use --cfg-mode fast instead."
+            ) from e
+        except Exception as e:
+            raise AnalysisIncompleteError(f"CFGEmulated failed: {e}") from e
+
+    else:
+        raise AnalysisIncompleteError(
+            f"Unknown CFG mode '{mode}'. Use 'fast' or 'emulated'."
+        )
+
+    graph = cfg.graph
+
+    return CFGSummary(
+        function_count=len(project.kb.functions),
+        basic_block_count=graph.number_of_nodes(),
+        edge_count=graph.number_of_edges(),
+        mode=mode,
+    )

snikrflow/analysis/backends/angr/dataflow.py

@@ -0,0 +1,205 @@
+"""
+SnikrFlow angr backend -- data flow (heuristic taint) analysis.
+
+Reuses the same symbolic-buffer setup as symbolic.py's run_symbolic_search,
+but instead of just checking whether the sink's address is reached, we
+inspect the VALUE sitting in the sink's own first argument register at
+the moment execution enters it. If that value's Claripy expression
+contains our "sym_input" symbolic variable, the source's data possibly
+flows into what the sink operates on -- not just "control flow got
+there," but "the tainted value got there."
+
+This is a HEURISTIC, single-argument-position check, not a sound full
+taint analysis (per the doc's terminology rules). It can only ever
+report POSSIBLE or INCONCLUSIVE, never CONFIRMED.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+import claripy
+
+from snikrflow.analysis.backends.angr.symbolic import (
+    DEFAULT_INPUT_SIZE,
+    DEFAULT_MAX_ACTIVE_STATES,
+    DEFAULT_MAX_STEPS,
+    DEFAULT_TIMEOUT_SECONDS,
+)
+from snikrflow.core.exceptions import AnalysisIncompleteError
+from snikrflow.core.models import Confidence, DataFlowResult, DataFlowStatus
+from snikrflow.elf.loader import LoadedBinary
+
+
+def check_data_flow(
+    binary: LoadedBinary,
+    source: int,
+    sink: int,
+    avoid: Optional[list[int]] = None,
+    input_size: int = DEFAULT_INPUT_SIZE,
+    max_active_states: int = DEFAULT_MAX_ACTIVE_STATES,
+    max_steps: int = DEFAULT_MAX_STEPS,
+    timeout_seconds: int = DEFAULT_TIMEOUT_SECONDS,
+) -> DataFlowResult:
+    project = binary.project
+    avoid = avoid or []
+
+    sym_input = claripy.BVS("sym_input", input_size * 8)
+
+    try:
+        state = project.factory.call_state(source, 0)
+    except Exception as e:
+        raise AnalysisIncompleteError(
+            f"Failed to build a call state at {hex(source)}: {e}"
+        ) from e
+
+    try:
+        buf_addr = state.heap.allocate(input_size)
+        state.memory.store(buf_addr, sym_input)
+        cc = project.factory.cc()
+        arg_reg = cc.ARG_REGS[0]
+        setattr(state.regs, arg_reg, buf_addr)
+    except Exception as e:
+        raise AnalysisIncompleteError(
+            f"Failed to set up the symbolic argument buffer: {e}"
+        ) from e
+
+    simgr = project.factory.simgr(state)
+
+    start_time = time.time()
+    steps_taken = 0
+    stop_reason = "unknown"
+
+    while simgr.active:
+        if time.time() - start_time > timeout_seconds:
+            stop_reason = "timeout"
+            break
+        if steps_taken >= max_steps:
+            stop_reason = "max_steps_reached"
+            break
+
+        try:
+            simgr.step()
+        except Exception:
+            stop_reason = "step_error"
+            break
+        steps_taken += 1
+
+        if avoid:
+            simgr.move(
+                from_stash="active", to_stash="avoided",
+                filter_func=lambda s: s.addr in avoid,
+            )
+
+        simgr.move(
+            from_stash="active", to_stash="found",
+            filter_func=lambda s: s.addr == sink,
+        )
+
+        if simgr.found:
+            stop_reason = "sink_reached"
+            break
+
+        if len(simgr.active) > max_active_states:
+            simgr.active = simgr.active[:max_active_states]
+
+    if stop_reason == "unknown":
+        if simgr.found:
+            stop_reason = "sink_reached"
+        elif not simgr.active:
+            stop_reason = "no_active_states"
+
+    if not simgr.found:
+        return DataFlowResult(
+            source=source, sink=sink,
+            status=DataFlowStatus.INCONCLUSIVE,
+            confidence=Confidence.INCONCLUSIVE,
+            states_explored=steps_taken, stopped_reason=stop_reason,
+            note="Sink was not reached within the configured limits. This is inconclusive, not proof of safety.",
+        )
+
+    found_state = simgr.found[0]
+
+    if not found_state.solver.satisfiable():
+        return DataFlowResult(
+            source=source, sink=sink,
+            status=DataFlowStatus.INCONCLUSIVE,
+            confidence=Confidence.LOW,
+            states_explored=steps_taken, stopped_reason=stop_reason,
+            note="Sink was reached, but the accumulated path constraints are UNSAT.",
+        )
+
+    # Check the sink's first few argument registers for taint. Two checks
+    # per argument, since attacker data can show up either way:
+    #   1. The register VALUE itself is symbolic (integer/value args, or
+    #      a pointer computed via symbolic arithmetic).
+    #   2. The register holds a concrete-ish pointer to memory that
+    #      itself contains tainted bytes (buffer/string args -- e.g.
+    #      memcpy's `src` -- where the taint lives in the pointed-to
+    #      memory, not the pointer value itself).
+    # We check multiple argument positions (not just arg 1) because for
+    # many real sinks (memcpy, strcpy, sprintf...) the tainted data is
+    # arg 2, not arg 1.
+    try:
+        cc = project.factory.cc()
+        arg_regs = cc.ARG_REGS[:4]
+    except Exception as e:
+        return DataFlowResult(
+            source=source, sink=sink,
+            status=DataFlowStatus.INCONCLUSIVE,
+            confidence=Confidence.INCONCLUSIVE,
+            states_explored=steps_taken, stopped_reason=stop_reason,
+            note=f"Sink was reached but its calling convention could not be resolved: {e}",
+        )
+
+    tainted = False
+    tainted_arg_index: Optional[int] = None
+
+    for idx, reg_name in enumerate(arg_regs):
+        try:
+            reg_value = getattr(found_state.regs, reg_name)
+        except Exception:
+            continue
+
+        if any(v.startswith("sym_input") for v in reg_value.variables):
+            tainted, tainted_arg_index = True, idx
+            break
+
+        if not reg_value.symbolic:
+            try:
+                addr = found_state.solver.eval(reg_value)
+                probe = found_state.memory.load(addr, 16)
+                if any(v.startswith("sym_input") for v in probe.variables):
+                    tainted, tainted_arg_index = True, idx
+                    break
+            except Exception:
+                continue
+
+    if tainted:
+        return DataFlowResult(
+            source=source, sink=sink,
+            status=DataFlowStatus.POSSIBLE,
+            confidence=Confidence.MEDIUM,
+            states_explored=steps_taken, stopped_reason=stop_reason,
+            note=(
+                f"Sink argument #{tainted_arg_index + 1} appears tainted by the "
+                "source's symbolic input (checked both the argument value "
+                "itself and, for pointer arguments, the memory it points "
+                "to). Heuristic result, not a sound full taint analysis."
+            ),
+        )
+
+    return DataFlowResult(
+        source=source, sink=sink,
+        status=DataFlowStatus.INCONCLUSIVE,
+        confidence=Confidence.LOW,
+        states_explored=steps_taken, stopped_reason=stop_reason,
+        note=(
+            "The sink was reached, but none of its first 4 arguments "
+            "(register value or pointed-to memory) appear derived from "
+            "the source's symbolic input. Note: a sink that takes no "
+            "arguments (a bare marker/flag function) will always show "
+            "this result -- there's nothing for it to receive."
+        ),
+    )

snikrflow/analysis/backends/angr/functions.py

@@ -0,0 +1,99 @@
+"""
+SnikrFlow angr backend -- function discovery.
+
+This is one of the few modules allowed to touch angr's analysis objects
+directly (project.analyses.CFGFast, project.kb.functions). It translates
+angr's Function/CFG knowledge-base objects into SnikrFlow-owned Function
+models before handing anything back up the stack.
+
+We run CFGFast rather than CFGEmulated here -- it's the scalable option
+suitable for an initial triage pass. Deeper/emulated CFG analysis is a
+later milestone with its own --cfg-mode flag.
+"""
+
+from __future__ import annotations
+
+from snikrflow.core.exceptions import AnalysisIncompleteError
+from snikrflow.core.models import Function, FunctionSource
+from snikrflow.elf.loader import LoadedBinary
+
+_JNI_PREFIXES = ("Java_",)
+_JNI_EXACT = ("JNI_OnLoad", "JNI_OnUnload")
+
+
+def _looks_like_jni(name: str) -> bool:
+    if not name:
+        return False
+    if name in _JNI_EXACT:
+        return True
+    return name.startswith(_JNI_PREFIXES)
+
+
+def discover_functions(binary: LoadedBinary) -> list[Function]:
+    project = binary.project
+    main_obj = project.loader.main_object
+
+    # Cross-reference lookup: address -> symbol, so we can tell whether an
+    # angr-discovered function also has a name/export/import status.
+    symbol_by_addr = {
+        sym.rebased_addr: sym for sym in main_obj.symbols if sym.rebased_addr
+    }
+
+    try:
+        if len(project.kb.functions) == 0:
+            project.analyses.CFGFast(normalize=True)
+        # else: CFGFast has already populated kb.functions/kb.callgraph on
+        # this project (e.g. an earlier call in the same process, such as
+        # `audit` chaining functions -> jni -> sinks) -- reuse it instead
+        # of re-running the full analysis.
+    except Exception as e:
+        raise AnalysisIncompleteError(f"CFGFast analysis failed: {e}") from e
+
+    functions: list[Function] = []
+
+    for addr, kb_func in project.kb.functions.items():
+        # angr creates synthetic placeholder functions in its own internal
+        # "extern" address space to model imported functions we don't have
+        # the real code for (since auto_load_libs=False). These aren't
+        # real locations inside the analyzed binary, and they show up as
+        # noise (e.g. appearing to call themselves) if not filtered out.
+        if not main_obj.contains_addr(addr):
+            continue
+
+        name = kb_func.name or f"sub_{addr:x}"
+        size = kb_func.size if kb_func.size else None
+
+        is_plt = bool(getattr(kb_func, "is_plt", False))
+        is_simprocedure = bool(getattr(kb_func, "is_simprocedure", False))
+
+        sym = symbol_by_addr.get(addr)
+        has_symbol = sym is not None
+        is_imported = bool(sym.is_import) if sym else is_simprocedure
+        is_exported = bool(getattr(sym, "is_export", False)) if sym else False
+
+        if is_plt:
+            source = FunctionSource.PLT_STUB
+        elif is_imported:
+            source = FunctionSource.IMPORT
+        elif has_symbol:
+            source = FunctionSource.SYMBOL_TABLE
+        else:
+            source = FunctionSource.ANGR_DISCOVERED
+
+        functions.append(
+            Function(
+                address=addr,
+                name=name,
+                size=size,
+                source=source,
+                has_symbol=has_symbol,
+                is_imported=is_imported,
+                is_exported=is_exported,
+                is_plt_stub=is_plt,
+                is_thunk=False,  # thunk detection lands in a later milestone
+                is_jni_candidate=_looks_like_jni(name),
+            )
+        )
+
+    functions.sort(key=lambda f: f.address)
+    return functions

snikrflow/analysis/backends/angr/jni.py

@@ -0,0 +1,45 @@
+"""
+SnikrFlow angr backend -- JNI function discovery.
+
+Reuses discover_functions() from functions.py (which runs CFGFast) rather
+than re-running CFG analysis from scratch. CFGFast populates
+project.kb.callgraph as a side effect, which we use here for callers/
+callees -- so this stays cheap on top of an already-discovered function
+set.
+"""
+
+from __future__ import annotations
+
+from snikrflow.analysis.backends.angr.functions import discover_functions
+from snikrflow.core.models import Function
+from snikrflow.elf.jni import demangle_jni_name
+from snikrflow.elf.loader import LoadedBinary
+
+
+def discover_jni_functions(binary: LoadedBinary) -> list[Function]:
+    all_functions = discover_functions(binary)  # also builds kb.callgraph
+
+    callgraph = binary.project.kb.callgraph
+
+    jni_functions: list[Function] = []
+    for f in all_functions:
+        if not f.is_jni_candidate:
+            continue
+
+        java_class, java_method = demangle_jni_name(f.name)
+        f.likely_java_class = java_class
+        f.likely_java_method = java_method
+
+        try:
+            f.callers = sorted(callgraph.predecessors(f.address))
+        except Exception:
+            f.callers = []
+
+        try:
+            f.callees = sorted(callgraph.successors(f.address))
+        except Exception:
+            f.callees = []
+
+        jni_functions.append(f)
+
+    return jni_functions

snikrflow/analysis/backends/angr/reachability.py

@@ -0,0 +1,84 @@
+"""
+SnikrFlow angr backend -- static reachability.
+
+Static reachability here means call-graph reachability: is there a chain
+of DIRECT calls from source to sink? This only sees direct calls -- it
+does NOT track indirect calls (function pointers, vtables, etc.), so a
+"not reachable" result is never proof of safety, only "no direct call
+chain found." Symbolic/data-flow reachability (later milestones) goes
+further; runtime verification goes further still. These are never
+treated as equivalent, per SnikrFlow's terminology rules.
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+
+from snikrflow.analysis.backends.angr.functions import discover_functions
+from snikrflow.core.models import AnalysisPath, Confidence, ReachabilityType
+from snikrflow.elf.loader import LoadedBinary
+
+
+def check_static_reachability(binary: LoadedBinary, source: int, sink: int) -> AnalysisPath:
+    all_functions = discover_functions(binary)
+    by_addr = {f.address: f for f in all_functions}
+    callgraph = binary.project.kb.callgraph
+
+    if source not in by_addr:
+        return AnalysisPath(
+            source=source, sink=sink, reachable=False,
+            reachability_type=ReachabilityType.INCONCLUSIVE,
+            confidence=Confidence.INCONCLUSIVE,
+            note=f"Source address {hex(source)} is not a known function start.",
+        )
+    if sink not in by_addr:
+        return AnalysisPath(
+            source=source, sink=sink, reachable=False,
+            reachability_type=ReachabilityType.INCONCLUSIVE,
+            confidence=Confidence.INCONCLUSIVE,
+            note=f"Sink address {hex(sink)} is not a known function start.",
+        )
+
+    if source == sink:
+        label = f"{by_addr[source].name} @ {hex(source)}"
+        return AnalysisPath(
+            source=source, sink=sink, reachable=True,
+            reachability_type=ReachabilityType.STATICALLY_REACHABLE,
+            function_path=[source], path_labels=[label],
+            confidence=Confidence.HIGH,
+            note="Source and sink are the same function.",
+        )
+
+    try:
+        path = nx.shortest_path(callgraph, source=source, target=sink)
+    except nx.NetworkXNoPath:
+        return AnalysisPath(
+            source=source, sink=sink, reachable=False,
+            reachability_type=ReachabilityType.NOT_REACHABLE,
+            confidence=Confidence.MEDIUM,
+            note=(
+                "No direct call-graph path found. This does NOT prove the "
+                "sink is unreachable -- indirect calls (function pointers, "
+                "vtables) aren't tracked by this analysis."
+            ),
+        )
+    except nx.NodeNotFound:
+        return AnalysisPath(
+            source=source, sink=sink, reachable=False,
+            reachability_type=ReachabilityType.INCONCLUSIVE,
+            confidence=Confidence.INCONCLUSIVE,
+            note="Source or sink address not present in the call graph.",
+        )
+
+    labels = [
+        f"{by_addr[a].name if a in by_addr else f'sub_{a:x}'} @ {hex(a)}"
+        for a in path
+    ]
+
+    return AnalysisPath(
+        source=source, sink=sink, reachable=True,
+        reachability_type=ReachabilityType.STATICALLY_REACHABLE,
+        function_path=path, path_labels=labels,
+        confidence=Confidence.MEDIUM,
+        note="Based on direct call-graph edges only; indirect/unresolved calls not tracked.",
+    )