Skip to content

armgit / kong

Public Imported from GitHub
0

The world's first agentic reverse engineer.

add type recovery by impl struct proposals and unification process

Amruth05ef03dabf12
diff --git a/kong/agent/analyzer.py b/kong/agent/analyzer.py
index 54fbfb6..d33df71 100644
--- a/kong/agent/analyzer.py
+++ b/kong/agent/analyzer.py
@@ -15,7 +15,7 @@ from typing import Protocol
from kong.agent.models import FunctionResult
from kong.agent.queue import WorkItem
from kong.ghidra.client import GhidraClient
-from kong.ghidra.types import BinaryInfo, FunctionInfo, StringEntry
+from kong.ghidra.types import BinaryInfo, FunctionInfo, StringEntry, StructDefinition
logger = logging.getLogger(__name__)
@@ -39,6 +39,7 @@ class LLMResponse:
comments: str = ""
reasoning: str = ""
variables: list[VariableRename] = field(default_factory=list)
+ struct_proposals: list[StructProposal] = field(default_factory=list)
raw: str = ""
input_tokens: int = 0
output_tokens: int = 0
@@ -50,6 +51,24 @@ class VariableRename:
new_name: str
+@dataclass
+class StructFieldProposal:
+ name: str
+ data_type: str
+ offset: int
+ size: int
+
+
+@dataclass
+class StructProposal:
+ """A struct layout proposed by the LLM based on offset-based memory accesses."""
+ name: str
+ total_size: int
+ fields: list[StructFieldProposal] = field(default_factory=list)
+ used_by_param: str = ""
+ source_function: int = 0
+
+
@dataclass
class AnalysisContext:
"""All context assembled for analyzing a single function."""
@@ -60,6 +79,7 @@ class AnalysisContext:
callee_snippets: list[CalleeSnippet] = field(default_factory=list)
referenced_strings: list[str] = field(default_factory=list)
known_functions: dict[int, str] = field(default_factory=dict)
+ known_types: list[StructDefinition] = field(default_factory=list)
@dataclass
@@ -98,17 +118,15 @@ class Analyzer:
binary_info: BinaryInfo,
known_results: dict[int, FunctionResult],
strings: list[StringEntry],
+ known_types: list[StructDefinition] | None = None,
) -> FunctionResult:
"""Full analysis pipeline for one function."""
func = item.function
- context = self._build_context(item, binary_info, known_results, strings)
+ context = self._build_context(item, binary_info, known_results, strings, known_types)
prompt = self._build_prompt(context)
response = self.llm.analyze_function(prompt)
- # TODO: validation?
- # TODO: error handling?
- # TODO: track token usage?
self._write_back(func.address, response)
@@ -122,6 +140,7 @@ class Analyzer:
comments=response.comments,
reasoning=response.reasoning,
llm_calls=1,
+ struct_proposals=response.struct_proposals,
)
def _build_context(
@@ -130,6 +149,7 @@ class Analyzer:
binary_info: BinaryInfo,
known_results: dict[int, FunctionResult],
strings: list[StringEntry],
+ known_types: list[StructDefinition] | None = None,
) -> AnalysisContext:
"""Assemble all context the LLM needs to analyze this function."""
func = item.function
@@ -155,6 +175,7 @@ class Analyzer:
callee_snippets=callee_snippets,
referenced_strings=func_strings,
known_functions=known_map,
+ known_types=known_types or [],
)
def _get_caller_snippets(
@@ -277,6 +298,20 @@ class Analyzer:
for addr, name in sorted(context.known_functions.items()):
parts.append(f"- 0x{addr:08x}: {name}")
+ if context.known_types:
+ parts.append("")
+ parts.append("### Known Struct Types")
+ parts.append(
+ "These structs have been recovered from the binary. "
+ "Use them in your signature if the function's parameters match."
+ )
+ for sd in context.known_types:
+ parts.append(f"\n```c\nstruct {sd.name} {{ // {sd.size} bytes")
+ for f in sd.fields:
+ parts.append(f" {f.data_type} {f.name}; // offset 0x{f.offset:x}, {f.size} bytes")
+ parts.append("};")
+ parts.append("```")
+
return "\n".join(parts)
def _write_back(self, addr: int, response: LLMResponse) -> None:
@@ -331,6 +366,26 @@ class Analyzer:
if "old_name" in v and "new_name" in v
]
+ struct_proposals = []
+ for sp in data.get("struct_proposals", []):
+ if "name" not in sp or "total_size" not in sp:
+ continue
+ fields = [
+ StructFieldProposal(
+ name=f.get("name", f"field_{i}"),
+ data_type=f.get("data_type", "undefined"),
+ offset=f.get("offset", 0),
+ size=f.get("size", 4),
+ )
+ for i, f in enumerate(sp.get("fields", []))
+ ]
+ struct_proposals.append(StructProposal(
+ name=sp["name"],
+ total_size=sp["total_size"],
+ fields=fields,
+ used_by_param=sp.get("used_by_param", ""),
+ ))
+
return LLMResponse(
name=data.get("name", ""),
signature=data.get("signature", ""),
@@ -339,5 +394,6 @@ class Analyzer:
comments=data.get("comments", ""),
reasoning=data.get("reasoning", ""),
variables=variables,
+ struct_proposals=struct_proposals,
raw=raw,
)
diff --git a/kong/agent/events.py b/kong/agent/events.py
index 4958c56..36fddb4 100644
--- a/kong/agent/events.py
+++ b/kong/agent/events.py
@@ -31,6 +31,9 @@ class EventType(Enum):
LLM_CALL_START = "llm_call_start"
LLM_CALL_COMPLETE = "llm_call_complete"
+ CLEANUP_TYPES_UNIFIED = "cleanup_types_unified"
+ CLEANUP_TYPE_CREATED = "cleanup_type_created"
+
EXPORT_FILE = "export_file"
RUN_START = "run_start"
diff --git a/kong/agent/models.py b/kong/agent/models.py
index e9707a6..15a4280 100644
--- a/kong/agent/models.py
+++ b/kong/agent/models.py
@@ -2,7 +2,11 @@
from __future__ import annotations
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+ from kong.agent.analyzer import StructProposal
@dataclass
@@ -20,3 +24,4 @@ class FunctionResult:
llm_calls: int = 0
skipped: bool = False
skip_reason: str = ""
+ struct_proposals: list[StructProposal] = field(default_factory=list)
diff --git a/kong/agent/prompts.py b/kong/agent/prompts.py
index 2ae1dc3..a81cd8c 100644
--- a/kong/agent/prompts.py
+++ b/kong/agent/prompts.py
@@ -12,6 +12,13 @@ Your analysis must be precise:
- If you cannot determine a function's purpose, say so — do not guess
- Confidence reflects how certain you are, not how important the function is
+Type recovery:
+- When a parameter is a pointer and the function accesses it at multiple fixed \
+offsets (e.g. *(param + 0x10), param[3], param->field_0x8), propose a struct layout
+- Only propose structs when there are at least 2 distinct field accesses at \
+concrete offsets — do not propose structs for single-field or ambiguous accesses
+- Name struct fields based on how they are used in the function
+
You respond only with a JSON object. No prose before or after."""
OUTPUT_SCHEMA = """\
@@ -24,7 +31,18 @@ Respond with exactly one JSON object:
"classification": "<category>",
"comments": "Brief description of what the function does",
"reasoning": "Why you chose this name and classification",
- "variables": [{"old_name": "local_10", "new_name": "buffer"}]
+ "variables": [{"old_name": "local_10", "new_name": "buffer"}],
+ "struct_proposals": [
+ {
+ "name": "struct_name",
+ "total_size": 32,
+ "fields": [
+ {"name": "field_name", "data_type": "int", "offset": 0, "size": 4},
+ {"name": "another_field", "data_type": "char *", "offset": 8, "size": 8}
+ ],
+ "used_by_param": "param_1"
+ }
+ ]
}
```
@@ -36,4 +54,7 @@ Confidence guidelines:
- 70-89: Strong structural evidence for the name (clear string refs, API calls)
- 50-69: Reasonable inference from context but multiple interpretations possible
- 30-49: Educated guess based on limited evidence
-- 0-29: Very uncertain, minimal evidence"""
+- 0-29: Very uncertain, minimal evidence
+
+struct_proposals: Only include when you see a pointer parameter accessed at \
+multiple fixed offsets. Omit entirely if there are no struct patterns."""
diff --git a/kong/agent/supervisor.py b/kong/agent/supervisor.py
index aae685a..6c36e67 100644
--- a/kong/agent/supervisor.py
+++ b/kong/agent/supervisor.py
@@ -15,6 +15,7 @@ from kong.agent.models import FunctionResult
from kong.agent.queue import WorkItem, WorkQueue
from kong.agent.signatures import SignatureDB
from kong.agent.triage import TriageAgent, TriageResult
+from kong.agent.type_recovery import StructAccumulator, apply_unified_structs
from kong.config import KongConfig
from kong.ghidra.client import GhidraClient
from kong.ghidra.types import BinaryInfo, FunctionInfo, StringEntry
@@ -93,6 +94,7 @@ class Supervisor:
self.binary_info: BinaryInfo | None = None
self.functions: list[FunctionInfo] = []
self.strings: list[StringEntry] = []
+ self.struct_accumulator = StructAccumulator()
self._listeners: list[EventCallback] = []
self._paused: bool = False
@@ -261,6 +263,9 @@ class Supervisor:
self.results[func.address] = result
self.stats.record_result(result)
+ if result.struct_proposals:
+ self.struct_accumulator.add_proposals(func.address, result.struct_proposals)
+
if not result.error and not result.skipped:
self._emit(Event(
type=EventType.FUNCTION_COMPLETE,
@@ -316,24 +321,135 @@ class Supervisor:
)
def _run_cleanup(self) -> None:
- """Re-analyze low-confidence functions with accumulated context."""
+ """Unify struct types, apply to Ghidra, re-analyze affected and low-confidence functions."""
self._emit(Event(
type=EventType.PHASE_START,
phase=Phase.CLEANUP,
message="Starting cleanup pass...",
))
+ structs_created = 0
+ retyped_addrs: list[int] = []
+
+ if self.struct_accumulator.proposal_count > 0:
+ unified = self.struct_accumulator.unify()
+ self._emit(Event(
+ type=EventType.CLEANUP_TYPES_UNIFIED,
+ phase=Phase.CLEANUP,
+ message=(
+ f"Unified {self.struct_accumulator.proposal_count} struct proposals "
+ f"into {len(unified)} types."
+ ),
+ data={
+ "proposals": self.struct_accumulator.proposal_count,
+ "unified": len(unified),
+ },
+ ))
+
+ retyped_addrs = apply_unified_structs(self.client, unified)
+ structs_created = len(unified)
+
+ for us in unified:
+ self._emit(Event(
+ type=EventType.CLEANUP_TYPE_CREATED,
+ phase=Phase.CLEANUP,
+ message=(
+ f"Created struct '{us.definition.name}' "
+ f"({us.definition.size} bytes, {us.definition.field_count} fields)"
+ ),
+ data={
+ "name": us.definition.name,
+ "size": us.definition.size,
+ "fields": us.definition.field_count,
+ },
+ ))
+
low_confidence = [
r for r in self.results.values()
if not r.skipped and not r.error and r.confidence < 50
]
+ low_conf_addrs = {r.address for r in low_confidence}
+
+ reanalyze_addrs = sorted(set(retyped_addrs) | low_conf_addrs)
+ reanalyzed = 0
+
+ if reanalyze_addrs and self.llm_client is not None:
+ known_types = self.client.list_custom_types()
+ analyzer = Analyzer(self.client, self.llm_client)
+
+ for addr in reanalyze_addrs:
+ if self._paused:
+ continue
+
+ old_result = self.results.get(addr)
+ func_name = old_result.original_name if old_result else f"FUN_{addr:08x}"
+
+ self._emit(Event(
+ type=EventType.FUNCTION_START,
+ phase=Phase.CLEANUP,
+ message=f"Re-analyzing {func_name} (0x{addr:08x})...",
+ data={"address": addr, "name": func_name},
+ ))
+
+ func_info = self._find_function(addr)
+ if func_info is None:
+ continue
+
+ item = WorkItem(
+ function=func_info,
+ callers=self.triage_result.call_graph.callers.get(addr, []) if self.triage_result else [],
+ callees=self.triage_result.call_graph.callees.get(addr, []) if self.triage_result else [],
+ )
+
+ try:
+ new_result = analyzer.analyze(
+ item,
+ binary_info=self.binary_info,
+ known_results=self.results,
+ strings=self.strings,
+ known_types=known_types,
+ )
+ except Exception as e:
+ self._emit(Event(
+ type=EventType.FUNCTION_ERROR,
+ phase=Phase.CLEANUP,
+ message=f"Error re-analyzing {func_name}: {e}",
+ data={"address": addr, "error": str(e)},
+ ))
+ continue
+
+ if new_result.confidence > (old_result.confidence if old_result else 0):
+ self.results[addr] = new_result
+ reanalyzed += 1
+
+ self._emit(Event(
+ type=EventType.FUNCTION_COMPLETE,
+ phase=Phase.CLEANUP,
+ message=(
+ f"0x{addr:08x} → {new_result.name} "
+ f"(confidence: {new_result.confidence}%, "
+ f"was {old_result.confidence if old_result else 0}%)"
+ ),
+ data={
+ "address": addr,
+ "name": new_result.name,
+ "confidence": new_result.confidence,
+ "previous_confidence": old_result.confidence if old_result else 0,
+ },
+ ))
- # TODO: Re-analyze with full context
self._emit(Event(
type=EventType.PHASE_COMPLETE,
phase=Phase.CLEANUP,
- message=f"Cleanup complete. {len(low_confidence)} functions re-examined.",
- data={"re_examined": len(low_confidence)},
+ message=(
+ f"Cleanup complete. {structs_created} structs created, "
+ f"{reanalyzed}/{len(reanalyze_addrs)} functions improved."
+ ),
+ data={
+ "structs_created": structs_created,
+ "reanalyze_candidates": len(reanalyze_addrs),
+ "reanalyzed": reanalyzed,
+ },
))
def _run_export(self) -> None:
@@ -356,6 +472,13 @@ class Supervisor:
))
+ def _find_function(self, addr: int) -> FunctionInfo | None:
+ """Look up a FunctionInfo by address from the triage function list."""
+ for f in self.functions:
+ if f.address == addr:
+ return f
+ return None
+
def _stats_dict(self) -> dict[str, int | float]:
s = self.stats
return {
diff --git a/kong/agent/type_recovery.py b/kong/agent/type_recovery.py
new file mode 100644
index 0000000..142bb2b
--- /dev/null
+++ b/kong/agent/type_recovery.py
@@ -0,0 +1,240 @@
+"""Type recovery — accumulate struct proposals from analysis, unify, and apply.
+
+Collects StructProposal objects emitted by the LLM during Phase 2 (analysis),
+merges proposals that describe the same underlying struct across multiple
+functions, creates the unified types in Ghidra, and identifies functions that
+should be re-analyzed with the improved type information.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from dataclasses import dataclass, field
+
+from kong.agent.analyzer import StructFieldProposal, StructProposal
+from kong.ghidra.client import GhidraClient
+from kong.ghidra.types import StructDefinition, StructField
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ParamTypeApplication:
+ """Records that a specific function parameter should receive a struct type."""
+ func_addr: int
+ param_name: str
+ struct_name: str
+
+
+@dataclass
+class UnifiedStruct:
+ """A struct definition produced by merging multiple proposals."""
+ definition: StructDefinition
+ source_proposals: list[StructProposal] = field(default_factory=list)
+ applications: list[ParamTypeApplication] = field(default_factory=list)
+
+
+class StructAccumulator:
+ """Collects struct proposals and unifies them into concrete types.
+
+ Usage during analysis::
+
+ acc = StructAccumulator()
+ # after each function analysis:
+ acc.add_proposals(func_addr, response.struct_proposals)
+ # during cleanup:
+ unified = acc.unify()
+ """
+
+ def __init__(self) -> None:
+ self._proposals: list[StructProposal] = []
+
+ @property
+ def proposal_count(self) -> int:
+ return len(self._proposals)
+
+ def add_proposals(self, func_addr: int, proposals: list[StructProposal]) -> None:
+ for p in proposals:
+ tagged = StructProposal(
+ name=p.name,
+ total_size=p.total_size,
+ fields=list(p.fields),
+ used_by_param=p.used_by_param,
+ source_function=func_addr,
+ )
+ self._proposals.append(tagged)
+
+ def unify(self) -> list[UnifiedStruct]:
+ """Merge proposals that describe the same struct.
+
+ Grouping strategy: two proposals are considered to describe the same
+ struct if they have the same total_size AND share at least one field
+ at the same offset with a compatible type. Within each group the
+ LLM-given name that appears most often wins; fields are merged by
+ offset, preferring the most descriptive name.
+ """
+ if not self._proposals:
+ return []
+
+ groups = self._group_proposals()
+ return [self._merge_group(g) for g in groups]
+
+ def _group_proposals(self) -> list[list[StructProposal]]:
+ by_size: dict[int, list[StructProposal]] = defaultdict(list)
+ for p in self._proposals:
+ by_size[p.total_size].append(p)
+
+ groups: list[list[StructProposal]] = []
+ for same_size in by_size.values():
+ sub = self._split_by_field_overlap(same_size)
+ groups.extend(sub)
+ return groups
+
+ @staticmethod
+ def _split_by_field_overlap(proposals: list[StructProposal]) -> list[list[StructProposal]]:
+ """Within same-size proposals, cluster by overlapping field offsets."""
+ if len(proposals) <= 1:
+ return [proposals]
+
+ assigned: list[int] = [-1] * len(proposals)
+ group_id = 0
+
+ for i, pi in enumerate(proposals):
+ if assigned[i] == -1:
+ assigned[i] = group_id
+ group_id += 1
+
+ offsets_i = {f.offset for f in pi.fields}
+ for j in range(i + 1, len(proposals)):
+ if assigned[j] != -1:
+ continue
+ offsets_j = {f.offset for f in proposals[j].fields}
+ if offsets_i & offsets_j:
+ assigned[j] = assigned[i]
+
+ clusters: dict[int, list[StructProposal]] = defaultdict(list)
+ for idx, gid in enumerate(assigned):
+ clusters[gid].append(proposals[idx])
+ return list(clusters.values())
+
+ @staticmethod
+ def _merge_group(group: list[StructProposal]) -> UnifiedStruct:
+ name_counts: dict[str, int] = defaultdict(int)
+ fields_by_offset: dict[int, list[StructFieldProposal]] = defaultdict(list)
+ applications: list[ParamTypeApplication] = []
+
+ for p in group:
+ name_counts[p.name] += 1
+ for f in p.fields:
+ fields_by_offset[f.offset].append(f)
+ if p.used_by_param and p.source_function:
+ applications.append(ParamTypeApplication(
+ func_addr=p.source_function,
+ param_name=p.used_by_param,
+ struct_name="",
+ ))
+
+ winning_name = max(name_counts, key=name_counts.get) # type: ignore[arg-type]
+
+ merged_fields: list[StructField] = []
+ for offset in sorted(fields_by_offset):
+ candidates = fields_by_offset[offset]
+ best = _pick_best_field(candidates)
+ merged_fields.append(StructField(
+ name=best.name,
+ data_type=best.data_type,
+ offset=best.offset,
+ size=best.size,
+ ))
+
+ total_size = group[0].total_size
+ definition = StructDefinition(
+ name=winning_name,
+ size=total_size,
+ fields=merged_fields,
+ )
+
+ for app in applications:
+ app.struct_name = winning_name
+
+ return UnifiedStruct(
+ definition=definition,
+ source_proposals=group,
+ applications=applications,
+ )
+
+
+def _pick_best_field(candidates: list[StructFieldProposal]) -> StructFieldProposal:
+ """Choose the best field description from multiple proposals at the same offset.
+
+ Prefers the candidate whose name is most descriptive (longest non-generic
+ name) and whose type is most specific (not 'undefined' or 'int' when a
+ more specific type is available).
+ """
+ def _score(f: StructFieldProposal) -> tuple[int, int]:
+ generic_names = {"field", "unk", "undefined", "pad"}
+ name_score = 0 if any(g in f.name.lower() for g in generic_names) else len(f.name)
+ generic_types = {"undefined", "undefined4", "undefined8"}
+ type_score = 0 if f.data_type.lower() in generic_types else 1
+ return (type_score, name_score)
+
+ return max(candidates, key=_score)
+
+
+def apply_unified_structs(
+ client: GhidraClient,
+ unified: list[UnifiedStruct],
+) -> list[int]:
+ """Create structs in Ghidra and apply them to function parameters.
+
+ Returns the list of function addresses whose parameters were retyped
+ (candidates for re-analysis).
+ """
+ affected_addrs: set[int] = set()
+
+ for us in unified:
+ try:
+ client.create_struct(us.definition)
+ except Exception:
+ logger.warning(
+ "Failed to create struct '%s' in Ghidra", us.definition.name,
+ exc_info=True,
+ )
+ continue
+
+ for app in us.applications:
+ try:
+ param_ordinal = _resolve_param_ordinal(client, app.func_addr, app.param_name)
+ if param_ordinal is not None:
+ client.apply_type_to_param(
+ app.func_addr,
+ param_ordinal,
+ app.struct_name,
+ as_pointer=True,
+ )
+ affected_addrs.add(app.func_addr)
+ except Exception:
+ logger.warning(
+ "Failed to apply struct '%s' to param '%s' of 0x%08x",
+ app.struct_name, app.param_name, app.func_addr,
+ exc_info=True,
+ )
+
+ return sorted(affected_addrs)
+
+
+def _resolve_param_ordinal(
+ client: GhidraClient,
+ func_addr: int,
+ param_name: str,
+) -> int | None:
+ """Map a parameter name (e.g. 'param_1') to its ordinal index."""
+ try:
+ info = client.get_function_info(func_addr)
+ except Exception:
+ return None
+ for p in info.params:
+ if p.name == param_name:
+ return p.ordinal
+ return None
diff --git a/tests/test_llm_client.py b/tests/test_llm_client.py
new file mode 100644
index 0000000..212e241
--- /dev/null
+++ b/tests/test_llm_client.py
@@ -0,0 +1,140 @@
+"""Tests for the Anthropic LLM client wrapper."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from kong.llm.client import AnthropicClient, TokenUsage, _PRICING
+
+
+def _mock_message(text: str, input_tokens: int = 100, output_tokens: int = 50):
+ """Create a mock Anthropic message response."""
+ block = MagicMock()
+ block.type = "text"
+ block.text = text
+
+ usage = MagicMock()
+ usage.input_tokens = input_tokens
+ usage.output_tokens = output_tokens
+
+ msg = MagicMock()
+ msg.content = [block]
+ msg.usage = usage
+ return msg
+
+
+class TestAnthropicClient:
+ @patch("kong.llm.client.anthropic.Anthropic")
+ def test_analyze_function_parses_json(self, mock_anthropic_cls):
+ mock_client = MagicMock()
+ mock_anthropic_cls.return_value = mock_client
+ mock_client.messages.create.return_value = _mock_message(
+ '{"name": "parse_config", "confidence": 85, "classification": "parser"}'
+ )
+
+ client = AnthropicClient(api_key="test-key")
+ response = client.analyze_function("analyze this function")
+
+ assert response.name == "parse_config"
+ assert response.confidence == 85
+ assert response.classification == "parser"
+
+ @patch("kong.llm.client.anthropic.Anthropic")
+ def test_tracks_token_usage(self, mock_anthropic_cls):
+ mock_client = MagicMock()
+ mock_anthropic_cls.return_value = mock_client
+ mock_client.messages.create.return_value = _mock_message(
+ '{"name": "f"}', input_tokens=200, output_tokens=80
+ )
+
+ client = AnthropicClient(api_key="test-key")
+ client.analyze_function("prompt1")
+
+ assert client.usage.input_tokens == 200
+ assert client.usage.output_tokens == 80
+ assert client.usage.calls == 1
+
+ @patch("kong.llm.client.anthropic.Anthropic")
+ def test_accumulates_across_calls(self, mock_anthropic_cls):
+ mock_client = MagicMock()
+ mock_anthropic_cls.return_value = mock_client
+ mock_client.messages.create.return_value = _mock_message(
+ '{"name": "f"}', input_tokens=100, output_tokens=50
+ )
+
+ client = AnthropicClient(api_key="test-key")
+ client.analyze_function("p1")
+ client.analyze_function("p2")
+
+ assert client.usage.input_tokens == 200
+ assert client.usage.output_tokens == 100
+ assert client.usage.calls == 2
+
+ @patch("kong.llm.client.anthropic.Anthropic")
+ def test_passes_system_prompt(self, mock_anthropic_cls):
+ mock_client = MagicMock()
+ mock_anthropic_cls.return_value = mock_client
+ mock_client.messages.create.return_value = _mock_message('{"name": "f"}')
+
+ client = AnthropicClient(api_key="test-key")
+ client.analyze_function("test prompt")
+
+ call_kwargs = mock_client.messages.create.call_args
+ assert "system" in call_kwargs.kwargs
+ assert "reverse engineer" in call_kwargs.kwargs["system"].lower()
+
+ @patch("kong.llm.client.anthropic.Anthropic")
+ def test_handles_malformed_response(self, mock_anthropic_cls):
+ mock_client = MagicMock()
+ mock_anthropic_cls.return_value = mock_client
+ mock_client.messages.create.return_value = _mock_message(
+ "I cannot analyze this function because reasons."
+ )
+
+ client = AnthropicClient(api_key="test-key")
+ response = client.analyze_function("prompt")
+
+ assert response.name == ""
+ assert "Failed to parse" in response.reasoning
+
+ @patch("kong.llm.client.anthropic.Anthropic")
+ def test_response_has_token_counts(self, mock_anthropic_cls):
+ mock_client = MagicMock()
+ mock_anthropic_cls.return_value = mock_client
+ mock_client.messages.create.return_value = _mock_message(
+ '{"name": "f"}', input_tokens=500, output_tokens=200
+ )
+
+ client = AnthropicClient(api_key="test-key")
+ response = client.analyze_function("prompt")
+
+ assert response.input_tokens == 500
+ assert response.output_tokens == 200
+
+
+class TestTokenUsage:
+ def test_total_tokens(self):
+ u = TokenUsage(input_tokens=100, output_tokens=50)
+ assert u.total_tokens == 150
+
+ def test_cost_calculation(self):
+ u = TokenUsage(input_tokens=1_000_000, output_tokens=1_000_000)
+ cost = u.cost_usd("claude-sonnet-4-20250514")
+ assert cost == 3.0 + 15.0
+
+ def test_cost_with_unknown_model_uses_default(self):
+ u = TokenUsage(input_tokens=1_000_000, output_tokens=1_000_000)
+ cost = u.cost_usd("unknown-model")
+ assert cost == 3.0 + 15.0
+
+
+class TestPricingValues:
+ def test_pricing_entries_exist(self):
+ assert "claude-sonnet-4-20250514" in _PRICING
+ assert "claude-haiku-4-20250414" in _PRICING
+
+ def test_haiku_cheaper_than_sonnet(self):
+ haiku_in, haiku_out = _PRICING["claude-haiku-4-20250414"]
+ sonnet_in, sonnet_out = _PRICING["claude-sonnet-4-20250514"]
+ assert haiku_in < sonnet_in
+ assert haiku_out < sonnet_out
diff --git a/tests/test_type_recovery.py b/tests/test_type_recovery.py
new file mode 100644
index 0000000..e826ebe
--- /dev/null
+++ b/tests/test_type_recovery.py
@@ -0,0 +1,645 @@
+"""Tests for the type recovery pipeline."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+from kong.agent.analyzer import (
+ Analyzer,
+ LLMResponse,
+ StructFieldProposal,
+ StructProposal,
+)
+from kong.agent.models import FunctionResult
+from kong.agent.type_recovery import (
+ ParamTypeApplication,
+ StructAccumulator,
+ UnifiedStruct,
+ apply_unified_structs,
+ _pick_best_field,
+ _resolve_param_ordinal,
+)
+from kong.ghidra.types import (
+ BinaryInfo,
+ FunctionClassification,
+ FunctionInfo,
+ ParameterInfo,
+ StructDefinition,
+ StructField,
+)
+
+from kong.agent.queue import WorkItem
+from kong.agent.events import EventType, Phase
+from kong.agent.supervisor import Supervisor
+from kong.config import KongConfig, OutputConfig
+
+
+def _field(name: str, dtype: str, offset: int, size: int) -> StructFieldProposal:
+ return StructFieldProposal(name=name, data_type=dtype, offset=offset, size=size)
+
+
+def _proposal(
+ name: str,
+ total_size: int,
+ fields: list[StructFieldProposal],
+ used_by_param: str = "",
+ source_function: int = 0,
+) -> StructProposal:
+ return StructProposal(
+ name=name,
+ total_size=total_size,
+ fields=fields,
+ used_by_param=used_by_param,
+ source_function=source_function,
+ )
+
+
+# ---------------------------------------------------------------------------
+# StructAccumulator
+# ---------------------------------------------------------------------------
+
+class TestStructAccumulator:
+ def test_empty_accumulator(self):
+ acc = StructAccumulator()
+ assert acc.proposal_count == 0
+ assert acc.unify() == []
+
+ def test_add_proposals(self):
+ acc = StructAccumulator()
+ acc.add_proposals(0x1000, [
+ _proposal("conn_t", 32, [_field("fd", "int", 0, 4)]),
+ ])
+ assert acc.proposal_count == 1
+
+ def test_tags_source_function(self):
+ acc = StructAccumulator()
+ p = _proposal("conn_t", 32, [_field("fd", "int", 0, 4)])
+ acc.add_proposals(0x1000, [p])
+ assert acc._proposals[0].source_function == 0x1000
+
+ def test_single_proposal_unifies_to_one(self):
+ acc = StructAccumulator()
+ acc.add_proposals(0x1000, [
+ _proposal("config_t", 24, [
+ _field("flags", "int", 0, 4),
+ _field("timeout", "int", 4, 4),
+ ]),
+ ])
+ unified = acc.unify()
+ assert len(unified) == 1
+ assert unified[0].definition.name == "config_t"
+ assert unified[0].definition.size == 24
+ assert len(unified[0].definition.fields) == 2
+
+ def test_same_size_overlapping_offsets_merge(self):
+ acc = StructAccumulator()
+ acc.add_proposals(0x1000, [
+ _proposal("conn_t", 32, [
+ _field("fd", "int", 0, 4),
+ _field("flags", "int", 4, 4),
+ ]),
+ ])
+ acc.add_proposals(0x2000, [
+ _proposal("connection", 32, [
+ _field("socket_fd", "int", 0, 4),
+ _field("port", "uint16_t", 8, 2),
+ ]),
+ ])
+ unified = acc.unify()
+ assert len(unified) == 1
+ assert unified[0].definition.size == 32
+ assert len(unified[0].definition.fields) == 3
+
+ def test_same_size_no_overlap_stays_separate(self):
+ acc = StructAccumulator()
+ acc.add_proposals(0x1000, [
+ _proposal("type_a", 16, [_field("x", "int", 0, 4)]),
+ ])
+ acc.add_proposals(0x2000, [
+ _proposal("type_b", 16, [_field("y", "int", 8, 4)]),
+ ])
+ unified = acc.unify()
+ assert len(unified) == 2
+
+ def test_different_sizes_stay_separate(self):
+ acc = StructAccumulator()
+ acc.add_proposals(0x1000, [
+ _proposal("small_t", 8, [_field("a", "int", 0, 4)]),
+ ])
+ acc.add_proposals(0x2000, [
+ _proposal("big_t", 64, [_field("b", "int", 0, 4)]),
+ ])
+ unified = acc.unify()
+ assert len(unified) == 2
+
+ def test_winning_name_by_majority(self):
+ acc = StructAccumulator()
+ for _ in range(3):
+ acc.add_proposals(0x1000, [
+ _proposal("config_t", 16, [_field("a", "int", 0, 4)]),
+ ])
+ acc.add_proposals(0x2000, [
+ _proposal("cfg", 16, [_field("a", "int", 0, 4)]),
+ ])
+ unified = acc.unify()
+ assert unified[0].definition.name == "config_t"
+
+ def test_applications_tracked(self):
+ acc = StructAccumulator()
+ acc.add_proposals(0x1000, [
+ _proposal(
+ "conn_t", 32,
+ [_field("fd", "int", 0, 4)],
+ used_by_param="param_1",
+ source_function=0x1000,
+ ),
+ ])
+ unified = acc.unify()
+ assert len(unified[0].applications) == 1
+ app = unified[0].applications[0]
+ assert app.func_addr == 0x1000
+ assert app.param_name == "param_1"
+ assert app.struct_name == "conn_t"
+
+
+# ---------------------------------------------------------------------------
+# _pick_best_field
+# ---------------------------------------------------------------------------
+
+class TestPickBestField:
+ def test_prefers_descriptive_name(self):
+ candidates = [
+ _field("field_0x0", "int", 0, 4),
+ _field("socket_fd", "int", 0, 4),
+ ]
+ best = _pick_best_field(candidates)
+ assert best.name == "socket_fd"
+
+ def test_prefers_specific_type(self):
+ candidates = [
+ _field("count", "undefined4", 0, 4),
+ _field("count", "int", 0, 4),
+ ]
+ best = _pick_best_field(candidates)
+ assert best.data_type == "int"
+
+ def test_single_candidate(self):
+ candidates = [_field("x", "int", 0, 4)]
+ best = _pick_best_field(candidates)
+ assert best.name == "x"
+
+
+# ---------------------------------------------------------------------------
+# apply_unified_structs
+# ---------------------------------------------------------------------------
+
+class TestApplyUnifiedStructs:
+ def test_creates_structs_and_applies_types(self):
+ client = MagicMock()
+ client.get_function_info.return_value = FunctionInfo(
+ address=0x1000, name="process", size=100,
+ params=[ParameterInfo(name="param_1", data_type="undefined *", ordinal=0)],
+ )
+
+ us = UnifiedStruct(
+ definition=StructDefinition(
+ name="conn_t",
+ size=32,
+ fields=[StructField(name="fd", data_type="int", offset=0, size=4)],
+ ),
+ applications=[
+ ParamTypeApplication(func_addr=0x1000, param_name="param_1", struct_name="conn_t"),
+ ],
+ )
+
+ affected = apply_unified_structs(client, [us])
+
+ client.create_struct.assert_called_once_with(us.definition)
+ client.apply_type_to_param.assert_called_once_with(
+ 0x1000, 0, "conn_t", as_pointer=True,
+ )
+ assert 0x1000 in affected
+
+ def test_handles_create_failure(self):
+ client = MagicMock()
+ client.create_struct.side_effect = Exception("DTM error")
+
+ us = UnifiedStruct(
+ definition=StructDefinition(name="bad_t", size=8, fields=[]),
+ applications=[
+ ParamTypeApplication(func_addr=0x1000, param_name="param_1", struct_name="bad_t"),
+ ],
+ )
+
+ affected = apply_unified_structs(client, [us])
+ assert affected == []
+ client.apply_type_to_param.assert_not_called()
+
+ def test_handles_apply_failure(self):
+ client = MagicMock()
+ client.get_function_info.return_value = FunctionInfo(
+ address=0x1000, name="f", size=100,
+ params=[ParameterInfo(name="param_1", data_type="void *", ordinal=0)],
+ )
+ client.apply_type_to_param.side_effect = Exception("Apply failed")
+
+ us = UnifiedStruct(
+ definition=StructDefinition(name="t", size=8, fields=[]),
+ applications=[
+ ParamTypeApplication(func_addr=0x1000, param_name="param_1", struct_name="t"),
+ ],
+ )
+
+ affected = apply_unified_structs(client, [us])
+ assert affected == []
+
+ def test_no_applications(self):
+ client = MagicMock()
+ us = UnifiedStruct(
+ definition=StructDefinition(name="orphan_t", size=16, fields=[]),
+ )
+ affected = apply_unified_structs(client, [us])
+ client.create_struct.assert_called_once()
+ assert affected == []
+
+
+# ---------------------------------------------------------------------------
+# _resolve_param_ordinal
+# ---------------------------------------------------------------------------
+
+class TestResolveParamOrdinal:
+ def test_resolves_by_name(self):
+ client = MagicMock()
+ client.get_function_info.return_value = FunctionInfo(
+ address=0x1000, name="f", size=100,
+ params=[
+ ParameterInfo(name="param_1", data_type="int", ordinal=0),
+ ParameterInfo(name="param_2", data_type="char *", ordinal=1),
+ ],
+ )
+ assert _resolve_param_ordinal(client, 0x1000, "param_2") == 1
+
+ def test_returns_none_for_unknown_param(self):
+ client = MagicMock()
+ client.get_function_info.return_value = FunctionInfo(
+ address=0x1000, name="f", size=100,
+ params=[ParameterInfo(name="param_1", data_type="int", ordinal=0)],
+ )
+ assert _resolve_param_ordinal(client, 0x1000, "param_99") is None
+
+ def test_returns_none_on_error(self):
+ client = MagicMock()
+ client.get_function_info.side_effect = Exception("No function")
+ assert _resolve_param_ordinal(client, 0x1000, "param_1") is None
+
+
+# ---------------------------------------------------------------------------
+# LLM JSON parsing — struct_proposals
+# ---------------------------------------------------------------------------
+
+class TestParseLLMJsonStructs:
+ def test_parse_with_struct_proposals(self):
+ raw = '''{
+ "name": "process_request",
+ "confidence": 75,
+ "struct_proposals": [
+ {
+ "name": "request_t",
+ "total_size": 24,
+ "fields": [
+ {"name": "method", "data_type": "int", "offset": 0, "size": 4},
+ {"name": "url", "data_type": "char *", "offset": 8, "size": 8}
+ ],
+ "used_by_param": "param_1"
+ }
+ ]
+ }'''
+ resp = Analyzer.parse_llm_json(raw)
+ assert len(resp.struct_proposals) == 1
+ sp = resp.struct_proposals[0]
+ assert sp.name == "request_t"
+ assert sp.total_size == 24
+ assert len(sp.fields) == 2
+ assert sp.fields[0].name == "method"
+ assert sp.fields[1].data_type == "char *"
+ assert sp.used_by_param == "param_1"
+
+ def test_parse_without_struct_proposals(self):
+ raw = '{"name": "foo", "confidence": 50}'
+ resp = Analyzer.parse_llm_json(raw)
+ assert resp.struct_proposals == []
+
+ def test_parse_malformed_struct_proposals_skipped(self):
+ raw = '{"name": "foo", "struct_proposals": [{"not_a_name": true}]}'
+ resp = Analyzer.parse_llm_json(raw)
+ assert resp.struct_proposals == []
+
+ def test_parse_struct_fields_with_defaults(self):
+ raw = '''{
+ "name": "f",
+ "struct_proposals": [{
+ "name": "s",
+ "total_size": 8,
+ "fields": [{"offset": 0}]
+ }]
+ }'''
+ resp = Analyzer.parse_llm_json(raw)
+ assert len(resp.struct_proposals) == 1
+ f = resp.struct_proposals[0].fields[0]
+ assert f.name == "field_0"
+ assert f.data_type == "undefined"
+ assert f.size == 4
+
+
+# ---------------------------------------------------------------------------
+# Analyzer context — known types in prompt
+# ---------------------------------------------------------------------------
+
+class TestAnalyzerContextTypes:
+ def test_known_types_included_in_prompt(self):
+ llm = MagicMock()
+ llm.analyze_function.return_value = LLMResponse(name="f")
+ client = MagicMock()
+ client.get_decompilation.return_value = "void f(void *p) { return; }"
+ client.get_function_info.return_value = FunctionInfo(
+ address=0x1000, name="FUN_00001000", size=100,
+ classification=FunctionClassification.MEDIUM,
+ )
+ client.get_xrefs_from.return_value = []
+
+ item = WorkItem(
+ function=FunctionInfo(
+ address=0x1000, name="FUN_00001000", size=100,
+ classification=FunctionClassification.MEDIUM,
+ ),
+ callers=[], callees=[],
+ )
+ binary_info = BinaryInfo(
+ arch="x86-64", format="ELF", endianness="little",
+ word_size=8, compiler="GCC",
+ )
+ known_types = [
+ StructDefinition(
+ name="config_t",
+ size=16,
+ fields=[
+ StructField(name="flags", data_type="int", offset=0, size=4),
+ StructField(name="timeout", data_type="int", offset=4, size=4),
+ ],
+ ),
+ ]
+
+ analyzer = Analyzer(client, llm)
+ analyzer.analyze(item, binary_info, {}, [], known_types=known_types)
+
+ prompt = llm.analyze_function.call_args[0][0]
+ assert "Known Struct Types" in prompt
+ assert "config_t" in prompt
+ assert "flags" in prompt
+ assert "timeout" in prompt
+
+ def test_no_known_types_section_when_empty(self):
+ llm = MagicMock()
+ llm.analyze_function.return_value = LLMResponse(name="f")
+ client = MagicMock()
+ client.get_decompilation.return_value = "void f() {}"
+ client.get_function_info.return_value = FunctionInfo(
+ address=0x1000, name="f", size=100,
+ classification=FunctionClassification.MEDIUM,
+ )
+ client.get_xrefs_from.return_value = []
+
+ item = WorkItem(
+ function=FunctionInfo(
+ address=0x1000, name="f", size=100,
+ classification=FunctionClassification.MEDIUM,
+ ),
+ callers=[], callees=[],
+ )
+ binary_info = BinaryInfo(
+ arch="x86-64", format="ELF", endianness="little",
+ word_size=8, compiler="GCC",
+ )
+
+ analyzer = Analyzer(client, llm)
+ analyzer.analyze(item, binary_info, {}, [])
+
+ prompt = llm.analyze_function.call_args[0][0]
+ assert "Known Struct Types" not in prompt
+
+
+# ---------------------------------------------------------------------------
+# Analyzer — struct proposals flow through to FunctionResult
+# ---------------------------------------------------------------------------
+
+class TestAnalyzerStructProposalPassthrough:
+ def test_struct_proposals_in_result(self):
+ response = LLMResponse(
+ name="process",
+ confidence=70,
+ struct_proposals=[
+ StructProposal(
+ name="req_t",
+ total_size=16,
+ fields=[_field("method", "int", 0, 4)],
+ used_by_param="param_1",
+ ),
+ ],
+ )
+ llm = MagicMock()
+ llm.analyze_function.return_value = response
+ client = MagicMock()
+ client.get_decompilation.return_value = "void f() {}"
+ client.get_function_info.return_value = FunctionInfo(
+ address=0x1000, name="f", size=100,
+ classification=FunctionClassification.MEDIUM,
+ )
+ client.get_xrefs_from.return_value = []
+
+
+ item = WorkItem(
+ function=FunctionInfo(
+ address=0x1000, name="f", size=100,
+ classification=FunctionClassification.MEDIUM,
+ ),
+ callers=[], callees=[],
+ )
+ binary_info = BinaryInfo(
+ arch="x86-64", format="ELF", endianness="little",
+ word_size=8, compiler="GCC",
+ )
+
+ analyzer = Analyzer(client, llm)
+ result = analyzer.analyze(item, binary_info, {}, [])
+
+ assert len(result.struct_proposals) == 1
+ assert result.struct_proposals[0].name == "req_t"
+
+
+# ---------------------------------------------------------------------------
+# Ghidra types dataclasses
+# ---------------------------------------------------------------------------
+
+class TestStructDefinition:
+ def test_field_count(self):
+ sd = StructDefinition(
+ name="test_t", size=16,
+ fields=[
+ StructField(name="a", data_type="int", offset=0, size=4),
+ StructField(name="b", data_type="int", offset=4, size=4),
+ ],
+ )
+ assert sd.field_count == 2
+
+ def test_field_at_offset(self):
+ sd = StructDefinition(
+ name="test_t", size=16,
+ fields=[
+ StructField(name="a", data_type="int", offset=0, size=4),
+ StructField(name="b", data_type="long", offset=8, size=8),
+ ],
+ )
+ assert sd.field_at_offset(0).name == "a"
+ assert sd.field_at_offset(8).name == "b"
+ assert sd.field_at_offset(4) is None
+
+ def test_struct_field_end_offset(self):
+ f = StructField(name="x", data_type="int", offset=4, size=4)
+ assert f.end_offset == 8
+
+
+# ---------------------------------------------------------------------------
+# Supervisor cleanup integration
+# ---------------------------------------------------------------------------
+
+class TestSupervisorCleanupIntegration:
+ def test_cleanup_with_struct_proposals(self, tmp_path):
+
+ funcs = [
+ FunctionInfo(
+ address=0x1000, name="process", size=100,
+ classification=FunctionClassification.MEDIUM,
+ ),
+ ]
+ client = MagicMock()
+ client.get_binary_info.return_value = BinaryInfo(
+ arch="x86-64", format="ELF", endianness="little",
+ word_size=8, compiler="GCC", name="test",
+ )
+ client.list_functions.return_value = funcs
+ client.get_strings.return_value = []
+ client.get_callers.return_value = []
+ client.get_callees.return_value = []
+ client.get_decompilation.return_value = "void f() {}"
+ client.get_function_info.return_value = funcs[0]
+ client.get_xrefs_from.return_value = []
+ client.list_custom_types.return_value = []
+
+ response = LLMResponse(
+ name="process_request",
+ confidence=75,
+ struct_proposals=[
+ StructProposal(
+ name="req_t",
+ total_size=16,
+ fields=[_field("method", "int", 0, 4)],
+ used_by_param="param_1",
+ ),
+ ],
+ )
+ llm = MagicMock()
+ llm.analyze_function.return_value = response
+
+ config = KongConfig(output=OutputConfig(directory=tmp_path / "out"))
+ sup = Supervisor(client, config, llm_client=llm)
+
+ events = []
+ sup.on_event(events.append)
+ sup.run()
+
+ assert sup.struct_accumulator.proposal_count == 1
+
+ event_types = [e.type for e in events]
+ assert EventType.CLEANUP_TYPES_UNIFIED in event_types
+ assert EventType.CLEANUP_TYPE_CREATED in event_types
+
+ def test_cleanup_without_struct_proposals(self, tmp_path):
+ funcs = [
+ FunctionInfo(
+ address=0x1000, name="f", size=100,
+ classification=FunctionClassification.MEDIUM,
+ ),
+ ]
+ client = MagicMock()
+ client.get_binary_info.return_value = BinaryInfo(
+ arch="x86-64", format="ELF", endianness="little",
+ word_size=8, compiler="GCC", name="test",
+ )
+ client.list_functions.return_value = funcs
+ client.get_strings.return_value = []
+ client.get_callers.return_value = []
+ client.get_callees.return_value = []
+
+ response = LLMResponse(name="helper", confidence=80)
+ llm = MagicMock()
+ llm.analyze_function.return_value = response
+
+ config = KongConfig(output=OutputConfig(directory=tmp_path / "out"))
+ sup = Supervisor(client, config, llm_client=llm)
+
+ events = []
+ sup.on_event(events.append)
+ sup.run()
+
+ assert sup.struct_accumulator.proposal_count == 0
+ event_types = [e.type for e in events]
+ assert EventType.CLEANUP_TYPES_UNIFIED not in event_types
+
+ def test_cleanup_reanalyzes_low_confidence(self, tmp_path):
+ funcs = [
+ FunctionInfo(
+ address=0x1000, name="FUN_00001000", size=100,
+ classification=FunctionClassification.MEDIUM,
+ ),
+ ]
+ client = MagicMock()
+ client.get_binary_info.return_value = BinaryInfo(
+ arch="x86-64", format="ELF", endianness="little",
+ word_size=8, compiler="GCC", name="test",
+ )
+ client.list_functions.return_value = funcs
+ client.get_strings.return_value = []
+ client.get_callers.return_value = []
+ client.get_callees.return_value = []
+ client.get_decompilation.return_value = "void f() {}"
+ client.get_function_info.return_value = funcs[0]
+ client.get_xrefs_from.return_value = []
+ client.list_custom_types.return_value = []
+
+ call_count = 0
+
+ def varying_response(prompt: str) -> LLMResponse:
+ nonlocal call_count
+ call_count += 1
+ if call_count == 1:
+ return LLMResponse(name="unknown_func", confidence=30)
+ return LLMResponse(name="decode_buffer", confidence=70)
+
+ llm = MagicMock()
+ llm.analyze_function.side_effect = varying_response
+
+ config = KongConfig(output=OutputConfig(directory=tmp_path / "out"))
+ sup = Supervisor(client, config, llm_client=llm)
+
+ events = []
+ sup.on_event(events.append)
+ sup.run()
+
+ assert sup.results[0x1000].name == "decode_buffer"
+ assert sup.results[0x1000].confidence == 70
+
+ cleanup_completes = [
+ e for e in events
+ if e.type == EventType.FUNCTION_COMPLETE and e.phase == Phase.CLEANUP
+ ]
+ assert len(cleanup_completes) == 1