diff --git a/devlog/_plan/260913_logic_analysis_skill/000_plan.md b/devlog/_plan/260913_logic_analysis_skill/000_plan.md new file mode 100644 index 00000000..b41ae728 --- /dev/null +++ b/devlog/_plan/260913_logic_analysis_skill/000_plan.md @@ -0,0 +1,84 @@ +# 260913 Logic-analysis skill unit — roadmap + +## Objective + +Distill a **logic-analysis methodology** (로직 파악 — understanding how a system +works, as opposed to fixing a defect) from three reverse-engineering learning +repos and integrate it into one existing codexclaw skill, then ship it through +the dev → main release pipeline. + +The failure this unit closes: agents asked "figure out how this app / AI tool / +undocumented API works" too often answer "I can't" or skim the surface. Classic +reverse-engineering pedagogy is exactly the discipline of comprehending an +unknown system from observation, but its presentation (assembly, debuggers, +GUI tools) does not transfer to an agent context. This unit translates the +*method*, not the tooling. + +Host goal: `distill-logic-analysis-methodology-from-re-learn`, session +`0d7e3cc3-8bdf-4645-8cf6-a7d42a2fb2ab`. This unit is the docs-only pass required +by LOOP-DOCS-FIRST-01; its D locks the work-phase map below. + +## Source material (measured, this session) + +Shallow clones at `/tmp`, verified present this session: + +| Clone | Upstream | Stars | Shape | +|---|---|---|---| +| `/tmp/re-mytechnotalent` | mytechnotalent/Reverse-Engineering | 14.3k | Per-lesson tutorial folders, x86/x64/ARM/AVR/RISC-V, 424 files | +| `/tmp/re-wtsxdev` | wtsxDev/reverse-engineering | 10.4k | Awesome-list README taxonomy, 34 files | +| `/tmp/re-z0f` | 0xZ0F/Z0FCourse_ReverseEngineering | 5.9k | Chapter course (1-8), Lingo/FAQ, 242 files | + +Three parallel explorer subagents (grok-4.6) each mine one clone for: +methodology principles with `path:line` evidence, agent-translatable +techniques, anti-give-up patterns, and content that must NOT be generalized. +Raw synthesis lands in `001_analysis_synthesis.md`. + +## Target-skill decision (audit result) + +Candidates audited against the request surface ("understand how X works", +not "fix X"): + +| Candidate | Fit | Verdict | +|---|---|---| +| `dev-debugging` | Owns systematic investigation of unknown behavior (Phase 1 trace/instrument, Phase 3 hypothesis discipline). Its boundary statement scopes it to *defects*; logic analysis is the same epistemics aimed at *comprehension*. 414/500 lines — headroom for a compact routing section. | **CHOSEN** — add `references/logic-analysis.md` + routing section + trigger metadata | +| `search` | Owns external/public-web evidence. Logic analysis is primarily *local observation* of a target system; search is one rung, not the owner. | Rejected — cross-link only | +| `qa` | Owns driving user-facing surfaces for verification. Overlaps on black-box probing but its gate is release verification, not comprehension. | Rejected — cross-link only | +| New skill | User explicitly prefers extending an existing skill; dev-debugging's Phase 1/3 machinery is 80% of the method. | Rejected unless A-phase audit finds a boundary collision | + +Boundary rule for the edit: dev-debugging keeps defect RCA as its core; the new +reference is routed to when the request is **comprehension without a defect** +("how does X work", "뜯어봐", "로직 파악", "reverse-engineer this flow"). + +## Constraints + +- Skill text English; SKILL.md ≤ 500 lines; bulk content in `references/` + (workspace AGENTS.md §2/§8). +- Commit format `[agent] {type}: {description}`; work stays on `dev`. +- Push + dev→main merge + release are explicitly user-authorized for this goal. +- No component/hook code changes; docs/skill content only. +- No new dependencies. No destructive git operations. + +## Work-phase map + +| WP | Title | Decade docs | Depends on | +|---|---|---|---| +| wp0-roadmap | This docs-only pass: parallel analysis, target decision, locked roadmap | `000_`, `001_` | — | +| wp1-skill-content | Integrate methodology into `dev-debugging` + validate (gate/tests) | `010_` | wp0-roadmap | +| wp2-release | Push dev, PR + merge dev→main, confirm release deploy | `020_` | wp1-skill-content | + +## Acceptance criteria (goalplan c-1..c-4) + +1. Analysis notes for all three clones under this unit dir with repo + `path:line` evidence. +2. Target skill chosen with rationale (this section); methodology integrated; + SKILL.md ≤ 500 lines; English. +3. Fresh validation output (repo gate / relevant tests) passes after the edit. +4. dev pushed; dev→main PR merged; release/deploy outcome confirmed with link + or CI status. + +## Resource bounds (HOTL) + +Write scope: this repo on `dev` + `/tmp` clones. Tools: shell, gh, explorer +subagents (analysis only). No credential/settings changes. Wall-clock: this +session. Subagent budget: the three dispatched explorers + at most one +reviewer in wp1 A-phase. diff --git a/devlog/_plan/260913_logic_analysis_skill/001_analysis_synthesis.md b/devlog/_plan/260913_logic_analysis_skill/001_analysis_synthesis.md new file mode 100644 index 00000000..dca911d7 --- /dev/null +++ b/devlog/_plan/260913_logic_analysis_skill/001_analysis_synthesis.md @@ -0,0 +1,355 @@ +# 001 — RE repo analysis synthesis + +Raw material from three parallel explorer subagents (grok-4.6), one per clone. +Each section is the agent's verified return, kept with its `path:line` citations +into the `/tmp` clones. The distilled skill content lives in `010_wp1_skill_content.md`; +this file is evidence, not the deliverable. + +--- + +## A. wtsxDev/reverse-engineering (awesome list) — agent d866486b + +**Shape:** `README.md` + remark-lint `package.json` only. 16-section taxonomy +(`README.md:6`–`README.md:21`): Books, Courses, Practice, Hex Editors, Binary +Format, Disassemblers, Binary Analysis, Bytecode Analysis, Import Reconstruction, +Dynamic Analysis, Debugging, Mac Decrypt, Document Analysis, Scripting, Android, +Yara. No first-class "decompiler", "network analysis", or "dynamic +instrumentation" heading. + +### Technique taxonomy → routing table (target → family → tools) + +| Target / question | Family | Tools | Cite | +|---|---|---|---| +| Learn RE from scratch | Books | IDA Pro Book; RE for Beginners; Practical RE; Practical Malware Analysis; Windows Internals | `README.md:25`–`47` | +| Structured course | Courses | Open Security Training; Modern Binary Exploitation; RPISEC Malware; SANS FOR610 | `README.md:49`–`66` | +| Crackme/CTF practice | Practice | Crackmes.de; Flare-on; challenges.re (malware corpora carry explicit warning) | `README.md:68`–`85` | +| Raw bytes / patched constants | Hex Editors | HxD; 010; HexFiend; Hiew; hecate (terminal) | `README.md:87`–`96` | +| "What IS this file?" headers/packer/symbols | Binary Format | CFF; Detect It Easy; PeStudio; MachoView; `file`/`nm`/`codesign` | `README.md:98`–`110` | +| Machine code → asm/CFG | Disassemblers | IDA; GHIDRA; Binary Ninja; Radare; Hopper; Capstone; `objdump` | `README.md:112`–`123` | +| Automated reasoning / symbolic exec | Binary Analysis | z3; bap; angr | `README.md:125`–`132` | +| Managed bytecode → source-like | Bytecode Analysis | dnSpy; Bytecode Viewer; JPEXS | `README.md:134`–`141` | +| Packed PE import table | Import Reconstruction | ImpRec; Scylla; LordPE | `README.md:143`–`149` | +| Live host behavior | Dynamic (host) | Process Hacker/Explorer/Monitor; Autoruns; Noriben; API Monitor; Instruments | `README.md:151`–`161` | +| Live network of a sample | Dynamic (network) | iNetSim; SmartSniff; TCPView; Wireshark; Fakenet | `README.md:162`–`165` | +| Memory image | Dynamic (memory) | Volatility; Dumpit; LiME | `README.md:166`–`168` | +| Detonate + behavioral report | Dynamic (sandbox) | Cuckoo | `README.md:169` | +| POSIX/macOS syscall/FS trace | Dynamic (OS trace) | `dtrace`/`dtruss`; `fs_usage`; `dmesg` | `README.md:172`–`174` | +| Step/breakpoint/emulate | Debugging | WinDbg; OllyDbg; x64dbg; gdb; lldb; qira; unicorn | `README.md:176`–`192` | +| Encrypted macOS/iOS binary | Mac Decrypt | class-dump `-deprotect`; readmem | `README.md:194`–`201` | +| Hostile Office/PDF | Document Analysis | oletools; Didier Stevens PDF tools; Origami | `README.md:203`–`209` | +| Automate IDA / parse PE | Scripting | IDAPython; IDC; `pefile` | `README.md:211`–`222` | +| Android APK | Android | apktool; dex2jar; JaDx | `README.md:224`–`233` | +| Pattern-hunt samples | Yara | Yara; yarGen | `README.md:235`–`242` | + +### Agent-accessible subset (shell + browser + editor only) + +Driveable CLI slice: `file`/`nm`/`codesign` (`README.md:108`–`110`); `objdump`/ +Radare/Capstone (`README.md:119`–`122`); z3/bap/angr (`README.md:130`–`132`); +gdb/lldb/unicorn (`README.md:188`–`192`); `dtrace`/`fs_usage`/`dmesg` +(`README.md:172`–`174`); Volatility on existing dumps (`README.md:166`); +oletools/PDF tools (`README.md:207`–`209`); `pefile` (`README.md:222`); +apktool/dex2jar/JaDx (`README.md:229`–`233`); Yara (`README.md:239`–`241`); +hecate (`README.md:96`); class-dump/readmem (`README.md:200`–`201`). + +GUI/lab-bound (never pretend available): IDA/GHIDRA/Binary Ninja/Hopper GUIs +(`README.md:116`–`120`); Sysinternals suite + API Monitor (`README.md:155`–`160`); +Wireshark/SmartSniff/TCPView (`README.md:163`–`164`); Cuckoo (`README.md:169`); +WinDbg/Olly/x64dbg (`README.md:180`–`187`); IDAPython track (`README.md:215`–`221`). + +Agent-native stand-ins the list does NOT name: `strings`/`grep`/`readelf`, +HTTP capture via `curl`/mitmproxy/`tcpdump`, added logging, black-box API +probing — the usual "how does X work" tools; this README is a binary-malware +map, not an application-logic map. + +### Learning-path resources (signal-ranked) + +1. RE for Beginners (free) `README.md:31` +2. Radare2 Book (CLI-native) `README.md:30` +3. Open Security Training `README.md:54` +4. Modern Binary Exploitation (RPI) `README.md:59` +5. RPISEC Malware Course `README.md:60` +6. Practical Reverse Engineering `README.md:33` +7. Practical Malware Analysis `README.md:35` +8. Reversing: Secrets of RE `README.md:34` +9. The IDA Pro Book `README.md:29` +10. Offensive/Defensive Android Reversing (DEF CON PDF) `README.md:66` + +### Gaps (what the list assumes an agent lacks) + +1. Human at a RE workstation (GUI products throughout). +2. Local binary/sample access — no SaaS/closed-API/production-service category. +3. Permission to run hostile code (`README.md:70`, `79`–`85`, `155`–`169`). +4. Windows malware lab (and often Mac lab). +5. IDA as the automation bus. +6. **No source-available lane** — reading source/symbols/logs/tests/docs never + listed (`README.md:7`–`21`), yet it is an agent's FIRST method. +7. **No web/JS/protocol-RE family** — network = fake-Internet + sniffing for + malware, not HTTP API mapping / source maps / DevTools. +8. No named dynamic-instrumentation family (no Frida/Pin/DynamoRIO; closest + API Monitor `README.md:160`, `dtrace` `README.md:172`). +9. Decompilation not first-class. +10. Books often paid; prefer beginners.re/radare book/OST/RPISEC. +11. Sandbox/memory work needs lab VMs. +12. Yara answers "have I seen this?" not "how does the logic work?" + +**Routing rule (agent):** local native/APK/Office artifact + structure/decompile +question → CLI slice (format → `objdump`/r2 → jadx/oletools → angr/gdb). Live +Windows malware behavior → human GUI lab; answer honestly, not "I can't". + +--- + +## B. mytechnotalent/Reverse-Engineering — agent 02680c08 + +**Shape correction:** not per-lesson markdown — `README.md` is a 527+ lesson +catalog; lesson bodies live in bundled PDFs. Local code is a thin Windows +x86/x64 sample set. The transferable method is a repeated loop: +**smallest runnable surface → observe live state → change one thing → +re-observe** ("Program → Debug → Hack" triad, `README.md:253`–`264`). + +### 14 methodology principles (each with repo evidence) + +1. **Pair a dead listing with a live run** — static vs dynamic split + (`README.md:153`, `1196`, `1201`). +2. **Start from the smallest runnable surface** — every architecture opens on + Hello World (`README.md:253`, `546`, `993`, `1092`, `1191`; + `0x0001-hello_world-x86/main.asm:13`). +3. **Program → Debug → Hack triad per primitive** — produce it, watch the + state, mutate one value/branch, confirm (`README.md:253`–`264`, cloned + across ARM/x64/Pico/Windows/RISC-V; "hack" = controlled mutation to test a + causal hypothesis). +4. **Follow one value through every store** — immediate → register → memory → + output (`README.md:253`–`313`; `0x0013-readfile/main.c:8`–`64`). +5. **Treat public interfaces as contracts** — annotate the visible boundary + from official docs/datasheet before guessing internals + (`0x0001-hello_world-x86/main.asm:14`–`20`; `README.md:804`, `1625`). +6. **Observable side effects are ground truth** — success/fail prints, bytes + on disk, stdout (`0x0006-directories/main.c:8`–`14`; `README.md:998`). +7. **Compare two encodings of the same behavior** — x86 vs x64 twins, C vs asm + blink (`README.md:1196`–`1237`, `1844`/`1849`, `2032` vs `2186`). +8. **Mutate one control-flow decision, re-run** — invert one predicate, watch + which path fires (`README.md:969`, `1008`–`1018`, `1750`–`1775`). +9. **Inspect the artifact, not only the source story** — on-disk ≠ mapped; + strings/ELF first, then live attach (`README.md:183`, `238`, `934`, + `998`, `1571`). +10. **Walk initialization in dependency order** — Reset_Handler line-by-line, + "why order matters" (`README.md:2032`, `2061`, `2196`). +11. **Probe through input — the cheapest experiment** — map validation/error + strings/success paths without a debugger (`README.md:1008`–`1018`, + `1167`–`1182`). +12. **Decompose into independently testable stages** — four build stages, one + API per chapter (`README.md:2012`, `2355`, `2047`–`2057`, `1216`–`1316`). +13. **Drop one abstraction layer when stuck** (or go one up) — C→asm, + docs→bytes, SDK→MMIO (`README.md:238`, `551`, `934`, `1844`/`1849`, + `2151`). +14. **Analyze line-by-line / function-by-function** — never "the binary" + (`README.md:2839`, `2847`, `2022`, `1097`, `934`). + +### Agent-translatable techniques (closed app / undocumented HTTP API / unfamiliar OSS) + +- Static+dynamic both before concluding "can't see inside": strings/imports/ + configs + one happy-path run recording UI text/logs/files/HTTP. +- Smallest surface: one menu item / `GET /` only / `examples/`+`main()`. +- Triad for APIs: known-good request → record response → flip ONE field and + table the delta ("hack the validation", `README.md:1018`). +- Follow one value: inject a unique canary (req-id, filename) and watch which + response fields echo it (`0x0013-readfile/main.c:8`,`64`). +- Contracts: write a request/response schema from samples like reading a + datasheet first (`README.md:1625`). +- Ground truth: status code + dependent second request; tests/logs/real run + beat comments (`README.md:2061`). +- Two encodings: GUI vs CLI vs mobile; SDK vs raw HTTP vs second client. +- One-branch mutation: omit auth / wrong content-type / empty array → map + error strings (`README.md:1013`). +- Artifact vs story: saved OpenAPI vs actual traffic — clients lie, HAR doesn't. +- Init order: CSRF cookie → login → token → resource; never start at the + resource. +- Probe through input as *mapping*, not attack: table status × body. +- Stages: auth, pagination, create, get, delete — separately. +- Drop a layer: SDK method → raw HTTP → TLS SNI; docs → source → generated + code → bytes. +- One route's full error matrix before the next route. + +### 11 anti-give-up patterns + +1. Next lesson is never "you're done" — program→debug→hack structure forbids + stopping at "I read it" (`README.md:253`–`264`, `417`–`472`). +2. Shrink the example until a technique is visible (`README.md:551`). +3. Hypothesis + falsifying check ("verify our hypothesis", `README.md:998`). +4. Confused → regress one layer, never invent (`README.md:934`, `551`). +5. Re-run the same observation after mutation (`README.md:939`, `964`, `969`). +6. One failed probe ≠ impossible — try a second breakpoint/hack + (`README.md:571`). +7. Homework pattern: method transfers to the next slot (`README.md:964`). +8. **Missing docs/source is a starting condition, not a stop condition** + (`README.md:551`, `238`). +9. Overwhelm is a chunking problem — "break it down" (`README.md:934`, + `1097`, `1013`). +10. Budget a troubleshooting pass; first bring-up is expected to fail + (`README.md:2216`, `2370`, `2832`). +11. ANY program is in scope once the tools exist (`README.md:253`). + +### Leave out + +ISA furniture (registers/encodings), debugger keystroke recipes, boot-media/ +chip bring-up trivia, malware taxonomy as a goal, tool installers, +electronics, STUXNET narratives, ASLR/opcode tables (keep only "runtime +addresses move" + "on-disk ≠ mapped"), capstone door-hack scenario. + +**Bottom line:** smallest observable → static artifact + one live run → +follow one value/contract → change one input or branch → re-check a side +effect → drop a layer or shrink the example if stuck. + +--- + +## C. 0xZ0F/Z0FCourse_ReverseEngineering — agent cd728d53 + +**Shape:** no single numbered checklist; the process is *demonstrated* across +Chapters 4–8. Theory transfers off Windows, tools/ABI do not (`README.md:3`, +`@BeforeYouBegin.md:11`). `Lingo.md` is 24 lines and does NOT define +static/dynamic analysis — those live in `Chapter 4 - Tools/4.1 ToolTypes.md:42-45`. + +### The 13-step RE process (demonstrated, cited) + +1. **State the goal, isolate the target** — "If we want to use the DLL, we + will need to know how it works" (`Chapter 6 - DLL/6.01 BeforeWeBegin.md:5`); + VM to observe "network traffic, disk usage, registry modifications" and + revert (`Chapter 1 - Introduction/1.2 Setup.md:16`); tools interchangeable, + method isn't (`1.2 Setup.md:11`, `Chapter 4 - Tools/4.0 Tools.md:3`). +2. **Don't start grinding the lowest representation** — goal is not "smash + your head against assembly"; use tools, log calls, write own code + (`README.md:34`); advanced skill comes from experience (`README.md:3`). +3. **Acquire just enough domain language first** — host language/ABI before + reversing (`Chapter 1 - Introduction/1.0 Introduction.md:18-21`, + `Chapter 5 - BasicReversing/5.1 BeforeWeBegin.md:7`); learn the + data-structure topic first or be "very confused" + (`Chapter 8 - Generic Table/8.04 GetElement.md:51`). +4. **Inventory the public surface before internals** — "we don't care too much + about what's going on internally. What we care about is what exported + functions are available, what do they do, what do we need to call them" + (`Chapter 6 - DLL/6.03 Exports.md:3`, `6.03:7`, + `Chapter 4 - Tools/4.1 ToolTypes.md:38`). +5. **Don't reverse the whole system** — slice to a function family, pick + "semi-documented (so we can check our work)" + (`Chapter 8 - Generic Table/8.00 GenericTable.md:3`); order = whatever + yields information (`8.04 GetElement.md:3`). +6. **Start from names/strings/known artifacts; find the real entry** — string + refs when symbols missing (`Chapter 5 - BasicReversing/5.3 + HelloWorld.md:36`); entry ≠ `main()` (`5.3:24-26`); guess type from name, + start at initialization which "will hint at what a table contains" + (`Chapter 8 - Generic Table/8.01 InitializeTable.md:3-5`); simple functions + first (`8.02 NumberGenericTableElements.md:3`). +7. **Skim for general idea, hypothesize BEFORE deep dive** — (`Chapter 6 - + DLL/6.04 SayHello.md:3`, `6.06 InitializePlayer.md:87`, `8.02:5`, + `8.04:55`). +8. **Read statically, treat reconstructions as guesses** — disassembly is "the + backbone" (`4.1 ToolTypes.md:13`); "never trust decompiler data types" + (`4.1:23`); metadata lies: `__cdecl` label, fastcall body (`Chapter 6 - + DLL/6.05 PrintArray.md:21-33`); "we wouldn't actually know for sure" + (`5.3:50`). +9. **Ignore scaffolding; keep the big picture** — skip security cookies, + prologues, instruction variants (`5.3:27-28`, `5.3:62`, `5.2 + FunctionCall.md:8`, `6.07 PrintPlayerStats.md:11`); "focus on the bigger + picture" (`8.01:3`, `6.05:17`). +10. **Write notes/labels/incremental model with UNKNOWN fields** — rename + found functions (`5.3:52`); "write comments and take notes" + (`6.06:256`); pseudo-code while reversing (`8.04:64`); `UNKNOWN`/ + `UNKNOWN_PTR` layout updated as evidence arrives (`8.01:89-101`, + `8.02:16-32`). +11. **Test hypotheses with observation, comparison, numbers** — side-effect + breakpoint test ("extremely likely we are correct", `5.3:123`); + comparison programs + graph diff (`6.04:22`, `5.3:125`); escalation + ladder: multiple tools → execute and watch → fully reverse (`5.3:64`); + plug test values (`8.04:133`); static provably insufficient for some + questions — class vs array needed dynamic (`Chapter 6 - DLL/6.08 + MysteryFunc.md:112`). +12. **Keep an open mind; update on contradiction** — (`8.01:38`, `8.01:58`, + `8.02:16`, `8.04:201`). +13. **Close the loop by USING the reconstructed interface** — reverse the DLL + AND "write a program that can use it" (`6.01:5`, `6.00 DLL.md:3`); + "Hello! printed as we guessed" (`6.04:84`); "We nailed it!" vs source + (`6.06:252`). Black-box → white-box. + +### Mindset rules + +- Computers don't assume; don't invert the spec ("even→red" ≠ "red→even"; + unspecified = anything) (`Chapter 2 - BinaryBasics/2.6 Mindset.md:3`, + `18-24`). +- Opaque blobs become intelligible with the template: "Protocols are simply + templates" (`2.6:28-37`); delimiters exist because computers are literal + (`2.6:39`). +- Prefer the stupid-simple mechanism (compare = subtract, `2.6:43`). +- Confusion is normal; persistence is the method (`5.1 BeforeWeBegin.md:9`, + `6.06:256`, `8.04:486`). +- No dumb questions; silent failure is the dumb move (`5.1:11`, `Chapter 6 - + DLL/6.10 FinalNotes.md:3`). +- **You don't need to understand everything on screen** (`Chapter 4 - + Tools/4.3 ToolGuides.md:82-83`, `5.2:8`, `5.3:68`, `Chapter 7 - + Windows/7.4 API.md:18`). +- Don't trust names/decorations/decompilers as ground truth (`6.05:21`, + `4.1:23`). +- Tools beat brute-force reading (`README.md:34`, `4.1:40`). +- Puzzle from fragments, not a linear read (`6.05:100`, `6.08:114`). +- Write your own programs and reverse them (`5.3:163`, `6.10:3`). +- Look things up; unknown instructions are normal (`Chapter 8 - Generic + Table/8.03 IsGenericTableEmpty.md:20`, `Chapter 3 - Assembly/3.6 + FinalNotes.md:7`). +- Difficulty expected; needless difficulty isn't (`README.md:40`). "I can't + analyze this" usually = refusing the loop, not hitting a real stop. + +### Observation toolkit → agent equivalents (selected) + +- Static = on-disk, not running (`4.1:44`) → docs/headers/OpenAPI/source/ + `strings`/`file`/`nm`; reading a library you never invoke is still static. +- Dynamic = running in memory (`4.1:45`) → run the CLI/server, `curl`, watch. +- Decompiler = untrusted hint (`4.1:23`) → LLM/type-inference reconstructions + are sketches, not evidence. +- Surface utilities (DUMPBIN exports, `4.1:38`, `6.03:7`) → `curl -I`, + OpenAPI, `npm ls`, `--help`, HAR entry points. +- String/reference search (`5.3:36`) → grep error strings/log lines to find + emitters. +- Breakpoint = controlled observation (`4.2 Debugging.md:5`) → log line before + the call, proxy breakpoint on one route. +- Step into/over/out (`4.2:11-13`) → read handler vs one `curl` black-box vs + return to caller. +- Log calls / own logger (`README.md:34`) → verbose flags, HTTP proxy, + wrapper SDK, request-id logs, `strace`/`dtruss`. +- Trace then analyze offline (`4.3:34`) → capture HAR/pcap once, reason on + the recording. +- Graph/CF compare (`6.04:22-32`, `5.3:125`) → diff two traces/SDK versions/ + minimal repro vs unknown. +- Harness/loader to invoke the surface (`6.01:13-19`, `6.04:96-107`) → + minimal client/fixture/REPL that actually calls the API. +- Plug numbers / walk paths (`8.04:133`, `220-226`) → table-driven inputs + forcing each branch. +- Notes/labels (`4.3:22`, `5.3:52`) → rename "endpoint X" as you learn. +- Environment observers (`1.2:27`, `1.2:16`) → `strace`, `lsof`, mitmproxy, + fs watch. +- Xrefs / find callers (`5.3:129`) → who calls this function / hits this + route. + +Black-box → white-box: observe outputs → guess types/layout → write a client → +refine dynamically when static can't distinguish (`5.3:123`, `8.01:89-101`, +`6.04:84`, `6.08:112`). + +### Vocabulary (real terms live in Ch.4, not Lingo) + +Lingo: WIP/TODO (don't freeze models on stubs), x64 vs x86 (ABI/pointer +size/tools differ), JRE/JVM/CLR/JIT/MSIL/IL (static view ≠ executed stream). +Teach from Ch.4: **static analysis** (`4.1:44`), **dynamic analysis** +(`4.1:45`), **breakpoint** (`4.2:5`), **import/export** (`Chapter 6 - +DLL/6.02 DLLBasics.md:12-15`), **entry point** (`5.3:26`), **calling +convention** (`Chapter 3 - Assembly/3.5 CallingConventions.md:3`). + +### Leave out + +Windows/x64 lock-in (`README.md:3`, `@BeforeYouBegin.md:11`), fastcall/shadow +space/XMM lanes, MSVC mangling/decorations, specific tools (x64dbg/Ghidra/ +DUMPBIN...), Intel syntax/PE loaders/WOW64, CRT noise, WinAPI A/W/Ex naming, +NTDLL Generic Table internals, endianness trivia, "avoid the documentation" +pedagogy (`8.00:5` — agents SHOULD use docs; the transferable move is checking +against an independent oracle), malware-lab/exploit content. + +**Transferable core:** isolate → inventory the callable surface → hypothesize +from names/strings/errors → observe with breakpoint-or-log + comparison +harness → keep UNKNOWN fields → update when contradicted → prove the model by +calling it. diff --git a/devlog/_plan/260913_logic_analysis_skill/010_wp1_skill_content.md b/devlog/_plan/260913_logic_analysis_skill/010_wp1_skill_content.md new file mode 100644 index 00000000..b45a28cb --- /dev/null +++ b/devlog/_plan/260913_logic_analysis_skill/010_wp1_skill_content.md @@ -0,0 +1,229 @@ +# 010 — wp1: logic-analysis content in dev-debugging + +Diff-level build doc for work-phase wp1-skill-content. Two files touched, both +under `plugins/codexclaw/skills/dev-debugging/`. No code, no tests touched; +validation is the repo gate + skill-shape checks (§Verification). + +## Decision recap (from 000_plan.md, audited in wp0) + +Target: `dev-debugging`. The request surface is **comprehension without a +defect** ("how does this app/AI-tool/API work", 로직 파악, 뜯어보기). That is +the same epistemics as Phase 1/3 (trace, instrument, hypothesize, falsify) +aimed at understanding instead of repair. `search` owns external evidence, +`qa` owns release verification — both get cross-links, neither owns this. + +--- + +## File 1 (NEW): `plugins/codexclaw/skills/dev-debugging/references/logic-analysis.md` + +Full content: + +```markdown +# Logic Analysis — Comprehending an Unknown System + +Read this when the task is to understand how a system works — a closed-source +app, an AI tool, an undocumented API, a protocol, an unfamiliar codebase — +and no defect is being fixed. Defects use the phases 0-4 method in +`../SKILL.md`; this reference is the same discipline aimed at comprehension. + +Distilled from three reverse-engineering courses (mytechnotalent +Reverse-Engineering, wtsxDev reverse-engineering list, Z0FCourse) — analysis +with citations: `devlog/_plan/260913_logic_analysis_skill/001_analysis_synthesis.md`. + +## The core rule + +**"I can't analyze this" is a skipped loop, not a limit.** Missing source, +missing docs, and no debugger are *starting conditions*, not stop conditions +— professional reverse engineers begin from exactly there. Refusal is correct +only at the honest-limits boundary (§Honest limits). Everything short of that +is a routing problem: pick the technique family that fits the target and run +the loop. + +## The Logic-Analysis Loop + +1. **State the question precisely.** "How does X work" is not a question; + "which endpoint charges the card, and what fields does it need" is. Decide + what "understood" means — usually: you can predict or reproduce a behavior. +2. **Isolate the target.** Work in a sandbox/VM/copy where you can observe + side effects (files, network, processes, DB rows) and revert mistakes. +3. **Acquire just enough domain language.** Learn the host vocabulary (ABI, + data structure, protocol family) before reading deeply — otherwise every + observation is unreadable. Do not front-load more than the next step needs. +4. **Inventory the public surface before internals.** Exports, routes, + commands, config keys, UI actions — what is callable, what does each entry + promise, what does calling it need? For a library you care about the + exported functions first, not the internals. +5. **Slice; don't reverse the whole system.** Pick one function family, one + route, one dialog. Prefer a semi-documented slice so you can check your + work against an independent oracle. Simple functions first — they teach + the conventions the hard ones use. +6. **Hypothesize from names, strings, and errors before the deep dive.** + Skim for the general idea, then write a guess: "a Generic Table is + probably a data structure; initialization will hint at its fields." + Treat every reconstruction — including decompiler/LLM output and metadata + labels — as a guess until observed evidence confirms it. Names lie. +7. **Observe: static AND dynamic.** Static: read the artifact as it sits + (source, strings, headers, bundles, OpenAPI leftovers). Dynamic: run the + smallest thing and watch (logs, proxy, `strace`/`dtruss`, added print + statements, one `curl`). A static-only conclusion is a hypothesis; some + questions are provably undecidable statically. +8. **Prove the model by using it.** Write the harness: a minimal client, a + REPL call, a test that invokes the interface you think you understood. + The loop closes when your client works — black-box observation has become + a white-box model. Then re-verify after any mutation. + +Run the loop per slice. Overwhelm is a chunking problem: break it down, name +one function/block/field, finish it, then the next. + +## Controlled mutation (the "hack" step) + +To learn a rule, change exactly one variable and re-observe: + +- Flip one input field, one flag, one predicate — never five at once. +- Table the delta: status × body × side effect. Error strings are schema. +- Probe through input — it is the cheapest experiment: boundary values and + wrong types map validation without any internals access. This is mapping, + not attacking: stay within authorization (§Honest limits). +- Inject a unique canary (request id, filename, email) and watch which + outputs echo it — that traces the data path with zero instrumentation. +- Compare two encodings of the same behavior (GUI vs CLI, SDK vs raw HTTP, + x86 vs x64 build): the diff isolates what is essential from what is + incidental. + +## The incremental model + +Keep written notes as you go — a running document, not memory: + +- Maintain the reconstructed schema/struct/state machine with explicit + `UNKNOWN` fields; fill them as evidence arrives. +- Rename things as you learn them ("endpoint X" → "createCharge"); never + keep raw hashes in your head. +- Record rejected hypotheses and what rejected them — the final explanation + must include the dead ends. +- Until contradicted, prefer the stupid-simple mechanism; keep an open mind + and update the model the moment evidence contradicts it. + +## Technique routing table + +| Target | First moves | Agent-accessible tools | +|---|---|---| +| Unfamiliar open-source repo | README → entry point → one test/example run; trace one identifier end-to-end | grep/ast-grep, the repo's own tests, a 10-line harness | +| Undocumented HTTP API | Inventory via JS bundles/OpenAPI leftovers/`--help`; one known-good request; then one-field mutations | `curl`, browser devtools/HAR, mitmproxy, jq | +| Closed-source desktop/CLI app | Strings, config files, logs, `--help`, file/registry/network side effects of one action | `strings`, `file`, `fs_usage`/`dtruss`, process listing, a signed-in browser profile | +| Local binary artifact (structure) | Format identification → symbols/imports → disassembly slice | `file`, `nm`, `objdump`, `readelf`, radare2, capstone, `pexpect`-style runs | +| Managed bytecode / APK | Decompile to source-like form, then read | jadx, apktool, dex2jar, oletools (docs), `pefile` | +| Live behavior of a running system | Syscall/FS/network trace; capture once, analyze offline | `strace`/`dtruss`, `lsof`, tcpdump, HAR/pcap capture | +| Automated reasoning about a small function | Encode and solve | z3/angr (programmable, no GUI) | + +## Human-lab boundary (route honestly, never fake) + +These need a specialist workstation or lab — say so instead of claiming the +technique or claiming impossibility: IDA/Ghidra GUI workflows, Sysinternals/ +Procmon, Wireshark GUI analysis, Windows unpacker GUIs, Cuckoo-style malware +detonation, time-travel debuggers on a live target. The honest answer is +"this slice needs tool T on a lab machine; here is what I CAN establish from +here" — never "I can't", never a fabricated result. + +## Anti-give-up escalation ladder + +When stuck, climb — do not stop: + +1. Shrink the example until the technique is visible (Hello-World-sized). +2. Re-read the actual error/artifact — every line, not a skim. +3. Form a hypothesis and design the check that would falsify it. +4. Run the check; a failed probe is information, try the second probe. +5. Drop one abstraction layer (SDK → raw HTTP → bytes) or rise one + (bytes → strings → documented API). +6. Compare against a second implementation/version/encoding. +7. Capture a trace and analyze it offline instead of live. +8. Look it up — unknown instructions/fields are normal; external docs and + the `search` skill are part of the loop. +9. Only now, report the exact blocking observation, what a human with tool T + would do, and what is already established. + +## Honest limits + +- **Authorization**: analyze only systems you may analyze. Mapping input + validation of your own service is fine; probing third-party systems, + bypassing controls, or detonating malware is not in this skill's scope. +- **Hostile code**: never execute unknown binaries to observe them. Static + inspection only, or hand to a lab. +- **Decompiler/LLM reconstructions are sketches, not evidence** — confirm by + observation before claiming. +- Some truths are dynamic-only (representation chosen at runtime); some need + the lab tools above. Name which case you are in. + +## Vocabulary worth having + +static analysis (artifact at rest) · dynamic analysis (running system) · +breakpoint (controlled observation point — a log line counts) · +import/export (the callable surface) · entry point (where execution really +starts — not `main`) · calling convention (who owns which argument) · +canary (unique traceable input) · black-box → white-box (observe → model → +prove by using). +``` + +## File 2 (MODIFY): `plugins/codexclaw/skills/dev-debugging/SKILL.md` + +Current: 414 lines. After: ~436 (≤500 gate holds). + +### Edit A — frontmatter description + keywords + +Append to `description` before the closing quote: +`; logic analysis of unknown systems (how apps/APIs/AI tools work) via references/logic-analysis.md` +Append trigger tokens: `'how does X work', 'figure out how', '로직 파악', '뜯어봐', 'reverse engineer'`. +Append to `keywords`: `"logic analysis", "comprehension", "unknown system", "reverse engineering"`. + +### Edit B — boundary paragraph (anchor: the `**Boundary**` paragraph at SKILL.md:17-20) + +Append this literal sentence to the end of that paragraph (after +"consult `dev-backend` or `dev-frontend`."): + +``` +Comprehension without a defect — understanding how an unknown app, API, AI +tool, or codebase works — routes to `references/logic-analysis.md`. +``` + +### Edit C — new compact section, inserted before "## Red Flags" + +```markdown +--- + +## Logic Analysis (comprehension without a defect) + +When the request is to understand how a system works — closed app, AI tool, +undocumented API, unfamiliar codebase — rather than to fix a defect, read +[Logic analysis](references/logic-analysis.md). Core rules: "I can't" is a +skipped analysis loop, not a limit; missing source/docs is a starting +condition; hypothesize from names/strings/errors, observe static AND dynamic, +mutate one variable at a time, keep an incremental model with UNKNOWN fields, +and prove the model by writing a client that uses it. Honest lab-boundary +routing (IDA/Procmon/Cuckoo class) beats both refusal and fabrication. +``` + +### Edit D — references table row + +Add to the Modular References table: +`| references/logic-analysis.md | Understanding how an unknown system works (no defect) | Logic-analysis loop, controlled mutation, routing table, lab boundary, anti-give-up ladder |` + +### Edit E — Compact Summary + +Append: `(8) comprehension tasks route to references/logic-analysis.md — "I can't" is a skipped loop`. + +--- + +## Verification (C-phase of wp1) + +1. `wc -l` on SKILL.md ≤ 500. +2. `node plugins/codexclaw/scripts/gate.mjs` (repo gate) — fresh output, exit 0. +3. `npm test` if the gate does not cover skill shape; record the relevant + suite output (skill inventory tests exist under `plugins/codexclaw/test/`). +4. `cxc receipt test` for the C>D attest receipt. +5. Grep: new reference linked from SKILL.md; no dangling relative link. + +## Commits (B-phase of wp1) + +- `[agent] feat(dev-debugging): add logic-analysis reference for comprehending unknown systems` +- `[agent] docs(plan): wp0 roadmap + analysis synthesis for logic-analysis unit` + (or combined into the first if gate prefers; keep devlog separate per + one-logical-change rule) diff --git a/devlog/_plan/260913_logic_analysis_skill/020_wp2_release.md b/devlog/_plan/260913_logic_analysis_skill/020_wp2_release.md new file mode 100644 index 00000000..05917eda --- /dev/null +++ b/devlog/_plan/260913_logic_analysis_skill/020_wp2_release.md @@ -0,0 +1,42 @@ +# 020 — wp2: release pipeline (dev → main → deploy) + +Diff-level build doc for work-phase wp2-release. User explicitly authorized: +push to origin, dev→main merge, and deploy/release completion. + +## Preconditions + +- wp1 done: skill edit committed on `dev`, gate green, C>D closed. +- Working tree contains only this unit's changes plus pre-existing untracked + junk (do NOT touch unrelated untracked files: `id.txtnID=necho`, `mktemp:`, + `output/`, `tmp/`, stray hash scripts, older devlog dirs). + +## Steps + +1. **Push dev** — `git push origin dev` (user-approved, DEV-GIT-PUSH-01 + satisfied by the goal text). +2. **Open PR dev → main** — `gh pr create --base main --head dev` with a + release summary naming this unit's change. Check for a PR template first + (`.github/PULL_REQUEST_TEMPLATE*`). + - Note: `main` is far behind `dev` (677 commits at goal creation) — this + repo's release train works by merging `dev` into `main` wholesale + (precedent: PR #166 "chore(release): promote codexclaw 0.2.26 to main", + base main ← head dev, merged). Follow that precedent; do not cherry-pick. +3. **Merge** — `gh pr merge --merge` (or the repo's ruleset-required method; + if the ruleset demands checks, wait for them with `gh pr checks --watch`). +4. **Confirm deploy/release** — identify the release mechanism: + `.github/workflows/` release dispatch (see commit `9d3159e4` "ci(release): + guard the dispatch, fail closed on re-publish, attest the payload"). + Evidence: `gh run list` / release listing showing the post-main-merge + release outcome. If release is tag-driven and out of this unit's scope, + record that as the deploy boundary with the workflow file:line. +5. **Evidence** — PR URL, merge SHA, run/release URLs recorded in this doc's + 095_done.md successor and the goalplan criterion c-4. + +## Failure handling + +- Merge conflict on the PR: mechanical resolution only; anything semantic → + NEEDS_HUMAN. +- Required check failure: diagnose; if caused by this unit's change, fix on + dev and re-push (loop back to wp1 C). If pre-existing/flaky, document with + run URL and report BLOCKED rather than force-merging. +- `gh` auth failure → BLOCKED, report exactly. diff --git a/plugins/codexclaw/skills/dev-debugging/SKILL.md b/plugins/codexclaw/skills/dev-debugging/SKILL.md index 358826d2..fc746f9f 100644 --- a/plugins/codexclaw/skills/dev-debugging/SKILL.md +++ b/plugins/codexclaw/skills/dev-debugging/SKILL.md @@ -1,10 +1,10 @@ --- name: cxc-dev-debugging -description: "MUST USE for any real runtime debugging in any language — crashes, silent failures, wrong output, build/test failures, flaky tests, performance regressions, integration bugs. A phases 0-4 root-cause method: architecture check → investigate → analyze → hypothesize → implement. Triggers: 'debug this', 'why is X failing', 'this test is flaky', 'fix the crash', 'root cause', '왜 안 돼', '디버깅', '원인 분석'." +description: "MUST USE for any real runtime debugging in any language — crashes, silent failures, wrong output, build/test failures, flaky tests, performance regressions, integration bugs. A phases 0-4 root-cause method: architecture check → investigate → analyze → hypothesize → implement. Logic analysis of unknown systems (how apps/APIs/AI tools work) via references/logic-analysis.md. Triggers: 'debug this', 'why is X failing', 'this test is flaky', 'fix the crash', 'root cause', '왜 안 돼', '디버깅', '원인 분석', 'how does X work', 'figure out how', '로직 파악', '뜯어봐', 'reverse engineer'." metadata: last-verified: "2026-07-02" short-description: "Phases 0-4 systematic root-cause debugging method (any language)." - keywords: [debug, error, stack trace, root cause, flaky, regression, crash, bisect] + keywords: [debug, error, stack trace, root cause, flaky, regression, crash, bisect, "logic analysis", "comprehension", "unknown system", "reverse engineering"] --- # dev-debugging — Systematic Root Cause Analysis @@ -17,7 +17,9 @@ build failures, performance regressions, integration bugs. **Boundary**: This skill covers how to reason about bugs. For test harness, reproduction frameworks, and verification tooling, see `dev-testing`. For domain-specific context (API errors, hydration issues, query performance), -consult `dev-backend` or `dev-frontend`. +consult `dev-backend` or `dev-frontend`. Comprehension without a defect — +understanding how an unknown app, API, AI tool, or codebase works — routes to +`references/logic-analysis.md`. > **C0/C1 work (small local patches):** See `dev` §0.0 Work Classifier + §0.1 Patch Fast-Path before reading references. @@ -205,6 +207,19 @@ explaining the causal mechanism before patching. --- +## Logic Analysis (comprehension without a defect) + +When the request is to understand how a system works — closed app, AI tool, +undocumented API, unfamiliar codebase — rather than to fix a defect, read +[Logic analysis](references/logic-analysis.md). Core rules: "I can't" is a +skipped analysis loop, not a limit; missing source/docs is a starting +condition; hypothesize from names/strings/errors, observe static AND dynamic, +mutate one variable at a time, keep an incremental model with UNKNOWN fields, +and prove the model by writing a client that uses it. Honest lab-boundary +routing (IDA/Procmon/Cuckoo class) beats both refusal and fabrication. + +--- + ## Red Flags — Return to Phase 1 If you catch yourself doing any of these, pause — root cause investigation @@ -367,6 +382,7 @@ action item that prevents the same class of bug from recurring. | File | When to Read | What It Covers | |------|-------------|----------------| | `references/methodologies.md` | Choosing a debug approach | Five Whys, bisection, differential diagnosis, subtraction, systematic logging | +| `references/logic-analysis.md` | Understanding how an unknown system works (no defect) | Logic-analysis loop, controlled mutation, routing table, lab boundary, anti-give-up ladder | | `references/async-debugging.md` | Concurrency issues | Race conditions, deadlocks, event loop blocking, promise/callback | | `references/tool-guides.md` | Quick cheatsheet | Node inspector basics, pdb basics, Chrome DevTools, git bisect, DB EXPLAIN | | `references/postmortem-template.md` | After resolving a significant incident | Blameless postmortem template | @@ -411,4 +427,5 @@ When context is limited, preserve: (1) Phase 0 — is it a bug or a design probl (2) Core principle — RCA before permanent repair; preauthorized reversible incident mitigation may come first, (3) phases 0-4 — architecture check → investigate → analyze → hypothesize → implement, (4) Repeated Failure Rule — after repeated failures, reassess, (5) one variable at a time, -(6) evidence over intuition, (7) failing test first. +(6) evidence over intuition, (7) failing test first, (8) comprehension tasks route to +`references/logic-analysis.md` — "I can't" is a skipped loop. diff --git a/plugins/codexclaw/skills/dev-debugging/references/logic-analysis.md b/plugins/codexclaw/skills/dev-debugging/references/logic-analysis.md new file mode 100644 index 00000000..b3560972 --- /dev/null +++ b/plugins/codexclaw/skills/dev-debugging/references/logic-analysis.md @@ -0,0 +1,142 @@ +# Logic Analysis — Comprehending an Unknown System + +Read this when the task is to understand how a system works — a closed-source +app, an AI tool, an undocumented API, a protocol, an unfamiliar codebase — +and no defect is being fixed. Defects use the phases 0-4 method in +`../SKILL.md`; this reference is the same discipline aimed at comprehension. + +Distilled from three reverse-engineering courses (mytechnotalent +Reverse-Engineering, wtsxDev reverse-engineering list, Z0FCourse) — analysis +with citations: `devlog/_plan/260913_logic_analysis_skill/001_analysis_synthesis.md`. + +## The core rule + +**"I can't analyze this" is a skipped loop, not a limit.** Missing source, +missing docs, and no debugger are *starting conditions*, not stop conditions +— professional reverse engineers begin from exactly there. Refusal is correct +only at the honest-limits boundary (§Honest limits). Everything short of that +is a routing problem: pick the technique family that fits the target and run +the loop. + +## The Logic-Analysis Loop + +1. **State the question precisely.** "How does X work" is not a question; + "which endpoint charges the card, and what fields does it need" is. Decide + what "understood" means — usually: you can predict or reproduce a behavior. +2. **Isolate the target.** Work in a sandbox/VM/copy where you can observe + side effects (files, network, processes, DB rows) and revert mistakes. +3. **Acquire just enough domain language.** Learn the host vocabulary (ABI, + data structure, protocol family) before reading deeply — otherwise every + observation is unreadable. Do not front-load more than the next step needs. +4. **Inventory the public surface before internals.** Exports, routes, + commands, config keys, UI actions — what is callable, what does each entry + promise, what does calling it need? For a library you care about the + exported functions first, not the internals. +5. **Slice; don't reverse the whole system.** Pick one function family, one + route, one dialog. Prefer a semi-documented slice so you can check your + work against an independent oracle. Simple functions first — they teach + the conventions the hard ones use. +6. **Hypothesize from names, strings, and errors before the deep dive.** + Skim for the general idea, then write a guess: "a Generic Table is + probably a data structure; initialization will hint at its fields." + Treat every reconstruction — including decompiler/LLM output and metadata + labels — as a guess until observed evidence confirms it. Names lie. +7. **Observe: static AND dynamic.** Static: read the artifact as it sits + (source, strings, headers, bundles, OpenAPI leftovers). Dynamic: run the + smallest thing and watch (logs, proxy, `strace`/`dtruss`, added print + statements, one `curl`). A static-only conclusion is a hypothesis; some + questions are provably undecidable statically. +8. **Prove the model by using it.** Write the harness: a minimal client, a + REPL call, a test that invokes the interface you think you understood. + The loop closes when your client works — black-box observation has become + a white-box model. Then re-verify after any mutation. + +Run the loop per slice. Overwhelm is a chunking problem: break it down, name +one function/block/field, finish it, then the next. + +## Controlled mutation (the "hack" step) + +To learn a rule, change exactly one variable and re-observe: + +- Flip one input field, one flag, one predicate — never five at once. +- Table the delta: status × body × side effect. Error strings are schema. +- Probe through input — it is the cheapest experiment: boundary values and + wrong types map validation without any internals access. This is mapping, + not attacking: stay within authorization (§Honest limits). +- Inject a unique canary (request id, filename, email) and watch which + outputs echo it — that traces the data path with zero instrumentation. +- Compare two encodings of the same behavior (GUI vs CLI, SDK vs raw HTTP, + x86 vs x64 build): the diff isolates what is essential from what is + incidental. + +## The incremental model + +Keep written notes as you go — a running document, not memory: + +- Maintain the reconstructed schema/struct/state machine with explicit + `UNKNOWN` fields; fill them as evidence arrives. +- Rename things as you learn them ("endpoint X" → "createCharge"); never + keep raw hashes in your head. +- Record rejected hypotheses and what rejected them — the final explanation + must include the dead ends. +- Until contradicted, prefer the stupid-simple mechanism; keep an open mind + and update the model the moment evidence contradicts it. + +## Technique routing table + +| Target | First moves | Agent-accessible tools | +|---|---|---| +| Unfamiliar open-source repo | README → entry point → one test/example run; trace one identifier end-to-end | grep/ast-grep, the repo's own tests, a 10-line harness | +| Undocumented HTTP API | Inventory via JS bundles/OpenAPI leftovers/`--help`; one known-good request; then one-field mutations | `curl`, browser devtools/HAR, mitmproxy, jq | +| Closed-source desktop/CLI app | Strings, config files, logs, `--help`, file/registry/network side effects of one action | `strings`, `file`, `fs_usage`/`dtruss`, process listing, a signed-in browser profile | +| Local binary artifact (structure) | Format identification → symbols/imports → disassembly slice | `file`, `nm`, `objdump`, `readelf`, radare2, capstone, scripted runs | +| Managed bytecode / APK | Decompile to source-like form, then read | jadx, apktool, dex2jar, oletools (docs), `pefile` | +| Live behavior of a running system | Syscall/FS/network trace; capture once, analyze offline | `strace`/`dtruss`, `lsof`, tcpdump, HAR/pcap capture | +| Automated reasoning about a small function | Encode and solve | z3/angr (programmable, no GUI) | + +## Human-lab boundary (route honestly, never fake) + +These need a specialist workstation or lab — say so instead of claiming the +technique or claiming impossibility: IDA/Ghidra GUI workflows, Sysinternals/ +Procmon, Wireshark GUI analysis, Windows unpacker GUIs, Cuckoo-style malware +detonation, time-travel debuggers on a live target. The honest answer is +"this slice needs tool T on a lab machine; here is what I CAN establish from +here" — never "I can't", never a fabricated result. + +## Anti-give-up escalation ladder + +When stuck, climb — do not stop: + +1. Shrink the example until the technique is visible (Hello-World-sized). +2. Re-read the actual error/artifact — every line, not a skim. +3. Form a hypothesis and design the check that would falsify it. +4. Run the check; a failed probe is information, try the second probe. +5. Drop one abstraction layer (SDK → raw HTTP → bytes) or rise one + (bytes → strings → documented API). +6. Compare against a second implementation/version/encoding. +7. Capture a trace and analyze it offline instead of live. +8. Look it up — unknown instructions/fields are normal; external docs and + the `search` skill are part of the loop. +9. Only now, report the exact blocking observation, what a human with tool T + would do, and what is already established. + +## Honest limits + +- **Authorization**: analyze only systems you may analyze. Mapping input + validation of your own service is fine; probing third-party systems, + bypassing controls, or detonating malware is not in this skill's scope. +- **Hostile code**: never execute unknown binaries to observe them. Static + inspection only, or hand to a lab. +- **Decompiler/LLM reconstructions are sketches, not evidence** — confirm by + observation before claiming. +- Some truths are dynamic-only (representation chosen at runtime); some need + the lab tools above. Name which case you are in. + +## Vocabulary worth having + +static analysis (artifact at rest) · dynamic analysis (running system) · +breakpoint (controlled observation point — a log line counts) · +import/export (the callable surface) · entry point (where execution really +starts — not `main`) · calling convention (who owns which argument) · +canary (unique traceable input) · black-box → white-box (observe → model → +prove by using).