FR-058 檢測工具擴充（四工具接入＋2026-07-31 追加 SonarQube 拉取與主動掃描）— 設計文件

狀態：全案已實作完成，決策者 2026-08-01 驗收通過（T-7.4 端到端驗收含 T-7.5／T-7.6 皆過；D1–D34 已拍板；D10 為 tombstone 空編號、D32 併入 D29，見 §2）｜建立日期：2026-07-30｜FR-056 檢測工具整合平台 → FR-057 OpenSCAP SSH connector 續作｜2026-07-31 追加 FR-058.5 SonarQube 拉取快照（§4.6）與 FR-058.6 SonarQube 主動掃描（§4.7）｜2026-08-01 追加 FR-058.7 SonarQube 上傳檔案掃描（§4.8，已實作完成並驗收） 討論稿（含流程圖與官方資源盤點）：discussion.html（四工具母案）、discussion-sonarqube-scan-mode.html（FR-058.6 SonarQube 主動掃描） 吸收 Notion CM-953「FR-057 後續：異質 OS 環境（Windows 等非 Linux 主機）的檢測支援方案」（狀態＝討論），於 FR-058.2 落地時一併結案，不另開平行卡。 2026-08-01 追加 FR-058.7 SonarQube 上傳檔案掃描（§4.8，拆分表 §5.12）——scan 模式的取源擴充；決策 D25–D31 定案、D32 併入 D29；討論稿：discussion-fr058.7-upload-scan.html（v4，決策者已全數過稿）。

FR-056 建立的檢測工具整合平台是 tool-agnostic 的：後端對任何具體工具零知識（不存在 if tool.code == "openvas" 這類分支），前端純 schema 驅動渲染，加一個工具原則上只要一條 SQL seed。FR-057 又補齊了 SSH 連線型態、setup_guide 說明欄位、多檔證據回收（result_ref.upload_uids）與兩條「靜默假成功」防護通道（host_failures / content_mismatch_hosts）。

本案站在這兩層地基上，一次接入四個工具，並補上平台唯一的結構性缺口——任務層敏感參數。

範圍註記（2026-07-31）：本文件各處的「四工具」指原始規劃的四棒（ZAP / InSpec / GCB / Nmap）。SonarQube 原於規劃期裁示「本期不做」移出，2026-07-31 決策者裁示重新納入，成為追加的第五棒 FR-058.5（拉取快照，詳見 §4.6）；同日再追加第六棒 FR-058.6（主動掃描，詳見 §4.7）——兩者同一個工具的兩種模式（D17），不是兩個工具。既有段落的「四工具」措辭不逐一改寫。

1.1 四工具的整合形態

以「連線型態」分，這四個工具分屬三種完全不同的模式——差別在於 connector 面對的是遠端服務 API、目標主機的遠端 shell，還是 agent 本機的命令列：

②′ 是 T-2.2 實作後才浮現的第四種形態（原歸在 ②，實際上方向相反）。connection_type 仍宣告為 SSH / WinRM——那是目標主機開放的協定，不代表 connector 自己建連線。詳見 §4.3「架構事實」。

①′ 是 FR-058.6 帶來的第五種形態。要注意的是 connection_type='CLI'（FR-056 定義至今無使用者）仍然沒有使用者——SonarQube 主動掃描雖然在 agent 本機跑二進位，但它的連線標的與憑證都是遠端 SonarQube server，歸 API 型而非 CLI 型；CLI 指的是「整個任務只在 agent 本機完成、不連任何遠端服務」。

1.2 平台唯一的結構性缺口：任務層敏感參數

現有設計把憑證與參數分成兩處放，而只有憑證那一條有加密：

若直接把被掃網站的登入帳密塞進 tool_params，會發生兩件事：① 帳密明文躺在資料庫；② FE 執行紀錄視窗會顯示任務參數——BE 現有的 secret 剝除機制是針對租戶層設定的 secret 定義寫的，任務層參數沒有這套保護，等於帳密直接顯示在畫面上。

這不是 ZAP 專屬問題（Nmap 若要做認證掃描、GCB 若每台主機帳密不同都會撞上同一格），因此當成平台級能力補上，成為 FR-058.0，並且是 ZAP 的硬前置。

1.3 端到端流程（以 ZAP 登入後掃描為例）

稽核員發佈任務：填 target_url、選「登入後主動」、填測試帳密
  → BE 依 param_schema 對 secret:true 欄位 Fernet 加密後寫入 tool_params（敏感欄位為密文）
  → 按「開始執行任務」：挑 agent、解密租戶工具憑證、建 agent_tasks（pending）、建執行紀錄
  → agent 心跳（mTLS，預設 300 秒）領回 pending_tasks（含當場解密的明文參數，僅傳輸中存在）
  → agent 起 daemon thread：ack → get_connector → ZAP 設定 context/登入認證/logged_in_indicator
     → ajaxSpider 爬取 → ascan 主動掃描（輪詢，支援 cancel_event / timeout）
     → core.htmlreport / core.jsonreport 雙格式（HTML 上傳當證據 / JSON 僅記憶體解析 summary）
  → 報告 bytes 走既有 blob 通道上傳 → 回報 result
  → 雲端取回存 job_evidences（source=DETECTION_TOOL）→ 通知負責人 → 依完成模式收尾
  → FE 執行紀錄顯示參數時，敏感欄位已剝除

敏感參數的生命週期：資料庫為密文、僅在派工傳輸與 agent 執行期間為明文、agent 用完即丟不落地、FE 一律剝除。

D10 原隨 SonarQube 移出本案而成為空編號；2026-07-31 SonarQube 重新納入為 FR-058.5 後，決策以 D13–D16 重新定案，D10 編號維持 tombstone 不重用、不重排（避免與先前溝通過的編號錯位），其餘編號不變。同日追加 FR-058.6 SonarQube 主動掃描，決策以 D17–D24 定案（全數已拍板，無待決策項）。2026-08-01 追加 FR-058.7 SonarQube 上傳檔案掃描，決策以 D25–D31 定案（全數已拍板）、D32 併入 D29 ④ 不獨立成案（編號保留、內容指向 D29）。同日 FR-058.7 驗收期間追加 D33（upload 任務不進自動派發清單）與 D34（檢測掃描通知加厚：九項內容＋失敗通知＋三管道）並定案。

2.1 補充：Linux GCB 為何不沿用既有的 OpenSCAP

技術上 Linux GCB 確實可以用 OpenSCAP 執行——它是 Linux 原生工具，FR-057 也已有可用的 SSH connector。不選它的原因不在 Linux 這一側，而在維護成本：Windows GCB 只有 CINC 這條路走得通（OpenSCAP 官方已聲明放棄 Windows native 支援，docs/windows.md 明文標示 no longer usable；引擎層也沒有 WinRM transport 與 Windows OVAL probe）。若 Linux 走 OpenSCAP，同一份 GCB 基準就要維護兩種 content 格式。

OpenSCAP 的定位不變，兩者按「基準來源」分工而非按 OS 分工：

• OpenSCAP 繼續服務 CIS / STIG 這類有官方 SCAP content（SSG）可直接取用的國際基準。
• CINC Auditor 負責 GCB 這種沒有官方 content、必須自產，且 Windows 端別無選擇的基準。

同一台 Linux 主機要查 CIS 就派 OpenSCAP 任務、要查 GCB 就派 CINC 任務，兩個任務可掛在同一個控制項底下、證據進同一個證據池——這正是 CM-953 已定的**「一任務一工具，靠多任務處理異質環境」**模型，本案沿用，不需改架構。

3.1 既有派工機制（本案沿用，除 D11 那一點外不改）

核心設計：雲端不主動推，agent 定期來問。 雲端連不到客戶內網，故不能主動下指令。agent 每隔 heartbeat_interval_sec（預設 300 秒）向雲端報到並領回待辦。這同時滿足防火牆限制——只有 agent 對外連出，無對內連入。

對加新工具的意義：派工鏈路本身是 tool-agnostic 的，四個新工具全部沿用，「發指令」機制完全不用改。真正要動的只有兩點——雲端一條 SQL seed（detection_tools 一列 + param_schema，零 Python）；agent 加一筆 _TOOL_ID_TO_CODE 映射 + 寫 connector 實作。而 D11 要解的正是後者的映射脆弱性。

3.2 元件 × 現況 × 本案動作

3.3 風險與既有技術債（實作時會撞到，拆任務時先知道）

4.0 共通：參考檔案座標

實作前先讀這些檔案，四個子需求都會用到：

SQL migration 撰寫鐵則（本案所有 seed 都要遵守）：檔頭寫 -- Date:、每個語句加日期註解、新建 table 必加 GRANT ... TO cm_app + sequence 權限、收尾必 INSERT public.schema_migrations；套用一律 psql --single-transaction -v ON_ERROR_STOP=1 -f <檔> 用 cmmgr 帳號（密碼請查 .env 或部署文件）。三環境（DEV / STG / POC）都要套。

4.X 橫向前置：_TOOL_ID_TO_CODE 解耦（D11）

現況：evidence-agent/core/task_executor_connectors/__init__.py 用 _TOOL_ID_TO_CODE = {1: "openvas", 2: "nessus", 3: "sonarqube", 4: "openscap"} 硬編 id 到 code 的映射。agent 不連雲端 DB 查工具目錄，只靠這張表認工具。

改動：

• BE _collect_pending_tasks() 組裝 pending_tasks 時，payload 加 detection_tool_code 欄位（值取自 detection_tools.code）。
• agent get_connector() 簽章改為優先吃 code；detection_tool_id 保留為 fallback（舊 agent / 舊 payload 過渡期不壞），fallback 路徑加 warning log。
• 移除 _TOOL_ID_TO_CODE 硬編表（或降級為僅 fallback 用的相容表，並在註解標明退役時機）。

為何排在最前面：三條開發線都會動到 agent 這個共用 repo。各自新增一支 connector 檔案彼此不衝突，但這個 factory 檔三條線都要改，同時開工會反覆衝突。而解耦本身工作量很小（改一個 factory + 派工 payload 加一個欄位），先做完三條線就不會撞同一個檔；等四個 connector 都寫完再回頭改，要重測的範圍會擴大四倍。

4.1 FR-058.0 任務層敏感參數（平台前置）

param_schema 語意擴充

detection_tool_param_schemas 的 schema JSON 每個欄位定義新增 "secret": true 旗標，語意與租戶層 config_field_schema 的 secret 定義一致。

BE 加解密接線（複用既有 Fernet 鏈，不另立機制）

已知坑：param_schema 是版本化的。加解密要以「該任務當初綁定的 schema 版本」為準來判定哪些 key 是 secret，否則 schema 改版後舊任務會解錯（把明文當密文解、或把密文當明文送）。

FE

• 欄位渲染：secret: true 且 type: password 走現成的 password 型態，不需新元件。
• 執行紀錄（JobExecutionDrawer.vue）：BE 已剝除，FE 不需再過濾；但要確認 _PRIMARY_PARAM_KEYS 之類的硬編邏輯不會意外把缺席的 key 顯示成空白或原始 key 名。

4.2 FR-058.1 ZAP（依賴 FR-058.0）

身分與整合形態

原 OWASP ZAP，現歸 Checkmarx 維護，仍為 Apache 2.0 開源授權。屬 DAST（動態應用程式安全測試）——對執行中的網站主動送出測試請求，找出網頁層弱點。

走 API / daemon 模式（與 OpenVAS 同型），不走 baseline CLI 模式。理由：API 模式能做「登入後掃描」，那是稽核場景真正有價值的能力；CLI baseline 只能被動掃表層，對合規證據的價值有限。

任務參數（param_schema）

沒有選登入模式時，後四欄整組不顯示（用 FE 現成的 condition 機制，不需新元件）。這對上「有帳密就深掃、沒有就一般掃描」的需求。scan_mode 預設值＝被動（D2），主動類選項在 FE 加警語。

租戶層 config_field_schema：ZAP 服務位址 + API key（secret）。

登入後掃描的適用範圍限制：僅傳統表單登入，SPA 列後續另案（D12）

上表這組參數是傳統表單登入模型——ZAP 對登入頁 POST 帳密欄位、用 cookie 維持 session、用 logged_in_indicator 比對回應內容判定是否仍在登入態。這個模型對 SPA（單頁式應用）天生不成立，三個原因彼此獨立、必須同時解決才會通：

本案定位：第一批只支援傳統表單登入，SPA 登入掃描列後續另案（決策與被排除方案見 D12）。setup_guide 需明白寫出此限制——且措辭必須是禁止使用而非「結果會不完整」，理由見下方實測驗證。

⚠️ 後果更正（2026-07-30 實測）：本節原先記載「對 SPA 掃描仍會完成、只是涵蓋範圍侷限於登入前頁面」（安靜成功），該描述是錯的。實際後果嚴重得多：ZAP daemon 會被自身的保護機制強制關閉，掃描不會完成，且連帶中斷同一台 ZAP 上其他任務。

實測驗證（2026-07-30，目標 http://192.168.50.151）：

完整因果鏈——

1. SPA 表單登入無效（原因 ①），ZAP 未取得任何登入態；
2. logged_in_indicator 在原始回應中找不到（原因 ③），ZAP 判定「未登入」；
3. ZAP 依設計重跑登入 → 再次失敗 → 再判未登入 → 無限迴圈；
4. 認證失敗次數累積達 100 次，觸發 ZAP 2.17.0 的 Insights 門檻 insight.auth.failure；
5. ZAP 主動關閉自己（不是被 agent 中止，也不是逾時）。

daemon log 摘錄：

[ZAP-Insights] INFO org.parosproxy.paros.control.Control - Shutting down ZAP due to High Level Insight:
HIGH : EXCEEDED_HIGH : http://192.168.50.151 : insight.auth.failure : 100
[ZAP-Insights] INFO ... - Discard Session
... (後續大量 Selenium NoSuchSessionException，為 ZAP 死後的餘波，非原因)
ZAP 2.17.0 terminated.
zap exited with code 2 (restarting)

讀 log 時容易誤判的一點：NoSuchSessionException 洗版看起來像 Selenium 出問題，但它發生在 Shutting down ZAP 之後，是 ZAP 已死造成的下游噪音，不是根因。根因只有 insight.auth.failure : 100 這一行。

營運層級影響（本次更正的重點）：ZAP daemon 是全租戶共用的單一服務，不是每個任務一個實例。因此一個 SPA 登入掃描任務可以把整台 ZAP 打掛，連帶中斷該台 ZAP 上其他正在執行的掃描——實測當下即發生：另一個任務在 ZAP 重啟的空檔收到 Connection refused 而失敗。這使問題性質從「報告涵蓋範圍不足」升級為「單一任務可造成全域服務中斷」。

範圍界定（避免過度解讀）：此問題僅限登入後掃描模式。被動掃描與主動掃描不建立 ZAP context、不設定任何認證、不比對登入特徵字串，因此不會產生認證失敗、不會累積計數、碰不到 Insights 門檻。第一批出貨的被動與主動兩種模式完全不受影響。

實測佐證（2026-07-30，對一個 Next.js SPA 站台）：

• 覆蓋範圍：掃到 10 個 URL，全部為登入前靜態資源——根路徑、_next/static 下的 JS / CSS chunk、favicon；無任何 API 端點、無任何登入後頁面。
• 產出：HTML 報告 57 KB，證據上傳鏈路本身正常（D4 的雙格式取報告已驗證可行）。
• alert 分佈：2 High / 8 Medium / 7 Low / 32 Informational，性質集中在站台層級組態問題（安全標頭、CSP、cookie 屬性、資訊洩漏），非應用邏輯漏洞。

這組數字同時也是匿名掃描的價值邊界的具體證據：對 SPA 而言，未解決登入即等同匿名掃描，能查出組態層問題但碰不到應用邏輯——這正是登入後掃描在稽核場景的價值所在，也是它值得列為獨立後續案、而非在第一批做半套的理由。

已知但本案不做：connector 端的自我保護（2026-07-30 裁示：只記錄不實作）

上述營運層級風險有一個成本很低的緩解手段，但本案不做：

• 內容：connector 在登入模式下自行偵測認證失敗異常累積（例如監看 ZAP 的認證失敗計數或重複登入次數），在逼近 Insights 門檻前主動中止任務並回傳明確訊息（如「目標網站可能是單頁式應用，登入後掃描不適用」），避免撞上門檻把共用的 ZAP 服務打掛。
• 決策：決策者 2026-07-30 裁示——本案只記錄不實作。
• 關聯與獨立性：與 Notion CM-984（SPA 支援後續需求）相關，但可獨立先做——它是防護措施，不需等 SPA 的 json-based 認證與 script-based session management 完成；即使 SPA 支援永遠不做，這道保護對「使用者誤把 SPA 當表單登入站台來掃」的情境仍然有效。

ZAP 2.17.0 相容性（使用者公司已安裝此版，實作前必須對齊）

沒有破壞性的 API 端點移除，主線呼叫序列可以沿用。

舊碼參考：前同事的 auto-pentest 專案

位置 ~/Documents/Projects/Jedicogy/auto-pentest/（DDD 分層 + MinIO 儲存）。它的價值不在架構，而在踩過坑才整理得出的那幾份知識。

connector 實作要點（evidence-agent/core/task_executor_connectors/zap.py）

• run()：依 scan_mode 分支（被動 / 主動 / 登入後主動）。登入後主動要先設定 context + 登入認證 + logged_in_indicator，再跑 ajaxSpider 與 ascan。
• 取報告：雙格式（D4，2026-07-30 改版）——core.htmlreport() 回 bytes 上傳當證據（檔名 ZAP掃描報告_<target>_<date>.html）；core.jsonreport() 回 bytes 只在記憶體解析出 summary，不上傳。不走 reports.generate（只寫 daemon 主機磁碟、無回傳內容端點）。
• probe()：只驗「連得到 ZAP daemon 且 API key 正確」，不建立任何掃描資源（與 base.py 的 probe() 語意一致）。
• cancel_event 與 timeout：輪詢迴圈每圈檢查 cancel_event，命中就 raise ScanCancelledError；另設 timeout 上限，避免無限等待。
• setup_guide：寫 daemon 啟動指令與 API key 設定說明（客戶自備，D3）。

4.3 FR-058.2 InSpec / CINC Auditor（獨立，可與 .0 並行）

身分與要解的問題

組態合規檢測引擎，用 Ruby DSL 撰寫檢測規則（profile）。本案接入它是為了解決 Windows 主機組態檢測這個既有缺口——FR-057 的 OpenSCAP connector 是 SSH 加 Linux 寫死的（/usr/bin/oscap、/etc/os-release、sudoers），無法處理 Windows 主機。

吸收 Notion CM-953（「FR-057 後續：異質 OS 環境（Windows 等非 Linux 主機）的檢測支援方案」，狀態＝討論，https://app.notion.com/p/3ac346da4cd0819390d2c5b85c754bf8），不另開平行卡。CM-953 提的三個選項中，選項 1（OpenSCAP Windows 走 WinRM）已被證實不可行——OpenSCAP 官方放棄 Windows 支援，且引擎沒有 WinRM transport、沒有 Windows OVAL probe，無論怎麼配置都掃不到 Windows 目標。InSpec / CINC 屬選項 2 的具體答案。CM-953 定的「一任務一工具、靠多任務處理異質環境」模型本案沿用，不需改架構。本子需求落地時一併結案 CM-953。

為什麼是 CINC 而非其他 SCAP 系工具

授權關鍵：必須用 CINC Auditor（Apache 2.0 自由重建版，Progress 官方認可的 drop-in 替代品），不要用官方 InSpec 6+ 商業 binary（需接受 Chef EULA 並持有 license key）。這一點在採購與部署文件上都要寫明（D5）。

架構事實：CINC 裝在 Agent 本機，與 OpenSCAP 相反（T-2.2 實作後補記，2026-07-31）

這一點與 OpenSCAP 的方向完全相反，後續實作者務必先看清楚：

這正是 D6「多做一個 transport 的邊際成本很低」的真正原因——transport 差異被 CINC 自己吸收了，connector 兩邊共用同一套指令組裝與 --reporter json 解析。原設計文件只有推論，T-2.2（CM-973，evidence-agent dcedb4f）實作後已有實證。

因此 openscap.py 只有「多目標逐台處理」與「host_failures 逐台回報」兩個形狀可借鏡，連線那一層完全不同，不可照抄。 本文件先前「對照 openscap.py 的 SSH 模式」之類的描述已依此更正（§4.0 參考檔案座標）。

對 FR-058.3 GCB 的直接影響：T-3.2 的 content 外部載入接口是建立在這個架構上的——profile content 由 agent 本機讀取後交給 cinc-auditor，不需要、也不應該送到目標主機。若誤以為 content 要先傳到被掃描的機器上，接口會設計錯，而那要等到端到端驗收才會發現。

T-2.2 建立的三個實作約定（後續棒次延續）

1. 憑證不進 argv。 cinc-auditor --password 會讓密碼出現在 Agent 主機的 ps 輸出，而證據 Agent 是長駐服務——任何能看到該主機行程的人都讀得到客戶的稽核帳號密碼。故改走官方 --config <JSON 檔> 的 credentials 區塊，命令列只帶 -t <transport>://<連線名>。config 檔與私鑰一律寫 /dev/shm（tmpfs，不落實體磁碟）、權限 0600、try/finally 用完即刪（含例外與取消路徑）。
2. 授權紅線以測試釘住。 指令刻意不帶任何 license 相關參數——CINC 沒有 license 機制，而官方 InSpec 6+ 未接受 EULA 會 exit 172。若日後有人把 Dockerfile 換成官方 InSpec，掃描會整批硬失敗，那個失敗是刻意留的路障，不該靠加 --chef-license accept 之類的參數「修好」（那等於預設替客戶接受商業授權條款）。已有測試釘住此約定。
3. probe 的檢查順序：憑證缺漏在前、引擎檢查在後。 兩組 transport 憑證都是非必填（設定當下無從得知任務會選哪一種），這個取捨成立的前提就是缺漏必須在 probe() 講清楚。順序若對調，憑證不齊的使用者會先看到「Agent 沒裝檢測引擎」——把客戶端設定問題誤報成我方部署問題，會把人導向完全錯誤的排查方向。已有測試釘住此順序。

設計要點

• 雙 transport（D6）：SSH（Linux）與 WinRM（Windows）。目標 transport 的選擇透過任務參數或設定欄位決定；detection_tools.connection_type 需涵蓋這兩種型態（SSH 已存在，WinRM 為新值）。實作落點為任務參數 params.transport（同租戶的 Linux / Windows 目標分屬不同任務，沿用 CM-953「一任務一工具」模型），憑證則兩組並存於租戶層（ssh_* / winrm_* 前綴）。
• 結果解析統一走 --reporter json：兩個 transport 輸出格式一致，connector 只需一套解析。
• 證據格式：html2 上傳、json 只算 summary（2026-07-31 實測後定案，對齊 D4 ZAP / D9 Nmap 的雙格式精神）：一次執行帶兩個 reporter，json 走 stdout 只在記憶體算 summary 不上傳，html2:<檔案> 寫出的 HTML 上傳當證據。兩份等價內容都進證據池是 D4 已排除過的走法。
  • 用 html2 而非內建的 html：後者是 RSpec 風格測試輸出，實測 grep 控制編號命中 0 次，無控制標題與嚴重程度，對稽核判讀無用；官方文件亦說明 html 僅為向下相容保留、「unaware of profiles or controls」。html2 三者皆有，且產出的 HTML 不引用任何外部 CDN 資源（自包含、離線可開）——證據要能長期保存後再開啟，這是必要條件而非加分項。
  • 不自行從 JSON 手刻 HTML：上游已有結構完整且自包含的產出，手刻只是多一份要維護的模板。
• 多目標處理沿用 FR-057 模式（僅此一項）：逐台掃、每台一個證據檔，host_failures 逐台失敗回報通道直接沿用（避免「靜默假成功」）。連線那一層不沿用——見上方架構事實表。
• 憑證：沿用租戶層 tenant_detection_tool_configs 加密鏈（Linux SSH 帳號／金鑰、Windows WinRM 帳號密碼）。若日後需要每台主機不同帳密，走 FR-058.0 的任務層敏感參數。
• agent image：加入 CINC Auditor。

4.4 FR-058.3 GCB（依賴 FR-058.2）

身分與範圍

政府組態基準（TWGCB），我國公務機關資通設備的組態安全基準，屬合規稽核情境的高需求項目。

本案範圍已由 D7 收斂：只做引擎（直接複用 .2 的 CINC Auditor，不另立引擎、不另寫 connector）與一份 Windows 最小 Demo profile，證明端到端鏈路可運作即可。

為何 Demo 選 Windows（2026-07-30 官方資源查訪的結論）

資料來源為 NICS 兩個官方頁面（GCB 說明文件頁標示 2026/6/26 更新、GCB 部署資源頁標示 2026/3/30 更新）。本次查訪最重要的發現：Linux 與 macOS 在部署資源頁完全沒有任何機器可讀檔案。

說明文件頁有完整的 RHEL 8 / RHEL 9 / Ubuntu 22.04 / macOS 15 基準，但沒有任何對應的機器可讀部署檔——連 shell script 都沒有。這證實並擴大了 NICS FAQ v1.6 §7.1「未提供 RHEL8 等平台自動化檢測工具」的說法。

Windows 有 GPO 檔這個結構化來源可直接參考，寫一個最小 Demo profile 的成本最低；Linux 只有 DOCX，連一條 Demo 規則都要先人工翻譯文件敘述。這是選 Demo 平台的理由，不是要在本案做 Windows content 工程。

常見誤解澄清：「是不是要把官方 PDF 轉成 content」——Windows 不需要（有 GPO 檔可解析）；Linux 需要，但那不是「轉檔」，而是逐條人工把文件敘述翻譯成檢查邏輯。content 工程已不在本案範圍，此處僅為背景說明。

本案的設計約束：content 必須可外部載入

content 不可硬編進 connector 或 agent image，必須設計成可從外部載入。理由：content 本質上是會持續變動的資料，不該綁在程式版本裡。日後要接後台更新機制時，若當初把 profile 打包進 agent，等於每次更新 content 都要重新發版並更新所有客戶站點的 agent。這個接口現在留成本極低，事後補要改動 connector 結構。

D7 約束的達成方式：不另做抽象層（T-3.2 定案，2026-07-31）

結論：約束已滿足，且不需要寫任何 code。 T-3.2 原規劃要做一層「content 外部載入接口」，實作前確認後裁示不做這層抽象——CINC 原生就支援三種 content 來源，而 params.profile 是直接進 cinc-auditor exec 的 argv，外部載入能力本來就在。再包一層只是把 CINC 的能力用我們的詞彙重新命名一次，徒增一個要維護、要測試、且會限縮上游能力的中間層。

D7 約束的逐條驗收：

• 不硬編進 connector ✅ — inspec.py 對 profile 的處理只有「取 params.profile、缺就報錯、有就原樣放進 argv」，connector 內不含任何 content 內容或路徑常數。
• 不打包進 agent image ✅ — Dockerfile 只裝引擎（cinc-auditor）與其相依（git、xsltproc），無任何 profile 檔。
• 更換 content 不需重建 image、不需改 connector ✅ — 換一份 content＝任務參數換一個字串，agent 端零改動。

架構前提再強調一次（§4.3 架構事實）：content 由 Agent 本機讀取後交給 cinc-auditor，不送到目標主機。CINC 裝在 agent 端、由它自己連出去掃，目標主機不需要安裝任何東西、也不需要拿到 profile。若誤以為 content 要先傳到被掃描的機器上，接口會設計錯，而那要到端到端驗收才會發現。

實跑佐證（2026-07-31，DEV agent 0.2.17 / 192.168.50.123）

① 兩份公開 content 對兩種 transport 各跑通一次（這同時是 T-2.3 的雙 transport 驗收）：

error 0 是這裡的重點——引擎確實把 content 取到、看懂、跑完，不是連上去之後靜默空轉。

② 裸 GitHub 網址走的是 git fetcher，不是 tarball 下載（踩過才知道的事實）：CINC 對裸 GitHub 網址會 shell out 呼叫 git 去查 default branch。agent image 原本沒裝 git，首次實跑因此在還沒連上目標主機之前就炸在 profile 解析階段（Errno::ENOENT）。已於 agent commit 6d1a4fc 補裝 git，DEV 現行 0.2.17 容器內為 git 2.47.3。

連帶的錯誤分類修正：當時所有失敗都被歸類成「連線目標失敗」，把 agent 端的 profile 取得問題誤報成客戶的網路/憑證問題。inspec.py 已補上 profile 階段的 marker 比對，並刻意排在連線判定之前（同 T-2.2 第 3 點的精神：分類籠統比分類錯更貴）。

③ tarball 形式對 git 零相依（T-3.1 為決定 profile 下拉預設值而做的對照實驗）：把容器內 /usr/bin/git 移走後重跑同兩個網址——

耗時無實質差異（84s / 88s）。裸網址今日之所以可用，完全建立在 6d1a4fc 補裝的 git 上；tarball 形式對此無相依。故 T-3.1 的 profile 下拉預設值一律採 tarball 形式（少一個外部相依與故障點），自行輸入的彈性不減。

兩個已知限制（本案不做，已裁示開後續卡）

「不做抽象層」的取捨有代價，兩者都是能力缺口而非 bug，且都不影響本案驗收（Demo 走公開網址）。記在此處是為了讓日後接後台 content 更新機制的人不必重新踩一次：

兩者的解法都指向同一件事：後台 content 管理機制（上傳／版更／套用），由平台把 content 送到 agent 可讀的位置，順帶消掉私有 repo 的認證需求。該機制 D7 已排除出本案，兩個限制併入其評估範圍。

Demo profile 的注意事項

必須避開 tattoo settings 陷阱：規則若讀取非 HKLM\Software\Policies 路徑，可能讀到上次殘留的舊值而誤判為通過，實際上政策根本沒生效（詳見 §3.3 風險表）。Demo 選題時就要挑正規政策區的項目。

4.5 FR-058.4 Nmap（完全獨立）

2026-07-30 改案：本節原為 connection_type='CLI'（agent 本機子行程）設計，已改為 SSH 型。改案的完整推導、NPSL 條款原文與三個被排除方案見 §2 的 D9。

身分與整合形態

網路埠與服務探測工具。在合規情境對應「開放服務盤點」「非必要服務關閉」這類控制項的證據。技術上是四個工具裡最單純的一個。

connection_type='SSH'，與 OpenSCAP 完全同構：nmap 由客戶安裝在自己指定的主機上，agent 透過 SSH 登入該主機執行 nmap -oX 並取回 XML 再解析。agent 本身不安裝 nmap、不在容器內執行它。

之所以不走原定的 CLI（agent 本機執行），有法律與技術兩個各自獨立成立的理由（詳見 D9）：法律上，NPSL v0.95 §3 的衍生作品定義明文涵蓋「專門執行本軟體並解析其結果」的程式，我們的 connector 正中此條，因此不能 bundle；同條款末段又明說不主張控制「執行使用者早已安裝在自己系統上的 nmap」的軟體，SSH 型正落在這個出口內。技術上，agent 跑在 Docker container 內，看不到主機上安裝的 nmap，原 CLI 設計的「客戶自備」在容器化部署下根本無法成立。

連帶結果：Nmap 需要 SSH 憑證（requires_credentials 為 TRUE），不再是零憑證工具。connection_type='CLI' 因此至今仍無任何實際使用者（FR-056 定義後未被用過）。

前提

授權：不要打包進我們的 image。 Nmap 採 NPSL（非標準開源授權，基於 GPLv2 但加了額外限制），不可 bundle 進我們發布的 agent image，也不可要求客戶把它裝進我們的容器。做法是客戶在自己指定的主機上安裝 nmap（apt install nmap 之類，無任何 docker 操作），agent 走 SSH 遠端呼叫。setup_guide 要寫清楚：在哪台主機安裝、各主流發行版的安裝與驗證指令、SSH 連線與帳號權限前提，以及埠掃描的授權警語（比照 ZAP）。

D9 原列的第二個前提「零憑證會被平台誤擋」在改案後不再適用於 Nmap（它現在需要 SSH 憑證）。但該平台能力（detection_tools 的「是否需要憑證」宣告欄位 + start_execution() 放行）仍然正確且保留，供日後真正零憑證的工具使用。

connector 實作要點（evidence-agent/core/task_executor_connectors/nmap.py）

主要對照範本是 openscap.py（SSH 型），不是本機子行程模式。 SSH 連線處理、私鑰暫存與用完清除、多目標主機逐台執行、host_failures 逐台失敗回報這些形狀直接複用。

• run()：SSH 登入指定主機 → 執行 nmap -oX → 取回 XML → 解析產出 summary（開放埠數、服務清單等）→ XML 或轉出的人可讀報告上傳當證據。多台執行主機時逐台一份證據，某台失敗以 host_failures 明確回報（不靜默假成功）。
• probe()：四段式錯誤分類，各段回各自明確的訊息——① SSH 連得上嗎（網路 / port）→ ② 認證過嗎（帳密 / 私鑰）→ ③ 該主機上有沒有 nmap 且可執行（command -v nmap + nmap --version）→ ④ 執行權限夠不夠（部分掃描類型需要提權）。第 ③ 段的訊息要讓管理員一看就知道「要去那台主機裝 nmap」，而不是丟原始的 exit code 127。
• cancel_event 與 timeout：取消時要中止遠端執行中的 nmap 並清理 SSH channel，raise ScanCancelledError；照 openscap.py 的遠端子行程取消形狀處理，不要留下對端的孤兒行程。
• param_schema：掃描目標、掃描類型、埠範圍等（皆非敏感，不涉及 FR-058.0）。SSH 憑證屬租戶層設定（tenant_detection_tool_configs，走既有 Fernet 鏈），不放任務參數。

4.6 FR-058.5 SonarQube（2026-07-31 追加；獨立，不依賴其他子需求）

決策脈絡見 D13–D16。原規劃期裁示「本期不做」移出（D10 因此成為 tombstone 空編號），2026-07-31 決策者裁示重新納入為第五個子需求。

身分與整合形態

SAST（靜態應用程式安全測試）——分析原始碼找出 bug、弱點與程式碼異味，在合規情境對應「安全開發流程」「程式碼安全檢測」這類控制項的證據。

平台第一個「拉取快照（pull-snapshot）」型工具。 連線形態歸 §1.1 的 ①（連遠端服務 API），但語意與 OpenVAS / ZAP 不同——連的是 API 卻不下掃描指令。根本原因：SonarQube Server 沒有任何觸發掃描的 Web API，掃描由 sonar-scanner 在有原始碼的環境（客戶 CI）執行後把結果推上 server，Web API 只能讀取既有結果（唯一例外是 SonarQube Cloud SaaS 的 Automatic Analysis，與 self-hosted 無關）。因此任務執行＝連 server 拉指定專案最近一次分析結果、組成 HTML 報告當證據（D13）。

租戶層設定（config_field_schema）

[
  {"key": "base_url", "label": "SonarQube 服務位址", "type": "text",     "required": true, "secret": false},
  {"key": "token",    "label": "User Token",        "type": "password", "required": true, "secret": true}
]

token 必須是 user token（squ_ 前綴），HTTP 用 Authorization: Bearer header 送出；token 所屬帳號只需目標專案的 Browse 權限。不可用 sqp_ / sqa_ analysis token——那兩種只能執行分析、不能呼叫讀取 API（D16），setup_guide 要寫明這個區別。

任務層參數（param_schema v1）

皆非敏感參數，不涉及 FR-058.0。

API 呼叫序列

全部只需 Browse 權限；branch 參數僅在使用者有填時附加到各呼叫。

probe 設計

兩段式：

1. api/system/status——免認證，驗連通與服務狀態（server 是否 UP）。
2. 帶 Authorization: Bearer 呼叫 api/authentication/validate——驗 token 有效性。陷阱：匿名呼叫此端點也回 valid:true（它驗的是「當前身分是否有效」，匿名也是一種有效身分），必須帶認證 header 呼叫、結果才有意義（D16）。

probe 是租戶層動作、當下沒有 project_key，專案層權限問題不在 probe 驗——留到 run() 時以明確訊息回報（例如專案不存在或無 Browse 權限）。

connector 實作要點（evidence-agent/core/task_executor_connectors/sonarqube.py）

與既有 API 型 connector（OpenVAS / ZAP）的關鍵差異：沒有輪詢迴圈——拉取型不需要等掃描完成，run() 是一串順序 API 呼叫。

• 取消：逐 API 呼叫之間檢查 cancel_event，命中 raise ScanCancelledError。
• timeout：每個 HTTP 呼叫設 60 秒 timeout（不是整體輪詢上限，是單呼叫上限）。
• HTTP client：用 agent 既有的 httpx（FR-039 心跳已用），不加新相依。
• issue 解析跨版本相容（D16）：impacts[] 優先（MQR 語意，10.2+ 回應就有），缺席時 fallback 舊 type + severity，相容 9.9 LTS 至 2026.x LTA。
• 報告（D15）：拉 JSON 自行 render 自包含 HTML（無外部 CDN 資源）上傳當證據，檔名 SonarQube掃描報告_<project_key>_<date>.html、content_type="text/html"。內容＝Quality Gate 狀態＋核心度量＋severity 分佈＋issue 清單（前 200 條，註明「僅列前 200 條／總數 N」）＋Security Hotspots＋分析時間。這是必做項不是 fallback——Community Build 沒有任何報告匯出功能（付費版才有 PDF）。
• summary dict：{"findings": <issues 總數>, "bugs": …, "vulnerabilities": …, "code_smells": …, "security_hotspots": …, "quality_gate": "OK"/"ERROR"}——數字取自 measures API，不從 issue 清單自行加總。

factory 註冊

_CONNECTOR_BUILDERS 加 "sonarqube": _build_sonarqube（lazy import，3 行 builder 形狀比照 _build_zap）。絕不動 _LEGACY_TOOL_ID_TO_CODE——表內既有的 3: "sonarqube" 是 legacy fallback（D11 解耦後的過渡相容表），保持原樣。

seed 特殊點（易踩雷，T-5.1 必讀）

DB 已有 FR-056 留下的 id=3 sonarqube 佔位列（status='coming_soon'、config_field_schema=[]、無 param_schema）。因此——

• seed 是 UPDATE 既有列 ＋ INSERT param_schema，不是 INSERT 新工具。照 ZAP seed 範本的 INSERT ... ON CONFLICT (code) DO NOTHING 寫，會被既有列擋下靜默跳過，看起來成功實際什麼都沒改。
• UPDATE 內容：config_field_schema（上方兩欄）＋ status → 'available' ＋ setup_guide ＋ description 只拿掉句尾「此工具尚在規劃中、目前無法使用，敬請期待。」其餘不動。
• 依環境異動鐵律，開發期間只套 DEV。

驗收環境

公司自有 SonarQube（http://192.168.50.171:9000，專案 guidant-ai-backend / guidant-ai-fe）直接當 DEV 端到端驗收目標。token 為 user token——不寫進任何文件，執行者自查本機環境。

FE 接入點

純 schema 驅動、零新元件。僅兩處微調（T-5.3）：

• JobExecutionDrawer.vue 的 _PRIMARY_PARAM_KEYS 加 'project_key'。
• i18n my-tasks.json（zh-tw + en，比照既有 summary_* key 所在檔）補 summary_bugs / summary_vulnerabilities / summary_code_smells / summary_security_hotspots / summary_quality_gate。

已知限制

4.7 FR-058.6 SonarQube 主動掃描模式（2026-07-31 追加；雛形，依賴 FR-058.5 已落地的拉取鏈路）

決策脈絡見 D17–D24；討論稿：discussion-sonarqube-scan-mode.html。

⚠️ 定位：這是雛形，不是完整產品。 本節每一處取捨都朝「最小可行」傾斜。遇到「這裡是不是應該做得更周全」的疑問時，先翻本節末的「後續強化」——所有被砍掉的東西都在那裡列了一句話說明為什麼這階段不做。決策者原話：「先用公開 repo 可以下載的那種，我們先做一個雛形，後面再慢慢加強」。

需求背景：為何 pull 不夠

FR-058.5 做的是拉取快照——連客戶的 SonarQube，把「最近一次分析結果」拉回來組報告，平台不觸發掃描。決策者看到實際畫面後指出：

流程好像不太對，我想要的是 user 有提供一版源碼，可能上傳 或是提供 server 位置，然後透過 sonarqube cli 去掃描並且產出結果報告 — 決策者，2026-07-31

這句話包含三個要素：① 使用者提供一版源碼 → ② 平台透過 sonar-scanner CLI 執行掃描 → ③ 產出結果報告。上線的 FR-058.5 只有 ③，而且那個「結果」不是平台掃出來的，是客戶自己先掃好放在 server 上的。

這是新需求不是 bug。 FR-058.5 的 D13 明確裁示了「拉取最近一次分析結果組報告、不觸發掃描」，當時就把「agent 端自跑 sonar-scanner」列為被排除的選項，理由是「agent 沒有原始碼，也不可能備齊各語言 build 環境」。那個判斷在當時的前提下是對的——當時沒有「使用者提供源碼」這個輸入。本案正是補上那個前提（把源碼送進 agent），而「不可能備齊各語言 build 環境」則靠收斂語言範圍解決（D18 只做不需要 build 環境的 A 類）。

為什麼要把這段軌跡寫進文件：設計文件上會留下「D13 排除了 agent 自跑 scanner，D17–D24 又把它做出來」這種看似矛盾的紀錄。寫明是為了讓未來的人知道這不是反覆，是前提變了——輸入從「沒有源碼」變成「使用者會提供源碼」，被排除的理由就不再成立。

兩種模式的差異（＝本案工作量所在）

兩模式並存，拉取模式不移除（D17）。理由：① 對「客戶已有成熟 CI」的情境，拉取模式是正確且更輕量的答案，主動掃描反而多餘（會在他們的 server 上多建一個專案、多跑一次分析）；② 成本已付掉（connector / seed / setup_guide 都已完成並上 DEV）；③ C# / VB.NET 這類技術上做不了主動掃描的語言，拉取模式是唯一的路。

一個容易誤會的地方：兩種模式都需要客戶有 SonarQube server——因為 sonar-scanner 沒有 dry-run，掃完必須把結果推到 server 才讀得到。差別只在「誰發動掃描」，不在「要不要有 server」。

相同的部分（可直接複用）：都連客戶自架的 SonarQube、憑證都是 base_url ＋ token、最後都組成自包含 HTML 進證據池、取消 / timeout 的行為標準一致。

端到端流程

使用者建任務：選 SonarQube、scan_mode=原始碼掃描（預設）、填 Git repo URL + 專案代碼後綴
  → BE 派工（既有鏈路，本案無敏感參數：公開 repo 不需憑證）
  → agent 領回 task → 步驟一：git clone 到磁碟型 tmp 目錄（不可用 /dev/shm，D22）
  → 步驟二：Popen 起 sonar-scanner（輪詢式取消，stdout 走檔案）
     → scanner 分析（分鐘~數十分鐘）→ 推送結果到客戶 SonarQube（寫入！專案不存在會自動建立）
     → scanner 產出 report-task.txt
  → 步驟三：解析 report-task.txt 取 ceTaskId → 輪詢 GET /api/ce/task?id=<id> 直到 status 脫離 IN_PROGRESS
  → 步驟四：拉 quality gate / measures / issues / hotspots → render 自包含 HTML（複用 FR-058.5 既有程式碼）
  → 報告 bytes 走既有 blob 通道上傳 → 進證據池
  → finally：刪除 tmp 目錄（掃完即刪，D22）

步驟一到三是全新的；步驟四可直接複用已上線的拉取模式程式碼。

流程上兩個最容易被忽略的坑（官方文件明確，非推論）

坑一：沒有 dry-run。 sonar-scanner 沒有「只分析不推送」的模式——每一次掃描都是對客戶 SonarQube 的寫入，且專案不存在時會自動建立（provision），等於污染客戶的專案清單。管理員想擋，只能移除 token 擁有者的 "Create Projects" 全域權限，沒有專門的開關。D21 的 Guidant-AI- 前綴解決「撞號」與「無法辨識來源」，但「每掃一次多一筆專案」本身沒有解。

坑二：掃完不等於能讀。 scanner 印 EXECUTION SUCCESS 只代表上傳完成，server 端是非同步序列佇列。必須解析 scanner 產出的 report-task.txt 取得 ceTaskId，再輪詢 GET /api/ce/task?id=<ceTaskId> 直到 task.status 脫離 IN_PROGRESS 才能拉結果。如果掃完就直接去拉，很可能拉到上一次的舊資料——而且拉得到、不會報錯。

⚠️ 補充陷阱：CE 介面顯示的「處理時間」不含排隊時間，不能拿它當 timeout 的依據。實際等待時間取決於客戶 server 當下的佇列長度，這是我們控制不了的變數。逾時錯誤訊息建議能區分兩段——「掃描超過 N 分鐘未完成」與「掃描已完成但貴公司 SonarQube 佇列超過 N 分鐘未消化」是兩種完全不同的客戶端問題，混在一起客戶不知道要查什麼。

租戶層設定（config_field_schema）— 一個字都不用改

FR-058.5 已 seed 的兩欄（base_url text required / token password secret required）兩模式完全共用。原因見 D17 更正說明：squ_ User Token 推得上去也讀得回來（只有 sqp_ / sqa_ analysis token 是只能推不能讀），且 D19 定案只支援公開 repo → 沒有 Git 憑證這回事。

這代表本案不需要動 config_field_schema，也不需要 FR-058.0 的任務層敏感參數能力（公開 repo 無憑證可加密）。

任務層參數（param_schema v2）

形狀直接照 ZAP seed 的既有寫法（{"key":"...","condition":{"field":"scan_mode","value":"..."}}），FE 走現成 visible computed，不可見欄位跳過必填驗證——因此 pull 模式不會被 scan 的必填欄位誤擋，反之亦然。

setup_guide 必須改寫（D24 配套②③）：現行 setup_guide 開頭寫的是「本平台不會觸發程式碼掃描」——加入 scan 模式後這句話變成錯的，必須改寫為分模式說明，並明講「預設為原始碼掃描模式，執行時會在貴公司的 SonarQube 建立 / 更新專案（key 為 Guidant-AI-<識別>）」＋ 支援語言清單（D18 配套①）＋ 收緊模式做法（預先建好專案 ＋ 移除 "Create Projects" 權限）。

connector 實作要點（evidence-agent/core/task_executor_connectors/sonarqube.py）

模式分流：在 run() 入口依 scan_mode 分兩條路。pull 分支＝現況原封不動，scan 分支新增。

⚠️ 模式值非法必須明確 raise，絕不靜默降級。 直接沿用 zap.py:164-171 _resolve_scan_mode() 的既有立場——那段註解的理由是：使用者選了「主動」卻因拼錯被降級成「被動」，會拿到一份看起來正常但實際沒掃的報告，那比直接失敗更糟。本案同理且更嚴重：選了 scan 卻退回 pull，使用者會拿到舊的快照卻以為是剛掃出來的，而稽核報告上會標示分析時間——一份「時間是三個月前但使用者以為是今天」的證據，是會誤導稽核結論的。

子行程執行：直接照抄 inspec.py 的既有骨架，兩個設計要點必須一起帶走：

• :685-722 _run_with_cancel（Popen ＋ 輪詢）——不用 subprocess.run(timeout)，因為它無法中途取消；
• stdout 走檔案不走 PIPE——大輸出會在 OS 管線緩衝區填滿時死鎖，scanner 輸出正是大輸出；
• :657-683 _terminate（SIGTERM → 寬限 → SIGKILL）處理取消與逾時。

暫存與清理（D22）：clone 目錄開在容器自身 /tmp（磁碟型），不可用 /dev/shm（tmpfs 記憶體型，既有 inspec.py:197-200 慣例是為小憑證檔設計的）。清理走 finally / contextmanager，掃完即刪——含失敗與取消路徑。

輪詢 CE 佇列：解析 scanner 產出的 report-task.txt 取 ceTaskId → 輪詢 GET /api/ce/task?id=<id> 直到 task.status 脫離 IN_PROGRESS；逾時訊息區分「掃描未完成」與「佇列未消化」兩段（見坑二）。

結果拉取與報告：完全複用 FR-058.5 既有的 _fetch_* 與 _render_report——這是兩模式共用的部分，不另寫一套。

FE 接入點

scan_mode 的 select 與條件欄位本身走現成 schema 驅動渲染，零新元件。

後續強化（本階段刻意不做，全數為裁示排除非遺漏）

風險與已知限制

落地前必須實測的項目

1. scanner 打包後的 image 體積增量——交付走 docker save，體積直接影響客戶體驗。
2. 逾時秒數的合理值——現在填任何數字都是猜的，官方零基準數據。
3. 各 A 類語言的實際記憶體用量——尤其 JS/TS 與 Kotlin 兩個 OOM 熱點。
4. 端到端驗收目標：公司自有 SonarQube（192.168.50.171:9000）＋ 一個公開 repo。

4.8 FR-058.7 SonarQube 上傳檔案掃描（2026-08-01 追加；scan 模式的取源擴充，依賴 FR-058.6 已落地的 scan 鏈路）

決策脈絡見 D25–D32；討論稿：discussion-fr058.7-upload-scan.html（v4，決策者已全數過稿）。

定位：scan 模式的取源擴充，不是新模式。 FR-058.6 scan 模式的管線是：取源（git clone）→ sonar-scanner 掃描 → 推上 SonarQube server → CE 等待 → 報告回收 → 品質門檻渲染。本案只把第一段的取源方式多加一種：從 tenant 儲存空間下載上傳的壓縮包並安全解壓。後面整條掃描管線全部複用，一行不動。新造的東西只有四塊：取源通道（D25）、執行時輸入的傳遞（D26）、檔案生命週期（D28 / D29）、解壓額度檢查（D30）。

需求背景：為何 scan 的 Git URL 不夠

決策者原話（2026-08-01）：

還是要可以上傳檔案做檢測，有辦法是上傳到 tenant 設定的儲存空間後，由 agent 拉下來，做掃描，掃完就刪，如果硬碟不夠就跳錯誤就好

宏觀流向由這句話定調成五段：① 使用者上傳源碼壓縮包 → ② 落地在 tenant 設定的儲存空間（system_configs 的 STORAGE_CONFIG，支援 local / minio / remote_agent 三後端——走既有機制，不另闢儲存路徑）→ ③ agent 把檔案拉下來執行掃描 → ④ 掃完就刪 → ⑤ agent 磁碟不夠直接報錯。後續討論釐清後，「掃完就刪」的適用範圍是 agent 端 workspace（tenant 儲存空間上的壓縮包保留供重掃沿用，D29 定案）。

FR-058.6 的 scan 模式取源只有公開 Git repo URL（D19 的刻意最小化取捨），但實際客戶情境裡「源碼不在公開 repo」才是常態：私有 repo（客戶不願交 git 憑證）、源碼根本不在 git（委外交付源碼包、歷史版本快照）、稽核要特定一版（客戶打包當下狀態最直接）。上傳模式一次涵蓋三種情境，並部分涵蓋原列 scope 外的「私有 repo 認證」需求（客戶打包上傳即可，完全不用把 git 憑證交給平台）。

上傳時機：任務抽屜發起執行時，不是任務設定（決策者拍板）

初版設計曾把上傳欄位放在任務設定表單（param_schema 加 file 型欄位），決策者審後指出流程不對：上傳的壓縮包是「這一次要掃的東西」——特定時點的源碼快照，不該混進設定表單。放設定表單的兩個問題：① 每掃新版都要改設定再執行（兩段式繞路，且任務設定僅專案管理者可改，執行者不見得改得動）；② 語意錯位（設定表單是「這個任務怎麼掃」，源碼包該在「要執行了」的當下提供）。

修正後的分工：任務設定表單只留 scan_mode 的第三選項 upload；上傳動作發生在任務抽屜發起執行時——scan_mode=upload 的任務，執行對話框出現上傳區，首次執行必須上傳（無檔不給按執行），檔案參照隨「發起執行」請求送出。參照落點是任務綁定層的 sticky 狀態（供之後重掃沿用，D29），每筆執行的 scan_params 快照同時各存一份（承接「這筆掃的是哪個檔」的稽核回溯）。附帶兩個好處：孤兒檔視窗大幅縮小（上傳與執行是同一個動作）；FE 參數表單元件完全不用動（DetectionConfigField 不需要新型別分支）。

端到端流程

任務設定已存 scan_mode=upload（設定表單裡沒有檔案欄位）
使用者在任務抽屜發起執行：
  執行對話框出現上傳區——已有 sticky 檔案時顯示「目前檔案：xxx.zip（上傳於 M/D）」可直接沿用
  → （換新版時）POST /file/upload 上傳壓縮包（驗副檔名與大小上限）
     → upload_files_for_tenant() 存入 tenant 儲存空間 → 回 file uid
  → POST /detection-tools/jobs/<uid>/execute（body 帶 source_file.uid；沿用舊檔則不帶 body）
  → BE start_execution：帶新 uid 則覆寫綁定的 sticky 參照、不帶則沿用、首次無檔 400
     從 upload_files 權威取 file_name / size / sha256（不信 FE，D31）
     寫執行紀錄（scan_params 快照含 source_file: {uid, file_name}）
     ＋ agent_tasks（params 夾 _source_file 完整參照，含 size / sha256 / limits）
  → agent 心跳（既有 mTLS 通道）領回任務 payload（含 source_file 參照）
  → agent 取源段（本案新造）：
     步驟一：shutil.disk_usage 磁碟檢查——不足直接 fail「agent 磁碟空間不足」（D28）
     步驟二：GET /api/1.0/agents/files/<uid>（mTLS 串流下載；BE 依 storage_type 讀出、
             minio / remote_agent 後端串流轉發不落地）
     步驟三：sha256 對帳（防竄改）
     步驟四：標準庫安全解壓進 scan workspace（zipfile / tarfile filter="data"；
             累計大小 / 檔數超過 D27 限額即中止清理，D30）
  → 以下全複用 FR-058.6 scan 管線：sonar-scanner 掃描（_run_with_cancel）
     → 推客戶 SonarQube → 輪詢 CE → 拉 issues / 品質門檻 → 組自包含 HTML 報告
  → 報告上傳進證據池 → 回報 result（既有 mTLS 通道）
  → finally：刪 agent workspace（既有機制＋五路徑測試鎖約）
  → tenant 儲存上的壓縮包保留供重掃沿用（D29 定案，不做終態刪檔；清理機制列 follow-up）
  → FE 執行紀錄顯示檔名（非裸 UUID，D31）

流程上兩個關鍵設計點：① 磁碟檢查在下載之前——不是解壓失敗才發現，呼應本 arc 教訓「錯誤要在最早能發現的地方被發現」；錯誤分類為 agent 環境問題，不是掃描失敗。② BE relay 不落地——tenant 儲存為 minio / remote_agent 時，BE 用串流轉發，遵守 FR-039 不變式「雲端任何路徑不得把 binary 寫進雲端磁碟」。

FR-039 三條不變式對照（本設計不破壞任何一條）：agent 不連雲端 DB（檔案參照由心跳 payload 下發，agent 只打 BE 的 HTTP 端點）；雲端不落地 binary（串流轉發）；只有 agent 對外連出、無對內連入（下載是 agent 主動發起的出站請求，方向與 heartbeat / result 一致）。

任務層參數（param_schema v3）

版本策略照既有規範：INSERT 新 version=3 ＋ v2 is_current=FALSE，不原地 UPDATE。v3 的變更縮小到只有 scan_mode 一欄——不新增型別、不新增欄位，source_file 不進 param_schema（它是執行時輸入）。

執行時輸入與 params 形狀（T-7.1 / T-7.2 並行前必須凍結的 key 契約）

source_file 不進 param_schema（設定表單沒有檔案欄位），但參照落點在任務綁定層的 tool_params（sticky 狀態，供重掃沿用，D29）：execute body 帶新 uid 時覆寫、不帶時沿用現值。每筆執行的 scan_params 快照另存一份完整資訊（含檔名，稽核回溯用）。

// 任務綁定 tool_params（schema 欄位 + sticky 檔案參照；後者不是 schema 欄位、FE 設定表單看不到）
{
  "profile": "...",
  "scan_mode": "upload",
  "project_key_suffix": "release-1.2",
  "_source_file": { "uid": "<file-uid>" }   // sticky：execute 帶新 uid 覆寫、不帶沿用
}

// 每筆執行的 scan_params 快照（每筆各存一份；file_name 等由 BE 從 upload_files 權威取，D31）
{
  "...任務設定各欄...",
  "source_file": { "uid": "<file-uid>", "file_name": "my-project-src.zip" }
}

// compliance.agent_tasks.params（心跳下發給 agent 的 payload，BE 注入內部 key）
{
  "...同上...",
  "_task_uid": "...",               // 既有夾帶慣例
  "_credentials": { ... },          // 既有：心跳時當場解密注入
  "_source_file": {                 // 新：agent 取源所需的完整參照
    "uid": "<file-uid>",
    "file_name": "my-project-src.zip",
    "size_bytes": 52428800,
    "sha256": "<上傳時算好的摘要>",   // agent 下載後對帳防竄改
    "limits": { ... }               // D27：BE 設定的限額隨 payload 下發（與 credentials 下發同構）
  }
}

註：_ 前綴 key 回 FE 時由 _resolve_scan_params()（detection_orchestration_service.py:385-400）剝除——既有機制自動涵蓋 _source_file，FE 只看得到 source_file 的 {uid, file_name}：執行紀錄顯示檔名、不顯示裸 UUID（D31）。

端點契約草案

A. 執行端點改造（既有端點加 request body）

B. 新端點：agent 檔案下載

connector 實作要點（agent 端取源段）

• 磁碟檢查（D28）：_scan_workspace() 建目錄前 shutil.disk_usage("/tmp")，free < （壓縮包大小 × 12 ＋ 1GB）即 fail，係數與底值吃 payload 下發的 limits。
• 下載 client：比照 core/task_executor.py:148-153 _post() 的 httpx mTLS client 形狀加 _get_stream()，串流寫進 workspace，下載後 sha256 對帳。
• 安全解壓（D30）：zip 走 zipfile（extractall 內建路徑消毒）、tar 系走 tarfile filter="data"（Python 3.11.4+，agent 基底 python:3.11-slim 足夠）；兩家族共用約二十行額度檢查層（解壓前加總宣告總大小與檔數、超過 D27 限額即拒絕；逐檔解時看 cancel_event）。
• 取源之後：接進既有 scan 管線（取代 _clone_repo() 分支），_run_scanner() 起整段原樣沿用；workspace 清理走既有 finally: shutil.rmtree（五路徑測試鎖約，test/test_sonarqube_connector.py:1132-1180）。

自動派發與 upload 模式（D33，2026-08-01 驗收發現後追加）

專案規劃頁「開始執行任務」在發佈時會對 detection_tool 任務自動派第一次掃描（FR-056.5 #5：TaskExecutionService.start_task_execution → _auto_dispatch_detection_scans，app/grc/service/task_execution_service.py:90-133，冪等條件＝該任務查無任何 detection_executions 紀錄）。自動路徑不帶檔案，對 scan_mode=upload 的任務必然打中「首次無檔 400」（DETECTION_TOOLS_400005），且被批次派發的 try/except 吞掉只留 warning log——形成 PM 看到成功 toast、執行者無感、且每按一次就再失敗一次的靜默失敗迴圈。D33 定案：upload 任務在挑選階段就排除——get_detection_jobs_without_execution（infra/grc/repository/task_execution_query.py:134-159）的查詢加上排除 tool_params->>'scan_mode'='upload' 綁定的條件，upload 任務一律由執行者在任務抽屜上傳檔案後手動執行（抽屜已有完整前置擋門），pull / scan 自動派發不變。FE 同步在批次發佈 confirm 文案補一句提示。實作為 T-7.5（§5.12）。

掃描完成通知（D34，2026-08-01 驗收期間提出後追加）

現況兩缺陷：① 成功通知內容過簡——只有「專案 X 的檢測工具掃描已完成」一句，且只發 Email（平台其他通知已是 Email／Discord／Telegram 三管標準）；② 失敗完全不通知——on_scan_failed 只寫 detection_executions，使用者要自己去任務抽屜看才知道掃描失敗。

九項資料鏈：通知內容擴為九項——專案（升級走 round 鏈取代現行 ORDER BY id LIMIT 1）、控制項群組、控制項、AO、任務名稱、工具名稱、掃描設定、時間（started/finished）、成功或失敗；另把 handler 現成卻沒用的 evidence 參數用起來（報告檔名／份數，零額外查詢）。掃描設定複用 _resolve_scan_params() 現成兩層剝除（_ 前綴內部欄位＋secret envelope），profile UUID 轉譯成名稱。新查詢走 8 層 join 鏈（job→workflow_execution_control_mapping→round→project→extension→ssp→profile_imports→catalog_controls/groups/parts），加在 infra/detection_tools/repository/detection_job_notify_query.py（天然擴充點）新增 get_notify_context(job_uid) 一次 SQL 取齊。失敗路徑：on_scan_failed 補查 job/binding（抄 on_scan_succeeded :472-475 pattern）後發通知，含 error_message，收件人與成功相同（指派人＋專案 manager＋reviewer）。hosts（目標主機 IP）照出（D34 ③）。文案準備 HTML（email 表格）＋純文字（Discord/Telegram）兩版，i18n 6 個 msgid（兩語系 messages.po＋pybabel compile）。

兩坑（探查已實證，實作必守）：① catalog_controls.control_id 跨 catalog 不唯一（DEV 實測同 control_id 41 筆）——join 時必須帶 catalog_id = profile_imports.source_catalog_id 過濾，否則會撈到別的 catalog 的同名控制項；② AO 的 title 對 CMMC 全 NULL——用 title or prose or part_id fallback（job_export_query.py:145 前例）。

範圍外（本段不做，另案）：站內鈴鐺通知——平台無 notifications 表，屬平台級新能力；收件人 locale 切換——通知在 agent request context 發、Accept-Language 是 agent 的，一律 zh_Hant_TW（既有限制，非本案引入）。

無 schema migration、無 DI 變更（_profile_domain／_tool_domain／_notify_query 全已注入）。實作為 T-7.6（§5.12）。

known limitations 與 scope 外（v1 接受，出貨時要知道）

scope 外清單（本案不做，有需求另立案）：7z / rar 等其他格式（已收 .zip / .tar / .tar.gz / .tgz，再擴充等實際需求出現）；私有 repo 認證（上傳模式已部分涵蓋，真正的 git 憑證管理仍列 §4.7 後續強化）；上傳檔案掃毒 / 內容檢查（源碼包長存於 tenant 設定的儲存空間；平台任何環節都不執行壓縮包內容——agent 只解壓後交給 sonar-scanner 做靜態分析；BE relay 串流不落 BE 自身磁碟。防毒屬防毒層議題，有需求另議）；檔案清理機制（D29 ④ follow-up）；agent 容器資源限制（部署面議題，本案只做應用層磁碟檢查）；多檔上傳 / 資料夾上傳（一次任務一個壓縮包，多模組專案由客戶自行打成一包）。

5.1 依賴關係與排程

兩條真依賴（不可並行）

• FR-058.0 任務層敏感參數 → FR-058.1 ZAP：ZAP 要收「被掃網站的登入帳密」屬任務層敏感資料。.0 未完成，ZAP 登入後掃描只能把帳密明文存進 tool_params，等於白做一次要重改。
• FR-058.2 InSpec/CINC connector → FR-058.3 GCB：GCB 不另立引擎，跑的就是 .2 的 connector。.2 沒有，.3 沒東西可跑。
• FR-058.5 SonarQube 拉取 → FR-058.6 SonarQube 主動掃描：同一個工具的兩種模式（D17），.6 的 seed 是在 .5 的 param_schema 上加 scan_mode 與條件欄位、connector 是在 .5 的檔案內加分支，且步驟四（拉結果組報告）直接複用 .5 的程式碼。.5 沒有，.6 無處可加。

可同時跑的線（原三條；2026-07-31 追加線 D 後為四條）

橫向 FR-058.X：_TOOL_ID_TO_CODE 解耦（建議最先單獨做完）
     ↓
線 A：FR-058.0 敏感參數 → FR-058.1 ZAP
線 B：FR-058.2 InSpec/CINC → FR-058.3 GCB
線 C：FR-058.4 Nmap（獨立）
線 D：FR-058.5 SonarQube 拉取（T-5.1 → T-5.2 → T-5.3）
       → FR-058.6 SonarQube 主動掃描（T-6.1 → T-6.2 → T-6.3）
       → FR-058.7 SonarQube 上傳檔案掃描（T-7.1〜T-7.4，2026-08-01 追加；
         T-7.1 BE 與 T-7.2 agent 可並行，但並行前必須先凍結欄位 key 契約，見 §5.12）

線 D 的 UI 驗收合併（2026-07-31 裁示）：FR-058.5 的三支子任務程式碼皆已完成並 commit，但端到端 UI 驗收尚未做（DEV detection_executions 內 sonarqube 仍 0 筆，只有 probe 通過與容器內手動驗證）。決策者裁示「那版基本不能用了，先不測試，要等這版」——因此 T-5.3 的 UI 驗收併入 T-6.3 一起做，一輪走完 pull 與 scan 兩模式（詳見 §5.9 與 §6 第 11 項）。→ 2026-08-01 已完成：pull 與 scan 兩模式端到端通過（detection_executions sonarqube 2 筆皆 succeeded，171 上長出 Guidant-AI-soybean-ui 專案），本段保留為歷史紀錄。

兩個實務但書（排程建議，不是純技術描述）

1. 橫向的 ID 解耦建議最先單獨做完，再開三條線。 三條線都會動到 agent 這個共用 repo：各自新增一支 connector 檔案彼此不衝突，但 _TOOL_ID_TO_CODE 那個 factory 檔三條線都要改，同時開工會反覆衝突。ID 解耦工作量很小（改一個 factory + 派工 payload 加一個欄位），先做完三條線就不會撞同一個檔。
2. 線 A 與線 B 的第一棒技能需求不重疊：.0 是 BE + FE 的加解密與欄位渲染，.2 是 agent 端的 WinRM 連線與 profile 執行，適合分給不同 session 平行跑。

5.2 FR-058.X 橫向前置：_TOOL_ID_TO_CODE 解耦 — 依賴：無（所有工具的共同前置）

5.3 FR-058.0 任務層敏感參數（平台前置） — 依賴：無（可與 .2 / .4 並行）

5.4 FR-058.1 ZAP — 依賴：FR-058.0（+ 建議 FR-058.X 先完成）

5.5 FR-058.2 InSpec / CINC Auditor — 依賴：無（可與 .0 並行；建議 FR-058.X 先完成）

5.6 FR-058.3 GCB — 依賴：FR-058.2

驗收條件是「鏈路可運作」，不是「涵蓋多少規則」（D7 明確定案）。這不是 content 工程。

5.7 FR-058.4 Nmap — 依賴：無（完全獨立；建議 FR-058.X 先完成）

5.8 FR-058.5 SonarQube — 依賴：無（獨立；2026-07-31 追加）

詳細設計見 §4.6；決策見 D13–D16。pull-snapshot 型，不觸發掃描。

5.9 FR-058.6 SonarQube 主動掃描 — 依賴：FR-058.5（2026-07-31 追加；雛形）

詳細設計見 §4.7；決策見 D17–D24。定位是雛形——驗收標準是「端到端鏈路可運作」，不是「掃描品質有多好」或「語言涵蓋多廣」。

5.10 收尾（本案完成後）

5.11 後續優化（本案不做，全案驗收後另議）— InSpec 報告呈現

2026-07-31 決策者實地比對兩份報告樣本後的結論：本輪照現行 html2 出貨驗收，以下列為後續優化案，最後再做。

背景：實測比對結果

同一次掃描（dev-sec/linux-baseline，59 條控制）產出的兩份報告：

關鍵澄清：兩者原始資料完全相同。 SAF 的優勢不是「內容較多」，而是把已有資料加工成結論：① 控制層狀態彙總（原始 JSON 只有逐檢查點的 pass/fail，沒有「這條控制算不算過」）② impact 數字依 InSpec 慣例轉 severity 文字 ③ 圖表。SAF 報告可讀文字量看似多 4 倍，主因是同一條控制重複呈現三次（總表／明細／Result Details），非資料量差異。

亦查明：SAF 的 800-53 Controls & CCIs 欄位對本 profile 是空的——該欄需 profile 自身帶 tags / refs 標記，dev-sec baseline 未帶（實測 59 條控制 tags 與 refs 全空）。若改用 MITRE 維護的 STIG profile 才會有值。

待議項目

本輪不處理的理由：① 屬純呈現優化，現行 html2 已跨過「人可讀」門檻（控制編號／標題／描述／原始檢測碼齊全），非不可出貨狀態；且全案驗收進行中，變動 image 相依結構會讓「驗的是哪個版本」複雜化。② 非正確性缺陷——證據 HTML 內逐條控制狀態俱在，稽核員點開報告看得到真相；且牽動跨工具一致性，需一併定義。

5.12 FR-058.7 SonarQube 上傳檔案掃描 — 依賴：FR-058.6（2026-08-01 追加；✅ 全數完成，2026-08-01 決策者驗收通過）

詳細設計見 §4.8；決策見 D25–D34（D33 為 2026-08-01 驗收發現後追加，對應 T-7.5；D34 為同日驗收期間提出的通知加厚，對應 T-7.6）。T-7.1 與 T-7.2 可並行，但並行前必須先凍結欄位 key 契約——承 FR-058.6 教訓：並行實作各自取名會對不上，FR-058.6 是用契約表避開的，本案照辦。契約項：source_file / _source_file 的形狀（§4.8「執行時輸入與 params 形狀」）、下載端點路徑、sha256 header 名。

完成標記（2026-08-01 收尾補記，commit hash 皆經 git log 核實）：

• T-7.1 ✅ BE fc3cbbe5（＋404 修正 fdfbb091）——param_schema 實為 v4 非設計時寫的 v3：v3 已被同日稍早的 fr058-20（scan 選項標籤精簡，e78f1fd9）佔用，故 fr058-21 為 v3 下架＋INSERT v4；execute sticky 參照／agent 下載端點（可插拔 resolver 清單，後被 FR-059 1d9e43e4 復用）皆落地
• T-7.2 ✅ agent 13af0b9（bump 0.2.24 64e41d9）＋契約對齊修正 8a444d3（limits key 名稱＋X-Agent-Uid header，bump 0.2.25 fd2572f）——mTLS 串流下載＋sha256 對帳＋磁碟檢查＋兩格式家族安全解壓
• T-7.3 ✅ FE a424511——任務抽屜上傳原始碼壓縮包＋執行紀錄顯示檔名
• T-7.4 ✅ 端到端驗收通過（2026-08-01 決策者親驗）。四個未實測項裁示：磁碟不足模擬與解壓炸彈接受單元測試涵蓋、環境變數調限額不另實測、nginx client_max_body_size 列上版必驗項（DEV 直連 BE 驗不到）
• T-7.5 ✅ BE 648d3370（挑選查詢排除 upload 綁定）＋FE f6a26d8（批次發佈 confirm 提示）
• T-7.6 ✅ BE 85d9ca9f——get_notify_context() 8 層 join、九項內容＋報告檔名、失敗通知、三管道（Email／Discord／Telegram）、i18n 6 msgid

1. 平台敏感參數：任務參數含敏感欄位時，DB 內為密文、agent 收到明文、FE 執行紀錄與 system_logs 皆不出現該值。
2. ZAP：管理員設定 ZAP 服務位址與 API key → 測試連線通過 → 任務選 ZAP、填 target_url、選「登入後主動」並填測試帳密 → 開始執行 → HTML 報告進證據池（可下載；不可預覽為第一批出貨標準）、summary 有 alert 統計、報告內容顯示已進入登入後頁面。
3. ZAP 預設安全：任務未主動選擇時 scan_mode 為被動；選主動類時 FE 顯示攻擊流量警語。
4. InSpec / CINC：對 Linux（SSH）與 Windows（WinRM）各一台目標執行 → 每台一份人可讀 HTML 報告進證據池（html2 reporter；JSON 僅在記憶體算 summary 不上傳，見 §4.3「證據格式」）；其中一台連不上時另一台仍成功，且失敗主機被明確回報（非靜默假成功）。
5. GCB：以一份 Windows 最小 Demo profile 跑通 WinRM 連線 → 認證 → profile 執行 → 結果解析 → 證據上傳整條鏈路；更換 content 不需重建 agent image。
6. Nmap（2026-07-30 改案為 SSH 型）：設定 nmap 執行主機的 SSH 憑證 → 測試連線通過 → 任務選 Nmap 填掃描目標 → 開始執行 → 報告進證據池、summary 有開放埠統計；執行主機未安裝 nmap 時 probe() 回明確訊息（可辨識是「沒裝 nmap」而非「連不上」或「認證失敗」）。
   零憑證放行能力（T-4.1，平台級）：以宣告為零憑證的工具驗證可正常開始執行、不再誤回 DETECTION_TOOL_CONFIG_NOT_FOUND，且需憑證的既有工具（含改案後的 Nmap）檢查行為不變。
7. D11 解耦：agent 依派工夾帶的 code 取 connector；三環境 seed id 不一致時不再造成派工錯配。
8. 既有工具迴歸：OpenVAS 與 OpenSCAP 全鏈不受影響（factory 取 connector / 憑證檢查 / 多檔回收 / FE 動態渲染）。
9. 取消與逾時：四個新工具在執行中皆可被取消（cancel_event），且皆有 timeout 上限，不會無限等待。
10. SonarQube（2026-07-31 追加，FR-058.5）：管理員設定 base_url 與 user token → 測試連線通過（system/status + 帶認證的 authentication/validate）→ 任務選 SonarQube、填 project_key → 開始執行 → 對公司自有 SonarQube（192.168.50.171:9000，guidant-ai-backend / guidant-ai-fe 兩專案）拉取快照 → 自包含 HTML 報告進證據池（可下載、不可預覽）、summary 數字（bugs / vulnerabilities / code_smells / security_hotspots / quality_gate）與 server 畫面對數；專案尚無分析結果時回明確錯誤「請先於客戶端執行 sonar-scanner」。取消與單呼叫 timeout（60 秒）行為同第 9 項標準。
    ⚠️ 2026-07-31 裁示：本項 UI 驗收與第 11 項合併一次做完（程式碼已完成，detection_executions 內 sonarqube 仍 0 筆，見 §5.1 但書）。→ 2026-08-01 已完成驗收。
11. SonarQube 主動掃描（2026-07-31 追加，FR-058.6）：建任務時 scan_mode 預設為原始碼掃描（D24）→ 填公開 Git repo URL ＋ 專案代碼後綴 → 開始執行 → agent clone 源碼、跑 sonar-scanner、推上公司自有 SonarQube（192.168.50.171:9000）→ server 上出現 Guidant-AI-<後綴> 專案（D21 前綴生效）→ 輪詢 ce/task 至處理完成 → 自包含 HTML 報告進證據池、summary 有數字。
    同一輪一併驗完 pull 模式（補做第 10 項）：切 scan_mode 為讀取既有結果 → 條件欄位改顯示 project_key / branch（隱藏欄位不觸發必填驗證）→ 報告進池、summary 與 server 畫面對數。
    負向驗收：scan_mode 帶非法值時明確失敗不靜默降級（絕不退回 pull 給出舊快照）；掃描逾時與佇列逾時訊息可區分；任務失敗或取消後 agent 容器內 tmp 目錄已清除（docker exec 確認無殘留源碼）。
    執行紀錄：scan 模式下主要參數區顯示 Git repo URL（非後綴），pull 模式顯示 project_key。