Security Onion MCP (Community Edition)

By CyberHawk Threat Intel · Rudra Verma | Senior Cyber Security Architect & Researcher

A full Tier 2/3 SOC operator MCP for Security Onion — that works on the FREE Community Edition, where the official (Pro-only) MCP cannot.

---

✅ FULLY WORKING ON SECURITY ONION COMMUNITY EDITION — NO PAID LICENSE REQUIRED

This is a real, live-tested operator built specifically for the FREE Community Edition. Every tool here was proven against a live Security Onion 2.4.190 CE grid — read + write. You do not need a Pro/Enterprise license, and you do not need the Connect API. The official Security Onion MCP requires Pro; this one runs on the free edition the vast majority of people actually use.

---

---

Why This Exists

The official securityonion-mcp depends on the Connect API (Hydra) feature — which is Pro/Enterprise only. On the free Community Edition it has nothing to connect to, so it simply doesn't work.

This MCP works on Community Edition by talking to the grid the way an analyst already can:

• OpenSearch (HTTPS → :9200) for all read/hunt tools
• SSH (so-* commands + sudo, host-key pinned) for all write/operate tools

No license, no Connect API. And it's a full operator — 21 tools spanning query, hunt, triage, detection authoring & tuning, PCAP, agent enrollment, and gated grid ops — versus the official server's ~3 read-only tools.

Who is this for? SOC analysts and blue teams running Security Onion Community Edition who want an LLM operator that can actually do things on the grid, not just read a Pro one they don't have.

---

Official vs. This

	Official securityonion-mcp	This (CE)
Works on free Community Edition	❌ (needs Pro Connect API)	✅
License required	Pro / Enterprise	None
Tools	~3 (read-only)	21 (read + write)
Deploy / tune detections (Suricata, Sigma, YARA)	❌	✅
Elastic Agent enrollment, PCAP export, grid ops	❌	✅
Backend	Connect API	OpenSearch (read) + SSH so-* (write)

Honest caveat: the official server is vendor-supported and rides SO's internal plumbing. This one is community/DIY and reaches the same surface via OpenSearch + SSH. For a CE user, it's not "similar" — it's the only thing that runs, and it does far more.

---

Tools (21)

Connectivity & read/hunt (OpenSearch) — ping, grid_status, query_events (OQL: Lucene + | groupby / | table / | sortby), get_alerts, get_alert_detail, pivot_connection, zeek_logs, hunt, list_indices, detections_status, agent_list.

Write / operate (SSH so-*, all gated with confirm) — suricata_add_rule, suricata_remove_rule, suricata_tune, sigma_deploy, yara_deploy, pcap_retrieve, agent_installer, acknowledge_alert, case_create, grid_command.

Every write tool defaults to a dry-run, validates before applying (Suricata rules go through so-suricata-testrule), and returns exactly what changed — honest {"ok": false, ...} on failure, never a fabricated success.

---

Install

Requires Python 3.12+ and network reach to your SO manager on 9200 (OpenSearch) and 22 (SSH).

git clone <this-repo> securityonion-mcp && cd securityonion-mcp
python -m venv venv && venv\Scripts\activate      # Windows  (or: source venv/bin/activate)
pip install -r requirements.txt

# credentials live ONLY in an untracked .env.local (never commit real secrets)
copy .env.example .env.local                       # then fill it in (see below)

Fill .env.local:

Var	Value
SO_API_ENDPOINT	https://YOUR-SO-MANAGER:9200
SO_OS_USER / SO_OS_PASSWORD	so_elastic + its password (sudo cat /opt/so/conf/elasticsearch/curl.config on the manager)
SO_SSH_HOST / SO_SSH_USER / SO_SSH_PASSWORD	manager IP + a sudo-capable account
SO_SSH_HOSTKEY	the manager's ed25519 fingerprint — pin it (see .env.example for the one-liner)
SO_API_VERIFY_SSL	false for a lab self-signed cert, or set SO_CA_CERT and true

Register with Claude Code

claude mcp add securityonion -s user \
  --env-file /abs/path/to/.env.local \
  -- /abs/path/to/venv/bin/python -m security_onion_mcp.server

On Windows the command is the venv's python.exe (e.g. ...\venv\Scripts\python.exe -m security_onion_mcp.server), run with the package directory on PYTHONPATH or launched from it.

---

Usage Examples

"Ping the grid and show me the top firing rules over the last 7 days." → ping + query_events("tags:alert | groupby rule.name", "-7d", "now")

"What's noisiest, and tune the worst offender for our benign source." → get_alerts + suricata_tune(sid, "suppress", {"ip": "...", "reason": "..."})

"Write a Suricata rule for this indicator, test it, and deploy it." → suricata_add_rule(rule, confirm=True) (validate → local.rules → so-rule-update)

"Generate a Windows Elastic Agent installer for enrollment." → agent_installer("windows", confirm=True)

"Pull the packets between these two hosts." → pcap_retrieve(src_ip="...", dst_ip="...")

See TESTING.md for the three validation proofs (ping, read query, gated Suricata write) with live expected output.

---

Guardrails

• Secrets never touch tracked files or logs — env-only, .env.local git-ignored, redaction on logging.
• Writes are gated — confirm=False default; each returns exactly what changed.
• Validate before apply — Suricata rules pass so-suricata-testrule before any deploy.
• grid_command is a hard allow-list — never an arbitrary shell; destructive ops need confirm + reason.
• Honest results — a non-zero exit or non-2xx returns {"ok": false, ...}; CE-uncertain paths report the real mechanism used (or an honest "SOC-UI" fallback) rather than faking success.
• SSH host-key pinned — MITM on the control channel is refused.

---

Requirements & Compatibility

• Security Onion 2.4.x (built and validated against 2.4.190 CE). OpenSearch reachable on 9200; a sudo-capable SSH account on the manager.
• Enterprise Plus not required. (If you do have Pro, the official MCP is an option too — this one still adds the write/operate surface.)

---

Disclaimer

For authorized defensive security operations on Security Onion grids you own or are authorized to administer. All actions (querying events, exporting PCAP, deploying detections) are blue-team operations. Authorized security research & administration only. Unauthorized use is illegal.

---

Connect with CyberHawk Threat Intel

🦅 Sign up FREE → cyberhawkthreatintel.com

YouTube @cyberhawkconsultancy · YouTube @cyberhawkk · TikTok · X @cyberhawkintel · Telegram

Rudra Verma | Senior Cyber Security Architect & Researcher | CyberHawk Threat Intel
Authorized security research & penetration testing only. Unauthorized use is illegal.

#cyberhawkthreatintel  #cyberhawkconsultancy  #cyberhawkk  #cybersecurity  #ethicalhacking  #pentesting  #redteam  #threatintel  #infosec