# APT Analysis MCP Server

An MCP (Model Context Protocol) server designed to assist in APT (Advanced Persistent Threat) malware analysis. Currently provides tools for securely downloading samples via a jump server.

## Features

- **Sample Downloader**: Securely download malware samples from a remote server via a jump host using SSH/SCP.
- **Rule Hash Query**: Query sample hashes associated with YARA rules by rule name and namespace.
- **Integrated Workflow**: Download samples directly by YARA rule name.

## Installation

1.  **Clone the repository:**
    ```bash
    git clone https://github.com/zrax-x/apt-analysis-mcp.git
    cd apt-analysis-mcp
    ```

2.  **Install dependencies:**
    It is recommended to use a virtual environment.
    ```bash
    python -m venv .venv
    .venv\Scripts\activate  # Windows
    # source .venv/bin/activate # Linux/Mac
    pip install -r requirements.txt
    ```

## Configuration

1.  **Copy the example configuration:**
    ```bash
    copy config.example.json config.json
    ```

2.  **Edit `config.json`:**
    Fill in your SSH details for the jumper and target servers, specify the local download directory, and configure the Rule Hash Mapping file path.

    ```json
    {
      "jumper": {
        "user": "your_jumper_user",
        "host": "jump_server_ip",
        "port": 22,
        "key": "~/.ssh/id_rsa_jumper"
      },
      "target": {
        "user": "your_target_user",
        "host": "target_server_ip",
        "port": 22,
        "workdir": "/path/to/target/workdir",
        "key": "~/.ssh/id_rsa_target"
      },
      "local_download_dir": "/path/to/local/samples",
      "rule_hash_mapping_file": "/path/to/Rule_Hash_Mapping.csv"
    }
    ```

    **Configuration Fields:**
    - `jumper`: Jump server (bastion host) SSH configuration
    - `target`: Target server SSH configuration where samples are stored
    - `local_download_dir`: Local directory to save downloaded samples
    - `rule_hash_mapping_file`: Path to the Rule_Hash_Mapping.csv file (absolute path recommended)

3.  **Generate Rule Hash Mapping:**
    The server requires a `Rule_Hash_Mapping.csv` file. Generate it by running:
    ```bash
    cd /path/to/yara_rules_parent_directory
    python3 build_rule_hash_mapping.py
    ```
    This will scan all YARA rules and create the mapping table. Then update the `rule_hash_mapping_file` path in `config.json` to point to this file.

## Usage with Claude Desktop

Add the server to your `claude_desktop_config.json` (typically in `%APPDATA%\Claude\` on Windows).

```json
{
  "mcpServers": {
    "apt-analysis": {
      "command": "path/to/your/venv/Scripts/python.exe",
      "args": [
        "path/to/apt-analysis-mcp/server.py"
      ]
    }
  }
}
```

## Available Tools

### 1. download_samples
Download malware samples by SHA256 hash.

**Parameters:**
- `hash_list` (list[str]): List of SHA256 hashes to download
- `output_dir` (str, optional): Local directory to save samples to (defaults to `local_download_dir` in config)

**Example:**
```
Download samples with hashes: ["3123bbd5564f4381820fb8da5810bd4d9718b5c80a7e8f055961007c6f30daff", "..."]
```

**Returns:**
```
"Successfully downloaded samples to /path/to/samples"
```

---

### 2. get_rule_sha256_list
Get SHA256 hash list for a YARA rule (ready for downloading samples).

This tool queries the Rule_Hash_Mapping.csv file (configured in `config.json`) to retrieve SHA256 hashes associated with a specific YARA rule. The returned hashes can be directly used with the `download_samples` tool.

**Parameters:**
- `rule` (str, required): YARA rule name (e.g., "APT_xxx")
- `namespace` (str, optional): YARA file path for exact matching (e.g., "./yara_rules/xxx/pe_rules/abc.yara")
  - If not provided, returns all rules matching the rule name
  - If provided, returns only the exact match

**Example Usage:**
```
Get SHA256 list for rule: APT_xxx
```

**Returns:**
```json
{
  "success": true,
  "sha256_hashes": [
    "3123bbd5564f4381820fb8da5810bd4d9718b5c80a7e8f055961007c6f30daff",
    "123408972b8ec9c2e64eeb46ce1db92ae3c40bc8de48d278ba4d436fc3c8b3a4",
    "ffaab4463be9d8131f363fd78e21d9de5d838a3ec4044526aea45a473d6ddd61",
    "..."
  ],
  "count": 9,
  "error": null
}
```

**Error Response:**
```json
{
  "success": false,
  "sha256_hashes": [],
  "count": 0,
  "error": "No SHA256 hashes found for rule: nonexistent_rule"
}
```

**Notes:**
- The tool reads from the `rule_hash_mapping_file` configured in `config.json`
- Returns only SHA256 hashes (MD5 hashes are not included as downloads require SHA256)
- Automatically deduplicates hashes if a rule appears in multiple files
- If the mapping file is not found or not configured, returns an error

## Workflow Examples

### Example 1: Query and Download Samples
```
Step 1: Get SHA256 list for rule: APT_IN_xxx
Step 2: Download samples with the returned SHA256 hashes
```

### Example 2: Download Specific Rule Samples
```
1. Get SHA256 list for rule: M_Hunting_yyy
2. Copy the SHA256 hashes from the response
3. Download samples with those hashes to /home/user/samples
```

## Development

- **Add new tools**: Create new modules in `tools/` and register them in `server.py`.