# **CyberHawk Threat Intel**

<p align="center">
  <img src="https://media.cyberhawkthreatintel.com/general/1771234479938-y9566.png" alt="CyberHawk Threat Intel" width="160"/>
</p>

<h1 align="center">Security Onion MCP (Community Edition)</h1>
<p align="center">
  <strong>By <a href="https://www.cyberhawkthreatintel.com">CyberHawk Threat Intel</a></strong> · Rudra Verma | Senior Cyber Security Architect & Researcher
</p>

<p align="center">
  <em>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.</em>
</p>

---

> # ✅ **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.**

---

<p align="center">
  <img src="https://img.shields.io/badge/Security%20Onion-2.4%20CE-16a34a?style=flat-square" alt="Security Onion CE"/>
  <img src="https://img.shields.io/badge/No%20Pro%20License-required-brightgreen?style=flat-square" alt="No Pro License"/>
  <img src="https://img.shields.io/badge/Tools-21%20(read%20%2B%20write)-0066cc?style=flat-square" alt="21 tools"/>
  <img src="https://img.shields.io/badge/MCP-FastMCP%20(Python%203.12%2B)-8B5CF6?style=flat-square" alt="FastMCP"/>
  <img src="https://img.shields.io/badge/by-CyberHawk%20Threat%20Intel-0066cc?style=flat-square" alt="CyberHawk"/>
  <img src="https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square" alt="License"/>
</p>

---

## Why This Exists

The **official [securityonion-mcp](https://github.com/Security-Onion-Solutions/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).

```bash
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

```bash
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`](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

<p align="center">
  <a href="https://www.cyberhawkthreatintel.com">
    <img src="https://media.cyberhawkthreatintel.com/general/1771234479938-y9566.png" alt="CyberHawk Threat Intel" width="120"/>
  </a>
</p>

<p align="center">
  <strong>🦅 Sign up FREE → <a href="https://www.cyberhawkthreatintel.com">cyberhawkthreatintel.com</a></strong>
</p>

<p align="center">
  <a href="https://youtube.com/@cyberhawkconsultancy">YouTube @cyberhawkconsultancy</a> ·
  <a href="https://youtube.com/@cyberhawkk">YouTube @cyberhawkk</a> ·
  <a href="https://tiktok.com/@cyberhawkthreatintel">TikTok</a> ·
  <a href="https://x.com/cyberhawkintel">X @cyberhawkintel</a> ·
  <a href="https://t.me/cyberhawkthreatintel">Telegram</a>
</p>

<p align="center">
  <em>Rudra Verma | Senior Cyber Security Architect & Researcher | CyberHawk Threat Intel</em><br/>
  <em>Authorized security research & penetration testing only. Unauthorized use is illegal.</em>
</p>

<p align="center">
  #cyberhawkthreatintel &nbsp;#cyberhawkconsultancy &nbsp;#cyberhawkk &nbsp;#cybersecurity &nbsp;#ethicalhacking &nbsp;#pentesting &nbsp;#redteam &nbsp;#threatintel &nbsp;#infosec
</p>