# Joe Sandbox MCP Server

A Model Context Protocol (MCP) server for interacting with [Joe Sandbox Cloud](https://jbxcloud.joesecurity.org/).
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:

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

2. Install dependencies using `uv`:

```bash
uv venv
uv pip install -e .
```

3. Launch the MCP server (see configuration below)

---

## Example Configuration

```json
{
"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](https://jbxcloud.joesecurity.org/resources/termsandconditions.pdf).

---

## 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.

### 14. Memory Dumps
Retrieve raw memory dumps captured during runtime.

### 15. Dropped Files
Retrieve all files dropped during analysis.

---

## License

This project is licensed under the [MIT License](./LICENSE).

JoeSandboxMCP

README

Installation