檢測工具管理（Detection Tool Management）

功能群：系統管理｜共用權限模型先讀 功能群總覽

事實基準：2026-08-01 從 FE src/views/plugin/ToolPluginManage.vue（846 行）+ BE app/detection_tools/ 全模組 + DEV config.detection_tools 實查掃出（FR-056 檢測工具整合平台 T-1.1~T-1.5 ＋ FR-057 OpenSCAP SSH 連接器 ＋ FR-058 檢測工具擴充四工具接入 ＋ FR-058.5/.6/.7 SonarQube 三模式接入）

變更紀錄

1. 功能描述

檢測工具管理是租戶層級的外部資安檢測工具設定介面：管理平台工具目錄中已啟用的檢測工具，供租戶填寫連線資訊（主機位址、帳密、SSH／WinRM 憑證等）、測試連線、並在 任務配置 頁把工具綁定到「檢測工具執行」型任務上。

現況工具目錄共八筆（DEV 實查 config.detection_tools，依 id 序）——七筆 available：OpenVAS（網路弱點掃描）、OpenSCAP（SCAP 組態合規稽核）、SonarQube（原始碼安全檢測 SAST，FR-058.5 起上架，三種執行模式見任務配置頁）、ZAP（網頁 DAST 動態掃描）、CINC Auditor（組態合規檢測引擎，SSH／WinRM 雙 transport）、Nmap（網路埠與服務探測）、政府組態基準（GCB）（依 TWGCB 檢測主機組態，與 CINC Auditor 共用引擎、差別在檢測內容，D7）；一筆 coming_soon 佔位：Nessus。SonarQube 的 available 目前僅 DEV（seed 依環境異動鐵律只套 DEV），上版後全環境生效。

平台維護的「工具目錄」（config.detection_tools）是 DB 驅動而非程式寫死：每筆工具定義代碼、顯示名稱、說明、連線類型（API/CLI/SSH）、設定欄位結構（config_field_schema，動態表單 JSON）、互斥憑證組別宣告（credential_group_schema，FR-058）、行為宣告欄位（requires_credentials / requires_target_host，FR-058）、部署前提說明（setup_guide）與平台層 status（available/coming_soon）。本頁的設定表單、任務配置頁的掃描參數表單，皆完全依 BE 回傳的 schema 動態渲染——FE 對工具型別零硬編，新增工具只需目錄補資料 + Agent 端補 connector，前端不用改代碼。

FR-058 一次接入四款工具，是對這個 schema-driven 架構的壓力測試，也逼出了三個原本埋在架構裡的耦合：① FE 硬判 connection_type === 'SSH' 來決定要不要問測試主機——CINC Auditor 同時支援 SSH 與 WinRM，connection_type 只能填一個值，行為判斷改由 requires_target_host 宣告；② 憑證整包覆蓋——CINC Auditor 有三個 secret 欄位（ssh_private_key/ssh_password/winrm_password），FE 只送有填值的欄位，BE 原本整包 encrypt 會洗掉沒動的憑證，改 merge 語意；③ 派工靠 tool id 硬編映射——agent factory 原以 _TOOL_ID_TO_CODE 固定表認 connector（只涵蓋 id 1–4），新工具會被誤判為「尚無 connector 實作」，改由派工 payload 夾帶 detection_tool_code（D11）。

主要使用者：持有 plugin.update capability 的角色（角色權限矩陣「檢測工具管理」列有 update 勾，v1.12.0 起；系統層 super_admin break-glass 放行，見 §3）。

角色速覽：

1.1 功能總覽（本頁全部功能）

UC（§2）展開本頁所有具實質後端寫入/呼叫邏輯的功能：新增/編輯設定（4，UC-TPM-01）、測試連線（5，UC-TPM-02）、停用（6，UC-TPM-03）、重置金鑰（7，UC-TPM-04）。純顯示/前端過濾類（1 目錄清單、2 搜尋、3 灰化、8 部署前提說明）於 §5 說明。

2. Use Case

角色速覽：見 §1。

流程圖視覺慣例：菱形 = 判斷、橘底 = 例外/擋下、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。

UC-TPM-01 新增 / 編輯工具連線設定

流程：開 Dialog（依 config_field_schema 動態渲染；有 credential_group_schema 者切成左右並排面板）→ 必填欄位未填且已 touched → 顯示「{欄位名} 為必填」→ 送出時先跳過 condition 不成立的隱藏欄位（不送未選分支的殘留值），secret 欄位分流進 credentials（有值才帶）、其餘進 field_values → POST（新增）或 PUT（編輯）→ 成功關閉 Dialog 並重整清單。

憑證部分更新採 merge 語意（FR-058，BE 24dba59f）：FE 只送「有填值」的 secret 欄位（UI 承諾「留空＝沿用原值」），BE update_tenant_config 帶 credentials 時先解密既有密文、以新 key 逐個蓋上去再重新加密，而非整包覆蓋。單一 secret 欄位的工具（OpenVAS / ZAP）merge 是等價操作、行為不變；多 secret 欄位工具（CINC Auditor 三個）若沿用舊的整包覆蓋，只改 SSH 私鑰會把 WinRM 密碼一併洗掉（實測踩過）。merge 語意下「清空單一 secret」不支援——整組清空走 UC-TPM-04 重置金鑰。出處：app/detection_tools/service/detection_tool_service.py::update_tenant_config:92-116。

UC-TPM-02 測試連線

流程：按「測試連線」→（前置條件 Dialog，開窗與否見下）→ BE 解密該租戶已存憑證 → 挑一台本租戶啟用中、capabilities 含 detection_scan 的 Agent → 透過既有 FR-039 mTLS 通道推送 POST /detection/probe（帶解密後憑證 + detection_tool_code + 憑證組別對應的 probe 參數，要主機者另帶 host）→ Agent 用與真實掃描相同的連線方式實連驗證（OpenVAS：python-gvm GMP over TLS；OpenSCAP：SSH 連線 + 認證 + oscap 指令存在性 + SCAP content 存在性四段檢查；ZAP：API 連線；CINC Auditor / GCB：依選定組別走 SSH 或 WinRM；Nmap：SSH 登入執行主機；SonarQube：兩段式——api/system/status 免認證驗連通後，帶 token 呼叫 api/authentication/validate 驗 token 有效性，不讀取任何專案資料、不觸發掃描，FR-058.5）→ 結果同步回傳 → 記錄 last_tested_at/last_test_result。

前置條件 Dialog 的兩軸（FR-058，彼此獨立可任意組合）——FE onTestConnectionCard 取兩者聯集決定要不要開窗，Dialog 標題隨實際要問的內容切換（testDialogHeader 三種文案）：

憑證組別為何不做自動偵測：「填了哪組就用哪組」在「客戶同時有 Linux 與 Windows 目標、兩組都填齊」時猜不出來，而猜錯產生的正是本案要消滅的那種誤導訊息（只填 WinRM 卻收到「本任務的連線方式為 SSH，但未填寫 SSH 稽核帳號」——訊息清楚但回答的是使用者沒問的問題）。BE _resolve_credential_group_params() 對「宣告了組別卻沒選 / 選了不存在的 key」一律明確回失敗、不派 probe、也不寫 last_test_result（沒真的測過就不該把結果蓋成 fail）。FE 只送組別 key，probe 參數的 key 與 value 由 BE 依 DB 宣告自行組出——參數會一路流到 agent connector 決定走哪條程式路徑，讓瀏覽器指定等於開一個注入面。

四種失敗原因分開呈現（皆 success=false，非 HTTP 錯誤）：①未設定憑證 ②本租戶無可用 detection_scan Agent ③憑證組別未選/不存在/宣告不完整（FR-058）④Agent 連得到但工具端連不通/帳密錯（訊息由 Agent 回傳原樣顯示）。多台測試（FR-057 T-2.3-fix）：FE 拆開並發，每台各發一次 POST test-connection（body 帶單台 host），BE 逐台呼叫 probe 並各自回傳，FE 逐列即時更新狀態（testing/ok/fail），不互等。

UC-TPM-03 停用工具設定

流程：按「停用」→ 先查詢 count_referencing_tasks（該工具目錄項被幾個 job_execution_detection_tools 綁定引用）→ 引用數 >0 時 confirm 訊息加註「有 {count} 個任務正使用此工具設定，仍要停用嗎？」，＝0 時純確認訊息 → 不論引用數多少，確認後一律直接停用（D6 軟提醒，非阻擋）→ PUT 更新 status。

UC-TPM-04 重置金鑰

流程：按「重置金鑰」→ confirm（「確定要重置 {name} 的憑證嗎？重置後需重新設定才能使用。」）→ 確認 → POST /detection-tools/configs/{uid}/reset → 成功後重整清單，該工具的機敏欄位回到未設定狀態（下次開 Dialog 不再顯示 •••• 遮罩）。

3. 權限矩陣

守門演進（v1.12.0 下放，BE fabf974e）：FR-056 上線時因本模組租戶層 capability 尚未 seed，寫入動作以 service 層帳號級 require_super_admin() 過渡守門（見舊版 §3 附註），導致只有系統層 super_admin 能存設定。v1.12.0 改為 route 層 @require_capability("plugin.update")——復用 tool-plugin-manage 頁對應的既有 plugin.* capability（三環境已存在且已配角色，無需新 seed / migration），符合 FR-048 授權守門雙軌規範的「主體域守門走 route decorator」形式；service 層的 require_super_admin() 已移除。停用因走同一 PUT 端點，一併納入守門。測試連線 / 查引用數仍完全無角色檢查，只靠 RBAC 選單擋入口——與寫入動作的守門粒度不一致，屬現況已知狀態（見 §12 坑 2）。

4. 狀態機與前置條件

本頁無輪次 / 階段狀態機，僅有工具目錄與租戶設定各自獨立的狀態：

5. UI 設計

版面骨架（Card grid + 設定 Dialog）：

📸 實機截圖待補：工具卡片 grid（八張卡、含等高與排序）、設定 Dialog（單欄版：secret 遮罩 + textarea 私鑰欄 + auth_method 條件顯示）、設定 Dialog（雙欄版：CINC Auditor 的 SSH／WinRM 並排面板）、測試連線前置條件 Dialog（憑證組別 SelectButton + 測試主機 + 逐台結果列）、部署前提說明 Dialog（逐段複製鈕）。

狀態呈現：每張工具卡片右上角狀態 Tag——coming_soon 顯示「敬請期待」（secondary）；有設定則依 config.status 顯示綠色「啟用」或紅色「停用」。設定 Dialog 標題固定為「啟用檢測工具」（t('lang.plugin_manage.active_plugin')，即使是編輯既有設定也沿用此標題，屬既有文案非新坑）。無 socket；設定儲存 / 重置後重打 fetchAll() 重新整理整頁資料；啟用 / 停用改樂觀更新 + 失敗回滾（先改本地 config.status，PUT 失敗才還原並顯示錯誤）。

卡片排列與等高（FR-058）：卡片依 cardRank 排序——啟用（0）→ 停用/未設定（1）→ coming_soon（2）壓底。容器 align-items-stretch 讓同一列卡片拉成該列最高者的高度，卡片內部 card → p-card-body → p-card-content 逐層 flex: 1 把多出來的高度吃進內容區，footer 因此貼底對齊。兩段缺一不成立：只有前者則外框等高但按鈕列仍跟著內容浮動、只有後者則卡片本身沒被拉高無空間可分配。內容區另設 min-height: 8rem 當最短卡地板（描述文案由後端填，將來若有工具只寫一句話不會縮成細片）。出處：ToolPluginManage.vue::cardRank:78-81、<style scoped> .custom-card 區塊。

卡片動作配置（FR-057 改版）：常用動作（設定 / 編輯、測試連線）留在卡面；次要 / 危險動作（部署前提說明、啟用 / 停用、重置金鑰）收進卡片右下角 overflow menu（pi-ellipsis-v 按鈕開 PrimeVue Menu popup），避免多按鈕擠壓換行跑版（ToolPluginManage.vue::getCardMenuItems:435-465）。

設定 Dialog 的憑證分區（FR-058）：宣告了 credential_group_schema 的工具，欄位依 field.group 對應宣告的 groups[].key 切成分區；每組做成獨立面板（完整外框 + 有底色的抬頭列 + 該組的 description 說明），排版用 CSS Grid repeat(auto-fit, minmax(20rem, 1fr))——欄數由可用寬度自算，兩組剛好兩欄、三組以上不會排成「2 + 1 落單」，窄螢幕自動降單欄。做成獨立面板而非只用一條分隔線，是因為「這兩組是分開的、只需填要掃的那一組」正是要傳達的核心訊息，一條細線在並排時讀起來仍像同一張連續表單。沒有 group 或 group 對不到任何宣告群組的欄位一律降級放最前面的無分區區塊（絕不靜默丟掉——使用者填不到欄位遠比排版不完美嚴重）。分區純屬排版：送出一律以扁平 config_field_schema 為準（buildPayload），分組不參與 payload 計算。出處：ToolPluginManage.vue::credentialGroups:182／ungroupedFields:186-189／groupedFieldSections:192-197、.credential-group-grid style。

部署前提說明 Dialog（FR-057 建立，FR-058 改版）：工具目錄項有 setup_guide（TEXT，markdown）時，overflow menu 出現「部署前提說明」項。FR-058 兩處改動：

• 逐段複製取代整份複製：splitSetupGuide() 用 marked.lexer() 把 markdown 拆成「說明段落」與「程式碼區塊」交替的片段，每個 code block 各自帶一顆複製鈕（複製後圖示短暫變勾勾，讓回饋落在按下的那顆按鈕上）。動機：同一份說明內含 Linux（SSH）與 Windows（WinRM）兩套互斥的準備腳本，使用者只需要其中一套；併成一大段複製等於逼他自己剪裁，貼進 shell 還是錯的。
• Dialog 加寬至 64rem（同雙欄設定 Dialog，加 960px 窄螢幕 fallback）：說明內含終端機指令與對照表，窄版會讓指令頻繁折行、表格被擠壓。

消毒鏈：說明段落走 marked.parser() → DOMPurify.sanitize() → v-html（信任來源仍過濾，防禦性一致）；程式碼區塊改由 Vue 文字插值輸出（自動跳脫），完全不經過 v-html，也不把內容拼進 HTML 字串。切段時把 tokens.links 帶進每段 prose，否則文件層級的參考式連結（[x]: url）在切段後解不出來。出處：ToolPluginManage.vue::splitSetupGuide:28-50、copyCodeBlock:57-70。

6. API 規格

Envelope：成功 {"code": 1, "data": …}、失敗 {"code": 0, "msg": "…"}（return_response）。

6.1 總清單（本頁呼叫的全部 endpoint）

任務執行相關端點（/detection-tools/jobs/{job_uid}/execute、.../cancel（FR-058 新增）、.../executions）屬 任務執行抽屜 功能，非本頁呼叫，列在該頁 spec。

6.2 工具目錄 / 租戶設定清單

[GET] /detection-tools

無 query。Response data[]（DetectionToolResponse）：

config_field_schema 各欄位屬性：

credential_group_schema 形狀（FR-058）：

probe_param_key / probe_param_value 不外流給 FE 使用：serializer 雖整個 credential_group_schema 原樣 dump，但 FE 契約上只准回傳選中的 key，probe 參數由 BE 依 DB 宣告自行組出。probe 參數會一路流到 agent connector 決定走哪條程式路徑（其他工具則是組出哪個檔案路徑），讓客戶端自由命名參數等於開一個注入面。

型態渲染對照（DetectionConfigField.vue）：text→InputText、password→Password（toggleMask）、number→InputNumber、select→Dropdown、textarea→Textarea（autoResize，SSH 私鑰欄用）、boolean→InputSwitch、select_or_text→PrimeVue editable Dropdown（可選常用選項、也可直接輸入清單外的自由字串，如 profile 欄）。

出處：api/detection_tools/serializers/detection_tool.py（DetectionToolResponse，FR-058 新增 requires_credentials / requires_target_host / credential_group_schema）、route DetectionToolsRoute、service detection_tool_service.py::list_tools（get_tools(enabled=True)）。

現況種子資料（2026-08-01 DEV 實查 config.detection_tools，八筆）：

CINC Auditor / GCB 的欄位全部 required=false：兩組互斥憑證只需填要掃的那一組，任一欄設必填都會擋住「只掃 Windows 的客戶」。缺欄位的錯誤落在派工/測試連線時由 connector 回報（訊息指名缺哪個欄位）。與 OpenSCAP 的「條件必填」（password/private_key 皆 required=true，靠 condition 決定套不套驗證）是兩種不同策略。

connection_type 對 CINC Auditor / GCB 只是形式值：兩者同時支援 SSH 與 WinRM，欄位填 SSH 純為滿足 NOT NULL 約束，實際 transport 由使用者在任務參數選（transport）或測試連線選憑證組別決定。相關 seed migration：scripts/sql/2026-07-30-fr058-{1,5,6,7,8}-*.sql、2026-07-31-fr058-{9,10,...,19}-*.sql、2026-08-01-fr058-{20,21}-*.sql（sonarqube 上架＝fr058-17、描述文案 v2＝fr058-15、GCB 8 支 TWGCB profile＝fr058-18；全數已套 DEV，STG / POC 依環境異動鐵律等上版放行）。

八筆工具描述為 2026-07-31 第二版（fr058-15）：決策者裁示描述以「主要功能可以幹嘛」為主——每則涵蓋「查出什麼／對應哪類控制項證據」，授權與商用性質、來源維護者、安裝部署前提三類內容全數移出（該資訊已在各工具 setup_guide 完整載明，卡片不重複）。coming_soon 者（Nessus）句尾保留「此工具尚在規劃中、目前無法使用，敬請期待。」狀態句。

[GET] /detection-tools/configs

無 query。Response data[]（TenantDetectionToolConfigResponse）：

出處：api/detection_tools/serializers/detection_tool.py:17-40（TenantDetectionToolConfigResponse.dump_entity 手動補 has_credentials）、service detection_tool_service.py:58-69::list_tenant_configs。FE 合併邏輯：ToolPluginManage.vue::tools computed:57-67（依 detection_tool_code === tool.code 配對）。

6.3 新增 / 更新設定

[POST] /detection-tools/configs

Request：

{
  "tool_uid": "<detection_tools uid>",
  "credentials": {"password": "..."},
  "field_values": {"base_url": "https://...", "username": "...", "port": 9390},
  "status": "enabled"
}

工具目錄項 status !== 'available' → DETECTION_TOOLS_400002（DETECTION_TOOL_NOT_AVAILABLE）。出處：api/detection_tools/serializers/detection_tool.py:43-47（TenantDetectionToolConfigCreateRequest）、route TenantDetectionToolConfigsRoute.post、service detection_tool_service.py:72-90::create_tenant_config（route 層另有 @require_capability("plugin.update") 守門，見 §3）。

[PUT] /detection-tools/configs/{uid}

Request（全部選填，partial-update 語意——None 欄位不更新）：

merge 而非整包覆蓋（FR-058，BE 24dba59f）：FE 只送有填值的 secret 欄位（UI 承諾「留空＝沿用原值」）。舊實作把送來的 credentials 整包 encrypt 覆蓋，多 secret 欄位的工具部分更新時會洗掉沒動的憑證——CINC Auditor 三個 secret（ssh_private_key/ssh_password/winrm_password），實測「只存 SSH 私鑰 → WinRM 密碼遺失」。單一 secret 工具（OpenVAS / ZAP）merge 是等價操作，行為不變。merge 下「清空單一 secret」不支援（FE 留空不會送 key）——這是刻意的，整組清空走 §6.4 reset。

出處：api/detection_tools/serializers/detection_tool.py（TenantDetectionToolConfigUpdateRequest）、service detection_tool_service.py::update_tenant_config:92-116（merge 邏輯於 :102-107）（route 層另有 @require_capability("plugin.update") 守門，見 §3）。

FE 送出邏輯（ToolPluginManage.vue::buildPayload:151-170）：遍歷扁平的 config_field_schema（憑證分區純屬排版、不參與 payload 計算），先依 isFieldVisible()（condition 判斷）跳過不可見欄位（FR-057，避免未選分支殘留值送出），值為 null/undefined/空字串一律跳過（不塞進 payload）；secret 欄位分流進 credentials，其餘進 field_values；credentials 物件若無任何 key 則整個欄位設為 undefined（axios 序列化時省略），確保「全部留空＝不動既有密文」。

6.4 重置 / 測試連線 / 引用計數

[POST] /detection-tools/configs/{uid}/reset

無 body。Response data：{"success": true}。清空 credentials_encrypted 為 NULL（專用 clear_credentials 方法，區別於 update() 的 None=skip 語意——重置要的正是清空，不能被 skip 邏輯擋住）。出處：service detection_tool_service.py:106-109::reset_tenant_config_key（route 層另有 @require_capability("plugin.update") 守門，見 §3）。

[POST] /detection-tools/configs/{uid}/test-connection

Request（全部選填，FR-057 新增）：

Response data：{"success": bool, "message": string}。

四種失敗訊息（皆 success=false，非 HTTP 錯誤）：

憑證組別失敗不寫 last_test_result：與「未設定憑證」「無可用 Agent」兩種前置失敗一致——沒真的測過，不該把 last_test_result 蓋成 fail 誤導後續判讀。

零回歸保證：無宣告組別的工具（八筆中的六筆）group_params 為空 → probe 呼叫完全不帶 params，形式與加入本機制之前逐字相同（硬性要求，不只是效果相同）。

出處：route TenantDetectionToolConfigTestConnectionRoute（api/detection_tools/routes/detection_tool_route.py:122-142，收 host + credential_group）、service detection_tool_service.py::test_connection:161-（host 逐台 probe 彙總 FR-057；credential_group 解析 FR-058）、_resolve_credential_group_params:124-159；憑證合併邏輯（field_values + 解密後的 credentials）於 :212；派工帶 detection_tool_code（D11，CM-959）於 :219；實際 mTLS 直推見 infra/detection_tools/connector/agent_probe_client.py（PROBE_PATH = "/detection/probe"）。

[GET] /detection-tools/configs/{uid}/referencing-tasks-count

無 query。Response data：{"count": int}——D6 軟提醒，不擋停用/重置動作，僅供 FE 組確認訊息文案。出處：service detection_tool_service.py:169-180::count_referencing_tasks（解出 tenant_config → detection_tool_id 後查 job_execution_detection_tools 引用數）。

7. 前端檔案地圖（compliance-manager-fe/）

8. 後端檔案地圖（本頁核心鏈路）

DDD 提醒：route 不碰 DB、app service 全數 @transaction、domain service 不依賴 infra、repo 遵循既有分層。寫入端點（新增/編輯/重置）的守門在 route 層 @require_capability("plugin.update")（v1.12.0 起，主體域守門走 route decorator 屬 FR-048 允許形式，decorator 內委派 DI 注入的 guard service，route 本身不碰 session）；測試連線/查引用數則完全無角色守門——改動時務必分開看待。

9. DB

9.1 資料表總清單（本頁讀寫的全部表）

9.3 核心表欄位（取自 DEV DB dump）

config.detection_tools — 平台工具目錄

config.tenant_detection_tool_configs — 租戶工具連線設定

config.detection_tool_param_schemas — 工具任務參數 schema（版本化）

與 config_field_schema 的差異：detection_tools.config_field_schema 是連線設定欄位（本頁用，如帳密/主機），detection_tool_param_schemas.param_schema 是任務掃描參數欄位（任務配置頁用，如 hosts/timeout_sec）——兩者是不同層次的 schema，命名相近容易混淆。

10. 頁面邏輯與資料對應

載入時序：onMounted 平行觸發 listTools() + listConfigs()，FE 端依 detection_tool_code === tool.code 合併成 tools computed（工具卡片資料來源）。

關鍵欄位對應（畫面 ↔︎ API）：

儲存流程：onSaveConfig 先做 client 端必填檢查（略過已有憑證的 secret 欄位）→ buildPayload() 分流 credentials/field_values →建立走 POST、既有走 PUT → 成功後關閉 Dialog + fetchAll() 整頁重新整理（非局部更新）。

錯誤對應：BE error envelope → toast 顯示；本頁常見碼：DETECTION_TOOLS_400002（工具非 available 不可新增設定）、DETECTION_TOOLS_404002（設定不存在）。測試連線刻意不用例外，而是回 {success:false, message}，避免整頁被連線失敗中斷。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. 寫入守門復用 plugin.update，非獨立的 detection-tools-manage.* capability：v1.12.0 守門下放（見 §3）選擇復用 tool-plugin-manage 頁既有的 plugin.* capability（三環境已 seed 已配角色，零 migration），而非另 seed 一組 detection-tools 專屬能力點——語意上「檢測工具管理頁的 update 權」與「工具設定寫入權」目前是同一顆勾，日後若要拆分頁面可見性與設定寫入權，需另開 capability。
2. 測試連線 / 查引用數完全無角色守門：僅 @jwt_required()，任何登入者理論上都能對已知 config uid 呼叫測試連線——與寫入動作（含停用，走 PUT 已納 plugin.update 守門）形成不一致的守門粒度，改動時勿混為一談。
3. 停用後任務配置頁下拉未過濾 status：config.tenant_detection_tool_configs.status='disabled' 後，任務配置頁的工具下拉來源是 GET /detection-tools（工具目錄，非租戶設定），本身不檢查租戶設定狀態——理論上使用者仍可能選到一個已停用設定的工具，實際派工時會因缺憑證（_resolve_credentials 找不到 enabled 設定）失敗。此為現況行為，未做前端過濾。
4. config_field_schema（連線設定）與 param_schema（任務參數）是兩層不同 schema：命名相近但用途、消費頁面都不同（見 §9.3 附註），維護時勿混淆——改一邊不會影響另一邊。
5. 憑證合併邏輯：測試連線時 field_values（如 base_url）與解密後的 credentials（如 password）需合併才是完整連線資訊（test_connection:212），單看其中一邊資訊不全——早期版本曾漏合併（b26f83f1 修正）。
6. credentials 全空時整個欄位省略，非傳空物件：FE buildPayload() 若無任何 secret 欄位有值，credentials 設為 undefined（非 {}）——若改成送空物件 {}，BE creds = payload.get("credentials") 會判定為 truthy（非 None）而觸發加密覆寫，把既有密文洗成加密後的空字串，是需要留意的坑（現況實作正確，記錄供未來重構參考）。
7. coming_soon 工具無法被選為連線設定或任務綁定：create_tenant_config 明確擋 status != 'available'（DETECTION_TOOLS_400002），FE 也把按鈕全部隱藏——nessus 目前只是目錄佔位，尚無 Agent connector 實作（sonarqube 已於 FR-058.5 上架轉 available，僅 DEV）。
8. connection_type 不足以描述連線行為，勿再用它做判斷（FR-058）：CINC Auditor / GCB 同時支援 SSH 與 WinRM 兩種 transport，但 connection_type 只能填一個值（現填 SSH 純為滿足 NOT NULL）。FE 原本硬判 connection_type === 'SSH' 決定要不要問測試主機，第二批 seed CINC Auditor 時實地撞到——需不需要問主機取決於「憑證含不含 host」，與走哪種協定無關。已改由 requires_target_host 宣告；credential_group_schema 則承載「有幾組互斥憑證」。新增判斷時一律加宣告欄位，不要回頭讀 connection_type。另有 CLI 型態值（本機執行、不經 SSH）已定義於 comment 但尚未有任何工具實際使用，屬未來擴充預留（Nmap 原規劃走 CLI，D9 改案後改 SSH 型）。
9. SSH 型工具的憑證＝租戶層一組共用稽核帳號：所有目標主機須用同名帳號 + 同一把私鑰/密碼登入（Tenable 業界慣例），非每台各自帳密——host inventory（每台各自憑證）是明列的未來範圍，本版不支援。CINC Auditor / GCB 的 WinRM 組同理（一組 Windows 管理員帳密掃全部 Windows 目標）。
10. 憑證組別「不猜」是刻意設計（FR-058）：宣告了 credential_group_schema 的工具，測試連線一律要求使用者明確選一組，不做自動偵測、不預選第一組。「填了哪組就用哪組」在兩組都填齊時（客戶同時有 Linux 與 Windows 目標）猜不出來，猜錯產生的正是本案要消滅的誤導訊息。日後若有人想「優化成自動判斷」，先看這條。
11. CINC Auditor / GCB 的 config_field_schema 逐字相同是刻意的：兩者同一顆引擎、同一組連線參數，seed 時刻意保持逐字一致（含 hint 文案），讓日後改一邊時 diff 能一眼看出另一邊是否漏改。改任一邊務必同步另一邊。
12. 憑證分區只是排版，payload 走扁平 schema：FE buildPayload() 遍歷的是扁平 config_field_schema、不看 group；分區與送出兩條路徑不會分歧。group 對不到任何宣告群組的欄位會降級顯示在無分區區塊（不靜默丟掉）——若看到某欄位跑到最上面沒有分區標題，多半是 seed 的 field.group 與 credential_group_schema.groups[].key 拼錯。
13. credential_group_schema 的 probe_param_key/probe_param_value 會整包 dump 給 FE：serializer 是 fields.Raw(allow_none=True) 原樣輸出，FE 契約上只准回傳 groups[].key。若日後改由 FE 直接送 probe 參數，等於讓瀏覽器指定送進 agent connector 的參數，是注入面——設計已明確排除，勿回頭走。
14. ZAP 對單頁式應用（SPA）不可使用登入後掃描——營運級風險，非單純掃不到：logged_in_indicator 比對的是伺服器回應的原始內容，SPA 的畫面文字是取得回應後才由瀏覽器產生，比對不到 → ZAP 判定尚未登入而反覆重試 → 認證失敗累積到 ZAP 2.17.0 的保護門檻後 daemon 主動停止自己；而 ZAP 是全租戶共用服務，一旦停止會連帶中斷其他租戶正在執行的掃描。本頁 ZAP 卡片的 setup_guide 已明白標示「請勿對單頁式應用使用登入後掃描」（2026-07-30-fr058-{3,4} 兩支 migration 補寫與更正）。被動 / 主動掃描不需登入、不受影響。設定連線資訊時的可控項只有 base_url/api_key，此限制實際發生在 任務配置 選 scan_mode='authenticated' 時。
15. config.detection_tools 沒有 i18n 機制（平台級缺口，FR-056 建表即存在）：name / description / setup_guide / config_field_schema 與 param_schema 的 label、hint、options[].label 全是中文寫死在 DB，切英文介面時本頁工具卡片與所有動態表單欄位仍是中文。FR-058 大幅擴充描述文案與 hint 之後，缺口的可見面積更大。已知並暫緩處理，非本輪範圍。
16. ⚠️ STG / POC 的工具目錄領先其 agent 版本（2026-07-31 實查）：FR-058 共 13 支 migration，前 11 支已誤套進三個環境（違反環境異動鐵律，事故已記錄於 CLAUDE.md 與 sql-migration skill），最後兩支（fr058-12 描述文案擴充、fr058-13 GCB Demo profile 選項）只在 DEV。後果：STG / POC 的目錄同樣顯示八筆、四款新工具皆 available，但兩地 agent 版本尚無對應 connector——使用者若在那兩個環境設定憑證並派工，會拿到跑不動的結果（目前租戶設定 0 筆、派工 0 筆，尚無實害）。上版時須連同 agent 部署一併處理；在此之前不要以「三環境目錄一致」推論「三環境功能一致」。

13. 開發與驗證

• 跑起來：BE python main_socketio.py（port 8000，log 在 log/app.log）；FE 在 compliance-manager-fe/ 起 Vite dev server。BE 改 service code 後必須重啟（無 hot reload）
• 測試帳號：dev 環境持 plugin.update capability 的帳號（角色權限矩陣「檢測工具管理」有 update 勾；系統層 super_admin 亦可 break-glass），密碼見 .env / 部署文件——新增/編輯/重置需此權限
• 導航路徑：登入 → 合規稽核 → 「檢測工具管理」（/plugin/tool-plugin-manage）
• 前置資料：config.detection_tools 需已 seed——FR-056 建表 scripts/sql/2026-07-26-fr056-1-detection-tools-config-schema.sql、FR-057 2026-07-28-fr057-1-openscap-seed.sql、FR-058 共 13 支 2026-07-3{0,1}-fr058-*.sql（DEV 全數已套，STG/POC 見 §12 坑 14）。測試連線需本租戶已部署具 detection_scan capability 的 Agent（見 檔案 Agent 管理 §12 坑 10——capabilities 欄位目前僅能直接改 DB 設定）；各工具目標端前提差異大，一律先看該工具卡片的「部署前提說明」（setup_guide）——OpenSCAP 需目標主機已裝 openscap-scanner + SSG content；CINC Auditor / GCB 引擎裝在 Agent 端主動連出、目標主機不需裝掃描程式（與 OpenSCAP 相反）；Nmap 需執行主機（非掃描目標）自行安裝 nmap；ZAP 需客戶自備可連線的 ZAP daemon
• E2E：compliance-manager-test/ repo（Cucumber + Playwright）；以 檢測工具 / detection-tool / tool-plugin 搜尋
• 相關文件：完整使用手冊見 docs/features/FR-056-2607-detection-tool-integration/user-manual.html；任務綁定與掃描參數見 任務配置與啟動；執行歷史與重新執行/取消機制見 任務執行抽屜；Agent capabilities 設定見 檔案 Agent 管理；FR-057 設計決策見 docs/features/FR-057-2607-openscap-ssh-connector/design.md；FR-058 決策表 D1–D34（四工具接入 D1–D12：含 ZAP 對 SPA 的營運級限制 D12、Nmap 改 SSH 型的 D9 改案與 NPSL 授權依據、GCB 複用 CINC 引擎的 D7；SonarQube 拉取 D13–D16、主動掃描 D17–D24、上傳掃描 D25–D34）見 docs/features/FR-058-2607-detection-tools-expansion/design.md §2 / §4.6–§4.8