Ernket / CodeScan-Artex

# SCA Audit
LLM 多 Agent 驱动的 **静态代码审计平台**（Go 后端 + Next.js 前端）
---
## 这是什么
SCA Audit 把「审计一个代码仓库」拆成**可并行的意图**，交给多个 LLM Agent 分工静态读完源码，把结果写成两张可回溯的图：**资产图**（这个系统对外暴露了什么）与**探索图**（我们是怎么一步步查到结论的）。
它和扫描器的区别在于**产出物**：
| | 扫描器 / SAST 规则 | SCA Audit |
| --- | --- | --- |
| 输入 | 代码 | 代码（**只读**） |
| 产出 | 规则命中列表 | **接口清单 + 每条接口所需权限**、缺陷结论（带 `文件:行号` + 代码片段）、依赖可达性判定 |
| 判断依据 | 模式匹配 | 读完整条**数据流**：参数从哪来 → 过没过校验 → 到没到 Sink |
| 误报处理 | 人工逐条看 | **独立会话复核**，结论三态回写漏洞状态 |
| 过程 | 黑盒 | 探索图 + 每次工具调用留痕，可复算 |
**只做静态分析。** 平台不发起任何网络请求、不执行任何系统命令、不做任何运行时验证——结论必须由源码证据支撑。这不是靠提示词约束，而是**在工具装配层物理删除**（见下节）。
---
## 安全边界（红线）
`agent/codeaudit_tools.go` 是「Agent 能调用什么」的唯一真源。工具来源侧是**三层防线**，缺一不可；写入侧另有拦截规则兜底：
**① Agent 的通用工具集只从 7 个本地文件工具构造**
 [code] 
没有 `Bash`。没有 `WebFetch` / `WebSearch`。其余全是平台自己的领域工具（登记资产、写回图、登记漏洞、依赖查询、复核结论）。
**② 装配层不再注入危险来源**
`server/hostTools()` 不返回流量工具、自定义工具与 MCP；`server/assembly.go` 不再展开 MCP 服务器——所以**连 `mcp__*` 工具都不会出现在 Agent 的工具列表里**。系统设置里的「MCP」「自定义工具」入口只保留历史数据查看。
**③ 兜底黑名单：配置也绕不过去**
即使有人往 DB 的 `tools` 表、可见性配置或宿主工具里塞进危险工具，也会在 `AugmentTools` 的最后一步按名字剔除：
 [code] 
**④ 写入侧还有拦截规则**
被测源码是审计证据，任何改动都会让结论不可复现。拦截规则按优先级匹配工具输入，首条命中即生效：
| 优先级 | 规则 | 匹配 | 动作 |
| --- | --- | --- | --- |
| 30 | 被测源码只读 | `\.\./source/` | 拒绝 |
| 20 | 工作区外写入需审批 | `\.\./` | 转人工 |
| 10 | 平台不出网 | `https?://` | 拒绝 |
拦截范围只覆盖写入类工具（`Write` / `Edit` / `MultiEdit`）——读工具的常规路径本来就是 `../source`、`../deps`。被拦下的调用会挂在任务详情的「拦截审批」里等人工裁决。
---
## 截图预览
> 以下截图取自 `NEXT_PUBLIC_MOCK=1` 的离线 Demo（无后端、内置 `acme-mall` 演示数据）。完整交互见在线 Demo。
| 仪表盘（总览 / Token 消耗 / 活动流） | 任务列表 |
| :---: | :---: |
| | |
| 任务 · 执行过程（会话 / 工具调用） | 探索链路（意图 · 事实 · 漏洞血缘） |
| :---: | :---: |
| | |
| 发现（跨任务漏洞汇总 · 按严重度 / 任务分组） | 漏洞复核（三态结论 + 逐条核对依据） |
| :---: | :---: |
| | |
| 测试资产 · 接口与**所需权限** | 资产覆盖图（力导向 · 已测高亮 · 节点折叠） |
| :---: | :---: |
| | |
| 第三方依赖（清单 / 类名索引 / 按需反编译） | 人在环路对话 |
| :---: | :---: |
| | |
| Agent 管理（提示词 / 工具 / 技能可见性） | LLM 配置（多档位 · 轮询与退避） |
| :---: | :---: |
| | |
| 后端日志（工具调用 / 拦截 / 依赖索引） |
| :---: |
| |
---
## 一次审计是怎么跑的
### 引擎与意图生命周期
引擎是**事件驱动**的闭环：图一变就唤醒 planner，planner 派意图，worker 领意图执行并写回，写回又触发下一轮——直到目标被证明（`prove_goal`）。
 [code] 
> **worker 的工作目录**是意图目录 `tasks/ /i `，因此代码在 `../source`、第三方依赖在 `../deps`。
### 双图架构：探索图 + 资产图
系统把「**要查什么**」和「**查到了什么程度**」拆成两张相互独立、又通过锚点相连的图：
 [code] 
- **资产图（全局共享）**：跨任务同一份的资产真值库，`exploration_anchors(node_id, asset_id)` 把探索节点锚定到具体资产。代码审计主要产出 **`app`（应用）** 与 **`endpoint`（接口）** 两类节点；接口节点带 `url / method / params / permission / file / line`。父子关系与去重 key 全部由程序计算，Agent 只提交原始信息。
- **探索图（每任务独立）**：节点为 `goal / intent / fact / finding / hint`，靠 `spawns / derived_from / yields / proves` 连成**血缘链**，回答「哪个方向派生自哪些事实、产出了什么缺陷」。
- 两图相连后，既能从「探索方向」看它查的是哪些接口，也能从「某个接口」反查它在本任务被哪些意图读过、得出过哪些事实——这支撑了**资产测试覆盖度**与**资产覆盖图**（范围内资产 + 已测高亮）。
### 接口权限判定（本平台的核心产出）
每个接口都要判定「**谁能调**」，取值六档：
`公开` / `注册用户` / `登录用户` / `管理员权限` / `内部接口` / `其他`
判定依据按优先级：① 网关白名单（最外层，命中即「公开」）② 类/方法级鉴权注解（`@PreAuthorize`、`@Secured` 等）③ 自研鉴权工具类与拦截器 ④ 路由分组与中间件注册范围。
两条容易判错的规则，平台按代码**实际生效**的边界记：
- **中间件兜底会骗人**：网关只验 token 有效性的路径，后端如果没注解，实际权限是「登录用户」而不是「管理员权限」——这类「标注权限 ≠ 实际权限」的接口会单独报出来。
- **没看到任何鉴权