Design & architecture设计与架构

Deterministic first.
LLM where it helps.
确定性优先,
LLM 只在帮得上的地方。

The whole design follows one belief: known-CVE detection is a job for deterministic tools, and the LLM earns its place only in the assist role. Here is how that belief shapes the layers, the orchestrator, and the repo. 整个设计遵循一个判断:已知 CVE 检测是确定性工具的活,LLM 只在辅助角色里才配上场。下面是这个判断怎么塑造了分层、编排器和仓库结构。

Read on GitHub去 GitHub 看源码 The four principles看四条原则
3
layers · L1 · L2 · L3检测层 · L1 · L2 · L3
10
tools, cloned not vendored工具 · 克隆不入库
0
tool bytes in git工具字节进 git
Four principles四条原则

What the design commits to.设计上认死的四件事。

1 · Deterministic before LLM1 · 确定性先于 LLM

cvehound's coccinelle rules and git-commit comparison are the core of ① — reproducible, no hallucination. The LLM post-processes, it doesn't lead.cvehound 的 coccinelle 规则和 git commit 比对是 ① 的核心——可复现、不幻觉。LLM 做后处理,不当主角。

2 · Skip, don't fail2 · 缺了就跳,不报错

A missing scanner is marked skipped with a reason, never a crash. A partial report is useful; a stack trace is not. "skipped" is honestly labelled as "not run", not "clean".缺个扫描器就标 skipped 带原因,绝不崩。半份报告有用,堆栈没用。"skipped" 老实标成"没跑",不是"没问题"。

3 · Layers stay separated3 · 三层始终分开

L1 facts, L2 hints and L3 measurements are shown separately in the report. An LLM "suspected" finding is never presented as an L1 "confirmed" one.L1 事实、L2 提示、L3 实测在报告里分开呈现。LLM 的"疑似"绝不冒充 L1 的"确认"。

4 · Reproducible, not vendored4 · 可复现,不塞字节

The 10 third-party tools are cloned by a script, never committed. The repo tracks method + orchestration; clone-tools.sh rebuilds the tree anywhere.10 个第三方工具靠脚本克隆,绝不提交进库。仓库只版本化方法 + 编排;clone-tools.sh 在任何机器重建工具树。

Inside ksecksec 内部

How one scanner runs.一个扫描器怎么跑。

Every scanner follows the same lifecycle: is the tool present? If not, record skipped. If yes, run it, normalize its output to JSON, and let report merge it. 每个扫描器都走同一条生命周期:工具在不在?不在就记 skipped。在就跑,把输出规整成 JSON,交给 report 合并。

1 scanner cvehound / … have(tool) ? skipped reason recorded, no crash run + normalize stdout → JSON result ksec report merge every JSON → md / html no yes main path skipped path
The lifecycle is identical for every scanner — presence check, run-or-skip, normalize to JSON, merge. A missing tool never stops the run. 每个扫描器生命周期一样——查在不在、跑或跳、规整成 JSON、合并。缺工具从不打断整轮。
Repo layout仓库布局

Where everything lives.东西都在哪。

linux-kernel-security-oss/
├── README.md            # overview + quickstart
├── docs/                # method notes 00–08 + this site
│   ├── 00-overview.md08-report-pipeline.md
│   └── index / usage / architecture.html
├── bin/
│   └── ksec             # L1 orchestrator (pure py3 stdlib)
├── harness/            # L3 dynamic
│   ├── ioctl_leak_probe.c
│   └── slabmon.sh
├── scripts/
│   ├── install-deps.sh  # one-command system deps
│   └── clone-tools.sh   # fetch the 10 tools
├── repos/              # cloned tools (bytes NOT in git)
└── .claude/commands/   # /kernel-sec-audit (L2)
The honest part诚实的部分

What the LLM is not.LLM 不是什么。

Don't expect "let Claude read the whole kernel and find bugs" — false-positive rates are high and the context won't fit. State-of-the-art CVE discovery is always LLM paired with a fuzzer, a static checker, or CodeQL. The LLM's real value here is post-processing, explanation, and spec synthesis. 别指望"让 Claude 读整棵内核源码帮我找洞"——误报高、上下文塞不下。实产 CVE 的做法都是 LLM 配 fuzzer、静态 checker 或 CodeQL。LLM 在这里的真实价值是后处理、解释和规格合成。

And every LLM finding is verified back against source and, where possible, measured on a device. The LLM proposes; the deterministic layers and your own testing dispose. 而且每条 LLM 发现都要回源码验证,能实测就实测。LLM 只负责提出;确定性层和你自己的测试负责定夺。