nuk3s/soc-ai

soc-ai 会读取你 [Security Onion](https://securityonionsolutions.com/) 网格上的告警，并使用你自行托管的 LLM 对其进行分诊。对于每条告警，它会拉取相关事件，检查主机的其他行为，在本地威胁情报中比对指标，并在必要时从传感器解码数据包。然后，它会为你提供结论、置信度数值以及得出该结论的推理过程。 该模型运行在你自己的硬件上，处于 [LiteLLM](https://docs.litellm.ai/) 网关之后。你网络中的任何数据都不会外泄，并且除非有人类点击批准，否则 agent 绝不会更改网格上的任何内容。对于难以判定的告警，系统提供了一个可选的云端“Oracle”以获取第二意见；在你开启之前它始终处于关闭状态，并且其输入会先经过脱敏处理。 ## 两种使用方式 **Web 控制台** 位于 `/app`，按规则显示你的告警队列，并在每条告警旁边内联展示 AI 的结论和置信度。你可以打开某个告警进行调查，或者通过自动分诊扫视整个未分诊的队列。每次调查都会生成一个可共享的永久链接。 **Security Onion 内部的按钮** —— 一个 Tampermonkey 用户脚本会在 SO 告警视图中直接植入一个“Hunt with AI”按钮，让你无需离开日常使用的网格即可进行分诊。 在底层，这两种方式运行的都是同一个 agent。对于单条告警，它会： - 读取告警上下文、相关事件（通过 OQL）以及该主机近期的告警历史； - 使用本地磁盘上的威胁情报（封锁列表、GeoIP/ASN、云前缀标记）来丰富指标； - 在 payload 至关重要时，从传感器拉取并解码原始 PCAP； - 权衡证据并写下结论，附带其置信度和判定理由； - 为你推荐可执行的写入操作（确认、升级为案例、添加评论），供你一键执行。 ## 它不会自行执行的操作 核心原则是，任何改变状态的操作都由你来掌控。 - **读取操作自由执行。** 拉取事件、上下文、丰富信息和数据包是安全的，因此 agent 无需询问即可执行。 - **写入操作需等待人类确认。** 确认告警、开启案例、留下评论 —— 这些操作只有在你点击批准后才会执行。agent 可以推荐写入操作，但无法自行执行。 - **未经你的同意，任何数据都不会离开你的网络。** 推理过程在你自己的硬件上、使用你自己的模型运行。Oracle —— 一个可选的云端第二意见 —— **默认关闭**：它是一项*按需启用*的云功能，即使你开启了它，内部主机名、用户名和 IP 也会在发送任何内容之前被脱敏。如果保持关闭，整个 pipeline 将完全留在你的网络中。 更多细节请参阅 [docs/SAFETY_MODEL.md](docs/SAFETY_MODEL.md)。 ## 快速开始 你需要一台安装了 `git` 和 `curl` 的 Linux 主机，能够连接到你的 SO 网格，以及一个至少提供一个模型的 LiteLLM 网关。`setup.sh` 会为你处理 Docker 相关操作。**首次安装者：请先浏览 [Security Onion 账户 + 防火墙前置条件](docs/SECURITY-ONION-SETUP.md)** —— 将 soc-ai 的 IP 穿透 SO 的防火墙以及授予审计日志角色，是两个最容易出问题的地方。 ``` git clone https://github.com/nuk3s/soc-ai.git && cd soc-ai ./setup.sh ``` `setup.sh` 会引导你完成连接设置，并在构建任何内容*之前*进行检查（密码错误或网关不可达会在几秒钟内报错，而不是在构建三分钟后），它允许你从网关的实时列表中选择你的模型（会通过身份验证来获取列表），生成密钥和 TLS 证书，启动整个技术栈，并打印出 URL 和管理员密码： ### 接下来在浏览器中处理告警 打开 `https://:8443/app`，接受自签名证书，并以 `admin` 身份登录。选择一个检测项，点击 **Hunt with AI**，观看 agent 实时进行调查 —— 它会拉取告警及其 Zeek/PCAP 上下文，丰富指标，并给出附带证据引用的结论。它推荐的任何向 Security Onion 回写的操作，都需要经过一键式的人类审批：

完整的 Docker 选项 —— 必需的挂载、SELinux 重打标签、上游 TLS 信任 (`*_VERIFY_SSL`)、8443 端口与 SO nginx 的冲突、手动 + rsync/systemd 路径 —— 位于 **[docs/DOCKER.md](docs/DOCKER.md)** 中；SO 账户、角色和防火墙设置位于 **[docs/SECURITY-ONION-SETUP.md](docs/SECURITY-ONION-SETUP.md)** 中。 ## 工作原理

`ANALYST_MODEL` 是 agent 用于进行分诊的唯一模型 —— 可以是你的网关提供的任何模型（模型 ID 会变动，因此需要重新探测 `/v1/models`）。推理在本地进行。Oracle 路径是数据到达云 API 的唯一途径，它是可选的，并且它只能看到脱敏后的输入。 ## 文档 - [docs/WEBUI_GUIDE.md](docs/WEBUI_GUIDE.md) —— 控制台：分诊、自动分诊、调查、管理员配置页面 - [docs/AGENT_TOOLS.md](docs/AGENT_TOOLS.md) —— agent 可以调用的每个工具及其防护机制 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) —— 各个组件是如何协同工作的 - [docs/OQL_PRIMER.md](docs/OQL_PRIMER.md) —— agent 用于搜索的查询语言 - [docs/SAFETY_MODEL.md](docs/SAFETY_MODEL.md) —— 审批流程、审计 schema 和 Oracle 脱敏机制 - [docs/DOCKER.md](docs/DOCKER.md) · [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) —— 安装指南 - [CHANGELOG.md](CHANGELOG.md) · [CONTRIBUTING.md](.github/CONTRIBUTING.md) · [SECURITY.md](.github/SECURITY.md) ## 基于它进行开发 ``` uv sync # Python deps + dev tools uv run pytest --ignore=tests/browser # the test suite uv run mypy soc_ai # strict type check cd frontend && npm ci && npm run build # the React console ``` ## 未来规划 1.0 版本是分诊引擎加上常驻控制台。接下来：基于 RAG 的 runbook 查找、对每个分组进行多条告警分诊，以及更广泛的情报覆盖范围。进展和提案位于 issue 跟踪器中。 ## 许可证 Apache 2.0。详见 [LICENSE](LICENSE)。

标签：DLL 劫持, LLM网关, Security Onion, 告警分诊, 大语言模型, 威胁情报, 安全运营, 开发者工具, 扫描框架, 策略控制器, 自动化分析, 请求拦截, 跨站脚本