FR-057 手測驗收棒 — 換 session 交接（2026-07-29）

項目	內容
緣由	FR-057 八張子任務卡全部完成（修正待驗證），三 repo 程式碼已就位、單元測試綠、主 session 已做獨立抽查；尚未經 user 手測驗收。本棒接手做端到端手測與問題修正
Branch	BE `feature/instance-agent`（10 commits 未 push）／FE `feature/instance-agent`（2 commits 未 push）／agent repo（4 commits，working tree 乾淨）
本棒角色	手測驗收 + 修問題，不做收尾（spec/SUMMARY/進版一律等 user 下令）
接手前必讀	本文 §0 讀序
預估時間	討論 + 升 image 約 1h；端到端手測視問題量

🧭 原始需求 / WHY

FR-057 = 在 FR-056 檢測工具整合平台上接入第二個掃描工具 OpenSCAP（CIS/STIG 組態合規稽核），並開出 connector 第三種連線型態 SSH。

大圖：FR-056（已隨 v1.11.0 上線）讓租戶設定檢測工具 → 任務按「開始執行」→ 客戶端 Agent（evidence-agent，Docker）心跳領派工 → 掃描 → 報告自動回收成任務證據。第一版只有 OpenVAS（API 型）。本案價值：①客戶多了組態合規稽核能力（不只弱點掃描）②connector 架構證明可擴（SSH 型開出後，未來 Lynis 等 CLI/SSH 工具同軌）。

關鍵設計事實（討論中 user 反覆確認過的）：

OpenSCAP 是純 CLI 無 API、無 daemon。組態稽核必須以登入身分在目標 OS 上執行——物理限制，全業界一致。目標主機需一次性裝 openscap-scanner + SCAP content（SSG），這是官方正規用法（Red Hat Satellite 同模式），不是我們的妥協。Agent 維持 Docker 形態不變，只當掃描發起端。
憑證＝租戶層一組共用稽核帳號（Tenable 業界標準），金鑰/密碼二擇一推薦金鑰 + use_sudo，沿用 FR-056 既有 Fernet 加密鏈與 D9 派工下發。
SCAP content 用目標主機自帶的 SSG（D3），不由平台推送 → 免維護版本矩陣。
證據＝每台一份 HTML 原樣上傳（D4/D5）→ 牽動 result 回收鏈由單檔擴多檔（FR-057.3 的由來）。
D3 實作澄清（2026-07-29，commit 3a67e938）：官方 oscap-ssh 腳本語意是「本機 content 推送到遠端」，與 D3 矛盾 → 定案 connector 自組 SSH 指令（paramiko）直接在目標上執行 oscap 引用目標本地 content。D3 核心價值不變。

§0 接手讀序

🔒 先懂需求 gate：本文「🧭 原始需求」全讀 + docs/features/FR-057-2607-openscap-ssh-connector/design.md §1–§2（背景 + D1–D7 + 變更紀錄的 D3 澄清）全讀
本文 §1（現況）→ §2（connector 實際行為）→ §3（本棒工作順序）
需要細節才開：design.md §4（詳細設計）／~/Projects/Billows/Audit-Manager/evidence-agent/core/task_executor_connectors/openscap.py（458 行，含大量設計註解）
Notion 母案：https://app.notion.com/p/3ab346da4cd081af9cfac78397f7acfb（data source collection://23c346da-4cd0-8041-955e-000bb6976dd2）

冷接自檢：①FR-057 解決什麼使用者問題？②為什麼不用官方 oscap-ssh 而自組 SSH 指令？③為什麼每台一份 HTML 而不是合併單檔？④本棒該做什麼、不該做什麼？——答不出回去讀 §0.1。

§1 現況：八張卡全完成（修正待驗證），未手測

子需求	卡號 / 子任務	Repo	commit
FR-057.1 BE/FE 地基	CM-942 T-1.1 migration seed	BE	`768aa289` + `3e30d99d`（required 語意修正）+ `de979c30`（setup_guide 落地鏈路）
	CM-943 T-1.2 FE 設定頁欄位型態	FE	`d3dc91a`
	CM-944 T-1.3 FE 任務參數 select_or_text	FE	`e77d303`
FR-057.2 Agent connector	CM-945 T-2.1 骨架	agent	`2ec3c5b`
	CM-946 T-2.2 `run()`	agent	`21e157b`
	CM-947 T-2.3 `probe()`	agent	`b628b1c`
FR-057.3 多檔回收鏈	CM-948 T-3.1 agent 多檔上傳	agent	`a14ab28`
	CM-949 T-3.2 BE 多檔取回	BE	`c20b22a2`

母案 CM-938 與三張子需求卡 CM-939/940/941 仍 Not started——收線時才動（等 user 下令）。

主 session 2026-07-29 獨立抽查結果（已實查，非 runner 自報）：

agent repo working tree 乾淨，四個 commit 都在
測試綠：cd ~/Projects/Billows/Audit-Manager/evidence-agent && PYTHONPATH=. poetry run pytest test/ -q → 122 passed, 1 skipped
factory core/task_executor_connectors/__init__.py 的 _TOOL_ID_TO_CODE 已加 4: "openscap"，且 .2 沒動 core/task_executor.py（檔案邊界正確）
實作有落實 D3 裁決：自組 SSH 指令（paramiko）非 oscap-ssh、exit code (0,2) 視為成功、遠端 mktemp 暫存 + finally 清理且等 recv_exit_status()、shlex.quote 全參數、私鑰 /dev/shm 暫存
⚠️ 已知小問題（不擋事，列 follow-up）：agent repo 缺 pytest.ini/conftest.py，裸跑 pytest test/ 會 ModuleNotFoundError，必須帶 PYTHONPATH=.

§2 connector 實際行為（讀 openscap.py 後寫實，供討論掃描指令用）

實際送到目標主機的掃描指令（_scan_one_host，所有參數過 shlex.quote）：

sudo /usr/bin/oscap xccdf eval --profile '<profile id>' --report '<遠端 mktemp .html>' '<content 路徑>'

sudo 前綴只在 use_sudo=true（預設 true）時加；/usr/bin/oscap 是寫死常數，對齊 setup_guide 腳本的 sudoers 白名單 NOPASSWD: /usr/bin/oscap
報告先在目標主機 mktemp --suffix=.html 建暫存（由登入帳號建立，oscap 以 root 開檔寫入不改擁有者，故登入者可讀回）；掃完 SFTP stat 顯式驗可讀性（讀不到給「sudo 情境下可能是暫存檔擁有者問題」明確診斷）→ 讀 bytes → finally 一律 rm -f 並 recv_exit_status() 等清理跑完才關連線
content 路徑解析（_resolve_content_path）：路徑以 .xml 結尾 → 直接用；否則視為目錄（含預設 /usr/share/xml/scap/ssg/content/）→ 遠端 cat /etc/os-release 取 ID/VERSION_ID → 組 <目錄>ssg-<id><ver>-ds.xml。版號格式：ubuntu 去點（22.04→2204），debian/rhel/centos/rocky/almalinux/ol/fedora 只取主版號。ID 不在表內或缺 VERSION_ID → 明確 raise 叫使用者直接填完整檔案路徑，不靜默猜檔名
exit code：0（全 pass）/2（有 fail 但掃描成功）視為成功；其餘 raise 並附 stdout 末 500 字
取消/逾時（_exec_with_cancel）：邊跑邊排空 stdout/stderr 避免 paramiko 管線死鎖（stderr 讀完丟棄不解析），每 0.5s 輪詢 cancel_event 與 deadline，命中則 channel.close() 並 raise ScanCancelledError/TimeoutError
summary（_parse_stdout_summary）：先把 \r 去掉再 splitlines（否則 Result\r\tpass 會被拆行破壞比對），取 Result 開頭行的值，pass/fail/notapplicable 各自計數、其餘（unknown/error/notchecked/…）一律進 error 桶；解析失敗回全零不拖垮派工。每筆 ScanResult 只放該台統計（findings=fail、hosts_scanned=1），多台加總由 task_executor._merge_summaries() 做——connector 不可自己加總，否則 N 倍虛報
多台策略：hosts 以 [,;\s]+ 正規化；單台失敗（連線/認證/執行/逾時）記 warning 續掃下一台，只有 ScanCancelledError 中止整個 run()；全部失敗才整體 raise（不靜默回空）
檔名：OpenSCAP掃描報告_<host>_<YYYYMMDD>.html
私鑰：tempfile.mkstemp 寫進 /dev/shm（不存在才 fallback 系統 tmp）+ 顯式 chmod 0600 + try/finally 刪；paramiko look_for_keys=False/allow_agent=False（不撿本機其他身分）、AutoAddPolicy（第一版接受首次連線風險）
probe()：需 params.host（單數，只測一台）→ ①②連線+認證（AuthenticationException → 「認證失敗」；SSHException/OSError → 「無法連線」）③ command -v /usr/bin/oscap 空 → 「未安裝 openscap-scanner」④ test -s <解析後 content> 非 OK → 「缺少 SCAP content」。四段任一失敗即 raise 不續探

§3 本棒工作順序

與 user 討論掃描指令細節與預期問題（user 明確要求的下一個議題）——素材見 §2，重點可能落在：profile id 是否對得上目標機實際 SSG 版本、content_path 用預設目錄推斷 vs 直接填檔案、sudo 白名單只涵蓋 /usr/bin/oscap 的邊界、逾時 3600s 是否合理
升級 192.168.50.123 上的 agent image（現行部署 0.2.8 不含 openscap connector）→ 見 §5，版號 bump 與升級步驟未定，需與 user 確認
端到端手測：設定頁填憑證 → 測試連線（probe）→ 建任務選 OpenSCAP + hosts + profile → 開始執行 → 驗證每台一份 HTML 報告進證據池
發現問題 → 開 Notion case 修 → 全綠後才走收尾（spec/SUMMARY/進版），等 user 下令

§4 測試環境（user 2026-07-29 已備妥）

角色	主機
管理機 / Agent 主機	`192.168.50.123`（agent 跑在該機 Docker）
目標主機 ×5	`192.168.50.123`（agent 宿主機自己）、`.151`、`.188`（DEV/STG DB）、`.171`、`.189`（POC DB）

各台已建 audit-scan 帳號 + 佈公鑰 + sudoers 白名單（NOPASSWD: /usr/bin/oscap）+ 裝 openscap-scanner 與 SSG content
部署腳本：123 上的 ~/deploy-openscap.sh（自包含、冪等可重跑；原始檔也在 user Mac 桌面）
稽核金鑰：123 上 ~/.ssh/openscap-audit-key（私鑰，要貼進 Guidant 設定頁）／.pub（已佈五台）
⚠️ 已知環境事實：.151/.188/.171/.189 四台共用同一組 SSH host key 指紋（同一 VM 映像克隆未重產）。connector 用 AutoAddPolicy 不會因此擋連線，但 CIS/STIG benchmark 會掃成 finding——屬預期，不是 bug

§5 Pre-flight（可直接複製）

# ① BE：branch / 未 push commits / 服務
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git rev-parse --abbrev-ref HEAD          # 應為 feature/instance-agent
git log --oneline origin/feature/instance-agent..HEAD | cat   # 應 10 筆
lsof -i :8000 | head                      # BE 是否在跑（沒跑：python main_app.py）

# ② agent repo：測試（必須帶 PYTHONPATH=.，repo 缺 conftest.py）
cd ~/Projects/Billows/Audit-Manager/evidence-agent
git status --short && PYTHONPATH=. poetry run pytest test/ -q

# ③ DEV DB 查 openscap seed（密碼查 .env DB_SECRET，勿寫進任何檔案）
psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev \
  -c "SELECT id,code,connection_type,status FROM config.detection_tools ORDER BY id"
# 預期：4 | openscap | SSH | available（id 必須是 4，agent factory 固定映射）

psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev \
  -c "SELECT dt.code, s.version, s.is_current FROM config.detection_tool_param_schemas s
      JOIN config.detection_tools dt ON dt.id = s.detection_tool_id WHERE dt.code='openscap'"

# ④ 目標主機就緒驗證（在 123 上跑，逐台換 IP）
for h in 192.168.50.123 192.168.50.151 192.168.50.188 192.168.50.171 192.168.50.189; do
  echo "=== $h ==="
  ssh -i ~/.ssh/openscap-audit-key -o StrictHostKeyChecking=no audit-scan@$h \
    'sudo /usr/bin/oscap --version | head -2; ls /usr/share/xml/scap/ssg/content/ | head -5; grep -E "^(ID|VERSION_ID)=" /etc/os-release'
done

# ⑤ agent 版本 / 容器狀態（在 123 上）
docker ps --filter name=agent --format '{{.Names}}\t{{.Image}}\t{{.Status}}'

§6 Agent image 升級（待確認，以下為推測步驟）

現行 123 部署的是 guidant-ai-agent:0.2.8，不含 openscap connector（connector 是 0.2.8 之後才進的四個 commit）。推測路徑（開工前先與 user 確認版號與出貨方式）：

# 開發機 build（依賴 .secrets/nexus.env，帳密查部署文件，不入版控）
cd ~/Projects/Billows/Audit-Manager/evidence-agent
IMAGE=guidant-ai-agent:0.2.9 ./rebuild.sh

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

# 123 上改 deploy/.env 的 AGENT_IMAGE 後起服務（必指定 service 名，避免 recreate 同 compose 的 DB）
docker compose up -d file-agent

待確認事項：①是否 bump 到 0.2.9（版號要同步五處：pyproject.toml、deploy/docker-compose.yml ×2、config/config.py 預設值——前次 e59c9fc 就是補這個漏）②123 是否能直接從開發機 docker save | ssh ③agent 心跳間隔吃部署機 agent.json 快取，改環境變數可能無效（memory reference_agent_heartbeat_interval_cache）。

§7 行為規範提醒

不切 branch（三個 repo 都已在 feature/instance-agent，branch 不對停下問 user）
不自動 push（BE 10 / FE 2 commits 未 push，等 user 明示）
顯式 git add <檔名>，禁用 -am
憑證絕不進版控：私鑰、DB 密碼、Nexus 帳密一律「查 .env / 部署文件」
改 agent code 要 rebuild image 才生效；改 BE service code 要重啟 BE（Claude 負責重啟，FE 由 user 自理）
BE 出錯先看 log：tail -200 log/app.log | grep -A 30 -i 'openscap\|detection\|Traceback\|ERROR'，不先問 user
收尾等命令：手測全綠後不自動寫 spec/SUMMARY/改 Notion 母案狀態/進版

§8 不在本棒 scope

install.sh 安裝精靈（user 明示最後再做）
Nessus / SonarQube connector、ARF findings 結構化解析、content 平台管理、host inventory 表、Push 模式（D7 明列第一版不做）
FR-057 全案收尾文件（spec / SUMMARY / 進版）——手測全綠 + user 下令才做
agent repo 補 pytest.ini/conftest.py（列 follow-up，不在本棒動）

§9 未 push commits 清單

BE feature/instance-agent（10 筆）：3a67e938 D3 實作澄清／c20b22a2 T-3.2 多檔取回／3e30d99d T-1.1 required 語意修正／7e93be34 前一棒 handoff／de979c30 setup_guide 落地鏈路／92b28070 big-feature-workflow skill／768aa289 T-1.1 migration seed／8c17aefa+81301ee1 mermaid 修復／3e39607e design 初版

FE feature/instance-agent（2 筆）：e77d303 T-1.3 select_or_text／d3dc91a T-1.2 設定頁欄位型態

agent（4 筆，working tree 乾淨）：b628b1c T-2.3 probe／21e157b T-2.2 run／2ec3c5b T-2.1 骨架／a14ab28 T-3.1 多檔上傳

§10 給 fresh session 的超短 prompt

請讀 ~/Projects/Billows/Audit-Manager/compliance-manager-be/docs/features/FR-057-2607-openscap-ssh-connector/handoff/2026-07-29-fr057-manual-test-handoff.md，
先過「🧭 原始需求」與 §0 冷接自檢（答不出先回去讀 design.md §1-§2），
再讀 §2（connector 實際掃描指令行為）與 §5 pre-flight。
你是手測驗收棒：先跟我討論掃描指令細節與預期問題，再升 123 上的 agent image，然後端到端手測。
不做收尾（spec/SUMMARY/進版/Notion 母案）除非我明確下令；不 push、不切 branch。