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:

   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.

   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:

   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.

   {
     "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:

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

{
  "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:

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

Error Response:

{
  "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.