FR-064 交接現況（STATE）

✅ ARC CLOSED — 2026-08-16 收尾：母案 CM-1188＋34 卡全 Done；兩 P0（BUG-1 死透／BUG-2 指紋）真 image 實證修復；188 已用 compose 起含兩 P0 的正式容器。收尾彙整見同資料夾 2026-08-16-FR-064-SUMMARY.md。下方為收尾當下現況快照，保留供回顧。

這份是 living 檔：每棒就地 Edit，只描述「此刻」。歷史脈絡看同資料夾的 FR-064-LOG.md。

三階段落地版戰線第二棒（FR-063 編譯 ✅ → FR-064 防竄改【本案，母案 CM-1188】 → FR-065 Installer）。

• 需求：客戶機上偵測產物被竄改 → 終結服務＋鎖定，唯一解鎖＝原廠一次性 unlock token。
• 定位（已對齊）：client-side 驗證擋不住決心逆向者，目標「99% 不值得＋1% 留蓄意痕跡」，B2B 法律層是真防線；離線必須成立。
• 機制：build 期逐檔 SHA-256 分層 manifest → LC Ed25519 簽章（復用 FR-062 體系，泛用 sign_payload/verify_payload，判別鍵 payload_type、缺鍵視為 license 保向後相容）→ 啟動 gate 驗章＋比對 core/resources → runtime 4h 抽查＋業務埋點 → tamper 雙落點（DB 全域單例表＋FS 標記）→ 拒啟鎖定。

首腦＝分析決策／協調；實作全走 runner（開 case 給新 session 為主，機械小修才本體 subagent）；驗收一律親驗不信自報。

D1–D10 全拍板 2026-08-15，D11 拍板 2026-08-16，完整表在 design.md §2（索引：分層驗證／簽驗共用層／main.py 錨點／唯讀化／雙落點／離線 unlock／邊界承認／4h+jitter 抽查／D9 回報 LC／D10 二次確認／D11 lockdown 殼＋forensic 存證＋邊界明文）。

git

BE 最新（新→舊）：19a086af CM-1242 掛載宿主 /etc/machine-id 修指紋漂移（BUG-2，未 push）／11c9502e＋7cc7989e CM-1241 BUG-1 終止改依承載送訊號（未 push）／0aaa0269 STATE 用語消歧／4e64ca07 CM-1231 殼內容協商改只看 Accept（UA 嗅探讓 XHR 拿到 HTML 的修正）／adf77882 CM-1236 scripts/README 修正／2d56edb6 CM-1238 落地版 docker-compose 定式（api+socketio 雙容器＋pki volume）／4c06ddc8 CM-1236 scripts/ 盤點整理／f929abe7 CM-1237 build_all.sh 一鍵管線／be3868f4 STATE/LOG docs／aeb2bd44＋24834d73 T-8.3 forensic。更早鏈（T-8.1 殼 520fc5e3、T-5.2 f8133e72、gate/manifest/唯讀化等）見 LOG。

Notion 卡（2026-08-16 傍晚盤點實況）

DEV DB

integrity_tamper_events 表存在確認 ✅（psql -h 192.168.50.188 -p 25432 -d guidant_ai_dev，to_regclass 回表名）。

188 實況（2026-08-16 傍晚唯讀查證）

• /opt/guidant_ai：branch feature/FR-064、HEAD 4e64ca07（與本地同步）
• 正式容器：guidant-api＋guidant-socketio 皆 guidant-ai-be:1.14.0、Up (healthy)；guidant-api log 有 [INTEGRITY] 產物完整性驗證通過（core+resources 共 1304 檔，version=1.14.0） ✅ gate 真容器實跑通過
• /srv/guidant/pki/：空（tamper 標記已清）✅
• image：本機 guidant-ai-be:1.14.0＋:latest 皆 2026-08-16 15:38 新打；Harbor tag 仍是 08-15 舊版（新 image 未推）
• /opt/license_center：HEAD 651db9c（與本地同步）；systemctl is-active license-center → active
• FE 部署 bundle：/var/www/html/audit-manager/assets/index-B6KcAQdr.js 含 INTEGRITY_503001（×2）✅ 鎖定碼已在線上 bundle
• 附註：/opt/license_center 對 jedi 帳號有 git dubious ownership 警告，查詢需帶 -c safe.directory=/opt/license_center

188 真 dist 產 manifest（core 1291/resources 13/thirdparty 5492）→ LC 簽章（kid 04b1e65f＝STG 鑰）→ BE verify_payload 驗章 PASS → 三層各抽一檔 sha256 與實檔全中。首次端到端全通。

第 7 棒已銷：gate 真 dist／正式 image 唯讀化／真容器 gate／殼真容器。

第 8 棒已銷：殼修正（4e64ca07）後整鏈（真 image BE 側四組協商全對：瀏覽器 UA＋JSON Accept 回 INTEGRITY_503001 JSON；FE 側 user 已於第 7 棒實測）／真實已出貨 license 匯入迴歸（三環境三把 kid 真照全過＋兩條負控＋D2 缺鍵向後相容確認）／T-7.1 五條中的 A-1／A-3／A-5 縮短版／殼在 orchestrator 下的行為（unhealthy 但不進重啟迴圈）。

第 9 棒已銷：C-1 scheduler 觸發×兩承載（scheduler 路徑不同病，修前修後皆 exit=1 死透）。

第 10 棒已銷（CM-1242）：C-2 真產物×gunicorn hook 觸發後服務死透（真 image 1.14.0 實測 Handling signal: quit→Shutting down: Master→容器 Exited、ping 000，BUG-1 修正端到端成立）／A-2 運行中改檔觸發（同上，hook 正常判定並終止）／A-4 unlock 真容器完整循環（鎖定→LC 簽 token→放檔→restart 解鎖成功＋標記清＋nonce 入帳＋DB unlocked_at 回填，四條負面案他機／過期／錯事件編號／重放全擋）／socketio 承載死透（PID 1＋eventlet＋APScheduler 條件下 _termination_signals() 回 []、os._exit(1)、容器 Exited(1)）／BUG-2 指紋漂移（掛載後跨 restart／換容器皆不變，附不掛載的負控復現）。

仍未實證：

1. 正式／STG／POC 尚未套用 machine-id 掛載——第 10 棒只改 repo 內 compose 檔與拋棄式容器；正式部署需 docker compose up -d recreate 兩容器才生效，等決策者放行
2. socketio 真 image 的完整竄改→死透鏈——第 10 棒 V5 驗的是承載條件下真的 _terminate_process()；「真 binary 被改→真抽查 job 比對出不符→終止」在 socketio 模式未實跑（8002 不載 REST 故無埋點端點、抽查 4h 且參數寫死不可調）。比對邏輯與 api 共用同一份 runtime_check，風險低但非已驗
3. scheduler×真 binary×4h 真窗——縮短間隔驗過不等於真窗驗過，由時間自然銷或後續長跑驗
4. 「≥24h 連續運行跨多輪抽查零誤報」（A-5 完整版）
5. 宿主無 /etc/machine-id 時 docker 建成目錄的退化行為——屬 docker 已知語意（掛載來源不存在時依目標推斷建立），deployment-env.md 已寫前置檢查，但未在缺檔宿主上實測；同理「machine-id 重生成會讓既有綁機憑證失效」亦為推論（不宜在 188 重生成驗證）
6. K8s liveness 下殼會 CrashLoop——第 8 棒觀察推得：Docker restart policy 只看 process 退出故安全，但 K8s liveness probe 失敗會 kill+重啟 pod → 鎖定態變 CrashLoop。FR-065 installer 若涵蓋 K8s 部署，需把鎖定態排除在 liveness 之外（目前 compose 落地版不受影響）

BUG-1（CM-1241，第 9 棒修，第 10 棒端到端證實）

症狀：真產物×gunicorn 下 hook 觸發 tamper 後服務沒死透——落點都寫了、FATAL 也印了，但 master 存活並 respawn，服務照常回 200。 真因（第 9 棒推翻原假設）：不是「master 收到 SIGTERM 走 graceful 沒死」，而是master 根本沒收到——容器內 pgid=1，killpg(1,sig)＝kill(-1,sig) 是 POSIX 廣播特例、Linux 明文排除 PID 1；且 kill(1,SIGKILL) 對無 handler 的 PID 1 也被核心忽略。 修法：_terminate_process() 改依承載分流——gunicorn worker 指名對 master 送 SIGQUIT（有 handler 收得到、quick shutdown 不 respawn），單 process 承載／容器 PID 1 只 os._exit(1)，bare metal 僅 pgid==pid 時 killpg。master pid 由 main.py post_fork 登記。 第 10 棒真 image 端到端證實：Handling signal: quit → Shutting down: Master → 容器 Exited、ping 000 ✅

BUG-2（CM-1242，第 10 棒修）

症狀：容器機器指紋每次重啟就變 → 解鎖憑證重啟即失效（永遠解不了鎖）、license 綁機漂移。 根因：Debian base image 的 /etc/machine-id 是 0 bytes 空檔（容器不跑 systemd 永遠填不上）＋/var/lib/dbus/machine-id 不存在 → 指紋退到第三級 uuid.getnode()（容器 MAC，每次 restart 就換）。 修法（選項 A，code 零改動）：compose 掛 - /etc/machine-id:/etc/machine-id:ro，指紋穩定錨定宿主機。實測跨 restart／換容器皆不變，附「不掛載」負控復現 bug。 ⚠️ 掛的是檔不是目錄——宿主缺檔時 docker 會建成目錄、指紋靜默退回 MAC，症狀與沒掛一樣；deployment-env.md 已補前置檢查。 綁機回歸：DEV 16 列綁舊指紋但全為歷史照（is_current=false），現行照 0 列綁機；STG/POC 皆 null → 無回歸。

相關卡：

• CM-1241 https://app.notion.com/p/FR-064-BUG-1-P0-hook-tamper-gunicorn-master-respawn-C-1-scheduler-3be346da4cd08132869ddb39342bf307
• CM-1242 https://app.notion.com/p/FR-064-BUG-2-P0-etc-machine-id-MAC-3be346da4cd081bd9495dc084c71845c
• 發現棒 CM-1229 https://app.notion.com/p/FR-064-T-7-1-License-3bd346da4cd08129b06afef7612b71d4

1. CM-1241 修 BUG-1 ✅（第 9 棒）／CM-1242 修 BUG-2＋複驗輪 ✅（第 10 棒，A-4 unlock 真循環＋socketio 死透一併銷案）
2. 🔴 user push 三支未 push commit（7cc7989e／11c9502e／19a086af）→ 188 pull → rebuild image（含 BUG-1 修正的 1.14.0 已在 188 本機，但 BUG-2 是 compose 組態不需 rebuild）
3. 正式／STG／POC 套用 machine-id 掛載（docker compose up -d recreate 兩容器）——等決策者放行，非開發期動作
4. CM-1239 解鎖 SOP 文件（已完成 91a3bcd8，修正待驗證）；CM-1240 FE details 開關已收 Done（29fead0 待 push/部署）
5. version-bump（現標 1.14.0，含 FR-064 出貨前走 version-bump skill）＋母案 CM-1188 收尾（等 user 令收 Done）——兩個 P0 已解除，此步的阻斷條件已消失
6. 場外：CM-1204 待排程；probe「問卷上傳落點」存量問題待開卡（T-6.2 發現）；AGENT_CERT user 另 session；test/ 下 9 支 AI Dashboard 舊測試 collection error（與 scripts/archive 同批，待 user 裁）

⚠️ 本節是建議清單，不是執行授權。接手方讀完盤點完即停，等 user 發令。

竄改測試 SOP（接手複驗用，第 7 棒實戰校正版）

• 絕不對正式 compose 容器測（read_only 改不了檔；且標記會寫進正式 /srv/guidant/pki，殘留會讓正式容器一直拒啟——本棒實際發生過，復原＝rm /srv/guidant/pki/.integrity-tamper＋compose 重起）
• 正確做法：拋棄式可寫容器＋-v /tmp/pki-test:/opt/guidant/pki；要看 FE 就讓它佔 8000（先 docker rm -f guidant-api，測完 compose 起回來）
• 改檔對象必須是 manifest 清單內的檔（resources 層模板檔最方便）；清單外新增檔案不觸發（設計如此，log/上傳/DB 都不在驗證範圍）
• unlock 眉角：fingerprint 抄該容器印的；解鎖前先把檔改回（否則解鎖後立刻再鎖，屬設計）；重啟用 restart 不可 rm（rm 換 fingerprint、token 作廢）

第 8 棒補充（真產物實測校正）：

• 要驗 DB 落點必須 -e DB_NAME=guidant_ai_dev 覆寫——拋棄式容器沿用 /srv/guidant/guidant.env 會指向 STG（該庫無 integrity_tamper_events 表）。啟動 gate 本就不寫 DB，所以只驗 boot 拒啟時不必覆寫；驗 runtime／hook 落點時必須。
• 改運行中的 binary 要用 unlink+rename：printf >> /app/guidant-ai 會被 Text file busy 擋下，正確作法 cp → 改副本 → mv 原檔改名 → mv 副本頂上。用前者會誤以為 binary 天然免疫。
• Nuitka 產物的埋點實際只驗 binary 一檔：_HOTPATH_PRIORITY_PREFIXES 那三個 common/* 前綴在真產物中不存在為獨立檔（全編進 binary），manifest grep 零命中 → 選檔退化成只剩 binary 本體。要觸發 hook 偵測，改的必須是 binary。
• 觸發 hook 的端點：POST /api/1.0/license/upload（需 root tenant（/1/）admin token，一般租戶 admin 會被 GRC_403060 擋在埋點前）或 SSP 報告匯出。

第 10 棒補充（CM-1242 指紋與 unlock 實戰）：

• 拋棄式容器必須加 -v /etc/machine-id:/etc/machine-id:ro，否則指紋每次 restart 就變、unlock token 必然對不上（BUG-2 本體）。加了之後 188 上的指紋恆為 ff793254d00c364107dda07846e5e90e4d4db79fbdbd2a4259fdf24e4a3da080。
• 查指紋三個出口（同一個值）：① 服務正常時 GET /api/1.0/license/activation/machine-code（需登入＋DEPLOYMENT_MODE=host，故拋棄式容器要 -e DEPLOYMENT_MODE=host）② 鎖定時看拒啟 log 的 machine_fingerprint: 行，或 lockdown 殼 503 JSON ③ 標記檔 .integrity-tamper 的 machine_fingerprint 欄位。
• root tenant admin 帳號＝admin／密碼同 DEV 慣用（blsadmin 是 tenant 102，打埋點端點會被 GRC_403060 擋掉）。
• 驗「過期」負面案不能用 CLI --valid-hours（有 1–336 下限防呆，擋在簽發端就中止了，核銷的效期關根本沒執行到）——要用 LC 私鑰 sign_payload 直接造「真簽章但 expires_at 在過去」的 token（load_private_key(Path("/opt/license_center/keys/private.pem"), os.environ["LICENSE_CENTER_KEY_PASSPHRASE"].encode())）。
• 驗「重放」要先手工重建標記檔（解鎖成功後標記已清），把同一個 event_uid 寫回 .integrity-tamper 再放已用過的 token。
• socketio 承載無法用埋點觸發：8002 不載 REST blueprint（main.py 設計），且抽查 4h 週期參數寫死不可調 → 要驗終止行為得自建 harness 重現承載條件（PID 1＋monkey_patch(all=False, socket=True)＋socketio.run＋BackgroundScheduler）但 mount 真源碼執行（PYTHONPATH=/src）。

• 開發只動 DEV；STG/POC 寫入等 user 明示
• 188 程式碼一律 git pull（先 checkout feature/FR-064——上次事故主因）
• STG 188 兩服務跑舊產物勿動
• LC 部署四步（pull → 依賴 → alembic PYTHONPATH=src → restart，見 memory feedback_lc_deploy_four_steps）
• 189 POC 的 LC 落後未對齊