Guidant AI 檢測工具整合平台 使用手冊

1. 總覽
2. 檢測工具設定
3. 任務設定
4. evidence-agent 升級部署
5. SSH 遠端掃描部署說明（OpenSCAP）
6. 端到端執行流程
7. 重新執行與取消機制
8. 人工測試 Checklist
9. 常見問題

1. 總覽

檢測工具整合平台讓 Guidant AI 直接調度外部資安檢測工具，目前已上線兩款： OpenVAS（弱點掃描，API 連線）與 OpenSCAP（CIS / STIG 組態合規稽核，SSH 遠端連線）。 稽核任務中的「檢測工具執行」任務按下開始執行後，系統會派工給部署於內網的 Agent 執行掃描， 掃描完成的報告會自動拉回雲端並登錄為該任務的證據，同時附上發現項目統計並寄送通知信給任務負責人； 若任務設定為「自動」完成模式，系統會在證據入庫後自動將任務標記完成， 「人工」模式則保留任務為執行中，等負責人檢視報告後手動按完成。

2. 檢測工具設定

2.1 平台工具目錄

平台維護一份「檢測工具目錄」（目前收錄 OpenVAS、OpenSCAP 兩款）。目錄是 DB 驅動而非程式寫死： 每個工具在目錄中定義工具代碼、顯示名稱、說明、連線類型（API / CLI / SSH）、設定欄位結構（動態表單 schema）、部署前提說明 與平台層總開關。未來新增其他工具（如 Nessus、SonarQube）時，於目錄新增資料並搭配對應 Agent connector 即可， 租戶設定頁與任務參數表單的欄位都會依目錄中定義的欄位結構自動渲染（FE 對工具型別零硬編）。

2.2 租戶設定頁

進入「檢測工具管理」頁面，對要使用的工具點「設定」， 填寫連線資訊後儲存。頁面主要操作：

2.3 OpenSCAP 專屬設定欄位

選 OpenSCAP 按「設定」，表單欄位如下：

2.4 憑證加密說明

2.5 測試連線

儲存設定後建議立即按工具卡片上的「測試連線」確認整條連線鏈路可用。 測試結果（成功 / 失敗）與時間會記錄在該筆設定上，方便日後追查連線狀況。 若測試失敗，請參考 第 9 章常見問題 的排查步驟。

2.6 部署前提說明（i 按鈕）

有部署前提的工具（目前為 OpenSCAP），卡片「⋮」選單會出現「部署前提說明」項，點開後顯示：

• 為什麼需要目標主機準備（純 CLI 工具無法遠端零安裝掃描的物理限制）
• 準備清單（裝套件、建帳號、佈公鑰、開 sudoers 白名單）
• Ubuntu/Debian 與 RHEL/CentOS/Rocky 兩份可直接執行的準備腳本

視窗內有「複製腳本」按鈕，一鍵把腳本部分（不含說明文字）複製到剪貼簿，可直接貼到目標主機終端機執行。 完整的準備步驟與腳本內容見 第 5 章。

3. 任務設定

3.1 設定入口與步驟

任務類型下拉選擇「檢測工具執行」後，任務卡片會出現 「檢測工具」下拉，列出本租戶已啟用的工具。 未選擇工具無法儲存，系統會擋下存檔。

3.2 掃描參數

選定工具後，依工具的參數 schema 填寫掃描參數。OpenVAS 目前的參數如下（表單完全依 BE 回傳的 schema 動態渲染，新增欄位不需要改 FE）：

3.3 OpenSCAP 掃描參數

選定 OpenSCAP 後，任務卡片出現以下參數。有預設值的欄位選定工具當下會自動帶入，不會看到空白表單：

3.4 完成模式

任務卡片的「完成模式」決定掃描結束後任務怎麼收尾：

4. evidence-agent 升級部署

檢測掃描由部署在客戶內網的 evidence-agent（出貨名 guidant-ai-agent）執行，目前部署版本為 0.2.8（已部署 192.168.50.123）。 evidence-agent 以 Docker image 形式出貨，升級方式是在開發機重新 build image 後 docker save / docker load 出貨， 不是在 Agent 主機上 git pull 源碼直跑。

4.1 重建與出貨步驟

# 於開發機 evidence-agent repo 根目錄
# 0) 確認在最新 feature/scan-plugin-integration 程式碼上

# 1) Nexus 認證 secret（.secrets/nexus.env 已存在可跳過；帳密查部署文件）
#    內容兩行：export POETRY_HTTP_BASIC_NEXUS_USERNAME=... / export POETRY_HTTP_BASIC_NEXUS_PASSWORD=...

# 2) build 新版 image —— 用 repo 根目錄的 rebuild.sh，IMAGE 版號需與五處版號同步清單一致
IMAGE=guidant-ai-agent:0.2.8 ./rebuild.sh
#    加 --no-cache 可強制全新重建：IMAGE=guidant-ai-agent:0.2.8 ./rebuild.sh --no-cache

# 3) 出貨到 agent 主機 192.168.50.123
docker save guidant-ai-agent:0.2.8 | ssh <user>@192.168.50.123 docker load

# 4) 在 123 上：deploy/.env 改 AGENT_IMAGE=guidant-ai-agent:0.2.8
#    （compose 的 AGENT_VERSION 亦已在 repo 內同步更新為 0.2.8）

# 5) 在 123 的 deploy/ 目錄重建 agent 容器
#    ⚠️ up -d 必須指定 service 名（guidant-ai-agent）——不帶名會對 compose 內
#       「所有」服務比對重建，同檔的 postgres 資料庫容器會被一併 recreate（無預警重啟）。
#    ⚠️ nginx（mTLS 入口）掛在 compose profile "full" 底下，指令仍需帶 --profile full
docker compose --profile full up -d guidant-ai-agent

# 6) 確認容器健康 + 心跳（應見 guidant-ai-agent / agent-db / nginx 三個容器）
docker compose --profile full ps
docker compose logs --tail 20 guidant-ai-agent

全新安裝（非升級）請參考 evidence-agent 專案內 deploy/README.md 的既有部署流程。

5. SSH 遠端掃描部署說明（OpenSCAP）

5.1 為什麼需要目標主機準備

OpenSCAP（oscap）是純 CLI 工具，沒有 server API、沒有常駐服務（daemon）。 組態合規稽核要檢查的是目標主機系統內部的實際狀態（設定檔內容、已裝套件版本、核心參數等）， 這類檢查必須以登入身分在目標作業系統上直接執行才能讀到——這是所有組態稽核工具的共同物理限制，不是本平台的取捨或妥協。 業界的官方標準做法是「發起端 SSH 登入目標主機 → 在目標上執行目標自己的 oscap → 把報告拉回」（Red Hat Satellite / Foreman 大規模環境採用同一模式）。

因此使用 OpenSCAP 之前，每一台要掃描的目標主機都需要一次性完成準備：安裝 openscap-scanner 與 SCAP content（SSG）、建立稽核帳號並佈署 SSH 公鑰、視需要開放 sudo 免密執行。 Agent 本身維持既有的 Docker 部署形態不變，只是「掃描發起端」——它透過 SSH 連到目標主機，實際的掃描動作在目標主機上跑，不在 Agent 容器內執行。

5.2 目標主機準備清單

• 安裝 openscap-scanner（`oscap` 指令本體）與 SCAP content 套件（Ubuntu/Debian 為 ssg-base + ssg-debderived；RHEL 系為 scap-security-guide）
• 建立稽核帳號（建議用固定名稱，如 audit-scan，所有目標主機統一使用同一帳號名稱）
• 佈署本設定頁使用的 SSH 公鑰到該帳號的 ~/.ssh/authorized_keys
• 設定 sudoers 白名單，只允許該帳號免密執行 /usr/bin/oscap（**不是**開放整台機器 sudo，見 5.4 常見問題）

5.3 目標主機準備腳本

以下腳本可在檢測工具設定頁的「部署前提說明」視窗（見 2.6）直接複製，貼到目標主機終端機以有 sudo 權限的帳號執行一次即可。兩份腳本邏輯相同，僅套件管理指令不同。

Ubuntu / Debian

sudo apt update
sudo apt install -y openscap-scanner ssg-base ssg-debderived openssh-server
sudo useradd -m -s /bin/bash audit-scan
sudo mkdir -p /home/audit-scan/.ssh
echo '<貼上本設定使用的 SSH 公鑰>' | sudo tee /home/audit-scan/.ssh/authorized_keys
sudo chown -R audit-scan:audit-scan /home/audit-scan/.ssh
sudo chmod 700 /home/audit-scan/.ssh
sudo chmod 600 /home/audit-scan/.ssh/authorized_keys
echo 'audit-scan ALL=(root) NOPASSWD: /usr/bin/oscap' | sudo tee /etc/sudoers.d/audit-scan

RHEL / CentOS / Rocky

sudo dnf install -y openscap-scanner scap-security-guide openssh-server
sudo useradd -m -s /bin/bash audit-scan
sudo mkdir -p /home/audit-scan/.ssh
echo '<貼上本設定使用的 SSH 公鑰>' | sudo tee /home/audit-scan/.ssh/authorized_keys
sudo chown -R audit-scan:audit-scan /home/audit-scan/.ssh
sudo chmod 700 /home/audit-scan/.ssh
sudo chmod 600 /home/audit-scan/.ssh/authorized_keys
echo 'audit-scan ALL=(root) NOPASSWD: /usr/bin/oscap' | sudo tee /etc/sudoers.d/audit-scan

5.4 SSH 連線細節

• 共用租戶層帳號：D1 決策——SSH 憑證放在租戶工具設定層，一組共用稽核帳號 + 密碼/金鑰，不是每台目標主機各自帳密。所有目標主機都用同一個帳號名稱與同一把金鑰/密碼登入，管理上比逐台各自配帳密簡單，也是業界（如 Tenable）建議的做法。
• 認證方式二擇一：密碼或 SSH 私鑰，設定頁二選一（見 2.3）；推薦金鑰認證。
• sudo 提權範圍精準受限：sudoers 設定只授權該帳號免密執行 /usr/bin/oscap 這一個指令（NOPASSWD: /usr/bin/oscap），不是給予該帳號整台主機的 sudo 權限——即使帳號密碼外洩，攻擊者也只能免密跑這一個掃描指令，無法用它任意提權執行其他指令。
• SSH host key 首次連線自動信任：第一版行為是首次連線自動接受目標主機的 host key（AutoAddPolicy），不會因為未知 host key 而擋下連線，也不會人工介入核對指紋。這是第一版的已知取捨，未來若有更高安全要求可考慮改為預先核對指紋的嚴格模式。

6. 端到端執行流程

6.1 完整鏈路

6.2 執行抽屜操作

在任務的執行抽屜中可進行以下操作：

6.3 證據與通知

• 掃描成功後，報告以檔案證據形式進入該任務的證據列表，來源標示為檢測工具，與人工上傳的證據並列。OpenSCAP 多台掃描時，每台各自一筆證據。
• 報告檔名帶有意義（含工具/目標主機/日期），例如 OpenVAS 的 OpenVAS掃描報告_192.168.50.151_20260727.pdf、OpenSCAP 的 OpenSCAP掃描報告_192.168.50.151_20260729.html，方便直接辨識內容，不需點開才知道是什麼。
• 系統會寄送 Email 通知任務相關負責人；若查無通知對象，僅記錄日誌、不影響掃描結果入庫。

7. 重新執行與取消機制

「重新執行」的行為依上一次執行是否還在進行中分岔，目的是避免同一個目標被疊出兩個並行掃描（互相干擾、拖慢，甚至產生兩份重複報告）。

7.1 無執行中的紀錄 → 直接派工

按「重新執行」（或首次「開始執行」）時，若目前沒有任何執行中的紀錄，系統直接派出新工單，跟以往行為一致，不會額外跳出確認視窗。

7.2 有執行中的紀錄 → 確認框 → 真中斷 → 才派新工單

確認後，系統不是只在畫面上假裝取消——會透過既有的雲端 → Agent mTLS 通道發出取消指令，把該掃描真正停下來（OpenVAS 呼叫官方的 stop_task；OpenSCAP 終止當下正在跑的 SSH 子行程），確認停止成功後，才標記舊執行紀錄為「已取消」並派出新的工單。 按「取消」則什麼都不會發生，維持原狀。

7.3 邊界情境

• 取消時掃描還在 pending（Agent 尚未領工）：雲端直接標記取消即可成功，不需要真的推給 Agent（推了也找不到）。
• 取消與掃描完成的競態：如果取消指令送出的同一瞬間，舊掃描剛好自然完成或失敗回報了結果，系統會判斷該筆執行已是「已取消」狀態，不會再產生額外的證據、不發通知、也不觸發自動完成——避免資料混亂（多一筆不該有的證據）。
• 繞過畫面直打 API：即使沒有經過確認流程直接呼叫執行 API，只要有執行中的紀錄且未帶「強制」旗標，BE 一律回錯誤擋下，不會讓使用者不小心疊出兩個並行掃描。

8. 人工測試 Checklist

• 前置環境
• 確認真實 OpenVAS 的 GVMd 9390 埠 TLS 有對外開放：在 Agent 主機執行 nc -zv <openvas-host> 9390 應回報連線成功。
  已知陷阱：Docker 版 OpenVAS（如 greenbone community 映像）預設常只開 Unix socket、不開 9390 TCP——先用 docker ps 檢查容器 port 對映是否有 9390，沒有就要調整 compose 設定把 GVMd TLS port 對外。
• evidence-agent 已完成第 4 章升級（重 build image 0.2.8 → save/load 出貨 → 改 AGENT_IMAGE → docker compose up -d），且雲端該 Agent 的 capabilities 已含 detection_scan。
• 工具設定
• 檢測工具管理頁可完成設定的新增、查看、修改、停用（含停用前引用任務數提示）與重置金鑰。
• 「測試連線」成功情境：填正確連線資訊（位址可不加 http:// 前綴）→ 顯示「連線成功」。
• 「測試連線」失敗情境：錯誤憑證 → 顯示認證失敗；不可達位址 → 顯示連線失敗原因；本租戶無可用 Agent → 明確提示需部署 Agent（非逾時乾等）。
• 已設定的機敏欄位重開表單顯示「••••（已設定，留空不變更）」，不回顯明文。
• 任務設定
• 任務類型可選「檢測工具執行」，工具下拉列出已啟用工具；未選工具擋存檔。
• 掃描參數表單出現 hosts（必填）＋ timeout_sec / scan_config_id / scanner_id / port_list_id（選填）；hosts 未填有必填提示。
• 完成模式可在「人工」與「自動」間切換並正確儲存。
• 執行與證據
• PM 在規劃頁按「開始執行任務」→ detection_tool 型任務自動派第一次掃描，不用進抽屜手動按。
• 抽屜按「開始執行」（無執行中紀錄）→ 抽屜執行紀錄出現一筆「執行中」，不彈確認框。
• 掃描完成後，該筆紀錄轉為成功並顯示「發現 {count} 項」，報告可下載開啟。
• 任務證據列表出現該掃描報告（來源＝檢測工具），檔名可讀（含主機/日期）。
• 收到掃描完成通知信。
• 執行紀錄區塊：有 running 或最新一筆失敗時預設展開，其餘預設收合；點標題列可手動收合/展開。
• 同批多任務（撞名防護）
• 規劃頁一次發佈多筆掃描同一目標的任務（觸發自動派工同時並行）→ 全部成功建立各自的 OpenVAS target/task，不再出現 Target exists already。
• 單一任務重複多次「重新執行」也不會撞名；Greenbone UI 上可從 target/task 名稱大致回推是哪一筆派工。
• 重新執行與取消機制
• 派一個掃描，趁它還在「執行中」時再按一次「重新執行」→ 應彈出確認視窗；按「取消」→ 應無任何動作。
• 按「確定重新執行」→ 到 Greenbone（123:9392）確認舊的那個任務真的停下來（顯示 Stopped）、新任務開始跑；執行紀錄舊那筆顯示「已取消」、新那筆顯示「執行中」。
• 沒有掃描在跑時按「重新執行」→ 不應彈確認框，直接派工。
• （若方便測試）取消後即使舊掃描仍回傳結果，也不應多產生一筆證據或多發一次通知。
• 完成模式分岔
• manual 模式：掃描完成後任務仍為執行中（PROCESSING），可由負責人手動按完成。
• auto 模式：掃描完成後任務自動變為已完成（COMPLETED）。
• 失敗與重試
• 失敗情境（錯誤憑證或不可達的 host）：執行紀錄標為失敗並保留錯誤訊息，任務仍為 PROCESSING，可按「重新執行」重試。
• 重掃多次：執行歷史累積多筆紀錄，每筆報告各自獨立可下載，最新在最上。
• OpenSCAP 專屬檢查（FR-057）
• 目標主機缺 openscap-scanner 時測試連線（probe）應明確回報「未安裝 openscap-scanner」，而非籠統的連線失敗或逾時。
• 目標主機缺 SCAP content（或 content_path 推斷失敗）時測試連線應明確回報「缺少 SCAP content」，並提示改填完整檔案路徑。
• 設定頁「認證方式」在密碼／私鑰間切換時，另一個未選中的欄位確實**不會**被送出殘留值（可用瀏覽器開發者工具檢查 request body 確認）。
• OpenSCAP 掃描 2 台以上目標主機 → 執行歷史該筆紀錄的報告清單出現對應台數的檔案，各自可獨立下載（非只有一份）。
• OpenSCAP 測試連線輸入多台主機 → 逐台結果即時分別顯示（測試中/成功/失敗），不需等全部跑完才看到第一筆結果。
• 其中一台目標主機的 sudoers 設定漏掉 NOPASSWD: /usr/bin/oscap → 掃描該台應失敗並回報可辨識的權限錯誤，不影響其他台的掃描結果。

9. 常見問題

9.1 測試連線失敗怎麼排查？

測試連線走 雲端 → Agent → 檢測工具 兩段鏈路（見 2.5），依失敗訊息分段排查：

• 提示「尚無可用的檢測 Agent」：本租戶沒有已啟用且 capabilities 含 detection_scan 的 Agent——先完成第 4 章的 Agent 部署與雲端 capabilities 設定。
• 提示「無法連線至 Agent」或「Agent 回應異常」：雲端 → Agent 這段不通。確認 Agent 容器存活、心跳正常；「回應異常（HTTP 500）」常見原因是 Agent 版本過舊（缺 /detection/probe、/detection/cancel 等端點），需照第 4 章重 build 升級。
• 提示認證失敗（Authentication failed）：Agent 連到了工具端但帳密不對。確認憑證正確；若不確定已存的值，可用「重置金鑰」重新輸入。OpenSCAP 另確認稽核帳號是否已在目標主機建立、公鑰是否已正確佈署到 authorized_keys。
• 提示網路不可達 / 逾時類錯誤：Agent → 檢測工具這段不通。OpenVAS 確認位址與 port 正確——GVMd 走 9390（GMP over TLS），在 Agent 主機執行 nc -zv <openvas-host> 9390 確認可達；OpenSCAP 確認目標主機的 SSH port（預設 22）對 Agent 主機可達、防火牆未擋。
• OpenSCAP 提示「未安裝 openscap-scanner」：目標主機尚未完成第 5 章的準備步驟，先在該主機執行對應的準備腳本。
• OpenSCAP 提示「缺少 SCAP content」：目標主機的 SSG content 套件未安裝，或 content_path 指向的路徑 / 推斷出的檔名不存在——確認套件已裝，或改在任務參數改填完整檔案路徑。
• 修改設定後務必先儲存再測試——測試連線測的是已存檔的值，未儲存的表單內容不會被測到。

9.2 掃描一直卡在「執行中」？

• 確認 Agent 服務存活且心跳正常（Agent 掛掉就沒有人領工單）；心跳「先跳再等」，若懷疑間隔異常先查 certs/agent.json 快取（見第 4 章）。
• 確認該 Agent 在雲端的 capabilities 含 detection_scan，否則工單永遠派不出去。
• OpenVAS 到 GVMd 端確認狀態與掃描任務是否真的在跑；OpenSCAP 確認目標主機的 SSH 連線與 oscap 程序是否卡住（大範圍組態掃描本來就耗時，可視情況調大 timeout_sec，預設 3600 秒）。
• 若確定卡住的掃描不需要了，可按「重新執行」走取消機制真正中斷（見第 7 章），不需要等它自然逾時。

9.3 掃描完成但證據沒出現在任務裡？

• 先開執行抽屜看執行紀錄：若該筆為失敗，展開查看錯誤訊息（常見為 hosts 未填或格式錯誤、工具端連線中斷）。
• 若該筆為「已取消」，代表這次執行被主動中斷（或與其他重新執行動作競態），不會有證據入庫是正常行為。
• 失敗不影響任務狀態，修正參數或環境後按「重新執行」即可重試。
• OpenSCAP 多台掃描時，部分台失敗不影響其他台入庫——執行歷史該筆的報告清單只會出現實際成功的那幾台。
• 若執行紀錄顯示成功但證據仍未出現，請聯繫系統管理員檢查後端日誌。

9.4 同時發佈多個掃描出現 Target exists already？

• 此為 OpenVAS 特有的舊版問題：0.2.8 之前的舊版 Agent 用「秒級時間戳記」命名掃描目標，同一秒內多筆掃描並行建立時會撞名。0.2.8 起改用「派工單唯一編號」命名，理論上不會再發生——若仍遇到，請確認 Agent 版本確實已升級。

9.5 OpenSCAP 私鑰貼入格式錯誤怎麼判斷？

• 設定頁的「SSH 私鑰」欄位需要貼入完整的 OpenSSH PEM 格式私鑰——包含開頭的 -----BEGIN OPENSSH PRIVATE KEY-----（或 RSA PRIVATE KEY 等變體）到結尾的 -----END ... PRIVATE KEY----- 整段，中間不可缺行、不可只複製部分內容。
• 常見錯誤：只複製了私鑰檔案內容的一部分（如漏了頭尾標記行）、貼成公鑰（.pub 檔內容，通常以 ssh-rsa/ssh-ed25519 開頭且是單行）、或私鑰本身有密碼保護（connector 目前不支援輸入私鑰密碼，需使用未加密的私鑰）。
• 若不確定貼的內容是否正確，可先用 ssh -i <私鑰檔> audit-scan@<目標主機> 在本機測試該私鑰是否能正常登入，確認無誤後再貼進設定頁。

9.6 OpenSCAP 掃描目標缺 SCAP content 怎麼辦？

• 先在目標主機執行第 5 章準備腳本安裝 SSG content 套件（Ubuntu/Debian 為 ssg-base/ssg-debderived；RHEL 系為 scap-security-guide）。
• 安裝後可用 ls /usr/share/xml/scap/ssg/content/ 確認 content 檔案是否存在；若目標主機的作業系統不在系統支援的自動推斷清單內（少見的發行版或版本），任務參數的 content_path 需改填該主機上實際的完整檔案路徑。
• 若目標 OS 版本較新、官方尚未發布對應 content（例：Ubuntu 26.04 尚無 ssg-ubuntu2604），安裝 SSG 套件也不會有對應檔案——該主機暫時無法有效掃描，待官方發布後更新套件即可，平台不需任何升級。請勿硬指定舊版 content 掃新版 OS：規則會全數 notapplicable，系統會標示「無實質檢查」。