客戶程式碼不進主系統，弱點資料天天自己更新

狀態：設計定案（D1～D12），已開卡待派｜日期：2026-10-21｜母卡 CM-2989、子卡 CM-2990～CM-3001｜前作：FR-134（功能完成未進版）、FR-039／056／058.7／059.3／066 討論稿（PM 意見、選項推演）：discussion.html｜雛形：prototype/index.html（五幕） 開發 branch：四個 repo 以開工當下 current branch 為準（runner 自己 git branch --show-current，不對就停下問）

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

PM 判定掃客戶程式碼的工具不能預設放在我們的主系統，而 FR-134 做出來的第三方元件掃描正是顧問把客戶原始碼壓縮檔上傳到主系統、由主系統沙箱掃。同時弱點資料更新現在要人手（裝機帶一份、管理員上傳、或按「檢查更新」），PM 判定弱點更新太快不能靠人。

本案兩件事：執行位置搬 Agent、弱點資料全自動。第三件事（工具帳密搬 Agent 端）獨立成 FR-157。

搬完之後

%%{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 API as 主系統 api
    participant AG as Agent 8444（瀏覽器門）
    participant AGC as Agent 心跳
    participant DB as 主系統 DB
    U->>API: POST /source-scan/targets/{uid}/scans（agent_uid、source_type）
    API->>DB: 建 source_scans（status=awaiting_upload）
    API-->>U: 回 scan_uid ＋ upload_ticket（5 分鐘、綁 agent＋scan）
    U->>AG: PUT /scan-input/{scan_uid}（Bearer ticket，檔案串流）
    AG->>AG: 落 /data/scan-input/{scan_uid}/，算 sha256
    AG-->>U: 回 {size_bytes, sha256}
    U->>API: POST /source-scan/scans/{uid}/start（sha256）
    API->>DB: source_scans→queued；建 agent_tasks（type=sbom_scan）
    AGC->>API: 心跳 → pending_tasks
    AGC->>AGC: 安全解壓 → syft → trivy／grype／osv（讀本機 vulndb/current）
    AGC->>API: POST /agents/tasks/{uid}/result（SBOM 多格式＋三家原始 JSON＋vulndb_date）
    API->>API: 正規化（既有 normalize/）→ 六區塊統計
    API->>DB: components／findings／summary（done）
    U->>API: 看結果、匯出、歷次比對（不變）

守住的邊界：主系統從頭到尾沒有碰過原始碼。瀏覽器開發者工具看得到上傳請求目的地是 Agent 的 IP。

整案一句話：顧問多選一台 Agent，程式碼直接傳到那台機器上掃；弱點資料我們每天發、主系統自己抓、Agent 自己來拿，沒有人要按任何按鈕。

依賴：A → B → C 串行；D 與 A 平行；E 要 D；F 要 E 驗過；G 最後。

5.1 A 每日發布鏈

%%{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
  subgraph JT["我們（每日 03:00，GitLab schedule → 188 runner）"]
    UP["上游：Trivy DB／Grype DB／OSV／KEV／EPSS"] --> B1["build_vulndb_bundle.sh（既有）"]
    B1 --> LC["License Center 簽 vulndb_manifest（既有）"]
    LC --> R2["R2：guidant-vulndb-YYYYMMDD.tar.zst<br/>latest.json"]
  end
  subgraph CUST["客戶（連網）"]
    R2 -->|"每日 GET latest.json"| API["主系統 worker：驗章→volume→刪舊→紀錄"]
    API -->|"心跳回應 vulndb{date,sha256}"| AG["Agent：較舊就 GET bundle→驗章→切換→刪舊"]
  end
  subgraph CLOSED["客戶（封閉）"]
    ADM["管理員上傳更新包（既有）"] --> API2["主系統"] -->|同一條心跳| AG2["Agent"]
  end

CI job（BE .gitlab-ci.yml 新增，獨立於出版四 stage）：

vulndb-publish:
  stage: build
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule" && $VULNDB_PUBLISH == "true"
  script:
    - scripts/build/build_vulndb_bundle.sh --out .build/vulndb      # 既有，含送 LC 簽
    - scripts/build/publish_vulndb_bundle.sh .build/vulndb          # 新：上傳 R2＋寫 latest.json＋清 30 天外

• GitLab 排程：每日 03:00 Asia/Taipei，變數 VULNDB_PUBLISH=true；出版 pipeline 的 workflow.rules 加一條 schedule 放行但其他 job 以 $VULNDB_PUBLISH 排除。
• publish_vulndb_bundle.sh（新）：用 rclone 或 aws s3（S3 相容）上傳到 R2 bucket guidant-vulndb；憑證走 CI 變數 R2_ACCESS_KEY_ID／R2_SECRET_ACCESS_KEY／R2_ENDPOINT（新 env var，先 grep 確認無同義；值不入版控）；上傳完才覆寫 latest.json（先包後索引，避免索引指到半個包）；刪 30 天前的包。
• latest.json 契約（凍結，產品端 check_update 消費）：

{"bundle_date":"2026-10-20","file":"guidant-vulndb-20261020.tar.zst","sha256":"…","size_bytes":503316480,
 "sources":{"trivy":{"date":"2026-10-20","count":312480},"grype":{…},"osv":{…},"kev":{…},"epss":{…}},
 "tool_versions":{"syft":"1.54.0","trivy":"0.75.0","grype":"0.120.0","osv-scanner":"2.6.0"}}

• 自訂網域 vulndb.jedicotech.com 綁 bucket（Cloudflare 同帳號）；bucket 公開讀。
• 失敗可見性：pipeline 紅走既有通知；主系統連三天沒抓到新包，設定頁黃字「更新站 3 天無新資料」。
• 鑰：一律正式鑰（kid f3b562a6d9755527，FR-134 §5.2）。開發鑰簽的包產品與 Agent 都會拒收（FR-134 已踩）。

5.2 B 主系統自動抓

改三處，皆在既有碼內：

1. config/config.py:239 VULNDB_UPDATE_URL 預設改 https://vulndb.jedicotech.com；.env sample 與 deployment-env.md 同步補一行。
2. vulndb_update_service 的每日開關預設 true（存在 system_config 的那筆初值；migration 補 seed）；check_update 連不到站時寫 vulndb_updates 一列 status=skipped、error=無法連線更新站，不拋錯不寄信；設定頁最近一列是 skipped 時顯示黃字並附「封閉網路請改用上傳更新包」。
3. _prune(keep) 改為刪除所有非 keep 的日期目錄（現況保留）。進行中的掃描已不在主系統跑（D2），刪舊無競態。

5.3 C Agent 同步

心跳契約擴充（jedi_remote_agent 心跳回應 data）：

"vulndb": {"bundle_date": "2026-10-20", "sha256": "<tar.zst 的 sha256>", "size_bytes": 503316480}

無弱點資料時 vulndb: null。心跳 payload（Agent → 雲端）加 vulndb_date（字串或 null）與 vulndb_sync_error（字串或 null，例 磁碟不足：剩 2.1GB，需 6GB）。雲端寫 remote_agents.vulndb_date、remote_agents.vulndb_sync_error（migration 兩欄）。沒帶就不動現值（與 capabilities 相容契約同款）。

控制面端點（jedi_remote_agent 或 jedi_source_scan 掛在 agents blueprint）：GET /api/1.0/agents/vulndb/bundle → 通行證驗身 → 串流回 current 對應的 .tar.zst（主系統 volume 要保留原包，_switch 時順便把包留在 <date>/bundle.tar.zst）。回 X-Bundle-Date、X-Bundle-Sha256 標頭。

Agent 端 core/vulndb_sync.py（新，照 profile_cache.py pattern）：

Agent 磁碟佈局：/data/vulndb/{<date>/, current -> <date>, .incoming/, .staging/}，compose named volume agent-vulndb，原生安裝版 /var/lib/guidant-agent/vulndb。

UI：Agent 清單加「弱點資料」（日期＋距今 tag：≤30 綠、31～90 黃、>90 紅、無則「尚未同步」＋原因）、「最後同步」；上方統計卡「弱點資料已同步 n/N」「主系統弱點資料 日期」。設定頁弱點資料加「Agent 同步狀態」表（雛形幕 3、4）。

5.4 D Agent 掃描執行器

core/task_executor_connectors/sbom_scan.py（新）：

tools-manifest 四列：id／版本／sha256／URL 照既有格式；fetch_bundle_tools.sh 的「解成目錄樹」對這四支就是放進 tools/bin/。sha256 取 GitHub release 的 checksums 檔實值。

5.5 E 源碼直傳 Agent

上傳票（主系統簽，jedi_remote_agent 新 agent_ticket_service，用既有資料面 JWT 私鑰 RS256）：

{"iss":"guidant-cloud","aud":"agent:<agent_uid>","sub":"<user login_name>","tenant_id":102,
 "purpose":"scan_upload","scan_uid":"<uid>","max_bytes":104857600,"jti":"<uuid>","exp":<now+300>}

• 端點 POST /source-scan/targets/{uid}/scans（既有建掃描端點改）回 {scan_uid, upload: {url: "https://<agent base host>:8444/scan-input/<scan_uid>", ticket}}；agent base host 取 remote_agents.base_url 的 host。
• FR-157 的登入票 purpose:"console_login"，同一支服務。

Agent 8444 listener（core/browser_plane_server.py 新，與 data_plane_server.py 同款 Flask thread）：

精靈（WizardStepSource.vue）：上方加「在哪台 Agent 上掃描」單選（來源 GET /remote-agents?capability=sbom_scan&online=true，過濾 vulndb_date 非空；一台自動選隱藏區塊；零台顯示「本租戶尚無可掃描的 Agent」並擋下一步）；上傳框下方直傳提示（雛形幕 1）；送出時先建掃描拿票，PUT 到票的 url（進度條顯示目的地，雛形幕 2），成功後 POST /source-scan/scans/{uid}/start 帶 sha256。CORS／憑證錯誤→白話訊息「無法連到 Agent 192.168.x.x，請確認您在客戶內網並已信任 Agent 憑證」。

掃描 job 拆分（jedi_source_scan）：

• source_scans 加 agent_uid、agent_local_uid、狀態多 awaiting_upload（建了還沒傳完；1 小時沒 start 由既有清理排程改 failed）。
• 派工半：start → 建 agent_tasks(type=sbom-scan, params) → queued。
• 結果半：Agent POST /agents/tasks/{uid}/result 既有路徑 → sbom_scan_result_handler（新，取代 job 的沙箱段）：取回傳檔→既有 normalize→寫表→done；vulndb_date 記 Agent 回報值。
• ISandboxScanner port、infra impl、/v1/scan client 刪。

5.6 F 收掉伺服器端

5.7 安全規則對照

決策者功課（開工前）：①建 Cloudflare R2 bucket guidant-vulndb、綁 vulndb.jedicotech.com、產一組唯寫 API token 填進 GitLab CI 變數；②確認 188 runner 的 GitLab 排程可用（Settings → CI/CD → Schedules）。