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

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:

Returns:

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:

Returns:

Error Response:

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

Example 2: Download Specific Rule Samples

Development

• Add new tools: Create new modules in tools/ and register them in server.py.