Guidant AI v1.13.0 Release Note

0. 發版前回歸 gate

本版回歸 gate（site-regression Core 檔位）經決策者裁示以手動驗收為準、豁免自動 gate——FR-058 全 arc 與 FR-059 皆於 DEV 端到端手測通過，三環境（DEV/STG/POC）已部署對應 BE/FE build 與 agent 0.2.27，決策者逐項驗收通過後放行發版。

1. 概述

v1.13.0 是 FR-056 檢測工具整合平台（v1.11.0）→ FR-057 OpenSCAP（v1.12.0）之後的第三波、也是規模最大的一波：在既有平台上一次接入五款檢測工具，並把「掃描依據（profile / content）」從人工版控鏈搬進後台管理頁。

自 v1.12.0 起，平台工具目錄從 2 款（OpenVAS / OpenSCAP）擴充到 7 款：

OpenVAS（弱點掃描，既有）· OpenSCAP（組態合規，v1.12.0）· OWASP ZAP（DAST 動態應用弱點）· CINC Auditor（InSpec 相容組態稽核，SSH + WinRM）· GCB（政府組態基準 TWGCB，復用 CINC 引擎）· Nmap（網路埠 / 服務掃描）· SonarQube（原始碼靜態品質 / 安全，pull / scan / upload 三種模式）

平台側同步補上兩項結構性能力：任務層敏感參數加密（FR-058.0，任何工具的敏感任務參數落庫即 Fernet 加密）與 _TOOL_ID_TO_CODE 解耦（派工 payload 夾帶 tool code，消除三環境 seed id 錯位導致靜默跑錯工具的風險）。

FR-059 檢測工具 Profile / Content 庫則把「新增一支掃描 profile」從「進 repo → 人工 rsync 到每台 agent → 寫 migration 改 param_schema 選項 → 逐環境套」的四步人工鏈，收斂為後台一頁管理：agent 只需升級一次學會「拉檔 + cache + sha256 對帳」，之後 content 的新增 / 改版 / 停用全在後台完成。

⚠️ 定位澄清：本版是 FR-058 全系列（含 ZAP / CINC Auditor / Nmap / GCB 四款工具）首次隨版發布——上一版 v1.12.0 的 release note 只涵蓋 FR-057 OpenSCAP，FR-058 全 arc 與 FR-059 的所有 commit 皆在 v1.12.0 定版之後產生、此前從未進版。

2. 重點新功能

2.1 平台能力強化（FR-058.0 / 橫向項）

• 任務層敏感參數加密（FR-058.0，D1）：param_schema 支援 secret: true 宣告——BE 寫入 tool_params 前以 Fernet 加密、派工時解密下發，FE 執行紀錄與稽核 log 一律剝除敏感值。這是平台上此前唯一的結構性缺口（租戶層憑證已加密，但任務層敏感參數如 ZAP 登入密碼、SonarQube token 仍明文），本版補齊。
• _TOOL_ID_TO_CODE 解耦（橫向項，D11）：派工 payload 直接夾帶 detection tool code，agent 不再靠固定 id 對照映射工具——消除「三環境 seed id 錯一位就靜默跑錯工具」這類最難察覺的環境債。
• 平台宣告欄位：detection_tools 新增 requires_credentials（零憑證工具如 Nmap 不再被 start_execution 誤擋）與 requires_target_host（FE 對「是否要輸入目標主機」的判斷從硬編 connection_type 解耦），並補 credential_group（互斥憑證組別）schema。

2.2 OWASP ZAP — 動態應用弱點掃描（FR-058.1）

• DAST 型工具：對執行中的 Web 應用發動動態掃描，補齊平台的「應用層弱點」維度（既有 OpenVAS 為主機層）。走 API / daemon 形態、ZAP server 由客戶自備（D3）。
• 三種 scan_mode（被動 / 主動 / 完整），預設被動並對主動 / 完整模式加攻擊流量警語（D2）——因主動掃描會對目標送真實攻擊流量。
• 雙格式證據：PDF 報告上傳 + JSON 僅記憶體解析（不落地），對齊 zaproxy 0.6.0 / 2.17.0 的警報去重語意。
• 登入後掃描：支援傳統表單登入四欄（條件必填，錯誤從 agent 執行期提前到 FE 表單驗證）；SPA（單頁式應用）登入掃描列為後續案（見 §10 CM-984）。

2.3 CINC Auditor — 組態合規稽核（FR-058.2）

• 選 CINC Auditor 而非官方 InSpec binary（Apache 2.0 授權，非商業 binary；D5）——功能等價、授權乾淨。
• SSH + WinRM 雙 transport 一次到位（D6），涵蓋 Linux 與 Windows 目標主機。
• 吸收並結案 Notion CM-953（異質 OS 檢測）：OpenSCAP 官方已棄 Windows 支援、實證不可行，改由 CINC Auditor 承接 Windows 組態稽核。
• 證據改為人可讀 HTML 報告（agent 0.2.17）。

2.4 GCB — 政府組態基準（FR-058.3）

• 不另立引擎，複用 FR-058.2 的 CINC connector，content 格式統一為 InSpec profile（D8）。
• 本案範圍＝引擎鏈路可運作 + 一份 Windows 最小 Demo profile（驗收＝鏈路可運作而非規則覆蓋量）；content 外部載入接口本案即留（D7），為 FR-059 的 content 後台管理鋪路。
• 政府組態基準（TWGCB）content 隨 FR-059 以 8 支公用版 profile 正式上架（見 §2.8）。

2.5 Nmap — 網路埠 / 服務掃描（FR-058.4）

• 原定 CLI 型態，D9 改案為 SSH 型（NPSL 授權不 bundle 進 image，改由 agent SSH 登入目標主機執行目標自帶的 nmap）。
• 平台首個「零憑證可選」工具的使用者——連帶推動 §2.1 的 requires_credentials 宣告欄位（解除零憑證工具被 start_execution 誤擋）。
• FE 摘要卡分開顯示「執行主機」與「掃描目標」（Nmap 兩者不同，不再混標）。

2.6 SonarQube — 原始碼靜態品質 / 安全（FR-058.5 / .6 / .7，三種模式）

SonarQube 是同一款工具、同一張工具卡，靠 scan_mode 分流三種取源模式（D17 ZAP 式共存，非拆三張卡；三模式共用同一組憑證 config_field_schema）：

• pull 拉取快照模式（FR-058.5，D13–D16）：平台首個「拉取快照」型工具。SonarQube Server 沒有任何觸發掃描的 Web API，故 pull 模式只讀取客戶端 CI / sonar-scanner 已推上 server 的既有分析結果，組成自包含 HTML 證據（Community Build 無報告匯出，自組為必做項）。憑證 base_url + user token（squ_；sqp_ / sqa_ analysis token 不能讀）；issue 解析 impacts[]（MQR 語意）優先、fallback 舊 type + severity，相容 9.9 LTS ~ 2026.x LTA。適用「客戶已有成熟 CI 天天在跑」的場景，零額外掃描負擔。
• scan 主動掃描模式（FR-058.6，D17–D24）：平台真的發動一次掃描——agent 端內建 sonar-scanner（打進 image，自帶 JRE 不裝 JDK，D20），clone 公開 Git repo（D19）到磁碟型 /tmp（不可用 /dev/shm 記憶體型，D22）、跑掃描推上客戶 SonarQube、輪詢 ce/task 直到分析完成、再複用 pull 模式的拉取 / 報告程式碼。只做 A 類純源碼 7 語言（Python / JS / TS / Go / PHP / Ruby / Kotlin，不需編譯產出；D18）。projectKey 一律加 Guidant-AI- 前綴（D21）。scan_mode 預設值＝scan（D24，與 ZAP D2 預設被動方向刻意相反——量級不同：ZAP 是對外部系統送攻擊流量、本案是在客戶自有 SonarQube 建一筆可刪紀錄；因預設指向不可回復側，setup_guide 改寫與 UI 明顯提示列為必做配套）。
• upload 上傳檔案掃描模式（FR-058.7，D25–D34）：scan 模式的取源擴充（scan_mode 多一個 upload 選項，後段掃描管線全複用）。使用者在任務抽屜發起執行時上傳原始碼壓縮包（非任務設定表單，D26）→ 落地租戶儲存空間 → agent 主動 mTLS 拉取（新端點 GET /api/1.0/agents/files/<uid>，D25）→ sha256 對帳 → 標準庫安全解壓（zipfile / tarfile filter="data"，D30）→ 進既有掃描管線。收 .zip / .tar / .tar.gz / .tgz 四格式，上傳 100MB / 解壓後 500MB / 50,000 檔（皆環境變數可覆寫，D27）；下載前 shutil.disk_usage 磁碟預檢（D28）。壓縮包保留供重掃沿用、歷史版本不刪（D29）。

兩項驗收期關鍵修正（併入本版）：

• T-7.5 upload 任務不進自動派發（D33）：專案規劃頁「開始執行任務」的自動派發不帶檔案，對 scan_mode=upload 任務必打中「首次無檔 400」、且被批次 try/except 吞掉，形成「PM 看到成功 toast、執行者無感的靜默失敗」，並因失敗不產生執行紀錄使冪等條件永遠成立、每按一次再失敗一次。修在挑選查詢階段（get_detection_jobs_without_execution）就排除 upload 綁定——upload 任務一律由執行者在任務抽屜手動執行；pull / scan 自動派發行為不變。
• T-7.6 檢測掃描通知加厚（九項內容 + 失敗通知 + 三管道）（D34）：
  • 九項內容：專案（升級走 round 鏈）／控制項群組／控制項／AO／任務名稱／工具名稱／掃描設定／時間（started + finished）／成功或失敗，並把現成未用的 evidence 參數用起來附報告檔名與份數。
  • 失敗也通知：現況失敗完全不通知（只寫 detection_executions），修正後 on_scan_failed 補查 job / binding 後發通知（含 error_message），收件人與成功通知相同（指派人 + 專案 manager + reviewer）——失敗更需要管理層知道。
  • 三管道：Email（既有）＋補齊 Discord / Telegram，文案 HTML + 純文字兩版，i18n 6 個 msgid。

2.7 SonarQube 掃描的兩個官方坑（已在實作處理）

• 沒有 dry-run：每次 scan 都是對客戶 server 寫入、專案不存在會自動建立（故 D21 前綴 + D24 事前告知為必做）。
• 掃完 ≠ 能讀：EXECUTION SUCCESS 只代表上傳完成，須解析 report-task.txt 取 ceTaskId、輪詢 ce/task 脫離 IN_PROGRESS 才拉得到當次結果（CE 顯示的處理時間不含排隊、不能當 timeout 依據）。

2.8 FR-059 檢測工具 Profile / Content 庫（掃描設定檔後台管理）

• 定位：把掃描依據（profile / content）從「BE repo 版控 + 人工 rsync + migration seed 選項」四步人工鏈，搬進後台管理頁。系統管理下新增獨立頁「掃描設定檔管理」（非塞進工具管理頁 tab，D3）。第一期只做形態 A（agent 本機讀取型），涵蓋 CINC / InSpec 與 GCB 兩工具。
• 六個管理動作：列表（分頁，公版 + 租戶自有合併查詢）／menu 下拉（任務抽屜用，按 detection_tool_id 過濾）／上傳（file，走驗證管線）或登記（url，只登記字串）／版更（INSERT 新 version + 舊版 is_current=FALSE）／fork + 複製到另一工具／停用（軟刪，歷史執行紀錄仍可回溯）。
• 三層防禦守門：① Route capability（四個 capability 全 is_platform=false，比照 flow_template 平掛）；② Service 層 guard（scope=='SYSTEM' 非平台管理員則 Forbidden）；③ DB RLS 四段 policy 兜底。
• 上傳驗證管線（全 repo 首個壓縮檔安全處理實作）：格式偵測（副檔名白名單 + magic number 雙重確認）→ 大小上限（50MB，Content-Length 預檢 + 實讀累計）→ 逐 entry 防 zip slip（路徑正規化、tar symlink / hardlink 拒收）→ 防 zip bomb（entry 數 + 解壓總量 + 壓縮比上限）→ 結構驗證（頂層或一層內須有 inspec.yml，只驗結構不驗語意，D8）→ sha256 計算 → 存儲。全程 streaming、不落地解壓。收 zip / tar / tar.gz / tgz 四格式（D4）。
• 公用版 seed：8 支 TWGCB（file 型，綁 gcb） ＋ 2 條 dev-sec linux-baseline / windows-baseline（url 型，綁 inspec） 搬遷成 SYSTEM 公用版（P3 / D7），確保上線第一天下拉零回歸；TWGCB 走與使用者相同的上傳管線打包（非直插 DB）。
• 下拉動態化（options_source）：param_schema 的 profile 欄位加宣告 "options_source": "profile_library"（type 仍 select_or_text），FE 據此改呼叫 profile menu API 動態組 options，不再讀死的靜態陣列；手填能力保留（庫內 file / 庫內 url / 現場手填三來源共存）。未來新工具接庫 FE 零改。
• profile_ref 授權 resolver：復用 FR-058.7 建立的 GET /api/1.0/agents/files/<uid> 通道；resolver 做成可插拔介面——端點逐一詢問 _FILE_ACCESS_RESOLVERS 清單，source_file（FR-058.7）與 profile_ref（FR-059）各自 append 一個 resolver（D6，兩案唯一直接技術契約）。
• agent 端：學會拉檔 + cache（/data/content/cache/<uid>/v<version>/）+ sha256 對帳，統一安全解壓成目錄餵給 cinc-auditor（不按格式分支）。

3. 重要修補

• 檢測工具下拉漏判 enabled：任務設定的檢測工具下拉未過濾停用工具——BE 補 query entity → WHERE 回歸測試、FE menuStore 補第二道防線。
• OpenSCAP content_path 移入進階摺疊區（fr058-22，方向 A）：非必填的進階參數不再佔用主表單版面；FE 支援 group="advanced" 進階摺疊區。
• detection-profile-manage 選單 pid 硬編 bug（fr059-4）：選單父節點 id 硬編錯誤，三環境已修並套用。
• i18n 部署流程修復（I18N_LOCAL.md）：2026-08-01 STG / POC 上版時，通知 Subject 因部署環境就地跑 pybabel extract/update（STG）或漏 compile（POC）而整條未翻譯——本版把「部署環境只 compile、絕不 extract / update」的鐵則與修復 SOP 固化進 I18N_LOCAL.md，防範文件流程債重演。

4. Breaking Changes

無破壞性變更，全部為新增能力：

• 五款工具皆以 detection_tools 新 seed 進工具目錄，OpenVAS / OpenSCAP 既有全鏈（factory 映射、回收路徑、FE 動態渲染）迴歸不受影響。
• SonarQube 三模式共用同一張工具卡與憑證 schema，scan_mode 為新增分流欄位。
• FR-059 profile 庫的 options_source 為 param_schema 的新增宣告，未接庫的工具下拉行為不變。
• 無新增任務狀態、無既有 API 行為變更。

5. DB Migration（27 支）

按檔名日期序套用即可，一律 psql --single-transaction -v ON_ERROR_STOP=1 -f <檔> 以 cmmgr 套用。DEV / STG / POC 三環境已全數套用（schema_migrations 記帳）。

FR-058 檢測工具擴充（fr058-1 ~ fr058-22）

⚠️ seed 順序不可變動：agent factory 已由 _TOOL_ID_TO_CODE 解耦（派工帶 tool code），但工具目錄 seed 順序仍應照檔名序套用。SonarQube 為 UPDATE 既有 id=3 佔位列——照 ON CONFLICT DO NOTHING 會靜默跳過。

FR-059 Profile / Content 庫（fr059-1 ~ fr059-4，含兩支 fr059-3）

⚠️ fr059-3-param-schema 必須在搬遷 seed 之後套用（否則下拉先動態化、庫內尚無公用版 profile 會短暫空選項）。完整部署順序見 FR-059 deploy-runbook.md。

6. 相依套件版本

• 本版無 jedi-* 套件版本變動（沿用 v1.12.0 的 jedi-common 0.0.30 等 pin；pyproject.toml 相依區段未動）。
• 無新增必要環境變數：檢測工具憑證加密沿用 FR-056 起的 DETECTION_TOOL_ENCRYPTION_KEY；任務層敏感參數（FR-058.0）與租戶憑證共用同一 Fernet 加密鏈。憑證值請查 .env 或部署文件。

7. Agent 版本（0.2.11 → 0.2.27）

部署須升級至 0.2.27（中間版直接跳最新）。三環境（DEV/STG/POC，agent 123 等）現為 0.2.27。

8. 部署順序與注意事項

1. DB migration：依 §5 順序套用（三環境已完成）。FR-059 的 fr059-3-param-schema 必須在搬遷 seed 之後。
2. BE：git pull → 重啟（main_app.py）。確認 .env 既有 DETECTION_TOOL_ENCRYPTION_KEY（v1.11.0 起必要）。
3. i18n：部署環境只 pybabel compile -d config/translations，絕不 extract / update（見 §3 與 I18N_LOCAL.md），compile 後重啟 BE。
4. FE：同版 build 部署。
5. Agent 升級至 0.2.27：⚠️ 跨平台 build（Mac arm64 → amd64 主機）須帶 --platform linux/amd64，出貨前 docker inspect 確認架構。FR-059 需先建 cache 掛載點（/data/content/cache）。AGENT_VERSION pin 已於 STG / POC 部署時解除（compose 改 ${AGENT_VERSION:-}），不再需要每次手動同步版本字串。
6. nginx client_max_body_size：⚠️ 新環境部署必設 client_max_body_size ≥ 上傳上限（本版 SonarQube upload 與 FR-059 profile 上傳皆走上傳鏈路，nginx 預設 1MB 會擋掉；STG / POC 已由決策者設 500M）。DEV 直連 BE 驗不到這一層，故列為上版必驗項。
7. 掃描目標主機準備：CINC Auditor / GCB / Nmap / OpenSCAP 的目標主機一次性準備（稽核帳號 / SSH 公鑰 / 工具存在性）見各工具設定頁 setup_guide。SonarQube scan 模式的 sonar-scanner 已打進 agent image，無需另備。

9. 已知限制與 follow-up

已知限制

• SonarQube scan 模式只做 A 類純源碼 7 語言（Python / JS / TS / Go / PHP / Ruby / Kotlin）：Java 需編譯產出、C# / VB.NET 技術上只能走 pull 模式（送進 scan 為靜默淺掃，故明確排除）。
• SonarQube Community Build 首次分析無品質門檻比較基準期：new_* 指標需前一版可比，首次分析 conditions 為空屬正常（顯示層已修為「條件為空時整塊不輸出」，不再謊稱客戶未設定）。
• agent 容器無資源配額上限（R2）：scan / upload 模式僅做逾時上限與磁碟預檢，記憶體 / 磁碟硬配額本版不做。

Follow-up

• CM-1030 _credentials at-rest 加密（下一輪）：FR-056 既有的租戶憑證派工快照（compliance.agent_tasks.params 內）目前仍明文存 DB（非歷史遺留、仍持續產生新資料）。方向已定：複用 common/util/detection_secret_params.py 現成 envelope 改存加密、心跳組裝時才解；會動派工路徑，四款工具（ZAP / CINC / Nmap / GCB）都需回歸。本版不含此改動，列下一輪處理。
• CM-1029 環境債（已結案）：本版部署時同批處理的環境債——STG / POC 補齊 fr058 / fr059 全部 migration、agent 升至 0.2.27、SonarQube coming_soon → available、AGENT_VERSION 舊 pin 解除、nginx client_max_body_size 設定——已於 2026-08-01 隨發版完成並結案。
• CM-992 GCB content 待補對照 + transport：GCB / Linux 組態基準的自動化檢查對照（原估「幾乎零自動化」經調研更正為約 45% 可自動化），剩餘項待補；「後台 content 管理機制」部分已由本版 FR-059 承接，CM-992 其餘範圍待排程。
• CM-984 ZAP SPA 登入掃描：ZAP 登入後掃描第一批只支援傳統表單登入，SPA（單頁式應用）登入需 json-based 認證 + script-based session management，列後續另案。
• CM-985 檢測報告呈現優化：全案驗收後才做，決策者裁示不納入 SonarQube（為 InSpec / GCB 等既有工具的報告呈現優化）。
• FR-059 孤兒檔清理：upload / profile 壓縮包歷史版本不刪（供重掃沿用），孤兒檔清理機制列 v1 follow-up。

10. 完整 changelog 索引

三 repo git log v1.12.0..HEAD（BE 83 / FE 20 / agent 39 commits）。主要脈絡：

• 平台橫向 + FR-058.0：5151fb2c（派工帶 tool code + 任務層敏感參數加密鏈）、b9520f7b / 9a15db96（requires_credentials / requires_target_host 宣告欄位）
• FR-058.1 ZAP：8f579c50（seed）、2d14ccb7（登入條件必填）、f8b0a370 / 2581b4f6（SPA 限制）
• FR-058.2 CINC Auditor：4d5226fa（seed）、ac1b7da0（改名 CINC）、1d23082b（互斥憑證組別）
• FR-058.3 GCB：04bdc821 / 536867c7（seed + Demo profile）、a8046a1e（8 支 TWGCB）、f2f61e70（TWGCB-01-011 完整基準）
• FR-058.4 Nmap：16ae4ff0（seed）、8ac863cf（D9 SSH 改案）
• FR-058.5/.6/.7 SonarQube：7b9d831e（.5 seed）、e020a3b9（.6 scan 模式）、fc3cbbe5（.7 upload）、648d3370（T-7.5 不自動派發）、85d9ca9f（T-7.6 通知加厚）
• FR-059 Profile 庫：9c95ae08（表 / RLS / ORM / repo）、e1d50929（六動作 API）、854b0209（上傳驗證管線）、355de397（8 TWGCB + 2 dev-sec seed）、2b1879ab（options_source 動態化）、1d9e43e4（profile_ref resolver）、43b02c15（選單登記）、950cfaed（選單 pid 修正）
• 收尾修補：0f261b76（OpenSCAP content_path 進階區）、f913f0d4（下拉 enabled 回歸測試）、d9bc1b7c / 382147ed（使用手冊納入 SPEC html 站）

11. 相關文件索引

• FR-058 設計文件（D1–D34 全決策）：docs/features/FR-058-2607-detection-tools-expansion/design.md
• FR-058 arc 收尾 SUMMARY（含 .5/.6/.7 與上版清單）：docs/features/FR-058-2607-detection-tools-expansion/handoff/2026-07-31-fr058-arc-SUMMARY.md
• FR-058 討論稿：discussion.html（四工具母案）／discussion-sonarqube-scan-mode.html（.6）／discussion-fr058.7-upload-scan.html（.7）
• FR-059 設計文件（P1–P7 + D1–D10）：docs/features/FR-059-2608-detection-profile-library/design.md
• FR-059 部署手冊（自包含）：docs/features/FR-059-2608-detection-profile-library/deploy-runbook.md
• 使用手冊（本版納入 SPEC html 站）：docs/user-manual/detection-tools-guide.md、docs/user-manual/scan-profile-guide.md
• 功能頁面 spec：docs/specs/current/ — system-admin/tool-plugin-manage.md、system-admin/detection-profile-manage.md、project-management/project-task-edit.md、audit-execution/my-tasks.md
• i18n 部署鐵則：I18N_LOCAL.md
• Notion cases：CM-957 ~ CM-1029（FR-058 / FR-059 母子卡連號；CM-1030 為下一輪 follow-up）