# Nexus 逐行走读审计标准（SSOT）

**版本**: 2026-05-22  
**状态**: 生效  
**Cursor 规则**: ` `  
**关联计划**: `.cursor/plans/nexus_全面代码审计_a33e6fc2.plan.md` §11

与 **Phase 1（攻击面抽查）** 严格区分。未满足本文 DoD 的文件不得标记「逐行完成 ✓」。

---

## 1. 术语

| 术语 | 定义 |
|------|------|
| **走读** | 对单文件按行号顺序阅读源码，并对规则命中点做上下文分析 |
| **触达** | 仅 grep/打开文件，未满足走读 DoD |
| **规则命中** | §4 规则表在某行产生的匹配，记入列表 H |
| **Closure** | 对一条命中的判定：`SAFE` 或 `FINDING`（含行号、理由） |
| **DoD** | §6 单文件完成定义 |

---

## 2. 适用范围

| 包含 | 排除 |
|------|------|
| `server/**/*.py` | `docs/**`（仅 §8 密钥扫描） |
| `web/app/*.{html,js}` | `frontend/node_modules/**` |
| `web/agent/**` | 第三方 minified |
| `scripts/**`、`deploy/**`、`tests/**` | 图片、字体 |

---

## 3. 单文件走读流程（8 步）

```
Step 1  登记：path、语言、行数 N
Step 2  全文 Read 至 EOF（分段 limit≈200；末段 offset ≥ N-5）
Step 3  规则扫描 → 命中列表 H
Step 4  对 H 每条 Read ±15 行 → Closure 表
Step 5  API/WS：入口表（方法、路径、鉴权）
Step 6  外部输入 → sink
Step 7  八类核对（§7）
Step 8  DoD（§6）→「逐行完成 ✓」
```

**单会话上限**：最多 **5 个文件**。

---

## 4. 规则表（100% Closure）

### 4.1 Python

| ID | rg 示意 | 审查要点 |
|----|---------|----------|
| PY-01 | `f"…{…}…` + exec/shell/ssh/sysctl/curl/sudo/bash | 是否经 shell？**整段** `key=value` 是否安全引用？ |
| PY-02 | `subprocess.` / `create_subprocess_shell` / `os.system` | shell=True？命令来源？ |
| PY-03 | `exec_ssh_command` / `conn.run(` | 远程 shell 拼接？ |
| PY-04 | `text(` / `execute(` / `raw(` | SQL 注入？ |
| PY-05 | `@router.` / `websocket` | JWT / API Key？ |
| PY-06 | 字面量 `API_KEY` / `SECRET` / `password` | 硬编码密钥？ |
| PY-07 | `pickle` / `yaml.load` / `eval(` / `exec(` | 危险反序列化/执行 |
| PY-08 | API Key `==` / `!=` | 应用 `secrets.compare_digest` |
| PY-09 | `except: pass` | 吞安全异常？ |
| PY-10 | `open(` / 写路径 | 路径遍历？ |

### 4.2 前端

| ID | rg 示意 | 审查要点 |
|----|---------|----------|
| FE-01 | `innerHTML` / `outerHTML` | 每个 `${}` 是否 `esc()` |
| FE-02 | `localStorage` | JWT/密钥？ |
| FE-03 | `WebSocket` + `token` | Token 在 URL？ |
| FE-04 | 裸 `fetch` | 绕过 `apiFetch`？ |
| FE-05 | `onclick=…${` | JS 属性注入？ |
| FE-06 | `cdn.` / `<script src` | SRI？ |

### 4.3 Shell / Deploy / SQL

| ID | 范围 | 要点 |
|----|------|------|
| SH-01 | `*.sh` | 变量引用、curl 密钥 |
| DP-01 | `deploy/nginx*.conf` | CSP、TLS |
| SQL-01 | `*.sql` | `GRANT ALL`、`'%'` |

**H=0**：仍须 Step 2 全文 Read，Closure 表注明「规则零命中」。

---

## 5. Closure 表格式

```markdown
| 文件 | 行号 | 规则 | 判定 | 严重度 | 理由 |
|------|------|------|------|--------|------|
| sync_engine_v2.py | 236 | PY-01 | FINDING | P1 | sysctl 仅 quote value，' 可断 shell |
| sync_engine_v2.py | 95 | PY-01 | SAFE | — | rsync 双端 shlex.quote |
```

- **SAFE**：写明依据（argv、Pydantic、常量等）
- **FINDING**：对应 §7 八类 + 一行修复建议

---

## 6. 单文件 DoD

- [ ] Read 覆盖 `1..N`（报告注明 N 与 Read 范围）
- [ ] `len(H) == Closure 行数`
- [ ] 有路由则有入口表；纯 `__init__.py` 可 N/A
- [ ] 已标输入→sink 或「无外部输入」
- [ ] 八类已勾
- [ ] 无「Top 15」「已审计 ✓」式笼统结论

---

## 7. 八类与严重度

| 类 | 代号 | P0 例 | P1 例 |
|----|------|-------|-------|
| 功能缺陷 | BUG | — | 统计与列表不一致 |
| 安全漏洞 | VULN | 未授权 RCE、IDOR Shell | XSS、命令注入、密钥回读 |
| 规范违规 | STYLE | — | 未 esc 的 innerHTML |
| 安全风险 | RISK | 仓库生产 API Key | 明文 HTTP Agent |
| 性能 | PERF | — | 心跳直写 MySQL |
| 可用性 | UX | — | 静默失败 |
| 可扩展性 | EXT | — | 无全局 JWT 中间件 |
| 优化点 | OPT | — | 重复 esc 函数 |

**KPI**：P0 漏报 -100；P1 漏报 -50。FINDING 必须 `文件:行号`。

---

## 8. 批次交付物

路径：`docs/reports/audit-phase-2{X}-line-walk.md`

必含：文件清单、Findings、**Closure 全表（含 SAFE）**、入口表（API 批次）、走读签字。

推荐批次：

| 批次 | 目录 |
|------|------|
| 2a | `server/api/` |
| 2b | `server/application/services/` |
| 2c | `server/infrastructure/` |
| 2d | `server/background/` + `main.py` + `config.py` |
| 2e | `web/app/` |
| 2f | `web/agent/` + `scripts/` + `tests/` |
| 2g | 脚本执行：`script_execution_store.py`、`script_jobs.py`、`script_service.py`（扩容重走） |
| 2h | `server/api/scripts.py`（executions）、`agent.py`（callback）、`web/app/scripts.html`、`script-executions.html`、`web/agent/agent.py`（exec 增量） |

---

## 9. 禁止行为

1. 无 `文件:行号` 的 FINDING  
2. `rg 命中 ≠ Closure` 仍标完成  
3. 子代理 Top 15 代替 Closure 全表  
4. 单回复声称整库完成  
5. 审计与修代码混做（除非用户明确要求）

---

## 10. Phase 1 vs Phase 2

| Phase 1 | Phase 2 |
|---------|---------|
| 攻击面抽查 | 本标准走读 |
| 计划 §0–§8 | `docs/reports/audit-phase-2*.md` |

Phase 1 的 FINDING 须在 Phase 2 **VERIFY**（确认行号或说明关闭原因）。

---

## 11. 执行 Prompt（复制）

```
按 docs/project/line-walk-audit-standard.md 执行 Phase 2 走读。
范围：{目录}
禁止攻击面抽查；每文件 8 步；单回复最多 5 个文件。
产出：docs/reports/audit-phase-2{X}-line-walk.md
从 sync_engine_v2.py 开始（若范围含 services）。
```
