# Malware Analysis MCP server (Cursor MCP Server)

This is a **Cursor MCP (Model Context Protocol) server** that talks to the MalwareBazaar Community API/VirusTotal to provide **real-time threat intel / malware sample metadata (IOCs)** for authorized defensive research workflows.

> Note: `get_file` (malware binary download) is **disabled** in this project. This server provides **metadata/IOCs only**.

## What you get

- **Recent sample metadata** from MalwareBazaar (`get_recent`)
- **Detailed metadata** for a specific `sha256` (`get_info`)
- Samples associated with a specific **tag** (`get_taginfo`)
- VirusTotal analysis stats summary (`vt_lookup`)
- Telegram alerts (`send_alert`)
- Check a **local file** against MalwareBazaar/VirusTotal by hashing it (`check_local_file`)
- Suggested **analysis blogs/resources** for a malware family/signature (`suggest_analysis_blogs`)

## Requirements

- Windows 10+
- Node.js (recommended LTS)
- `npm`

## Install

Inside the project folder:

```bash
npm install
```

## Configure (.env)

Set these in the root `.env` file:

```env
PORT=3000

# MalwareBazaar (required)
MB_AUTH_KEY=YOUR_ABUSECH_AUTH_KEY

# VirusTotal (optional - only for vt_lookup)
VT_API_KEY=YOUR_VT_KEY

# Telegram (optional - only for send_alert)
TG_BOT_TOKEN=YOUR_BOT_TOKEN
TG_CHAT_ID=YOUR_CHAT_ID
```

- **Where to get `MB_AUTH_KEY`**: `https://auth.abuse.ch/`

## Cursor MCP setup (important)

Cursor runs MCP servers from `mcp.json`.

For this repo, the **global Cursor config** file `c:\Users\user\.cursor\mcp.json` contains a `malware-mcp` entry that runs using stdio transport:

- `cmd.exe /c npx -y ts-node ${workspaceFolder}/mcp-server.ts`
- Automatically loads `.env` via `envFile: ${workspaceFolder}/.env`

### After changing config

- Restart Cursor (or reload MCP) so the new config is loaded.

## Run (manual testing)

You can also run it locally:

```bash
npx ts-node mcp-server.ts
```

This is a **stdio MCP server**, so you won’t see “web server style” output—Cursor/the MCP host will communicate over the MCP protocol.

## MCP Tools

### help

Prints a quick usage guide listing all tools and example prompts/args.

**Input**

- none

**Example**

```text
Run help
```

### get_recent

Get recent sample metadata from MalwareBazaar.

**Input**

- `limit` (1..100, default 10)
- `selector` (`"100"` or `"time"`, default `"100"`)

**Example**

```json
{ "limit": 10, "selector": "100" }
```

### get_info

Get full metadata for a specific sample.

**Input**

- `hash` (sha256 string)

**Example**

```json
{ "hash": "81ddacc1d4689616b993f34465cb372e6046c035b45a4831343bd55ed37d48ee" }
```

### get_taginfo

Get samples associated with a specific tag.

**Input**

- `tag` (required)
- `limit` (1..1000, default 100)

**Example**

```json
{ "tag": "TrickBot", "limit": 50 }
```

### virustotal_lookup (alias: vt_lookup)

VirusTotal analysis stats summary.

**Input**

- `hash` (sha256 string)

**Example**

```json
{ "hash": "81ddacc1d4689616b993f34465cb372e6046c035b45a4831343bd55ed37d48ee" }
```

### send_alert

Send a message via your Telegram bot.

**Input**

- `message` (string)

**Example**

```json
{ "message": "🚨 New malware sample: <sha256> ..." }
```

### get_file (disabled)

This tool is intentionally **disabled** because it would involve downloading live malware binaries.

### check_local_file

Compute the **SHA256** of a local file (on this PC) and check whether it matches a known entry in MalwareBazaar. Optionally also performs a **VirusTotal** lookup by SHA256 (requires `VT_API_KEY`).

**Input**

- `path` (string, required): absolute path to the file
- `vt` (boolean, optional, default `true`): also run VirusTotal lookup

**Example**

```json
{ "path": "C:\\\\Users\\\\user\\\\Downloads\\\\somefile.exe", "vt": true }
```

### suggest_analysis_blogs

Suggests relevant **analysis blogs/resources** for the same malware family/signature (Malpedia / MITRE / abuse.ch / vendor writeups).  
You can pass a **signature name** directly, or pass a **hash** and it will try to resolve the signature via MalwareBazaar first.

**Input**

- `signature` (string, optional)
- `hash` (string, optional; sha256 recommended)

**Examples**

```json
{ "signature": "HijackLoader" }
```

```json
{ "hash": "4f9669712b6cd325eba9e94faf73a7d6ac29cdb724e857f5693aebe542f64b94" }
```

## Utility Tools (encoding/encryption/compression/analysis)

These tools run **offline** (no uploads) and are useful for quick data transformations and analysis.

### base64_encode

```json
{ "text": "hello" }
```

### base64_decode

```json
{ "base64": "aGVsbG8=" }
```

### url_encode / url_decode

```json
{ "text": "a+b c" }
```

### hex_encode / hex_decode

```json
{ "text": "hello" }
```

### gzip_compress

Compress UTF-8 text and return **base64**.

```json
{ "text": "hello" }
```

### gzip_decompress

Decompress from **base64** (gzip bytes) back to UTF-8.

```json
{ "base64": "<gzip_base64>" }
```

### hash_text

```json
{ "alg": "sha256", "text": "hello" }
```

### entropy

```json
{ "text": "hello" }
```

### hexdump_text

```json
{ "text": "hello", "limitBytes": 256 }
```

### aes_gcm_encrypt

Encrypt UTF-8 text using AES-256-GCM with PBKDF2-derived key (password + salt). Returns a JSON envelope.

```json
{ "text": "secret", "password": "pass123", "salt": "cyberchef-lite" }
```

### aes_gcm_decrypt

```json
{ "envelope": "{...json...}", "password": "pass123" }
```

## Files

- `mcp-server.ts`: **Real MCP stdio server** (recommended for Cursor MCP)

## Troubleshooting

- **`MalwareBazaar Auth-Key missing`**: set `MB_AUTH_KEY` in `.env`.
- **Tools not showing in Cursor**: restart Cursor and check MCP Logs.
- **`VT API key missing`**: `vt_lookup` requires `VT_API_KEY` in `.env`.
- **`VT API key missing`**: `virustotal_lookup` (or `vt_lookup`) requires `VT_API_KEY` in `.env`.
- **Telegram errors**: verify `TG_BOT_TOKEN` and `TG_CHAT_ID`.