指南OneMux

診斷 OpenAI API 事故,同時避免憑證外洩

實用指南:如何在保護 API 金鑰、限制權限並規劃憑證輪替的同時,取得有效訊號以診斷 OpenAI API 故障。

AI

摘要 · TL;DR

OpenAI API 請求失敗時,應保留足以找出故障原因的證據,同時避免記錄機密或敏感內容。依用途區分憑證、限制憑證的使用範圍,並在事故發生前演練輪替程序。

重點

  • 記錄請求結果與安全識別資訊,不要記錄 API 金鑰、授權標頭或完整提示詞與回應。
  • 不同職責使用不同憑證,並只授予工作負載所需的權限。
  • 將狀態、錯誤類別、耗時與請求識別碼視為診斷訊號,而不是暴露請求內容的理由。
  • 可行的輪替計畫應涵蓋建立替代憑證、部署、驗證,以及撤銷舊憑證。
文章目錄 (5)

若 OpenAI API 事故的日誌能保留營運證據,同時避免收集憑證或不必要的客戶資料,就更容易診斷問題。先從故障訊號著手,例如非成功狀態、逾時或應用程式例外,接著將其與請求識別碼及受影響的部署關聯起來。請勿讓 API 金鑰存放在不受信任或由代理程式產生的程式碼可讀取的環境中。

建立安全的診斷紀錄

每次 API 呼叫只記錄回答以下四個問題所需的資訊:何時發生、哪個工作負載送出請求、發生哪一類故障,以及能否與供應商端的證據進行關聯?

實用的紀錄可以包含時間戳記、自行產生的不透明作業 ID、端點類別、HTTP 狀態、耗時、重試次數,以及(若有傳回)供應商請求 ID。請記錄例外類別或經清理的錯誤類別,而非直接輸出例外物件:部分程式庫會在例外文字中包含請求詳細資訊。除非經過審核的流程確認有特定需求,且具備適當保護措施,否則不要將提示詞、回應、授權標頭或原始請求與回應本文寫入一般日誌。

以下 Python 程式碼是示意模式,並非經測試的整合範例。祕密資訊的擷取函式與回應處理方式,取決於你的應用程式和 SDK。此範例刻意不記錄請求本文或憑證。

import logging
import time
import uuid

logger = logging.getLogger(__name__)


def send_request(client, payload):
    operation_id = str(uuid.uuid4())
    started = time.monotonic()

    try:
        result = client.responses.create(**payload)
        logger.info(
            "openai_request_succeeded",
            extra={
                "operation_id": operation_id,
                "elapsed_ms": round((time.monotonic() - started) * 1000),
                "provider_request_id": getattr(result, "_request_id", None),
            },
        )
        return result
    except Exception as exc:
        # Do not log str(exc), request headers, or payload here.
        logger.error(
            "openai_request_failed",
            extra={
                "operation_id": operation_id,
                "elapsed_ms": round((time.monotonic() - started) * 1000),
                "exception_type": type(exc).__name__,
            },
        )
        raise

採用此模式前,請確認用戶端如何提供請求 ID,以及例外訊息是否可能包含敏感資料。追蹤、錯誤回報、代理伺服器日誌與支援套件也應採用相同的遮蔽規則;只清理應用程式日誌並不足夠。

利用故障訊號縮小原因範圍

狀態碼或例外只是線索,並非完整診斷。部署後若驗證失敗突然增加,可能表示憑證遺漏、無效或提供方式有誤。速率限制回應增加,可能代表請求量或並行程度有所變化。逾時可能與網路存取、上游延遲或用戶端逾時設定過短有關。若供應商已成功回應,但使用者請求仍失敗,問題也可能出在應用程式端的剖析或下游流程。

比較部署前後的故障率與延遲,並依工作負載或環境區分結果。不要依祕密值分組,也不要為了「確認」兩個系統是否共用金鑰而將金鑰寫入日誌。若要確認服務使用哪個憑證,請透過授權管道檢查其祕密管理工具參照與部署設定。

區分並限制憑證

OpenAI 的沙箱安全指引建議使用隔離的運算環境;對於不得共用資料的工作負載,應使用不同環境;並為應用程式或工作負載設定專用的 OpenAI 專案。該指引也區分應用程式 API 金鑰與執行器環境金鑰:後者用於連接環境,並不授權其他 API 操作。指引列出 Agents API 工作階段、推論與保險庫管理的特定權限;請只指派工作負載所需的權限。請參閱 OpenAI 的沙箱安全指引。

將應用程式金鑰存放在代理程式產生的程式碼無法讀取的環境之外。不要將金鑰嵌入原始碼、容器映像檔或日誌中。對於第三方憑證,指引建議將祕密資訊存放在環境之外,並透過受信任的機制提供,例如在適用情況下使用代理伺服器或以保險庫為基礎的方式。注入環境的祕密資訊仍可供在該環境中執行的程式碼存取,因此僅靠注入並不能確保其無法被讀取。

訂定憑證輪替程序

請在事故發生前寫下並演練以下步驟:

  1. **準備:**確認憑證的負責人、權限、使用該憑證的服務,以及祕密管理工具中的存放位置。確認哪些人有權建立、部署和撤銷憑證。
  2. **替換:**建立僅具備必要權限的替代憑證。將其存放在核准的祕密管理工具中,不要放進工單、聊天內容或原始碼儲存庫。
  3. **部署:**透過正常的發布流程更新相關工作負載。若允許新舊憑證並存,舊憑證僅保留至完成驗證所需的最短時間。
  4. **驗證:**送出低風險請求,並檢查成功情況、故障率與日誌。確認沒有服務仍依賴舊憑證。
  5. **撤銷並檢視:**撤銷舊憑證。若懷疑憑證已外洩,應優先撤銷,並調查受影響的工作負載與日誌,而不是等到例行輪替日期。

若輪替後請求立即失敗,請檢查服務是否確實取得新祕密資訊、是否已重新啟動或重新整理祕密資訊存取,以及替代憑證是否具備正確權限。未確認所需操作前,不要為了解決權限錯誤而授予廣泛存取權限。

精簡事故檢查清單

  • 故障是否僅影響單一工作負載、環境或版本?
  • 狀態、延遲、重試次數與安全的請求識別資訊是否顯示出某種模式?
  • 日誌是否未包含授權標頭、金鑰,以及不必要的提示詞或回應內容?
  • 憑證是否透過核准的祕密管理管道儲存及提供?
  • 是否能在不變更無關服務的情況下替換並撤銷憑證?

目標不是記錄所有內容,而是保留足夠的安全證據,以區分憑證、流量、網路與應用程式故障;並在懷疑憑證外洩時迅速輪替。

常見問題

OpenAI API 請求失敗時,我應該記錄哪些資訊?

記錄時間戳記、自行產生的不透明作業 ID、端點類別、HTTP 狀態或經清理的錯誤類別、耗時、重試次數,以及(若有)供應商請求 ID。預設情況下,不要記錄 API 金鑰、授權標頭或完整請求與回應本文。

代理程式產生的程式碼應該能存取 API 金鑰嗎?

避免將應用程式 API 金鑰暴露給不需要使用它的程式碼。OpenAI 的沙箱安全指引建議將應用程式金鑰存放在環境之外,並說明代理程式產生的程式碼可以存取其環境中的檔案與憑證。

何時應輪替或撤銷 OpenAI API 金鑰?

依照明確訂定的營運時程輪替憑證;若懷疑憑證外洩,應立即撤銷。完整的程序涵蓋建立替代憑證、部署、驗證,以及撤銷舊憑證。

為什麼憑證輪替後請求可能會失敗?

工作負載可能仍在使用快取或舊的祕密資訊、尚未重新整理設定,或新憑證缺少必要權限。請確認已部署的祕密資訊參照與所需權限,但不要將憑證本身寫入日誌。

相關文章