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

---

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)
• Claude Desktop

1. Clone the Repository

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

2. Create Virtual Environment and Install Dependencies

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)

pip install suricata-check

4. Install Suricata (if not already installed)

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

# Verify
suricata -V

5. Download Detection Rules

sudo suricata-update

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

6. Configure

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

7. Test the Server

# 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):

{
  "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:

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

# Activate venv
source .venv/bin/activate

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

---

🏗️ Built With

• Suricata — Open-source IDS/IPS engine by OISF
• suricata-check — Rule quality analysis library
• FastMCP — Python MCP server framework
• pydantic-settings — Environment-based configuration

Inspired by 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

White hat or no hat 🎩

---

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