REMnux

You can use the REMnux MCP Server to enable AI assistants to drive REMnux malware analysis tools from a flexible deployment, with secure guardrails and tool-guided reasoning. It provides a unified interface for local, Docker-based, or HTTP-connected operation, along with file-type aware analysis and structured outputs to streamline malware investigations.

How to use

You interact with the MCP server through your preferred MCP client. Choose a deployment mode that matches your environment, then configure the client to connect using the corresponding transport. The server can run locally on REMnux, connect to REMnux over Docker or SSH, or expose an HTTP endpoint for network access. Use the built-in tool guidance to have the AI select appropriate tools for each file type, and rely on the structured outputs to reason about results.

How to install

Prerequisites: install Node.js version 18 or later on the machine that will host the MCP client and, if using Docker or SSH, ensure you can access the REMnux system.

Scenario 1: AI Tool on Your Machine, REMnux as Docker/VM. Start the REMnux environment and connect via Docker or SSH.

# Start REMnux container (Docker mode, recommended)
docker run -d --name remnux remnux/remnux-distro:noble

# Connect Claude Code (stdio transport — server runs as a child process)
claude mcp add remnux -- npx @remnux/mcp-server --mode=docker --container=remnux

Scenario 1, alternative: use a VM and SSH transport.

# Start REMnux VM and provide SSH access

claude mcp add remnux -- npx @remnux/mcp-server --mode=ssh --host=YOUR_VM_IP --user=remnux --password=YOUR_PASSWORD

Claude Desktop / Cursor config (example): the following JSON config tells the client how to launch the MCP server.

{
  "mcpServers": {
    "remnux": {
      "command": "npx",
      "args": ["@remnux/mcp-server", "--mode=docker", "--container=remnux"]
    }
  }
}

How to install (continued)

Scenario 2: AI Tool and MCP Server both on REMnux. Run the server locally with a stdio transport. The simplest setup is to run the server on REMnux and let your AI tool connect locally.

{
  "mcpServers": {
    "remnux": {
      "command": "remnux-mcp-server"
    }
  }
}

How to install (continued)

Scenario 3: AI Tool on your machine, MCP server on REMnux exposed over HTTP. Start the server on REMnux with HTTP transport and a token, then connect your AI client over HTTP.

export MCP_TOKEN=$(openssl rand -hex 32)
remnux-mcp-server --mode=local --transport=http --http-host=0.0.0.0
echo "Token: $MCP_TOKEN"  # save this for the client

On your machine, configure the client to connect via HTTP with the token.

claude mcp add remnux --transport http http://REMNUX_IP:3000/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Additional setup notes

Security, file workflows, and tool guidance are built into the MCP server. You can enable optional REMnux documentation alongside the MCP server for richer tool documentation, but this is not required for operation.

Configuration and security considerations

HTTP transport requires a token for authentication. Bindings default to localhost; you may bind to all interfaces for network access if you need remote clients. Use a strong token and consider HTTPS with a reverse proxy. The server enforces anti-injection patterns and output budgets to protect the environment.

Troubleshooting

If you encounter connectivity or blocking issues, verify the deployment mode and the transport configuration. Common checks include ensuring the REMnux container is running for Docker mode, validating SSH access for SSH mode, and confirming the HTTP endpoint is reachable for HTTP transport.

Development

Developers can run the MCP server locally, build, test, and run integration tests. Typical steps involve installing dependencies, building the project, and starting the server in the desired mode. Use tests to verify SSH, Docker, and local flows.

Design notes

The server offers a unified connection layer that supports Docker exec, SSH, and local execution. It includes file-type-aware analysis, defense-in-depth guardrails, and a browsable tool registry for discovering available capabilities.

Security model and patterns

The security model relies on container/VM isolation as the primary boundary, with anti-injection patterns, restricted piping, and timeouts to mitigate misuse. Path sandboxing can be enabled to restrict file operations. This design aims to balance thorough malware analysis with operational safety.

Tools and capabilities overview

The MCP server exposes a range of tools and actions to perform malware analysis on REMnux samples. It includes commands to run tools, inspect files, extract IOCs, download artifacts, and obtain tool usage guidance. Output is structured to support AI reasoning with fields such as detected type, depth, and tool outputs.

Notes on usage guidance

Tools provide guidance and guardrails to help AI agents choose appropriate analyses for each file type. Outputs are designed to be neutral in labeling to reduce confirmation bias when evaluating results.

License

GPL-3.0 — see LICENSE

Available tools

run_tool

Execute a command in REMnux, supporting piped commands and redirections for comprehensive analysis.

get_file_info

Obtain file type, hashes, and basic metadata for a given file.

list_files

List files within the samples or output directories on REMnux.

extract_archive

Extract archives (.zip, .7z, .rar) with automatic password detection.

upload_from_host

Upload a file from the host into the REMnux samples directory with size limits.

download_from_url

Download a file from a URL into the REMnux samples directory with optional headers.

download_file

Download a file from the output directory back to the host, with optional password-protected archiving.

analyze_file

Auto-select and run REMnux tools based on detected file type for end-to-end analysis.

extract_iocs

Extract IOCs from text with confidence scoring and noise filtering.

suggest_tools

Detect file type and return recommended tools with analysis hints without executing tools.

get_tool_help

Retrieve usage help for any installed REMnux tool.

check_tools

Verify which REMnux analysis tools are installed and available.