Project maintenance tracker: build, fixes, refactors, optimization, docs

[mitsuakki]

Meta: repo health - updates, fixes, refactors, optimizations

Notes to myself to organize maintenance work on the toolbox image. I'll split sub-items into their own issues/PRs as I pick them up.

Build and tooling

• Split the Dockerfile into stages (base, r2/ghidra, angr/python stack, fuzzing, android) so a rebuild after a small change doesn't reinstall everything
• Pin versions for radare2, Ghidra, angr, AFL++, honggfuzz, apktool, jadx, frida instead of pulling latest at build time, so builds are reproducible
• Add a CI workflow that builds the image on push/PR and fails fast if the build breaks
• Add a release workflow (tag, build and push image to GHCR/Docker Hub). No releases published yet
• Review image size. 62.9% Python / 25% Dockerfile / 12.1% shell suggests a lot of tool installs. Look at multi-stage builds and removing build only deps from the final layer
• Document minimum Docker/Docker Compose version required

Fixes

• Verify ENABLE_GHIDRA_HEADLESS_MCP default behavior is documented consistently everywhere it's referenced (README says default 1, confirm docker-compose.yml matches)
• Check that the Ghidra headless server actually recovers/restarts if it crashes inside the container, instead of leaving the MCP bridge pointing at a dead server
• Confirm r2pm -r r2mcp and bridge_mcp_ghidra.py handle the container not having a binary loaded yet without hanging or erroring unhelpfully
• Sweep scripts/ for hardcoded paths, container names (ctf-re vs toolbox, README uses both, docker-compose likely defines one, make sure they match everywhere)
• Sweep for TODO/FIXME comments across docker/ and scripts/, convert into tracked issues

Refactor

• Consolidate MCP server config examples in README into a single source of truth (they currently exist as copy paste JSON blocks per client, easy to drift). Consider generating them from configs/base.json
• Move tool specific helper scripts (angr-solve.py, fuzz-init.sh) into a consistent scripts/<tool>/ layout with a shared argument parsing convention
• Normalize container naming (README mixes ctf-re and toolbox), pick one and use it everywhere including docs
• Extract common Docker layer logic (apt installs, cleanup) into reusable stages or a base Dockerfile if docker/ has multiple Dockerfiles

Optimization

• Cache apt/pip layers properly (order Dockerfile instructions so dependency installs are cached separately from tool installs that change more often)
• Investigate lazy starting heavier services (Ghidra headless) only when needed instead of always on by default, to reduce idle resource usage
• Profile container startup time and image pull size, trim unused packages from the RE stack (angr, AFL++, honggfuzz, Android tools) if usage patterns show most people only use a subset

Testing

• Add a smoke test that builds the image and checks each MCP server actually responds (radare2, ghidra-headless) before merging
• Add a basic test binary in the repo to validate angr-solve.py, fuzz-init.sh, and the r2/Ghidra flows end to end
• Test the Android RE tools (apktool, jadx, frida, objection) against a sample APK as part of CI or a manual checklist

Documentation

• Add a troubleshooting section (MCP client not connecting, Ghidra server not starting, permission issues from SYS_PTRACE/seccomp unconfined)
• Document the security tradeoffs more prominently (currently one paragraph at the bottom) since SYS_PTRACE and disabled seccomp are meaningful for anyone running untrusted binaries
• Add a CONTRIBUTING.md if I want outside contributions (build steps, how to add a new tool/MCP server)
• Document resource requirements (RAM/CPU) for running Ghidra headless plus the rest of the stack simultaneously
• Add examples for Cline/Continue/Zed configs instead of just saying "same command/args work"

Misc / hygiene

• Add issue/PR templates
• Add a CHANGELOG.md, start using it from the next tagged release onward
• Confirm LICENSE covers all bundled tools correctly (MIT license on the repo, but bundled tools like Ghidra, angr, AFL++ have their own licenses, worth a NOTICE file)

---

This is a living checklist for myself. I'll convert any item into its own issue and link it back here when I start working on it.

[mitsuakki]

@sopugavega Thanks for looking into the hanging bridge issue, the dead PID detection idea sounds right and matches something I already had flagged for this repo.

That said, I don't run attached binaries or follow links to APKs from issues, especially not on a reverse engineering toolbox where that's a pretty sensitive thing to accept blind. If you want this fix in, please open a PR with the actual diff against the MCP init script (the restart on dead PID logic) so it can be reviewed as code. Happy to look at it that way.

[mitsuakki]

@sopugavega Thanks for looking into the hanging bridge issue, the dead PID detection idea sounds right and matches something I already had flagged for this repo.

That said, I don't run attached binaries or follow links to APKs from issues, especially not on a reverse engineering toolbox where that's a pretty sensitive thing to accept blind. If you want this fix in, please open a PR with the actual diff against the MCP init script (the restart on dead PID logic) so it can be reviewed as code. Happy to look at it that way.

Not so surprising, but this account was a bot and it got banned