<p align="center"> <img src="./assets/logo.png" alt="Joe Sandbox MCP banner"> </p>

Joe Sandbox MCP Server

A Model Context Protocol (MCP) server for interacting with Joe Sandbox Cloud.
This server exposes rich analysis and IOC extraction capabilities from Joe Sandbox and integrates cleanly into any MCP-compatible application (e.g. Claude Desktop, Glama, or custom LLM agents).

Features

• Flexible Submission: Submit local files, remote URLs, websites, or command lines for dynamic analysis.
• IOC Extraction: Retrieve indicators of compromise for dropped files, IPs, domains, and URLs.
• Signature Detections: Retrieve and extract actionable evidence from sandbox signatures.
• Process Trees: Visualize full execution hierarchies, including command lines and parent-child relationships.
• Unpacked PE Files: Download in-memory unpacked binaries extracted during execution, often revealing runtime payloads.
• PCAP Downloads: Retrieve the full network traffic capture (PCAP) recorded during analysis for offline inspection.
• LLM-Suitable Responses: All results are structured for clear consumption by language models, with truncation and relevant filtering.

Quick Start

Installation via uv (Recommended)

1. Clone the repository:

   git clone https://github.com/joesecurity/joesandboxMCP.git
   cd joesandboxMCP
   

2. Install dependencies using uv:

   uv venv
   uv pip install -e .
   

3. Launch the MCP server (see configuration below)

---

Example Configuration

{
  "mcpServers": {
    "JoeSandbox": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/joesandboxMCP",
        "run",
        "main.py"
      ],
      "env": {
        "JBXAPIKEY": "your-jbxcloud-apikey",
        "ACCEPTTAC": "SET_TRUE_IF_YOU_ACCEPT"
      }
    }
  }
}

Legal Notice

Use of this integration with Joe Sandbox Cloud requires acceptance of the Joe Security Terms and Conditions.

By setting the environment variable ACCEPTTAC=TRUE, you explicitly confirm that you have read and accepted the Terms and Conditions.

---

Available Tools

The Joe Sandbox MCP server provides a wide range of tools to help you interact with sandbox reports, monitor executions, and extract threat intelligence in a format that's easy for large language models to understand.

1. Submit Analysis

Submit files, URLs, websites, or command lines for sandbox analysis.
You can choose whether to wait for results or return immediately and check back later.
Supports various options like internet access, script logging, and archive passwords.

2. Search Past Analyses

Look up historical submissions using hashes, filenames, detection status, threat names, and more.
Quickly find whether something has already been analyzed.

3. Check Submission Status

Get the current status and key metadata for a previously submitted sample.
Includes detection verdict, systems used, and analysis score.

4. AI Summaries

Retrieve high-level reasoning statements generated by the sandbox's AI.
Helpful for understanding complex behavior in plain language.

5. Malicious Dropped Files

See which files were dropped during execution and marked as malicious.
Includes hash values, filenames, origin processes, and detection indicators.

6–8. Network Indicators

Show domains, IP addresses, or URLs contacted during analysis.
Can be filtered to focus only on clearly malicious items or high-confidence detections.
Includes details like IP resolution, geographic hints, communication context, and detection evidence.

9. Behavioral Detections (Signatures)

Get a summary of key behavioral detections triggered during execution.
Can be filtered to focus only on high impact items.

10. Process Tree

Visualize the full hierarchy of processes that ran during execution.
Shows parent-child relationships, command lines, and termination info.

11. Unpacked Binaries

Retrieve executable files that were unpacked or decrypted in memory.
Great for identifying payloads not visible in the original file.

12. Network Traffic (PCAP)

Download the full network packet capture recorded during analysis.
Useful for traffic inspection, C2 callbacks, or domain/IP extraction.

13. Recent Activity

List your most recent sandbox submissions and see what systems they ran on, how they scored, and what verdicts were returned.

---

License

This project is licensed under the MIT License.