beenuar / AiSOC

本文为原文前 6,000 字符的节选翻译，完整内容请查看原文。

AiSOC An open-source, self-hostable AI Security Operations Center. It ingests your security telemetry, detects and correlates threats, investigates them with AI agents whose reasoning is fully auditable, and proposes responses a human approves. Technical Guide (PDF) · Docs · Architecture · What actually works · Discussions

AiSOC 是一个开源、可自托管的 AI 安全运营中心。它能够摄取您的安全遥测数据，检测并关联威胁，利用推理过程完全可审计的 AI 代理进行调查，并提出由人工审批的响应方案。技术指南 (PDF) · 文档 · 架构 · 实际效果 · 讨论

What AiSOC does Telemetry arrives from your security tools. AiSOC normalizes it, runs the 2538 executable rules of its 7023-rule library, groups what fires into incidents, investigates each one with an AI agent whose every prompt and tool call is recorded, and proposes an action. New threat intelligence re-sweeps the history you already collected, and a human approves before anything reaches a vendor.

AiSOC 的功能：遥测数据从您的安全工具中传入。AiSOC 对其进行标准化处理，运行其 7023 条规则库中的 2538 条可执行规则，将触发的事件归类为安全事件，并由 AI 代理对每一项进行调查，记录下所有的提示词和工具调用，最后提出行动建议。新的威胁情报会重新扫描您已收集的历史数据，在任何信息发送给供应商之前，均需经过人工审批。

What it looks like running Watch the full three minutes — install to AI verdict on one server against the published images, terminal waits shortened and the recording saying so on screen. The stills below are from a v20.1.0 run under the same rules — the recording is older than they are. (step by step · what is real) Alerts — each attributed to the connector that fed it. Automated triage — the bundled local model’s verdict, confidence and rationale, verbatim. Threat intelligence — the real CISA KEV catalog, minutes after boot, with no API key. SOC operations — with nothing connected yet, and it says so rather than showing a placeholder.

运行效果：观看完整的三分钟视频——从安装到在单台服务器上针对已发布镜像得出 AI 结论，终端等待时间已缩短，屏幕上会有相应说明。下方的静态图片来自 v20.1.0 版本在相同规则下的运行情况——录像比版本本身更早。（分步说明 · 真实情况）警报——每一项都归因于提供数据的连接器。自动分类——内置本地模型给出的结论、置信度和理由，逐字记录。威胁情报——真实的 CISA KEV 目录，启动几分钟后即可获取，无需 API 密钥。SOC 运营——在尚未连接任何设备时，系统会明确提示，而不是显示占位符。

Quick start git clone https://github.com/beenuar/AiSOC && cd AiSOC make up On Windows, or on a machine with nothing installed yet, one line does the prerequisites too: iwr -useb https://raw.githubusercontent.com/beenuar/AiSOC/main/install.ps1 | iex (curl -fsSL https://raw.githubusercontent.com/beenuar/AiSOC/main/install.sh | bash on Linux and macOS). Without Docker at all, pip install aisoc-sandbox && aisoc-sandbox demo walks one alert through the agent funnel offline in under 30 seconds. Without your own machine, open the repo in GitHub Codespaces and run make up in its terminal. All four end at the same console; only the first three install anything.

快速入门：执行 git clone https://github.com/beenuar/AiSOC && cd AiSOC 然后运行 make up。在 Windows 或尚未安装任何软件的机器上，一行命令即可完成先决条件配置：iwr -useb https://raw.githubusercontent.com/beenuar/AiSOC/main/install.ps1 | iex（Linux 和 macOS 上使用 curl -fsSL https://raw.githubusercontent.com/beenuar/AiSOC/main/install.sh | bash）。如果完全不使用 Docker，可以通过 pip install aisoc-sandbox && aisoc-sandbox demo 在 30 秒内离线演示一个警报通过代理漏斗的过程。如果没有自己的机器，可以在 GitHub Codespaces 中打开仓库并在终端运行 make up。这四种方式最终都会进入同一个控制台；只有前三种需要安装任何内容。

The Technical Guide covers this in depth: server sizing, where the model runs, every failure mode with its cause and fix, the REST API, MCP, and every console surface. Needs Docker Compose v2 with 8 GB memory and 20 GB free disk in the Docker VM, plus python3 (3.9+) and bash; make doctor checks all of it and Installation says what each number was measured against.

技术指南对此进行了深入介绍：服务器规模、模型运行位置、每种故障模式及其原因和修复方法、REST API、MCP 以及每个控制台界面。需要 Docker Compose v2，Docker 虚拟机需具备 8 GB 内存和 20 GB 可用磁盘空间，此外还需要 python3 (3.9+) 和 bash；make doctor 会检查所有这些要求，而“安装”部分说明了每个数值的衡量标准。

The first run downloads a ~2 GB model into a volume only make clean clears. make up also creates .env and generates the fifteen secrets in it — the credential vault, the session signing key, five service-to-service credentials and four datastore passwords — then creates an administrator and prints its password, generated on your machine, shown once and stored nowhere. Lost it? make bootstrap ARGS=—reset-password mints another.

首次运行时会下载一个约 2 GB 的模型到卷中，只有 make clean 才能清除它。make up 还会创建 .env 文件并生成其中的 15 个密钥——凭据库、会话签名密钥、五个服务间凭据和四个数据存储密码——然后创建一个管理员账户并打印其密码。该密码在您的机器上生成，仅显示一次，不会存储在任何地方。丢失了？运行 make bootstrap ARGS=--reset-password 可重新生成。

A port already in use does not stop the install. AiSOC publishes on a free one, names what held the old one, and moves the console address with it: 64 seconds to a signed-in console on a bare clone with 5432 and 11434 both taken. Then prove it works. make smoke posts one real event to the ingest API and follows it through Kafka, detection, correlation and Postgres, then reads the alert back out of the public API. Every stage reports PASS or FAIL: $ make smoke [PASS] raw telemetry accepted by ingest [PASS] event traversed the spine and became an alert PASS: 10/10 stages

端口被占用不会阻止安装。AiSOC 会发布在一个空闲端口上，指出占用旧端口的程序，并随之移动控制台地址：在 5432 和 11434 端口均被占用的情况下，从克隆到登录控制台仅需 64 秒。然后验证其是否有效。make smoke 会向摄取 API 发布一个真实事件，并跟踪其通过 Kafka、检测、关联和 Postgres 的全过程，然后从公共 API 读取该警报。每个阶段都会报告 PASS 或 FAIL：$ make smoke [PASS] 原始遥测数据被摄取接口接收 [PASS] 事件穿过主干并成为警报 PASS: 10/10 阶段

Sign in at the address make up printed. A tenant with nothing connected lands on a setup wizard rather than an all-zero dashboard, and its state is read from your own data so it stays right if you connect a source through the API. The spec is docs/openapi.yaml — interactive docs are off in this production-class stack. Stuck? make doctor, which on a host where you have not run make up yet says exactly that.

在 make up 打印的地址登录。未连接任何设备的租户会进入设置向导，而不是显示全零的仪表板。其状态是从您自己的数据中读取的，因此如果您通过 API 连接数据源，状态将保持准确。规范文件为 docs/openapi.yaml——在此生产级堆栈中，交互式文档处于关闭状态。遇到问题？运行 make doctor，如果主机上尚未运行 make up，它会明确提示。

Press Load sample data in the wizard. Five scenarios take the same ingest path a real connector uses — not inserted rows — so watching them become alerts means watching the pipeline work. They span low to critical on purpose, because a first run where everything is a crisis teaches you nothing about how triage separates signal from routine. They are attributed to AiSOC in the source column, refuse to load into a tenant that already has real alerts, and do not mark setup complete. (what each step proves)

在向导中点击“加载示例数据”。五个场景采用与真实连接器相同的摄取路径——而非直接插入行——因此观察它们成为警报的过程，就是观察管道工作的过程。它们故意涵盖了从低到高危的级别，因为如果第一次运行全是危机，您将无法了解分类系统如何将重要信号与常规数据区分开来。它们在来源列中被归因于 AiSOC，拒绝加载到已有真实警报的租户中，并且不会将设置标记为完成。（每一步的验证内容）

For the larger fixed corpus used by demos and evals, make demo loads a synthetic dataset — the pipeline shape, never a benchmark, a customer or an incident. Every row is is_synthetic = true and labelled in the console.

对于演示和评估中使用的大型固定语料库，make demo 会加载一个合成数据集——仅用于展示管道形态，绝非基准测试、客户数据或真实事件。每一行数据都标记为 is_synthetic = true 并在控制台中显示。

Connect real data Push, with a credential from make ingest-token (the tenant comes from it, not a header): curl -X POST http://localhost:8081/v1/ingest/batch \ -H ‘Content-Type: application/json’ -H “Authorization: Bearer $AISOC_INGEST_TOKEN” \ -d ’{“connector_id”:“edr-1”,“connector_type”:“crowdstrike”,“events”:[{“severity”:“high”, “title”:“Encoded PowerShell from Office”,“host”:“WIN-FIN-01”}]}’ Or pull, by configuring one of 90 click-and-connect data connectors in Settings → Connectors — Splunk, Sentinel, Elastic, CrowdStrike, Okta, AWS and Kubernetes audit among those with vendor-specific normalization and setup docs (coverage).

连接真实数据：使用 make ingest-token 获取的凭据进行推送（租户信息来自凭据，而非标头）：curl -X POST http://localhost:8081/v1/ingest/batch \ -H 'Content-Type: application/json' -H "Authorization: Bearer $AISOC_INGEST_TOKEN" \ -d '{"connector_id":"edr-1","connector_type":"crowdstrike","events":[{"severity":"high", "title":"Encoded PowerShell from Office","host":"WIN-FIN-01"}]}' 或者通过在“设置”→“连接器”中配置 90 个即插即用数据连接器之一进行拉取——Splunk、Sentinel、Elastic、CrowdStrike、Okta、AWS 和 Kubernetes 审计等均包含在内，并配有特定于供应商的标准化和设置文档（覆盖范围）。

Without a vendor profile a connector still ingests through a generic mapping that resolves host, user and source IP. A real cloud estate does not hand you its logs over a REST call. Four collectors read the surfaces one actually emits to: a CloudTrail organisation trail on S3 notified over SQS (management events, data events and VPC flow logs), a GCP Pub/Sub subscription on a Cloud Logging sink, an Azure Event Hubs capture, and a syslog/CEF listener. Each keeps a resumable cursor and a bounded per-poll budget, so a backlog applies backpressure instead of flooding ingest. Bringing existing detections? packages/aisoc-migrate translates Splunk SPL, Sentinel KQL and Elastic EQL and refuses rather than approximating what it cannot carry, because an almost-right rule is harder to find than a missing one: of

如果没有供应商配置文件，连接器仍可通过通用映射进行摄取，该映射可解析主机、用户和源 IP。真实的云环境不会通过 REST 调用直接交付日志。四个收集器会读取实际输出的表面：通过 SQS 通知 S3 上的 CloudTrail 组织跟踪（管理事件、数据事件和 VPC 流日志）、Cloud Logging 接收器上的 GCP Pub/Sub 订阅、Azure 事件中心捕获以及 syslog/CEF 监听器。每个收集器都保持一个可恢复的游标和有限的轮询预算，因此积压数据会产生背压，而不是淹没摄取接口。需要迁移现有检测规则？packages/aisoc-migrate 可以转换 Splunk SPL、Sentinel KQL 和 Elastic EQL，对于无法转换的内容，它会拒绝而非进行近似处理，因为“几乎正确”的规则比“缺失”的规则更难排查。