hotflow 0.1.0__py3-none-any.whl

hotflow/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Jarkko Sakkinen <jarkko.sakkinen@iki.fi>
+
+"""Probabilistic control-flow analysis for ELF binaries."""
+
+from hotflow.analyzer import analyze_binary
+
+__version__ = "0.1.0"
+
+__all__ = ["analyze_binary", "__version__"]

hotflow/analyzer.py

@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Jarkko Sakkinen <jarkko.sakkinen@iki.fi>
+
+"""End-to-end analysis orchestration for binary functions."""
+
+from __future__ import annotations
+
+import fnmatch
+from collections.abc import Iterator
+from pathlib import Path
+
+from hotflow.binary import ElfBinary, LoadedFunction
+from hotflow.cfg import build_cfg
+from hotflow.disassembly import disassemble
+from hotflow.frequency import solve_frequencies
+from hotflow.loops import analyze_loops
+from hotflow.metrics import FunctionAnalysis, analyze_metrics
+from hotflow.probability import assign_probabilities
+
+
+def _defined_function_names(elf: ElfBinary) -> list[str]:
+    return [
+        sym.name
+        for sym in elf.list_symbols(function_only=True)
+        if sym.section_name is not None
+    ]
+
+
+def _select_function_names(names: list[str], patterns: list[str]) -> list[str]:
+    """Select exact names or shell globs in pattern order without duplicates."""
+    selected: list[str] = []
+    seen: set[str] = set()
+    for pattern in patterns:
+        for name in names:
+            if name not in seen and (
+                name == pattern or fnmatch.fnmatchcase(name, pattern)
+            ):
+                selected.append(name)
+                seen.add(name)
+    return selected
+
+
+def _analyze_loaded(loaded: LoadedFunction, model_name: str) -> FunctionAnalysis:
+    instructions = disassemble(
+        loaded.code_bytes,
+        base_address=loaded.address,
+        mode_64=loaded.is_64bit,
+        relocations=loaded.relocations,
+    )
+
+    cfg = build_cfg(
+        loaded.address,
+        loaded.size,
+        instructions,
+    )
+    loops = analyze_loops(cfg)
+    assign_probabilities(cfg, loops, model_name)
+    solve_frequencies(cfg)
+
+    return analyze_metrics(
+        symbol=loaded.symbol.name,
+        address=loaded.address,
+        size=loaded.size,
+        architecture=loaded.architecture,
+        section_name=loaded.section_name,
+        model_name=model_name,
+        cfg=cfg,
+        loops=loops,
+    )
+
+
+def analyze_binary(
+    binary_path: str | Path,
+    patterns: list[str] | None = None,
+    model_name: str = "heuristic",
+) -> Iterator[FunctionAnalysis]:
+    """Analyze exact symbol names or shell globs, opening the ELF once."""
+    with ElfBinary(binary_path) as elf:
+        available = _defined_function_names(elf)
+        names = (
+            available
+            if patterns is None
+            else _select_function_names(available, patterns)
+        )
+        for name in names:
+            yield _analyze_loaded(elf.load_function(name), model_name)

hotflow/binary.py

@@ -0,0 +1,294 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Jarkko Sakkinen <jarkko.sakkinen@iki.fi>
+
+"""ELF binary loading, symbol extraction, and section mapping."""
+
+from __future__ import annotations
+
+from bisect import bisect_right
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from elftools.elf.elffile import ELFFile
+from elftools.elf.relocation import RelocationSection
+from elftools.elf.sections import SymbolTableSection
+
+
+class BinaryError(Exception):
+    """Base exception for binary loading and symbol lookup errors."""
+
+
+class SymbolNotFoundError(BinaryError):
+    """Raised when a requested symbol is not found in the binary."""
+
+
+@dataclass
+class SymbolInfo:
+    """An extracted ELF symbol."""
+
+    name: str
+    address: int
+    size: int
+    section_name: str | None
+    section_index: int | None
+    binding: str
+    is_function: bool
+
+
+@dataclass
+class RelocationInfo:
+    """Relocation entry in a relocatable ELF file."""
+
+    offset: int
+    symbol_name: str | None
+
+
+@dataclass
+class LoadedFunction:
+    """A function loaded from an ELF binary ready for disassembly."""
+
+    symbol: SymbolInfo
+    address: int
+    size: int
+    code_bytes: bytes
+    architecture: str
+    is_64bit: bool
+    section_name: str | None = None
+    relocations: dict[int, RelocationInfo] = field(default_factory=dict)
+
+
+class ElfBinary:
+    """Parser and extractor for ELF binaries."""
+
+    def __init__(self, file_path: str | Path) -> None:
+        self._path = Path(file_path)
+        self._file = self._path.open("rb")
+        try:
+            self.elf = ELFFile(self._file)
+        except Exception as error:
+            self._file.close()
+            raise BinaryError(f"Failed to parse ELF file: {error}") from error
+
+        self.arch = self.elf.get_machine_arch()
+        self.is_64bit = self.elf.elfclass == 64
+
+        self._symbol_tables: list[SymbolTableSection] | None = None
+        self._symbols: list[SymbolInfo] | None = None
+        self._symbols_by_name: dict[str, list[SymbolInfo]] | None = None
+        self._section_symbol_addrs: dict[int, list[int]] | None = None
+        self._relocations_by_section: dict[int, dict[int, RelocationInfo]] = {}
+
+    def __enter__(self) -> ElfBinary:
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._file.close()
+
+    def _get_symbol_tables(self) -> list[SymbolTableSection]:
+        if self._symbol_tables is None:
+            tables = []
+            symtab = self.elf.get_section_by_name(".symtab")
+            if isinstance(symtab, SymbolTableSection):
+                tables.append(symtab)
+            dynsym = self.elf.get_section_by_name(".dynsym")
+            if isinstance(dynsym, SymbolTableSection):
+                tables.append(dynsym)
+            self._symbol_tables = tables
+        return self._symbol_tables
+
+    def _ensure_symbol_index(self) -> None:
+        if self._symbols is not None:
+            return
+        symbols: list[SymbolInfo] = []
+        by_name: dict[str, list[SymbolInfo]] = {}
+        section_sym_addrs: dict[int, list[int]] = {}
+        seen: set[tuple[str, int, int | None]] = set()
+        num_sections = self.elf.num_sections()
+        section_names: dict[int, str] = {}
+
+        for table in self._get_symbol_tables():
+            for sym in table.iter_symbols():
+                name = sym.name
+                if not name:
+                    continue
+                st_value = sym["st_value"]
+                sec_idx = sym["st_shndx"]
+                sec_idx_int = sec_idx if isinstance(sec_idx, int) and 0 <= sec_idx < num_sections else None
+                key = (name, st_value, sec_idx_int)
+                if key in seen:
+                    continue
+                seen.add(key)
+
+                if sec_idx_int is not None:
+                    if sec_idx_int not in section_names:
+                        sec = self.elf.get_section(sec_idx_int)
+                        section_names[sec_idx_int] = sec.name if sec else ""
+                    sec_name = section_names[sec_idx_int] or None
+                    section_sym_addrs.setdefault(sec_idx_int, []).append(st_value)
+                else:
+                    sec_name = None
+
+                st_type = sym["st_info"]["type"]
+                is_func = st_type in ("STT_FUNC", "STT_GNU_IFUNC")
+                sym_info = SymbolInfo(
+                    name=name,
+                    address=st_value,
+                    size=sym["st_size"],
+                    section_name=sec_name,
+                    section_index=sec_idx_int,
+                    binding=sym["st_info"]["bind"],
+                    is_function=is_func,
+                )
+                symbols.append(sym_info)
+                by_name.setdefault(name, []).append(sym_info)
+
+        for sec_idx_k in section_sym_addrs:
+            section_sym_addrs[sec_idx_k].sort()
+
+        self._symbols = symbols
+        self._symbols_by_name = by_name
+        self._section_symbol_addrs = section_sym_addrs
+
+    def list_symbols(self, function_only: bool = False) -> list[SymbolInfo]:
+        """List all symbols or function symbols in the ELF."""
+        self._ensure_symbol_index()
+        seen = set()
+        result = []
+        for sym in self._symbols or []:
+            if function_only and not sym.is_function:
+                continue
+            if sym.name in seen:
+                continue
+            seen.add(sym.name)
+            result.append(sym)
+        return result
+
+    def find_symbol(self, symbol_name: str) -> SymbolInfo:
+        """Find a symbol by exact name."""
+        self._ensure_symbol_index()
+        candidates = (self._symbols_by_name or {}).get(symbol_name)
+        if not candidates:
+            raise SymbolNotFoundError(
+                f"Symbol '{symbol_name}' not found in binary '{self._path}'"
+            )
+        func_candidates = [c for c in candidates if c.is_function]
+        if func_candidates:
+            return max(
+                func_candidates,
+                key=lambda s: (
+                    s.section_name is not None,
+                    s.size > 0,
+                    s.binding == "STB_GLOBAL",
+                ),
+            )
+        return candidates[0]
+
+    def _infer_symbol_size(self, symbol: SymbolInfo, section) -> int:
+        """Infer size of a symbol when st_size is 0."""
+        sec_size = section["sh_size"]
+        sec_addr = section["sh_addr"]
+        sym_addr = symbol.address
+
+        min_next_addr = None
+        if symbol.section_index is not None and self._section_symbol_addrs:
+            addrs = self._section_symbol_addrs.get(symbol.section_index)
+            if addrs:
+                idx = bisect_right(addrs, sym_addr)
+                if idx < len(addrs):
+                    min_next_addr = addrs[idx]
+
+        is_relocatable = self.elf["e_type"] == "ET_REL"
+        if is_relocatable:
+            offset = sym_addr
+            if min_next_addr is not None and min_next_addr <= sec_size:
+                return min_next_addr - offset
+            return sec_size - offset
+        else:
+            if min_next_addr is not None and min_next_addr <= (sec_addr + sec_size):
+                return min_next_addr - sym_addr
+            return (sec_addr + sec_size) - sym_addr
+
+    def _get_relocations_for_section(self, section_index: int) -> dict[int, RelocationInfo]:
+        """Extract relocations targeting a specific section."""
+        if section_index in self._relocations_by_section:
+            return self._relocations_by_section[section_index]
+
+        relocs: dict[int, RelocationInfo] = {}
+        for section in self.elf.iter_sections():
+            if isinstance(section, RelocationSection) and section["sh_info"] == section_index:
+                symtab = self.elf.get_section(section["sh_link"])
+                for rel in section.iter_relocations():
+                    sym_name = None
+                    if symtab and rel["r_info_sym"] < symtab.num_symbols():
+                        target_sym = symtab.get_symbol(rel["r_info_sym"])
+                        sym_name = target_sym.name
+
+                    relocs[rel["r_offset"]] = RelocationInfo(
+                        offset=rel["r_offset"],
+                        symbol_name=sym_name,
+                    )
+        self._relocations_by_section[section_index] = relocs
+        return relocs
+
+    def load_function(self, symbol_name: str) -> LoadedFunction:
+        """Extract function bytes and metadata for analysis."""
+        symbol = self.find_symbol(symbol_name)
+
+        if symbol.section_index is None:
+            raise BinaryError(f"Symbol '{symbol_name}' has no defined section")
+
+        section = self.elf.get_section(symbol.section_index)
+        if section is None:
+            raise BinaryError(
+                f"Section index {symbol.section_index} for symbol '{symbol_name}' not found"
+            )
+
+        is_relocatable = self.elf["e_type"] == "ET_REL"
+        sec_data = section.data()
+        sec_addr = section["sh_addr"]
+
+        if is_relocatable:
+            func_offset = symbol.address
+            actual_addr = symbol.address
+        else:
+            func_offset = symbol.address - sec_addr
+            actual_addr = symbol.address
+
+        if func_offset < 0 or func_offset >= len(sec_data):
+            raise BinaryError(
+                f"Symbol '{symbol_name}' offset {func_offset} is outside section '{section.name}' (size {len(sec_data)})"
+            )
+
+        func_size = symbol.size
+        if func_size == 0:
+            func_size = self._infer_symbol_size(symbol, section)
+
+        if func_size <= 0:
+            raise BinaryError(f"Unable to determine size for symbol '{symbol_name}'")
+
+        code_bytes = sec_data[func_offset : func_offset + func_size]
+        relocations = self._get_relocations_for_section(symbol.section_index)
+
+        # Adjust relocations relative to function address/offset
+        func_relocs: dict[int, RelocationInfo] = {}
+        for r_offset, r_info in relocations.items():
+            if is_relocatable:
+                if func_offset <= r_offset < func_offset + func_size:
+                    func_relocs[r_offset] = r_info
+            else:
+                if actual_addr <= r_offset < actual_addr + func_size:
+                    func_relocs[r_offset] = r_info
+
+        return LoadedFunction(
+            symbol=symbol,
+            address=actual_addr,
+            size=len(code_bytes),
+            code_bytes=code_bytes,
+            architecture=self.arch,
+            is_64bit=self.is_64bit,
+            section_name=section.name,
+            relocations=func_relocs,
+        )

hotflow/cfg.py

@@ -0,0 +1,255 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Jarkko Sakkinen <jarkko.sakkinen@iki.fi>
+
+"""Control-Flow Graph (CFG) representation and construction."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+import networkx as nx
+
+from hotflow.disassembly import Instruction, InstructionCategory
+
+
+class EdgeKind(str, Enum):
+    """Types of control-flow edges."""
+
+    FALLTHROUGH = "fallthrough"
+    CONDITIONAL_TAKEN = "conditional_taken"
+    UNCONDITIONAL = "unconditional"
+    BACKEDGE = "backedge"
+
+
+@dataclass
+class Edge:
+    """An edge between basic blocks in the CFG."""
+
+    src: int
+    dst: int
+    kind: EdgeKind
+    probability: float = 0.0
+    probability_source: str = ""
+    confidence: str = "medium"
+    reason: str = ""
+    frequency: float = 0.0
+
+
+@dataclass
+class BasicBlock:
+    """A basic block of linear machine instructions."""
+
+    address: int
+    size: int
+    instructions: list[Instruction] = field(default_factory=list)
+    flags: set[str] = field(default_factory=set)
+    frequency: float = 0.0
+    reach_probability: float = 0.0
+
+    @property
+    def last_instruction(self) -> Instruction | None:
+        return self.instructions[-1] if self.instructions else None
+
+    @property
+    def instruction_count(self) -> int:
+        return len(self.instructions)
+
+    @property
+    def branch_count(self) -> int:
+        return sum(1 for insn in self.instructions if insn.is_branch)
+
+    @property
+    def call_count(self) -> int:
+        return sum(1 for insn in self.instructions if insn.is_call)
+
+    @property
+    def return_count(self) -> int:
+        return sum(1 for insn in self.instructions if insn.is_return)
+
+    @property
+    def is_exit(self) -> bool:
+        return "exit" in self.flags
+
+    @property
+    def is_trap(self) -> bool:
+        return "trap" in self.flags or "noreturn" in self.flags
+
+
+class CFG:
+    """Control-Flow Graph for a function."""
+
+    def __init__(self, entry_address: int) -> None:
+        self.entry_address = entry_address
+        self.graph: nx.DiGraph[int] = nx.DiGraph()
+
+    def add_block(self, block: BasicBlock) -> None:
+        self.graph.add_node(block.address, block=block)
+
+    def add_edge(self, edge: Edge) -> None:
+        self.graph.add_edge(edge.src, edge.dst, edge=edge)
+
+    def get_block(self, address: int) -> BasicBlock | None:
+        data = self.graph.nodes.get(address)
+        return data["block"] if data else None
+
+    @property
+    def blocks(self) -> dict[int, BasicBlock]:
+        return {addr: data["block"] for addr, data in self.graph.nodes(data=True)}
+
+    @property
+    def edges(self) -> list[Edge]:
+        return [data["edge"] for _, _, data in self.graph.edges(data=True)]
+
+    def get_outgoing_edges(self, block_address: int) -> list[Edge]:
+        return [
+            data["edge"]
+            for _, _, data in self.graph.out_edges(block_address, data=True)
+        ]
+
+    def get_edge(self, src: int, dst: int) -> Edge | None:
+        data = self.graph.get_edge_data(src, dst)
+        return data["edge"] if data else None
+
+    @property
+    def exit_blocks(self) -> list[BasicBlock]:
+        return [
+            data["block"]
+            for _, data in self.graph.nodes(data=True)
+            if data["block"].is_exit or self.graph.out_degree(data["block"].address) == 0
+        ]
+
+    @property
+    def reachable_blocks(self) -> set[int]:
+        if not self.graph.has_node(self.entry_address):
+            return set()
+        return {self.entry_address} | nx.descendants(self.graph, self.entry_address)
+
+    @property
+    def cyclomatic_complexity(self) -> int:
+        """Calculate McCabe cyclomatic complexity: E - V + 2P."""
+        v = self.graph.number_of_nodes()
+        e = self.graph.number_of_edges()
+        if v == 0:
+            return 0
+        return max(1, e - v + 2)
+
+
+def build_cfg(
+    function_address: int,
+    function_size: int,
+    instructions: list[Instruction],
+) -> CFG:
+    """Build a control-flow graph from disassembled instructions."""
+    if not instructions:
+        return CFG(function_address)
+
+    function_end = function_address + function_size
+    entry_address = instructions[0].address
+    cfg = CFG(entry_address)
+    address_to_index = {
+        instruction.address: index
+        for index, instruction in enumerate(instructions)
+    }
+    leaders = {entry_address}
+
+    for index, instruction in enumerate(instructions):
+        if instruction.is_branch:
+            if (
+                instruction.target is not None
+                and function_address <= instruction.target < function_end
+                and instruction.target in address_to_index
+            ):
+                leaders.add(instruction.target)
+            if index + 1 < len(instructions):
+                leaders.add(instructions[index + 1].address)
+        elif (instruction.is_return or instruction.is_trap) and index + 1 < len(instructions):
+            leaders.add(instructions[index + 1].address)
+
+    leader_indexes = sorted(address_to_index[address] for address in leaders)
+    for position, start in enumerate(leader_indexes):
+        end = (
+            leader_indexes[position + 1]
+            if position + 1 < len(leader_indexes)
+            else len(instructions)
+        )
+        block_instructions = instructions[start:end]
+        block = BasicBlock(
+            address=block_instructions[0].address,
+            size=sum(instruction.size for instruction in block_instructions),
+            instructions=block_instructions,
+        )
+        if block.address == entry_address:
+            block.flags.add("entry")
+        cfg.add_block(block)
+
+    block_addresses = sorted(cfg.blocks)
+    for index, address in enumerate(block_addresses):
+        block = cfg.blocks[address]
+        last_instruction = block.last_instruction
+        if last_instruction is None:
+            continue
+        next_address = (
+            block_addresses[index + 1]
+            if index + 1 < len(block_addresses)
+            else None
+        )
+
+        if last_instruction.is_conditional:
+            if (
+                last_instruction.target is not None
+                and last_instruction.target in cfg.blocks
+            ):
+                cfg.add_edge(
+                    Edge(
+                        src=block.address,
+                        dst=last_instruction.target,
+                        kind=EdgeKind.CONDITIONAL_TAKEN,
+                    )
+                )
+            fallthrough = last_instruction.address + last_instruction.size
+            if fallthrough in cfg.blocks:
+                cfg.add_edge(
+                    Edge(
+                        src=block.address,
+                        dst=fallthrough,
+                        kind=EdgeKind.FALLTHROUGH,
+                    )
+                )
+        elif last_instruction.is_unconditional:
+            if (
+                last_instruction.target is not None
+                and last_instruction.target in cfg.blocks
+            ):
+                cfg.add_edge(
+                    Edge(
+                        src=block.address,
+                        dst=last_instruction.target,
+                        kind=EdgeKind.UNCONDITIONAL,
+                    )
+                )
+            else:
+                block.flags.add("exit")
+        elif last_instruction.is_return:
+            block.flags.add("exit")
+        elif last_instruction.is_trap:
+            block.flags.update(("trap", "exit"))
+        elif last_instruction.category == InstructionCategory.INDIRECT_BRANCH:
+            block.flags.update(("indirect", "exit"))
+        elif (
+            next_address is not None
+            and last_instruction.address + last_instruction.size == next_address
+        ):
+            cfg.add_edge(
+                Edge(
+                    src=block.address,
+                    dst=next_address,
+                    kind=EdgeKind.FALLTHROUGH,
+                )
+            )
+        else:
+            block.flags.add("exit")
+
+        if not cfg.get_outgoing_edges(block.address):
+            block.flags.add("exit")
+
+    return cfg