🐡 Fugu: Binary Nutrition Lab

Fugu is a web-based binary analysis lab: a Next.js 16 dashboard that plates angr telemetry like a nutrition label, lets you inspect taint flows in a call-graph aquarium, and pipes a DSL-driven patch kitchen straight into the browser.

Neon highlights

• Binary Nutrition Facts — BinaryFactsLabel renders file metadata, sections, protection bits, and entropy just like a cereal label.
• Ransomware, Crypto, and IoC trays — RansomwareIndicatorsCard, CryptoUsageCard, IoCPanel, and FilesystemBehaviorCard turn raw telemetry into snackable diagnostics.
• Call Graph Aquarium — CallGraphView blends react-force-graph-2d with IoC pills, simulations, and taint overlays so you can follow suspicious swim lanes.
• Query & Patch Lab — components/query-workbench.tsx talks to /api/query, runs the Python DSL (fugu/query_dsl.py), logs patches in SQLite, and lets you apply them without leaving the UI.
• Sim Vault & Patch Pantry — /api/simulations and /api/patches persist path simulations and mutations in data/*.db, so your telemetry survives refreshes and demos.

Anatomy (snout-to-tail)

1. Frontend — Next.js 16, React 19, Tailwind 4, and Lucide icons live in app/ and components/. app/page.tsx handles polling, tab state, and the brutalist treatment.
2. Binary store — app/api/binary/route.ts keeps the UI hot by writing telemetry into an in-memory store (lib/binary-store.ts) that mirrors the last POST.
3. Persistence — lib/patch-db.ts and lib/simulation-db.ts use better-sqlite3 to write into data/patches.db + data/simulations.db. WAL is enabled so it works out-of-the-box.
4. DSL & patch pipeline — /api/query spawns python -m fugu.query_dsl, streams the current snapshot via stdin, then logs patch operations or newly generated path simulations.
5. Patch application — /api/patches/apply spawns python -m fugu.patch_apply, writes patched binaries to FUGU_PATCH_OUTPUT_DIR (or next to the original), and marks rows as applied.
6. Python brain — fugu/ wraps angr for collection (fugu/main.py), the DSL engine, patch helpers, and requirements for a slim venv.

Getting started

Requirements

• Node.js 20+ and pnpm 8+
• Python 3.10+ with pip
• macOS/Linux (Windows works via WSL or a shell that can run the scripts below)

Install dependencies

pnpm install
python3 -m venv .venv
source .venv/bin/activate
pip install -r fugu/requirements.txt

Tip: set PYTHON_BIN and/or VIRTUAL_ENV if your Python lives somewhere else—lib/python.ts will pick it up automatically.

Run the Binary Nutrition dashboard

pnpm dev
# visit http://localhost:3000

Useful scripts: pnpm lint, pnpm build, and pnpm start.

Feeding the fish (POST /api/binary)

/api/binary is the single ingestion endpoint. Send a POST with as much telemetry as you have—the UI turns on whenever hasData is true. The /test helper page (app/test/page.tsx) can send a curated payload or copy a ready-made curl command.

curl -X POST http://localhost:3000/api/binary \
  -H "Content-Type: application/json" \
  -d '{
        "binaryId": "demo-id",
        "binaryPath": "/tmp/demo.bin",
        "binaryData": { "name": "demo.bin", "format": "ELF", "architecture": "x86_64" },
        "callGraph": [{ "id": "main", "name": "main", "calls": ["decrypt_payload"] }],
        "ransomwareProfile": {...},
        "iocs": {"items": []},
        "cryptoUsage": {...},
        "filesystemBehavior": {...},
        "simulations": [],
        "malwareFamilies": [],
        "taintSummary": null
      }'

GET /api/binary is polled every 2 seconds via useSWR so the dashboard updates automatically.

Query & patch DSL cheat sheet

components/query-workbench.tsx sends whatever you type to /api/query, which pipes it to python -m fugu.query_dsl. Highlights:

QUERY sections WHERE entropy > 7
QUERY imports WHERE name CONTAINS "mutex"
SIMULATE PATH FROM main DEPTH 120 LIMIT 2
SIMULATE MUTATE security TOGGLE nx
PATCH MUTATE security SET nx = true

• QUERY returns filtered data with counts.
• SIMULATE PATH records traversals and saves them in SQLite so the Call Graph tab can highlight them.
• SIMULATE MUTATE previews structural or metadata changes.
• PATCH MUTATE logs operations; the Patch Log (PatchLogPanel) lets you apply, clear, or review batches.

API + file map

Endpoint / file	Purpose
POST /api/binary (app/api/binary/route.ts)	Accepts telemetry, warms the in-memory store, and replaces simulation rows.
GET /api/binary	Returns the latest snapshot for the dashboard.
POST /api/query (app/api/query/route.ts)	Spawns the DSL engine, logs patches via lib/patch-db.ts, and persists simulations.
GET /api/patches / DELETE /api/patches	Lists or clears logged mutations for the active binary.
POST /api/patches/apply	Runs python -m fugu.patch_apply, writes a .patched binary, and stamps a batch ID.
GET /api/simulations	Reads historical simulations from data/simulations.db.
fugu/main.py	CLI that runs angr, emits telemetry, and can optionally boot pnpm dev via --start-ui.
fugu/query_dsl.py / fugu/patch_apply.py	DSL interpreter + patch helper that power the Query Lab.

Configuration knobs

• PYTHON_BIN — force a specific interpreter (helpful if angr lives in a system install).
• VIRTUAL_ENV — respected when resolving Python paths.
• FUGU_PATCH_OUTPUT_DIR — controls where patched binaries land (defaults to the original binary’s folder).

Set them inline (FUGU_PATCH_OUTPUT_DIR=/tmp/patched pnpm dev) or via .env.

Running the angr CLI

Use the bundled helper to analyze a binary and post results straight into the dashboard:

python -m fugu.main serve --path ./binaries/evil.bin \
  --endpoint http://localhost:3000/api/binary \
  --start-ui

--start-ui launches pnpm dev for you, creating an end-to-end Binary Nutrition tasting menu with a single command.

---

Now toss a suspicious sample into the tank, watch the Binary Nutrition label light up, and enjoy how Fugu keeps analysis, simulation, and patching inside one neon theme.