APT Analysis MCP Server

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 SHA25