Skip to content

armgit / kong

Public Imported from GitHub
0

The world's first agentic reverse engineer.

refactor: fix inline imports, move AnalysisStats to models, clean up init files

Amruth15c0050ab8fc
diff --git a/kong/__main__.py b/kong/__main__.py
index fe0e7d9..0dcb652 100644
--- a/kong/__main__.py
+++ b/kong/__main__.py
@@ -151,6 +151,7 @@ def analyze(
_print_final_stats(supervisor, llm_client)
client.close()
else:
+ # Deferred to avoid loading Textual when running --headless
from kong.tui.app import KongApp
app = KongApp(supervisor)
try:
diff --git a/kong/agent/__init__.py b/kong/agent/__init__.py
index 1adc5c9..f48c55c 100644
--- a/kong/agent/__init__.py
+++ b/kong/agent/__init__.py
@@ -5,7 +5,8 @@ from kong.agent.events import Event, EventType, Phase
from kong.agent.models import FunctionResult
from kong.agent.queue import WorkItem, WorkQueue
from kong.agent.signatures import SignatureDB, SignatureMatch
-from kong.agent.supervisor import AnalysisStats, Supervisor
+from kong.agent.models import AnalysisStats
+from kong.agent.supervisor import Supervisor
from kong.agent.triage import CallGraph, LanguageHints, TriageAgent, TriageResult
__all__ = [
diff --git a/kong/agent/analyzer.py b/kong/agent/analyzer.py
index b1fed84..ed130da 100644
--- a/kong/agent/analyzer.py
+++ b/kong/agent/analyzer.py
@@ -10,13 +10,17 @@ from __future__ import annotations
import json
import logging
from dataclasses import dataclass, field
-from typing import Protocol
+from typing import TYPE_CHECKING, 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, StructDefinition
+if TYPE_CHECKING:
+ from kong.agent.deobfuscator import Deobfuscator
+ from kong.llm.tools import ToolExecutor, ToolSchema
+
logger = logging.getLogger(__name__)
@@ -29,8 +33,8 @@ class LLMClient(Protocol):
self,
prompt: str,
system: str,
- tools: list[dict[str, object]],
- tool_executor: object,
+ tools: list[ToolSchema],
+ tool_executor: ToolExecutor,
max_rounds: int = 10,
) -> LLMResponse: ...
@@ -115,7 +119,7 @@ class Analyzer:
self,
client: GhidraClient,
llm_client: LLMClient,
- deobfuscator: object | None = None,
+ deobfuscator: Deobfuscator | None = None,
) -> None:
self.client = client
self.llm = llm_client
@@ -131,14 +135,15 @@ class Analyzer:
model: str | None = None,
) -> FunctionResult:
"""Full analysis pipeline for one function."""
- from kong.agent.deobfuscator import Deobfuscator, classify_obfuscation
+ # Inline import: deobfuscator imports from analyzer at module level (circular).
+ from kong.agent.deobfuscator import classify_obfuscation
func = item.function
context = self._build_context(item, binary_info, known_results, strings, known_types)
techniques = classify_obfuscation(context.decompilation) if self._deobfuscator else []
- if techniques and isinstance(self._deobfuscator, Deobfuscator):
+ if techniques and self._deobfuscator:
response, tool_calls = self._deobfuscator.deobfuscate(context, techniques)
sig_applied = self._write_back(func.address, response)
return FunctionResult(
diff --git a/kong/agent/models.py b/kong/agent/models.py
index 9f5d3df..e5981df 100644
--- a/kong/agent/models.py
+++ b/kong/agent/models.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import time
from dataclasses import dataclass, field
from typing import TYPE_CHECKING
@@ -9,6 +10,60 @@ if TYPE_CHECKING:
from kong.agent.analyzer import StructProposal
+@dataclass
+class AnalysisStats:
+ """Aggregate statistics for the full run."""
+ total_functions: int = 0
+ analyzed: int = 0
+ renamed: int = 0
+ confirmed: int = 0
+ high_confidence: int = 0
+ medium_confidence: int = 0
+ low_confidence: int = 0
+ skipped: int = 0
+ errors: int = 0
+ llm_calls: int = 0
+ start_time: float = 0.0
+ end_time: float = 0.0
+ signature_matches: int = 0
+
+ @property
+ def named(self) -> int:
+ return self.renamed + self.confirmed
+
+ @property
+ def duration_seconds(self) -> float:
+ end = self.end_time or time.time()
+ return end - self.start_time if self.start_time else 0.0
+
+ @property
+ def name_rate(self) -> float:
+ return self.named / self.total_functions if self.total_functions else 0.0
+
+ def record_result(self, result: FunctionResult) -> None:
+ if result.skipped:
+ self.skipped += 1
+ return
+ if result.error:
+ self.errors += 1
+ return
+ self.analyzed += 1
+ self.llm_calls += result.llm_calls
+ if result.name:
+ if result.name != result.original_name:
+ self.renamed += 1
+ else:
+ self.confirmed += 1
+ # TODO: calibrate these eventually. these buckets are arbitrary, need eval data to
+ # determine meaningful confidence tiers for the LLM's self-reported scores.
+ if result.confidence >= 80:
+ self.high_confidence += 1
+ elif result.confidence >= 50:
+ self.medium_confidence += 1
+ else:
+ self.low_confidence += 1
+
+
@dataclass
class FunctionResult:
"""Result of analyzing a single function."""
diff --git a/kong/agent/supervisor.py b/kong/agent/supervisor.py
index 8c5b93e..4872ce1 100644
--- a/kong/agent/supervisor.py
+++ b/kong/agent/supervisor.py
@@ -9,19 +9,21 @@ from __future__ import annotations
import logging
import time
from concurrent.futures import ThreadPoolExecutor, as_completed
-from dataclasses import dataclass
from kong.agent.analyzer import Analyzer, LLMClient, LLMResponse
from kong.agent.deobfuscator import Deobfuscator, classify_obfuscation
from kong.agent.events import Event, EventCallback, EventType, Phase
-from kong.agent.models import FunctionResult
+from kong.agent.models import AnalysisStats, 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.export.source import ExportData, export_source
+from kong.export.structured import export_json
from kong.ghidra.client import GhidraClient
from kong.ghidra.types import BinaryInfo, FunctionInfo, StringEntry
+from kong.llm.client import TokenUsage
logger = logging.getLogger(__name__)
@@ -32,60 +34,6 @@ MAX_PARALLEL_LLM = 4
REQUEST_STAGGER_SECONDS = 0.5
-@dataclass
-class AnalysisStats:
- """Aggregate statistics for the full run."""
- total_functions: int = 0
- analyzed: int = 0
- renamed: int = 0
- confirmed: int = 0
- high_confidence: int = 0 # >= 80
- medium_confidence: int = 0 # 50-79
- low_confidence: int = 0 # < 50
- skipped: int = 0
- errors: int = 0
- llm_calls: int = 0
- start_time: float = 0.0
- end_time: float = 0.0
- signature_matches: int = 0
-
- @property
- def named(self) -> int:
- return self.renamed + self.confirmed
-
- @property
- def duration_seconds(self) -> float:
- end = self.end_time or time.time()
- return end - self.start_time if self.start_time else 0.0
-
- @property
- def name_rate(self) -> float:
- return self.named / self.total_functions if self.total_functions else 0.0
-
- def record_result(self, result: FunctionResult) -> None:
- if result.skipped:
- self.skipped += 1
- return
- if result.error:
- self.errors += 1
- return
- self.analyzed += 1
- self.llm_calls += result.llm_calls
- if result.name:
- if result.name != result.original_name:
- self.renamed += 1
- else:
- self.confirmed += 1
- # TODO: calibrate these eventually. these buckets are arbitrary, need eval data to
- # determine meaningful confidence tiers for the LLM's self-reported scores.
- if result.confidence >= 80:
- self.high_confidence += 1
- elif result.confidence >= 50:
- self.medium_confidence += 1
- else:
- self.low_confidence += 1
-
-
class Supervisor:
"""Main agent loop that orchestrates the full analysis pipeline.
@@ -125,13 +73,20 @@ class Supervisor:
for cb in self._listeners:
cb(event)
+ @property
+ def is_paused(self) -> bool:
+ return self._paused
+
def pause(self) -> None:
self._paused = True
def resume(self) -> None:
self._paused = False
-
+ def export(self) -> None:
+ """Trigger export manually (e.g. from TUI keybind)."""
+ self._run_export()
+
def run(self) -> dict[int, FunctionResult]:
"""Run the full analysis pipeline. Returns addr -> FunctionResult."""
self.stats.start_time = time.time()
@@ -658,10 +613,6 @@ class Supervisor:
def _run_export(self) -> None:
"""Generate output files."""
- from kong.export.source import ExportData, export_source
- from kong.export.structured import export_json
- from kong.llm.client import TokenUsage
-
self._emit(Event(
type=EventType.PHASE_START,
phase=Phase.EXPORT,
diff --git a/kong/agent/type_recovery.py b/kong/agent/type_recovery.py
index 9ae79d9..33a85ba 100644
--- a/kong/agent/type_recovery.py
+++ b/kong/agent/type_recovery.py
@@ -90,33 +90,6 @@ class StructAccumulator:
groups.append(same_name)
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)
diff --git a/kong/evals/__init__.py b/kong/evals/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/kong/export/__init__.py b/kong/export/__init__.py
index c5ed44d..8b13789 100644
--- a/kong/export/__init__.py
+++ b/kong/export/__init__.py
@@ -1 +1 @@
-"""Export pipeline for Kong analysis results."""
+
diff --git a/kong/export/source.py b/kong/export/source.py
index d5cb032..d49f4ad 100644
--- a/kong/export/source.py
+++ b/kong/export/source.py
@@ -4,7 +4,7 @@ from dataclasses import dataclass
from pathlib import Path
from kong.agent.models import FunctionResult
-from kong.agent.supervisor import AnalysisStats
+from kong.agent.models import AnalysisStats
from kong.ghidra.types import BinaryInfo
from kong.llm.client import TokenUsage
diff --git a/kong/llm/tools.py b/kong/llm/tools.py
index 1715287..2edd892 100644
--- a/kong/llm/tools.py
+++ b/kong/llm/tools.py
@@ -13,6 +13,7 @@ from typing import Any, TYPE_CHECKING
from kong.symbolic.dead_code import ResolvedPredicate, Resolution, eliminate_dead_code
from kong.symbolic.simplifier import simplify_expression
+from kong.symbolic.state_machine import trace_state_machine
if TYPE_CHECKING:
from kong.ghidra.client import GhidraClient
@@ -199,8 +200,7 @@ class ToolExecutor:
def __init__(self, ghidra_client: GhidraClient) -> None:
self.client = ghidra_client
- self.call_log: list[ToolCallRecord] = field(default_factory=list)
- self.call_log = []
+ self.call_log: list[ToolCallRecord] = []
@property
def call_count(self) -> int:
@@ -262,8 +262,6 @@ class ToolExecutor:
return cleaned
def _trace_state_machine(self, inputs: dict[str, Any]) -> str:
- from kong.symbolic.state_machine import trace_state_machine
-
func_addr = inputs["function_address"]
state_var = inputs["state_variable"]
result = trace_state_machine(self.client, func_addr, state_var)
diff --git a/kong/state/__init__.py b/kong/state/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/kong/tui/__init__.py b/kong/tui/__init__.py
index ebb87db..8b13789 100644
--- a/kong/tui/__init__.py
+++ b/kong/tui/__init__.py
@@ -1 +1 @@
-"""Kong TUI package."""
+
diff --git a/kong/tui/app.py b/kong/tui/app.py
index d324405..dd698c0 100644
--- a/kong/tui/app.py
+++ b/kong/tui/app.py
@@ -123,11 +123,11 @@ class KongApp(App):
elapsed=elapsed,
llm_calls=llm_calls,
cost=cost,
- paused=self.supervisor._paused,
+ paused=self.supervisor.is_paused,
)
def action_toggle_pause(self) -> None:
- if self.supervisor._paused:
+ if self.supervisor.is_paused:
self.supervisor.resume()
else:
self.supervisor.pause()
@@ -140,4 +140,4 @@ class KongApp(App):
self.run_worker(self._run_export, thread=True)
def _run_export(self) -> None:
- self.supervisor._run_export()
+ self.supervisor.export()
diff --git a/tests/test_agent_supervisor.py b/tests/test_agent_supervisor.py
index 5d91e4b..9948b5a 100644
--- a/tests/test_agent_supervisor.py
+++ b/tests/test_agent_supervisor.py
@@ -6,7 +6,8 @@ from unittest.mock import MagicMock
from kong.agent.events import EventType, Phase
from kong.agent.models import FunctionResult
-from kong.agent.supervisor import AnalysisStats, Supervisor
+from kong.agent.models import AnalysisStats
+from kong.agent.supervisor import Supervisor
from kong.config import KongConfig, OutputConfig
from kong.ghidra.types import BinaryInfo, FunctionClassification, FunctionInfo
diff --git a/tests/test_export_source.py b/tests/test_export_source.py
index 6c2ff4e..5ad3298 100644
--- a/tests/test_export_source.py
+++ b/tests/test_export_source.py
@@ -5,7 +5,7 @@ from pathlib import Path
import pytest
from kong.agent.models import FunctionResult
-from kong.agent.supervisor import AnalysisStats
+from kong.agent.models import AnalysisStats
from kong.export.source import ExportData, export_source
from kong.ghidra.types import BinaryInfo
from kong.llm.client import TokenUsage
diff --git a/tests/test_export_structured.py b/tests/test_export_structured.py
index 143e52d..dd00d9a 100644
--- a/tests/test_export_structured.py
+++ b/tests/test_export_structured.py
@@ -6,7 +6,7 @@ from pathlib import Path
import pytest
from kong.agent.models import FunctionResult
-from kong.agent.supervisor import AnalysisStats
+from kong.agent.models import AnalysisStats
from kong.export.source import ExportData
from kong.export.structured import export_json
from kong.ghidra.types import BinaryInfo
diff --git a/tests/test_tui.py b/tests/test_tui.py
index 8a525a9..878c497 100644
--- a/tests/test_tui.py
+++ b/tests/test_tui.py
@@ -8,6 +8,7 @@ from textual.app import App
from textual.widget import Widget
from textual.widgets import RichLog, Static
+from kong.agent.events import Event, EventType
from kong.agent.supervisor import Supervisor
from kong.tui.app import EVENT_STYLES, AgentEvent, KongApp
from kong.tui.widgets import AgentLog, BinaryHeader, ProgressWidget, StatusBar
@@ -93,7 +94,7 @@ class TestStatusBar:
class TestKongApp:
def test_is_app_subclass(self) -> None:
supervisor = create_autospec(Supervisor, instance=True)
- supervisor._paused = False
+ supervisor.is_paused = False
supervisor.stats = MagicMock()
supervisor.stats.llm_calls = 0
app = KongApp(supervisor)
@@ -101,7 +102,7 @@ class TestKongApp:
def test_stores_supervisor(self) -> None:
supervisor = create_autospec(Supervisor, instance=True)
- supervisor._paused = False
+ supervisor.is_paused = False
supervisor.stats = MagicMock()
supervisor.stats.llm_calls = 0
app = KongApp(supervisor)
@@ -113,7 +114,6 @@ class TestEventStyles:
assert isinstance(EVENT_STYLES, dict)
def test_event_styles_has_expected_keys(self) -> None:
- from kong.agent.events import EventType
expected_keys = {
EventType.PHASE_START,
EventType.PHASE_COMPLETE,
@@ -132,7 +132,6 @@ class TestEventStyles:
class TestAgentEvent:
def test_agent_event_wraps_event(self) -> None:
- from kong.agent.events import Event, EventType
event = Event(type=EventType.RUN_START, message="test")
msg = AgentEvent(event)
assert msg.event is event