子需求：FR-058.7 SonarQube 上傳檔案掃描（scan 模式取源擴充）

任務摘要

FR-058.7 的 evidence-agent 側取源段實作。包含：① mTLS 串流下載 client：比照 core/task_executor.py _post() 的 httpx mTLS client 形狀加 _get_stream()，串流寫進 workspace；② 下載後 sha256 對帳防竄改；③ 磁碟檢查：下載前 shutil.disk_usage("/tmp")，free < 壓縮包×12＋1GB 即 fail；④ 雙家族安全解壓：zip 走 zipfile、tar 系走 tarfile filter="data"，兩家族共用約二十行額度檢查層（解壓炸彈計量＋cancel）；⑤ 接進既有 scan 管線（取代 _clone_repo() 分支，_run_scanner() 起原樣沿用，workspace 生命週期複用既有 finally: shutil.rmtree）；⑥ 單元測試。

關鍵約束

• 磁碟檢查係數與底值吃 payload 下發的 limits（agent 不自己配置，單一真相在 BE，D27）；錯誤訊息明確標「agent 磁碟空間不足」並歸類為 agent 環境問題、不是掃描失敗（D28）；實作放 _scan_workspace() 建目錄前
• 解壓前加總封存宣告總大小與檔數、超過限額即拒絕；逐檔解時看 cancel_event；累計超額即中止並清理（D30）；不 shell 出去跑 unzip / tar CLI、不引第三方套件
• tarfile filter="data" 需 Python 3.11.4+，agent 基底 python:3.11-slim 足夠
• 與 T-7.1 並行前先凍結 key 契約：_source_file 形狀、下載端點路徑、sha256 header 名（§4.8）

design.md 座標

詳細設計見 §4.8（connector 實作要點、端到端流程）；決策理由見 §2 D25、D27、D28、D30；驗收條件見 §5.12 T-7.2。

驗收條件摘要

• 單元測試綠（含五路徑 workspace 清理斷言擴充、兩格式家族解壓案例、路徑逃逸 / 超額壓縮包被擋案例）
• image build 過；容器內對實際壓縮包手動跑通全鏈路（下載 → 對帳 → 解壓 → scan → 推 171 → 拉結果 → HTML）
• 磁碟不足與超額壓縮包兩條負向路徑皆明確 fail 且 workspace 已清

已完成修正（2026-08-01）

做了什麼（白話）

讓 agent 可以「掃使用者上傳的源碼壓縮包」，而不是只能掃公開的 Git 網址。

原本的主動掃描模式只有一條取源路：去 clone 一個公開 Git repo。但客戶的源碼常常不在公開 repo（私有 repo 不願交憑證、源碼根本不在 git、稽核要特定一版）。這次做的是把「取源」那一段多加一種方式——使用者在發起執行時上傳壓縮包，agent 從雲端把它拉下來、驗證、解開，然後後面整條掃描流程完全沿用，一行都沒改（掃描 → 推上客戶 SonarQube → 等佇列 → 拉結果 → 組 HTML 報告）。

換句話說：這不是第三種模式，是既有 scan 模式的取源擴充（D25）。