From d3d81baee476b61411ede8be15ca4e91eb2c49e9 Mon Sep 17 00:00:00 2001 From: Solomon Neas Date: Fri, 26 Jun 2026 11:12:20 -0400 Subject: [PATCH] docs: OSS adoption upgrade Bring the README and maintainer-health files up to the adoption standard. README: - Prominent website link to lidless.dev/soc-stack near the top - Live CI and release status badges plus the existing tool badges - Sharpened first paragraph: what / why / how it differs - New keyword-rich "What it does" section (SOC lab, Proxmox, Wazuh, TheHive, Cortex, MISP, Zeek, Suricata, homelab, MCP) - Redacted result-JSON example block (RFC 5737 documentation IPs) - "Why not something else?" and "What soc-stack is not" sections - Local clone quickstart and an honest single-maintainer status note Health files: - Add CODE_OF_CONDUCT.md (Contributor Covenant 2.1) - Add .github/ISSUE_TEMPLATE/config.yml (no blank issues, route security and questions off the issue tracker) - Add a no-PII / no-leak checkbox to the pull request template - Add an Unreleased CHANGELOG entry for the docs work --- .github/ISSUE_TEMPLATE/config.yml | 11 +++ .github/PULL_REQUEST_TEMPLATE.md | 1 + CHANGELOG.md | 4 ++ CODE_OF_CONDUCT.md | 19 ++++++ README.md | 109 ++++++++++++++++++++++++++---- 5 files changed, 131 insertions(+), 13 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 CODE_OF_CONDUCT.md diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..a9075f5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Project website and tool index + url: https://lidless.dev/soc-stack + about: Overview, the wider lidless.dev SOC tooling, and where this fits. + - name: Security report (do not file publicly) + url: https://github.com/solomonneas/soc-stack/security/advisories/new + about: Report a vulnerability privately. See SECURITY.md. Do not open a public issue for anything that leaks a secret. + - name: Question or usage help + url: https://github.com/solomonneas/soc-stack/discussions + about: For setup questions and general usage, start a discussion rather than filing a bug. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 9e7c177..88f30ef 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -10,6 +10,7 @@ - [ ] Integration assertion passes on the self-hosted Proxmox runner (if touching a component or lib) - [ ] No em-dashes in commit messages or files - [ ] No `Co-Authored-By` trailers +- [ ] No leaked PII, secrets, real private IPs, hostnames, or `/home/` paths (documentation IPs use the RFC 5737 range; real values are scrubbed) ## Related diff --git a/CHANGELOG.md b/CHANGELOG.md index 01270fb..2704557 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ All notable changes to soc-stack are documented in this file. Format follows [Ke ## [Unreleased] ### Added +- README adoption pass: prominent website link, live CI and release badges, a keyword-rich "What it does" section, a redacted result-JSON example block, and "Why not something else?" / "What soc-stack is not" sections +- `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1) +- `.github/ISSUE_TEMPLATE/config.yml` (disables blank issues, routes security reports and questions off the issue tracker) +- No-PII / no-secret-leak checkbox in the pull request template - TTY component picker when run locally without `--components`/`--manifest` - `--include-secrets-json` (result JSON redacts credentials by default) and `--mcp-bind-host` (MCP SSE binds 127.0.0.1 by default) - `SECURITY.md` documenting the threat model and hardening posture diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..68844c5 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,19 @@ +# Code of Conduct + +This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). + +The full text lives at the link above. The short version: be respectful, assume good faith, keep feedback technical, and remember that everyone here is volunteering their time. + +## Scope + +The Code of Conduct applies to all project spaces: GitHub issues and pull requests on this repo, project-related discussions on Discord or other chat surfaces, and any in-person events where someone is representing the project. + +## Reporting + +If you experience or witness a violation, please email **me@solomonneas.dev**. Reports are confidential. You should get an acknowledgment within 72 hours. + +The maintainer is also the recipient of security reports, see [SECURITY.md](SECURITY.md). Please tag the subject line so it is easy to route (for example "CoC report" vs "security report"). + +## Enforcement + +The maintainer is responsible for clarifying and enforcing standards. Enforcement actions can include private warnings, public clarifications, temporary or permanent bans from project spaces, and reverting or rejecting contributions. diff --git a/README.md b/README.md index 479a389..aafc6d9 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,14 @@

SOC Stack

- One-shot Proxmox installer for a complete Security Operations Center. + One command on a Proxmox host builds a complete, self-hosted Security Operations Center lab in about 30 minutes. +

+ +

+ Website: lidless.dev/soc-stack + CI status + Latest release + MIT License

@@ -17,10 +24,28 @@ MCP servers Docker Compose stacks Bash installers - MIT License

-Run one command on a Proxmox host, or have an agent do it, and ~30 minutes later you have Wazuh (SIEM), TheHive + Cortex (case management + SOAR), MISP (threat intel), Zeek + Suricata (NSM + IDS), custom dashboards, and 9 MCP servers wired up and talking to each other. Non-interactive by default. Idempotent. JSON output for agents. Built for replication. +SOC Stack is a one-command installer that stands up a full open-source Security Operations Center on a single Proxmox host: Wazuh, TheHive + Cortex, MISP, Zeek + Suricata, dashboards, and a row of MCP servers, all wired together. You want a realistic SOC to train on, test detections against, or run as a homelab, but assembling six tools by hand and integrating them eats days. It differs from a pile of per-tool guides by treating the whole stack as one declarative, idempotent, agent-friendly deploy: each tool is a self-contained LXC component, cross-component integrations wire automatically, and the entire run is non-interactive with JSON output so an AI agent can SSH in and one-shot it. + +**Website:** [lidless.dev/soc-stack](https://lidless.dev/soc-stack) + +> **Project status.** v1.0.0 is tagged and the full stack deploys and asserts green end-to-end on Proxmox VE 7.x/8.x/9.x. It is an actively developed, single-maintainer lab tool built for homelabs, training, and internal SOC replication, not a hardened multi-tenant production deployment. See [SECURITY.md](SECURITY.md) for the threat model and the [CHANGELOG](CHANGELOG.md) for what is in flight. + +## What it does + +SOC Stack is a self-hosted SOC lab builder for homelabs and security training. Run one command on a Proxmox VE host and roughly 30 minutes later you have a working Security Operations Center: + +- **Wazuh** for SIEM / XDR (alerting, FIM, vulnerability detection, agent management) +- **TheHive + Cortex** for case management and SOAR (analyzers, responders, observable enrichment) +- **MISP** for threat intelligence (IOC sharing, feeds, correlation) +- **Zeek + Suricata** for network security monitoring and intrusion detection (NSM + IDS/IPS) +- **Custom dashboards** (Bro Hunter + Playbook Forge) behind nginx +- **9 MCP servers** so an AI agent can query Wazuh, TheHive, Cortex, MISP, Zeek, Suricata, MITRE ATT&CK, Rapid7, and Sophos over a single MCP config + +Every tool runs in its own dedicated, unprivileged LXC. The orchestrator handles VMID allocation, network setup, idempotency, secret generation, and cross-component integration wiring. The whole run is non-interactive by default and emits structured JSON, so a person or an agent can replicate the same lab on demand. + +Keywords: SOC lab, security operations center, Proxmox homelab, Wazuh SIEM, TheHive, Cortex SOAR, MISP threat intelligence, Suricata IDS, Zeek NSM, blue team training, detection engineering, self-hosted security, MCP servers for security tooling. ## Quick start @@ -52,6 +77,14 @@ curl -sSL https://raw.githubusercontent.com/solomonneas/soc-stack/main/install.s --mcp-config-out /root/mcp-clients.json ``` +Prefer to read before you run? Clone the repo and execute the same orchestrator locally; the behavior is identical: + +```bash +git clone https://github.com/solomonneas/soc-stack.git +cd soc-stack +sudo bash install.sh --components all --dry-run # validate + plan, deploy nothing +``` + After install: - `/root/soc-stack.json` lists every component with its LXC VMID, IP, ports, endpoints, warnings, and secret file paths. Raw passwords and API tokens are redacted by default; pass `--include-secrets-json` only when an automation workflow explicitly needs them. - `/root/mcp-clients.json` is a paste-ready `mcpServers` config block for Claude Desktop, OpenClaw, or any MCP client. It contains bearer tokens and is written root-only. @@ -77,15 +110,46 @@ Each component runs in its own dedicated LXC. Components can be deployed indepen Configured automatically after all components deploy: -- **Wazuh → TheHive**: Wazuh alerts at level 8+ forward to TheHive as alerts via a custom Python integration (`/var/ossec/integrations/custom-thehive.py`). -- **TheHive ↔ Cortex**: TheHive's Cortex connector points at the local Cortex with an org-scoped API key. -- **MISP → Suricata**: hourly cron pulls Snort/Suricata rules from MISP's `restSearch` endpoint into Suricata's update.d. -- **Zeek → Wazuh**: Wazuh agent runs in the zeek-suricata LXC and forwards conn.log, dns.log, http.log, ssl.log, notice.log to the Wazuh manager. -- **MCP servers ← all peers**: each MCP server's env file is populated with its corresponding tool's URL + API key from peer state. - -## Status +- **Wazuh -> TheHive**: Wazuh alerts at level 8+ forward to TheHive as alerts via a custom Python integration (`/var/ossec/integrations/custom-thehive.py`). +- **TheHive <-> Cortex**: TheHive's Cortex connector points at the local Cortex with an org-scoped API key. +- **MISP -> Suricata**: hourly cron pulls Snort/Suricata rules from MISP's `restSearch` endpoint into Suricata's update.d. +- **Zeek -> Wazuh**: Wazuh agent runs in the zeek-suricata LXC and forwards conn.log, dns.log, http.log, ssl.log, notice.log to the Wazuh manager. +- **MCP servers <- all peers**: each MCP server's env file is populated with its corresponding tool's URL + API key from peer state. + +## What a finished install looks like + +`/root/soc-stack.json` is the source of truth for what got deployed. With secrets redacted, a full-stack run reports each component, its LXC, its endpoints, and any warnings (IPs and tokens below are placeholder values from the [RFC 5737](https://datatracker.ietf.org/doc/html/rfc5737) documentation range): + +```json +{ + "version": "1.0.0", + "preset": "minimal", + "status": "deployed", + "components": [ + { + "component": "wazuh", + "status": "deployed", + "vmid": 9001, + "ip": "192.0.2.11", + "endpoints": { "dashboard": "https://192.0.2.11:443", "api": "https://192.0.2.11:55000" }, + "credentials": { "user": "admin", "password": "REDACTED" } + }, + { + "component": "mcp", + "status": "deployed", + "vmid": 9006, + "ip": "192.0.2.16", + "endpoints": { "wazuh_sse": "http://127.0.0.1:3001/sse", "thehive_sse": "http://127.0.0.1:3002/sse" } + } + ], + "integrations": [ + { "from": "wazuh", "to": "thehive", "status": "wired" }, + { "from": "misp", "to": "suricata", "status": "wired" } + ] +} +``` -**v1.0.0** (current, 2026-05-16): All 6 components + 5 cross-component integrations verified end-to-end on Proxmox VE. Self-hosted CI runs on every PR (shellcheck, bats, manifest validation, per-component integration matrix) and on merge to main (full-stack integration). See the [CHANGELOG](CHANGELOG.md) for full history. +The exact result-JSON schema is documented in [`docs/design/specs/2026-05-15-soc-stack-unification-design.md`](docs/design/specs/2026-05-15-soc-stack-unification-design.md). ## Agent-friendly contract @@ -226,14 +290,33 @@ curl -sSL https://raw.githubusercontent.com/solomonneas/soc-stack/main/install.s ``` Re-running the installer from a newer checkout is the upgrade path: already-deployed components are left alone, new components deploy, and integration re-wires. To pick up a new version of one component, destroy it and re-run with `--components `. The installer never auto-updates a running component in place. +## Why not something else? + +- **Why not install each tool by hand?** You can, and the official docs for Wazuh, TheHive, MISP, and Suricata are good. But six installs plus the integrations between them (alert forwarding, analyzer wiring, IOC feeds, log shipping) is a multi-day project that breaks the next time you rebuild. SOC Stack makes the whole thing one reproducible command. +- **Why not a single all-in-one SIEM VM (SecurityOnion, Wazuh OVA, etc.)?** Those are excellent and purpose-built. SOC Stack is different on purpose: each tool lives in its own LXC you can scale, snapshot, or destroy independently, the components are the real upstream projects (not a fork), and the cross-tool integrations are explicit and inspectable rather than baked into one appliance. +- **Why not Ansible or Terraform?** Nothing stops you, and a config-management rewrite is a reasonable future direction. The current design favors plain, auditable bash you can read top to bottom and a `curl | sudo bash` path an agent can drive without extra tooling on the host. State files, not a state backend, drive idempotency. +- **Why not run it on Docker / Kubernetes directly?** Several components already use Docker Compose inside their LXC. The Proxmox LXC layer gives each tool isolation, its own IP, and snapshot/rollback at the container level, which matches how a homelab SOC is actually operated. + +## What soc-stack is not + +- **Not a hardened production SOC.** It is a lab and training tool. It assumes a trusted Proxmox host and a trusted internal bridge. Do not expose the component IPs to an untrusted network without a firewall, VLAN, and TLS termination in front. The full threat model is in [SECURITY.md](SECURITY.md). +- **Not a managed or hosted service.** There is no SaaS, no telemetry, and no phone-home. Everything runs on hardware you control. +- **Not a fork or a repackage of the upstream tools.** It deploys Wazuh, TheHive, Cortex, MISP, Zeek, and Suricata from their real sources at pinned versions; it does not modify them. +- **Not an auto-updater.** The installer pins versions and never silently upgrades a running component in place; updates happen on your schedule. +- **Not multi-host.** It targets a single Proxmox host. Multi-node is out of scope today. + ## Adding a new component See [docs/adding-a-component.md](docs/adding-a-component.md) for the component contract walk-through, and [docs/design/specs/2026-05-15-soc-stack-unification-design.md](docs/design/specs/2026-05-15-soc-stack-unification-design.md) for the full design. +## Contributing + +Contributions are welcome. New components follow a six-file contract, every lib function gets a bats test, and CI runs shellcheck plus bats on every PR. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). + ## Security -Default credentials are rotated and verified on deploy, secrets are root-only, result JSON is redacted by default, and MCP servers bind to localhost unless you say otherwise. The full threat model, what is hardened versus deliberately accepted, lives in [SECURITY.md](SECURITY.md). +Default credentials are rotated and verified on deploy, secrets are root-only, result JSON is redacted by default, and MCP servers bind to localhost unless you say otherwise. The full threat model, what is hardened versus deliberately accepted, lives in [SECURITY.md](SECURITY.md). Found a vulnerability? Use GitHub's private vulnerability reporting on this repository. ## License -MIT +[MIT](LICENSE). Copyright (c) 2026 Solomon Neas.