原始碼弱點掃描與 SBOM 報表 — 設計定案

狀態：設計定案（D1–D14 全數拍板）｜日期：2026-10-10｜前作：FR-122（沙箱與 AI 閘道）、FR-056／058.7（檢測工具與源碼上傳）、FR-127／128（出貨 SBOM 管線） 討論稿（現況盤點座標、業界對照、各選項推演）：discussion.html

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

顧問輔導客戶時，專案的第三方套件弱點本該由客戶工程師盤點回報，實務上常被「那個不嚴重」「我們環境打不到」帶過，顧問沒有技術背景無從判斷。本案讓顧問不靠工程師就能拿到一份有工具原始輸出背書的弱點報表。

產品現況：出貨管線已有整條「Syft 產 SBOM → Trivy＋Grype 雙掃 → 白名單判定」（scripts/build/sbom.sh、vuln_gate.py），但只服務我們自己的出貨，客戶看不到。缺的是：

1. 沙箱裡沒有掃描工具：guidant-sandbox 只會拆檔，沒有 Syft／Trivy／Grype，呼叫介面只有 /v1/extract。
2. 弱點資料無法離線：build 機每次掃描都線上更新，沒有任何匯出、釘版、隨包帶的機制；落地版客戶裝好弱點永遠是零。
3. 沒有「給非技術人看」的那一層：市面工具全是 CVE 清單與分數，沒有事實統計、歷次比對、可交付報表。
4. 檢測工具一律派 Agent：FR-056 的工具是「資料庫一列＋Agent 執行器」，沒有「伺服器自己跑」這條路。

端到端

%%{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 guidant-api
    participant S as SeaweedFS
    participant W as guidant-worker
    participant SB as guidant-sandbox
    participant V as vulndb volume
    participant DB as guidant-db
    U->>API: 上傳源碼包或 SBOM 檔
    API->>S: 存原檔
    API->>DB: 建 source_scans（queued）＋入列 background_jobs
    W->>DB: 撿單（SKIP LOCKED）
    W->>S: 取原檔到工作目錄
    W->>SB: POST /v1/scan（檔案、選項）
    SB->>SB: 安全解壓 → syft → trivy／grype（離線）
    SB->>V: 唯讀讀取弱點資料
    SB-->>W: SBOM 多格式＋兩家原始 JSON
    W->>W: 正規化：配對、KEV／EPSS、六區塊統計、NTIA
    W->>S: 存 SBOM、原始 JSON（算 sha256）
    W->>DB: 寫 components／findings／summary（done）
    U->>API: 看結果、匯出報表

執行期四段白話進度（接收檔案 → 產出物料清單 → 比對弱點 → 整理報告）由 worker 經 ctx.report_progress 回報，清單頁輪詢顯示。檢測工具入口（§5.5）走同一條：start_execution 看到伺服器端工具就入列同一種背景工作，跑完多一步呼叫 DetectionResultHandler 把報表轉成任務證據。

整案一句話：顧問上傳客戶的原始碼或 SBOM，十幾分鐘後拿到一份看得懂、工程師賴不掉的弱點報表；三個月後再掃一次，修了沒一眼看到。

給非工程讀者的背景：現代程式九成以上是拼裝現成的第三方套件。套件被發現有安全漏洞時，用到它的程式就跟著有風險。SBOM（軟體物料清單）是一份「這支程式用了哪些套件、哪個版本」的清單；拿這份清單去比對公開的弱點資料庫，就知道哪裡有洞、多嚴重、有沒有修正版。

依賴：A → B、C 平行 → D、E、H 平行 → F（要 C＋D）→ G。B 未完成前 C 可在 DEV 用線上資料開發。

5.0 程式碼落點：新 jedi 套件 jedi-source-scan

核心引擎做成新套件 jedi-source-scan（~/Projects/Jedicogy/module/jedi-python-package/jedi-source-scan/），DDD 四層照 jedi-detection 的目錄形狀；主專案與檢測工具入口都只是它的呼叫端。理由：D9「核心不知道被誰叫」在套件邊界上最自然；出貨管線日後若要反過來吃產品服務，也只依賴套件。

開發期走 poetry path dependency（主專案 pyproject.toml 取消註解），path 改動不 commit；發版等決策者明示。

5.1 沙箱擴充（子需求 A）

compose 樣板（docker/production/docker-compose.yml）：

x-guidant-sandbox-hardening: &guidant-sandbox-hardening
  read_only: true
  cap_drop: [ALL]
  security_opt: ["no-new-privileges:true"]
  tmpfs:
    - /tmp:size=4g            # D12：掃描工作區（原 2g）
    - /home/classifier:mode=1777
  mem_limit: 4g               # D12
  cpus: 2
  pids_limit: 256
  # 預留：egress policy 由網段決定；第一版所有實例皆 internal（none）

guidant-sandbox 服務段改 <<: *guidant-sandbox-hardening，自己只留 image、environment、networks、volumes；volumes 加 guidant-scan-vulndb:/opt/vulndb:ro。頂層 volumes: 加 guidant-scan-vulndb。installer 的服務名清單不動（容器沒增）。

image（jedi-evidence-classification/docker/Dockerfile）：多階段加一層下載三支工具的釘版二進位（版本與出貨管線同：syft 1.54.0／trivy 0.75.0／grype 0.120.0，從 GitHub release 取並驗 sha256），放 /usr/local/bin；不裝任何弱點資料。Trivy／Grype 的快取目錄用環境變數指到 /opt/vulndb/{trivy,grype}。

守衛測試（test/security/code/test_security_shape_container_hardening.py）：

• SANDBOX_SERVICES 改為「compose 內所有名字以 -sandbox 結尾的服務」動態取得，舊的四容器 tuple 拿掉名單改規則，其餘三容器照原規則。
• 沙箱類新增三條斷言：read_only is True、所有 networks 都是 internal: true、tmpfs 有 /tmp。
• 突變測試：把 read_only 拿掉要紅、把網段 internal 拿掉要紅。

🔴 出貨弱點閘：三支工具本身進了 image，scripts/build/sbom.sh --images 會掃到它們的 Go 二進位依賴。A 階段 build 完先在 188 跑一次 sbom.sh --images 與 vuln_gate.py，有 Critical 就依 vuln-allowlist.txt 四欄格式登記（理由寫「掃描工具自身依賴，不對外暴露」，到期日給三個月），不可為了過閘降版工具。

5.2 弱點資料更新（子需求 B）

更新包 guidant-vulndb-<YYYYMMDD>.tar：

合計約 250–350 MB（估算值，A／B 階段 build 機實測回填）；解開進 volume 約 3.5 GB；更新時新舊並存約 7 GB——安裝文件磁碟需求要加這一條。產製腳本 scripts/build/build_vulndb_bundle.sh（新檔，sbom.sh 不動）；安裝包 build_bundle.sh 收一份進 vulndb/，進 sha256 manifest。

進入途徑三條，寫入同一條：

1. 裝機／升級：install.sh 在起沙箱前把包內那份解進 guidant-scan-vulndb（比照 storage-seed 的 docker cp 寫法，install.sh:1949-2016）；升級時只在包內日期較新才覆蓋。客戶無感。
2. 設定頁上傳：系統設定頁「弱點資料」區塊。因檔案超過 110 MB 全站上限，走分塊上傳（前端切 50 MB 塊逐段 PUT、後端落暫存合併；MAX_REQUEST_BODY_MB 與 nginx 都不動）。合併後驗 manifest 簽章、逐檔 sha256、bundle_date 不得早於現行 → 解進 volume 的新目錄 → 原子切換 symlink current → 清舊目錄。
3. 連網自動：設定頁「檢查更新」按鈕與排程（預設每日），api 向自家站台 GET /vulndb/latest（URL 在 config，預設我們的站台）取 manifest 比日期，較新就由 worker 下載走同一條驗簽寫入。沙箱不出網，下載一律由 api／worker 做。

更新紀錄（決策者要求「誰什麼時間點上傳」）：表 public.vulndb_updates（平台層、無 tenant_id）：uid、bundle_date、previous_bundle_date、source（installer｜ui_upload｜auto_download）、status（succeeded｜failed）、error、sha256、sources（JSONB：各來源日期筆數）、created_user（installer 寫 system）、created_at。設定頁顯示最近 20 筆，同時走既有稽核事件埋點（事件 vulndb.update）。

使用端：掃描時 Trivy 帶 --skip-db-update --offline-scan --cache-dir /opt/vulndb/current/trivy，Grype 設 GRYPE_DB_AUTO_UPDATE=false、GRYPE_DB_CACHE_DIR=/opt/vulndb/current/grype；KEV／EPSS 由 worker 正規化階段讀（不在沙箱內）。每筆 source_scans.vulndb_date 記當次資料日期；結果頁與報表顯示，超 30 天黃、90 天紅。

5.3 核心引擎（子需求 C）

資料模型（schema compliance，共同欄位 id、uid、tenant_id NOT NULL、org_unit_id、created_user／updated_user、created_at／updated_at；RLS 照 FR-129.2 一條 FOR ALL；GRANT 表與 sequence 給 cm_app；收尾 INSERT schema_migrations）：

兩個 key：match_key＝ecosystem+name+version+正規化弱點編號（跨工具配對，別名收斂 GHSA／PYSEC→CVE，借 vuln_gate.py:84 收 relatedVulnerabilities 的寫法）；fingerprint＝ecosystem+name+正規化弱點編號（不含版本，升版仍受影響算「仍在」）。

job handler sbom_scan（@register_job_handler('sbom_scan')，max_attempts=1）：payload 只放 scan_uid（無金鑰）。流程：

1. report_progress({'stage':'receive'})：從儲存取原檔到工作目錄（沿用 stage_to_dir pattern）；source_type=upload 走 ProfileArchiveValidator＋ArchiveBombGuard 檢查 → safe_extract（新寫，§D13）；source_type=sbom 驗 JSON／XML 格式與 CycloneDX／SPDX 版本辨識（schema 驗證在沙箱內做）。
2. report_progress({'stage':'sbom'})：SandboxClient.scan(job_uid, files, options) → 沙箱 /v1/scan：syft dir:<工作區> -o cyclonedx-json@1.6=... -o spdx-json@2.3=...（依選項多格式多版本）；source_type=sbom 時略過 syft、直接把上傳檔當輸入。
3. report_progress({'stage':'vuln'})：沙箱內 trivy sbom <cdx> --format json --skip-db-update --offline-scan、grype sbom:<cdx> -o json；回傳 SBOM 檔案群＋兩份原始 JSON。
4. report_progress({'stage':'report'})：worker 正規化——解析兩份 JSON 成統一 finding、match_key 配對、KEV／EPSS enrich（讀 volume 內檔）、六區塊統計、NTIA 七要素、缺 lock 偵測（Syft 輸出的 cataloger 來源判斷：只有 python-package-cataloger 類而無 lock cataloger）、授權風險；存 SBOM／原始 JSON（算 sha256）進儲存；寫三張表；status=done。

沙箱逾時 20 分鐘（D12）；任何階段失敗 status=failed 寫 error，不重跑。worker 啟動時沿用 sweep_stale_job_dirs 清殘留。

安全解壓 jedi_detection/common/safe_extract.py：safe_extract(archive_path, dest_dir, limits) -> ExtractReport，照 .claude/rules/security/uploads-parsing.md 四道：禁 extractall、每個 entry realpath 必在 dest_dir 內、拒 symlink／hardlink／裝置檔、邊解邊累計 bytes 與檔數超限即中止、工作目錄不得是符號連結。呼叫端在沙箱內（沙箱 /v1/scan 收到的是壓縮檔，解壓在沙箱裡做）。

沙箱端點 /v1/scan（scan_service.py）：Bearer token 同 /v1/extract；輸入多部檔案＋JSON 選項；單一併發（--max-concurrent 1 不變）；對外回傳一律視為外部輸入（worker 解析時 bleach 不適用、改走嚴格 JSON schema）。SandboxClient.scan() 登記進 test_security_shape_external_calls.py。

六區塊 summary 形狀（對齊 detection_executions.summary，兩入口共用）：

{"severity":{"trivy":{"critical":1,"high":9,"medium":15,"low":3},"grype":{...}},
 "kev":{"count":1,"items":["CVE-..."]},
 "epss":{"threshold":0.1,"count":2,"items":[...]},
 "fixable":{"with_fix":7,"without_fix":3,"oldest_fix_date":"2023-04-01"},
 "coverage":{"missing_lock":["npm"],"ntia":{"score":5,"missing":["supplier","author"]}},
 "delta":{"vs_scan_uid":"...","fixed":4,"new":2,"remaining":8},
 "vulndb_date":"2026-10-08","components":568,"findings":28}

5.4 入口 1 獨立模組

能力點：detection.source-scan.{read,create,update,delete,execute,export} 宣告在 jedi_source_scan/plugin/contract.py；跑 scripts/deliverables/gen_permission_matrix.py 重產 FE capabilities.js；migration 加 ui_routes（路徑 /source-scan，license_module='plugin'）＋route_capabilities（ALL：detection.source-scan.read）＋bump CAPABILITY_CATALOG.VERSION。shipped-roles.json：稽核主管／稽核員 pattern 加 detection.source-scan.* 扣 delete、update；唯讀 detection.source-scan.read。弱點資料設定併入系統設定頁（system.system-config.update，管理員）。

API（api/source_scan/routes/，全部 @jwt_required → @require_license("plugin") → @require_capability(...)，資源域守門在 app service 查 target 屬租戶）：

審計欄位回傳 created_user_name／updated_user_name（app service 批次轉 nickname）。

FE（照 FR-129.2 commit 6ae57765 14 檔形狀）：router、api.js、SourceScanService.js、config/sourceScan.js、views/source-scan/{SourceScanTargetList,SourceScanWizard,SourceScanResult,SourceScanDiff}.vue、i18n source-scan.json（zh-tw／en）＋menu.json＋error-code.json；元件級 v-can。每支 Vue 不超過 800 行，結果頁三層各拆子元件。

畫面骨架（自行設計，見 §3 UI 約束）：①對象清單（名稱、客戶備註、來源、最近掃描日、重點數字、趨勢；按鈕新增／重掃／看結果／歷次比對）；②精靈三頁（這是什麼／程式在哪：只有上傳源碼包與上傳 SBOM 檔兩選一／怎麼掃：標準掃描＋進階勾工具與格式版本）；送出後清單列顯示四段進度；③結果頁三層分頁（事實儀表板六區塊＋授權風險＋資料日期警示／對照層每弱點一列排序可選、兩家不一致標示／原始層下載）；④歷次比對三欄；⑤設定頁（弱點資料日期、上傳更新包、檢查更新、更新歷史、資源上限）。

5.5 入口 2 檢測工具（子需求 H）

核心不判斷入口：差異只在「誰建 source_scans 列」與「跑完要不要多呼叫 DetectionResultHandler」（看 detection_execution_uid 是否非空）。

5.6 報表與 AI 分析（子需求 E）

格式：HTML（Jinja 模板，單檔內嵌 CSS，可展開原始片段）→ PDF（同一份 HTML 經 WeasyPrint，照 project_summary_report_route.py 的 bleach 消毒與 _data_uri_only_url_fetcher，字型 Noto Sans CJK TC）；DOCX（docxtpl 範本 jedi_source_scan/templates/report_*.docx，照 ssp_docx_generator.py 填值）。共用品牌頁首頁尾放模板內（產品名、租戶名、產生時間、頁碼）。

硬規則：不出現結論句（「屬高風險」「建議立即」），只出事實句；每個弱點列四件事（工具、CVE 連 https://nvd.nist.gov/vuln/detail/<id>、advisory 連結、fixed version）；附錄一頁（工具與版本、弱點資料日期、各原始檔 sha256 與系統內路徑）；資料來源說明一頁（NVD／CVSS—NIST、CISA KEV、EPSS—FIRST、套件官方修正紀錄）。缺 lock 時「涵蓋完整度」段必在統計同頁、不得只在附錄。

AI 分析（D14）：結果頁按鈕 → POST /source-scan/scans/<uid>/ai-analysis → 經 FR-122 AI 閘道（既有 provider 設定、額度、呼叫紀錄、Prompt Guard）送提示樣板（輸入只放 summary 與前 20 筆 finding 的事實欄位，不放原始 JSON）；回應存 source_scans.ai_analysis JSONB（文字、模型、時間、誰按的）；畫面標「AI 生成，以上方統計為準」。報表不含 AI 分析。

5.7 歷次比對（子需求 F）

SourceScanDiffService.diff(scan_a, scan_b)，借 SspDiffService 骨架：以 fingerprint 配對 findings → fixed（a 有 b 無）、new（a 無 b 有）、remaining（兩邊都有，版本可能不同，附兩邊版本）；components 以 purl 去版本配對列升降版。結果不落表、即時算；source_scans.summary.delta 在每次掃描完成時對 target.latest_scan_uid 自動算一次存入。回訪報告＝顧問摘要樣式加「與上次比」一節。

5.8 資安規則對應

粒度：一張子任務＝一個 session 做得完；每張卡開卡時把本節對應列＋§5 對應段展開進卡。

%%{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[T-A1] --> A2[T-A2] --> A3[T-A3]
  A1 --> A4[T-A4]
  B1[T-B1] --> B2[T-B2]
  A1 --> B2
  B1 --> B3[T-B3] --> B4[T-B4] --> D3[T-D3]
  C1[T-C1] --> C2[T-C2]
  A3 --> C2
  C2 --> C3[T-C3]
  C2 --> C4[T-C4]
  C1 --> C5[T-C5]
  C3 --> C6[T-C6]
  C4 --> C6
  C5 --> C6
  C6 --> D1[T-D1] --> D2[T-D2]
  C6 --> E1[T-E1] --> E2[T-E2]
  C6 --> E3[T-E3]
  C6 --> F1[T-F1]
  D2 --> F1
  C1 --> H1[T-H1] --> H2[T-H2]
  C2 --> H2
  H2 --> H3[T-H3]
  E1 --> H3
  H1 --> H4[T-H4]
  H3 --> H5[T-H5]
  D2 --> H5
  D2 --> G[T-G1～G4]
  E2 --> G
  F1 --> G
  H5 --> G
  B4 --> G

決策者在 DEV 親手做（全部跑完再收集失敗，不逐項修）：

1. 沙箱：docker exec guidant-sandbox syft version、trivy --version、grype version 三支有；docker exec guidant-sandbox curl -m 5 https://github.com 失敗；docker compose config | grep -A20 guidant-sandbox 看到 read_only: true 與 4g；既有證據分類跑一筆照常。
2. 守衛：pytest test/security/code/test_security_shape_container_hardening.py 綠；手動把 compose 沙箱 read_only 註解掉再跑 → 紅。
3. 弱點資料：設定頁顯示資料日期；上傳 T-B1 產的包 → 日期前進、歷史多一列寫自己帳號與時間；把包內任一檔改一個位元組再上傳 → 拒收並有白話錯誤；拿舊日期包 → 拒收。
4. 獨立模組：以稽核主管登入 → 側選單有「原始碼掃描」→ 新增對象、上傳一個含 package-lock.json 的範例專案 zip → 清單四段進度走完 → 結果頁六區塊有數字、KEV 區塊有列、對照層切換排序表頭跟著變、原始層下載 CycloneDX 1.6 與 SPDX 2.3 兩檔都能開。
5. 缺 lock：上傳一個只有 package.json 的 zip → 結果頁「涵蓋完整度」明確標示 npm 缺 lock、品質分較低。
6. SBOM 上傳：把步驟 4 下載的 CycloneDX 檔新建對象上傳 → 弱點數與步驟 4 一致。
7. 報表：匯出 3 樣式×3 格式九份；PDF 中文不缺字；全文搜尋「高風險」「建議立即」為零；附錄 sha256 與原始層顯示一致。
8. AI 分析：不按按鈕 → AI 呼叫紀錄無新列；按 → 多一列、畫面出現「AI 生成」標示。
9. 歷次比對：把範例專案某套件升到有修正的版本重壓 zip、同對象重掃 → 比對頁「修掉」出現該弱點；改成仍受影響的另一版 → 「仍在」。
10. 檢測工具入口：專案規劃建 detection_tool 任務 → 下拉有「SBOM 弱點掃描」、選後無 Agent 指派欄 → 任務頁上傳 zip 按執行（所有 Agent 離線）→ 執行列表一筆跑完 → 任務證據清單出現 PDF 與 SBOM → 「看完整結果」數字與獨立模組一致。
11. 權限與授權：唯讀角色看不到新增、打 POST 回 403；以沒買檢測工具包的租戶登入 → 側選單無此項、檢測工具下拉無此列。
12. 畫面：精靈、清單、設定頁全文搜尋「Git」為零；版面與 ITRI SecureScan 截圖無可辨識雷同。

• 全站 110MB 上限：更新包約 300MB，設定頁上傳必走分塊；不可為此調 MAX_REQUEST_BODY_MB（會連帶放寬所有端點）。
• 磁碟：volume 解開 3.5GB、更新時 7GB，安裝文件與 installer 前置檢查要加。
• 證據分類排隊：共用一顆沙箱，大源碼包掃描 20 分鐘內分類會等；C 階段量測，不可接受時調 --max-concurrent，不拆容器。
• 缺 lock 看起來很乾淨：弱點數可能為零但涵蓋不完整；「涵蓋完整度」必與統計同頁顯示，不得只在附錄。
• 兩家工具不一致：同一 CVE 一家報 High 一家 Critical 是常態；對照層標「工具意見不一致」並列兩家分數，不取平均。
• Trivy Java：掃 Java 專案可能需要 trivy-java-db，B 階段實測、必要時進更新包。
• source_type 枚舉：資料層預留 git 但 API 與 UI 不開放；守衛可加一條「序列化器枚舉只含 upload／sbom」。
• 沙箱回傳是外部輸入：工具 JSON 解析用嚴格 schema 與長度上限，不信任 severity 字串直接進 DB（白名單對照）。
• 自動首掃：server 型任務啟動時若無檔案不可自動跑失敗一筆，抽屜要提示先上傳。
• 出貨基線：T-C1／T-H1／T-B3 的 migration 完成要回報「出貨基線待重產」，決策者裁示後才動 188 基線庫。