FR-177 Agent 本體資安掃描第一期

🔴 總結報告分兩版：SUMMARY.md 是 PM 版（結論、發現按嚴重度但不含檔名行號、三個反覆模式、修法摘要、順序、可信度），可上需求文件站；工程師版（每條含檔名行號、六張修正卡寫到函式）在 Agent repo docs/security-scan/FR-177/SUMMARY-engineering.md，不上站，等修正出貨後再考慮公開。本頁是進度表與座標。

這是資安掃描系列的第七個 arc。跨 arc 的結論、修正卡狀態與覆蓋率地圖在 security-scan-consolidated/；本頁只講 Agent 這一支。作業手冊是 .claude/skills/security-scan-lead/SKILL.md。

Agent（repo evidence-agent）是裝在客戶自有設備上的程式：管證據檔、跑檢測工具、收主系統指令、提供本機主控台。2026-09 的 FR-077 掃的是主系統這一側的 jedi-remote-agent 套件與接線，Agent 自己的程式一個檔都沒進 scope；之後 FR-166／170／172 又把 Agent 重寫成 guidant_agent/ 七個模組，更新鏈是全新程式。

全包 214 支 Python、約 27,400 行，中文 docstring 密度高（研究員讀起來一行約是英文碼的兩到三倍 token），所以每棒壓在 1,000 行上下；分兩批各四棒平行。第一期挑「客戶內網直接打得到」的八塊；主控台其他路由、掃描執行核心、各工具 connector 的指令執行（sonarqube.py 1,711 行、inspec.py 1,050 行等）留第二、三期，等第一期結果出來再決定要不要掃。

agent_auth.py 刻意同時放在 A1 與 A2（接縫檔重疊帶入，手冊第一節「切不開時」），兩棒分在不同批，驗收時比對兩邊對同一檔的結論、重複的挑掉。

第一期指出的兩個缺口已納入：device_uuid 算法進 B7、主機端升級腳本進 B8。B8 的第一條重點是 upgrade_runner.sh:50 從新映像 cat 出腳本直接 source 進 root shell，要對照是在驗章前還是後，A3 的結論是否成立取決於此。原 B6 1,836 行超安全線拆成 B6a／B6b。

第三期（已開卡，上表）：原規劃：connectors 六棒（sonarqube.py 1,711 單檔、inspec.py 1,050 單檔、nmap＋zap、openscap＋openvas＋兩支 sbom）與 netdiag 兩棒（probes 十一檔、app 七檔），全部是 subprocess 組參數跑外部工具。等第二期驗完再開；可先用 Semgrep 的 python subprocess 規則掃一遍，命中點寫進卡的「重點看什麼」。不掃、首腦 grep 補查：config/config.py、platform/container／bootstrap／registry／background、common/code、shared 剩餘、各 ports/、migrations。

決策者 11-06 裁「第三期開一開掃完一起修」。全部是 connector 與網路診斷：Agent 組參數去跑外部掃描工具的地方。Semgrep（p/python＋p/command-injection＋p/secrets）掃整個範圍只命中 1 條（inspec.py:646），因為程式都是 list argv 或 shlex.quote 過的字串，規則抓不到「quote 錯地方／漏一欄」，要靠研究員讀。

批次邏輯：兩批各四棒並行（決策者裁）。看門狗殺的是研究員自己累積太多 token 時的自動壓縮，與旁邊有沒有別棒並行無關，第 1／3 批四五棒並行含 1,388 行的 B7 都沒事。C1～C5 中文密度 4,400～10,364 字偏高，卡上寫了「journal.jsonl 第二個 failed 就停、不讓工具重試」，C1 若被砍是它自己體積問題，到時再拆。各棒第一條重點：C1 源碼包內放 sonar-project.properties 覆寫 sonar.host.url 外送 token；C2 SSH／WinRM 密碼寫進 cinc 設定檔的落地與清理；C3／C5 在客戶主機上以字串執行 nmap／oscap（可 sudo），shlex.quote 是唯一防線且 quote 後工具自己的參數解析（target 以 - 開頭當選項）仍要看；C4 ZAP 登入密碼是任務參數會不會落 local_runs.params 明文；C6 SBOM 工具跟 symlink 讀到 secrets/；C7 probes 是全 Agent 唯一准直接 subprocess 的地方，驗 target.ip 進 argv 前有沒有 -- 或 IP 驗證；C8 報告把探測 raw 輸出渲染成 HTML 的跳脫。

| 修④a | CM-3573 | 7 | 主系統下發「主機名→IP」對照（#233 主系統側，工作坊首腦替決策者選 A 案後開） | #233 | ✅ 驗收通過（11-07） | | 修④b | CM-3574 | 8 | Agent 不再自查 DNS，只認下發對照（#233 Agent 側） | #233 | ✅ 驗收通過（11-07） | | 修① FE | CM-3575 | 7 | 主控台規則包只能下拉選、改位址提示重填（FE repo） | #223 #232 | ✅ 驗收通過（11-07） | | 修① jedi | CM-3576 | 7 | jedi-detection 派工擋手填規則包、015 migration 改提示 | #223 | ✅ 驗收通過（11-07），未發版 | | 修⑥ jedi | CM-3584 | 9 | jedi-detection 016 加 ca_cert 欄、ZAP 說明改 https | #236 #238 | ✅ 驗收通過（11-07），未發版 |

第 7 批四張互不撞檔；第 8 批兩張等第 7 批合回（修②、修⑥與修① 共用 ldap_routes.py／secret_form／inspec.py）。兩處要決策者在卡上回答：修① 網址目標只收 IP 或解析後綁 IP、修② LDAP 設定提權方案 A／B。資安開發規範已依本次掃描先強化（Agent 四支、主系統三支＋總覽），修正卡的修法與新條款對齊。

等決策者裁：逐棒報告複本 reports/（含未修期間寫的行號）合回 main 前要不要只留 Agent repo 正本。

這一輪第一次用 agent-workshop 跑掃描卡。前六輪的做法是決策者在 runner 視窗親手打啟動指令，因為 claude-security 只接受使用者回合的啟動句；工作坊這次加了「每張卡一支開場 prompt 覆寫檔」，把啟動指令當成小弟 session 的第一句送進去，就等於使用者打的。

• 覆寫檔在本 repo .claude/workshop-prompts/dispatch-CM-35xx.md（八支，已入版控），前兩行是啟動指令與成本承認句，--scope 與卡片範圍一致，第三段是跑完後要交什麼。
• 子卡 Repo 欄選 agent，小弟工作目錄是 Agent 的卡工作區 evidence-agent/.worktrees/CM-3507/，報告寫在那裡的 docs/security-scan/FR-177/，合回後才在 Agent 主資料夾。
• Model 填 opus、Effort low，工作坊預設補成 opus[1m]。理由在手冊第一節：研究員繼承主 session 模型與 context 上限，Sonnet 跑會被 180 秒看門狗砍掉重派。
• 工作坊的停滯判定（session busy 就不判卡死）還沒在真掃描上驗過。第一張跑起來 10 分鐘後用 CLAUDE_CONFIG_DIR=<小弟帳號設定目錄> claude agents --json --all 看 status 是不是 busy；是 idle 就停下來，不要再派。
• 等 FR-172 合回 Agent 主線再開工作坊，八棒掃同一個 commit。開工作坊前在母卡 append 實際 commit hash。

第 1 批驗收結果（2026-11-06，首腦）：四棒 stamp 皆 verified、同 commit bab2aa3、研究員全回。無 HIGH。工具通過 3 條低（A6 F1～F3）、人工補 1 條低～中（A1 M1）；首腦開檔核對四條全部屬實（cert_files.py:106-115、session.py:111、console/api/__init__.py:61、local_auth_routes.py:117-136）。越界：A3／A5／A6 為查證呼叫端翻過範圔外檔（upgrade_order.sh、update_console.py、安裝腳本），均標明只為核對、無越界發現登記。報告複本在 reports/，正本在 Agent repo；run 歸檔 security-scan-consolidated/runs/agent/。四條登記總表 §3.1 第 219～222 項，修正卡等第 2 批驗完統一開。 第 2 批＋第 3 批驗收結果（2026-11-06 01:50～02:30，首腦）：九棒 stamp 皆 verified、研究員全回、面板全部完整跑完（第 2 批掃 3813abd、第 3 批掃 749d3b4，與 bab2aa3 只差報告檔，程式碼相同）。一條 HIGH：B5 F1 手動掃描可手填 InSpec 規則包路徑，首腦四段逐行核對攻擊路徑屬實（scan_routes.py:159 → local_runs.py:114 → inspec.py:872-877 → :913），B2 M1 是同一條從路由層看到的。中 7 條、低 6 條，首腦抽核關鍵行全部屬實。併同項：B5 F1＋B2 M1、B5 F2＋B2 M2、B1 F1＋B3 人工-1。A8 淨新增 0。越界：各棒為核呼叫端翻範圍外檔皆標明只為查證。登總表 §3.1 第 223～232 項。

一個橫向觀察：#223／#224／#229／#232 四條都是「主控台路由層把使用者輸入原樣交下去、沒有每工具／每欄位的白名單」這一族，修正卡可考慮併一張「主控台輸入白名單」統一做；#227／#232 都是「位址可改但沒要求重填祕密或提升權限」，與 SR-06.3 同源。

第 4 批驗收結果（2026-11-06 03:00～03:30，首腦）：四棒 stamp 皆 verified、研究員全回、面板完整（掃 63334f4）。B6a 2 中（F1 併 #224、F2 DNS 換綁 #233）；B6b 0 候選淨新增 0；B7 1 中（手動升級路徑 install.sh:2361-2363 root source 新映像未驗章 bash，#234）；B8 0 候選，人工逐行核時序：自動升級（升級單）路徑先用現行映像 verify-tree 驗新版樹才交棒，A3「新版程式驗章前一行都沒執行」成立；手動路徑的洞與 B7 F1 同條。首腦開檔核 install.sh:2363、upgrade_order.sh:57-61／282／393-416、upgrade_runner.sh:47-55、allowed_targets.py:230-238 屬實。

乾淨的部分（兩棒以上核實）：自動更新鏈三道鎖（A3＋B8）、Ed25519 驗章核心與啟動閘（A5）、8443 JWT 守門殼與五支 cmd（A2）、出向通道無關閉 TLS 驢證的路（A1＋B6b）、證據檔直傳票券（A8）。

修正卡併卡建議（等決策者裁）：

1. 「主控台輸入白名單」一張：#223＋#224＋#229＋#232＋#233，根因都是路由層把使用者輸入原樣交下去、清冊只比對固定鍵名——改成每工具／每欄位列舉可收的鍵、網址目標只收 IP 或主系統列的主機名。#223 是 HIGH，這張優先。
2. 「位址改了要重填祕密／提升權限」一張：#227（LDAP 來源改成只准本機管理員）＋#232 的 pinned_keys（已含在 1）。
3. 「session 生命週期」一張：#220＋#221＋#228，三條都是「該踢的時機沒踢」，同一支 console_session 改。
4. 「升級鏈手動路徑補驗章」一張：#234，install.sh --upgrade 比照自動路徑先 verify-tree。
5. 「DoS 兩條」一張：#225 8443 握手逾時＋#226 tar 逐成員計數。
6. 零碎：#219 私鑰 os.open 帶 mode、#230 診斷包加 scope、#231 總覽吃 include_targets，可併進 1 或 3 順手做。

第三期（已開卡，見上）：connectors 六棒（sonarqube.py 1,711 單檔、inspec.py 1,050 單檔、nmap＋zap、openscap＋openvas＋兩支 sbom）與 netdiag 兩棒，全是 subprocess 組參數；#223 已證明 connector 會原樣吃路由層交下來的參數，第三期的價值在「connector 本體有沒有把其他欄位拼進 argv」。建議先用 Semgrep python subprocess 規則掃一遍，命中點寫進卡。

第二期要補的範圍：A1 指出 device_uuid 算法在 platform/host_identity.py＋fingerprint.py、A3 指出主機端升級腳本 scripts/install/lib/upgrade_order.sh，兩者都不在第一期任何棒內。

小弟掃完只是把卡送到「修正待驗證」，不是結束。每棒首腦照手冊第五節七步驗：核 stamp（面板有沒有真的跑完、幾票投出；candidates: 0 的 verified 是「沒東西可投」不是「乾淨」）→ 讀報告 → 越界檢查 → HIGH 逐條自己開檔 → 「重點看什麼」逐條有沒有人工結果 → 回寫母卡、本頁進度表、跨 arc 總表。工作坊的首腦 session 沒有手冊脈絡，只做形式驗（四件交齊）；實質驗收由有手冊脈絡的首腦 session 做。

修正卡八棒全部驗完才統一開，同檔同根因併一張，優先序照「落地版打得到的綁出貨前、只影響 SaaS 的可暫緩」。掃到 CRITICAL 當場回報決策者，不等全部掃完。

• 前作 FR-077 遠端 Agent 控制鏈資安掃描（主系統側）
• Agent 架構 evidence-agent/docs/ARCHITECTURE.md；FR-170 重整 FR-170-2610-agent-architecture/
• 同族舊發現：FR-108 第 115～117 項（規則包）、FR-084 T1-2（驗章器掉包）、FR-076 L1（硬編公鑰）、FR-075 S1（LDAP 三洞）

以下全部由 build 掃資料夾產生，新增檔案重 build 即自動出現。標題連結指向渲染後的 HTML，md 連向源檔。

交付與收口

reports/（25 份）

證據與盤點

卡片內容（決策紀錄、驗收條件）以 Notion 為準，本頁只記座標。

相關需求：

• FR-077 — remote-agent-security-scan
• FR-170 — agent-architecture
• FR-172 — agent-independent-update
• FR-108 — detection-security-scan
• FR-084 — integrity-security-scan