AiSOC Show HN 发布文案的技术解读：60 秒告警分诊背后的确定性评分栈与诚实评测口径

• 人工智能
• AI Agent
• 网络安全
• 后端
• 前端

AiSOC 是一个 MIT 许可、可自托管的开源 AI SOC（安全运营中心），而marketing/launch/show-hn.md是它为 Hacker News "Show HN" 准备的发布稿。这份稿件表面上是营销文案，实际上每一句话都被仓库里的代码、测试和评测数据钉住：200 条确定性 fixture、一个约 200 行的加性评分函数、一份与服务端逐字节对齐的 TypeScript 移植，以及一套明确区分"substrate 自检"和"wet eval（真 LLM 调用）"的评测体系。本文以该发布稿为主线，逐段拆解它承诺了什么、仓库如何兑现，以及你在复用这套文案或这套工具时需要注意的边界条件。

一、这份发布稿的定位：一个 60 秒的"楔子"，不是全栈演示

发布稿的第一段就把产品拆成两层：完整的 AI SOC 全栈（connectors → OCSF 归一化 → Kafka → fusion → 自动分诊 → 受治理的响应，外加记录每一次 agent prompt、工具调用和推理依据的 Investigation Ledger），以及一个零安装的前门——npx aisoc triage --demo。

前门的价值在于时间成本。全栈是一次约 3.5 分钟的 Docker 承诺（首次拉镜像更久），而 CLI 的目标是"一分钟内拿到一个判决"。这条路径刻意不依赖账号、Docker、API key 或网络。

1.1 原始文案（Title / Body）

发布稿给出的标题与正文如下，可直接作为文案骨架复用：

Show HN: AiSOC – open-source AI SOC; triage a batch of alerts in 60s with `npx aisoc`

Hi HN — I've been building AiSOC, an open-source, self-hostable AI SOC (security operations center). The whole thing is MIT-licensed: the agent, the detection substrate, and the console. The fastest way to see what it does, with zero setup: npx aisoc triage --demo That runs a bundled, fully-deterministic 200-alert fixture through the same triage verdict engine the full stack uses, and prints a table of verdicts (escalate / review / suppress) plus a one-line summary. No account, no Docker, no API key, no network. It finishes in well under a second. Two things I wanted to get right, because they're what I'd want from a security tool: 1. Deterministic by default. The verdict engine is a plain, readable scoring function — no LLM call required. An LLM "band" is optional and only runs if you pass your own API key, which is used to call the provider directly and is never proxied through any server we run. Every "viral" surface (the CLI, the free web tools, the shareable replays) works with zero keys. 2. Honest evals. There's a public eval harness that gates every PR. It's explicit about what's a real measurement vs. a substrate self-consistency check over a synthetic dataset — the benchmark page spells out exactly what each suite does and doesn't prove. The `--demo` number above is a synthetic fixture demonstrating the mechanism, not a claim about your environment. The full stack (connectors → OCSF normalize → Kafka → fusion → auto-triage → governed response, with an Investigation Ledger that logs every agent prompt, tool call, and rationale) is a `docker compose up` away, and there's a zero-dependency Python sandbox (`pip install -e packages/aisoc-sandbox`) if you don't want Docker.

注意正文里两个刻意的克制：一是把--demo的收益明确定性为"演示机制"，而不是"对你的环境的性能主张"；二是把"autonomous"这个词从默认叙事里摘掉——响应默认走 copilot / dry-run。

1.2 一个必须先读的发布前置条件

发布稿开头有一段几乎比正文更重要的警告：aisoc在每次打 tag 时都会被构建和打包，但从未上传到 npm，因此npx aisoc今天并不解析。阻塞点是 npm 凭据（账号侧操作），不是代码。

这一点在 CLI 包的 README 中被重复声明，并给出了从克隆仓库运行的等价命令：

pnpm --filter aisoc build && node packages/aisoc-lite/dist/cli.js triage --demo

这就是为什么发布稿要求你在发文前二选一：要么先完成首发上传，要么把所有npx aisoc命令替换为上面的从克隆形式。npx与本地构建之间的差异只影响分发，不影响 verdict 引擎——packages/aisoc-lite/package.json里bin.aisoc指向dist/cli.js，npm run smoke走的正是同一条路径。

从源码结构看，这也解释了一个容易踩的坑：aisoc是 pnpm workspace 内的包（name: "aisoc"，publishConfig.provenance: true），必须通过 workspace 过滤构建，单独的npm install不会把dist/生成出来。

二、npx aisoc triage --demo究竟执行了什么

把 CLI 展开，一次triage --demo是六步流水线，入口在 cli.ts，业务编排在 triage.ts。

2.1 参数解析：手写解析器而非框架

parseArgs只有约 20 行：以--前缀判定 flag，若下一个 token 不以--开头则当作该 flag 的值，否则视为布尔真。这个设计的目的写在文件头注释里——CLI 只有一个运行时依赖（picocolors），保证npx冷启动快、供应链面小。"这是安全工具，每个依赖都是负债"。

值得注意的解析细节：

• --share支持省略值（--share→true）或带路径（--share out/card）；
• --max-rows用带连字符的键名映射到maxRows；
• toBool把字符串"false"/"0"视为假，其余字符串为真；
• 未知命令返回退出码 2，运行时异常返回 1，成功返回 0——便于 CI 与脚本消费。

2.2 数据源解析与归一化

resolveSource的优先级是：--demo>--file <path>>--source <name>（缺省demo）。允许的 source 为demo | jsonl | splunk | sentinel | elastic | crowdstrike。

这里是发布稿"works with zero keys"承诺的技术落点，也是最容易被误读的地方。看 sources.ts 的实现：

• demo读取打包进二进制/包内的确定性 fixture；
• jsonl读取本地 JSONL 或 JSON 数组（整份文件是对象且含alerts字段时也会被接受）；
• splunk/sentinel/elastic/crowdstrike四个 live 适配器当前直接抛错，提示这些源需要凭据、请改用--demo或导出为 JSONL，并注明 live connector 认证随 v8 CLI GA 落地。

也就是说，--source splunk今天不是一个可用的免密 PR 通道，而是一个明确的占位与引导。写文案时若把"支持 Splunk/Sentinel/Elastic/CrowdStrike"说成"可直连"，就与源码事实不符——仓库里能确认的是字段级的自动识别，不是凭据级的直连。

normalizeRecord才是真正的兼容层，它用一组候选键名把各家厂商的告警压平成统一的Alert：

两个值域转换函数同样是"让原始导出一把梭"的关键：

• coerceSeverity把informational/none/notice映射为info，warning/warn/moderate→medium，severe/urgent→critical；纯数字则按≥9 critical / ≥7 high / ≥4 medium / ≥1 low分档。
• coerceRisk把 0–100 与 0–1 两种风格的 risk 统一到[0,1]：>1时除以 100，否则原值截断到非负。

2.3 批量评分与排序

triageBatch对每个 alert 调用scoreAlert，然后按true_positive → likely_true_positive → needs_review → likely_benign排序，同档内按置信度降序。这解释了终端表格为什么"先看到要处理的"。summarize负责汇出可复制粘贴的一句话摘要，并统计noisePercent（保留一位小数）。

--limit在数据源加载后切片，--max-rows（默认 20）只影响渲染，不改变评分集合——这意味着摘要里的总数与你看到的行数可以不一致，属于设计而非 bug。

2.4 渲染、分享卡与遥测

渲染层 table.ts 不引入任何布局依赖，手工做定宽对齐，并且用正则剥掉 ANSI 转义再计算可见宽度，保证带颜色的单元格仍然对齐。列宽固定为11 / 14 / 6 / 42 / 34，标题与证据超出即截断为省略号。--attention-only在渲染前过滤掉likely_benign。

摘要行的徽标直接暴露了这次运行的性质：

• deterministic: true→[deterministic · no LLM]
• 被 LLM 精修过 →[LLM-assisted]

这正是发布稿"deterministic by default"在界面上的可见证据。

三、200 条 fixture 是怎么造出来的

--demo的可信度取决于 fixture 的可复现性。gen-fixtures.mjs 用一个固定种子的mulberry32PRNG（种子0x415_50c）生成全部字段，不使用墙钟、不使用网络，重跑即字节级复现src/fixtures/demo-alerts.json。

分布是被刻意设计的，而且被测试钉死：

生成结束后做一次基于同一 PRNG 的 Fisher–Yates 洗牌，避免 fixture 文件里已经按档位排好序——排序是引擎的职责（triageBatch），不是数据的属性。

由此得到的 headline 在 README 中被展示为：

✓ AiSOC triaged 200 alerts: 12 TP, 171 FP suppressed (85.5% noise), 17 need review — in 0.1s [deterministic · no LLM]

85.5%来自171 / 200。这条字符串不是手写文案，engine.test.ts 断言了四件事：fixture 恰好 200 条、分布恰为 12/17/171、两次运行的(id, verdict, confidence)完全一致、以及 headline 的精确格式（测试用 4200ms 注入，断言— in 4.2s）。一旦有人改动摘要措辞或分档边界，CI 会失败。

四、确定性评分栈：一个可以手算的函数

发布稿的第一条 first-comment 承诺："triage scoring is an additive weight stack … clamped to [0.05, 0.95], mapped to four bands. It's ~200 lines"。这个描述与 stages.ts 完全对得上，而该文件是 scoring.py 中score_triage的忠实移植。

4.1 权重栈

所有分支相加后经clamp压到[0.05, 0.95]。理论上限是0.6 + 0.35 + 0.15 + 0.12 + 0.05 = 1.27，因此高分告警必然被压到 0.95——这是刻意的设计约束：永不断言确定性，也永不断言不可能。

关键词集合与 Python 原版逐字一致：

critical: ransomware, lateral movement, credential dump, exfiltration, mimikatz, cobalt strike, c2, rootkit, supply chain, zero-day, data breach high: phishing, malware, exploit, privilege escalation, brute force, suspicious login, anomaly, backdoor

匹配方式是对title + raw + JSON.stringify(iocs)拼接后转小写做子串包含。注意c2这种短词会带来误报面（例如某些哈希或域名片段），这是确定性打分器的固有代价，也是后续 LLM band 存在的原因之一。

4.2 四个档位与建议动作

recommendationFor用switch+never穷尽守卫：将来新增一个 verdict 层级而不处理它，TypeScript 会在编译期报错，而不是在运行时静默返回undefined。

4.3 可解释性：basis 与 evidence

scoreAlert同时产出两份解释：

• basis: string[]：人类可读的逐条依据，例如vendor risk_score=0.90、critical-severity keyword match in alert text、3 MITRE technique ID(s) attached；
• evidence: EvidenceFactor[]：结构化因子（factor / detail / contribution），按贡献绝对值降序，只保留前 3 条。

终端表格的 "TOP EVIDENCE" 列取evidence[0].detail，回退到basis[0]。share.ts生成的报告卡则完全不含这些内容——它只有聚合计数。

如果一条告警什么信号都没有，basis会被补上一条no salient signals — defaulting to floor confidence，并把no_signal因子（贡献 0）塞进 evidence。这保证"为什么它被判为噪声"永远有一个显式答案，而不是空数组。

五、parity：为什么 CLI 的判决等于服务端的判决

这是发布稿里最容易被挑战的点——"a CLI verdict lands in the same band the server would assign"。仓库用两层测试回应。

5.1 常量与边界钉死

stages.test.ts直接 import 了_internals（CONF_FLOOR、CONF_CEIL、CRITICAL_KEYWORDS、HIGH_KEYWORDS、verdictBand），并断言：

• floor/ceil 恰为0.05 / 0.95，空告警的置信度不低于 0.05，全信号告警不高于 0.95；
• 分档边界精确到小数点后两位：0.80 → true_positive、0.79 → likely_true_positive、0.60 → likely_true_positive、0.59 → needs_review、0.40 → needs_review、0.39 → likely_benign；
• recommendationFor四个输入全覆盖。

5.2 手算得出来的那一条用例

最有说服力的测试是一条可以口算的用例：

risk 0.5 → min(0.5 × 0.6, 0.6) = 0.30 "phishing email" 命中 high 关键词 → +0.20 1 个 IOC（srcIp） → min(1 × 0.05, 0.15) = 0.05 合计 = 0.55 → needs_review

测试断言confidence ≈ 0.55且verdict === "needs_review"。当一次移植的每个系数都可手算复现时，"parity" 就不再是口号。

需要说明的是，仓库能确认的是评分函数的系数、分档阈值与关键词集合与 Python 原版一致；服务端的score_triage还额外读取state.mitre_mappings（来自 agent 状态，而不仅是原始告警字段），因此同一条告警在两条路径上的输入可能有差异。CLI 侧的techniques来自归一化后的Alert，这是"同分档"承诺成立的前提条件。

5.3 校准门槛在服务端

scoring.py的设计文档明确写了校准由services/agents/tests/test_confidence_calibration.py执行，构建会在指标越界时失败。当前仓库中该测试的阈值常量为：

BRIER_THRESHOLD_TRIAGE = 0.20 ECE_THRESHOLD_TRIAGE = 0.20 BRIER_THRESHOLD_INVESTIGATION = 0.18 ECE_THRESHOLD_INVESTIGATION = 0.18

这印证了发布稿 first-comment 里"pinned by a calibration test (Brier + ECE thresholds) against a 200-incident synthetic corpus"的说法——但要注意，这是substrate 上的校准约束，不是"agent 在真实遥测上准确率很高"的同义词。

六、可选的 LLM band：只碰"模糊的中间"

第二条承诺是"BYO-key, never proxied"。llm.ts 的行为可以完整描述为四条：

第一，只有--llm才触发。默认路径永远不 import 到网络调用分支之外的行为（demo 与 CI 路径不会走到这里）。

第二，必须有用户自己的 key。detectProvider读取ANTHROPIC_API_KEY（默认模型claude-3-5-haiku-latest）或OPENAI_API_KEY（默认gpt-4o-mini），两者都可用AISOC_LLM_MODEL覆盖；都没有则打印一条黄色提示并保持确定性结果。

第三，只精修needs_review档。triage.ts在确定性结果出来后筛出verdict === "needs_review"的告警送进模型。这是"LLM band 叠加在确定性地基上"的字面实现：地基决定哪些分数值得再问一次。

第四，直连 provider，不经任何 AiSOC 服务。Anthropic 走https://api.anthropic.com/v1/messages，OpenAI 走${OPENAI_BASE_URL || "https://api.openai.com/v1"}/chat/completions。OPENAI_BASE_URL的存在意味着你可以指向自建兼容网关，这也说明"不代理"是架构事实而非承诺措辞。

提示词层面有两个工程细节值得借鉴：

• system prompt 要求返回紧凑 JSON（{"verdicts":[{"id","verdict","confidence","rationale"}]}），并显式要求"保守，宁可needs_review也不要猜"；
• parseRefinements用"第一个{到最后一个}"的粗粒度切片再JSON.parse，解析失败返回空数组；置信度被重新 clamp 到[0.05, 0.95]。

应用精修时，applyRefinements会重算recommendation，往basis追加一条(LLM band refined this verdict)，并把整份结果的deterministic置为false——于是 headline 徽标从[deterministic · no LLM]变成[LLM-assisted]，读者一眼能看出这次输出是否被模型影响过。任一步骤抛错都会退回确定性判决，而不是让 CLI 失败。

七、"Honest evals"：这套评测到底证明了什么

发布稿第二条承诺是评测的诚实性，并把细节指向 benchmark 页面（apps/docs/docs/benchmark.md）。该页的核心是一张二分表：

页面写明的工作区规则是：绝不把 substrate 自检当作 live agent 性能呈现。这条规则直接对应发布稿里那句"The--demonumber above is a synthetic fixture demonstrating the mechanism, not a claim about your environment."

7.1 最新结果与两套"降噪数字"

两个降噪数字并存的原因被单独用一节解释，这也是整套评测里最值得学习的部分：legacy 套件在测试内部实现了一套与产品不同的四层分组（按(rule_id, host, user)，窗口 10/30/5 分钟），而生产Correlator调用的RawAlert.correlation_key()是按{tenant}:{entity}:{tactic}、一小时窗口分组。维度不同、窗口不同，答案就不同。于是 75.3% 描述的是一个产品并不运行的算法；真正对应的数字是 33.3%，更难听，但是自己的。

更关键的是这个新门槛是双边有界而非单边下限：只有下限时，一个把所有告警塌缩成一条 incident 的 key 也能满足（99.9% 降噪 + 一个没用的 SOC），所以"降得越多越好"只在某一点之前成立，门槛要说出那一点在哪。

7.2 判决质量：承认模型接近随机

benchmark 页面里最反营销的一段，是用 36 对"孪生样本"（共 72 条，同标题、同规则、同严重度、同厂商、同技术点，只有证据不同）测出的结果：四分类下常数回答的 balanced accuracy 是 0.250，而实测最好的llama3.1:8b-instruct-q4_K_M只有 0.357，mistral:7b甚至只有 0.210（因为它弃权 31%，而 plain accuracy 会给它 0.500 的高分）。结论被直接写出来：每一个被测模型都远更接近随机而非有用，并且自动关闭（auto-close）的精确率在 0.091–0.571 之间，不支持自主关单。

这正好解释了发布稿为什么在 "Do / don't" 里要求：

• Do链接 benchmark 页面，并在开头就说明 copilot/dry-run 默认；
• Do邀请对架构和评测的审视；
• Don't引用任何不在 benchmark 页面上的 precision/recall 数字；
• Don't在没有 copilot 默认前提的情况下称它 "autonomous"。

7.3 提示注入：两个数字与 91 分的差距

页面还公开了一组对比：PromptInjectionGuard在它被加固过的语料上检出 98.1%（53/54），而在冻结之后由读过规则的人新写的 held-out 语料上只有 7.1%（2/28）。作者明确表示这 91 分的差距就是"多少加固其实是在拟合模式"的诚实度量，并且不给 held-out 率设下限——因为对 held-out 集设目标，本质上就是在指示自己针对它调参。CI 只强制"测量必须发生，且页面数字与测量一致"（scripts/check_injection_eval.py）。

这套方法论对任何写安全工具发布稿的人都有直接借鉴价值：区分"确定性回归"和"行为测量"，把前者做成每 PR 的门槛，把后者做成周更并允许它显示"not measured"而不是 0。

八、默认静音的遥测

发布稿承诺"no account, no Docker, no API key, no network"。TELEMETRY.md 把这个"no network"扩写成一条可验证的策略：

优先级从高到低：--no-telemetry→--telemetry→AISOC_TELEMETRY=0→AISOC_TELEMETRY=1→ 默认关闭。

开启后发送的完整载荷只有聚合计数与运行元数据：

{ "event": "triage", "version": "0.1.0", "source": "demo", "total": 200, "truePositive": 12, "needsReview": 17, "suppressed": 171, "deterministic": true, "elapsedMs": 63 }

永不采集的清单被逐项列出：告警标题与描述、任何原始事件文本、IOC、主机名与用户名、文件路径与内容、API key、被翻译的检测规则、以及任何逐告警数据。src/telemetry.test.ts用单测断言载荷构造器无法把告警内容塞进去。

还有一条容易被忽略但很重要的事实：没有默认端点，项目不运营任何 collector。开启遥测但不设置AISOC_TELEMETRY_ENDPOINT时，完全不发生网络调用；设置后才以 2 秒超时 POST 到你自己指定的地址，且错误被静默忽略——遥测永远不会让 CLI 失败或变慢。文档还坦白了一个历史教训：它曾经默认指向一个已不再解析的托管 collector，导致"用户同意发送的数据被丢弃"，而这比不采集更伤信任，所以现在发送必须给出显式目的地。

九、--share与两条"看得见"的出口

9.1 可发布的报告卡

--share [path]把一次运行渲染成 Markdown + 自包含 SVG 两张产物，默认基线名aisoc-report-card.md，SVG 取同名的.svg。

隐私边界写在 share.ts 的注释里：卡片只包含聚合计数与 verdict 档位元数据，不含告警标题、IOC、主机名、用户名，因此"可以不做脱敏审查直接发"。渲染委托给共享包@aisoc/report-card（与降噪看板、Web OG 图使用同一渲染器），在构建期打进了 CLI，保证npx aisoc仍是单一自包含产物。SVG 尺寸为 1200×630，即社交平台的 unfurl 比例。

9.2 全栈与零依赖沙箱

发布稿给了两条"往上走"的路径：

• 全栈：docker compose up。仓库内的入口是根目录Makefile的make up（make demo会额外灌入带is_synthetic=true标记的合成数据），编排文件在 infra/compose/docker-compose.demo.yml，另有airgap / gpu / host-llm / dev等变体。CLI 也提供aisoc up：它会校验 Docker 是否存在、把--ref限制在[A-Za-z0-9._/-]+（防止把 compose URL 改写到任意主机）、把固定 ref 的 compose 文件拉到临时目录再docker compose -f ... up -d，最后打印控制台地址（localhost:3000/cases/INC-RT-001?tab=ledger）。
• 零依赖沙箱：pip install -e packages/aisoc-sandbox（或pip install aisoc-sandbox）。它把一条告警 fixture 走过Detect → Triage → Hunt → Respond四段漏斗，用确定性离线推理器替代真实 LLM，并把 Investigation Ledger 打到终端。包体 < 50 KB、启动 < 5 秒、Python 3.10+、零运行时依赖；它自己也声明了取舍——推理是确定性的、工具是模拟而非真正执行的。

两条路径的关系是"演示深度"与"启动成本"的权衡：CLI 给一条判决，沙箱给一条四段调查链路加账本，全栈给真实的 connectors / Kafka / fusion / 受治理响应。

十、把这份稿件变成可复用的发布检查表

发布稿最后的 "Do / don't" 虽然只有四条，但每一条都对应本文前面某处可验证的事实。把它扩成一张发布前自检表更实用：

对照发布稿里的两个 URL：Repo: https://github.com/beenuar/AiSOC与Benchmark methodology: .../apps/docs/docs/benchmark.md。在仓库内传播时，后者应写成相对路径 apps/docs/docs/benchmark.md；前者的价值是给出可克隆地址，仅在需要说明git clone时保留。

十一、结论：这份发布稿真正在卖什么

它没有卖"最强的 AI SOC"，也没有给出任何 precision/recall 承诺。它卖的是三件可以当场验证的事：

1. 一条能在一秒内跑完、且结果可复现的命令——200 条 fixture、固定 PRNG 种子、被测试钉死的分布与摘要格式；
2. 一个你能读懂、能口算、与服务端系数一致、并且解释自己每一个判断的评分函数——加性权重、双边 clamp、四档映射、basis+ top-3evidence；
3. 一套愿意公布难听数字的评测——33.3% 而不是 75.3%，0.357 而不是"接近人类"，7.1% 而不是 98.1%，以及"not measured" 而不是 0。

对准备复用这份文案的人，最实际的建议是：先把packages/aisoc-lite构建起来，跑一遍triage --demo，亲手核对那行12 TP, 171 FP suppressed (85.5% noise), 17 need review；再打开stages.ts按权重表手算一条你自己构造的告警。当这两步都成立时，文案里的每一句话你都拥有了证据——这也正是这份 Show HN 稿件从"营销稿"变成"技术文档"的地方。

• 人工智能
• AI Agent
• 网络安全
• 后端
• 前端