Guidant AI v1.12.0 Release Note

1. 概述

v1.12.0 的主軸是 FR-057 OpenSCAP 掃描工具接入：在 v1.11.0 上線的檢測工具整合平台（FR-056）上接入第二個工具 OpenSCAP——開源組態合規稽核工具（CIS / STIG benchmark），讓客戶在既有的弱點掃描（OpenVAS）之外，多了組態合規稽核能力。

架構上，本案為 connector 層開出第三種連線型態 SSH（既有 API / CLI 之外）：OpenSCAP 是純 CLI、無 server API 無 daemon，組態稽核必須以登入身分在目標 OS 上執行（讀設定檔 / 套件庫 / sysctl，物理限制、全業界一致）。Agent 維持 Docker 形態不變，只當掃描發起端——SSH 登入目標主機、在目標上執行目標自己的 oscap、把報告拉回。SSH 型態開出後，未來 Lynis 等 CLI / SSH 類工具皆可同軌擴充，證明 FR-056 的 connector 架構可擴。

端到端流程：

租戶設定 OpenSCAP（SSH 稽核帳號 + 金鑰/密碼，加密存放）→ 任務設「檢測工具執行」選 OpenSCAP、填 hosts / profile → 按「開始執行」→ Agent 心跳領派工 → 逐台 SSH 登入目標主機執行掃描 → 每台一份 HTML 報告拉回並上傳 → 雲端逐檔取回存證據池 → 通知負責人 → 依完成模式收尾。

本版另含手測期挖出的 3 項修正（見 §3），其中 CM-952（漏掃靜默）與 CM-954（假成功報告）是稽核產品可信度的關鍵修正——兩者都是「系統回報成功、實際沒達成稽核目的」的靜默假陽性問題。

2. 重點新功能：FR-057 OpenSCAP 接入（SSH 連線型態）

2.1 核心設計：目標主機側掃描引擎 + 租戶層共用稽核帳號

• 目標主機需一次性準備：安裝 openscap-scanner + SCAP content（scap-security-guide，SSG）、建立稽核帳號、佈署 SSH 公鑰與 sudoers 白名單。這是 OpenSCAP 官方正規用法（Red Hat Satellite 同模式）——掃描引擎在目標主機上，Agent container 內只需 SSH client。
• setup_guide 部署前提說明：檢測工具設定頁內建前提說明與一鍵複製的目標主機準備腳本（deb / rpm 雙版），不必翻手冊；detection_tools 新增 setup_guide 欄位（markdown），FE 動態渲染。
• 租戶層一組共用稽核帳號（業界標準做法，Tenable 官方同款建議）：每台目標主機建同名專用掃描帳號；認證方式金鑰 / 密碼二擇一，推薦金鑰，另設 use_sudo 提權開關（完整掃描需 root 級讀取，企業普遍禁 root 遠端登入，「一般帳號 + sudo 提權」是標準模式）。憑證沿用 FR-056 既有 Fernet 加密鏈與派工下發機制，零新表零新機制。
• SCAP content 用目標主機自帶的 SSG：天然匹配該機 OS 版本，平台免維護 content 版本矩陣——未來 SSG 更新只需目標主機更新套件，平台與 Agent 皆不需升級。實作上 connector 自組 SSH 指令直接在目標上執行 oscap 引用目標本地 content（官方 oscap-ssh 腳本語意為「本機 content 推送到遠端」，與此設計矛盾，故不採用）。
• 每台一份 HTML 報告原樣上傳：多目標掃描逐台掃、每台各產一份證據檔（檔名含主機名），summary 統計加總。配套將 result 回收鏈由單檔擴為多檔（result_ref.upload_uids 陣列 + BE 逐檔取回寫 job_evidences，保留單數 key 向下相容，OpenVAS 既有路徑不受影響；單檔失敗記 warning 續處理其餘）。
• FE 動態表單型態擴充：為承載 SSH 設定新增 textarea（私鑰）、條件顯示（認證方式切換密碼 / 私鑰欄位）、select_or_text（profile 下拉常用 CIS / STIG 選項 + 自由輸入）等欄位型態——皆由 BE schema 驅動，後續工具沿用。

2.2 執行歷史增強

• 人事時地物完整呈現：每筆執行紀錄補 scan_params 快照（當次實際用的參數，非任務當前綁定值）與發動者 nickname。
• detection_tool_name 逐筆忠實：每筆紀錄顯示自己當時的工具名稱，任務事後換綁工具不會竄改歷史。
• 多報告逐份下載（CM-952 同批）：一次執行掃多台產生多份報告時，執行歷史列出該次全部報告、逐份可下載——原本只下載得到第一份。
• FE 執行紀錄列改雙行摘要 + 執行詳情視窗，並提供手動重新整理（重新整理同時連動刷新證據清單）。
• 同批修正：任務換綁檢測工具存不進去（update 分支漏寫 detection_tool_id）。

2.3 測試連線增強

• SSH 型工具測試連線先輸入測試主機：SSH 型態沒有固定 server 端點，改為彈框輸入一或多台測試主機再發測。
• 多台並發逐台結果列：多台測試主機並發探測，各台獨立回填結果列、完測即時更新，不互等。
• probe 四段逐段檢查：SSH 連線 → 認證 → oscap 指令存在性 → SCAP content 存在性，缺什麼報什麼（連不上 / 認證失敗 / 缺 oscap / 缺 content 分類明確），部署缺件不再是神祕失敗。

3. 手測期修正（Notion CM-936 / CM-952 / CM-954）

CM-952 漏掃靜默：單台失敗不再無痕跡

多台掃描時 connector 逐台獨立執行、單台失敗（SSH 不通 / 缺 content / 非 Linux 主機）不拖垮整批——但原本失敗完全沒有任何地方記錄，任務照樣顯示「成功」，稽核人員會誤以為全部主機都掃過了。修正：

• Agent 將失敗主機清單與原因併入 summary（agent 0.2.10）
• FE 顯示「部分成功」狀態並列出失敗主機與失敗原因
• 同批修正「多台報告只下載得到一份」（report_file_uid 單值只存第一筆 → 改由 job_evidences 讀取全部）與「執行紀錄預設不展開」

CM-954 假成功報告：零實質檢查不再偽裝成完美通過

SCAP content 版本比目標 OS 舊時（如 Ubuntu 26.04 用 2404 content），oscap exit=0 產出完整報告，但所有規則都因平台判定不匹配而 notapplicable——零實質檢查卻回報「成功」「發現 0 項」，比失敗更危險（會被當成「已檢查且乾淨」寫進稽核紀錄）。修正採雙重把關（agent 0.2.11）：

• 事前：probe 階段比對 content 檔名版本與目標 OS 版本，不匹配即警示
• 事後：以 pass + fail == 0 且 notapplicable > 0 判定，命中時報告仍上傳但打 content_mismatch 旗標；FE 標示「無實質檢查」警示並隱藏「發現 0 項」避免誤讀

設計取捨：刻意不用比例門檻（如 notapplicable ≥ 95%）——容器化等環境本來就大量規則不適用，只要有一條規則真的跑過就不判定為不匹配；跨 OS 家族借用 content（如以 RHEL content 掃 CentOS / Rocky，業界合法用法）亦不誤報。

CM-936 Agent 管理頁移除「類型」欄位

Agent 已不再分類型，管理頁拆掉多餘的「類型」欄位（純 FE，220f013）。

4. Breaking Changes

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

• OpenSCAP 以 detection_tools 第 4 筆 seed 進工具目錄，OpenVAS 既有全鏈（factory 映射、單檔回收路徑、FE 動態渲染）迴歸不受影響。
• result_ref 多檔結構保留單數 upload_uid 讀取相容。
• 無新增任務狀態、無既有 API 行為變更。

5. DB Migration（3 支）

按檔名日期序套用即可，一律 psql --single-transaction -v ON_ERROR_STOP=1。

現況：DEV / STG / POC 三環境已全數套用（schema_migrations 記帳）。⚠️ OpenSCAP 的 detection_tools.id=4 是關鍵——agent factory 的工具映射是固定對照，seed 順序不可變動。

6. 相依套件版本

無變動。無新增必要環境變數（憑證加密沿用 FR-056 的 DETECTION_TOOL_ENCRYPTION_KEY；SSH 憑證存 DB 密文，值請查 .env 或部署文件）。

7. Agent 版本（0.2.8 → 0.2.11）

部署須升級至 0.2.11（0.2.9 / 0.2.10 為中間版，直接跳最新即可）。

8. 部署順序與注意事項

1. DB migration：依 §5 順序套用（三環境已完成）。
2. BE：git pull → 重啟（main_app.py）。確認 .env 既有 DETECTION_TOOL_ENCRYPTION_KEY 存在（v1.11.0 起必要）。
3. FE：同版 build 部署。
4. Agent 升級至 0.2.11：⚠️ 跨平台 build 陷阱——開發機（Mac arm64）build 部署到 amd64 主機時，docker build 必須帶 --platform linux/amd64，否則產出的 image 在目標主機 exec format error crash loop。build 完先 docker inspect <image> --format '{{.Os}}/{{.Architecture}}' 確認 linux/amd64 再出貨。部署機本地 docker-compose.yml 的 AGENT_VERSION 需一併手動同步（不隨 git pull 更新，漏改會導致 agent 自報版本與實際 image 不符）。
5. 掃描目標主機一次性準備：每台目標主機安裝 openscap-scanner + SSG content、建稽核帳號、佈公鑰與 sudoers 白名單——完整腳本見檢測工具設定頁 OpenSCAP 的 setup_guide（一鍵複製）。準備完成後用設定頁「測試連線」逐台驗證（probe 四段檢查會指出缺件）。

9. 已知限制與 follow-up

已知限制

• 目標 OS 過新、官方尚無對應 SSG content 時無法有效掃描：如 Ubuntu 26.04 目前上游尚未發布 ssg-ubuntu2604，該類主機暫時掃不出有效結果（probe 會明確報「缺少 SCAP content」；硬指定舊版 content 則觸發 CM-954 的「無實質檢查」標示）。屬上游 content 生態限制非平台缺陷——官方發布後在目標主機更新 SSG 套件即可，平台與 Agent 皆不需升級。

Follow-up

• CM-953：Windows / 異質 OS 目標主機支援（討論中，待拍板是否開獨立 FR）。
• CM-937（FR-056.9）：Agent 心跳自報 capabilities（取代手動改 DB）。
• 失敗主機部分重掃：目前單台失敗後僅能整批全部重掃，尚無「只重掃失敗台」。
• 未開卡：main_app.py 加 load_dotenv()（方向已拍板）。

10. 相關文件索引

• FR-057 設計文件（含 D1–D7 決策與 D3 實作澄清）：docs/features/FR-057-2607-openscap-ssh-connector/design.md
• 討論稿（含流程圖）：docs/features/FR-057-2607-openscap-ssh-connector/discussion.html
• arc 收官 handoff（含跨平台 build 教訓與環境現況）：docs/features/FR-057-2607-openscap-ssh-connector/handoff/2026-07-29-fr057-arc-complete-handoff.md
• 使用手冊（FR-056 手冊擴充 OpenSCAP / SSH 章節）：docs/features/FR-056-2607-detection-tool-integration/user-manual.html
• 功能頁面 spec（本版更新 3 頁）：docs/specs/current/ — system-admin/tool-plugin-manage.md、project-management/project-task-edit.md、audit-execution/my-tasks.md
• Notion cases：CM-938 ~ CM-952、CM-954（CM-953 討論中）