kunglao-agent

kunglao-agent는 자율 리버스 엔지니어링 시스템입니다. 대상과 답이 필요한 질문을 넘겨주면, 시스템이 스스로 경로를 계획하고, 워커 사망에서 복구하고, 크래시 후 재개하면서 몇 시간 또는 며칠 동안 독자적으로 문제를 풀어나가며, 모든 답이 원시 증거에서 도출되고 기계적 검증 게이트를 통과할 때에만 수렴합니다.

English · Simplified Chinese

현재는 Claude Code 플러그인으로 제공됩니다 — Claude Code는 여러분이 대화하는 인터페이스일 뿐, 제품 자체가 아닙니다. 제품은 루프입니다: 전문 워커들이 분석하고(정적 분석 우선), 독립적인 검증자가 모든 사실을 원시 증거로부터 맹목적으로 재도출하며, 기계적 게이트가 작업 완료 여부를 결정합니다. 산출물은 모든 주장이 바이트 단위로 고정되고, 독립적으로 검증되며, 증거 색인화된 사실 기반입니다 — 신뢰는 관례가 아니라 기계장치에 의해 강제됩니다.

kunglao-agent를 사용하는 이유

설계부터 장기 지평. 작업은 몇 시간에서 며칠에 걸쳐 무인으로 실행됩니다: 예약된 하트비트가 루프를 살아 있게 유지하고, 죽은 워커는 조정되어 그들의 주장이 다시 큐에 들어가며, 크래시는 디스크 상태에서 재개되고, 막힌 주장은 스스로 복구됩니다. 수렴했을 때 판정을 읽으면 됩니다 — 각 단계를 일일이 돌볼 필요가 없습니다. 장기 지평 자율성을 참조하세요.
신뢰할 수 있는 답변. 독립적인 검증자가 원시 아티팩트로부터 맹목적으로 재도출하기 전까지 어떤 사실도 PROVEN이 되지 않습니다; 모든 사실은 evidence/_index.json을 통해 sha256으로 색인화된 원시 아티팩트를 인용합니다.
전체 리버스 엔지니어링 스펙트럼. Windows/Linux 네이티브 바이너리, Android APK, 웹/JS, 프로토콜 분석, 펌웨어 에뮬레이션, 리스크 컨트롤 대응책 — 단일 도메인 도구가 아닌 하나의 시스템입니다.
정적 우선 경제성. 정적으로 종결되는 작업은 동적 도구를 전혀 건드리지 않습니다; 모든 에스컬레이션은 선언되고, 게이트를 거치며, 감사됩니다.
지식을 재도출하는 대신 재사용합니다. 등록된 분석 도구(암호 디코더, 디스어셈블리 파이프라인, 그래프 쿼리)의 성장하는 카탈로그는 시스템이 일회성 스크립트를 작성하기 전에 검증된 도구를 먼저 찾도록 합니다 — 그리고 모든 실행은 증발하는 채팅 기록이 아닌 재사용 가능한 사실을 남깁니다.
죽지 않고 복구합니다. 워커 사망, API 연결 끊김, 크래시는 일급 이벤트입니다: 루프가 이를 감지하고, 이미 생성된 것을 스냅샷하며, 처음부터가 아닌 중단된 지점부터 계속하도록 재디스패치합니다.
당신의 환경, 당신의 규칙. VMware, ssh, docker, adb, 또는 순수 정적 전용 — 시스템은 이미 가지고 있는 실행 채널을 구동합니다. 저하 모드란 없습니다; 실행이 전혀 필요 없는 작업은 VM을 요구하지 않습니다.

빠른 시작

kunglao-agent는 Claude Code 내에서 실행됩니다. 디스크의 샘플에서 판정까지:

1. 플러그인 설치

아무 디렉터리에서나, Claude Code에서:``` /plugin marketplace add amd2g2zz/kunglao-agent /plugin install kunglao-agent@kunglao-agent

(대안: 개발용으로 `claude --plugin-dir /path/to/kunglao-agent` 사용.)

### 2. 워크스페이스 초기화```
/kunglao-agent:init ~/cases/synth-dropper --type windows

kunglao-init은 워크스페이스를 스캐폴딩하고, CLAUDE.md를 작성하며, --type에 대한 툴체인을 탐색하고, .mcp.json을 스캐폴딩합니다. 해당 타입에 필요한 도구가 없으면 HARD-reject합니다 — 수정 안내는 오류 블록에 있습니다.

3. 작업을 명시하고 분석을 시작하세요```

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

독립적인 검토자가 결과를 판단할 수 있도록 브리프를 작성하세요: **분석 목표**(무엇을 알아야 하는가), **검증 논리**(답변을 신뢰할 수 있게 만드는 것 — 예: "서명은 동일한 입력으로부터 재현 가능해야 함"), **제약 조건**(예: "호스트에서 실행 금지"). 모든 것이 `task_spec.yaml`에 기록되며, 거기서부터 루프가 스스로 작동합니다. 일반적인 요청이 어떻게 잘 구성된 명세로 바뀌는지는 [작업을 명시하는 방법](#how-to-state-the-task)을 참조하세요.

### 4. 결과물 읽기```
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

작업을 명시하는 방법

루프는 완료 기준 — 즉 오라클 — 을 사용자가 명시한 최종 상태로부터 기계적으로 도출합니다. 모호한 진술은 모호한 오라클을 낳고, 분석은 필요한 것이 아니라 증명 가능한 쪽으로 흘러갑니다. 네 가지 표현 방식이 이러한 흐름의 대부분을 포괄합니다. 각각에 대해: 사용자가 말하는 것, 그것이 보통 의미하는 것, 잘 정형화된 진술, 그리고 오라클이 무엇에 고정되는지를 다룹니다.

"我要纯算" — "순수 알고리즘만"

보통 의미하는 것: 앱의 서명/암호화 루틴을 오프라인에서 재현하는 것 — unidbg 하네스 또는 런타임에 기기나 앱 없이 실행되는 재작성. "앱을 분석하라"가 아니다; 앱은 단지 알고리즘이 존재하는 곳일 뿐이다.```

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:** 모든 쌍(보류된 쌍 포함)에 대한 바이트 단위 정확한 재현 — 그리고 독립 실행되는 재현.

### "我要解密" — "복호화하고 싶다"

**보통 두 가지 서로 다른 목표 중 하나를 의미 — 어느 쪽인지 말하라:**

- **(a) 캡처된 본문 하나를 복호화** — 이 데이터에 대한 일회성 답변: "이 캡처된 캐시 파일의 평문을 생성하라."
- **(b) 복호화 능력** — 알고리즘 + 키 복구, 내일 캡처할 데이터에 재사용 가능.

잘 구성된 (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).

잘 구성된 경우 (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이 고정하는 기준:** (a) 평문이 앱이 렌더링하는 내용과 일치하는지 검증; (b) 알고리즘 + 키가 식별되고, 카나리아 왕복 결과가 디바이스가 생성한 암호문과 바이트 단위로 동일한지. "한 번 복호화됐다"는 어느 쪽도 충족하지 않는다.

### "帮我分析这个协议" — "이 프로토콜을 분석해 줘"

**보통 의미하는 것:** 와이어 포맷 복원 — 프레이밍, 필드 의미론, 그리고 실행 가능한 코덱.```
> 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: 코덱이 캡처된 모든 프레임을 바이트 단위로 정확히 왕복 처리하는지, 그리고 홀드아웃 프레임이 관찰된 앱 동작과 일치하는 필드로 디코딩되는지에 있습니다.

"这个 sign 在哪算的" — "이 sign은 어디에서 계산되는가?"

보통 의미하는 것: 증거가 있는 위치. 코드에서 한 지점을 지목하는 것은 값싼 일이며, 그 답은 이 지점이 바로 그 지점이라는 증거가 있을 때에만 유용합니다.```

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:** 이름이 지정된 클래스/메서드/네이티브 함수, 그리고 그 지점에서 캡처된 값을 재현하는 훅.

### 이것들의 공통점

- **샘플과 동작을 명시하라** — 카테고리가 아니라 어떤 파라미터, 엔트리, 또는 흐름인지. "我要纯算"은 카테고리이고, "api.example.com/v2/*에서 `sign` 헤더를 생성하는 서명자"는 타깃이다.
- **성공은 데이터여야 한다.** 캡처된 입력/출력 쌍을 첨부하라; 보류된 쌍이 검증을 정직하게 만든다 — 재현은 한 번도 본 적 없는 데이터에 과적합할 수 없다.
- **오라클은 당신이 진술한 최종 상태에서 도출된다.** 모호한 진술, 모호한 검증, 표류하는 분석.
- **제약이 계획을 바꾼다.** 정적 분석만? 디바이스 사용 가능? 어떤 채널? 미리 말하라 — 이것이 작업 시작 전에 경로를 결정한다 ([Bring your own environment](#bring-your-own-environment) 참조).

## 서브커맨드

| Command | Use when | What it does |
|---|---|---|
| `/kunglao-agent:init <workspace> [--type windows\|linux\|android\|web\|macos] [--lane malware\|algorithm\|protocol\|web\|data\|app]` | engagement 시작 시, 가장 먼저 | 워크스페이스를 스캐폴딩하고, 해당 타입에 맞게 툴체인을 탐색하며, `CLAUDE.md`와 `.mcp.json`을 작성한다; 필수 도구가 없으면 수정 안내와 함께 HARD-reject |
| `/kunglao-agent:analysis <workspace>` (별칭 `analyze`) | init 이후 — 작업을 진술하고 시작 | 목표 / 검증 로직 / 제약을 한 번 수집한 뒤 수렴 루프를 실행: 리포트까지 dispatch / verify 사이클 반복 |
| `/kunglao-agent:resume <workspace>` | 크래시, 재부팅, 또는 "내가 어디까지 했더라?" 이후 | 읽기 전용 브레이크포인트 브리핑 (상태, 열린 클레임, 진행 중인 워커, 크래시 타임라인)과 상태 머신이 제시하는 다음 행동 |
| `/kunglao-agent:upgrade <workspace> [--dry-run]` | 플러그인 업데이트 후, 오래된 워크스페이스에서 (또는 업그레이드 프롬프트가 스탬프가 뒤처졌다고 할 때) | 워크스페이스 스캐폴드 (훅, 템플릿, 이벤트 어휘)를 현재 플러그인 버전으로 마이그레이션; `--dry-run`은 미리보기; 사용자 데이터 (클레임, 팩트, 증거)는 절대 건드리지 않음 — 바이트 드리프트 시 RC=4로 거부 |
| `/kunglao-agent:help` | 그 외 모든 경우 | 사용법 목록 출력 |

일반적인 순서: `init`이 워크스페이스 생성 → `analysis`가 작업을 진술하고 시작 → (문제가 생기면 `resume`) → 수렴 시 리포트 읽기 → 플러그인 업데이트 후 오래된 워크스페이스에 `upgrade`.

## 실행 모습

*engagement의 형태 — 무엇을 입력하고, 무엇이 돌아오며, 어디를 봐야 하는가.* 합성 예시: 작은 Windows dropper가 `~/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?"

거기서부터 루프는 스스로 실행됩니다 — 경로는 샘플이 밝혀내는 것에 따라 적응합니다. 자리를 비워도 됩니다(장기 자율성 참조). 수렴하면 아래의 결과물을 읽으십시오.

시나리오

두 가지 추가 엔드투엔드 경로 — 대상에 맞는 것을 선택하십시오(일반 Windows PE / Linux ELF 바이너리의 경우 위의 작업 사례가 그 경로입니다).

Android APK — 사용자가 입력하는 것, 어디에 무엇이 남는가

```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?" ``` - **위치:** `bins/` (APK), `facts/` (클래스 그래프, 네이티브 `.so` 인벤토리), `evidence/` (캡처, 덤프). - **완료 기준:** 모든 질문이 재현 가능한 증거로 뒷받침됨. - **경로는 적응한다.** 일부 APK는 순수 정적 DEX 작업으로 마무리되고, 다른 것들은 온디바이스 디버깅이 필요하다 — 루프는 샘플이 실제로 무엇인지에 따라 결정한다.

Web / JS — 언팩 → 디오브푸스케이트 → 서명된 파라미터 리플레이

```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?" ``` - **위치:** `evidence/` (캡처, 디오브푸스케이트된 코드), `facts/` (서명 키, nonce 파생). - **참고:** `web`은 베타 단계 대상이다 — 툴체인 기준은 의도적으로 가볍게 설정되어 있으며, 누락된 기능은 초기화 시점이 아니라 루프가 실제로 필요로 할 때 드러난다.

얻을 수 있는 것

신뢰가 관습이 아니라 기계적으로 작동하는 클레임 레지스터와 팩트 베이스:

검증된 수렴 — PROVEN은 독립적인 블라인드 검증자의 정확한 일치 승인을 요구하며, CONVERGED는 모든 주요 질문이 바이트 증명으로 답변되고, 고아 클레임이 없으며, 스피닝이 없어야 한다.
증거 무결성 — 모든 팩트는 evidence/_index.json을 통해 원시 아티팩트(캡처 / 트레이스 / 덤프 / 바이너리)로 추적된다. 파생된 요약은 설계상 제외된다.
메이커-체커 — 작업자(메이커)가 팩트를 작성하고, 레드팀 검증자(체커)가 블라인드로 재도출한다. 항상 서로 다른 에이전트가 수행한다.

어떤 클레임도 작성자의 말만으로 PROVEN에 도달하지 않는다: 독립적인 검증자가 블라인드로 재도출해야 하며, 일련의 기계적 게이트를 통과해야 한다. 전체 게이트 설계는 docs/design/loop-engineering.md에 있다.

실행 후, 파일들은 서로 다른 질문에 답한다:

팩트 예시:```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}

## 장기 자율성

실제 인게이지먼트는 20분짜리 채팅이 아닙니다. kunglao-agent는 모든 단계를 사람이 이끌지 않고도 문제에 계속 매달립니다:

- **몇 시간 또는 며칠 동안 무인으로 실행** — 예약된 하트비트가 방문 사이에도 루프를 계속 작동시키며, 멈춘 루프는 조용히 죽는 대신 플래그가 지정됩니다.
- **실패로부터 복구** — 죽거나 멈춘 워커는 교체되고 그들의 질문은 다시 큐에 들어갑니다. 막힌 작업은 유휴 상태로 있는 대신 스스로 복구됩니다.
- **크래시와 재부팅에서도 살아남음** — `/kunglao-agent:resume <workspace>`가 디스크 상태로부터 상황을 재구성하고 다음 작업을 명시합니다.
- **채팅이 아닌 디스크에 기억** — 클레임, 사실, 증거, 전체 감사 추적이 워크스페이스에 존재하므로 어떤 세션이든 인게이지먼트를 다시 이어받을 수 있습니다.

목표와 질문을 주면, 몇 시간 또는 며칠 동안 문제를 풀고, 실패로부터 복구하며, 수렴했을 때 판정을 읽으면 됩니다.

## 좋은 결과 얻기

- **정적으로 접근 가능한 타겟을 제공하세요.** 루프는 정적 우선입니다: 언팩된 APK, 난독화되지 않은 번들, 또는 스트립되지 않은 바이너리가 동적 작업을 강제하는 것보다 훨씬 빠르게 수렴합니다.
- **필요해지기 전에 동적 레그를 설정하세요.** 주요 질문에 실행이 필요하다면 먼저 채널을 선택하세요([자체 환경 가져오기](#bring-your-own-environment) 참조) — init은 `local`에서 동적 작업을 HARD 거부합니다.
- **"작동 중"과 "막힘" 구분하기** — `runs/`에 새 항목이 있으면 루프가 살아 있는 것입니다. 하트비트가 죽었거나 새로운 사실 없이 같은 결정이 반복되면 그렇지 않은 것입니다 — `/kunglao-agent:resume <workspace>`가 진단하고 다음 움직임을 명시합니다.

## 타겟별 툴체인

init에서 선택한 `--type`이 어떤 HARD 등급 도구가 설치되어야 하는지 고정합니다. 안내는 접혀 있습니다 — 타겟을 펼치세요. **모든 타입은 두 개의 MCP 서버를 요구합니다:** `ghidra` (`claude mcp add ghidra -- <path>/bridge-mcp-ghidra.exe`)와 `sequential-thinking` (`claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking`).

<details>
<summary><strong>windows (PE32+ x86-64)</strong> — 네이티브 Windows 바이너리</summary>

| Tier | Tool | Install |
|---|---|---|
| HARD | `pefile` (Python) | `pip install pefile` |
| HARD | `die` (Detect It Easy) | `KUNGLAO_DIE` env 또는 PATH — [ntinfo.com](https://ntinfo.com) |
| HARD | `floss` (FLARE FLOSS) | [flare-floss docs](https://github.com/mandiant/flare-floss) 참조 |
| HARD | Ghidra 또는 IDA | 둘 중 하나; [Internals](#internals) 참조 |
| HARD (T2/T3) | VMware + vmr-shell, 또는 ssh/docker 채널 | [자체 환경 가져오기](#bring-your-own-environment) 참조 |
| HARD (T2/T3) | `frida-server` (이름 변경, 사용자 지정 포트) | 디바이스/VM 측 바이너리, 기본 포트 1337 |

Windows T3 동적 작업은 `x64dbg` MCP도 사용합니다. `volatility` (메모리 포렌식)와 IDA-Pro MCP는 선택 사항입니다 — [Internals](#internals) 아래의 MCP 매니페스트를 참조하세요.

</details>

<details>
<summary><strong>linux (ELF)</strong> — 네이티브 Linux 바이너리 / 펌웨어 / 메모리 이미지</summary>

| Tier | Tool | Install |
|---|---|---|
| HARD | `file`, `readelf`, `objdump` | `binutils` 패키지 |
| HARD | Ghidra 또는 IDA | 둘 중 하나 |
| HARD (T2/T3) | VMware + vmr-shell, 또는 ssh/docker 컨트롤 플레인 | [자체 환경 가져오기](#bring-your-own-environment) 참조 |
| HARD (T2/T3) | `frida-server` (이름 변경, 사용자 지정 포트) | 디바이스 측 바이너리, 포트 1337 |
| WARN | `gdbserver` (호스트 측 PATH), `strace`, `ltrace` | 선택적 추가 |

`ssh-mcp`는 원격 / 클라우드 / docker 호스트를 위한 ssh 컨트롤 플레인을 활성화합니다.

</details>

<details>
<summary><strong>android (APK / DEX / 네이티브 .so)</strong> — 가장 어려운 타겟 타입, 가장 많은 HARD 항목</summary>

| Tier | Tool | Install |
|---|---|---|
| HARD | `aapt` 또는 `aapt2` (또는 `unzip` 폴백) | Android SDK build-tools |
| HARD | `jadx` (DEX → Java 디컴파일러) | [skylot/jadx](https://github.com/skylot/jadx) |
| HARD | `apktool` (APK 리소스 디코드/리빌드) | [iBotPeaches/Apktool](https://github.com/iBotPeaches/Apktool) |
| HARD | `gitnexus` (디컴파일 후 그래프) | `npm i -g gitnexus` |
| HARD | Ghidra 또는 IDA | APK에 네이티브 `.so`가 포함된 경우에만 |
| HARD | `adb` + `ro.debuggable=1`인 **루팅된 디바이스** | platform-tools + 디바이스의 사용자 지정 frida |
| HARD | `frida-server` (이름 변경, 사용자 지정 포트 1337) | 디바이스 측 바이너리 |
| HARD | `android_server` (IDA 원격 디버깅) | 디바이스 측 바이너리, 포트 23946 |
| WARN | `apkid` | `pip install apkid` |
| WARN | `baksmali` | [smali releases](https://github.com/baksmali/smali/releases)에서 |

</details>

<details>
<summary><strong>web &amp; macos (베타)</strong> — 최소 툴체인, 설계상 HARD 항목 없음</summary>

| Tier | Tool | Install |
|---|---|---|
| WARN | `camoufox-reverse` MCP (web) | 훅 / 트레이스 / 네트워크 캡처를 위한 안티 디텍트 Firefox |
| WARN | `docker` (web 채널 기본값) | Docker Desktop, 또는 `KUNGLAO_CHANNEL=ssh`를 명시적으로 설정 |
| WARN | `lipo`, `otool`, `nm`, `codesign`, `xattr` (macOS) | Xcode Command Line Tools |
| WARN | `ghidra` MCP (macOS) | 권장 — [Internals](#internals) 아래의 매니페스트 참조 |

둘 다 베타 단계 타겟입니다: 누락된 기능은 init이 아니라 루프가 실제로 필요로 할 때 표면화됩니다. macOS 동적 작업은 `ssh` 채널(Mac 호스트로)을 사용합니다. 선택적 x64dbg 브라우저 디버그 경로의 경우 위의 Windows 툴체인을 설치하세요.

</details>

위의 모든 것에 대한 단일 매니페스트 소스 — 언제든지 프로브하세요: `python scripts/mcp_probe.py <ws> --type <windows|linux|android|web|macos>` (종료 1 = HARD 누락).

## 자체 환경 가져오기

동적 디버깅에는 에이전트가 구동할 수 있는 실행 컨트롤 플레인이 필요합니다. `KUNGLAO_CHANNEL`은 다섯 개의 일급 채널 중 하나를 선택합니다 — 환경에 이미 있는 것을 사용하세요. 어느 것도 저하된 모드가 아닙니다:

| Channel | What it drives | Prerequisites |
|---|---|---|
| `vmr` (기본값) | VMware VM, **모든 게스트 OS** — 스냅샷/되돌리기 워크플로가 대체 불가능한 가치 | vmr-shell 스킬; `KUNGLAO_VM_HOST` + 포트 9876/1337 |
| `ssh` | ssh로 접근 가능한 모든 박스: 베어 메탈, 클라우드 VM, Mac, 원격 docker 호스트 | 키 인증 — 프로브가 실제 BatchMode `ssh ... true`를 실행 |
| `docker` | 로컬 또는 원격 docker 데몬 — `docker exec`는 모든 제어 경로와 동등 | `docker version` 정상; 선택적 `KUNGLAO_DOCKER_CONTAINER` |
| `adb` | Android 에뮬레이터 또는 실제 디바이스 | `adb devices`에 표시됨; frida용 `adb forward tcp:1337 tcp:1337` |
| `local` | **호스트에서 정적 전용 분석** | 없음 — 빨간 선 참조 |

> **`local` 빨간 선:** local은 **정적** 작업 전용입니다 — 호스트에서 샘플을 절대 실행, 디버그, 주입하지 마세요. 동적 요구 사항이 있으면 `KUNGLAO_CHANNEL`을 `vmr`/`ssh`/`docker`/`adb`로 전환하세요. init은 `local`에서 동적 작업을 HARD 거부합니다.

채널 프로브는 동적 작업에만 실행됩니다(정적 전용 작업은 건너뜀). `ssh` 채널 실행은 **ssh-mcp** 컨트롤 플레인(`npm i -g ssh-mcp`)을 통해 흐릅니다. 일반 CLI ssh가 폴백입니다. ssh를 통한 원격 docker의 경우 `KUNGLAO_DOCKER_CONTAINER`를 설정하세요.

## 구성

네 개의 변수가 대부분의 설정을 커버합니다:

| Variable | Default | Meaning |
|---|---|---|
| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | unset | 설정하지 않거나 `0`으로 유지해야 함 — truthy 값은 디스패치를 teammate 채널로 라우팅하며 거부됨 |
| `KUNGLAO_CHANNEL` | `vmr` | 동적 실행 컨트롤 플레인: `vmr` \| `ssh` \| `docker` \| `adb` \| `local` — [자체 환경 가져오기](#bring-your-own-environment) 참조 |
| `KUNGLAO_VM_HOST` | unset | 동적 분석용 VM/호스트 (vmr-shell :9876, Frida :1337) |
| `GHIDRA_HOME` | unset | Ghidra 설치 루트 (`support/analyzeHeadless.bat` 포함해야 함) |

드물게 필요: `KUNGLAO_DOCKER_CONTAINER` (`ssh`/`docker` 채널의 docker 실행 타겟), `KUNGLAO_FRIDA_PORT` (기본 1337), `KUNGLAO_DIE` (DIE 경로, PATH로 폴백), `KUNGLAO_CLAUDE_JSON` (사용자 수준 MCP 레지스트리에 대한 테스트 오버라이드).

## 안전

- 샘플은 호스트에서 절대 실행되지 않습니다 — `block_malware_exec` 훅이 이를 강제합니다. 동적 작업은 VM/컨테이너/디바이스 전용으로 실행되며 세션별 권한 부여가 필요합니다.
- Ground truth 계층: 원시 아티팩트 > 로컬 도구 > 샌드박스 > 위협 인텔 (CTI는 반증 가능한 가설이며, 결코 진실이 아님).
- Maker-checker: 워커는 절대 자기 검증하지 않습니다. 검증자는 절대 maker의 결론을 읽지 않습니다.
- Bins, 설정, 훅은 절대 커밋되지 않습니다. 시크릿은 워크스페이스와 저장소에서 제외됩니다.

## 개발

기여를 환영합니다. 워크플로: `dev`에서 브랜치, 변경당 하나의 브랜치, `dev`로 PR.```bash
git worktree add .worktrees/<name> -b <name> dev
uv sync --locked
uv run python -m pytest -q
gh pr create --base dev

전체 스위트의 권위 있는 진입점은 python -m pytest -q입니다(.github/workflows/release-check.yml 참조).

설계 문서는 docs/와 specs/에 있습니다. License를 참조하세요.

내부 구조

MCP 공급(전체 매니페스트)

단일 진실 공급원: scripts/mcp_probe.py; kunglao-init은 워크스페이스 .mcp.json이 없을 때 스캐폴딩합니다(--no-mcp는 건너뜀; 기존 파일은 절대 덮어쓰지 않음). 프로브: python scripts/mcp_probe.py <ws> --type <windows|linux|android|web|macos> — 종료 코드 1 = HARD 누락, 2 = WARN 누락만 해당.

워크스페이스 레이아웃

샘플 참여당 하나의 워크스페이스:

``` / ├── 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 ``` kunglao 훅은 워크스페이스 수준에서 연결되며, 전역 `~/.claude/settings.json`은 절대 기록되지 않습니다.

라이선스

이중 라이선스: 개인, 학술 및 내부 사용에는 AGPL-3.0(무료 — LICENSE 참조); 클로즈드 소스 또는 SaaS 상업적 사용에는 상업용 라이선스가 필요합니다 — LICENSE-commercial.md 참조.

Claude Code	kunglao-agent가 실행되는 곳	Anthropic 문서 참조
Python 3.10+ (Python 2는 지원되지 않음)	플러그인이 `uv`를 통해 고정된 환경을 포함; 직접 건드릴 필요 없음	시스템 또는 `uv` 관리
`uv`	잠긴 환경 리졸버	`pip install uv` 또는 astral.sh/uv
Ghidra 또는 IDA	디컴파일을 위한 하나의 정적 분석 제품군	대상별 툴체인 참조

완료되었는가?	루프의 종료 코드 — `CONVERGED` (0)는 모든 주요 질문에 검증된 답변이 있음을 의미하며, 클레임별 상태는 `claim-register.yaml`에 있다
무엇을 발견했는가?	`facts/F<NNN>.md` — 파일당 하나의 바이트 고정 팩트로, `claim-register.yaml`에 의해 클레임에 매핑된다
어떻게 재현하는가?	`evidence/_index.json` — 팩트 → 원시 아티팩트 (경로 + sha256); 각 팩트는 `reproduce:` 명령을 포함한다
정확히 무슨 일이 있었는가?	`runs/` — 틱별 원장과 작업자 상태

`ghidra`	HARD	필수, 모든 유형	디컴파일 / 정적 분석	`claude mcp add ghidra -- <path>/bridge-mcp-ghidra.exe`
`sequential-thinking`	HARD	필수, 모든 유형	구조화된 추론	`claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking`
`x64dbg`	HARD	Windows T3 동적	동적 디버깅(VM 원격)	`claude mcp add x64dbg -- x64dbg-automate-mcp`
`volatility`	WARN	Windows T3	메모리 포렌식	`claude mcp add volatility -- python <path>/volatility_mcp_server.py`
`ida-pro-vm`	WARN	IDA 선택 시	원격 IDA 분석	`claude mcp add --transport http ida-pro-vm <ida-mcp-url>`
`gitnexus`	HARD	Android 그래프 구축	디컴파일 후 지식 그래프	`claude mcp add gitnexus -- gitnexus mcp`
`virustotal`	WARN	CTI	위협 인텔리전스(패밀리 귀속 가설)	`claude mcp add virustotal -- npx -y @burtthecoder/mcp-virustotal`
`ssh-mcp`	WARN	채널	ssh 실행 제어 플레인	`claude mcp add ssh-mcp -- ssh-mcp`
`camoufox-reverse`	WARN	웹(베타)	브라우저 JS 리버싱(훅 / 트레이스 / 네트워크 캡처)	`claude mcp add camoufox-reverse -- python -m camoufox_reverse_mcp`

인기

kunglao-agent

kunglao-agent

kunglao-agent를 사용하는 이유

빠른 시작

1. 플러그인 설치

3. 작업을 명시하고 분석을 시작하세요```

작업을 명시하는 방법

"我要纯算" — "순수 알고리즘만"

"这个 sign 在哪算的" — "이 sign은 어디에서 계산되는가?"

시나리오

얻을 수 있는 것

내부 구조

라이선스