# 🦊 SuricataMCP Server

**Turn Claude Desktop into a network security analyst.**

A comprehensive Model Context Protocol (MCP) server that connects Claude Desktop to Suricata IDS/IPS. Analyze PCAPs, manage detection rules, and lint rule quality — all through natural language. Built from scratch with Python and FastMCP.

![Python](https://img.shields.io/badge/Python-3.10+-blue) ![Suricata](https://img.shields.io/badge/Suricata-7.x%20|%208.x-orange) ![Tools](https://img.shields.io/badge/MCP_Tools-18-green) ![License](https://img.shields.io/badge/License-MIT-yellow)

---

## What This Does

Instead of running Suricata from the terminal, writing grep pipelines to search rules, and manually linting signatures, you talk to Claude and it does it for you. Ask Claude to:

- *"What version of Suricata is installed?"* → Runs `suricata -V`
- *"Analyze this PCAP file for threats"* → Runs Suricata against a PCAP and returns parsed alerts, stats, and EVE JSON events
- *"Show me all enabled rules related to DNS tunneling"* → Searches 64,000+ rules instantly
- *"Check this rule for quality issues"* → Runs suricata-check and returns actionable feedback
- *"Disable rule SID 2100498"* → Comments out the rule with automatic backup
- *"Write a rule to detect HTTP traffic to evil.com and validate it"* → Creates the rule, validates syntax through Suricata's engine, and lints it for best practices

All results come back in the chat. No terminal switching. No manual log parsing.

---

## 🛠️ Integrated Tools (18)

### Core Suricata (7 tools)
| Tool | Description |
|------|-------------|
| **get_suricata_version** | Get installed Suricata version |
| **get_suricata_help** | Get CLI help output |
| **get_suricata_build_info** | Get build info — features, libraries, compile flags |
| **analyze_pcap** | Full PCAP analysis — alerts, stats, and EVE JSON events |
| **get_alerts_from_pcap** | Alerts only from a PCAP file (parsed fast.log) |
| **get_stats_from_pcap** | Stats only from a PCAP file |
| **get_eve_events_from_pcap** | EVE JSON events, filterable by type (alert, dns, http, tls, flow) |

### Rule Analysis — via suricata-check (3 tools)
| Tool | Description |
|------|-------------|
| **analyze_rule** | Lint a single rule for quality issues |
| **analyze_rule_with_checkers** | Lint with specific checker include/exclude patterns |
| **analyze_ruleset_file** | Lint an entire .rules file and get a summary |

### Rule Management (8 tools)
| Tool | Description |
|------|-------------|
| **list_rules** | List/search rules with filtering (enabled/disabled/keyword) |
| **get_rule_by_sid** | Look up a specific rule by SID |
| **enable_rule** | Uncomment a disabled rule |
| **disable_rule** | Comment out an enabled rule |
| **add_rule** | Append a new rule to the rules file |
| **edit_rule** | Replace a rule by SID |
| **delete_rule** | Remove a rule by SID |
| **validate_rule_syntax** | Validate rule syntax through Suricata's engine |

### Key Features
- **Structured output**: Alerts parsed into structured dicts, not raw log lines
- **EVE JSON support**: Full access to Suricata's rich JSON event output
- **Automatic backups**: Every rule modification creates a timestamped backup
- **Cross-platform**: Works on Linux, macOS, and Windows
- **Environment-based config**: All settings via `.env` or environment variables
- **Graceful degradation**: suricata-check is optional — core tools work without it

---

## 🚀 Quick Start

### Prerequisites
- **Python 3.10+**
- **Suricata** installed ([download](https://suricata.io/download/))
- **Claude Desktop**

### 1. Clone the Repository

```bash
git clone https://github.com/Hackerobi/suricata-mcp-server.git
cd suricata-mcp-server
```

### 2. Create Virtual Environment and Install Dependencies

```bash
python3 -m venv .venv
source .venv/bin/activate    # Linux/Mac
# .venv\Scripts\activate     # Windows

pip install -r requirements.txt
```

### 3. Install suricata-check (Optional — for rule analysis tools)

```bash
pip install suricata-check
```

### 4. Install Suricata (if not already installed)

```bash
# Ubuntu/Debian
sudo add-apt-repository ppa:oisf/suricata-stable
sudo apt update
sudo apt install suricata

# Verify
suricata -V
```

### 5. Download Detection Rules

```bash
sudo suricata-update
```

This fetches the Emerging Threats Open ruleset (~64,000 rules) to `/var/lib/suricata/rules/suricata.rules`.

### 6. Configure

```bash
cp .env.example .env
# Edit .env if your paths differ from defaults
```

### 7. Test the Server

```bash
# Start the server
python server.py

# Or run the test suite
sudo .venv/bin/python test_tools.py
```

### 8. Configure Claude Desktop

Add to your Claude Desktop profile config (e.g., `~/.config/Claude/profiles/SOC.json` on Linux):

```json
{
  "mcpServers": {
    "SuricataMCP": {
      "command": "sudo",
      "args": [
        "/path/to/suricata-mcp-server/.venv/bin/python",
        "/path/to/suricata-mcp-server/server.py"
      ],
      "cwd": "/path/to/suricata-mcp-server"
    }
  }
}
```

> **Note:** `sudo` is needed because Suricata's rules and config files are root-owned. For passwordless operation, add to sudoers:
> ```
> youruser ALL=(root) NOPASSWD: /path/to/.venv/bin/python /path/to/server.py
> ```

### 9. Restart Claude Desktop

The SuricataMCP tools will appear automatically. Start analyzing.

---

## 🔑 Environment Variables

All settings are prefixed with `SURICATA_MCP_` and can be set in `.env` or as environment variables.

| Variable | Default (Linux) | Description |
|----------|----------------|-------------|
| `SURICATA_MCP_SURICATA_DIR` | `/usr/bin` | Directory containing Suricata binary |
| `SURICATA_MCP_SURICATA_EXE` | `suricata` | Suricata executable name |
| `SURICATA_MCP_RULES_FILE` | `/var/lib/suricata/rules/suricata.rules` | Default rules file path |
| `SURICATA_MCP_SURICATA_CONFIG` | `/etc/suricata/suricata.yaml` | Suricata YAML config |
| `SURICATA_MCP_COMMAND_TIMEOUT` | `300` | Max seconds for Suricata commands |

---

## 💡 Usage Examples

### PCAP Threat Analysis
> "Analyze the PCAP at /tmp/suspicious_traffic.pcap and show me all alerts"

Claude runs `analyze_pcap` → returns structured alerts with timestamps, SIDs, and messages.

### Rule Quality Audit
> "Check this rule for issues: `alert tcp any any -> any 443 (msg:"TLS to suspicious port"; sid:1000001; rev:1;)`"

Claude runs `analyze_rule` → returns 10+ actionable suggestions for metadata, content matching, SID ranges, and best practices.

### Rule Search and Management
> "Find all enabled rules related to SQL injection, then disable SID 2006546"

Claude chains: `list_rules` (search="sql injection", enabled_only=True) → `disable_rule` (sid=2006546)

### Syntax Validation
> "Write a rule to detect HTTP POST requests to /admin/upload and validate it"

Claude writes the rule → runs `validate_rule_syntax` through Suricata's engine → fixes any errors → confirms it's valid.

### EVE JSON Deep Dive
> "Run this PCAP through Suricata and show me all DNS queries"

Claude runs `get_eve_events_from_pcap` with event_type="dns" → returns structured DNS query/response data.

### Combined Workflow
> "Analyze this PCAP, check what rules triggered, then lint those rules for quality improvements"

Claude chains: `analyze_pcap` → extracts SIDs from alerts → `get_rule_by_sid` for each → `analyze_rule` on each → synthesizes a report.

---

## 🔒 Security

- **Automatic backups**: Every rule file modification creates a timestamped `.backup_YYYYMMDD_HHMMSS.rules` file
- **Input validation**: Rules are validated before being added (must have action, SID)
- **Least privilege sudo**: Configure sudoers for only the specific server command
- **No destructive defaults**: The server never modifies rules without explicit tool calls
- **Never commit** `.env` to version control

---

## 📁 Project Structure

```
suricata-mcp-server/
├── server.py              # FastMCP server — all 18 tools
├── config.py              # Pydantic-settings configuration
├── test_tools.py          # Integration test script
├── requirements.txt       # Python dependencies
├── .env.example           # Configuration template
├── .gitignore
├── suricatamcp.service    # Systemd service for background running
└── README.md
```

---

## 🔧 Running as a Background Service

Install the systemd service for automatic startup:

```bash
sudo cp suricatamcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable suricatamcp
sudo systemctl start suricatamcp

# Check status
sudo systemctl status suricatamcp

# View logs
sudo journalctl -u suricatamcp -f
```

---

## 🧪 Running Tests

```bash
# Activate venv
source .venv/bin/activate

# Run with sudo (needed for rules file access)
sudo .venv/bin/python test_tools.py
```

---

## 🏗️ Built With

- **[Suricata](https://suricata.io/)** — Open-source IDS/IPS engine by OISF
- **[suricata-check](https://suricata-check.teuwen.net/)** — Rule quality analysis library
- **[FastMCP](https://github.com/jlowin/fastmcp)** — Python MCP server framework
- **[pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)** — Environment-based configuration

Inspired by [Medinios/SuricataMCP](https://github.com/Medinios/SuricataMCP) — rebuilt from scratch with full rule management and analysis capabilities.

---

## ⚠️ Disclaimer

This project is not affiliated with the OISF (Open Information Security Foundation) or the official Suricata project. It is an independent MCP integration built for security analysis workflows. Always ensure you have proper authorization before analyzing network traffic.

---

## 🤝 Contributing

Pull requests welcome. To add a new tool:

1. Add the function in `server.py` with the `@mcp.tool()` decorator
2. Add a test case in `test_tools.py`
3. Update this README
4. Submit a PR

---

## 📬 Contact

- **Discord:** sgtwolf787
- **GitHub:** [@Hackerobi](https://github.com/Hackerobi)

White hat or no hat 🎩

---

*Built with Claude. Tested with Suricata 8.0.3 and 64,357 ET Open rules. Stay legal.*