kunglao-agent

kunglao-agent est un système autonome de rétro-ingénierie. Vous lui confiez une cible et les questions auxquelles vous avez besoin de réponses ; il travaille le problème pendant des heures ou des jours de façon autonome — planifiant son propre parcours, se remettant de la mort de workers, reprenant après des crashs — et ne converge que lorsque chaque réponse est dérivée de preuves brutes et survit à des portes de vérification mécaniques.

English · Simplified Chinese

Il est actuellement distribué sous forme de plugin Claude Code — Claude Code est l'interface avec laquelle vous dialoguez, pas ce qu'est le produit. Le produit, c'est la boucle : des workers spécialisés analysent (statique d'abord), un vérificateur indépendant redérive chaque fait à l'aveugle à partir des preuves brutes, et des portes mécaniques décident quand le travail est terminé. Le livrable est une base de faits où chaque affirmation est ancrée octet par octet, vérifiée indépendamment et indexée par preuves — la confiance est imposée par la mécanique, pas par convention.

Pourquoi kunglao-agent

Longue portée par conception. Les engagements s'exécutent sans surveillance pendant des heures et des jours : un heartbeat planifié maintient la boucle en vie, les workers morts sont réconciliés et leurs affirmations remises en file, les crashs reprennent depuis l'état sur disque, les affirmations bloquées s'auto-récupèrent. Vous lisez le verdict quand il converge — vous ne surveillez pas chaque étape. Voir Long-horizon autonomy.
Des réponses fiables. Aucun fait n'est PROVEN tant qu'un vérificateur indépendant ne l'a pas redérivé à l'aveugle à partir de l'artefact brut ; chaque fait cite un artefact brut indexé par sha256 via evidence/_index.json.
Le spectre complet de la rétro-ingénierie. Binaires natifs Windows/Linux, APK Android, web/JS, analyse de protocoles, émulation de firmware, contre-mesures de contrôle des risques — un seul système, pas un outil mono-domaine.
Économie du statique d'abord. Une tâche qui se clôture statiquement ne touche jamais à l'outillage dynamique ; chaque escalade est déclarée, contrôlée et auditée.
Il réutilise la connaissance au lieu de la redériver. Un catalogue croissant d'outils d'analyse enregistrés (décodeurs crypto, pipelines de désassemblage, requêtes de graphes) signifie que le système puise dans un outillage éprouvé avant d'écrire des scripts jetables — et chaque exécution laisse derrière elle des faits réutilisables, pas une transcription de conversation qui s'évapore.
Il récupère au lieu de mourir. Les morts de workers, les déconnexions d'API et les crashs sont des événements de premier ordre : la boucle les détecte, capture ce qui a déjà été produit et redispatch pour continuer là où les choses se sont arrêtées — pas depuis zéro.
Votre environnement, vos règles. VMware, ssh, docker, adb, ou simplement statique seul — le système pilote le canal d'exécution que vous possédez déjà. Rien n'est un mode dégradé ; une tâche qui n'a jamais besoin d'exécution ne demande jamais de VM.

Démarrage rapide

kunglao-agent s'exécute dans Claude Code. D'un échantillon sur disque à un verdict :

1. Installer le plugin

Depuis n'importe quel répertoire, dans Claude Code :``` /plugin marketplace add amd2g2zz/kunglao-agent /plugin install kunglao-agent@kunglao-agent

(Alternative : `claude --plugin-dir /path/to/kunglao-agent` pour le développement.)

### 2. Initialiser un espace de travail```
/kunglao-agent:init ~/cases/synth-dropper --type windows

kunglao-init initialise l'espace de travail, écrit CLAUDE.md, sonde la chaîne d'outils pour votre --type, et génère .mcp.json. Il rejette de manière STRICTE lorsqu'un outil requis pour votre type est manquant — les conseils de correction se trouvent dans le bloc d'erreur.

3. Énoncez la tâche et lancez l'analyse```

/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.

Rédigez le brief de manière à ce qu'un évaluateur indépendant puisse juger le résultat : **objectif d'analyse** (ce que vous devez savoir), **logique de vérification** (ce qui rend une réponse fiable — par ex. « la signature doit être reproductible à partir des mêmes entrées »), **contraintes** (par ex. « aucune exécution sur l'hôte »). Tout est consigné dans `task_spec.yaml` ; à partir de là, la boucle s'auto-alimente. Pour savoir comment les demandes courantes se transforment en énoncés bien formés, voir [Comment formuler la tâche](#how-to-state-the-task).

### 4. Lire le livrable```
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

Comment énoncer la tâche

La boucle dérive son critère d'achèvement — l'oracle — mécaniquement à partir de l'état final que vous énoncez. Un énoncé vague produit un oracle vague, et l'analyse dérive vers tout ce qui peut être prouvé au lieu de ce dont vous aviez besoin. Quatre formulations couvrent la majeure partie de cette dérive. Pour chacune : ce que disent les utilisateurs, ce que cela signifie généralement, un énoncé bien formé, et ce sur quoi l'oracle s'ancre.

« 我要纯算 » — « juste l'algorithme pur »

Signifie généralement : la reproduction hors ligne de la routine de signature/chiffrement de l'application — un harnais unidbg ou une réécriture qui s'exécute sans appareil et sans application au moment de l'exécution. Pas « analyser l'application » ; l'application n'est que l'endroit où vit l'algorithme.```

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:** rejeu byte-exact sur chaque paire, y compris celles retenues — et la reproduction s'exécutant de manière autonome.

### "我要解密" — "Je veux déchiffrer"

**Cela signifie généralement l'une de deux cibles différentes — précisez laquelle :**

- **(a) déchiffrer un corps capturé** — une réponse ponctuelle concernant ces données : « produire le texte en clair de ce fichier de cache capturé. »
- **(b) une capacité de déchiffrement** — algorithme + récupération de clé, réutilisable sur les données que vous capturerez demain.

Bien formé (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).

Bien formé (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 s'ancre sur :** (a) le texte en clair validé par rapport à ce que l'application affiche ; (b) l'algorithme + la clé identifiés et l'aller-retour du canary octet pour octet identique au texte chiffré produit par l'appareil. « Il a déchiffré une fois » ne satisfait ni l'un ni l'autre.

### « 帮我分析这个协议 » — « analyse ce protocole pour moi »

**Signifie généralement :** récupération du format de transmission — cadrage, sémantique des champs, et un codec que vous pouvez exécuter.```
> 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: le codec effectue un aller-retour sur chaque frame capturée octet par octet, et la frame mise de côté se décode en champs qui correspondent au comportement observé de l'application.

"这个 sign 在哪算的" — « où ce signe est-il calculé ? »

Signifie généralement : un emplacement avec preuve. Nommer un point dans le code ne coûte rien ; la réponse n'est utile qu'avec la preuve que ce point est bien le bon.```

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 ancré sur :** une classe/méthode/fonction native nommée, plus un hook à ce point reproduisant les valeurs capturées.

### Ce que ces éléments ont en commun

- **Nommer l'échantillon et le comportement** — quel paramètre, entrée ou flux — pas la catégorie. « 我要纯算 » est une catégorie ; « le signataire produisant l'en-tête `sign` sur api.example.com/v2/* » est une cible.
- **Le succès doit être une donnée.** Joindre les paires entrée/sortie capturées ; les paires retenues sont ce qui rend la vérification honnête — une reproduction ne peut pas surapprendre des données qu'elle n'a jamais vues.
- **L'oracle est dérivé de l'état final que vous avez énoncé.** Énoncé vague, vérification vague, analyse à la dérive.
- **Les contraintes changent le plan.** Statique uniquement ? Un appareil disponible ? Quel canal ? Dites-le d'emblée — cela décide de la route avant que le travail ne commence (voir [Apportez votre propre environnement](#bring-your-own-environment)).

## Sous-commandes

| Commande | À utiliser quand | Ce qu'elle fait |
|---|---|---|
| `/kunglao-agent:init <workspace> [--type windows\|linux\|android\|web\|macos] [--lane malware\|algorithm\|protocol\|web\|data\|app]` | démarrer un engagement, en premier | échafaude le workspace, sonde la chaîne d'outils pour le type, écrit `CLAUDE.md` et `.mcp.json` ; rejette STRICTEMENT avec des conseils de correction lorsqu'un outil requis est manquant |
| `/kunglao-agent:analysis <workspace>` (alias `analyze`) | après init — énoncez la tâche et démarrez | collecte une fois votre objectif / logique de vérification / contraintes, puis exécute la boucle de convergence : cycles dispatch / verify jusqu'au rapport |
| `/kunglao-agent:resume <workspace>` | après un crash, un redémarrage, ou tout « où en étais-je ? » | brief de point d'arrêt en lecture seule (santé, affirmations ouvertes, workers en cours, chronologie du crash) plus l'action suivante issue de la machine à états |
| `/kunglao-agent:upgrade <workspace> [--dry-run]` | après une mise à jour du plugin, sur un workspace plus ancien (ou quand l'invite de mise à niveau indique que l'estampille est en retard) | migre l'échafaudage du workspace (hooks, templates, vocabulaire d'événements) vers la version actuelle du plugin ; `--dry-run` prévisualise ; les données utilisateur (affirmations, faits, preuves) ne sont jamais touchées — une dérive d'octets refuse avec RC=4 |
| `/kunglao-agent:help` | tout le reste | affiche la liste d'utilisation |

Ordre typique : `init` crée le workspace → `analysis` énonce la tâche et démarre → (`resume` si quelque chose dérape) → lire le rapport à la convergence → `upgrade` les anciens workspaces après les mises à jour du plugin.

## À quoi ressemble une exécution

*La forme d'un engagement — ce que vous tapez, ce qui revient, où regarder.* Un exemple synthétique : un petit dropper Windows atterrit dans `~/cases/synth-dropper` :```bash
/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?"

À partir de là, la boucle s'exécute d'elle-même — la route s'adapte à ce que l'échantillon s'avère être. Vous pouvez partir (voir Long-horizon autonomy). Lorsqu'elle converge, lisez le livrable ci-dessous.

Scénarios

Deux autres parcours de bout en bout — choisissez celui correspondant à votre cible (pour un binaire Windows PE / Linux ELF classique, le cas traité ci-dessus est le bon parcours).

Android APK — ce que l'utilisateur tape, ce qui aboutit où

```bash /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?" ``` - **Lands in:** `bins/` (the APK), `facts/` (class graph, native `.so` inventory), `evidence/` (captures, dumps). - **Done looks like:** every question backed by reproducible evidence. - **The route adapts.** Some APKs close with pure static DEX work; others need on-device debugging — the loop decides from what the sample actually is.

Web / JS — unpack → deobfuscate → signed-parameter replay

```bash /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?" ``` - **Atterrit dans :** `evidence/` (captures, code désobfusqué), `facts/` (clé de signature, dérivation de nonce). - **Remarque :** `web` est une cible en phase bêta — la barre de la chaîne d'outils est délibérément légère ; la capacité manquante se révèle lorsque la boucle en a réellement besoin, pas à l'initialisation.

Ce que vous obtenez

Un registre de revendications et une base de faits où la confiance est mécanique, et non conventionnelle :

Convergence vérifiée — PROVEN exige la validation par correspondance exacte d'un vérificateur aveugle indépendant ; CONVERGED exige que chaque question primaire soit répondue avec une preuve octet par octet, zéro revendication orpheline, aucune rotation à vide.
Intégrité des preuves — chaque fait remonte via evidence/_index.json jusqu'à un artefact brut (capture / trace / dump / binaire). Les résumés dérivés sont exclus par conception.
Séparation des rôles (maker-checker) — l'agent de travail (maker) écrit les faits ; le vérificateur redteam (checker) les redérive en aveugle. Des agents différents, toujours.

Aucune revendication n'atteint PROVEN sur la parole de son auteur : un vérificateur indépendant doit la redériver en aveugle, et un ensemble de barrières mécaniques doit être franchi. La conception complète des barrières se trouve dans docs/design/loop-engineering.md.

Après l'exécution, les fichiers répondent à différentes questions :

Exemple de fait :```yaml id: F061 status: VERIFIED-BY-W01-static-byte-recheck claim_id: C-401 provenance:

{role: sample, path: bins/}
{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}

## Autonomie à long terme

Les engagements réels ne sont pas une conversation de vingt minutes. kunglao-agent reste sur le problème sans qu'un humain supervise chaque étape :

- **Fonctionne pendant des heures ou des jours, sans surveillance** — un battement de cœur planifié maintient la boucle active entre vos visites, et une boucle bloquée est signalée au lieu de mourir silencieusement.
- **Récupère après un échec** — les workers morts ou bloqués sont remplacés et leurs questions remises en file d'attente ; le travail bloqué s'auto-récupère au lieu de rester inactif.
- **Survit aux plantages et aux redémarrages** — `/kunglao-agent:resume <workspace>` reconstruit l'état des choses à partir de l'état sur disque et nomme l'action suivante.
- **Se souvient sur disque, pas dans le chat** — les revendications, les faits, les preuves et une piste d'audit complète résident dans le workspace, de sorte que n'importe quelle session peut reprendre l'engagement.

Vous lui donnez une cible et les questions ; il travaille le problème pendant des heures ou des jours, récupère après les échecs, et vous lisez le verdict lorsqu'il converge.

## Obtenir de bons résultats

- **Fournissez-lui des cibles accessibles en statique.** La boucle est statique d'abord : un APK décompressé, un bundle non obfusqué ou un binaire non strippé converge bien plus vite qu'un binaire qui force un travail dynamique.
- **Préparez la partie dynamique avant d'en avoir besoin.** Si vos questions principales nécessitent une exécution, choisissez d'abord un canal (voir [Apportez votre propre environnement](#bring-your-own-environment)) — init rejette de manière HARD une tâche dynamique sur `local`.
- **Distinguer « en cours » de « bloqué »** — de nouvelles entrées dans `runs/` signifient que la boucle est vivante ; un battement de cœur mort ou la même décision qui se répète sans nouveaux faits signifie qu'elle ne l'est pas — `/kunglao-agent:resume <workspace>` diagnostique et nomme le prochain mouvement.

## Chaîne d'outils par cible

Le `--type` que vous choisissez à l'init verrouille quels outils de niveau HARD doivent être installés. Les indications sont repliées — dépliez votre cible. **Tous les types nécessitent deux serveurs MCP :** `ghidra` (`claude mcp add ghidra -- <path>/bridge-mcp-ghidra.exe`) et `sequential-thinking` (`claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking`).

<details>
<summary><strong>windows (PE32+ x86-64)</strong> — binaires Windows natifs</summary>

| Niveau | Outil | Installation |
|---|---|---|
| HARD | `pefile` (Python) | `pip install pefile` |
| HARD | `die` (Detect It Easy) | variable d'env `KUNGLAO_DIE` ou dans le PATH — [ntinfo.com](https://ntinfo.com) |
| HARD | `floss` (FLARE FLOSS) | selon la [doc flare-floss](https://github.com/mandiant/flare-floss) |
| HARD | Ghidra ou IDA | l'un des deux ; voir [Internals](#internals) |
| HARD (T2/T3) | VMware + vmr-shell, ou un canal ssh/docker | voir [Apportez votre propre environnement](#bring-your-own-environment) |
| HARD (T2/T3) | `frida-server` (renommé, port personnalisé) | binaire côté appareil/VM, port par défaut 1337 |

Le dynamique Windows T3 utilise aussi le MCP `x64dbg` ; `volatility` (forensique mémoire) et le MCP IDA-Pro sont optionnels — voir le manifeste MCP sous [Internals](#internals).

</details>

<details>
<summary><strong>linux (ELF)</strong> — binaires Linux natifs / firmware / images mémoire</summary>

| Niveau | Outil | Installation |
|---|---|---|
| HARD | `file`, `readelf`, `objdump` | paquet `binutils` |
| HARD | Ghidra ou IDA | l'un des deux |
| HARD (T2/T3) | VMware + vmr-shell, ou un plan de contrôle ssh/docker | voir [Apportez votre propre environnement](#bring-your-own-environment) |
| HARD (T2/T3) | `frida-server` (renommé, port personnalisé) | binaire côté appareil, port 1337 |
| WARN | `gdbserver` (PATH côté hôte), `strace`, `ltrace` | extras optionnels |

`ssh-mcp` active le plan de contrôle ssh pour les hôtes distants / cloud / docker.

</details>

<details>
<summary><strong>android (APK / DEX / .so natif)</strong> — le type de cible le plus difficile, le plus d'éléments HARD</summary>

| Niveau | Outil | Installation |
|---|---|---|
| HARD | `aapt` ou `aapt2` (ou repli `unzip`) | Android SDK build-tools |
| HARD | `jadx` (décompilateur DEX → Java) | [skylot/jadx](https://github.com/skylot/jadx) |
| HARD | `apktool` (décodage/reconstruction des ressources APK) | [iBotPeaches/Apktool](https://github.com/iBotPeaches/Apktool) |
| HARD | `gitnexus` (graphe post-décompilation) | `npm i -g gitnexus` |
| HARD | Ghidra ou IDA | uniquement si l'APK contient des `.so` natifs |
| HARD | `adb` + **un appareil rooté** avec `ro.debuggable=1` | platform-tools + frida personnalisé sur l'appareil |
| HARD | `frida-server` (renommé, port personnalisé 1337) | binaire côté appareil |
| HARD | `android_server` (débogage distant IDA) | binaire côté appareil, port 23946 |
| WARN | `apkid` | `pip install apkid` |
| WARN | `baksmali` | depuis les [versions smali](https://github.com/baksmali/smali/releases) |

</details>

<details>
<summary><strong>web &amp; macos (bêta)</strong> — chaînes d'outils minimales, aucun élément HARD par conception</summary>

| Niveau | Outil | Installation |
|---|---|---|
| WARN | MCP `camoufox-reverse` (web) | Firefox anti-détection pour hook / trace / capture réseau |
| WARN | `docker` (canal web par défaut) | Docker Desktop, ou définir `KUNGLAO_CHANNEL=ssh` explicitement |
| WARN | `lipo`, `otool`, `nm`, `codesign`, `xattr` (macOS) | Xcode Command Line Tools |
| WARN | MCP `ghidra` (macOS) | recommandé — voir le manifeste sous [Internals](#internals) |

Les deux sont des cibles au stade bêta : les capacités manquantes se révèlent lorsque la boucle en a réellement besoin, pas à l'init. Le travail dynamique macOS utilise le canal `ssh` (vers un hôte Mac) ; pour le chemin optionnel de débogage navigateur x64dbg, installez la chaîne d'outils Windows ci-dessus.

</details>

Source unique de manifeste pour tout ce qui précède — sondez-la à tout moment : `python scripts/mcp_probe.py <ws> --type <windows|linux|android|web|macos>` (sortie 1 = HARD manquant).

## Apportez votre propre environnement

Le débogage dynamique nécessite un plan de contrôle d'exécution que l'agent peut piloter. `KUNGLAO_CHANNEL` sélectionne l'un des cinq canaux de première classe — utilisez ce que votre environnement possède déjà ; aucun n'est un mode dégradé :

| Canal | Ce qu'il pilote | Prérequis |
|---|---|---|
| `vmr` (par défaut) | VM VMware, **n'importe quel OS invité** — les workflows snapshot/revert sont sa valeur irremplaçable | compétence vmr-shell ; `KUNGLAO_VM_HOST` + ports 9876/1337 |
| `ssh` | N'importe quelle machine joignable en ssh : bare metal, VM cloud, Mac, hôte docker distant | auth par clé — la sonde exécute un vrai `ssh ... true` en BatchMode |
| `docker` | Démon docker local ou distant — `docker exec` équivaut à n'importe quel chemin de contrôle | `docker version` au vert ; `KUNGLAO_DOCKER_CONTAINER` optionnel |
| `adb` | Émulateur Android ou appareil réel | `adb devices` le montre ; `adb forward tcp:1337 tcp:1337` pour frida |
| `local` | **Analyse statique uniquement sur l'hôte** | aucun — voir la ligne rouge |

> **Ligne rouge de `local` :** local est réservé au travail **statique** uniquement — n'exécutez, ne déboguez et n'injectez jamais l'échantillon sur l'hôte. Toute exigence dynamique bascule `KUNGLAO_CHANNEL` vers `vmr`/`ssh`/`docker`/`adb` ; init rejette de manière HARD une tâche dynamique sur `local`.

Les sondes de canal ne s'exécutent que pour les tâches dynamiques (les tâches statiques uniquement les ignorent). L'exécution via le canal `ssh` passe par le plan de contrôle **ssh-mcp** (`npm i -g ssh-mcp`) ; le ssh CLI simple est le repli. Pour docker distant via ssh, définissez `KUNGLAO_DOCKER_CONTAINER`.

## Configuration

Quatre variables couvrent la plupart des configurations :

| Variable | Défaut | Signification |
|---|---|---|
| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | non définie | doit rester non définie ou `0` — les valeurs truthy routent les dispatches via le canal teammate et sont rejetées |
| `KUNGLAO_CHANNEL` | `vmr` | plan de contrôle d'exécution dynamique : `vmr` \| `ssh` \| `docker` \| `adb` \| `local` — voir [Apportez votre propre environnement](#bring-your-own-environment) |
| `KUNGLAO_VM_HOST` | non définie | VM/hôte pour l'analyse dynamique (vmr-shell :9876, Frida :1337) |
| `GHIDRA_HOME` | non définie | racine d'installation de Ghidra (doit contenir `support/analyzeHeadless.bat`) |

Rarement nécessaires : `KUNGLAO_DOCKER_CONTAINER` (cible d'exécution docker pour les canaux `ssh`/`docker`), `KUNGLAO_FRIDA_PORT` (défaut 1337), `KUNGLAO_DIE` (chemin DIE, repli sur le PATH), `KUNGLAO_CLAUDE_JSON` (surcharge de test pour le registre MCP au niveau utilisateur).

## Sécurité

- Les échantillons ne s'exécutent jamais sur l'hôte — le hook `block_malware_exec` l'impose ; le travail dynamique s'exécute uniquement en VM/conteneur/appareil et nécessite une autorisation par session.
- Hiérarchie de la vérité terrain : artefact brut > outil local > sandbox > threat intel (le CTI est une hypothèse falsifiable, jamais la vérité).
- Maker-checker : un worker ne s'auto-vérifie jamais ; un vérificateur ne lit jamais la conclusion du maker.
- Les binaires, les réglages et les hooks ne sont jamais commités ; les secrets sont exclus des workspaces et du dépôt.

## Développement

Les contributions sont les bienvenues. Workflow : branchez depuis `dev`, une branche par changement, PR vers `dev`.```bash
git worktree add .worktrees/<name> -b <name> dev
uv sync --locked
uv run python -m pytest -q
gh pr create --base dev

L'entrée faisant autorité pour la suite complète est python -m pytest -q (voir .github/workflows/release-check.yml).

La documentation de conception se trouve dans docs/ et specs/. Voir License.

Internals

MCP supply (the full manifest)

Source unique de vérité : scripts/mcp_probe.py ; kunglao-init génère un fichier .mcp.json d'espace de travail lorsqu'il est absent (--no-mcp l'ignore ; un fichier existant n'est jamais écrasé). Sonde : python scripts/mcp_probe.py <ws> --type <windows|linux|android|web|macos> — code de sortie 1 = HARD manquant, 2 = WARN manquant uniquement.

Workspace layout

Un espace de travail par engagement d'échantillon :``` / ├── bins/ # 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

Les hooks kunglao sont configurés au niveau du workspace ; votre fichier global `~/.claude/settings.json` n'est jamais modifié.

</details>

---

## Licence

Double licence : **AGPL-3.0** pour un usage personnel, académique et interne (gratuit — voir [LICENSE](https://github.com/amd2g2zz/kunglao-agent/blob/master/LICENSE)) ; une **licence commerciale** est requise pour un usage commercial à code fermé ou en SaaS — voir [LICENSE-commercial.md](https://github.com/amd2g2zz/kunglao-agent/blob/master/LICENSE-commercial.md).

Claude Code	où kunglao-agent s'exécute	selon les docs Anthropic
Python 3.10+ (Python 2 n'est pas pris en charge)	le plugin embarque un env épinglé via `uv` ; vous n'y touchez pas	système ou géré par `uv`
`uv`	résolveur d'env verrouillé	`pip install uv` ou astral.sh/uv
Ghidra ou IDA	une suite d'analyse statique pour la décompilation	voir Toolchain by target

Est-ce terminé ?	le code de sortie de la boucle — `CONVERGED` (0) signifie que chaque question primaire a une réponse vérifiée ; statut par revendication dans `claim-register.yaml`
Qu'a-t-il trouvé ?	`facts/F<NNN>.md` — un fait ancré sur les octets par fichier, mis en correspondance avec les revendications par `claim-register.yaml`
Comment le reproduire ?	`evidence/_index.json` — fait → artefact brut (chemin + sha256) ; chaque fait porte une commande `reproduce:`
Que s'est-il exactement passé ?	`runs/` — le registre tick par tick et le statut des agents de travail

`ghidra`	HARD	requis, tous types	décompilation / analyse statique	`claude mcp add ghidra -- <path>/bridge-mcp-ghidra.exe`
`sequential-thinking`	HARD	requis, tous types	raisonnement structuré	`claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking`
`x64dbg`	HARD	Windows T3 dynamique	débogage dynamique (VM distante)	`claude mcp add x64dbg -- x64dbg-automate-mcp`
`volatility`	WARN	Windows T3	forensique mémoire	`claude mcp add volatility -- python <path>/volatility_mcp_server.py`
`ida-pro-vm`	WARN	lorsque IDA est choisi	analyse IDA distante	`claude mcp add --transport http ida-pro-vm <ida-mcp-url>`
`gitnexus`	HARD	construction de graphe Android	graphe de connaissances post-décompilation	`claude mcp add gitnexus -- gitnexus mcp`
`virustotal`	WARN	CTI	renseignement sur les menaces (hypothèses d'attribution de famille)	`claude mcp add virustotal -- npx -y @burtthecoder/mcp-virustotal`
`ssh-mcp`	WARN	canal	plan de contrôle d'exécution ssh	`claude mcp add ssh-mcp -- ssh-mcp`
`camoufox-reverse`	WARN	web (bêta)	reverse engineering JS navigateur (hooks / trace / capture réseau)	`claude mcp add camoufox-reverse -- python -m camoufox_reverse_mcp`

Populaires

kunglao-agent

kunglao-agent

Pourquoi kunglao-agent

Démarrage rapide

1. Installer le plugin

3. Énoncez la tâche et lancez l'analyse```

Comment énoncer la tâche

« 我要纯算 » — « juste l'algorithme pur »

"这个 sign 在哪算的" — « où ce signe est-il calculé ? »

Scénarios

Ce que vous obtenez

Internals