FR-057 OpenSCAP 掃描工具接入（SSH 連線型態）— 設計文件

狀態：設計定案（D1–D7 已拍板）｜建立日期：2026-07-28｜FR-056 檢測工具整合平台續作 討論稿（含流程圖）：discussion.html

FR-056 檢測工具整合平台第一版只接了 OpenVAS（API 型）。本案新增第二個工具 OpenSCAP——開源組態合規稽核工具（CIS / STIG benchmark），並藉此開出 connector 架構的第三種連線型態 SSH（既有 API / CLI 之外）。

為什麼是 SSH 遠端掃描（設計前提，已查證定案）

• OpenSCAP（oscap）是純 CLI，無 server API、無 daemon。組態稽核要讀目標主機系統內部（設定檔 / 套件庫 / sysctl），必須以登入身分在目標 OS 上執行——這是物理限制，全業界一致。
• 官方遠端模式是 oscap-ssh：發起端 SSH 登入目標 → 推送 content → 在目標上執行目標自己的 oscap → 把報告拉回。Red Hat Satellite / Foreman 大規模採用同一模式。
• Agent 維持 Docker 形態不變：Agent 是掃描發起端（站點調度器），container 內只需 openssh-client + oscap-ssh 腳本；真正的掃描引擎（openscap-scanner 套件）在各目標主機上。
• Nessus / Qualys 能「零安裝」是因為自造檢查引擎（商業核心資產）；OpenSCAP 開源專案沒有這層，目標裝 openscap-scanner 是選用 OpenSCAP 的隨附條件（幾 MB CLI 工具、非常駐、不開 port）。

端到端流程

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

4.1 租戶設定欄位（config_field_schema）

secret 欄位（password/private_key）進 credentials_encrypted 密文；其餘進 field_values。

4.2 任務參數（param_schema）

content_path 語意：填目錄時 connector 依目標 OS 推斷 ssg-<os><ver>-ds.xml；填檔案路徑時直接用。第一版先實作「必填完整檔案路徑或用預設推斷」中較簡單的一種，plan 階段定案。

4.3 Agent connector（core/task_executor_connectors/openscap.py）

• run()：解析 hosts → 逐台自組 SSH 指令執行 ssh <user>@<host> [sudo] oscap xccdf eval --profile <p> --report <遠端 mktemp 暫存> <目標上的 content 路徑> → 拉回 HTML 報告 bytes（scp/cat）→ 清理遠端暫存 → 解析 stdout 規則統計 → 回傳多檔 ScanResult（見 4.5）。不經 oscap-ssh 官方腳本（其語意為本機 content 推送，與 D3 矛盾，見變更紀錄 2026-07-29）。私鑰認證：憑證中的 private_key 寫入記憶體型暫存（/dev/shm 或 tmpfile 0600），掃完即刪，不落地持久化。
• probe()：SSH 連線 + 認證 → 遠端執行 command -v oscap + SSG content 路徑存在性檢查 → 缺什麼在錯誤訊息中明確分類（連不上 / 認證失敗 / 缺 oscap / 缺 content）。與 run() 共用連線參數解析（單一真相，同 OpenVAS 模式）。
• 取消 / 逾時：SSH 指令是子行程——輪詢 cancel_event，取消時 terminate 子行程 raise ScanCancelledError；逾時逐台計時 raise TimeoutError。
• oscap 退出碼：0=全 pass、2=有 fail（掃描成功，報告有效）、1=執行錯誤。2 不可誤判為失敗。

4.4 exit code 與 summary

stdout 每條規則一行 Result: pass/fail/notapplicable/...，彙總成：

{"findings": <fail數>, "pass": n, "fail": n, "notapplicable": n, "error": n, "hosts_scanned": n}

解析失敗不拖垮派工（同 OpenVAS _parse_summary 原則：證據到手 summary 可缺）。

4.5 多檔證據回收鏈擴充（跨 agent + BE）

• Agent task_executor：逐檔上傳 blob → result_ref 從 {"upload_uid": x} 擴為 {"upload_uids": [{"uid": x, "filename": f}, ...]}；保留單數 key 讀取相容（OpenVAS 路徑不動也不壞）。
• BE detection_result_handler：讀 upload_uids（fallback upload_uid）逐檔 mTLS GET /blob/{uid} → 逐檔寫 job_evidences。單檔失敗記 warning 續處理其餘（部分成功優於全失敗）。
• 檔名：OpenSCAP掃描報告_<host>_<日期>.html。

4.6 部署前提（設定頁說明 + 準備腳本）

detection_tools 加 setup_guide 欄位（TEXT，markdown），FE 設定頁渲染 + 腳本區塊一鍵複製。腳本內容（範例，deb/rpm 雙版）：

# 每台目標主機執行一次（Ubuntu/Debian）
sudo apt install -y openscap-scanner ssg-base ssg-debderived   # RHEL 系: openscap-scanner scap-security-guide
sudo useradd -m -s /bin/bash audit-scan
echo '<公鑰>' | sudo tee /home/audit-scan/.ssh/authorized_keys  # 目錄權限步驟略，見完整腳本
echo 'audit-scan ALL=(root) NOPASSWD: /usr/bin/oscap' | sudo tee /etc/sudoers.d/audit-scan

依賴鏈：FR-057.1（BE 地基）→ FR-057.2（Agent connector）∥ FR-057.3（多檔回收鏈），.2/.3 可並行（.3 不依賴 openscap connector 本身，用假多檔即可測）。

FR-057.1 BE：SSH 型態 + OpenSCAP 目錄與設定頁 — 依賴：無

FR-057.2 Agent：OpenSCAP connector — 依賴：FR-057.1

FR-057.3 多檔證據回收鏈 — 依賴：FR-057.1（可與 .2 並行）

1. 管理員在檢測工具管理頁設定 OpenSCAP（金鑰認證）→ 測試連線通過（含前提檢查）
2. 任務選 OpenSCAP、填 2 台 hosts + CIS profile → 開始執行 → 每台各一份 HTML 報告進證據池
3. 任一台缺 openscap-scanner → probe/掃描回明確錯誤訊息（非神祕失敗）
4. OpenVAS 既有全鏈迴歸不受影響（factory / result 單檔路徑 / FE 動態渲染）