跳轉到

Guidant AI v1.24.0 Release Note

項目 內容
版本 1.24.0（功能版號；主軸＝資安測試出的修正全案——FR-126 依 81 條安全需求逐條測試後測出的缺口，17 張修正卡一次落地）
發布日期 2026-10-04
上一版本 1.23.1（2026-10-01）
涵蓋區間 2026-10-01～2026-10-04（BE c13f4fd3c..本版進版 commit；FE 7368d98..本版進版 commit）
涵蓋需求 FR-126 資安測案擴充與修正（母卡 CM-2384）、CM-2401 共用設定讀取卡總部層級、FR-127 GitLab 一鍵發版到 e2e 與 SBOM
規模 jedi-* 套件升版 14 支（remote-agent 1.3.0 為功能版號，其餘 patch）；套件自帶 DB migration 3 支；主線 migration 無新增；服務組成不變
適用部署 先升 190 e2e 專機跑資安全套重跑；STG／POC 待決策者放行；仍為 --skip-prod-key-check 內部測試包
部署性質 服務組成不變；Redis 改三個服務各自帳號（升級自動補）；三支套件 SQL 隨 migrate 輪套；BE 第一次啟動自動把既有整合憑證加密

為什麼是功能版號不是 1.23.2：代理程式報到多了「待核准」新狀態、三支套件帶 migration、jedi-common 共用錯誤碼對外契約改變（數字碼改 COMMON_* 字串），不是純 bug fix。

0. 發版前回歸 gate

本版不在發版前跑 site-regression。把關改在部署 190 之後由 FR-126 第 3 棒跑資安測案全套（API 約 150 情境、守衛 280+、部署檢查 49 項）頂替，決策者已知。17 張修正卡各自在 DEV 驗過（單元測試、守衛測試、實打端點，細節見各卡與 commit message）。

1. 概述

FR-126 把資安總報告的 81 條安全需求（SR）逐條寫成自動化測案，跑下來測出 22 條紅與後續約 15 個新缺口。本版把它們全部修掉：

  • 登入與身分：雙因子第二關改驗第一關簽發的憑據，不登入就不能猜驗證碼；雙因子失敗次數改記在資料庫，重啟不歸零。
  • 代理程式報到：註冊 token 有效期與使用次數上限；新報到的機器先進「待核准」，管理員核准前雲端不派工給它。
  • AI：租戶只能填金鑰、不能改 AI 位址；AI 出口守門「阻擋」級真的會攔（之前只記不攔）；AI 呼叫紀錄的明文清理排程恢復運作。
  • 祕密與錯誤訊息：SMTP／儲存／LDAP 等整合憑證加密存庫；設定遮罩改白名單；log 出口一律過遮罩；資料庫錯誤不再把原文回前端。
  • 前門與即時連線：nginx 加安全標頭、HSTS、請求大小分級上限、免登入端點限速；CSP 先以 Report-Only 上線並收違規回報；即時連線限同帳號連線數與事件速率。
  • 權限邊界：非成員一律回 404（與資源不存在相同）；唯讀成員不能刪證據檔；全公司共用設定（SMTP／LDAP／登入政策）讀取也要總部層級。
  • 外部呼叫與匯入：通知逾時、webhook 防 SSRF、Drive 覆寫網址只收 https、所有 Excel 匯入先過壓縮炸彈檢查、SSP 匯入不洩 SQL。
  • 檢測與 Redis：掃描外部位址要二次確認、壞規則包不可派；agent 連受檢主機驗 SSH 指紋；Redis 改三個帳號各自最小權限。

2. 修正清單（17 張卡，一句一條）

卡號 修了什麼
CM-2428 AI 呼叫紀錄清明文的排程沒宣告系統身分，過去靜默什麼都沒清；改為宣告系統身分並加登記守衛
CM-2455 規則包抽取背景執行緒拿不到 app context，網址型規則包抽取一律失敗；套件 service 延遲殼記住建殼時的 app
CM-2447 租戶層 AI 設定拒收 base_url、讀取不回位址；AI 位址永遠原廠，租戶只能自填金鑰
CM-2426 代理程式註冊 token 加效期與使用次數上限；新報到進「待核准」，核准前雲端資料面也不呼叫它（管理頁新增「待核准的機器」區塊）
CM-2456 AI 閘道出口守門「阻擋」級真正攔下（之前 AI 回覆含私鑰會原樣顯示）
CM-2449 前門 nginx：安全標頭、HSTS、請求大小分級上限、免登入端點限速；即時連線限連線數／事件速率／Origin 白名單；CSP 以 Report-Only 上線，新增 CSP 違規回報與前端錯誤轉送兩支免登入端點；MAX_REQUEST_BODY_MB 預設 50→110 對齊前門
CM-2441 雙因子第二關 /otp-verify 改送第一關簽發的 mfa_token，不再收使用者編號
CM-2452 掃描派工：發動與改目標寫稽核、壞規則包不可選不可派、外部目標要二次確認、AI 名冊類查詢只送統計、Discord／Telegram 推播只說「有事請登入」
CM-2454 api-logs 空條件不再倒整表；公鑰表補正式鑰；雙因子失敗計數落 DB；Google Drive 權限範圍維持不變（決策者裁不收窄 drive.file）
CM-2451 通知逾時、webhook SSRF、Drive 覆寫網址只收 https、Excel 匯入過炸彈檢查、SSP docx 匯入先擋超長參數不洩 SQL、下載加 nosniff、新任務信跳脫
CM-2427 非專案成員拒絕一律 404、與資源不存在逐字相同；唯讀成員刪證據檔改擋下
CM-2453 Redis 拆 api／socketio／worker 三帳號最小權限（升級自動補帳號）；agent SSH 驗主機指紋（測試連線顯示指紋）；log 轉送預設加密、選明文出風險警示
CM-2457 Office 壓縮炸彈檢查搬到 jedi-common，iam 使用者／oscal-v2 框架／survey 問卷與答案四處 Excel 匯入讀檔前都過
CM-2458 jedi-common 共用錯誤處理不再把資料庫例外原文回前端，只回固定碼、原文進日誌
CM-2450 SMTP／儲存密鑰等整合憑證加密落庫；設定遮罩改白名單；log 不印 config、所有 logging 出口掛遮罩
CM-2448 控制面不再宣稱 mTLS：agent 打前門不帶客戶端憑證、nginx 殘留設定清掉，文件明寫「控制面只靠通行證」
CM-2401 全公司共用設定（SMTP／LDAP／登入政策）讀取比照寫入卡總部層級；非總部開頁顯示說明不報錯

3. 升級須知（必讀）

  1. AI_PROVIDER_ENCRYPTION_KEY 現在也保護 SMTP／儲存／LDAP 等五種整合憑證。 升級後 BE 第一次啟動會自動把既有明文憑證加密（冪等，重啟不重複）。這把鑰遺失或被換掉，這些設定全部讀成「未設定」，要到設定頁重填——不會 500、也不會拿密文去登入。請確認 .env 內此值有備份，切勿重新產生。
  2. ai-gateway 出口守門規則檔升級不覆蓋既有檔。 客戶若自訂過規則，新版預設規則（阻擋級真正攔下）要手動合併。
  3. jedi-common 共用錯誤碼從數字改 COMMON_* 字串。 資料庫類錯誤原本回 error_code: 400／409，現在回 COMMON_400003／COMMON_409001／COMMON_408001／COMMON_500001，訊息只剩固定文字。對接本系統 API 的外部程式若依數字碼分支要跟著改。
  4. Google Drive 權限範圍維持不變。 資安測試曾建議收窄成 drive.file，決策者裁不改，既有 Drive 連線不必重新授權。
  5. Redis 改三個服務帳號。 升級時 installer 自動補三組密碼進 .env，既有的不動；補完到換版之間舊帳號照常可用。
  6. 代理程式報到待核准。 只影響新報到的機器；既有 active 的代理程式升級後維持 active。

4. Breaking Changes

  • 資料庫類錯誤的 error_code 改字串（見升級須知 3）。
  • /otp-verify 第二關改收 mfa_token，舊版前端送使用者編號會被拒（FE 同版已對齊）。
  • 非專案成員打專案資源從 403 改 404。
  • 租戶層寫 AI_PROVIDER_CONFIG 帶 api_key 以外的欄位回 400 SYSTEM_CONFIG_400007。

5. DB Migration

主線

無新增（scripts/sql/manifest.tsv 未變），出貨基線不必重產，99-stamp.sql 只隨版號重生 marker。

套件自帶（build 時由 flatten_pkg_migrations.sh 攤平進包，migrate 輪套；不蓋章）

檔案 內容
jedi_iam/003-mfa-attempts.sql 新表 public.mfa_attempts：雙因子失敗計數落 DB
jedi_remote_agent/006-remote-agent-pending-approval.sql remote_agents 加報到來源等欄位，支援「待核准」狀態
jedi_api_log/008-log-forwarding-default-tls.sql log 轉送欄位預設改 TCP＋TLS；只改「出廠後沒人存過」那一列，客戶存過的設定不動

整合憑證加密不是 SQL migration（資料庫沒有加密鑰），由 BE 啟動時的冪等補跑處理。

6. 相依套件版本

套件 v1.23.1 本版
jedi-common 1.3.3 1.3.4
jedi-iam 1.4.6 1.4.8
jedi-system-core 1.2.1 1.2.2
jedi-log 1.3.1 1.3.2
jedi-compliance-audit 1.3.3 1.3.4
jedi-survey 1.2.2 1.2.3
jedi-detection 1.2.3 1.2.4
jedi-remote-agent 1.2.4 1.3.0
jedi-evidence-classification 1.6.0 1.6.2
jedi-file-upload 1.3.3 1.3.4
jedi-notification 1.2.2 1.2.3
jedi-ai-dashboard 1.6.0 1.6.1
jedi-ai-gateway 0.1.0 0.1.1
jedi-oscal-v2 2.5.0 2.5.1

其餘不變。檢測 Agent 側另有 CM-2448／2453 的改動（不帶客戶端憑證、SSH 驗主機指紋），agent 版本與部署見 agent repo。

7. 部署順序

  1. 188 build 機：/opt/guidant-ai-be git pull 到本版 commit；poetry update 指定上表 14 支套件名（flatten_pkg_migrations.sh 從 venv 讀套件 SQL，venv 舊就不會有三支新 SQL）；build_all.sh --all → build_bundle.sh --skip-prod-key-check。
  2. 開包驗：BE 版本烙印 1.24.0；scripts/sql/packages/manifest.tsv 含上述三支且 .sql 檔在。
  3. 190 e2e：GitLab pipeline deploy-e2e（scripts/build/deploy_e2e.sh 1.24.0，走 install.sh --upgrade）。驗三支套件 SQL 已登記 schema_migrations、登入正常、既有 agent 心跳仍 active。
  4. 跑資安測案全套；STG（188）／POC（189）等決策者放行，升級有人用的機器先停 api 再 --upgrade。

8. 同期其他改動

  • FR-127：GitLab 一鍵發版到 e2e（deploy-e2e job）、SBOM 與 osv 弱點總表。
  • 路由 × 守門軸清單腳本 collect_route_guards.py（CM-2421）。

9. 已知限制與 follow-up（不擋本版）

  • CSP 仍是 Report-Only，收一段時間違規回報後再改強制。
  • 81 條 SR 中 04.12（問卷共編）待裁改測，仍屬人工驗證。
  • PROD 簽章鑰仍缺。

10. 相關文件

  • Notion：CM-2384（母卡）、上表 17 張修正卡、發版 CM-2459／2460
  • docs/features/FR-126-2610-security-taxonomy-expansion/
  • 資安報告站 docs/security-report/