Skip to content
Back to search

tiny-dec

MarketplaceWorks with Claude CodeGitHub

A tiny educational decompiler that helps people understand how decompilation works.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zhangzhuosjtu--tiny-dec/badge.svg)](/listings/zhangzhuosjtu--tiny-dec)

HTML

<a href="/listings/zhangzhuosjtu--tiny-dec"><img src="/api/listings/zhangzhuosjtu--tiny-dec/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Learn with the AI Tutor

Install Claude Code, then:

# 1. Add the marketplace
/plugin marketplace add ZhangZhuoSJTU/tiny-dec

# 2. Install the plugin
/plugin install tiny-dec@tiny-dec

# 3. Reload to activate
/reload-plugins

Type **`/tiny-dec:teach-decompilation`** to start.

Install from Source

# System dependencies (Ubuntu/Debian)
$ sudo apt-get install -y clang lld llvm binutils build-essential python3 python3-pip

# Python dependencies
$ pip install poetry
$ poetry install

# Build RV32I fixture binaries for tests
$ ./scripts/build_fixtures.sh

Decompile

# Full decompilation to C (default)
$ poetry run tiny-dec decompile ./binary.elf

# Target a specific function
$ poetry run tiny-dec decompile ./binary.elf --func parse_record

# Stop at any intermediate stage and look inside
$ poetry run tiny-dec decompile ./binary.elf --stage ssa --func main

# Inspect binary metadata
$ poetry run tiny-dec info ./binary.elf

Every stage is a window into the pipeline:

loader → decode → pcode → disasm → ir → simplify → dataflow → ssa
→ calls → stack → memory → scalar_types → aggregate_types → variables
→ range → interproc → structuring → c_lowering → c

Test

$ poetry run pytest            # all 500 tests
$ poetry run ruff check .      # lint
$ poetry run mypy tiny_dec     # type check

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "tiny-dec",
  3. "owner": {
  4. "name": "ZhangZhuoSJTU"
  5. },
  6. "plugins": [
  7. {
  8. "name": "tiny-dec",
  9. "source": "./",
  10. "version": "1.0.0",
  11. "description": "Interactive decompilation teacher — learn how decompilers work by exploring tiny-dec's 19-stage RV32I pipeline with guided lessons, quizzes, and hands-on exercises."
  12. }
  13. ]
  14. }
README.md · README · 368 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="assets/logo.svg" alt="tiny-dec" width="640">
  3. </p>
  4. <p align="center">
  5. <strong>Learn decompilation by building one from scratch.</strong><br>
  6. <sub>19 stages. Every step inspectable. From raw RISC-V bytes to readable C.<br>
  7. RV32I: the simplest real ISA, so the focus stays on decompilation, not instruction encoding.</sub>
  8. </p>
  9. <p align="center">
  10. <img src="https://img.shields.io/badge/tutor-AI%20powered-D97757?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyTDMgN3YxMGw5IDUgOS01VjdMMTIgMnptMCAxOC4yTDUgMTUuOFY4LjJMMTIgMy44bDcgNC40djcuNkwxMiAyMC4yeiIvPjwvc3ZnPg==&logoColor=white" alt="AI Tutor">
  11. <a href="https://tiny-dec.zzhang.xyz"><img src="https://img.shields.io/badge/%F0%9F%94%8D_live_demo-tiny--dec.zzhang.xyz-e04832" alt="Live Demo"></a>
  12. <img src="https://img.shields.io/badge/python-%E2%89%A53.12-3776AB?logo=python&logoColor=white" alt="Python">
  13. <img src="https://img.shields.io/badge/arch-RISC--V%20RV32I-764ABC" alt="RISC-V RV32I">
  14. <img src="https://img.shields.io/badge/pipeline-19%20stages-orange" alt="19 stages">
  15. </p>
  16. > [!TIP]
  17. > *This project is inspired by the amazing open-source efforts behind [angr](https://github.com/angr/angr), [radare2](https://github.com/radareorg/radare2), and [Ghidra](https://github.com/NationalSecurityAgency/ghidra). Thanks for all the open-source work that makes projects like this possible.*
  18. > [!NOTE]
  19. > **This is a teaching tool, not a production decompiler.** The pipeline is deliberately factored into many small, isolated stages so that each concept can be studied independently. A real-world decompiler (Ghidra, IDA, angr, Binary Ninja) would fuse, reorder, or iterate these passes for performance and precision. We trade that efficiency for clarity: if you can follow each stage here, you will understand what the production tools are doing under the hood.
  20. ## Learn with Our AI Tutor
  21. We ship tiny-dec as a **Claude Code plugin**. An AI tutor assesses your level, walks you through each pipeline stage, quizzes you, and lets you experiment with real binaries, all inside your terminal.
  22. <p align="center"><img src="assets/tutor-demo.svg" alt="AI tutor session in Claude Code" width="720"></p>
  23. ## See the Pipeline in Action
  24. <p align="center">
  25. <a href="https://tiny-dec.zzhang.xyz"><img src="assets/demo.gif" alt="tiny-dec pipeline walkthrough" width="720"></a><br>
  26. <sub>A bird's-eye view of all 19 stages. Explore interactively at <a href="https://tiny-dec.zzhang.xyz">tiny-dec.zzhang.xyz</a>.</sub>
  27. </p>
  28. ## Quick Start
  29. ### Learn with the AI Tutor
  30. Install Claude Code, then:
  31. ```bash
  32. # 1. Add the marketplace
  33. /plugin marketplace add ZhangZhuoSJTU/tiny-dec
  34. # 2. Install the plugin
  35. /plugin install tiny-dec@tiny-dec
  36. # 3. Reload to activate
  37. /reload-plugins
  38. ```
  39. Type **`/tiny-dec:teach-decompilation`** to start.
  40. ### Install from Source
  41. ```bash
  42. # System dependencies (Ubuntu/Debian)
  43. $ sudo apt-get install -y clang lld llvm binutils build-essential python3 python3-pip
  44. # Python dependencies
  45. $ pip install poetry
  46. $ poetry install
  47. # Build RV32I fixture binaries for tests
  48. $ ./scripts/build_fixtures.sh
  49. ```
  50. #### Decompile
  51. ```bash
  52. # Full decompilation to C (default)
  53. $ poetry run tiny-dec decompile ./binary.elf
  54. # Target a specific function
  55. $ poetry run tiny-dec decompile ./binary.elf --func parse_record
  56. # Stop at any intermediate stage and look inside
  57. $ poetry run tiny-dec decompile ./binary.elf --stage ssa --func main
  58. # Inspect binary metadata
  59. $ poetry run tiny-dec info ./binary.elf
  60. ```
  61. Every stage is a window into the pipeline:
  62. ```
  63. loader → decode → pcode → disasm → ir → simplify → dataflow → ssa
  64. → calls → stack → memory → scalar_types → aggregate_types → variables
  65. → range → interproc → structuring → c_lowering → c
  66. ```
  67. #### Test
  68. ```bash
  69. $ poetry run pytest # all 500 tests
  70. $ poetry run ruff check . # lint
  71. $ poetry run mypy tiny_dec # type check
  72. ```
  73. ## Example Output
  74. **Raw RISC-V instructions go in.** Readable C comes out:
  75. <table>
  76. <tr>
  77. <th>Assembly (RV32I)</th>
  78. <th>Decompiled Output</th>
  79. </tr>
  80. <tr>
  81. <td valign="top">
  82. ```asm
  83. ; parse_record
  84. addi x2, x2, -32
  85. sw x1, 28(x2)
  86. sw x8, 24(x2)
  87. addi x8, x2, 32
  88. sw x10, -12(x8)
  89. sw x11, -16(x8)
  90. addi x10, x0, 0
  91. sw x10, -20(x8)
  92. sw x10, -24(x8)
  93. jal x0, 0x11154
  94. lw x10, -24(x8)
  95. lw x11, -16(x8)
  96. bge x10, x11, 0x111b8
  97. lw x10, -12(x8)
  98. lw x11, -24(x8)
  99. slli x11, x11, 3
  100. add x10, x10, x11
  101. lw x11, 0(x10)
  102. lw x10, -20(x8)
  103. add x10, x10, x11
  104. sw x10, -20(x8)
  105. lw x10, -12(x8)
  106. lw x11, -24(x8)
  107. slli x11, x11, 3
  108. add x10, x10, x11
  109. lw x11, 4(x10)
  110. lw x10, -20(x8)
  111. add x10, x10, x11
  112. sw x10, -20(x8)
  113. lw x10, -24(x8)
  114. addi x10, x10, 1
  115. sw x10, -24(x8)
  116. jal x0, 0x11154
  117. lw x10, -20(x8)
  118. lw x1, 28(x2)
  119. lw x8, 24(x2)
  120. addi x2, x2, 32
  121. jalr x0, 0(x1)
  122. ```
  123. </td>
  124. <td valign="top">
  125. ```c
  126. #include <stdint.h>
  127. typedef struct agg_8 {
  128. int32_t field_0;
  129. int32_t field_4;
  130. } agg_8;
  131. static uint32_t main(void) {
  132. int32_t local_24_4;
  133. int32_t local_20_4;
  134. int32_t local_16_4;
  135. int32_t local_12_4;
  136. uint32_t call_ret;
  137. local_12_4 = 20;
  138. local_16_4 = 2;
  139. local_20_4 = 10;
  140. local_24_4 = 1;
  141. call_ret = parse_record(&local_24_4, 2);
  142. return call_ret;
  143. }
  144. static uint32_t parse_record(
  145. agg_8* arg_x10_4,
  146. int32_t arg_x11_4) {
  147. int32_t local_24_4;
  148. int32_t local_20_4;
  149. local_20_4 = 0;
  150. local_24_4 = 0;
  151. while (local_24_4 <s arg_x11_4) {
  152. local_20_4 = local_20_4
  153. + arg_x10_4[local_24_4].field_0;
  154. local_20_4 = local_20_4
  155. + arg_x10_4[local_24_4].field_4;
  156. local_24_4 = local_24_4 + 1;
  157. }
  158. return local_20_4;
  159. }
  160. ```
  161. </td>
  162. </tr>
  163. </table>
  164. > Recovered: **struct layout**, **pointer parameter**, **while loop**, **array indexing with field access**, and **local variables**.
  165. It handles more than loops and structs:
  166. ```c
  167. // Switch recovery from equality-ladder CFG patterns
  168. static int32_t dispatch(uint32_t arg_x10_4, uint32_t arg_x11_4) {
  169. uint32_t local_24_4;
  170. uint32_t local_12_4;
  171. local_24_4 = arg_x10_4;
  172. switch (arg_x10_4) {
  173. case 0:
  174. local_12_4 = arg_x11_4 + 1;
  175. break;
  176. case 1:
  177. local_12_4 = arg_x11_4 + 4;
  178. break;
  179. case 2:
  180. local_12_4 = arg_x11_4 << 1;
  181. break;
  182. case 3:
  183. local_12_4 = arg_x11_4 - 3;
  184. break;
  185. default:
  186. local_12_4 = -1;
  187. break;
  188. }
  189. return local_12_4;
  190. }
  191. ```
  192. ```c
  193. // Interprocedural analysis with prototype inference
  194. static int32_t main(void) {
  195. int32_t local_16_4;
  196. int32_t local_12_4;
  197. local_12_4 = 7;
  198. local_16_4 = helper(local_12_4);
  199. return local_16_4 - 2;
  200. }
  201. static int32_t helper(int32_t arg_x10_4) {
  202. return (arg_x10_4 << 1) + arg_x10_4 + 1;
  203. }
  204. ```
  205. ## The Pipeline
  206. 19 stages, three phases. Each stage produces a typed, deterministic artifact you can inspect with `--stage`. The stages are split for learning purposes; a production decompiler would combine several of these into fewer, more tightly coupled passes.
  207. ### Phase 1: Frontend (Bytes to IR)
  208. | # | Stage | What it does |
  209. |---|-------|-------------|
  210. | 00 | [**Loader**](tiny_dec/loader/) | Parse ELF structure, resolve symbols, find `main`. The loader is deliberately shallow: it delegates all ELF parsing to [pwntools](https://github.com/Gallopsled/pwntools) and uses simple heuristics for main discovery, since binary format parsing is not the educational focus of this project. |
  211. | 01 | [**Decode**](tiny_dec/decode/) | Decode RV32I instruction words into structured objects |
  212. | 02 | [**P-code Lift**](tiny_dec/ir/) | Lift each instruction into semantic p-code operations |
  213. | 03 | [**Disassembly**](tiny_dec/disasm/) | Recursive traversal to build basic blocks and CFG |
  214. | 04 | [**IR Containers**](tiny_dec/ir/) | Wrap functions and programs into durable typed containers |
  215. ### Phase 2: Analysis
  216. | # | Stage | What it does |
  217. |---|-------|-------------|
  218. | 05 | [**Simplify**](tiny_dec/analysis/simplify/) | Constant folding, identity elimination, temporary forwarding |
  219. | 06 | [**Dataflow**](tiny_dec/analysis/dataflow/) | Forward intraprocedural constant propagation |
  220. | 07 | [**SSA**](tiny_dec/analysis/ssa/) | Dominance-frontier SSA with memory versioning |
  221. | 08 | [**Calls**](tiny_dec/analysis/calls/) | Call classification, ABI argument/return snapshots |
  222. | 09 | [**Stack**](tiny_dec/analysis/stack/) | Frame layout recovery, stack slot identification |
  223. | 10 | [**Memory**](tiny_dec/analysis/memory/) | Partition recovery for stack, global, and pointer accesses |
  224. | 11 | [**Scalar Types**](tiny_dec/analysis/types/) | Type inference: `bool`, `int`, `pointer`, `word` |
  225. | 12 | [**Aggregate Types**](tiny_dec/analysis/types/) | Struct layout recovery from pointer arithmetic patterns |
  226. | 13 | [**Variables**](tiny_dec/analysis/highvars/) | Group SSA values and memory slots into named variables |
  227. | 14 | [**Range**](tiny_dec/analysis/range/) | Interval analysis and branch predicate refinement |
  228. | 15 | [**Interproc**](tiny_dec/analysis/interproc/) | Cross-function prototype inference and summaries |
  229. ### Phase 3: Backend (Structure and Emit)
  230. | # | Stage | What it does |
  231. |---|-------|-------------|
  232. | 16 | [**Structuring**](tiny_dec/structuring/) | Recover `if` / `while` / `switch` from CFG topology |
  233. | 17 | [**C Lowering**](tiny_dec/c_emit/) | Lower to C-like IR with typed declarations and expressions |
  234. | 18 | [**C Render**](tiny_dec/pipeline/) | Emit readable C with precedence-aware formatting |
  235. ## Project Layout
  236. ```
  237. tiny_dec/
  238. ├── loader/ ELF loading and symbol resolution
  239. ├── decode/ RV32I instruction decoder
  240. ├── ir/ P-code semantics and IR containers
  241. ├── disasm/ Recursive disassembler and CFG builder
  242. ├── analysis/
  243. │ ├── simplify/ Canonical IR cleanup
  244. │ ├── dataflow/ Constant propagation
  245. │ ├── ssa/ SSA construction
  246. │ ├── calls/ Call modeling and ABI facts
  247. │ ├── stack/ Stack frame recovery
  248. │ ├── memory/ Memory partitioning
  249. │ ├── types/ Scalar and aggregate type recovery
  250. │ ├── highvars/ Variable recovery
  251. │ ├── range/ Range and predicate analysis
  252. │ └── interproc/ Interprocedural summaries
  253. ├── structuring/ Control-flow structuring
  254. ├── c_emit/ C lowering and rendering
  255. ├── pipeline/ End-to-end decompilation driver
  256. └── cli.py Command-line interface
  257. tests/
  258. ├── fixtures/
  259. │ ├── src/ 13 C programs (loops, structs, calls, switches, ...)
  260. │ └── bin/ 39 cross-compiled RV32I ELF binaries
  261. └── posts/
  262. └── post_00/ ... post_18/ One test suite per pipeline stage
  263. ```
  264. ## Why Is It Built This Way?
  265. **Explicit over clever.** Every intermediate representation is a concrete, typed Python dataclass. No hidden state, no magic.
  266. **Deterministic output.** Every stage has a text renderer that produces identical output given identical input. This is both the debugging surface and the test oracle.
  267. **One stage, one job.** Each stage solves exactly one problem and passes a well-defined artifact to the next. You can stop the pipeline at any point and inspect what it produced.
  268. **Conservative analysis.** The pipeline never invents information. When evidence is ambiguous, it preserves the raw form rather than guessing. Residual `raw<...>` expressions in the output are honest about what the analysis couldn't resolve.
  269. **This is a teaching tool, not a production decompiler.** The pipeline is deliberately factored into many small, isolated stages so that each concept can be studied independently. A real-world decompiler (Ghidra, IDA, angr, Binary Ninja) would fuse, reorder, or iterate these passes for performance and precision. We trade that efficiency for clarity: if you can follow each stage here, you will understand what the production tools are doing under the hood.
  270. ## Fixture Binaries
  271. 13 C programs compiled to RV32I ELF at three optimization levels (39 binaries total, with strict no-compressed-instruction verification):
  272. | Variant | Flags | Purpose |
  273. |---------|-------|---------|
  274. | `*_O0_nopie` | `-O0 -fno-pie` | Unoptimized, predictable stack layout |
  275. | `*_O2_nopie` | `-O2 -fno-pie` | Optimized, tests register allocation recovery |
  276. | `*_O2_pie` | `-O2 -fpie` | Position-independent, tests GOT/PLT handling |
  277. Rebuild with `./scripts/build_fixtures.sh` (requires `clang`, `lld`, `llvm` with RISC-V support).
  278. ## Further Reading
  279. <p align="center">
  280. <a href="https://decompilation.wiki"><img src="assets/card-decompilation-wiki.svg" alt="decompilation.wiki" width="100"></a>
  281. &nbsp;
  282. <a href="https://mahaloz.re"><img src="assets/card-mahaloz.svg" alt="mahaloz.re" width="100"></a>
  283. &nbsp;
  284. <a href="https://github.com/ZhangZhuoSJTU/tiny-dec/issues/new?template=suggest-resource.yml"><img src="assets/card-more.svg" alt="Suggest a resource" width="100"></a>
  285. </p>
  286. <p align="center"><sub>Actively-maintained resources that go deeper into the concepts behind each pipeline stage.</sub></p>
  287. ## Special Thanks
  288. - [Seunghyun Sung](https://www.linkedin.com/in/seunghyun-sung/)
  289. - [Hugo Matousek](https://www.linkedin.com/in/hugo-matousek/)
  290. ## License
  291. [MIT](LICENSE)
website/capture-demo.mjs · Bundled script · 80 lines · 1 finding marked
  1. import { chromium } from 'playwright';
  2. import { execSync } from 'child_process';
  3. const URL = 'http://165.22.35.184:5173/';
    • Note: Talks to a raw IP address or throwaway host, where malware is often staged
    • Line 4 on GitHub
  4. const OUT_DIR = '/home/zhuo/tiny-dec-internal/assets/demo-frames';
  5. execSync(`rm -rf ${OUT_DIR} && mkdir -p ${OUT_DIR}`);
  6. const browser = await chromium.launch({ headless: true });
  7. const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
  8. await page.goto(URL, { waitUntil: 'networkidle' });
  9. await page.waitForTimeout(2000);
  10. let frame = 0;
  11. const snap = async () => {
  12. const path = `${OUT_DIR}/frame_${String(frame).padStart(3, '0')}.png`;
  13. await page.screenshot({ path });
  14. console.log(` [${frame}] captured`);
  15. frame++;
  16. };
  17. // Steps per stage: [popup(1) + callouts(N)]
  18. // Stage 0 = hero (no popup), Stage 21 = complete (no popup)
  19. // From the walkthrough data:
  20. const stageCallouts = [
  21. 0, // 0: hero/start - no walkthrough
  22. 2, // 1: raw bytes
  23. 4, // 2: loader
  24. 8, // 3: decode
  25. 5, // 4: pcode
  26. 6, // 5: disasm & cfg
  27. 3, // 6: ir containers
  28. 4, // 7: simplify
  29. 4, // 8: dataflow
  30. 4, // 9: ssa
  31. 4, // 10: calls
  32. 3, // 11: stack
  33. 3, // 12: memory
  34. 3, // 13: scalar types
  35. 4, // 14: aggregate types
  36. 3, // 15: variables
  37. 3, // 16: range
  38. 3, // 17: interproc
  39. 4, // 18: structuring
  40. 3, // 19: c lowering
  41. 3, // 20: final c
  42. 0, // 21: complete - no walkthrough
  43. ];
  44. // Frame 0: Hero
  45. await snap();
  46. // For stages 1-20: each has 1 popup + N callouts + free browse
  47. // ArrowRight advances: hero -> popup -> callout1 -> callout2 -> ... -> free browse -> next popup
  48. for (let stage = 1; stage <= 20; stage++) {
  49. // ArrowRight to enter stage (shows popup)
  50. await page.keyboard.press('ArrowRight');
  51. await page.waitForTimeout(1000);
  52. await snap(); // popup
  53. const callouts = stageCallouts[stage];
  54. for (let c = 0; c < callouts; c++) {
  55. await page.keyboard.press('ArrowRight');
  56. await page.waitForTimeout(800);
  57. await snap(); // callout
  58. }
  59. // ArrowRight to dismiss last callout -> free browse
  60. await page.keyboard.press('ArrowRight');
  61. await page.waitForTimeout(600);
  62. await snap(); // free browse view
  63. }
  64. // ArrowRight to complete
  65. await page.keyboard.press('ArrowRight');
  66. await page.waitForTimeout(1000);
  67. await snap(); // complete
  68. await browser.close();
  69. console.log(`\nDone! ${frame} frames captured in ${OUT_DIR}`);

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.