benolenick/security-shallots

# Security Shallots Security Shallots 是一款专为家庭实验室（homelab）和拥有约 1-10 台计算机的小型办公室设计的轻量级安全侦察工具。 它并不打算完全替代 Security Onion。其目标是在不引入 Elasticsearch、Kibana、专用 SOC 工作流或大型服务器的前提下，为家庭运维者提供 SIEM/NSM 技术栈中实用的日常功能。 其核心理念非常简单： - 收集高价值的网络、主机和路由器信号 - 记住这个小型机群中“正常”的状态是怎样的 - 揭示状态偏移（drift）、蜜罐触达（canary touches）、异常的首次活动以及告警集群 - 尽可能保留短期的数据包证据 - 生成紧凑的“侦察卡片”，供人工或更强的 AI 审查 该侦察工具不会做出最终的安全裁决。它的职责是将那些可能被遗漏的事项升级上报。 ## 效果展示 您整个小型网络的安全状态，都集中在一个小盒子上完成了分诊处理。（以下截图均为内置的使用合成数据的演示配置 - `python -m tools.demo_seed`。）  **告警经过了分诊处理，而不是简单堆砌。** 已知的噪声（如 LLMNR、内部 SSH、软件包更新、流重传等）会被自动抑制；剩下的部分则会按严重程度排序，并支持一键抑制 / 调查 / 升级。  **本地 LLM 会将原始告警转化为通俗易懂的英文事件报告** —— 包括发生了什么、为何重要，以及相应的操作手册（runbook）—— 且完全在您自己的 GPU 上运行。任何数据都不会离开您的网络。  ## 最佳适用场景 Shallots 专为以下场景设计： - 家庭实验室 - 约 10 台计算机以下的小型办公室 - 拥有可发送 syslog 日志的路由器/防火墙的网络 - Raspberry Pi 4/5、迷你 PC、旧笔记本电脑或小型服务器 - 希望在没有完整 SOC 技术栈的情况下获取实用告警的运维者 它**不**适用于以下场景： - 企业的留存/搜索需求 - 合规性案例管理 - 高吞吐量下的全数据包捕获 - 在非托管的交换机局域网中实现全面的东向流量可见性 - 替代笔记本电脑和台式机上的 EDR ## 可见性至关重要 Shallots 只能分析它所能看到的流量和日志。 推荐的部署位置： | 部署位置 | Shallots 能看到的内容 | 适用性 | |---|---|---| | 路由器/网关 syslog + DNS 日志 | 防火墙事件、DHCP/DNS、WAN 边缘活动 | 最佳的 Pi 默认模式 | | 托管交换机镜像/SPAN 端口 | 用于 Suricata/pcap 的镜像 LAN 流量 | 最佳的 IDS 模式 | | 串联式网关/路由器 | 流经 Shallots 主机的路由流量 | 进阶模式 | | 仅普通 LAN 端口 | 绝大多数仅为 Shallots 主机自身的流量 | 功能受限 | 在许多家庭网络中，插入普通交换机端口的 Pi 将无法看到所有的设备到设备流量。在这种模式下，应将 Shallots 视为 syslog、DNS、安全姿态（posture）、蜜罐（canary）和出口流量的侦察工具，而不是完整的网络 IDS。 ## 功能说明 核心功能： - 基于 SQLite 的告警存储和 API - Web 仪表盘 - 用于路由器、防火墙、NAS 设备和 Linux 主机的 syslog 接收器 - Suricata EVE 日志摄取（需在已安装 Suricata 时） - CrowdSec 信号摄取（需在已安装 CrowdSec 时） - Argus 轻量级端点/出口流量代理数据摄取 - 短期滚动 pcap 证据缓冲区 - 告警抑制与噪声清理 - 生产/运维状态的健全性检查门槛 - 安全姿态扫描器：用于监测服务漂移、DNS 记忆、执行记录、时间同步、传感器覆盖范围以及蜜罐状态 - 用于捕获高价值异常触达的微型蜜罐监听器 - 用于 AI 辅助审查的本地语料库/上下文存储 - 可选的本地或远程 AI 分诊 - 面向更强模型审查的分层升级机制 重型功能均为可选。树莓派（Pi）的配置文件应从 syslog、安全姿态、蜜罐、DNS/上下文和小型 pcap 环形缓冲区开始。只有当主机拥有足够的 CPU 和有利的流量观测点时，才添加 Suricata。 ## 配置文件 | 配置文件 | 目标平台 | 推荐组件 | |---|---|---| | `pi-core` | Pi 4/5、USB SSD | syslog、安全姿态、蜜罐、蜜罐监听器、SQLite/API、云端/远程 AI | | `pi-ids` | Pi 5 或更快设备 | 包含 `pi-core`，外加小型 pcap 环形缓冲区和保守的 Suricata 规则 | | `mini` | NUC/旧笔记本电脑 | Suricata、CrowdSec、Argus、pcap 环形缓冲区、本地或云端 AI | | `full` | 小型服务器 | 所有传感器、本地模型、更长留存期、更丰富的评估/升级机制 | 针对树莓派（Pi）的实用建议： - 如果使用 pcap 或进行重度日志记录，请通过 USB SSD 启动，切勿使用 SD 卡 - 严格控制 pcap 留存限制，例如设置为 64-256 MB - 密切关注 Suricata 的丢包情况 - 建议将 LLM 任务交由云端/远程 AI 或局域网内的另一台机器处理 - 除非硬件为迷你 PC/服务器，否则请保持禁用本地 AI ## 快速开始 手动开发安装： ``` python3 -m venv .venv . .venv/bin/activate pip install -e ".[dev]" cp config.example.yaml config.yaml python -m shallots -c config.yaml run ``` 通过代码库检出进行服务安装： ``` sudo bash setup/deploy-linux-service --repo /home/user/security-shallots sudo systemctl enable --now shallotd.service sudo systemctl enable --now shallot-watchdog.timer ``` 可选的安全姿态服务： ``` sudo install -m 0644 deploy/systemd/shallot-posture-scan.* /etc/systemd/system/ sudo install -m 0644 deploy/systemd/shallot-honey-listener.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable --now shallot-posture-scan.timer sudo systemctl enable --now shallot-honey-listener.service ``` 随后在以下地址打开仪表盘： ``` https://:8844 ``` 在将仪表盘暴露给您的局域网（LAN）之前，请务必设置 `web.username`、`web.password`、`tls_cert` 和 `tls_key`。 ## 向其他机器部署代理 上述主机是您的**中央服务器**。要监控网络上的其他机器，您需要在每台机器上部署一个轻量级代理，使其向服务器汇报。目前有两种代理类型 —— 完整的操作步骤请参阅 [`docs/GUIDE.md`](docs/GUIDE.md) 第 3 节。 **Clove** —— 日常代理（预配置的 Wazuh 代理，可选配 CrowdSec）。 在 Linux 端点上只需执行一条命令，并将其指向您服务器的 IP： ``` curl -fsSL https://raw.githubusercontent.com//security-shallots/main/setup/endpoint/clove \ | sudo bash -s -- --manager ``` Windows 端点请使用 `setup/endpoint/clove.ps1 -Manager `。Clove 会自动注册到服务器上的 Wazuh 管理器（端口 **1514/1515**）；服务器会持续追踪管理器的 `alerts.json`，并将这些事件整合到同一个处理流水线中。无需进行其他额外配置。 **Argus** —— 针对您最关注的机器部署的重型主机哨兵（用于出口监控、文件/持久化/会话监控、防篡改）。它会通过 HTTPS 并携带专属的代理密钥，直接将数据发送到服务器的 Argus webhook： ``` sudo setup/endpoint/install-argus-linux \ --server-url https://:8855/api/ingest/argus \ --secret --enable --start ``` 连接关系总结 —— 所有数据都汇聚回同一台服务器： ``` endpoint (clove) ──1514/1515──▶ Wazuh manager ─┐ endpoint (Argus) ──8855 HTTPS──▶ Argus webhook ─┼─▶ Shallots pipeline ─▶ dashboard router / firewall ──514 syslog──▶ syslog receiver┘ ``` 局域网（LAN）之外的代理（如 VPS 或亲属家中的设备）可通过 VPN/WireGuard 链接或通向管理器/webhook 端口的反向隧道以相同方式连接服务器 —— 代理的配置完全相同，只需更改目标地址即可。 ## 管理命令 ``` tools/shallot_ops_sanity.py --json tools/shallot_production_gate.py --json tools/shallot_full_stack_status.py --json tools/shallot_posture_scan.py scan tools/shallot_posture_eval.py --json tools/shallot_public_listener_audit.py --json ``` 实用的服务检查命令： ``` systemctl status shallotd systemctl status shallot-posture-scan.timer systemctl status shallot-honey-listener.service journalctl -u shallotd -f ``` ## AI 分诊 Shallots 无需 AI 也能正常工作。规则、蜜罐、安全姿态偏移监测以及告警存储等功能依然有效。 对于树莓派（Pi）或微型集线器，建议使用远程/云端 AI 或局域网内性能更强的机器： ``` ai: tier: remote_api batch_size: 2 batch_interval_sec: 900 ``` 对于配备本地 Ollama 的迷你 PC/服务器： ``` ai: tier: local ollama_url: "http://127.0.0.1:11434" ollama_model: "granite3.3:8b" batch_size: 2 batch_interval_sec: 900 ``` 边缘侦察工具（edge scout）被刻意设计为不带有主观判断色彩： ``` scout: enabled: true model: "granite3.3:8b" batch_size: 10 interval_sec: 60 corpus_path: "data/fleet_context.db" ``` 对于任何云端模型路径，请务必涂改敏感信息，并且除非运维者明确同意，否则应避免发送原始 payload。 ## 架构 ``` router/syslog ─┐ Suricata EVE ──┤ CrowdSec ──────┼──> normalize/dedup/enrich ──> SQLite ──> API/dashboard Argus agents ──┤ │ posture scan ──┘ ├──> scout cards canaries/honey ───────────────┘ └──> optional tiered AI escalation ``` Shallots 特意采用了以下技术： - Python asyncio - SQLite/WAL - 简单的 systemd 定时器 - 有界的 pcap/日志留存限制 - 可选的传感器，而非强制性的重型服务 ## 文档说明 - **[docs/GUIDE.md](docs/GUIDE.md)** - 完整的入门指南：涵盖架构、两种代理类型、逐步安装说明、告警解读、配置参考以及**故障排除**（第 8 节）。 - **[docs/TUNING.md](docs/TUNING.md)** - 如何让它适应您的网络：静默噪声、设置安全姿态、调整告警推送机制，以及判断其何时值得信赖。 - **[SECURITY.md](SECURITY.md)** - 报告安全问题。 ## 当前成熟度 这是一个活跃的原型/参考构建版本。在完全依赖其进行无人值守运行之前，请务必： - 确认网络部署位置能够观测到您关注的流量 - 运行生产环境检查门槛 - 进行一次蜜罐/评估流程 - 如果使用了 Suricata，请检查丢包情况 - 配置告警推送方式 - 进行浸泡测试，并审查误报和漏报情况 ## 许可证 MIT

标签：AI风险缓解, LangChain, Metaprompt, PB级数据处理, 安全告警, 安全运维, 异常检测, 本地大模型, 计算机取证, 轻量级, 逆向工具