第三方元件風險：檢測工具入口（Detection Tool Entry）
功能群：第三方元件風險｜兩個入口的差異先讀 功能群總覽 §3
事實基準：2026-10-11 從 FE src/components/grc/planning/ServerSideToolParams.vue、AoTaskForm.vue、src/components/grc/JobExecutionDrawer.vue、src/components/detection-tools/ServerSideToolCard.vue、jedi-detection server_side_dispatch.py／server_side_result.py、jedi-source-scan detection_dispatch_handler.py／detection_result_forwarder.py、DEV config.detection_tools（code='sbom-scan'）實查掃出
變更紀錄
| 日期 |
FR |
變更 |
| 2026-10-14 |
FR-137 |
任務可設週期與自動執行：到期由系統開掃、沿用上次上傳的檔案；掃完與上一次比對，新出現 CRITICAL／HIGH 寄給額外通知對象（見 UC-STE-02 末段） |
| 2026-10-11 |
FR-134 |
新頁：「第三方元件弱點掃描」作為檢測工具——不派 Agent、任務抽屜上傳檔案後執行、結果與產物轉任務證據、抽屜「看完整結果」連結果頁 |
1. 功能描述
本頁不是一條獨立路由，而是第三方元件風險在檢測工具流程裡的那一段：專案規劃時把「第三方元件弱點掃描」綁到任務上，執行人在任務抽屜上傳檔案並執行，掃描結果（報告 PDF、SBOM、各工具原始結果）自動成為該任務的證據。
與其他檢測工具最大的不同：這個工具不派 Agent。它不連任何主機，掃的是使用者上傳的檔案，所以沒有 Agent 指派、沒有目標主機、沒有排程。工程端以 config.detection_tools.execution_target='server' 區分，畫面上不顯示這個區分、不另取名——這個資訊對使用者沒有可操作的東西（Agent 工具顯示 Agent 名稱是因為換一台就通、要靠它排錯；本工具沒有可換的對象）。
主要使用者：專案管理者（綁工具）、任務執行人（上傳與執行）、稽核員（看證據）。
角色速覽
| 角色 |
一句話 |
| 專案管理者 |
在任務配置選工具、設掃描模式與工具 |
| 任務被指派人或專案 manager |
在任務抽屜上傳檔案、執行、重新執行 |
持 detection.source-scan.read |
抽屜多一顆「看完整結果」 |
1.1 功能總覽
| # |
功能 |
說明 |
位置 |
詳述 |
| 1 |
工具卡 |
「第三方元件弱點掃描」只顯示名稱與說明；沒有設定、測試連線、啟用停用（是否可用由授權決定） |
檢測工具管理 |
檢測工具管理 |
| 2 |
任務參數 |
選這個工具後 Agent 指派區塊不出現，改顯示本工具參數與提示句 |
任務配置 |
UC-STE-01 |
| 3 |
上傳檔案 |
任務抽屜出現檔案槽：原始碼封存檔或 SBOM 文件（依掃描模式） |
任務抽屜 |
UC-STE-02 |
| 4 |
執行／重新執行 |
建一次執行並發起掃描；重新執行沿用任務設定的工具與參數 |
任務抽屜 |
UC-STE-02 |
| 5 |
結果轉證據 |
報告 PDF、各格式 SBOM、各工具原始結果寫進任務證據 |
任務抽屜證據區 |
UC-STE-03 |
| 6 |
看完整結果 |
執行列上的按鈕，開該次掃描的結果頁 |
任務抽屜執行列 |
掃描結果頁 |
| 7 |
模組清單可見 |
這類掃描列在「第三方元件風險 → 任務發起的掃描」頁籤 |
模組清單 |
受評系統清單 §5.3 |
2. Use Case
UC-STE-01 在任務上綁定工具
| 項目 |
內容 |
| 角色 |
專案管理者（任務配置權限見任務配置頁） |
| 前置條件 |
授權含檢測工具包 |
| 產出 / 後置條件 |
任務綁定 sbom-scan，參數落在任務層 tool_params，分派列為空 |
選定工具後顯示提示「選用此工具不需指派 Agent，待掃描的原始碼封存檔或 SBOM 於任務執行時上傳。」與三個參數：
| 參數 |
型別 |
預設 |
說明 |
掃描模式 scan_mode |
單選，必填 |
upload |
上傳原始碼封存檔（由平台產製 SBOM 後比對）／上傳 SBOM 文件（直接比對弱點） |
SBOM 格式 sbom_formats |
複選 |
CycloneDX JSON 1.6、SPDX JSON 2.3 |
產出哪幾種 SBOM |
弱點掃描工具 tools |
複選 |
Trivy、Grype、OSV-Scanner |
跑哪幾家 |
後端存檔時對這類工具一律清空 Agent 分派列（detection_job_binding_handler.py::_is_server_side_tool）。
UC-STE-02 上傳檔案並執行
| 項目 |
內容 |
| 角色 |
任務被指派人或專案 manager |
| 前置條件 |
任務狀態為進行中；任務已綁定本工具 |
| 產出 / 後置條件 |
一個執行群組＋一列執行（無 agent_task）；一筆 source_scans（target_uid 空、detection_execution_uid 指向該執行）；背景工作 |
- 檔案沿用：本次有上傳就用新檔並記住；沒上傳就沿用上次那份。從未上傳過 → 400。
- 同一任務同時只能有一輪：已有執行中的群組 → 409
DETECTION_TOOLS_409003。掃描是背景工作、不能中途取消，重新執行也不能疊出第二輪。
- 重新執行沿用任務設定：已執行過的任務，說明文字下方多一行「將沿用此任務設定的掃描工具與參數；要變更請至專案規劃修改任務設定。」——工具勾選是建任務時存下的參數（例如建任務時只勾兩家），重新執行照同一組參數跑，歷次結果才可比。要改工具請回專案規劃改任務設定。Agent 型工具不顯示這行。
- 處理函式失敗時整筆回滾，執行列與群組不留殘缺紀錄。
- 週期自動執行（FR-137）：任務設了週期且開「自動執行」時，時間到由系統以
system 身分走同一條派工路徑，不帶新檔＝沿用上次那份；從沒上傳過就派不出去（照上面「從未上傳過 → 400」），只記 warning、仍寄信請執行人手動執行。抽屜執行紀錄上這筆標「自動執行」。週期設定見任務配置「任務週期」。
- 門檻通知（FR-137）：掃描完成後與同一筆任務上一次成功的掃描比對，有新出現的 CRITICAL／HIGH 就寄給任務設定的額外通知對象（首掃全部算新出現），紀錄在通知紀錄。
UC-STE-03 結果轉任務證據
| 項目 |
內容 |
| 角色 |
系統（背景工作） |
| 前置條件 |
掃描結束 |
| 產出 / 後置條件 |
成功：證據寫入、執行列 succeeded、群組收口；失敗：執行列 failed 帶錯誤訊息 |
- 成功時轉成證據的檔案：報告 PDF 排第一（成為執行列的代表報告），接著各格式 SBOM、各工具原始結果。報告是完整版，含全部弱點列表。
- 檔名規則同總覽 §8 第 1 條：任務掃描沒有受評系統，名稱取任務名（沒有就專案名），例如
Evidence upload_弱點掃描報告_20261011-1403.pdf。
- 證據落地、群組收口、
completion_mode=auto 的自動完成判斷，與 Agent 型工具走同一套（server_side_result.complete），不另寫一份。
- 執行列的
summary 帶統計，抽屜依中文對照表顯示嚴重度、KEV、EPSS、可修補、涵蓋度、元件數。
3. 權限矩陣
| 操作 |
FE 判定 |
BE 強制 |
BE 檢查位置 |
| 綁定工具 |
任務配置頁既有守門 |
任務配置既有守門 |
見任務配置頁 §3 |
| 執行／重新執行 |
抽屜既有守門（canEdit） |
任務被指派人或專案 manager（assert_job_operator）；任務須進行中 |
detection_orchestration_service.py::start_execution |
| 看完整結果 |
v-can=detection.source-scan.read |
detection.source-scan.read |
SourceScanDetailRoute.get |
| 工具可見 |
依授權過濾工具清單 |
GET /detection-tools 依 license 過濾 |
jedi-detection routing |
任務操作守的是任務權限（grc.job.*），不是 detection.source-scan.*——見系統管理總覽「A 任務情境看任務權限」。
4. 狀態機與前置條件
| 條件 |
效果 |
出處 |
| 任務不是進行中 |
409 DETECTION_TOOLS_409002 |
start_execution |
| 任務未綁定工具 |
400 DETECTION_TOOLS_400003 |
同上 |
| 已有執行中的群組 |
409 DETECTION_TOOLS_409003 |
server_side_dispatch.dispatch |
| 沒有本次上傳、也沒有上次那份 |
400 SOURCE_SCAN_400002 |
detection_dispatch_handler.py |
| 指名的檔案不存在 |
404 DETECTION_TOOLS_404003 |
server_side_dispatch._resolve_input_files |
| 工具沒有登記處理函式（系統設定壞掉） |
412 DETECTION_TOOLS_412003 |
server_side_dispatch.dispatch |
| 掃描模式不是 upload／sbom |
400 SOURCE_SCAN_400001 |
detection_dispatch_handler.py |
5. UI 設計
| 畫面 |
本工具的呈現 |
| 檢測工具管理 |
工具卡只有名稱與說明，沒有徽章、按鈕、選單 |
| 任務配置 |
不顯示 Agent 指派、目標主機、排程；顯示提示句與三個參數（掃描模式、SBOM 格式、弱點掃描工具），格式與工具收在「進階參數」 |
| 任務抽屜 執行區 |
檔案槽（依掃描模式限定副檔名）；執行群組列與執行紀錄列不顯示 Agent 名稱那一格；已執行過時多一行沿用參數提示 |
| 任務抽屜 執行列 |
「看完整結果」（有 read 權限才出現）、下載報告 |
| 任務抽屜 執行詳情 |
開始／結束時間 YYYY-MM-DD HH:mm:ss；掃描報告清單點檔名或眼睛鈕可預覽（PDF 進預覽框、JSON 走文字預覽），旁邊保留下載 |
6. API 規格
本入口沒有自己的 endpoint，走檢測工具既有端點：
| Method + Path |
說明 |
GET /detection-tools |
工具清單，回應帶 execution_target |
| 任務配置存檔端點 |
見任務配置頁 §6 |
| 任務抽屜執行端點 |
body 帶 source_files（每項只送 uid，檔名等由後端從 upload_files 權威取回） |
GET /source-scan/scans/{uid} |
「看完整結果」 |
派工結果回傳一列 executions[0]，帶 source_scan_uid；抽屜據此顯示「看完整結果」。
7. 前端檔案地圖（compliance-manager-fe/）
| 檔案 |
角色 |
src/utils/detectionExecutionTarget.js |
isServerSideTool：判斷一律看 execution_target，不看 connection_type（本工具的 connection_type 是 null） |
src/composables/useServerSideExecutionDisplay.js |
抽屜用的判斷 |
src/components/detection-tools/ServerSideToolCard.vue |
工具卡 |
src/components/grc/planning/ServerSideToolParams.vue、AoTaskForm.vue |
任務參數區 |
src/components/grc/job-drawer/DetectionSourceFileUpload.vue |
抽屜檔案槽 |
src/components/grc/JobExecutionDrawer.vue |
抽屜：執行、沿用參數提示、看完整結果（超標檔，新邏輯一律另開檔） |
src/components/grc/job-execution/ExecutionInfoDialog.vue |
執行詳情：時間格式、報告預覽 |
8. 後端檔案地圖
| 鏈路 |
檔案 |
| 派工分岔 |
jedi-detection detection_orchestration_service.py::start_execution（一行分岔）→ server_side_dispatch.py::dispatch |
| 本工具處理函式 |
jedi-source-scan detection_dispatch_handler.py::dispatch_sbom_scan（@register_server_side_handler('sbom-scan')） |
| 結果回收 |
jedi-source-scan detection_result_forwarder.py → jedi-detection server_side_result.py::complete／fail |
| 綁定存檔 |
jedi-detection detection_job_binding_handler.py::_is_server_side_tool |
| 工具目錄 seed |
jedi-detection migrations（新客戶）＋BE scripts/sql/2026-10-10-fr134-h1-sbom-scan-tool.sql（既有庫升級） |
9. DB
| 表 |
讀/寫 |
說明 |
| config.detection_tools |
讀 |
code='sbom-scan'、execution_target='server'、requires_target_host=false、requires_credentials=false |
| config.detection_tool_param_schemas |
讀 |
三個參數 |
| compliance.detection_execution_groups／detection_executions |
寫 |
一群組一執行列，agent_task_uid 為 NULL |
| compliance.source_scans |
寫 |
target_uid NULL、detection_execution_uid 指向執行列 |
| job_evidences |
寫 |
結果檔 |
config.detection_tools.code='sbom-scan' 是資料值：改了那一列的 code，處理函式就找不到（412）。
10. 頁面邏輯與資料對應
- 判斷是否本類工具：FE 讀工具清單的
execution_target；BE 讀同一欄位。兩端同一判準，查不到工具時當 Agent 型。
- 任務被刪除後，該任務的掃描不再列在模組的「任務發起的掃描」頁籤。
11. 背景行為與外部依賴
| 類型 |
內容 |
| 背景工作 |
同獨立模組：sbom_scan，worker 執行 |
| 稽核事件 |
派工記 DETECTION_SCAN_STARTED（6123，與 Agent 型同一支） |
| jedi-* 套件 |
jedi-detection（派工分岔、結果回收）、jedi-source-scan（處理函式、核心） |
12. 邊界情況與已知坑
- 重新執行不會自動加新工具：任務建立時勾的工具清單是快照；系統新增第三家工具後，舊任務重新執行仍只跑任務設定裡的那幾家。
- 掃描不能取消：背景工作不支援取消，執行中只能等它結束或逾時（20 分鐘）。
- 任務掃描不從模組刪：跟著任務走；任務刪除後該掃描不在模組清單出現。
- 錯誤訊息
DETECTION_TOOLS_412003（工具沒有登記處理函式）描述的是實際部署位置：只在系統設定壞掉時給管理員看，不屬一般使用者畫面。
13. 開發與驗證
- 驗收：專案規劃建一個檢測工具任務選「第三方元件弱點掃描」→ Agent 指派不出現 → 啟動任務 → 抽屜上傳封存檔 → 執行 → 證據區出現報告 PDF、SBOM、原始結果（檔名以任務名開頭）→「看完整結果」開結果頁 → 模組「任務發起的掃描」頁籤看得到這筆
- 相關：檢測工具管理、任務配置頁、我的任務