工具帳密留在客戶機房，存了什麼檔自己看得到

狀態：設計定案（D1～D11），已開卡待派｜日期：2026-10-22｜母卡 CM-3026、子卡 CM-3027～CM-3036｜前作：FR-156（入場券＋8444 門）、FR-056 D9（被推翻）、FR-039／066.6（Agent 儲存） 討論稿（PM 意見、選項推演）：discussion.html｜雛形：prototype/index.html（六幕，右上可切「IT 管理員／稽核人員」身分看權限差異） 開發 branch：四個 repo 2026-10-22 查皆在 feature/FR-139；runner 開工 git branch --show-current 再確認，不對就停下問，不切

🔴 這份是設計決策，不是現況。 內文的行號與座標停在 2026-10-22 定稿當時，之後實作改動的結果不回頭改寫這裡——上線後的現況看 SPEC 頁。

PM 判定檢測工具的連線帳密是客戶機敏資料，不該存在我們主系統。現況（FR-056 D9）是主系統 config.tenant_detection_tool_configs.credentials_encrypted 存 Fernet 密文，派工時解密塞進派工單下發，Agent 用完即丟。落地版客戶的立場是「能打進我內網主機的密碼，為什麼在你們資料庫裡」。

決策者再加一項：客戶部署時會把 Agent 當儲存設備，證據檔本體落在 Agent 機的 SeaweedFS（主系統只有 storage_type=remote_agent 的參照列；DEV 實查 186 列），但 Agent 那邊沒有任何畫面，客戶想知道「這台存了什麼」只能問我們。

本案兩件事：帳密搬 Agent 本機、Agent 開一個主控台讓人看檔。兩件事共用同一道門：FR-156 E1 做好的五分鐘入場券＋Agent 8444 瀏覽器門。

做完之後

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
sequenceDiagram
    participant U as 使用者瀏覽器
    participant M as 主系統
    participant AG as Agent 8444（瀏覽器門）
    U->>M: Agent 管理頁按「開啟設定頁」或「瀏覽檔案」
    M->>M: 查他有哪些能力點：Agent 設定？Agent 檔案？
    M-->>U: 五分鐘入場券（誰、租戶、哪台、scope=[configure, files]）
    U->>AG: 新分頁開 https://agent:8444/console#票
    AG->>AG: 用雲端公鑰驗票：這台嗎、過期嗎、jti 用過嗎
    AG-->>U: 發 30 分鐘 HttpOnly session（記 scope），抹掉網址上的票
    U->>AG: 總覽／檔案（files）、檢測工具（configure）
    AG->>AG: 每個 API 先看 session 的 scope，不在範圍回 403
    AG->>AG: 帳密 Fernet 加密存本機；操作寫本機稽核
    AG->>M: 心跳：configured_tools、storage、console_events

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart LR
  A1[Agent 主控台<br/>檢測工具分頁] -->|填寫| A2[(Agent 本機<br/>tool-credentials.enc)]
  A3[主系統派工單<br/>不帶 _credentials] --> A4[Agent task_executor<br/>依工具代號讀本機]
  A2 --> A4
  A2 -.心跳只報已設定／最後測試.-> A5[主系統<br/>remote_agents.configured_tools]
  A5 --> A6[工具設定頁<br/>各 Agent 狀態表]
  A5 --> A7[派工前檢查<br/>沒設定立即失敗]

整案一句話：使用者在主系統 Agent 清單按一下，新分頁直接進到 Agent 機上的主控台（免再登入）；有「Agent 設定」權限的人在那裡填檢測工具帳密，有「Agent 檔案」權限的人在那裡看這台存了哪些檔；主系統從此不存帳密，派工時 Agent 用自己機上的那份。

依賴：A → B 與 C 平行 → C 的派工改道 → D 的三頁改版與搬家 → E。FR-156 E1 已 Done，本案直接接上。決策者功課：無。

5.1 A 跳轉與主控台殼

能力點（主線 phase=active migration，照 scripts/sql/2026-10-10-fr134-source-scan-capabilities.sql 形狀）

• capabilities.action 若有 CHECK 約束要先查（\d public.capabilities），新值不在清單就一併放寬。
• 出廠範本角色：「稽核員」補 browse-files；「負責人」「審核者」「瀏覽者」不補（決策者要加去角色管理勾）。role_capability_patterns 既有 detection.*.* 的範本會自動涵蓋。
• CAPABILITY_CATALOG/VERSION 加一。

簽票端點（jedi-remote-agent，ROUTE_TABLE 加 ("/remote-agents/<string:uid>/console-ticket", RemoteAgentConsoleTicketRoute, AUTH_ADMIN)；BE _ADMIN_CAPABILITIES["RemoteAgentConsoleTicketRoute.post"] = (configure, browse-files)）：

POST /api/1.0/remote-agents/{uid}/console-ticket
→ scope = [s for s in ("configure","files") if capability_checker(對應能力點)]
→ agent_ticket_service.issue(purpose="console_login", agent_uid, subject=login_name,
      tenant_id, origin=request Origin, scope=scope, display_name=nickname)
← {url: "<agent_url>/console#<ticket>", expires_in: 300, scope: [...]}

票 claims（凍結）：aud=agent:<uid>、sub=<login_name>、tenant_id、purpose=console_login、jti、origin、scope: ["configure","files"]（子集）、display_name、exp（5 分鐘）。scope 空就不簽（403）。

Agent 8444 主控台路由（browser_plane_server.py 已 200 餘行，新路由放 core/console/ 套件，create_browser_app 只掛 blueprint）：

• 票放 URL # 後：前端載入後讀 location.hash，POST 換 session，history.replaceState 抹掉。
• jti 一次性：記憶體 set，五分鐘後淘汰；Agent 重啟後視窗可接受（票只五分鐘），不持久化。
• session 存記憶體；Agent 重啟全部失效，使用者回主系統再按一次即可。
• 不在 scope 的 API 回 403 {error_code: "AGENT_CONSOLE_SCOPE_DENIED"}；前端照 me.scope 不渲染該分頁。
• CORS：主控台與 API 同源（都在 8444），不需 CORS；/scan-input 的 CORS 處理不動。

FE console 入口（D5）：compliance-manager-fe/console/（index.html、main.js、App.vue、views/{Overview,Tools,Files}.vue、api.js）；vite.console.config.js：root: 'console'、base: '/console/'、build.outDir: '../dist-console'，alias @ 同主站以共用 src/assets 的設計 token、src/config/locales/i18n（只載 remote-agent.json、plugin_manage 與新 agent-console.json）、PrimeVue 元件按需 import；不載 Pinia 使用者 store、不載主站 router。package.json 加 build:CONSOLE。evidence-agent build_agent_bundle.sh 加一步：FE_CONSOLE_DIST（預設 ../compliance-manager-fe/dist-console）存在才複製進 assets/console/，不存在 build 失敗（不是略過）。體積上限 2 MB（gzip 前），量過寫進回寫。

5.2 B 檔案瀏覽

GET /console/api/files?q=<檔名包含>&from=<date>&to=<date>&uploader=<login>&sort=created_at|size&order=desc&page=1&size=50
← {total, items: [{uid, file_name, size, mimetype, storage_type, sha256, created_at, created_user}], stats: {file_count, bytes_used, backend, backend_healthy, disk_free_bytes, scan_input_bytes, vulndb_bytes}}
GET /console/api/files/<uid>/download      → Content-Disposition attachment，串流自後端（FileUploadService 既有 adapter）
GET /console/api/files/uploaders            → 上傳者清單（distinct created_user）給篩選用

• 讀 Agent SQLite upload_files，只列 storage_scope='customer' 的證據檔；源碼暫存（scan-input/）與弱點資料（vulndb/）只算目錄大小進 stats，不列。
• 下載寫本機稽核 file_downloaded {uid, file_name, sha256}。
• 沒有刪除端點（D6）；沒有專案／證據欄（D7）。
• 上傳者顯示 created_user（主系統 login name）；暱稱 Agent 沒有，第一版就顯示 login name。

5.3 C 工具帳密搬 Agent

表單定義下發（D3）：BE core/plugins/_agent_tool_schemas.py 提供 tool_schemas_heartbeat_extra()→心跳回應多 tool_schemas_version（＝config.detection_tools 最大 updated_at 的 epoch 或 CAPABILITY_CATALOG 式計數）；新端點 GET /api/1.0/agents/tool-schemas（AUTH_AGENT，掛在 jedi-remote-agent ROUTE_TABLE，資料由宿主 payload_provider 風格的 tool_schemas_provider 注入）回：

{version, tools: [{code, name, name_i18n: {zh_Hant_TW, en}, requires_credentials, requires_target_host,
                   config_field_schema: [...原樣...], credential_group_schema: {...原樣或 null}}]}

Agent _observe_tool_schemas：版本與 /data/tool-schemas.json 不同就拉一次、原子寫入。主控台工具頁從這份畫表單；拉不到時工具頁顯示「尚未取得工具目錄，請稍候（Agent 需先與主系統完成一次心跳）」。

Agent 本機儲存（D11）：core/credential_store.py

• secrets/secrets.key：第一次寫入時 Fernet.generate_key()，os.open(..., 0o600)；讀取時檢查 mode 不是 0600 就警告（不拒絕）。
• secrets/tool-credentials.enc：Fernet 密文，解開是 {<tool_code>: {fields: {...所有連線欄位含非機敏...}, configured_at, configured_by, last_test_at, last_test_result, last_test_message}}；整檔讀寫、寫入走 temp＋os.replace。
• API：get(code) -> dict|None、put(code, fields, actor)、clear(code, actor)、status() -> {code: {configured_at, last_test_at, last_test_result}}（不含欄位值）、mark_test(code, ok, message)。
• 日誌與稽核永不印欄位值；status() 是心跳 configured_tools 的來源。

主控台工具 API：

GET  /console/api/tools                      → 目錄（tool-schemas.json）＋ status()
GET  /console/api/tools/<code>               → 非機敏欄位回顯、機敏欄位只回 {set: true}
PUT  /console/api/tools/<code> body {fields} → 機敏欄位留空＝不改（與主系統 has_credentials 慣例同）；寫稽核 credential_set
DELETE /console/api/tools/<code>             → clear；寫稽核 credential_cleared
POST /console/api/tools/<code>/test body {target_host?, credential_group?} → 用本機帳密呼叫 connector.probe()（與 api/detection/routes/detection_route.py 同一條路，差別是帳密來源），回 {ok, message, duration_ms}，mark_test

欄位驗證照 config_field_schema（required、type）在 Agent 做一次；gcb／inspec 的 credential_group_schema 兩組（SSH／WinRM）各自存在 fields 下的群組 key，形狀與主系統 field_values 一致，派工時 connector 不用改讀法。

派工改道（C2，jedi-detection detection_orchestration_service）：

if agent.credential_store:                      # 新版 Agent（心跳自報）
    if tool_code not in agent.configured_tools:  # 心跳自報的 status()
        → execution failed, error DETECTION_AGENT_TOOL_NOT_CONFIGURED,
          message「Agent {name} 尚未設定 {tool} 連線，請至該台設定頁填寫」
    params 不帶 _credentials
else:                                           # 舊版 Agent，搬家過渡
    照 FR-056 D9 解密下發（直到 D2 搬家完成清掉密文）

Agent task_executor：credentials = params.pop("_credentials", None) or credential_store.get(code)；兩者皆無→failed 同一句話。probe 路由（8443 /detection/probe）同樣：body 沒帶 credentials 就讀本機。主系統「測試連線」改：選一台 Agent→POST /detection-tools/configs/<uid>/test-connection {agent_uid, target_host?, credential_group?} 不帶帳密→Agent 本機帳密 probe→結果寫 tenant_detection_tool_configs.last_test_*（與主控台本機測試各自記錄，兩邊都能測）。

心跳回報：payload configured_tools: {<code>: {configured_at, last_test_at, last_test_result}}、credential_store: true；雲端 remote_agents.configured_tools JSONB、credential_store BOOLEAN DEFAULT false（套件 migrations/010-remote-agent-console.sql）。

5.4 D 主系統端配合

三頁改版（D1 卡）

• RemoteAgentManage.vue：加「已設定工具」欄（configured_tools 的 key 綠標、目錄內其餘工具灰標、tooltip 最後測試）、「儲存」欄（storage_stats：{file_count} 檔 · {bytes_used} · {backend}）；按鈕：$can(configure)→「開啟設定頁」、否則 $can(browse-files)→「瀏覽檔案」；只有 browse-files 的人：隱藏新增／啟停／撤銷／註冊 token 區塊與「已設定工具」欄；離線的 Agent 按鈕 disabled。按下→POST console-ticket→window.open(url, '_blank', 'noopener')。按鈕旁提示「需在可連到 Agent 的網路」。
• ToolPluginManage.vue（超標）：對話框連線欄位整段移除，改掛新子元件 ToolAgentStatusTable.vue（每台 Agent 一列：名稱、已設定／未設定、最後測試、「前往設定」＝同一支簽票）；「測試連線」改先選 Agent（只有一台自動選）；detectionCredentialFields.js 不再被工具頁 import（主控台 console 入口改用它，搬到 src/utils/ 共用位置不動）。
• BE 清單 API（jedi-remote-agent RemoteAgentManageRoute）serializer 加 configured_tools、storage_stats、credential_store。

搬家（D2 卡）

升級後 Agent 第一次心跳 credential_store=true 且 remote_agents.credential_store 由 false→true
→ 宿主 lifecycle hook：對該租戶每支 credentials_encrypted 非空的工具，建 agent_tasks
    type="credential_handover", params={tools: {<code>: {fields: field_values ∪ 解密後機敏欄位}}}（既有 mTLS pending_tasks 通道）
→ Agent 執行器收到：credential_store.put 每支（已設定的不覆蓋，回執 skipped）→ result {stored:[...], skipped:[...]}
→ 雲端 result handler：tenant_detection_tool_configs.handover[<agent_uid>] = {at, stored, skipped}
→ 每次回執後檢查：該租戶所有 enabled 且 credential_store=true 的 Agent 都回執了
    → credentials_encrypted=NULL、field_values 只留非連線欄位（啟用等）、status='on_agent'、稽核 CREDENTIALS_HANDED_OVER
→ Agent 清單「已設定工具」欄在過渡期顯示「帳密搬家中：2/3 台」（有 handover 未齊）

• 租戶還有 Agent 沒升級：主系統等；期間舊 Agent 照舊收帶帳密的派工單（§5.3 的 else 分支）。
• 已撤銷／停用的 Agent 不算在「全部回執」分母。
• 重跑安全：Agent 端已設定的工具不覆蓋；雲端 handover 以 agent_uid 為 key 冪等。

稽核回傳（D3 卡）

• Agent 本機 console-audit.jsonl（append，每列 {at, actor, action, tool|file_uid, file_name, sha256, ok}），心跳帶 console_events: [...上次心跳後新增的...]，雲端回 console_events_ack: <最後一筆 at> 後 Agent 才前進游標（沒 ack 下次重送，雲端以 (agent_uid, at, action) 去重）。
• 雲端寫既有稽核 audit()：事件碼 6085～6088，actor=<sub>、agent_uid、tool／file_uid；FE 稽核報表的事件碼 i18n 補四條。

5.5 E 文件與出貨

SPEC 三頁（Agent 管理、檢測工具、新頁「Agent 主控台」）；手冊「檢測工具設定」改成主控台流程、加「誰能開」（兩個能力點）、「檔案頁看得到這台全部檔案」限制、憑證警告處理；安裝文件 8444 埠與 FE console 體積；docs/claude/domain-capabilities.md 補 credential_store、console session、tool_schemas_provider 三列；出貨基線重產（本案主線 migration：能力點 1 支、tenant_detection_tool_configs.handover 1 支）。

5.6 安全規則對照

排序以「決策者何時看得到畫面」為準：先讓主控台開得出來、檔案頁有真資料（Agent 索引本來就有東西），再做帳密。同批依卡號串行。

決策者功課（開工前）：無。角色管理裡要不要給哪些角色「Agent 檔案」，上線後由客戶管理員自己勾；出廠只補「稽核員」。