Guidant AI v1.11.0 Release Note

1. 概述

v1.11.0 的主軸是 FR-056 檢測工具整合平台：讓客戶的資安檢測工具（首發 OpenVAS）從「人工掃描、人工下載報告、人工上傳證據」變成一條全自動鏈路——

規劃頁指定任務用哪個檢測工具 → 開始執行時雲端派工給客戶內網 Agent → Agent 調度 OpenVAS 實際掃描 → 報告 PDF 與發現統計自動寫回成該任務的證據 → 通知任務負責人 → 依完成模式決定是否自動結案。

架構上完全複用 FR-039 既有的 mTLS Agent 認證與心跳通道（不新增對外連線面），Agent 以 capabilities 宣告是否具備 detection_scan 能力，雲端派工時只挑有該能力的 Agent。connector 層抽象化，Nessus / SonarQube 等其他工具可依同一介面擴充（本版僅完整實作與驗收 OpenVAS）。

本版另含 2026-07-27 一整天手測期挖出並修復的 13 項問題（見 §3），user 已於當日親測整條鏈路（同批多任務派工零撞名、auto/manual 雙完成模式、PDF 證據＋發現統計、取消機制真中斷）全數通過。

2. 重點新功能：FR-056 檢測工具整合平台

2.1 檢測工具設定（FR-056.1）

「檢測工具管理」頁從純前端假資料的佔位頁，改為接真後端的完整 CRUD：

• 租戶可自行設定檢測工具連線資訊（host / 帳密 / 參數），憑證走 app 層加密存 DB，使用獨立的 DETECTION_TOOL_ENCRYPTION_KEY（與 Google Drive token 金鑰分離，洩漏影響面隔離）
• 設定卡片上提供「測試連線」，由雲端經 mTLS 推給 Agent 實際探測目標工具，回傳可用與否及失敗原因
• 掃描參數表單由後端 param schema 驅動動態渲染，新增工具或調整欄位不需改前端

2.2 任務類型擴充（FR-056.2）

任務類型新增「檢測工具執行」（detection_tool），與既有 general / survey 並列：

• 專案規劃頁可為任務綁定「用哪個工具、哪份租戶設定、掃描參數」（OpenVAS 首發參數：掃描目標 hosts 必填；timeout / Scan Config / Scanner / Port List 選填）
• 新增完成模式 flag：manual（預設，維持既有人工按完成的行為）／ auto（掃描成功即自動結案）

2.3 Agent 掃描執行能力（FR-056.3）

• remote_agents 新增 capabilities 能力清單欄位；具 detection_scan 的 Agent 才會被派掃描工單
• 新增 agent_tasks 派工單表與狀態機（pending → dispatched → running → succeeded / failed / cancelled），非法與終態轉換一律拒絕
• 派工單搭既有心跳通道下發，Agent 領取後 ack，執行完回報結果
• Agent 端支援真中斷：重新執行時對進行中的舊掃描呼叫 stop_task 實際終止，再派新工單

2.4 執行編排與轉證據（FR-056.4）

• 任務「開始執行」時（含專案規劃頁發佈流程）自動派發首次掃描
• 掃描完成後，報告 PDF 自動寫入為該任務證據（來源標記 DETECTION_TOOL），另解析 XML 產出發現項目統計（XML 本身不上傳，避免使用者看不懂的格式進證據池）
• 完成後發信通知任務負責人；依完成模式決定是否自動將任務標記完成
• 任務抽屜新增「執行紀錄」區塊：歷次執行狀態、時間、報告下載，可收合（running / failed 預設展開）

3. 手測期修正（2026-07-27，Notion CM-928~934）

阻斷級（整條鏈路卡死）

• 心跳信封層級解析錯位：Agent 端 pending_tasks 永遠讀不到派工單——真正讓整條鏈路無法運作的根因。
• 測試連線架構死路（CM-929）：原設計由 BE 直連 OpenVAS，客戶內網不可達 → 改為雲端經 mTLS 推給 Agent 執行探測，移除 BE 側 probe。
• 派工憑證永遠是空值：tenant_config_id 未寫入派工單 → 改以 (tenant_id, detection_tool_id) fallback 反查憑證設定。
• 建立掃描目標必炸 400：GVMd create_target 缺 port_list_id → 補預設值並開放參數覆寫（migration #11 同步擴充 param schema）。
• 掃描目標字串被拆成亂碼：hosts 字串被誤當 list 逐字元拆解 → connector 邊界正規化。

安全

• API log 記錄明文憑證：心跳 API log 記下了解密後的憑證，違反「解密憑證不落地」原則 → middleware 對敏感欄位統一遮罩。

功能與體驗

• 同批多任務派工撞名（CM-934）：OpenVAS target/task 以秒級 timestamp 命名，同秒派工必撞 Target exists already → 改用 Agent task_uid（天然唯一）命名。
• 重新執行疊出並行掃描（CM-931）：無確認亦不中斷舊掃描 → 加確認框 ＋ 真中斷後才派新工單。
• 報告格式使用者看不懂、統計永遠空（CM-932）：證據改用 PDF，統計另解析 XML。
• 執行紀錄佔版面 / 排序錯亂（CM-930）：加可收合 toggle 與智慧預設，排序改由 BE repo 層 ORDER BY started_at DESC, id DESC。
• 輪次篩選未連動專案篩選（CM-933）：任務管理頁未選專案時輪次下拉可誤選 → 未選專案時 disable；同案順修 PrimeVue v-tooltip 直接掛 Dropdown 導致頁面崩潰。
• Agent 在線狀態與健康檢查互相打架（CM-928）：兩個燈號各自渲染（心跳快取 15 分鐘寬限 vs 即時探測），改為健康檢查完成後以其結果為準。
• Agent 升級要空等一輪心跳：改「先跳再等」，啟動即回報版號。

4. 其他修補

• 內建流程範本開放平台管理員維護（CM-906）：原內建範本無編輯入口，改為平台管理員可維護（BE 權限 + FE 入口）。
• api_log after_request response fallback：非 dict 回應改回空字串，避免序列化例外。
• 轉證據 handler 檔名／content_type：沿用 Agent 回傳值，不再寫死 xml。

5. Breaking Changes

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

• 「檢測工具管理」頁從硬編碼展示資料改為真實 CRUD——舊頁面本無持久化資料，無遷移需求。
• 任務類型新增 detection_tool，未新增任何任務狀態（沿用既有 JobStatus）。
• 完成模式預設 manual，既有任務完成邏輯不受影響。

6. DB Migration（11 支）

⚠️ 套用順序須按依賴關係，非檔名字母序（jedt-fix-rls-delimiter 依賴 job-execution-detection-tools 先建表）。一律 psql --single-transaction -v ON_ERROR_STOP=1。

現況：DEV / STG / POC 三環境已全數套用並驗證一致（各 11 筆 schema_migrations 記帳）。

7. 相依套件版本

無變動。

8. 部署順序與注意事項

1. BE .env 先補環境變數 DETECTION_TOOL_ENCRYPTION_KEY（Fernet key，值請查部署文件或 .env）——缺少會讓心跳處理與檢測工具設定頁直接 500，STG / POC 上線時皆曾踩到。同時確認既有 DRIVE_TOKEN_ENCRYPTION_KEY 存在。
2. DB migration：依 §6 順序套用（三環境已完成）。
3. BE：git pull → 重啟（main_app.py）。
4. FE：同版 build 部署。
5. Agent 升級至 0.2.8：image 已更名為 guidant-ai-agent，部署機 .env 的 AGENT_IMAGE 須改 guidant-ai-agent:0.2.8（沿用舊名 evidence-agent 會誤向 Docker Hub pull 而 access denied）。舊 compose 部署機標準重啟式：docker compose --profile full up -d --remove-orphans --force-recreate（不帶 --profile full 會誤砍 nginx；永遠不加 -v）。
6. 既有 Agent 補 capabilities：舊資料的 compliance.remote_agents.capabilities 僅含 file_storage，需補 detection_scan 否則派工挑不到該 Agent（CM-937 自報機制上線後可免此步）。

9. 已知 follow-up

• CM-936：Agent 管理頁隱藏多餘的「類型」欄位（純 FE）。
• CM-937（FR-056.9）：Agent 心跳自報 capabilities（取代手動改 DB）、使用手冊補環境開通 checklist 章、detection_probe_no_agent 錯誤文案優化。
• 未開卡：main_app.py 加 load_dotenv()（方向已拍板，解決 .bashrc 環境變數服務讀不到的部署坑）、OpenVAS target/task 殘留清理策略、Agent 對外暴露防火牆收緊。
• 其他 connector（Nessus / SonarQube）：架構已預留，本輪僅實作與驗收 OpenVAS。
• remote_agents.capabilities 目前無管理 UI，僅能改 DB。
• 失敗情境（如填不存在的 IP）未逐項手測，理論上由既有錯誤處理涵蓋。

10. 相關文件索引

• FR-056 設計與實作計畫：docs/features/FR-056-2607-detection-tool-integration/design.md、implementation-plan.md
• arc 收官 SUMMARY：docs/features/FR-056-2607-detection-tool-integration/handoff/2026-07-27-fr056-manual-test-arc-SUMMARY.md
• 使用手冊：docs/features/FR-056-2607-detection-tool-integration/user-manual.html
• 功能頁面 spec（本版更新 6 頁）：docs/specs/current/ — evidence/tool-plugin-manage.md、evidence/remote-agent-manage.md、evidence/_overview.md、audit-execution/my-tasks.md、project-planning.md、project-task-edit.md
• Notion cases：CM-906、CM-927 ~ CM-935