FR-114 資安修正：合回主線前的整理（給決策者）

首腦第 4 棒整理，材料來自 BOARD／STATE／LOG／各工作區 commit，未逐行核 diff；決策依據以 Notion 各卡「首腦驗收」段為準。

母卡：CM-2019。這份只寫「現在是什麼狀態、合回要怎麼做、要測什麼、要你裁什麼」，每棒怎麼走到這裡的沿革在 FR-114-LOG.md。

53 張卡做完 50 張，程式面第 1～5 批全部驗收過（Done）。 所有改動都還放在四個工作區（worktree，也就是跟主線隔開的副本資料夾）的 fix/security-b1 分支上：

還沒合回主線、套件還沒發新版、任何環境（含 DEV 的服務本身）都還沒部署這批程式。 DEV 資料庫已套過本批六支 migration（資料庫結構異動腳本），首腦 09-23 深夜實查 schema_migrations 六支全在（最晚一支 09-23 12:50）；這是開發期正常狀態。

剩下沒做的 3 張：

• CM-2061（5B-5）：等舊版證據分類退場（CM-1849）做完，才能確認那五件是否跟著消失。
• CM-2071、CM-2072（第 6 批）：要動資料結構，原本就排在「第 1～5 批合回、測過一版」之後。

標「操作會變」的，是使用者畫面或流程會有感的地方，總測時要特別看。

2.1 登入後看不到不該看的

以前很多功能只問「你有沒有登入」，不問「這筆資料跟你有沒有關係」。現在補上了：

• 檔案：稽核證據、SSP 佐證、意見回饋附件等檔案的下載、預覽、換發下載通行證、刪除，都要先確認你是這個檔案所屬專案或單據的相關人；不是的話一律回「找不到這個檔案」，不回「沒有權限」，避免別人拿編號一個一個試（CM-2033）。操作會變：系統認不出歸屬的舊檔（孤兒檔）會變成下載不了。
• 問卷：任務問卷的列表、答案、填答歷史、討論串，改成「該專案任一成員可讀」；空白查詢不再回整張表，直接拒絕（CM-2034）。
• 專案內的各種查詢：流程留言、稽核退回歷程、流程範本、專案與控制項成員、任務指派、摘要報告、稽核輪次、工作項，都會反查「這筆是不是屬於網址上的那個專案、你是不是成員」（CM-2035、CM-2036、CM-2037、CM-2039）。操作會變：摘要報告清單頁只列「我參與的專案」，習慣從這頁看全局的管理者會少看到東西。
• 公告：新增「發送範圍」（全公司或指定部門），讀取時依範圍過濾，點進看不到的公告回「找不到」；既有公告一律標「全公司」，行為不變（CM-2026、CM-2027、CM-2028）。操作會變：公告表單多一個必選的「發送範圍」，選「指定部門」時部門欄才必填。
• 資產與掃描設定的下拉選單：設備、資訊系統、掃描設定檔的讀取改成要有對應的讀取權限（device.read、information-system.read、detection-profile.read），缺權限的角色由 migration 自動補上（CM-2029、CM-2032、CM-2042）。操作會變：真的沒權限時，下拉選單不再「安靜變空」，而是顯示「沒有權限」並鎖住欄位（CM-2082）。
• AI 儀表板與意見回饋：AI 儀表板 26 支查詢各自申報要什麼權限，拿掉「一律當管理者」的後門（CM-2038）；意見回饋清單多一個「查看範圍」參數（只看我的／看全部），管理頁明確送「看全部」（CM-2030）。

2.2 動不了不是自己的資料

• 任務完成與退回：只有該任務的被指派人與專案 manager 能按；弱點檢測的八個按鈕（開始、取消、刪除執行紀錄等）同一套規則（CM-2021、CM-2022）。操作會變：一般成員按別人任務的「完成」會收到 403（拒絕存取）提示。掃描跑完自動完成的那條路維持可用。
• 只有作者能改刪：問卷討論（刪除改成軟刪除，畫面看得出被移除而不是整筆消失）、公告、意見回饋，都比對作者本人（CM-2024、CM-2025、CM-2026、CM-2030）。
• 寫入時反查填進來的東西：專案成員與任務指派寫入時，確認填的任務、群組、控制項屬於這個專案（CM-2023）；範本資源庫三條寫入路徑補歸屬、建立端加次數上限（CM-2040）；SSP 參考文件刪除要確認文件真的屬於這份計畫（CM-2041）；問卷資料夾與即時填答的身分改用登入身分，不信請求裡帶的名字（CM-2060）。
• 全公司共用設定只有總部能改：LDAP、SMTP、登入政策、日誌轉送四處，子公司管理員改會被拒（CM-2054）。操作會變：子公司管理員存檔時收到 403。
• 流程範本：驗證端點要權限且有長度與節點數上限；範本新增、修改一定經過檢查；起稽核輪次要求範本已發布（CM-2031、CM-2059、CM-2083）。操作會變：用草稿範本起輪次會被擋。
• 停權立即生效：帳號被停權後，手上已發出的登入通行證下一個請求就失效，續期也被拒，網頁與即時通訊兩條路都擋（CM-2056）。

2.3 代理程式與防竄改

• 代理程式每次打進來都要證明身分：代理程式（裝在客戶機房、替我們去掃主機的那支程式）登記時，雲端多發一張長效通行證；之後心跳、確認收單、回報結果、下載證據檔四條路都要帶這張證，雲端每次驗章並查資料庫看這台有沒有被撤銷或停用（CM-2052）。操作會變：管理畫面按「撤銷」後，那台機器四條路當場全斷；被撤銷的機器重新登記會被拒，不會洗回正常。
• 重灌後接手原機器要證明：帶舊編號重新登記，必須用舊私鑰簽名證明自己是原機器，否則當新機器處理；登記時送的憑證申請（CSR）上的機器識別碼必須等於本次登記的機器，堵住冒用別台指紋拿真憑證的路（CM-2052）。
• 時鐘偏差警告：代理程式登記與心跳時比對雲端時間，差超過 60 秒就醒目警告（只警告，不中止）。偏差過大時證據檔上傳會全部失敗，以前現場只看得到一行難懂的錯誤（CM-2085）。
• 驗簽工具拔不掉：負責核對簽章的零件（cryptography、cffi）改成強制編進產品核心，不再以可替換的原始檔形式附帶；打包版不再理會「換掉要核對哪個目錄」的環境變數（CM-2053）。
• 鎖定紀錄刪不掉：機器因竄改被鎖後，開機時除了看檔案標記也查資料庫；刪掉標記檔重開，資料庫還有紀錄就照樣鎖，並把標記補回去。解鎖回執要附原廠簽過的解鎖碼，手寫的回執不採信。竄改回報送出的主機紀錄先遮蔽密碼再附上（CM-2053）。

2.4 憑證與設定

• 版控裡的密碼殘留清掉：資料庫管理員密碼（249 檔）、外部平台通行證、AI 金鑰、Google 雲端硬碟金鑰、交接文件帳密、47 檔過期登入通行證，全部從現存檔案清除（不改寫 git 歷史）；開始掃描時不再把明文主機帳密多存一份進派工表（CM-2048、CM-2049、CM-2050、CM-2051）。
• 密鑰不再回傳給前端：儲存設定頁的物件儲存密鑰，後端只回「有沒有設定過」，不回真值；儲存設定也加進密鑰遮蓋名單（CM-2063、CM-2054）。操作會變：密鑰欄顯示遮罩，沒改就不送，只改其他欄位不會洗掉密碼。
• 日誌轉送可加密：日誌轉送設定頁新增「傳輸加密」開關與「信任憑證」欄（CM-2056）。操作會變：設定頁多兩個欄位，既有設定一律維持不加密。
• 連線驗證與版本鎖定：GitHub 連線恢復憑證驗證（CM-2066）；快取連線改用套件已修好的那份（CM-2043）；套件 monorepo 17 支的版本鎖定檔（poetry.lock）納入版控（CM-2067）。
• 交出去的東西先處理：匯出 Excel、Word 時，=、+、-、@ 開頭的內容當文字不當公式；日誌轉送的換行編碼，避免一筆被讀成兩筆（CM-2055）；檔案預覽先驗真實格式，不在白名單或內容與副檔名不符的一律改成下載，HTML 預覽不執行裡面的程式（CM-2062）。操作會變：部分以前能直接預覽的檔案改成下載。
• 各種上限：AI 儀表板與 AI 助手加逾時與次數上限，超過回 429（請求太頻繁）；AI 助手訊息上限 4000 字（CM-2064）；清單每頁筆數上限 1000、設定值打錯字改退回正式模式、寫日誌失敗不連累使用者請求（CM-2065）；弱點檢測規則包解析前擋惡意內容、壓縮檔炸彈上限、測試連線主機數上限、重新解析去重（CM-2057、CM-2058）。操作會變：AI 連按太快會看到「請稍後再試」。

2.5 刪掉的功能

• 三組沒人呼叫的任務管理功能（CM-2044）。
• 開發用小工具 gen_comment.py 與從沒被讀過的死開關；jedi-common 的 [ai] 選配相依跟著拿掉（CM-2045）。
• 全站成員名冊查詢入口 /issue/get_members（資料表與同步程式保留，意見回饋指派負責人還在用）（CM-2046）。
• 「快速設定」獨立畫面兩個入口（專案規劃頁裡的快速配置不受影響）（CM-2047）。操作會變：那兩個網址直接打不開。
• 密碼產生器兩份零引用的重複副本，只留 jedi-iam 那一份（CM-2068）。

3.1 為什麼有順序

三個事實決定了順序，任何一個沒照做，服務會直接起不來或代理程式全斷線：

1. BE 用到了套件的新東西，但 BE 還指著舊版套件。 BE 工作區已 commit 的程式 import 了只有新版套件才有的東西，例如 jedi_remote_agent.api.agent_pass_required（代理程式通行證守門）、jedi_integrity.ports.IBootLockStore（開機查資料庫鎖定）、jedi_common.utils.export_safety（匯出防公式）、jedi-task-platform 的 resolve_project_id_for_job。而 BE 主線 pyproject.toml 仍 pin 舊版（例如 jedi-remote-agent==1.1.2、jedi-integrity==1.1.0、jedi-common==1.2.0）。只合 BE 不發套件，一開機就 ImportError。 runner 開發時是靠 path dependency（直接指向本機套件資料夾）與 PYTHONPATH 繞過去的，那些設定沒有 commit。
2. 代理程式新舊版與雲端新舊版互不相容，而且是兩個方向都不相容。 舊代理程式配新雲端：舊版只認「404 就重新登記」，收到新雲端的 401（未帶通行證）會一直失敗、一直重試，等於斷線。新代理程式配舊雲端：新版登記時要拿通行證，舊雲端不發，新版會當成雲端設定錯誤一直重試。所以雲端與代理程式要同一次上。
3. 套件之間也有新依賴。 jedi-survey 用到 jedi-task-platform 新加的專案成員守門；jedi-issue 與 jedi-log 用到 jedi-common 新加的匯出防公式工具。這幾支發版時，依賴對方的版本下限要一起抬高，否則裝到舊版的組合會壞（這是我從 import 查到的三處，發版的人要再全面 grep 一次）。

首腦不合回、不發版、不部署，下表每一步都由決策者或你指定的人執行。

3.2 步驟表

3.3 要發版的 17 支套件

依「除了測試與 lock 之外有沒有改到程式」判斷。以下是工作區 fix/security-b1 相對 feature/review 的實際變動（排除測試檔與 poetry.lock）：

不用發版的 4 支：jedi-evidence-classification、jedi-license-runtime、jedi-notification、jedi-oscal-v2 只多了 poetry.lock 入版控，lock 不進發布出去的套件檔，程式沒變。

注意：派工時給我的 18 支清單裡有 evidence-classification、license-runtime、notification（只有 lock），但沒有 jedi-compliance-audit（7 檔程式）與 jedi-system-core（1 檔程式）。以上表為準。

3.4 合回時要對得上的關鍵 commit

合回的人核對用。每個 repo 的完整清單用 git -C <工作區> log --oneline feature/review..HEAD 看。

BE 與 FE 主線在工作區分岔後：BE 主線多了 77 筆（只和工作區在 docs/features-site/ 重疊，見第 4 節），FE 與代理程式主線沒有新 commit，可以直接快轉合回。

3.5 出事怎麼退

合回之後、總測之前如果發現起不來或大面積壞掉，退法依壞在哪一層：

• BE 起不來（ImportError）：幾乎都是步驟 2、3 漏了某支套件。先看錯誤訊息指的套件名，確認 Nexus 上有新版、BE pin 有改、poetry update 有點名它。不要用 path dependency 臨時救，那會把開發設定帶進主線。
• 代理程式全斷線：先看雲端與代理程式是不是都換成新版。只換了一邊就把另一邊也換上；兩邊都要退時一起退，不可只退一邊。
• 某個功能被新守門擋住正常使用者：先確認那個角色有沒有對應權限（第 6 節的兩支補權限 migration 是否已套）。確定是守門寫錯才開卡改，不要為了讓總測過而拿掉守門。
• 整批要撤：四個 repo 的合回各自是一筆合併 commit，可以各自 revert；套件已發出去的新版號不收回，BE 把 pin 改回舊版號即可。資料庫那六支 migration 都是「只加不刪」（加欄位、補權限、放寬一條新增規則），留著不影響舊版程式運作，撤程式時不必撤資料庫。

建議開一張清理卡一次做完，在四個工作區裡 commit，做完再進第 3 節步驟 1。

這是唯讀驗證，不部署、不動 STG。 CM-2053 把驗簽工具改成編進核心，有三件事只有跑一次完整打包才看得到，runner 只在 188 跑過單支套件的小探針（編 cryptography 33 秒、驗章正常），沒跑全量。

在哪跑、開跑前做什麼：

• 188 的 /opt/guidant-ai-be，先 git pull 到合回後的主線 commit（部署機一律 git pull，不 scp）。
• 開跑前 pgrep -f 'nuitka|build_all' 確認沒有別的 build 在跑（互撞會 linker crash）。
• 照 188 固定陷阱：指定 smoke 專用臨時庫（不要連 STG 那顆庫、不要去套 migration）、注意 FE image 標籤、先看磁碟。細節見 scripts/build/README.md。
• 出貨基線要先重產（第 6 節），否則 build 的 stamp gate（出包前檢查基線有沒有跟上 migration 的關卡）會紅。

要驗的三點：

背景：新客戶安裝時不是從頭重放每一支 migration，而是載入 scripts/init/02-schema.sql 這份「已經長好的資料庫結構」。主線新增了結構類 migration 卻沒更新這份檔，新裝客戶就會少掉那些欄位，而且服務全綠、沒有任何錯誤訊息。

本批六支 migration（全都已登記在 scripts/sql/manifest.tsv）：

STATE 寫「七支」是多算了：實際是六支檔，其中四支要進基線，兩支補權限的是資料類，照規則本來就不進 02-schema.sql（資料類硬塞進基線蓋章，等於宣告那些資料永遠不插）。另外套件隨包的三支 migration（jedi-bulletin 001、jedi-issue 004、jedi-log 005）走攤平流程，不屬主專案基線。

重產要寫入 188 上的基線庫，屬於環境異動。 卡開好等你一句「做」。步驟（先備份、只套這四支、重產兩份產物、驗 diff 只有新增、本機重跑 stamp gate）見 .claude/skills/sql-migration/SKILL.md「首腦重產的步驟」，這裡不抄。建議時機：合回主線後、188 全量 build 之前。

你 09-23 裁「最後從安裝到功能整個重測一遍」。以下按六組列，每條都是能親手點、親眼看的。標 ★ 的是 opus 抽查時退回過、修法有判斷，請優先測。

測試帳號建議先備好：專案 manager、同專案一般成員（viewer）、不在這個專案的同公司帳號、子公司管理員、總部管理員、一個自建且拿掉讀取權限的測試角色。

7.1 安裝與升級

7.2 登入與權限

7.3 專案流程

7.4 代理程式

測這組需要工程師在旁邊，部分項目要用 runner 在 DEV 實跑過的那組腳本送請求。

7.5 防竄改

在 build 產物上測，不是在原始碼模式測（原始碼模式刻意不查資料庫鎖定）。

7.6 設定頁

7.7 測完怎麼回報

• 每組測完，把「哪一條不如預期、實際看到什麼、用哪個帳號」記下來，全部測完再一次交給首腦，不要測一條修一條。
• 首腦依回報分三類：守門寫錯（開卡改程式）、權限資料缺（補 migration）、預期行為但使用者會困惑（改文案或手冊）。
• ★ 那幾條如果有任何一條不過，先停，不要往 STG／POC 推。

8.1 報告裡還沒修的

資安檢視總報告（docs/security-report/SUMMARY.md）145 件，目前狀態列還標未修或部分修的有 23 件：

分三類說明：

本批已做完、只是狀態列還沒改的（6 件）：#1（代理程式身分）、#17、#18、#90、#133（防竄改），這五件改「已修」；#91（解鎖碼帳本壞掉）改「部分修」，因為目前只記警示不拒絕，原因見下。

本 arc 範圍內、排在後面的：

• #9、#66、#67（舊版證據分類）：由 CM-1849 舊線退場處理。
• #89、#129～#132（舊版證據分類的另外五件）：等 CM-1849 做完，CM-2061 確認。
• #23、#24、#104、#105（資料庫隔離牆）：第 6 批資料庫牆，等第 1～5 批合回測過一版才開卡。
• #41（標「部分修」）、#109（標「功能本身已斷」）：第 6 批 CM-2071、CM-2072 補資料結構後收尾。

不在本 arc 的：

• #75（前端打包腳本裡的套件庫帳密）：沿用 CM-1998。
• #98（每套安裝都種同一組最高權限帳密）、#99（三環境公鑰並列）：已裁暫緩。
• #101（內部套件庫走明文）：已裁內網不修，lock 已入版控，標部分修。
• #96、#97（郵件）：寄信失敗時把整組郵件設定含密碼寫進紀錄檔；連郵件伺服器有加密但不認對方身分，攔在中間的人能收走帳密與每封信（含一次性驗證碼、新帳號初始密碼）。這兩件模組頁寫「工單 CM-1606 已開、未排期」，不在本 arc 任何一張卡裡。要你裁（見第 9 節）。

8.2 開機查資料庫失敗時一律放行，範圍比原裁示大

場景：客戶的產品主機開機時，防竄改機制會去資料庫查「這台有沒有未解除的鎖定紀錄」。你原本裁的是「資料庫連不上時放行並警示」，理由是不能因為資料庫暫時掛了就讓客戶整套起不來。

現況：jedi-integrity 的 boot_db_lock.py 把任何查詢失敗都當成「連不上」處理，包括「表不存在」「權限不足」「資料庫密碼設定缺欄位」。後面這幾種其實是連得上、但查不成功。

風險：一個有主機權限、想繞過鎖定的人，如果能讓查詢失敗（例如改掉資料庫帳號的權限），開機就只剩檔案標記那一道。要你裁（見第 9 節）。

8.3 另開卡候選（不在本 arc）

• 離線機器的指紋可被接手：受害機離線時，別人直接用受害機的機器指紋登記，會照「重灌後接手」的設計拿到同一列。這是既有設計，不是本批造成（CM-2052 抽查點出）。
• 公版只有一個管理員角色：出貨公版只內建 Administrator，客戶自建角色從零勾。以後每加一顆讀取守門，客戶都可能踩到「選單變空」。長期正解是公版內建幾個一般角色範本，預勾讀取類權限。
• 兩支沒人呼叫的方法：摘要報告的 get_project_summary_reports、get_project_summary_report_by_id，可刪。
• 稽核階段「目前進度」查詢：非成員仍查得到資料（CM-2035 範圍外）。
• list_ap_parties 查不到輪次就放行：寫法偏寬，總測時留意（CM-2037 順帶）。
• 儲存設定新建時密碼留空：只有前端擋，後端 create_system_config 沒檢查（CM-2063 順帶）。
• tamper_event_repo.exists 沒人呼叫：開機查鎖改由宿主的短命連線做，這支舊方法閒置。
• 管理者代刪問卷討論：CM-2024 卡上沒要求，沒做。

8.4 擋得到、擋不到的分界

不要把這批修正理解成「風險歸零」。

• 代理程式（CM-2052）：修完後，網路上的外人冒充不了代理程式、A 客戶冒充不了 B 客戶、被撤銷的機器當場斷線。擋不到的是能實際碰到那台代理程式主機的人，他撈得到機器上的私鑰與通行證。這是設計本身：代理程式要登入客戶主機做掃描，就一定得拿到那些鑰匙，而那台機器在客戶自己的機房。風險範圍從「網路上任何人」縮小到「能實際碰到那台機器的人」。
• 防竄改（CM-2053）：修完後，換掉驗簽零件、刪標記檔、手寫回執、換核對目錄這幾條已知的一步得手路徑都堵住了。擋不到的是有能力改整包執行檔（binary）的人：驗簽工具編進核心層，是讓「換一個零件」不再可行，但能整包重編或改二進位的人仍然繞得過。這套機制的定位是擋住隨手改檔案，不是擋住有完整主機權限又懂內部運作的攻擊者。
• #91 為什麼只記警示：解鎖碼帳本檔毀損時如果直接拒絕開機，而原廠目前沒有「帳本壞了重新簽發」的流程，機器一壞就永遠解不開。所以降級成高等級警示，等原廠有重簽流程再收緊。

① 什麼時候合回

• 現在合：清理卡做完就照第 3 節步驟開始合回、發版、部署 DEV、總測。第 6 批與 5B-5 之後在主線上另外做。
• 等 5B-5 與第 6 批一起：三張剩下的卡也做完才一次合回。代價是第 6 批要等 CM-1849，時間不確定，這段期間主線繼續往前跑，合回衝突會變多。

② 發版順序確認

• 照第 3 節步驟表：套件先合先發（jedi-common 最先），BE 改 pin，FE，代理程式，然後雲端與代理程式同一次上 DEV。你只要回「照表」。
• 要調整：請指出哪一步要換。

③ #96、#97 郵件密碼寫進紀錄檔與連線不認人

• 另開卡納入本 arc：改動小（錯誤訊息不帶整組設定、加密時驗證對方憑證），可以跟這批一起合回、一起總測。
• 維持 CM-1606 另排：本批合回不等它，報告上這兩件繼續標未修。

④ 開機查資料庫失敗時的放行範圍

• 維持現狀：任何查詢失敗都放行並警示。客戶端資料庫任何小毛病都不會擋開機，但「改權限讓查詢失敗」這條繞法留著。
• 收窄：只有「真的連不上」才放行，「連得上但查詢失敗」改成拒絕開機。擋掉那條繞法，代價是資料庫權限或結構有問題時客戶會開不了機，要靠支援排除。

⑤ 出貨基線什麼時候重產

• 合回主線後、188 全量 build 前做（建議）：build 的出包檢查才不會紅。
• 等 STG／POC 上版前再做：現在不動 188 基線庫，但在那之前出不了包。

⑥ 另開卡候選要開哪些（第 8.3 節八項，每項回「開」或「不開」即可）

• 我的建議：「公版一般角色範本」與「儲存設定後端密碼空值檢查」值得開；「兩支死方法」「tamper_event_repo.exists」可以併進下一張清理卡；其餘總測時觀察再定。

⑦ 小事，合回時順便裁

• 套件 monorepo 還有 10 支沒有 poetry.lock（含 6 支封存的），要補：合回時一起跑。不補：維持現狀，只有那 17 支有 lock。