kunglao-agent

kunglao-agent is an autonomous reverse-engineering system. You hand it a target and the questions you need answered; it works the problem for hours or days on its own — planning its own path, recovering from worker deaths, resuming after crashes — and converges only when every answer is derived from raw evidence and survives mechanical verification gates.

English · Simplified Chinese

It currently ships as a Claude Code plugin — Claude Code is the interface you talk to, not what the product is. The product is the loop: specialist workers analyse (static first), an independent verifier re-derives every fact blind from the raw evidence, and mechanical gates decide when the work is done. The deliverable is a fact base where every claim is byte-anchored, independently verified, and evidence-indexed — trust is enforced by machinery, not convention.

Why kunglao-agent

• Long-horizon by design. Engagements run unattended across hours and days: a scheduled heartbeat keeps the loop alive, dead workers are reconciled and their claims re-queued, crashes resume from on-disk state, blocked claims self-recover. You read the verdict when it converges — you don't babysit each step. See Long-horizon autonomy.
• Answers you can trust. No fact is PROVEN until an independent verifier re-derives it blind from the raw artifact; every fact cites a sha256-indexed raw artifact through evidence/_index.json.
• The full reverse-engineering spectrum. Windows/Linux native binaries, Android APKs, web/JS, protocol analysis, firmware emulation, risk-control countermeasures — one system, not a single-domain tool.
• Static-first economics. A task that closes statically never touches dynamic tooling; every escalation is declared, gated, and audited.
• It reuses knowledge instead of re-deriving it. A growing catalog of registered analysis tools (crypto decoders, disassembly pipelines, graph queries) means the system reaches for proven tooling before writing one-off scripts — and every run leaves behind reusable facts, not a chat transcript that evaporates.
• It recovers instead of dying. Worker deaths, API disconnects, and crashes are first-class events: the loop detects them, snapshots what was already produced, and re-dispatches to continue from where things stopped — not from zero.
• Your environment, your rules. VMware, ssh, docker, adb, or plain static-only — the system drives whichever execution channel you already have. Nothing is a degraded mode; a task that never needs execution never asks for a VM.

Quick start

kunglao-agent runs inside Claude Code. From a sample on disk to a verdict:

1. Install the plugin

From any directory, in Claude Code:

/plugin marketplace add amd2g2zz/kunglao-agent
/plugin install kunglao-agent@kunglao-agent

(Alternative: claude --plugin-dir /path/to/kunglao-agent for development.)

2. Init a workspace

/kunglao-agent:init ~/cases/synth-dropper --type windows

kunglao-init scaffolds the workspace, writes CLAUDE.md, probes the toolchain for your --type, and scaffolds .mcp.json. It HARD-rejects when a required tool for your type is missing — the fix guidance is in the error block.

3. State the task and start the analysis

/kunglao-agent:analysis ~/cases/synth-dropper
> Goal: confirm this dropper's persistence mechanism and network endpoints;
>   every conclusion must be reproducible from raw evidence.
> Verification: key findings count only if an independent verifier re-derives
>   them blind and reaches the same answer.
> Constraints: static-first; never execute the sample on the host.

Write the brief so an independent reviewer could judge the result: analysis goal (what you need to know), verification logic (what makes an answer trustworthy — e.g. "the signature must be reproducible from the same inputs"), constraints (e.g. "no execution on the host"). Everything is recorded in task_spec.yaml; from there the loop drives itself. For how the common asks turn into well-formed statements, see How to state the task.

4. Read the deliverable

claim-register.yaml   # every claim terminal, with verifier sign-off
facts/F<NNN>.md       # byte-anchored, reproducible, frontmatter contract
evidence/_index.json  # every fact → raw artifact (sha256 + path)
runs/                 # session audit trail

How to state the task

The loop derives its completion criterion — the oracle — mechanically from the end-state you state. A vague statement yields a vague oracle, and the analysis drifts toward whatever can be proven instead of what you needed. Four phrasings cover most of that drift. For each: what users say, what it usually means, a well-formed statement, and what the oracle anchors on.

"我要纯算" — "just the pure algorithm"

Usually means: offline reproduction of the app's signing/crypto routine — a unidbg harness or a rewrite that runs with no device and no app at run time. Not "analyze the app"; the app is only where the algorithm lives.

> Sample: the v7.2 APK; behavior: the signer producing the `sign`
>   header on api.example.com/v2/* requests.
> Criterion: a standalone reproduction (unidbg or rewrite) replays
>   every captured (input → sign) pair byte-exact — including the
>   withheld pairs — with no device or app at run time.
> Attach: captures/sign-pairs.jsonl — 20 input/output pairs captured
>   from a live session; 10 of them withheld from the analysis.

Oracle anchors on: byte-exact replay on every pair, including the withheld ones — and the reproduction running standalone.

"我要解密" — "I want decryption"

Usually means one of two different targets — say which:

• (a) decrypt one captured body — a one-off answer about this data: "produce the plaintext of this captured cache file."
• (b) a decryption capability — algorithm + key recovery, reusable on data you capture tomorrow.

Well-formed (a):

> Sample: the v7.2 APK; behavior: the local config cache
>   files/.cfg/v2.dat is encrypted at rest.
> Criterion: produce the plaintext of the captured v2.dat and validate
>   it against what the app renders (field names and values match the
>   screenshot captured alongside).

Well-formed (b):

> Sample: the v7.2 APK; behavior: request bodies on
>   api.example.com/v2/* are encrypted with a static key.
> Criterion: identify the algorithm and the key, then run a canary
>   round-trip — encrypt a known plaintext with the recovered key and
>   match the ciphertext the device produced, byte for byte.
> Attach: captures/request-bodies.jsonl — ciphertext bodies captured
>   from the device, with the requests that produced them.

Oracle anchors on: (a) the plaintext validating against what the app renders; (b) algorithm + key identified and the canary round-trip byte-identical to device-produced ciphertext. "It decrypted once" satisfies neither.

"帮我分析这个协议" — "analyze this protocol for me"

Usually means: wire-format recovery — framing, field semantics, and a codec you can run.

> Sample: the Android chat app; behavior: the TCP protocol on
>   gateway.example.com:443, as captured in gateway-session.pcap.
> Criterion: a codec that round-trips every captured frame byte-exact,
>   and decodes the held-out frame to fields matching the observed app
>   behavior.
> Attach: captures/gateway-session.pcap — 40 frames, plus 1 held-out
>   frame kept out of the analysis.

Oracle anchors on: the codec round-tripping every captured frame byte-exact, and the held-out frame decoding to fields that match observed app behavior.

"这个 sign 在哪算的" — "where does this sign get computed?"

Usually means: a location with proof. Naming a point in the code is cheap; the answer is only useful with evidence that this point is the point.

> Sample: the v7.2 APK; behavior: the `sign` header attached to every
>   request.
> Criterion: name the class/method (or native function) where `sign`
>   is computed, and hook that point to reproduce the captured `sign`
>   values from the same inputs.
> Attach: captures/sign-session.jsonl — captured `sign` values with
>   their request inputs.

Oracle anchors on: a named class/method/native function, plus a hook at that point reproducing the captured values.

What these have in common

• Name the sample and the behavior — which parameter, entry, or flow — not the category. "我要纯算" is a category; "the signer producing the sign header on api.example.com/v2/*" is a target.
• Success must be data. Attach captured input/output pairs; the withheld pairs are what make the check honest — a reproduction cannot overfit data it never saw.
• The oracle is derived from your stated end-state. Vague statement, vague verification, drifting analysis.
• Constraints change the plan. Static-only? A device available? Which channel? Say so up front — it decides the route before work starts (see Bring your own environment).

Subcommands

Typical order: init creates the workspace → analysis states the task and starts → (resume if anything goes sideways) → read the report at convergence → upgrade old workspaces after plugin updates.

What a run looks like

The shape of an engagement — what you type, what comes back, where to look. A synthetic example: a small Windows dropper lands in ~/cases/synth-dropper:

/kunglao-agent:init ~/cases/synth-dropper --type windows   # probes Ghidra, VM reachability
/kunglao-agent:analysis ~/cases/synth-dropper
> "What does this binary do, and where does it phone home?"

From there the loop runs itself — the route adapts to what the sample turns out to be. You can walk away (see Long-horizon autonomy). When it converges, read the deliverable below.

Scenarios

Two more end-to-end paths — pick the one matching your target (for a plain Windows PE / Linux ELF binary, the worked case above is the path).

/kunglao-agent:init ~/cases/sample.apk --type android
/kunglao-agent:analysis ~/cases/sample.apk
> "Does this APK load code dynamically or fight debugging? If so, where is
>   the hidden logic and what does it do?"

/kunglao-agent:init ~/cases/example-site.com --type web
/kunglao-agent:analysis ~/cases/example-site.com
> "how is the XHR request signed, and where does the nonce come from?"

What you get

A claim register and fact base where trust is mechanical, not conventional:

• Verified convergence — PROVEN requires an independent blind verifier's exact-match sign-off; CONVERGED requires every primary question answered with byte-proof, zero orphan claims, no spinning.
• Evidence integrity — every fact traces through evidence/_index.json to a raw artifact (capture / trace / dump / binary). Derived summaries are excluded by design.
• Maker-checker — the worker (maker) writes facts; the redteam verifier (checker) re-derives them blind. Different agents, always.

No claim reaches PROVEN on its author's word: an independent verifier must re-derive it blind, and a set of mechanical gates must pass. The full gate design lives in docs/design/loop-engineering.md.

After the run, the files answer different questions:

Example fact:

id: F061
status: VERIFIED-BY-W01-static-byte-recheck
claim_id: C-401
provenance:
  - {role: sample, path: bins/<sha>}
  - {role: capture_log, path: runs/c329-inner-pe.bin}   # via evidence/_index.json
reproduce: python -c "import struct; ..."               # runs against the cited artifact
verifier_sign_off: {verifier: kunglao-redteam, verdict: CONFIRMED}

Long-horizon autonomy

Real engagements are not a twenty-minute chat. kunglao-agent stays on the problem without a human shepherding every step:

• Runs for hours or days, unattended — a scheduled heartbeat keeps the loop working between your visits, and a stalled loop is flagged instead of silently dying.
• Recovers from failure — dead or stuck workers are replaced and their questions re-queued; blocked work self-recovers instead of idling.
• Survives crashes and reboots — /kunglao-agent:resume <workspace> rebuilds where things stood from on-disk state and names the next action.
• Remembers on disk, not in chat — claims, facts, evidence, and a full audit trail live in the workspace, so any session can pick the engagement back up.

You give it a target and the questions; it works the problem for hours or days, recovers from failures, and you read the verdict when it converges.

Getting good results

• Feed it static-accessible targets. The loop is static-first: an unpacked APK, an unobfuscated bundle, or an unstripped binary converges far faster than one that forces dynamic work.
• Set up the dynamic leg before you need it. If your primary questions will require execution, pick a channel first (see Bring your own environment) — init HARD-rejects a dynamic task on local.
• Telling "working" from "stuck" — fresh entries in runs/ mean the loop is alive; a dead heartbeat or the same decision repeating with no new facts means it is not — /kunglao-agent:resume <workspace> diagnoses and names the next move.

Toolchain by target

The --type you pick at init locks which HARD-tier tools must be installed. Guidance is collapsed — expand your target. All types require two MCP servers: ghidra (claude mcp add ghidra -- <path>/bridge-mcp-ghidra.exe) and sequential-thinking (claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking).

Single manifest source for everything above — probe it any time: python scripts/mcp_probe.py <ws> --type <windows|linux|android|web|macos> (exit 1 = HARD missing).

Bring your own environment

Dynamic debugging needs an execution control plane the agent can drive. KUNGLAO_CHANNEL selects one of five first-class channels — use what your environment already has; none is a degraded mode:

local red line: local is for static work only — never execute, debug, or inject the sample on the host. Any dynamic requirement switches KUNGLAO_CHANNEL to vmr/ssh/docker/adb; init HARD-rejects a dynamic task on local.

Channel probes run only for dynamic tasks (static-only tasks skip them). ssh-channel execution flows through the ssh-mcp control plane (npm i -g ssh-mcp); plain CLI ssh is the fallback. For remote docker over ssh, set KUNGLAO_DOCKER_CONTAINER.

Configuration

Four variables cover most setups:

Rarely needed: KUNGLAO_DOCKER_CONTAINER (docker execution target for the ssh/docker channels), KUNGLAO_FRIDA_PORT (default 1337), KUNGLAO_DIE (DIE path, falls back to PATH), KUNGLAO_CLAUDE_JSON (test override for the user-level MCP registry).

Safety

• Samples never execute on the host — the block_malware_exec hook enforces it; dynamic work runs VM/container/device-only and requires per-session authorization.
• Ground truth hierarchy: raw artifact > local tool > sandbox > threat intel (CTI is a falsifiable hypothesis, never truth).
• Maker-checker: a worker never self-verifies; a verifier never reads the maker's conclusion.
• Bins, settings, and hooks are never committed; secrets are excluded from workspaces and the repo.

Development

Contributions are welcome. Workflow: branch from dev, one branch per change, PR back to dev.

git worktree add .worktrees/<name> -b <name> dev
uv sync --locked
uv run python -m pytest -q
gh pr create --base dev

The authoritative full-suite entry is python -m pytest -q (see .github/workflows/release-check.yml).

Design documentation lives in docs/ and specs/. See License.

Internals

<workspace>/
├── bins/<sha256>              # the sample (gitignored)
├── task_spec.yaml             # primary_questions / scope / constraints / success_criteria
├── claim-register.yaml        # claims C-NN with status (OPEN/PROVEN/STAMP/...)
├── claim_deps.yaml            # claim DAG
├── facts/                     # byte-anchored facts F-NNN.md + _INDEX.md
├── evidence/                  # raw artifacts + _index.json (eid → path + sha256)
├── runs/                      # worker-status, plans, ledgers, .heartbeat.json
├── blockers/                  # failure-attribution records per claim
└── CLAUDE.md                  # workspace rules, generated by kunglao-init

License

Dual-licensed: AGPL-3.0 for personal, academic, and internal use (free — see LICENSE); a commercial license is required for closed-source or SaaS commercial use — see LICENSE-commercial.md.