FR-177.A1 掃描報告：Agent 註冊、憑證與身分

⚠️ 歷史紀錄：本報告描述的問題已於 2026-11-07 全部修正並合回 Agent 主線（修正卡 CM-3559～3564、3573～3576、3584，驗收紀錄見母卡 CM-3507）。文中的檔名與行號是掃描當下（commit bab2aa3）的版本，修正後已變動，請勿拿來定位現行程式。

工具沒找到問題；我自己照「重點看什麼」逐條核對，找到 1 個值得開修正卡的小問題（嚴重度：低～中）：私鑰檔建立的那一瞬間權限是「大家都能讀」，之後才改成只有本人能讀，而且改權限失敗時會默默放過。其餘六點人工查過都不成立。

Agent（裝在客戶機器上的程式）第一次裝好時怎麼向主系統報到、拿到自己的憑證與通行證；憑證快到期時怎麼自己換新；這些金鑰檔怎麼存在客戶機器上。這段是 Agent 身分的根：私鑰或通行證被同機其他程式拿走，就能冒充這台 Agent 跟主系統講話。

範圍 6 個檔、1336 行：guidant_agent/sync/app/enroll.py、guidant_agent/sync/app/cert_renew.py、guidant_agent/sync/domain/registration.py、guidant_agent/sync/domain/agent_auth.py、guidant_agent/sync/adapters/cert_files.py、guidant_agent/platform/agent_identity.py。

急不急：不急，排一般修正卡即可。打得到的前提是「客戶機器已經被別人登入」；正式安裝形態下憑證目錄多半在只有服務帳號能進的資料目錄裡，會再擋一層（本棒範圍外，未核對）。

M1 — 私鑰檔建檔當下權限太寬，改權限失敗默默放過（低～中）

• 白話：程式寫私鑰檔的步驟是 ① 用一般方式開新檔（這時檔案權限跟著系統預設，Linux 一般是「擁有者可寫、所有人可讀」，也就是 0644）② 把私鑰寫進去 ③ 才把權限改成「只有擁有者能讀寫」（0600）。①到③之間有一小段時間，同台機器的其他帳號讀得到。另外③如果失敗（例如某些掛載點不支援改權限），程式直接略過、連一行 log 都沒有，私鑰就一直是大家可讀。
• 出事會怎樣：拿到 agent.key＋agent.crt 的人可以自己簽「持有證明」（DPoP，就是每個請求附上「我真的有這把私鑰」的簽章），再配上 agent.json 裡的通行證，就能以這台 Agent 的身分打主系統；拿到私鑰還能在換證時冒充「舊的那台」。
• 要先有什麼才打得到：
  1. 攻擊者在客戶機器上已經有帳號（或能跑程式）；
  2. 憑證目錄對他是可進入的——enroll.py:90 用 os.makedirs(cfg.cert_dir, exist_ok=True) 建目錄，沒指定權限，跟著系統預設（通常 0755）；
  3. 剛好在註冊／換證那一刻讀，或者遇到改權限失敗的掛載點。
• 在哪裡：
  • guidant_agent/sync/adapters/cert_files.py:110：open(path, "wb") 建檔，沒指定權限
  • guidant_agent/sync/adapters/cert_files.py:112-115：寫完才 os.chmod，OSError 直接 pass
  • guidant_agent/sync/app/enroll.py:131（私鑰）、:138（含通行證的 meta）：呼叫上面那支
  • guidant_agent/sync/app/enroll.py:90：憑證目錄建立沒指定權限
  • 附帶：首次註冊（enroll.py:93 → write_registration 直接寫正式目錄）不是「先寫暫存再改名」，中途斷電可能留下寫一半的檔。後果只是下次開機判定不完整而重新註冊（is_enrolled 要四個檔都在），或某檔是半截而啟動失敗；換證那條（cert_renew.py:185-195）已經走暫存目錄＋swap，沒這個問題。
• 怎麼修：在 cert_files.write_secret 裡改成「建檔當下就給定權限」：fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, mode) 寫進暫存檔、os.fsync、再 os.replace(tmp, path)；mode=0o600 時若 os.chmod／os.open 權限設定失敗就 raise（或至少 logger.warning），不要默默 pass。enroll.py:90 改成 os.makedirs(cfg.cert_dir, mode=0o700, exist_ok=True)，並對既有目錄補一次 os.chmod(cfg.cert_dir, 0o700)。
• 核對註記：本條是 runner 開檔讀出來的，工具的研究員沒提、三人投票沒投過。系統預設權限（umask）在正式安裝時實際是多少、install.sh 有沒有事先把目錄設成 0700，不在本棒範圍，沒查；如果安裝腳本已經鎖住目錄，實際風險降為「只剩改權限失敗那條」。

• 「這些問題存在嗎」：M1 是 runner 開檔逐行讀出來的，行號都對過，但沒經過三個獨立檢查員投票。程式邏輯本身確定（建檔→寫→改權限、失敗 pass），實際風險取決於安裝時目錄與系統預設權限，這部分沒查。
• 「只有這些嗎」：不能這樣宣稱。 工具只派了一個研究員，他回報零條；三個檢查員因此沒有東西可投（0 票）。工具標示的「verified（已驗證）」在這裡的意思是「沒有東西需要驗」，不等於確認這六個檔是乾淨的。另外 device_uuid 的算法、主系統那頭驗不驗 SAN，都在範圍外。