FR-059 檢測工具 Profile / Content 庫（掃描設定檔後台管理）— 設計文件

狀態：設計定稿（P1–P7 + D1–D10 共 17 項全數拍板）｜建立日期：2026-08-01｜FR-058 檢測工具擴充續作 討論稿（含流程圖）：discussion.html Notion 開卡：尚未進行——等 FR-058.7 開卡完成後接續（避免 Case No 跳號）；屆時 CM-992 需關聯本 FR

---

---

2.1 現況：每加一支 profile 的四步人工維運鏈

掃描工具（第一期 CINC Auditor / InSpec 與 GCB）執行時需要 profile / content 檔作為掃描依據。以 GCB（TWGCB 政府組態基準）為例，目前一支新 profile 要走完這條鏈才會出現在使用者的下拉選單裡：

四步裡沒有任何一步是一線工程師或客戶端管理員做得到的。現況投放狀態也印證維運成本：8 支 TWGCB profile 只投放到 DEV agent（192.168.50.123），STG / POC 的 agent 根本沒有這些檔案——選了下拉選項也掃不動。

2.2 CM-992 記錄的兩個限制（立案理由）

• 限制①：封閉網路無法投放 profile——封閉網路客戶的 agent 連不了外網，只能用「agent 本機路徑」型 profile；但目前沒有任何機制能把 profile 檔送進 agent container（content 掛載是人工 rsync，客戶做不來）。本案解法：profile 上傳到平台 → agent 透過既有 mTLS 通道拉檔＋cache，檔案遞送不再依賴外網或人工投放。
• 限制②：私有版本庫無憑證路徑——CINC 原生支援 URL 取 profile，但 params.profile 是 secret:false 純文字，token 塞進 URL 會洩漏到 FE 執行紀錄與稽核 log，私有 repo 的 profile 無路可走。本案解法：私有 profile 直接打包上傳成租戶自有 profile，不再需要從私有 repo 拉；URL 憑證機制明列不做（P5），需求出現再立案。

2.3 目標狀態

agent 只升級一次（學會「拉檔＋cache」），之後 content 的新增 / 改版 / 停用全部在後台完成——不再重建 agent image、不再人工 rsync、不再為選項寫 migration。公用版由 root 租戶維護全租戶可見，各租戶也能上傳自己的 profile，模式與流程管理（flow_templates）的雙軌完全一致。

2.4 端到端流程（文字版）

管理者在「掃描設定檔管理」頁上傳 profile（zip/tar/tar.gz/tgz 或登記 URL）
  → BE 驗證（格式 / 大小 / 結構含 inspec.yml / 防 slip・bomb）→ 計算 sha256 → 存平台儲存 + 落 config.detection_tool_profiles
  → 任務抽屜 profile 下拉動態列出庫內項目（按 detection_tool_id 過濾）
  → 使用者選庫內 profile 發起執行（params.profile = "profile:<uid>"）
  → 派工 _collect_pending_tasks() 偵測前綴、展開 _profile 內部 payload（uid/version/sha256/...）
  → agent 心跳領工 → 查本機 cache /data/content/cache/<uid>/v<version>/
      命中 → 直接用；miss → GET /api/1.0/agents/files/<uid>（FR-058.7 通道）拉檔
      → 重算 sha256 對帳（不符即 fail）→ 安全解壓進 cache 目錄
  → 把解壓後「目錄」餵給 cinc-auditor（四格式一條路徑，D4）→ 掃描 → 報告走既有 blob 回收鏈

---

P1–P7 為前期已拍板事項（討論稿 §2 原樣）；D1–D10 於 2026-08-01 全數定案。

---

相關 repo 皆已實查（附檔案座標）。結論：雙軌資料模型、檔案儲存、agent 安全通道全有現成拍板模式可抄；真正的新造點集中在「profile 庫本體」「派工展開」「agent cache」「上傳安全驗證」四處。

---

5.1 資料模型

新表 config.detection_tool_profiles（D1），Category C 雙軌形狀＋P4 版本模型：

CHECK 約束（source_type 與來源欄位互斥成對）：

• source_type='file' → file_id IS NOT NULL AND url IS NULL
• source_type='url' → url IS NOT NULL AND file_id IS NULL

唯一索引三組（形狀抄 2026-05-12-flow-template-management-schema.sql:70-73）：

1. (detection_tool_id, tenant_id, name, version) unique——租戶內同工具同名同版唯一
2. 公版名稱全域唯一 partial index（WHERE scope='SYSTEM' AND is_active）
3. 同名 is_current=TRUE 僅一筆的 partial unique——版本模型完整性

RLS 四段 policy：直接抄 scripts/sql/2026-06-29-fr042-tenant-scope-module-frames-flow-templates.sql:41-72（module_frames 版）——SELECT 的 scope='SYSTEM' 分支獨立放最前（公版人人可讀）＋super_admin＋path 子樹；INSERT WITH CHECK 堵 SYSTEM 偽造；UPDATE 要 USING＋WITH CHECK 兩段（防租戶把自己的列升級成公版）；DELETE 非 super 不能刪 SYSTEM。helper app_tenant_allowed_for_session() 已存在直接呼叫。

Migration 鐵則：新表必加 GRANT ... TO cm_app＋sequence 權限；語句加日期註解＋檔頭 -- Date:；收尾 INSERT public.schema_migrations；套用節奏依 D10（DEV 先行）。

ORM Model：繼承 BaseModel, TenantScopedMixinModel（jedi_common before_flush listener 自動填 tenant_id；SYSTEM 列由 root session 建立自然掛 ROOT）；Repo 繼承 BaseRepositoryImpl（session lazy，禁止 __init__ 內 get_session()）。

5.2 API 設計

管理頁六個動作（實際 route 命名與 schema 於 plan 階段依 docs/claude/api-patterns.md 定稿）：

三層防禦守門（抄 flow_templates 模式，§4 盤點）：

1. Route capability：讀寫四個 capability 全部 is_platform=false（比照 flow_template 平掛）——租戶管理員可建 / 改 / 停用自己的 TENANT profile 與 fork 公版，這正是雙軌功能的核心；「公版只有 root 能動」交給第 2 層 service guard 與第 3 層 RLS，不在 capability 層鎖（實際 capability 命名與角色矩陣掛法 plan 階段定；守門一律走 common/authz/，禁止另立 helper）。勘誤（2026-08-01，實作 session 發現）：初稿此處誤引 2026-06-30-compliance-framework-platform-capability.sql 的「寫入 is_platform=true」不對稱模式——那適用於「整個資源寫入天生 root-only」的純系統資產（框架目錄）；profile 庫是租戶可寫的雙軌資源，套該模式會讓租戶自助全滅、service guard 淪為死碼。
2. Service 層 guard：抄 app/flow_template_app_service.py:187-197 _guard_builtin_writable 模式，改判 scope=='SYSTEM' and not viewer_is_platform_admin() → ForbiddenError（root 判定 canonical＝common/authz/platform.py viewer_is_platform_admin()，不硬編 id）。
3. DB RLS 兜底（§5.1 四段 policy）。

審計欄位 enrich：response 有 created_user / updated_user（login_name）時必同時回 created_user_name / updated_user_name（nickname）——在 app service 層批次查 User.login_name → User.nickname，不在 infra 層 JOIN（pattern 見 app/oscal/service/ssp_docx_import_app_service.py:_enrich_party_user_org_names()）。

Error code：遵循 CLAUDE.md「<模組前綴>_<HTTP狀態碼><序號>」命名規則，落在 detection_tools 家族檔 common/code/detection_tools_error_code.py（前綴 DETECTION_TOOLS_，序號接續既有）。需新增（草列，plan 階段定稿序號）：

DDD 分層：route 不碰 session；app service public method 一律 @transaction；DB 操作走 domain service → repository interface → infra 實作；DI 於 di_containers/ 對應 container wiring。

5.3 上傳驗證管線（本案新造點）

現況全 repo 無壓縮檔安全處理先例（§4），本管線為第一個實作，設計如下：

格式偵測：副檔名白名單（.zip / .tar / .tar.gz / .tgz）＋ magic number 雙重確認（zip=PK\x03\x04、gzip=\x1f\x8b、tar=offset 257 的 ustar），不符即拒收。

檢查順序（streaming，全程不落地解壓；D4 / D8）：

1. 大小上限——Content-Length 預檢＋實讀累計雙保險，超過 50MB 即斷。
2. 開檔——依格式用 tarfile 或 zipfile 開啟（兩者皆標準庫；zip 需 seekable 來源，以記憶體 / spooled buffer 承接）。
3. 逐 entry 安全檢查：
   • 防 path traversal（slip）：entry 路徑正規化後不得為絕對路徑、不得含 .. 逸出；tar 的 symlink / hardlink entry 一律拒收。
   • 防 bomb：entry 數上限＋宣告解壓總量上限＋壓縮比上限（實際數值 plan 階段定，量級參考：現有 TWGCB 單支數百 KB）。
4. 結構驗證——頂層或一層目錄內須有 inspec.yml（D8：只驗結構，不驗 profile 語意正確性；正確性由掃描執行結果反映，界線明寫）。
5. sha256 計算——對原始壓縮檔 bytes 計算，落 detection_tool_profiles.sha256 作 agent 對帳信任根。
6. 存儲——SYSTEM 公版走 upload_system_file()、TENANT 走 upload_files_for_tenant()（§4 canonical service，不另造）。

兩種格式共防：tar 系與 zip 的 slip / bomb 檢查邏輯共用同一套 entry 檢查器（僅迭代介面不同），避免 zip 路徑漏防。

5.4 下發機制（核心）

派工時 _collect_pending_tasks()（app/remote_agent/service/agent_enrollment_service.py:241-249）組 payload 階段，偵測 params.profile 的值並分流：

agent cache 細節（D4 / D9）：

• 目錄結構 /data/content/cache/<uid>/v<version>/，存解壓後內容；解壓完成後寫入完成標記（含來源壓縮檔 sha256），命中判斷＝目錄存在＋標記 sha256 與 _profile.sha256 一致。
• agent 端解壓同樣做 slip / bomb 防護（BE 驗過不代表 agent 可信任傳輸後內容——對帳通過後解壓仍走安全解壓器）。
• cache key 含 version → 版本更新自然失效（舊版目錄不再被引用）；agent 重啟不清；第一期無上限＋手動清理指引，LRU 列 follow-up（D9）。

取檔授權（profile_ref resolver，D6）：復用 058.7 端點、授權 resolver 分流——profile_ref claim 的驗證語意＝「該 uid 是該 agent 名下 pending / running 任務 params 中引用的 profile 檔」（cache miss 拉檔發生在任務執行中，任務綁定天然成立）。本案實作此 resolver；前置條件＝058.7 把授權驗證做成可插拔 resolver 介面（須在該案開工前談定、寫進其 T-7.1 規格）。

具體介面契約（兩案凍結契約）：resolver 是一個 callable，收 (agent_uid, file_uid)，回傳「認不認這個 uid」（bool 或含理由的結果物件）；端點授權段逐一詢問模組層 resolver 清單（058.7 落地 _FILE_ACCESS_RESOLVERS = [source_file_resolver]），任一認可即放行、全部不認才拒絕。本案 T-2.3 的動作＝實作 profile_ref_resolver 並 append 進該清單，不動端點本體。此契約 2026-08-01 已由 058.7 協調者下達其 T-7.1 執行者，D6 前置條件已滿足（058.7 側並會留註解標明「FR-059 將 append profile_ref resolver，resolver 介面即兩案契約，不要在重構中收掉」）。

5.5 下拉動態化

param_schema 的 profile 欄位加宣告 "options_source": "profile_library"（type 維持 select_or_text，P6）——FE 看到此宣告，改呼叫 profile menu API（帶 detection_tool_id 過濾，P7）動態組 options，不再讀死的 options 陣列。

• 機制 tool-agnostic：未來任何工具任何欄位要接庫，seed 宣告即可，FE 零改（§5.7 checklist 的基礎）。
• param_schema 升版動作：inspec 與 gcb 各 INSERT 新 version（舊版 is_current=FALSE，照該表既有版本紀律），新版 profile 欄位帶 options_source 宣告並拿掉靜態 options——8 支 TWGCB 容器路徑選項與 dev-sec 2 條 URL 選項由搬遷 seed（§5.6）轉為庫資料承接。升版 migration 套用節奏依 D10。

5.6 搬遷 seed（P3 / D7）

• 顯示名稱沿用現行 param_schema options 的 label——確保下拉零回歸（P3 驗收條件）。
• 所屬工具：TWGCB 8 支綁 gcb、dev-sec 2 條綁 inspec（P7 分池）。
• 執行節奏：DEV 先行驗收，STG / POC 等決策者明示放行（D10）。

5.7 新工具接入 checklist（後續接工具照表操課，不用考古）

⑴ 同形態新工具（形態 A：content 在 agent 本機讀取）＝零開發接入，三步驟

前提：該工具的 connector 已存在、且其掃描引擎吃「agent 本機 content」（同 CINC / GCB 形態）。

BE / FE / agent 程式碼零改——profile 表帶 detection_tool_id 天然分池（P7）、FE 靠 options_source 宣告驅動（§5.5）、agent 的 _profile 處理與 cache 是 tool-agnostic 通用路徑（§5.4）。

⑵ 異形態工具（如 OpenSCAP content 在目標主機、ZAP policy 在客戶 server）

• profile 庫本體全形態共用：儲存（file / url 雙軌）、版本模型、雙軌 scope、管理頁與全部管理 API 一概不動、直接沿用；表結構不改（P1 tool-agnostic 設計的意義所在）。
• 只需為該形態新增「下發策略」段——即派工展開 _profile 之後「檔案最後一哩怎麼到位」的策略。例：OpenSCAP 型＝agent 拉檔後經 SSH 推送至目標主機再執行；ZAP 型＝透過客戶 ZAP daemon 的 API 匯入 policy。接入時要寫的東西＝該形態的下發策略設計（agent 端行為）＋connector 對接；不要動 profile 庫表與管理 API。
• 接入時機的判斷素材：該工具的 content 由誰讀（agent / 目標主機 / 第三方 daemon）——是形態 A 就走 ⑴，不是就寫下發策略走 ⑵。

---

依賴鏈：FR-059.1（BE 地基）→ FR-059.2（下發整合）∥ FR-059.4（FE，管理頁部分）→ FR-059.3（Agent 端，硬依賴 058.7 通道）。

並行契約凍結項（FR-058 arc 既有教訓：並行前先凍結契約）：

1. 庫參照格式 profile:<uid>（D2）
2. _profile payload 形狀（file 型 {uid, version, sha256, source_type, file_name}；url 型 {uid, source_type, url}）
3. cache 目錄結構 /data/content/cache/<uid>/v<version>/（存解壓後內容＋完成標記）
4. 取檔端點的 profile_ref 授權 resolver 介面（D6，已於 2026-08-01 談定：callable 收 (agent_uid, file_uid) 回傳認可與否，端點逐一詢問 _FILE_ACCESS_RESOLVERS 清單、任一認可放行；詳見 §5.4）

FR-059.1 BE 地基 — 依賴：無（決策已全數定案）

FR-059.2 下發整合 — 依賴：FR-059.1；058.7 resolver 介面談定（D6）

FR-059.3 Agent 端 — 依賴：058.7 通道先存在（硬依賴）；FR-059.2 契約凍結

FR-059.4 FE — 依賴：FR-059.1 API 落 DEV（管理頁）；FR-059.2（下拉）

後續版（非本案第一版範圍，D5）：新機制上線驗收通過後的下一版，拿掉 agent /data/content bind mount 與 param_schema 靜態 options 舊路（手填容器路徑能力因 P6 永遠保留）。

---

1. 上傳四格式：管理頁分別上傳 zip / tar / tar.gz / tgz 四種格式的 profile → 全部通過驗證入庫；惡意樣本（path traversal / 解壓 bomb / 無 inspec.yml / 超過 50MB / 假副檔名）全數被擋且錯誤訊息明確可辨識。
2. 下拉即選：上傳後任務抽屜下拉立即可選（不經任何 migration / 部署動作）；GCB 抽屜只見 gcb 池、CINC 只見 inspec 池（P7）。
3. 派工取檔全鏈：選庫內 file 型 profile 發起執行 → agent cache miss → 走 058.7 通道拉檔 → sha256 對帳通過 → 安全解壓 → 解壓目錄餵 cinc-auditor → 掃描成功、報告回收進證據池。
4. cache 命中：同 profile 再次派工 → cache 命中不重拉（agent log 佐證）；版更後派工 → 因 cache key 含 version 自然 miss、拉新版。
5. 對帳防線：sha256 不符（竄改模擬）→ 掃描 fail 且錯誤可辨識，不靜默使用髒檔（FR-039 不變式）。
6. 三層取值相容：庫內 url 型（dev-sec 搬遷公版）與現場手填值照現行為執行成功（P6 零破壞）。
7. 雙軌守門：公版 fork 成租戶自有副本可編輯；非 root 對公版寫入被擋（403）；租戶 A 看不到租戶 B 的自有 profile（RLS）。
8. 封閉網路情境模擬：agent 無外網、僅靠平台通道取得 profile 完成掃描——CM-992 限制①的直接驗證。
9. 下拉零回歸：搬遷 seed（P3 / D7）＋param_schema 升版後，下拉內容與搬遷前完全一致（8 支 TWGCB＋2 條 dev-sec 名稱不變）。
10. 三環境節奏：以上驗收全數在 DEV 完成；STG / POC 的 migration / seed / agent 部署一律等決策者明示放行（D10 環境異動鐵律）。