Docker Usage

MCGhidra can automatically provision Docker containers running Ghidra in headless mode. Each container gets a dedicated port from a configurable pool, and containers are tracked by session to prevent cross-talk between concurrent MCP clients.

Quick Start

docker_auto_start(binary_path="/path/to/binary")

This checks for an existing instance analyzing the same binary, and if none is found, starts a new container with an auto-allocated port.

Environment Variables

The Docker entrypoint accepts these environment variables:

Variable	Default	Description
MCGHIDRA_PORT	8192	HTTP API port inside the container
MCGHIDRA_MAXMEM	2G	Max JVM heap size
PROJECT_NAME	MCGhidra	Ghidra project name
PROJECT_DIR	/projects	Project directory inside container
GHIDRA_LANGUAGE	(auto-detect)	Processor language ID (e.g., ARM:LE:32:v4t)
GHIDRA_BASE_ADDRESS	(auto-detect)	Base address for raw binaries (e.g., 0x00000000)
GHIDRA_LOADER	(auto-detect)	Loader type (e.g., BinaryLoader)

Port Pool

Ports are allocated from a pool to prevent conflicts:

Variable	Default	Description
MCGHIDRA_PORT_START	8192	First port in the pool
MCGHIDRA_PORT_END	8319	Last port in the pool (128 ports)
MCGHIDRA_PORT_LOCK_DIR	/tmp/mcghidra-ports	Lock file directory

Port allocation uses flock-based locking for cross-process safety.

Raw Firmware Import

For binaries without recognized headers (raw firmware dumps, bootloader images):

docker_start(
    binary_path="/path/to/firmware.bin",
    language="ARM:LE:32:v4t",
    base_address="0x00000000"
)

When language is specified, loader is automatically set to BinaryLoader. This tells Ghidra to treat the file as raw bytes mapped at the given base address, rather than trying to parse it as an ELF, PE, or Mach-O.

To override the auto-loader (e.g., if you have an ELF but need a specific language):

docker_start(
    binary_path="/path/to/firmware.elf",
    language="ARM:LE:32:v7",
    loader="AutoImporter"
)

Container Lifecycle

Tool	Description
docker_auto_start	Find existing or start new container
docker_start	Start a container explicitly
docker_stop	Stop and remove a container
docker_health	Check if API is responding
docker_logs	View container output
docker_status	List all containers and images
docker_cleanup	Remove orphaned containers and stale locks
docker_session_info	Show this session’s containers

Input Validation

All firmware import parameters are validated before reaching the container:

• Language: Must match ARCH:ENDIAN:SIZE:VARIANT pattern (e.g., ARM:LE:32:v4t)
• Base address: Must be a valid hex string (e.g., 0x00000000 or 00000000), max 64-bit
• Loader: Must be alphanumeric with underscores (e.g., BinaryLoader)

Invalid values are rejected with a descriptive error before any Docker operations occur.