commit e0b8f0e8c71faf238c6b3b127533dd6b7e5daa1a Author: Linus Henke Date: Sun Nov 1 19:16:01 2026 +0100 Add CLAUDE.md describing the Docker-based RE setup Co-Authored-By: Claude Opus 5.5 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0b8c7f7 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,84 @@ +# CLAUDE.md + +Guidance for Claude Code when working in this repository. + +## Purpose + +This repo provides a reproducible, Docker-managed reverse-engineering workstation on Linux, built around **Claude Desktop** with two MCP integrations: + +1. **Reverse Engineer Anything MCP**: general-purpose RE tooling exposed to Claude over MCP. +2. **Ghidra + GhidraMCP**: Ghidra with the GhidraMCP plugin, so Claude can query and annotate an open program (functions, decompilation, xrefs, renames, comments). + +The goal is that `docker compose up` gives you a working setup where Claude Desktop can drive both toolsets against binaries in a shared workspace, without installing Ghidra, a JDK or RE tooling on the host. + +## Status + +The repo is at an early stage (no code yet). The layout below is the **intended** structure. Update this file when the real structure differs. + +## Intended layout + +``` +. +├── CLAUDE.md +├── README.md # user-facing setup and usage +├── docker-compose.yml # orchestrates all services +├── .env.example # versions, ports, UID/GID, display settings +├── claude-desktop/ +│ ├── Dockerfile # Claude Desktop (Linux build) + GUI deps +│ └── claude_desktop_config.json # MCP server definitions (template) +├── ghidra/ +│ ├── Dockerfile # JDK + Ghidra + GhidraMCP plugin +│ └── scripts/ # plugin install / headless helpers +├── re-mcp/ +│ └── Dockerfile # Reverse Engineer Anything MCP server +├── scripts/ # host helpers (xhost setup, start/stop, health checks) +└── workspace/ # shared, git-ignored: binaries + Ghidra projects +``` + +## Architecture + +- **One service per container.** Claude Desktop, Ghidra and the RE MCP server each get their own image, connected on one compose network. +- **Shared workspace volume.** Every container mounts `./workspace` at the same path (e.g. `/workspace`), so a file path means the same thing to Claude, Ghidra and the RE MCP. +- **GUI forwarding.** Claude Desktop and Ghidra are GUI apps. Default to X11 forwarding (`/tmp/.X11-unix` + `DISPLAY`). Support Wayland through XWayland. Keep a noVNC/VNC fallback in mind for headless hosts. Never solve display access with a blanket `xhost +`. Scope it (`xhost +local:docker` or `+SI:localuser:...`). +- **GhidraMCP wiring.** GhidraMCP has two parts: + - a Ghidra plugin that runs an HTTP server inside Ghidra (default port `8080`), and + - a Python MCP bridge (`bridge_mcp_ghidra.py`) that speaks MCP to Claude and forwards calls to that HTTP server. + + The bridge is configured with the Ghidra server URL (e.g. `http://ghidra:8080/`). The plugin must be enabled in the CodeBrowser and a program must be open, or the bridge has nothing to talk to. +- **MCP transport between containers.** Claude Desktop starts local MCP servers as stdio subprocesses. Because the servers live in other containers, pick one approach and apply it consistently: + - *Preferred:* run the MCP servers with an HTTP/SSE transport in their own containers. Bridge them into Claude Desktop's stdio config with a small proxy (e.g. `mcp-remote` or `mcp-proxy`) installed in the Claude Desktop image. + - *Alternative:* install the bridges inside the Claude Desktop image and point them at the other containers over the network. This works well for the GhidraMCP bridge, which is just Python + HTTP. + - Avoid mounting the Docker socket into the Claude Desktop container just to `docker exec` MCP servers. + +## Conventions + +- **Pin versions.** Ghidra version, GhidraMCP release, JDK version, Claude Desktop build and RE MCP commit go in `.env` / build args, not `latest`. The GhidraMCP release must match the Ghidra version it was built for. +- **Run as non-root** inside containers. Map the host UID/GID (via `.env`) so files in `workspace/` stay owned by the user. +- **Persist state in named volumes or `workspace/`**: Claude Desktop config/login (`~/.config/Claude`), Ghidra user settings and projects. Rebuilding an image must not lose sign-in or analysis. +- **No secrets in the repo.** Credentials, session data and `workspace/` contents are git-ignored. Ship `.env.example`, never `.env`. +- **Untrusted binaries.** Samples under analysis may be malicious. Never execute them on the host or in the Claude Desktop container. Containers that might run samples (dynamic analysis) should have no host mounts beyond `workspace/` and should allow network isolation (`network_mode: none` or an internal-only network). +- **Linux only.** Target recent Docker Engine + Compose v2 (`docker compose`, not `docker-compose`). Make the setup work under both Docker and rootless Podman where practical. On SELinux hosts such as Fedora, bind mounts need `:z`/`:Z`. + +## Common commands + +These are expected once the compose setup exists. Keep this list in sync with reality. + +```bash +cp .env.example .env # then adjust UID/GID, versions, DISPLAY +xhost +local:docker # allow containers to use the X server +docker compose build +docker compose up -d +docker compose logs -f +docker compose down +``` + +## Things to verify, not assume + +- **Claude Desktop on Linux.** Check whether an official Linux build is available at the time of work. If not, use a maintained community repackaging and document which one and why. Confirm the config path, usually `~/.config/Claude/claude_desktop_config.json`. +- **Reverse Engineer Anything MCP.** Confirm the upstream repository, install method, runtime (Python/Node), required external tools and supported transports before writing its Dockerfile. Record the source URL in the README. +- **GhidraMCP.** Confirm the current release, its supported Ghidra version, the bridge's CLI flags and its default ports from the upstream README. + +## When making changes + +- After changing a Dockerfile or compose file, run `docker compose config` to validate it, then build the affected service. +- When adding an MCP server, update `claude-desktop/claude_desktop_config.json`, `docker-compose.yml`, `README.md` and the Architecture section above together.