The world's first agentic reverse engineer.
feat: add semantic synthesis module for cross-function analysis
Amruthb464b2cd9d8a
diff --git a/kong/synthesis/__init__.py b/kong/synthesis/__init__.pynew file mode 100644index 0000000..3af3ac6--- /dev/null+++ b/kong/synthesis/__init__.py@@ -0,0 +1 @@+"""Semantic synthesis: cross-function LLM analysis for globals, structs, and name refinement."""diff --git a/kong/synthesis/semantic.py b/kong/synthesis/semantic.pynew file mode 100644index 0000000..76bb32d--- /dev/null+++ b/kong/synthesis/semantic.py@@ -0,0 +1,163 @@+"""Semantic synthesis: single LLM call over complete analysis to unify globals, structs, and names."""++from __future__ import annotations++import json+import logging+import re+from dataclasses import dataclass, field+from typing import TYPE_CHECKING++from kong.agent.models import FunctionResult++if TYPE_CHECKING:+ from kong.agent.analyzer import LLMClient++logger = logging.getLogger(__name__)++_DAT_PATTERN = re.compile(r"DAT_[0-9a-fA-F]+")+++@dataclass+class SynthesisResult:+ globals: dict[str, str] = field(default_factory=dict)+ structs: list[dict[str, object]] = field(default_factory=list)+ name_refinements: dict[str, str] = field(default_factory=dict)+++class SemanticSynthesizer:+ """Makes one LLM call over complete post-naming analysis to unify globals, synthesize structs,+ and refine names."""++ def __init__(self, llm: LLMClient) -> None:+ self.llm = llm++ def synthesize(+ self,+ results: list[FunctionResult],+ decompilations: dict[int, str],+ model: str | None = None,+ ) -> SynthesisResult:+ prompt = self._build_synthesis_prompt(results, decompilations)+ response = self.llm.analyze_function(prompt, model=model)+ return self._parse_response(response.raw)++ def _build_synthesis_prompt(+ self,+ results: list[FunctionResult],+ decompilations: dict[int, str],+ ) -> str:+ parts: list[str] = []++ parts.append(+ "You are performing a cross-function synthesis pass over an analyzed binary. "+ "Your three tasks are:"+ )+ parts.append("")+ parts.append(+ "1. **Rename global variables**: For each DAT_XXXXXXXX address that appears "+ "in multiple functions, propose a meaningful name based on how it is used."+ )+ parts.append(+ "2. **Synthesize structs**: If multiple functions access fields at consistent "+ "offsets from the same base pointer or global, propose a struct definition."+ )+ parts.append(+ "3. **Refine function names**: If seeing all functions together reveals better "+ "names than the per-function pass produced, propose refinements."+ )+ parts.append("")+ parts.append("Respond with a single JSON object (no other text):")+ parts.append("```json")+ parts.append("{")+ parts.append(' "globals": {"DAT_XXXXXXXX": "meaningful_name", ...},')+ parts.append(' "structs": [{"name": "StructName", "fields": [{"name": "field", "type": "int", "offset": 0}]}, ...],')+ parts.append(' "name_refinements": {"0xADDRESS": "better_name", ...}')+ parts.append("}")+ parts.append("```")++ globals_map = self._extract_globals(decompilations)+ results_by_addr = {r.address: r for r in results}++ multi_use_globals = {+ name: addrs for name, addrs in globals_map.items() if len(addrs) >= 2+ }++ if multi_use_globals:+ parts.append("")+ parts.append("## Global Variables")+ parts.append("")+ for dat_name, addrs in sorted(multi_use_globals.items()):+ func_names = []+ for addr in sorted(addrs):+ r = results_by_addr.get(addr)+ label = r.name if r else f"FUN_{addr:08x}"+ func_names.append(label)+ parts.append(f"- `{dat_name}` referenced by: {', '.join(func_names)}")++ parts.append("")+ parts.append("## Functions and Decompilations")+ parts.append("")++ for result in results:+ if result.address not in decompilations:+ continue+ parts.append(f"### {result.name} (0x{result.address:08x})")+ parts.append(f"Classification: {result.classification}, Confidence: {result.confidence}")+ parts.append("```c")+ parts.append(decompilations[result.address])+ parts.append("```")+ parts.append("")++ return "\n".join(parts)++ def _extract_globals(self, decompilations: dict[int, str]) -> dict[str, set[int]]:+ result: dict[str, set[int]] = {}+ for addr, code in decompilations.items():+ for match in _DAT_PATTERN.finditer(code):+ dat_name = match.group(0)+ if dat_name not in result:+ result[dat_name] = set()+ result[dat_name].add(addr)+ return result++ @staticmethod+ def _parse_response(raw: str) -> SynthesisResult:+ text = raw.strip()++ if "```json" in text:+ start = text.index("```json") + 7+ end = text.index("```", start)+ text = text[start:end].strip()+ elif "```" in text:+ start = text.index("```") + 3+ end = text.index("```", start)+ text = text[start:end].strip()++ try:+ data = json.loads(text)+ except (json.JSONDecodeError, ValueError):+ logger.warning("Failed to parse synthesis response as JSON")+ return SynthesisResult()++ return SynthesisResult(+ globals=data.get("globals", {}),+ structs=data.get("structs", []),+ name_refinements=data.get("name_refinements", {}),+ )++ @staticmethod+ def _apply_globals(code: str, globals_map: dict[str, str]) -> str:+ for dat_name, meaningful_name in globals_map.items():+ code = code.replace(dat_name, meaningful_name)+ return code++ def apply_to_decompilations(+ self,+ result: SynthesisResult,+ decompilations: dict[int, str],+ ) -> dict[int, str]:+ return {+ addr: self._apply_globals(code, result.globals)+ for addr, code in decompilations.items()+ }diff --git a/tests/test_synthesis.py b/tests/test_synthesis.pynew file mode 100644index 0000000..35375e5--- /dev/null+++ b/tests/test_synthesis.py@@ -0,0 +1,242 @@+"""Tests for the semantic synthesis module."""++from __future__ import annotations++from dataclasses import dataclass++import pytest++from kong.agent.models import FunctionResult+from kong.synthesis.semantic import SemanticSynthesizer, SynthesisResult+++@dataclass+class FakeLLMResponse:+ raw: str = ""+ input_tokens: int = 0+ output_tokens: int = 0+++class FakeLLMClient:+ """Minimal mock satisfying the LLMClient protocol for synthesis tests."""++ def __init__(self, raw_response: str = "{}") -> None:+ self._raw_response = raw_response+ self.last_prompt: str = ""+ self.last_model: str | None = None++ def analyze_function(+ self, prompt: str, *, model: str | None = None+ ) -> FakeLLMResponse:+ self.last_prompt = prompt+ self.last_model = model+ return FakeLLMResponse(raw=self._raw_response)++ def analyze_with_tools(+ self,+ prompt: str,+ system: str,+ tools: list[dict[str, object]],+ tool_executor: object,+ max_rounds: int = 10,+ ) -> FakeLLMResponse:+ return FakeLLMResponse(raw=self._raw_response)+++SAMPLE_DECOMP_A = """\+void FUN_00401000(void) {+ int local_8 = DAT_100008000;+ int local_c = DAT_100004000;+ printf("%d", local_8 + local_c);+}+"""++SAMPLE_DECOMP_B = """\+void FUN_00402000(void) {+ int val = DAT_100008000;+ return val * 2;+}+"""++SAMPLE_DECOMP_NO_GLOBALS = """\+int add(int a, int b) {+ return a + b;+}+"""+++def _make_result(+ address: int,+ name: str = "",+ classification: str = "utility",+ confidence: int = 70,+) -> FunctionResult:+ return FunctionResult(+ address=address,+ original_name=f"FUN_{address:08x}",+ name=name or f"func_{address:x}",+ classification=classification,+ confidence=confidence,+ )+++class TestGlobalExtraction:+ def test_extracts_globals_from_multiple_functions(self) -> None:+ decompilations = {+ 0x401000: SAMPLE_DECOMP_A,+ 0x402000: SAMPLE_DECOMP_B,+ }+ synth = SemanticSynthesizer(FakeLLMClient())+ result = synth._extract_globals(decompilations)++ assert "DAT_100008000" in result+ assert result["DAT_100008000"] == {0x401000, 0x402000}++ assert "DAT_100004000" in result+ assert result["DAT_100004000"] == {0x401000}++ def test_no_globals_when_none_present(self) -> None:+ decompilations = {+ 0x401000: SAMPLE_DECOMP_NO_GLOBALS,+ }+ synth = SemanticSynthesizer(FakeLLMClient())+ result = synth._extract_globals(decompilations)+ assert result == {}+++class TestPromptBuilding:+ def test_includes_multi_use_globals(self) -> None:+ results = [_make_result(0x401000, "process_data"), _make_result(0x402000, "compute")]+ decompilations = {0x401000: SAMPLE_DECOMP_A, 0x402000: SAMPLE_DECOMP_B}+ synth = SemanticSynthesizer(FakeLLMClient())+ prompt = synth._build_synthesis_prompt(results, decompilations)++ assert "DAT_100008000" in prompt+ assert "process_data" in prompt or "compute" in prompt++ def test_excludes_single_use_globals(self) -> None:+ results = [_make_result(0x401000, "process_data"), _make_result(0x402000, "compute")]+ decompilations = {0x401000: SAMPLE_DECOMP_A, 0x402000: SAMPLE_DECOMP_B}+ synth = SemanticSynthesizer(FakeLLMClient())+ prompt = synth._build_synthesis_prompt(results, decompilations)++ global_section_start = prompt.find("## Global Variables")+ functions_section_start = prompt.find("## Functions and Decompilations")+ if global_section_start != -1 and functions_section_start != -1:+ global_section = prompt[global_section_start:functions_section_start]+ assert "DAT_100004000" not in global_section++ def test_includes_all_functions(self) -> None:+ results = [_make_result(0x401000, "alpha"), _make_result(0x402000, "beta")]+ decompilations = {+ 0x401000: SAMPLE_DECOMP_NO_GLOBALS,+ 0x402000: SAMPLE_DECOMP_NO_GLOBALS,+ }+ synth = SemanticSynthesizer(FakeLLMClient())+ prompt = synth._build_synthesis_prompt(results, decompilations)++ assert "alpha" in prompt+ assert "beta" in prompt+ assert "0x00401000" in prompt+ assert "0x00402000" in prompt+++class TestResponseParsing:+ def test_parse_valid_json(self) -> None:+ raw = '''{+ "globals": {"DAT_100008000": "g_counter"},+ "structs": [{"name": "Point", "fields": [{"name": "x", "type": "int", "offset": 0}]}],+ "name_refinements": {"0x00401000": "init_counter"}+ }'''+ result = SemanticSynthesizer._parse_response(raw)+ assert result.globals == {"DAT_100008000": "g_counter"}+ assert len(result.structs) == 1+ assert result.structs[0]["name"] == "Point"+ assert result.name_refinements == {"0x00401000": "init_counter"}++ def test_parse_json_in_markdown_fence(self) -> None:+ raw = '''Some preamble text+```json+{+ "globals": {"DAT_100008000": "g_config"},+ "structs": [],+ "name_refinements": {}+}+```+Trailing text'''+ result = SemanticSynthesizer._parse_response(raw)+ assert result.globals == {"DAT_100008000": "g_config"}++ def test_parse_empty_response(self) -> None:+ result = SemanticSynthesizer._parse_response("not valid json at all")+ assert result.globals == {}+ assert result.structs == []+ assert result.name_refinements == {}++ def test_parse_partial_response(self) -> None:+ raw = '{"globals": {"DAT_100008000": "g_flag"}}'+ result = SemanticSynthesizer._parse_response(raw)+ assert result.globals == {"DAT_100008000": "g_flag"}+ assert result.structs == []+ assert result.name_refinements == {}+++class TestGlobalApplication:+ def test_apply_globals_replaces_dat_names(self) -> None:+ code = "int val = DAT_100008000 + DAT_100008000;"+ globals_map = {"DAT_100008000": "g_counter"}+ result = SemanticSynthesizer._apply_globals(code, globals_map)+ assert result == "int val = g_counter + g_counter;"++ def test_apply_globals_preserves_unmapped(self) -> None:+ code = "int a = DAT_100004000; int b = DAT_100008000;"+ globals_map = {"DAT_100008000": "g_counter"}+ result = SemanticSynthesizer._apply_globals(code, globals_map)+ assert "DAT_100004000" in result+ assert "g_counter" in result++ def test_apply_to_decompilations_all_functions(self) -> None:+ decompilations = {+ 0x401000: "use DAT_100008000;",+ 0x402000: "read DAT_100008000;",+ }+ synthesis_result = SynthesisResult(+ globals={"DAT_100008000": "g_value"},+ structs=[],+ name_refinements={},+ )+ synth = SemanticSynthesizer(FakeLLMClient())+ updated = synth.apply_to_decompilations(synthesis_result, decompilations)+ assert updated[0x401000] == "use g_value;"+ assert updated[0x402000] == "read g_value;"+++class TestSynthesizeIntegration:+ def test_synthesize_calls_llm_and_returns_result(self) -> None:+ raw_response = '''{+ "globals": {"DAT_100008000": "g_state"},+ "structs": [],+ "name_refinements": {"0x00401000": "initialize_state"}+ }'''+ llm = FakeLLMClient(raw_response=raw_response)+ synth = SemanticSynthesizer(llm)++ results = [_make_result(0x401000, "process_data"), _make_result(0x402000, "compute")]+ decompilations = {0x401000: SAMPLE_DECOMP_A, 0x402000: SAMPLE_DECOMP_B}++ synthesis = synth.synthesize(results, decompilations)++ assert llm.last_prompt != ""+ assert "DAT_100008000" in llm.last_prompt+ assert synthesis.globals == {"DAT_100008000": "g_state"}+ assert synthesis.name_refinements == {"0x00401000": "initialize_state"}++ def test_synthesize_with_model_override(self) -> None:+ llm = FakeLLMClient(raw_response='{"globals": {}, "structs": [], "name_refinements": {}}')+ synth = SemanticSynthesizer(llm)++ results = [_make_result(0x401000)]+ decompilations = {0x401000: SAMPLE_DECOMP_NO_GLOBALS}++ synth.synthesize(results, decompilations, model="claude-haiku-4-5-20251001")+ assert llm.last_model == "claude-haiku-4-5-20251001"