# 資安檢視總報告 — 模組頁撰寫規格

**產出落點**：`docs/security-report/M<NN>-<slug>.md`（只寫 md，不要自己 build）
**範本**：`docs/security-report/M01-remote-agent.md` —— **動筆前先完整讀過這份**
**讀者**：PM 與老闆（不懂程式），以及稽核方。**不是工程師。**

---

## 一、這份文件是什麼、不是什麼

| 是 | 不是 |
|---|---|
| 決策者消化過、要拿去對客戶／老闆講的版本 | 原始技術報告的翻版 |
| 會被當成**稽核證據**（證明「我們確實檢視過」） | 內部施工紀錄 |
| 講「出事會怎樣、誰受影響、怎麼修」 | 講「程式碼哪裡寫錯」 |

原始技術報告保留在需求中心不動，**不要改那邊任何檔案**。

---

## 二、頁面固定五段，順序不可變

### front matter

```yaml
---
title: <中文模組名>
eyebrow: Guidant AI 資安檢視 · 模組報告
h1: <中文模組名>（<模組代號>）
lede: <一兩句：這塊做什麼＋這塊最值得知道的一件事>
---
```

### 第 1 段：這塊在產品裡做什麼

三到六句。**讀者可能完全不知道這是什麼東西**，要從「客戶會用到什麼功能」講起，不要從技術架構講。

如果這塊有「為什麼它是敏感目標」的理由（例如手上握有密碼、是所有功能的地基），用 `::: grid2` 兩張卡並排：左邊「它平常在做什麼」、右邊「為什麼它是敏感目標」。沒有這種理由就不要硬湊。

### 第 2 段：檢視軌跡  ← **這段是稽核證據，不可省略**

開頭一行：
```
**檢視期間**：YYYY-MM-DD ～ YYYY-MM-DD｜**範圍**：N 個檔案（若有細分就註明）｜**共 N 輪**
```

接一段引言，指向原始報告：
```
> **原始技術報告**放在需求中心的 [FR-0NN 站](https://guidantai-feature-doc.jedicotech.com/<資料夾名>/)，檔名見下表最後一欄。那裡有每一輪的完整技術細節、檔案清單與逐條推理，供需要深究或稽核抽查時查閱。
```

然後一張表：

| 輪次 | 查什麼 | 檔數 | 覆核投票 | 結果 | 原始報告檔名 |

- 「查什麼」寫白話（「代理程式怎麼證明我是誰」，不是「agent identity 與 enrollment」）
- 「覆核投票」寫實際票數（「15 票全投完」）或實際狀況（「覆核未完整跑成」）
- 「原始報告檔名」用行內程式碼標記包起來，**不要做成連結**（多數還沒發佈到公網，連過去是 404）

**只要有任何一輪的覆核沒跑完整，就要加一個 `::: {.callout .warn}` 說明**：為什麼沒跑成、我們怎麼補的。**不准隱瞞**——誠實交代在稽核場合是加分的。

**零發現的模組，這一段更重要**——那頁的全部價值就在於證明「有查」。

### 第 3 段：問題一覽表

**排序：先按風險（最嚴重→高→中→低），同風險的把同一分類排在一起。**

表頭固定：

| # | 問題 | 風險 | 分類 | 出事會怎樣（誰受影響） | 怎麼修 | 狀態 |

欄位規則：

- **#**：本頁內從 1 開始編。**不要用跨模組總表的編號**（那個是內部編號，讀者用不到）
- **風險**：`🔴 **最嚴重**` / `🟠 高` / `🟡 中` / `⚪ 低`
- **分類**：**只能用下面第三節那張表的九選一**，不可自創
- **出事會怎樣**：⚠️ **這欄最容易寫錯**。要寫**業務後果**不是技術現象：
  - ❌「不必登入就能取走明文帳密」← 技術現象
  - ✅「客戶會失去對自己機房主機的控制權——取走的是客戶自己的伺服器帳密，不只是我們系統的資料」
  - 特別要點出**誰會是那個拿到的人**（離職員工、外包、網路上任何人、同公司別部門的同事）
- **怎麼修**：一句話講修法方向，細節留到第 4 段
- **狀態**：`⬜ **未修**`（有工單就附卡號）/ `✅ 已修`（要寫怎麼修好的）/ `⚠️ 部分修`（要寫改了什麼、還剩什麼）
  - **狀態一律以總表 `docs/features/security-scan-consolidated/README.md` §3 為準**。那裡標了兩次複查結果（2026-09-16、2026-09-20），有 ✅ 已修 / ⚠️ 部分修 的就照抄
  - 沒被複查過的一律寫 `⬜ **未修**`，**不要自己判斷**

若有「範圍外順手撈到」的發現，另起一張小表，並註明它們不屬於這塊。

### 第 4 段：逐條展開

每條一個 `##` 或 `###` 段落。**只有最嚴重／高風險的需要完整展開**，中低風險的一小段講完即可。

完整展開包含：
- **問題是什麼**——白話，可以用比喻
- **影響**——能用表格列「打進去能拿到什麼」就用表格
- **建議怎麼修**——分步驟的用表格列出「步驟／做什麼／為什麼不能省」

**要決策者拍板的事項用 `::: {.callout .decided}` 框出來**，並把選項的優缺點做成表。

### 第 5 段：這塊的結論

一個 `::: {.callout}`（依嚴重度選 crit/warn/ok），內容：
- **一句話**：這塊的整體狀況
- **建議**：優先順序上的判斷，以及可以跟哪些一起修

後面接一張統計表：檢視輪數、通過的發現數、最嚴重幾條、已修幾條、已開工單幾張。

最後固定加：

```markdown
---

| 你想知道 | 看哪裡 |
|---|---|
| 我們用什麼方法查、結果有多可信 | [檢視方法與工具](GUIDE-01-method-and-tools.html) |
| 其他模組的檢視結果 | [回總報告首頁](index.html) |
```

---

## 三、分類只能用這九種（跨模組統一，不可自創）

| 分類 | 什麼情況用 |
|---|---|
| **身分驗證缺失** | 根本不檢查對方是誰 |
| **只驗登入、不檢查歸屬** | 知道你是誰，但不問「這筆資料是你的嗎」 |
| **客戶資料沒隔開** | A 客戶看得到 B 客戶的東西 |
| **密碼外流** | 憑證已經在外面了（寫死、進版控、公開網站） |
| **敏感內容寫進日誌** | 密碼原文落在紀錄檔 |
| **回應夾帶不該送的欄位** | 多送了內部欄位出去 |
| **外部送什麼就收什麼** | 不驗輸入 |
| **防竄改機制被削弱** | 專用於 jedi-integrity 那塊 |
| **資源耗盡** | 一個人就能讓系統對所有人停擺 |
| **要先做產品決策** | 不是技術問題，是規則沒定 |

（實際十項，分類名照抄，不要改字。）

---

## 四、白話標準 ← **最常出錯的地方**

「白話」**不是**把句子講得口語，是**讀者完全不需要技術背景就能懂**。

| 不可以寫 | 要改成 |
|---|---|
| API / 端點 / route | 功能、入口、管道 |
| token / credential | 通行證、帳號密碼、金鑰 |
| RLS / tenant isolation | 客戶資料隔離 |
| middleware / decorator | （改講它做的事，例如「把關的那道檢查」） |
| repository / service 層 | （不要提分層，改講「負責取資料的那段程式」） |
| CVE / CVSS | （不要用，改講嚴重程度） |
| 研究員 / 檢查員 / 候選 / 驗證章 | 這些是方法章的術語，模組頁**不要再提**，直接講結果 |
| TLS 憑證驗證被停用 | 連線時沒有確認對方是不是真的那個網站 |

**檔名與行號可以留**（這是對內版，而且稽核要追得到），但不要讓它們出現在「出事會怎樣」那欄。

**禁止的說法**：
- 「已確認安全」「沒有漏洞」← 我們的方法不能宣稱這個，只能說「這一輪在這個範圍內沒有找到問題」
- 「全面檢視」「完整涵蓋」← 同上
- 任何把「工具沒找到」講成「這裡乾淨」的說法

---

## 五、素材從哪裡來

| 要什麼 | 去哪裡找 |
|---|---|
| 這塊做什麼、主要發現摘要 | `docs/features/security-scan-consolidated/README.md` §0.5 的「已掃完」表 |
| 每一輪查什麼、票數、結果 | 同檔 §1「逐輪掃描進度」，找對應 FR 的那幾列 |
| 每條問題的完整描述、風險、修法 | 同檔 §3.1（資安類）與 §3.2（非資安但真 bug），用 FR 編號搜 |
| 問題的目前狀態（已修／部分修） | 同上，§3 開頭有兩次複查結果，條目上直接標了 |
| 該模組的檢視期間、輪次細節 | `docs/features/<該 FR 資料夾>/README.md` 與 `SUMMARY.md`（若有） |

**§3.2 的非資安項目也要收進來**——它們不是資安問題但確實是 bug，分類用「要先做產品決策」或在表下另起一小節說明。

---

## 六、交件前自檢

- [ ] 五段齊全、順序正確
- [ ] 第 2 段有檢視期間、檔數、輪數、每輪票數、原始報告檔名
- [ ] 有任何一輪覆核沒跑完整 → 已加 callout 說明
- [ ] 問題表排序正確（風險優先、同類相鄰）
- [ ] 「出事會怎樣」欄講的是業務後果，不是技術現象
- [ ] 分類全部來自第三節那十種
- [ ] 狀態欄與總表 §3 一致
- [ ] 通篇 grep 一次第四節的禁用詞，零命中
- [ ] 沒有出現「已確認安全」「沒有漏洞」「全面檢視」
- [ ] 頁尾導覽表已加

---

## 七、紀律

- **只寫 `docs/security-report/M<NN>-<slug>.md` 一個檔**，不要碰別的
- **不要自己跑 build**（`render_index.py`），統籌者統一做
- 不要改需求中心任何檔案
- 數字一律從上面第五節的來源抄，**不要自己算、不要憑印象**
- 查不到的寫「查不到」並在回報中列出，不要猜