English | 한국어

NexusCore MCP is an advanced Model Context Protocol (MCP) server specifically designed for AI-driven dynamic malware analysis. It bridges the gap between Large Language Models (LLMs) like Claude/GPT-4 and low-level system instrumentation, enabling AI agents to actively debug, inspect, and analyze evasive malware in real-time.

Why NexusCore? Traditional sandboxes give you a static report. NexusCore allows an AI agent to interactively manipulate malware execution—bypassing anti-debugging checks (Themida/VMProtect) via Frida, dumping memory, and performing forensic triage on the fly.

• Architecture
• Features & Tools
• Prerequisites
• Quick Start
• AI Integration Guide
• Usage Examples
• Tool Reference
• Analysis Scenarios
• Troubleshooting
• Disclaimer

graph TD
    A["AI Agent (Claude/Cursor)"] -- "MCP Protocol (Stdio)" --> B["NexusCore MCP Server"]
    
    subgraph "Core Analysis Engine"
        B -- "Persistent DB" --> C[("Sled Cache / Job Queue")]
        B -- "Large Data" --> D["StreamManager (Dumps)"]
        B -- "Observability" --> E["OpenTelemetry (Jaeger)"]
    end
    
    subgraph "SOTA Analysis Tools"
        B -- "Micro-Emu" --> F["Unicorn Engine"]
        B -- "Ref Bridge" --> G["Ghidra/IDA/x64dbg"]
        B -- "Py Sandbox" --> H["AI Decryptor Tester"]
        B -- "Self-Correction" --> I["YARA Verifier"]
    end
    
    subgraph "Host OS (Virtualized)"
        B -- "Inject" --> J["Frida Engine (Stealth)"]
        B -- "API" --> K["External (DIE, Capa, PE-Sieve)"]
    end

• SHA256 Caching: Die/Capa/Floss results cached by file hash (1hr TTL)
• Batch Buffering: Frida IPC batching for 10x less overhead
• Async I/O: spawn_blocking for file operations
• Standardized JSON: Unified response format with timing metadata

Before you begin, ensure you have:

• OS: Windows 10/11 (x64) - Preferably a clean Virtual Machine (VirtualBox/VMware)
• RAM: 4GB+ recommended
• Disk Space: 5GB+ for tools and dependencies

• Chocolatey - Package manager
• Rust (1.70+) - Compiler toolchain
• Visual C++ Build Tools - MSVC linker
• Python 3.8+ - For some analysis tools
• Git - Version control

• Detect It Easy (DIE) - Packer/compiler detection
• CAPA - Capability analysis
• FLOSS - String extraction
• Sysinternals Suite - Process utilities

• CAPEv2 Sandbox - Remote malware submission (self-hosted or public instance)
• Frida - Dynamic instrumentation (auto-configured)

git clone https://github.com/sjkim1127/Nexuscore_MCP.git
cd Nexuscore_MCP

We provide an All-in-One PowerShell script that configures your entire analysis environment.

Run as Administrator in PowerShell:

Set-ExecutionPolicy Bypass -Scope Process -Force
.\scripts\setup_tools.ps1

This script will:

• ✅ Install Chocolatey package manager
• ✅ Install Rust, Python, Git, 7-Zip, and Visual C++ Build Tools
• ✅ Download DIE, CAPA, FLOSS, and Sysinternals tools to .\bin\
• ✅ Add tools to your system PATH

⏱️ Expected time: 10-15 minutes (depending on internet speed)

After installation completes, restart your terminal to apply PATH changes.

Create a .env file in the root directory:

# .env - Configuration File
CAPE_API_URL=http://192.168.1.100:8000    # Your CAPEv2 instance (optional)
CAPE_API_TOKEN=your_token_here             # API token if required (optional)
RUST_LOG=info                              # Log level (trace, debug, info, warn, error)

Note: If you don't have a CAPEv2 sandbox, you can skip this or use a public instance. The other tools will work independently.

cargo build --release

Build time: 5-10 minutes (first build compiles all dependencies)

Run the MCP server standalone to verify it works:

.\target\release\nexuscore_mcp.exe

You should see:

[INFO] Starting NexusCore MCP Server (RMCP Standard)...
[INFO] Listening on Stdio...

Press Ctrl+C to stop. The server is now ready to integrate with AI clients.

1. Locate your Claude Desktop config file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Edit the config file and add NexusCore MCP:

{
  "mcpServers": {
    "nexuscore": {
      "command": "C:\\Path\\To\\NexusCore_MCP\\target\\release\\nexuscore_mcp.exe",
      "args": [],
      "env": {
        "CAPE_API_URL": "http://127.0.0.1:8000",
        "RUST_LOG": "info"
      }
    }
  }
}

Important: Replace C:\\Path\\To\\NexusCore_MCP with your actual installation path. Use double backslashes (\\) in Windows paths.

1. Restart Claude Desktop completely (Quit and reopen)

2. Verify installation: Start a new chat and type:

   Can you list all available NexusCore tools?
   

   Claude should respond with a list of malware analysis tools.

1. Open Cursor Settings → MCP Servers

2. Click Add Server and enter:

   • Name: NexusCore
   • Command: C:\Path\To\NexusCore_MCP\target\release\nexuscore_mcp.exe
   • Environment Variables:
     • CAPE_API_URL: http://127.0.0.1:8000
     • RUST_LOG: info

3. Save and restart Cursor

Add the server configuration to your client's MCP settings using stdio transport:

• Command: Path to nexuscore_mcp.exe
• Transport: Stdio (stdin/stdout)
• Protocol: MCP (Model Context Protocol)

Here are real-world conversations showing how to interact with NexusCore through AI agents:

You: I have a suspicious file "invoice.exe". Can you analyze it?

Claude: I'll help you analyze invoice.exe. Let me start with static analysis.

[Claude calls die_scan tool]

Claude: The file is detected as:
- Compiler: Microsoft Visual C++ 8.0
- Packer: **UPX 3.96**
- Entropy: High (7.2/8.0) - Likely packed

Let me check for malware capabilities:

[Claude calls capa_scan]

Claude: CAPA detected the following capabilities:
- ✅ Network communication (HTTP)
- [X] Custom Dashboard UI
- [X] Integration with code analysis (Copilot / DeepSeek)
- [ ] Automated Deobfuscation
- [ ] Sandboxed macOS execution

## Creating Custom Tools

You can easily extend NexusCore MCP by creating and registering your own custom tools using the `Tool` trait and `inventory` crate. No need to touch the central server registry!

### 1. Implement the `Tool` trait

Create a new file for your tool, e.g., `src/tools/custom/my_tool.rs`:

```rust
use crate::tools::Tool;
use async_trait::async_trait;
use serde_json::Value;
use anyhow::Result;

pub struct MyCustomTool;

#[async_trait]
impl Tool for MyCustomTool {
    fn name(&self) -> &str {
        "my_custom_tool"
    }

    fn description(&self) -> &str {
        "A custom tool that does something awesome."
    }

    // You can optionally override `schema` to define JSON Schema parameters
    
    async fn execute(&self, args: Value) -> Result<Value> {
        // Your logic here
        Ok(serde_json::json!({
            "status": "success",
            "message": "Hello from custom tool!"
        }))
    }
}

// Automatically register the tool
inventory::submit! {
    crate::tools::ToolRegistration::new(|| std::sync::Arc::new(MyCustomTool))
}

Make sure your tool's module is included in the project tree. For example, add pub mod my_tool; in src/tools/custom/mod.rs. The inventory::submit! macro will automatically register your tool into the system dynamically at startup!

This project is licensed under the MIT License. Recommendation: This is likely malware. Proceed with dynamic analysis in a VM?

### Example 2: Bypassing Anti-Debug Protection

You: The malware crashes when I debug it. Can you help?

Claude: This suggests anti-debugging protection. I'll spawn it in stealth mode.

[Claude calls spawn_process with stealth=true]

Claude: Process spawned (PID: 4568) with Frida stealth hooks:

• IsDebuggerPresent() → FALSE
• NtQueryInformationProcess() → Patched
• CheckRemoteDebuggerPresent() → Bypassed

The process is now suspended. Let me scan for persistence:

[Claude calls scan_persistence]

Claude: Found persistence mechanism:

• Location: HKCU\Software\Microsoft\Windows\CurrentVersion\Run
• Key: "WindowsUpdate"
• Value: C:\Users\Admin\AppData\Roaming\svchost.exe

Should I resume the process and monitor its behavior?

### Example 3: Unpacking and Dumping (experimental)

You: Can you unpack this Themida-protected binary?

Claude: I'll attempt to find the Original Entry Point (OEP).

[Claude calls spawn_process, then find_oep (experimental)]

Claude: OEP Analysis:

• Current EIP: 0x004015A0 (Themida stub)
• Detected unpacking loop at 0x00401200
• OEP candidate: 0x00405000 (after 2,450 instructions)

Let me attach and dump the process memory:

[Claude calls attach_process, then memory dump]

Claude: Memory dumped (520 KB). Now fixing the Import Address Table:

[Claude calls iat_fixer]

Claude: IAT reconstructed with 89 imports. The unpacked binary is ready: 📁 Output: invoice_unpacked.exe

Would you like me to analyze the unpacked code with CAPA?

### Example 4: Network Behavior Analysis

You: What network connections does this malware make?

Claude: Let me spawn the process and monitor its behavior.

[Claude calls spawn_process, scan_handles]

Claude: Detected network activity:

• TCP connection to 192.168.45.23:8080
• HTTP User-Agent: "Mozilla/5.0"
• Mutex: Global{5F2A8C9D-1234}

Let me check if this IP is known malicious... [Continues analysis]

---

## 📚 Analysis Scenario: "Cracking Themida"

1.  **Initial Triage**:
    *   Agent calls `die_scan` -> Result: "Themida / WinLicense 2.x".
    *   Agent calls `cape_submit` -> Result: "Timeout / Crashed" (Sandbox evasion detected).
2.  **Stealth Execution**:
    *   Agent calls `spawn_process(path="malware.exe", stealth=true)`.
    *   NexusCore spawns process bundled with `stealth_unpacker.js` to hook `IsDebuggerPresent` and `NtQueryInformationProcess`.
3.  **Behavior Monitoring**:
    *   Agent calls `scan_handles` to find Mutex `Global\GoGoMalware`.
    *   Agent calls `scan_persistence` and finds `HKCU\..\Run\Updater`.
4.  **dumping & Fixing**:
    *   Agent identifies unpacked code region.
    *   Agent calls `iat_fixer` to rebuild the binary.

---

## 🔧 Tool Reference

Complete reference for all available tools with parameters and response formats.

### Process Management Tools

#### `spawn_process`
Spawns a process in suspended state with optional Frida instrumentation.

**Parameters:**
```json
{
  "path": "C:\\malware\\sample.exe",
  "stealth": true,              // Optional: Enable anti-debug bypass
  "args": ["--config", "test"]  // Optional: Command-line arguments
}

Response:

{
  "pid": 4568,
  "status": "suspended",
  "stealth_enabled": true
}

Attaches to an existing running process.

Parameters:

{
  "pid": 4568
}

Resumes a suspended process.

Parameters:

{
  "pid": 4568
}

Injects custom Frida JavaScript into a process.

Parameters:

{
  "pid": 4568,
  "script": "console.log('Hooked!'); Interceptor.attach(...);"
}

Detects packers, compilers, and protectors using Detect It Easy.

Parameters:

{
  "file_path": "C:\\malware\\sample.exe"
}

Response:

{
  "detections": ["UPX 3.96", "MSVS 2019"],
  "entropy": 7.2,
  "file_type": "PE32"
}

Analyzes malware capabilities using CAPA.

Parameters:

{
  "file_path": "C:\\malware\\sample.exe"
}

Response:

{
  "capabilities": [
    "create TCP socket",
    "enumerate files",
    "create registry key"
  ]
}

Extracts obfuscated strings using FLOSS.

Parameters:

{
  "file_path": "C:\\malware\\sample.exe"
}

Finds the Original Entry Point of packed executables.

Parameters:

{
  "pid": 4568,
  "max_instructions": 10000
}

Response:

{
  "oep_address": "0x00405000",
  "instructions_traced": 2450
}

Disassembles code at a specific address.

Parameters:

{
  "pid": 4568,
  "address": "0x00401000",
  "length": 100
}

Fixes PE headers and sections of dumped executables.

Parameters:

{
  "input_file": "C:\\dumps\\memory.bin",
  "output_file": "C:\\dumps\\fixed.exe"
}

Rebuilds Import Address Table using Scylla.

Parameters:

{
  "pid": 4568,
  "dump_file": "C:\\dumps\\memory.bin"
}

Scans for persistence mechanisms.

Parameters:

{
  "scan_registry": true,
  "scan_startup": true
}

Response:

{
  "registry_keys": [
    {
      "hive": "HKCU",
      "path": "Software\\Microsoft\\Windows\\CurrentVersion\\Run",
      "name": "Updater",
      "value": "C:\\malware.exe"
    }
  ],
  "startup_files": []
}

Lists open handles and mutexes of a process.

Parameters:

{
  "pid": 4568
}

Response:

{
  "handles": [
    {
      "type": "File",
      "name": "C:\\Windows\\System32\\notepad.exe"
    },
    {
      "type": "Mutant",
      "name": "Global\\MyMalwareMutex"
    }
  ]
}

Submits a sample to CAPEv2 sandbox.

Parameters:

{
  "file_path": "C:\\malware\\sample.exe",
  "timeout": 300
}

Response (asynchronous job):

{
  "job_id": "job_...",
  "status": "Processing in background. Use check_job_status tool to poll.",
  "tool": "cape_submit"
}

Solution:

• Ensure you built the project: cargo build --release
• Use the full absolute path in your config: C:\\Users\\YourName\\NexusCore_MCP\\target\\release\\nexuscore_mcp.exe
• Use double backslashes (\\) in Windows paths

Solution:

• Run Claude Desktop/Cursor as Administrator
• Ensure the target executable exists and has read permissions
• Check if antivirus is blocking execution
• Verify Frida is installed: pip install frida-tools

Solution:

• Re-run the setup script: .\scripts\setup_tools.ps1

• Manually add tools to PATH:

  $env:Path += ";C:\NexusCore_MCP\bin\DetectItEasy"
  $env:Path += ";C:\NexusCore_MCP\bin\Capa"

• Restart your terminal

Solution:

• Install Visual C++ Build Tools:

  choco install visualcpp-build-tools -y

• Or download from: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022

Solution:

• Verify CAPE is running: Open http://127.0.0.1:8000 in a browser
• Check .env file has correct CAPE_API_URL
• CAPE submission is optional - other tools work independently

Solution:

• Run your MCP client (Claude Desktop/Cursor) as Administrator
• Some system processes are protected - use a VM for malware analysis

Enable verbose logging by setting in your .env:

RUST_LOG=debug

View logs in real-time:

.\target\release\nexuscore_mcp.exe 2> debug.log

• Issues: GitHub Issues
• Documentation: Check the /docs folder (if available)
• Community: Join discussions in the repository

This tool is intended for authorized security research and malware analysis only. The authors and contributors are not responsible for any misuse or damage caused by this software. Always run malware in an isolated Virtual Machine.

MIT License