FR-058 檢測工具擴充 — 全案收尾 SUMMARY

---

FR-058「檢測工具擴充」是 FR-056 檢測工具整合平台（v1.11.0 上線）的後續 arc，在既有平台上新增四款檢測工具（OWASP ZAP、CINC Auditor、Nmap、GCB）並補強平台層能力（憑證 / 目標主機宣告欄位、互斥憑證組別、取消執行、hosts / targets 分離）。本次為全案收尾，由協調者派工多個 subagent 平行處理文件與死碼清理。

收尾範圍為範圍 B：完整收尾但不 push、不進版。具體邊界：

• 做：文件補齊（使用手冊 / 三頁 SPEC / DB schema 參考 / discussion.html）、前端死碼清理、階段性 commit
• 不做：push（BE / FE 皆保留本地）、進版與 release note、STG / POC 同步、對非 DEV 環境套 migration

所有產出已 commit 在 feature/FR-058，push 與進版皆等決策者明示。本文 §1〜§9 為2026-07-31 收尾時點的快照；其後 SonarQube 重新納入為 FR-058.5（§10）、再追加 FR-058.6 主動掃描（§11）與 FR-058.7 上傳檔案掃描（§12），2026-08-01 全案驗收通過結案。主體各節維持四工具口徑不回溯改寫；範圍界定補註（防下一棒誤判）見 §13、發版時的上版清單見 §14。

2.1 四款檢測工具

四款工具皆登錄於平台目錄表 config.detection_tools：

CINC Auditor 的目錄 key 仍為 inspec（歷史沿革，migration fr058-10 改的是顯示名稱，未改 key）。四款中只有 CINC Auditor 支援雙傳輸：Linux 走 SSH、Windows 走 WinRM。GCB 在執行引擎上復用 CINC，差別在載入的 profile content。

2.2 平台層新增能力

• requires_credentials / requires_target_host 兩支宣告欄位 — 取代前端原本硬編 connection_type === 'SSH' 的耦合判斷。工具是否需要憑證、是否需要目標主機，改由後端目錄宣告，前端只讀旗標。原本前端靠 connection_type 反推行為，工具一多就會誤判（例如 API 型的 ZAP 其實也需要憑證），改成目錄宣告後，新增工具不必再動前端條件式。
• credential_group_schema（JSONB） — 宣告互斥憑證組別。前端只送組別 key，後端自行從 DB 組裝探測參數，憑證明文不經過前端。
• 取消執行（cancel） — 執行中的檢測任務可主動中止。
• hosts / targets 分離 — 連線目標（hosts）與掃描標的（targets）拆為兩個概念，不再混用同一組欄位。

四條主要決策，完整推理與被排除選項見 design.md 與 discussion.html。

D4 — ZAP 證據格式由 PDF 改為 HTML

改用 core.htmlreport() + core.jsonreport() 取出報告。原因是 reports.generate 只會把檔案寫到 ZAP 主機本機磁碟、呼叫端取不回來（ZAP issue #7821）。

D7 — GCB 復用 CINC 引擎 + content 外部載入

GCB 不另起檢測引擎，直接復用 CINC Auditor。GCB profile 放在 BE repo 的 content/detection-profiles/，刻意不放 agent repo —— agent Dockerfile 末尾的 COPY . . 會把 content 靜默烘進 image，造成 content 更新必須重建 image 的隱性耦合。

D9 — Nmap 由 CLI 型改為 SSH 型

兩個理由：一是容器化與 CLI 型定位本身矛盾；二是 NPSL v0.95 §3 的衍生作品條款涵蓋「專門執行本軟體並解析其結果」的軟體，GPL 式的 subprocess 防線在 NPSL 下不成立。出口是同條款尾段並未主張控制「執行使用者早已安裝的 nmap」——因此改為 SSH 型，由 agent 透過 SSH 呼叫目標主機上既有的 nmap。

D12 — SPA 限制

ZAP 的「登入後主動掃描」對單頁式應用（SPA）會誤判 logged_in_indicator，導致無限重試登入，觸發 ZAP 2.17.0 的 Insights 門檻後 daemon 自我關閉，進而波及同租戶其他掃描。使用手冊已明確標註請勿對 SPA 使用該模式——限制範圍是該模式，不是全面禁用 ZAP。

收尾工作包由多個 subagent 平行處理，落成 5 個 commit（BE 4 + FE 1）。

① 23dedd78 — 使用手冊

新增 docs/user-manual/detection-tools-guide.md（432 行，客戶面操作指南），並更新 docs/user-manual/README.md 登記。

獨立成檔的理由：既有手冊偏「稽核生命週期 / 教育訓練」敘事，本篇的對象是「設定期 + 非系統使用者的 IT 管理員」，讀者輪廓與閱讀時機都不同，硬塞進既有章節會破壞原手冊的敘事線。

結構：

• §1 位置與角色分工／Agent 概念
• §2 四款工具對照
• §3 共通四步驟
• §4 各工具細節（4.1 ZAP／4.2 CINC／4.3 Nmap／4.4 GCB）
• §5 排查
• 附錄：名詞對照

② e253a403 — database-schema.md 補齊

docs/claude/database-schema.md +270 行，新增「Domain: Detection Tools（FR-056 ~ FR-058）」章節。

六張表：

另補：8 個 JSONB 欄位結構說明（附 DEV 實際樣本）、Cross-Module FK Reference +8 列（明確區分真 FK 與 soft-ref）、RLS 對照表，以及一個只有 \d 查得到、schema dump 看不出來的 partial index：

uq_jedt_job_active UNIQUE(job_execution_id) WHERE is_delete = false

已知缺口一併記錄：detection_tools 尚無 i18n（沒有對應的 *_trans 表）。

③ 562f4b79 — discussion.html 更新

討論稿由 1060 行擴為 1351 行（+334 / −43），依實作與實測結果回填：

• §4.2 — D12 SPA 主治
• §5.3 — CINC 架構 + 雙傳輸
• §6.4 — GCB content 介面 + Demo 2 項限制／CM-992
• §7 — 改寫（Nmap；§7.1 為 D9 理由）
• §8 — D12 決策卡
• §9 — 風險表 +2 列
• §11 — 全新（平台能力 11.1–11.5）

NPSL 授權段由原本單一「主張豁免」的 callout，改寫為兩張 crit callout：先陳述壞消息（§3 衍生作品條款確實涵蓋本案情境），再說明出口。這個改寫是為了避免讀者只看到結論、誤以為授權風險不存在。三張 mermaid 圖首行的 %%{init:...}%% 完好保留。

④ ece8c02e — SPEC 三頁更新

docs/specs/current/ 三頁 SPEC，含 html 產物共 6 檔異動，+1272 / −275。

system-admin/tool-plugin-manage.md

• §1 由「兩款已上線」更正為目錄八筆（六筆 available、兩筆 coming_soon）
• UC-TPM-01 憑證合併；UC-TPM-02 改寫為「前置條件 Dialog、兩軸聯集」
• §4 / §5 / §6 / §9 / §12 的狀態閘門改以 requires_target_host 為鍵
• 補憑證分組面板、Dialog 動態寬度、逐區塊文案、卡片等高
• 補 response schema + credential_group_schema 結構表 + 取自 DEV 實庫的八列 seed 表
• 新增／改寫九條陷阱

project-management/project-task-edit.md

• 新增 §5 子節：四款工具掃描參數（取自實庫 detection_tool_param_schemas）、任務層 secret 加密鏈五階段、必填驗證
• §6.2 補 secret_keys_set
• §9.3 補 envelope 儲存
• 三條新陷阱
• 既有 JSON 範例中的內網 IP 換成 <target host> 佔位

audit-execution/my-tasks.md

• 功能 #14（取消執行）
• §6.1 三個檢測端點
• §11.1 新增「取消」子節（共用 _cancel_running_execution、兩種 409、「成功才標記 cancelled」）與「hosts / targets 分離」子節

三頁皆依 writing-feature-specs SOP 補檔頭變更紀錄。驗證：render_html.py "docs/specs/current" 全綠、敏感資訊 grep = 0、「GRC 系統」= 0。

⑤ 5aea161（FE）— WorkflowSetupEditor 死碼移除

src/views/workflow/WorkflowSetupEditor.vue 移除死碼 toolsMenu（Nessus / Nmap / OWASP ZAP / Wireshark 硬編清單）與兩個 Dropdown，改為說明註解。

判定依據（DEV 實查，三條獨立佐證）：

1. 該硬編清單與 config.detection_tools 完全脫鉤，工具目錄改動不會反映到這裡
2. 唯一渲染條件 actionType === 'TOOL_EXECUTION' 已不可能成立——public.system_menus 中 TASK_TYPE 的 exec_tool 列 enable=0，而 GET /system-menu/TASK_TYPE 在 route 層即濾掉 enable != 1
3. DEV 全部 workflow_templates / hi_workflow_templates 的 BPMN XML 查無 TOOL_EXECUTION

檢測工具的真實入口是專案規劃頁：ProjectPlanningView → menuStore.detectionToolMenu ← GET /detection-tools，存 job_type='detection_tool'。

收尾期間另有三個功能面 commit 由協調者另派、同期落地，不屬收尾工作包但屬同一 arc。

f2f61e70 屬 FR-058.3 的直接延續，與 CM-992 不衝突：CM-992 的範圍是「content 產製（GPO 解析器）+ 後台管理機制」，本筆是「接入一份已產好的 content」，走的是既有機制，兩者不重疊。

本節為**截至撰寫時（2026-07-31）**的狀態快照。收尾期間有平行工作線同時在動環境，此類跨 session 事實請以時點理解，不要當恆真陳述。

6.1 Agent 版本軸

DEV / STG / POC 三環境 agent 皆為 0.2.18，STG / POC 的上版（agent 更新 + content 掛載 + Demo profile 投放）稍早已完成。

因此 FR-056 時期列管的風險「工具顯示 available 但 agent 無對應 connector」，在 FR-058 已解除，不再列為未決風險。

另有一條平行工作線在修 WinRM UTF-8 錯誤，該修正完成後 agent 會 bump 到 0.2.19。本文記載為撰寫時的 0.2.18。

Agent 版本軸與 DB migration 數量軸是兩條獨立的軸，不要互相推論：agent 三環境齊平，不代表 migration 也齊平。

6.2 Migration 數量軸

DEV 領先三支是刻意的開發期狀態，不是違規。 三支分別為 fr058-14（TWGCB profile 選項）、fr058-15（工具描述 v2）、fr058-16（下拉選項清理），皆在決策者審閱中尚未同步。依環境異動鐵律，STG / POC 同步屬上版動作，需決策者明示放行。

需要釐清的分界：收尾派工單所寫的「任何 migration 只套 DEV」是給收尾 session 的行為指令（收尾期間不要自己往 STG / POC 套），不是對歷史現況的描述。fr058-1 ~ fr058-13 是在環境異動鐵律確立之前套進三環境的，該事實已記錄於 CLAUDE.md 與 sql-migration skill，不列為待補救事項。

6.3 完整 migration 清單（16 支）

scripts/sql/ 下 FR-058 相關 migration：

第 4 項是本次收尾唯一刻意留下的文件債：手冊寫的是當下能跑的形式，不是未來的形式。CM-992 開工時要記得回頭改這一節，否則手冊會教出一個不存在的操作路徑。

8.1 Notion 卡號碰撞

收尾派工單記「互斥憑證組別 = CM-986」，中段 handoff 卻記 CM-985。實查 Notion 確認 CM-986 才是正確的；CM-985 是「FR-058 後續優化：InSpec 報告呈現」，比 CM-986 晚 3.5 小時建立。

CM-986 卡片內文已記錄此碰撞，並裁定不回頭修改既有 commit message（那些 message 寫的是 cm-985）——改寫 git 歷史的成本高於留一條註記。

教訓：跨 session 傳遞的卡號要以 Notion 實查為準，不要以任何一份 handoff 的轉述為準。轉述會漂。

8.2 git index 競態（發生兩次，皆自行復原）

多個平行 subagent 共用同一個 git index，各自的第一次 commit 都掃入了對方已 staged 的檔案。兩次皆以 git reset --soft HEAD~1 + git restore --staged 復原後，重新只 commit 自己的檔案。

教訓：多 agent 平行作業時，顯式 git add <檔名> 不足以隔離——因為別的 agent 可能已經先 stage 了東西，git commit 仍會把整個 index 掃進去。正確做法是兩層：

1. commit 前先看 git status --short，確認有沒有他人預先 staged 的檔案
2. 改用 git commit --only <檔名> -m "..."，只 commit 指定檔案，繞過 index 現況

這條已回寫到後續派工單的鐵則段。

8.3 多 session 併行的狀態漂移

收尾 session 開工時查到的環境狀態（agent 版本、migration 數），在其工作期間被另一條平行工作線改變了。收尾方選擇停下回報而非自行判斷，是正確處理。

教訓：此類跨 session 事實應以「撰寫時點」標註（本文 §6 即照此處理），而不是寫成恆真陳述。文件裡一句沒有時間戳的「三環境皆為 X」，在多線併行的 arc 裡幾小時就會過期，且過期後看不出來已過期。

Notion 卡片

本節記載收尾動作完成之後才發生的範圍變動，不在本 SUMMARY 主體（§1〜§9）的快照範圍內。主體各節維持「四款工具、D1–D12」的收尾時點口徑，不回頭改寫。

10.1 變動內容

SonarQube 重新納入，成為第五個子需求 FR-058.5。規劃期決策者曾裁示「本期不做」而將其移出本案，D10 因此成為空編號；2026-07-31 決策者裁示重新納入，決策以 D13–D16 定案。

D10 編號維持 tombstone，不重用、不重排——避免與先前已溝通過的編號錯位。

10.2 技術定位

SonarQube 是平台第一個「拉取快照（pull-snapshot）」型工具：server 端沒有任何可觸發掃描的 Web API，掃描由客戶端 CI / sonar-scanner 執行，connector 只拉取既有分析結果組報告。歸類上仍屬「① 連遠端服務 API」形態，但語意不同——連的是 API 卻不下掃描指令，只讀取既有結果。平台面零改動，工作集中在 connector 與 seed。

10.3 落點與對本文的影響

design.md 已更新：新增 §4.6 詳細設計、拆分表加 T-5.1〜T-5.3 三子任務、§2 決策表改為 D1–D16、§6 加對應驗收項。該份 design.md 異動落於 commit 18a01d1a（2026-07-31 19:51），本文不重複其內容。

對本 SUMMARY 而言：§2「FR-058 全案做了什麼」的四款工具表、§3「關鍵設計決策摘要」的 D4 / D7 / D9 / D12，都是收尾時點的正確記載，不因 FR-058.5 而失效。要看完整範圍與 D1–D34 全表，請直接開 design.md。

FR-058.5 落地 commit：BE seed 7b9d831e（T-5.1，param_schema v1）、agent connector 2d92ac4（T-5.2，bump 0.2.21 2aa95ec）、FE 微調 fef7e94（T-5.3 程式碼部分）。UI 端到端驗收依裁示併入 FR-058.6 的 T-6.3 一輪做完（見 §11）。

11.1 需求與定位

決策者看到 FR-058.5 pull 模式實際畫面後指出「流程不對」——他要的是平台真的發動一次掃描（使用者提供 Git repo URL → agent clone 源碼、跑 sonar-scanner → 推上客戶 SonarQube server → 輪詢 → 拉結果組報告），而非只讀客戶 CI 已推上去的既有結果。這是前提變了的新需求，不是 FR-058.5 做錯：D13 當時排除「agent 自跑 scanner」的理由是 agent 沒有源碼，本案補上了那個輸入。決策以 D17–D24 定案，兩模式並存靠 scan_mode 參數分流（對已有成熟 CI 的客戶 pull 仍是正確答案；C# / VB.NET 因 MSBuild 架構限制永遠只能走 pull）。

11.2 落地內容

11.3 端到端驗收（2026-08-01 上午通過）

detection_executions 內 sonarqube 從 0 筆變 2 筆皆 succeeded（pull：project_key=guidant-ai-backend；scan：repo soybean-ui），且 171 server 上實際長出 Guidant-AI-soybean-ui 專案（D21 前綴生效）。這一輪同時補完了 FR-058.5 尚欠的 UI 驗收。

11.4 品質門檻條件修正（驗收期間發現）

報告顯示「此專案未設定品質門檻條件」但門檻結果卻是 OK。真因不是解析少剝一層（協調者原推測被實測推翻）：SonarQube 內建 gate 條件幾乎全是 new_* 指標，需要比較基準期（period）——專案首次分析沒有前一版可比，API 回 conditions: [] 且 status 仍給 OK。修正為「條件為空時整塊不輸出、不再謊稱客戶未設定；品質門檻結果一格一律保留」——agent 139156f，bump 0.2.23 e0d11c6。教訓：收到「沒東西就藏起來」的顯示層要求，先驗資料層是不是我們沒讀到。

12.1 需求與決策

FR-058.6 驗收通過後，決策者提出客戶要能直接上傳源碼壓縮包做檢測（不是每個客戶都有可公開存取的 Git repo）。定位為 scan 模式的取源擴充，不是新模式——scan_mode 多一個 upload 選項，取源之後整條掃描管線全複用。決策 D25–D34 定案（D32 併入 D29 ④；D33 / D34 為驗收期間追加）。關鍵定案：

• 上傳時機在任務抽屜發起執行時，不是任務設定表單（D26）——source_file 是執行時輸入不進 param_schema
• 取源通道：agent 主動 mTLS 拉取（BE 端點 GET /api/1.0/agents/files/<uid> 串流轉發不落地），非 BE 推檔（D25）
• 檔案生命週期：server 端壓縮包保留供重掃沿用＋歷史不刪（D29，推翻討論中「終態即刪」的中間版本）；agent 端掃完即刪
• 格式與限額：.zip / .tar / .tar.gz / .tgz；上傳 100MB／解壓後 500MB／50,000 檔，環境變數可覆寫（D27）；磁碟預留檢查（D28）＋標準庫安全解壓與解壓炸彈計量（D30）

12.2 落地內容

12.3 驗收紀錄（2026-08-01 決策者驗收通過）

T-7.4 端到端驗收通過（含 T-7.5 / T-7.6）。四個未實測項的裁示：

1. 磁碟不足模擬——接受單元測試涵蓋，不另做環境級模擬
2. 解壓炸彈超額壓縮包——接受單元測試涵蓋
3. 環境變數調限額——不另實測
4. nginx client_max_body_size——列上版必驗項（見 §14），DEV 直連 BE 驗不到

至此 FR-058 全案（.0〜.7 ＋ 橫向前置項）結案。

「任務層敏感參數已修」的範圍是 job_execution_detection_tools.tool_params 內 secret: true 欄位（FR-058.0，envelope 加密機制在 common/util/detection_secret_params.py）。

不含 _credentials——那是 FR-056 既有的租戶憑證派工快照（compliance.agent_tasks.params 內），at-rest 仍是明文，且仍在持續產生新資料（非歷史遺留）。已裁示發版時一併修：複用 common/util/detection_secret_params.py 現成的 envelope（不要新造輪子），改存加密、心跳組裝時才解；會動派工路徑，四款工具（ZAP / CINC / Nmap / GCB）都要回歸。

看到 _credentials 明文時不要誤判為迴歸——第三棒協調者就曾因此誤判過一次。

CM-957 家族共 52 張卡，全案驗收通過後由收尾 Notion 線批次標 Done（母卡 CM-957 一併更新結案註記）。