Skip to content

armgit / kong

Public Imported from GitHub
0

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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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"