如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
Codex

Codex 應用案例

設定安全性上下文

明確訂出要保護的項目、要檢查的規則,以及要回報的內容。

難度 Intermediate
任務時間跨度 30m

瞭解如何準備並設定 Codex 執行安全性審查與掃描所需的上下文。

最適合的對象

  • 正在為程式碼庫的安全性審查與掃描做準備的開發人員。
  • 負責記錄系統風險、安全性需求與回報準則的應用程式安全團隊。
  • 需要向安全性智慧體提供系統架構、工程與維運知識的團隊。

目錄

    ← 所有應用案例

    設定安全性上下文

    明確訂出要保護的項目、要檢查的規則,以及要回報的內容。

    瞭解如何準備並設定 Codex 執行安全性審查與掃描所需的上下文。

    Intermediate
    30m
    依步驟設定

    最適合的對象

    • 正在為程式碼庫的安全性審查與掃描做準備的開發人員。
    • 負責記錄系統風險、安全性需求與回報準則的應用程式安全團隊。
    • 需要向安全性智慧體提供系統架構、工程與維運知識的團隊。

    技能與外掛程式

    技能 使用理由
    Codex Security:threat Model 建立威脅模型,涵蓋應用程式的資產、進入點、安全邊界與假設。
    Codex Security:define Security Policy 產生初始安全性政策,並將其加入程式碼庫。

    威脅模型、AGENTS.md、SECURITY.md 與知識庫有何不同?

    AGENTS.md 記錄團隊共用的工程指引,讓成員遵循一致的準則。SECURITY.md 說明組織希望 Codex 如何評估系統的安全狀況,以及如何回報評估結果。威脅模型則描述系統實際面臨的安全威脅。這些文件的內容有所重疊,但威脅模型通常只是整體安全政策的一部分。

    舉例來說,威脅模型會詳述系統資產、進入點、攻擊者可控制的輸入、信任邊界、身分驗證所依據的假設、需要特殊權限的操作,以及具有風險的元件。

    # Threat Model
    
    The public API accepts untrusted JSON and file uploads.
    Requests cross from the internet-facing API into internal billing and
    identity services. Attackers are unauthenticated users or compromised
    tenant accounts. Protect tenant data, billing mutations, and service credentials.

    security.md 說明組織希望 Codex 如何評估上述安全狀況,以及如何回報評估結果。

    # Security Policy
    
    ## Security Invariants
    
    - Every billing mutation must be authorized for the active tenant.
    - Uploaded content must be parsed within explicit size and resource limits.
    - Service credentials must never be returned to clients.
    
    ## Reportable Findings
    
    Report realistic violations of tenant isolation, authentication bypass,
    unsafe parsing, secret exposure, or unauthorized billing mutations.
    
    ## Severity Context
    
    Cross-tenant access is Critical.
    Single-tenant unauthorized mutation is High.
    
    ## Out of Scope
    
    Development-only tools that cannot be included in production builds.

    知識庫則為特定掃描提供參考文件,例如架構文件、安全政策、其他威脅模型,或 CLI 掃描器應納入考量的系統運作資訊。以下是預先為 CLI 掃描器準備的 Markdown 架構文件範例。

    # Payment Service Security Context
    
    ## Purpose
    
    The payment service creates charges, issues refunds, and stores references
    to payment-provider customers. It does not store full card numbers or CVVs.
    
    ## Deployment and Exposure
    
    - `POST /api/payments` is internet-facing through the API gateway.
    - `POST /internal/refunds` is reachable only from the support service.
    - Background workers consume messages from the `payment-events` queue.
    - The service runs with access to the payment-provider API and billing database.
    
    ## Authentication and Authorization
    
    - Public endpoints use JWTs issued by the identity service.
    - The API gateway validates signatures, issuer, and expiration.
    - This service remains responsible for tenant authorization.
    - Internal requests use workload identity; network location alone is not trusted.
    - Refunds above £1,000 require a previously recorded approval.
    
    ## Trust Boundaries
    
    1. Internet client → API gateway
    2. API gateway → payment service
    3. Payment service → payment provider
    4. Payment service → billing database
    5. Message producers → `payment-events` consumer
    
    Inputs crossing any of these boundaries must be treated as untrusted unless
    the receiving component performs the documented validation.
    
    ## Sensitive Assets and Operations
    
    - Payment-provider API credentials
    - Customer-to-provider identifier mappings
    - Charge creation
    - Refund issuance
    - Webhook signature secrets
    - Tenant billing history
    
    ## Important Data Flows
    
    ### Creating a charge
    
    1. The API receives an authenticated request containing an order identifier.
    2. The service retrieves the order using both tenant ID and order ID.
    3. The service calculates the amount from server-side order data.
    4. The service creates the provider charge with an idempotency key.
    5. The resulting provider identifier is stored in the billing database.
    
    Client-supplied amounts must never be passed directly to the provider.
    
    ### Processing a webhook
    
    1. The raw request body is retained.
    2. The provider signature is verified over the raw bytes.
    3. The event timestamp must be within five minutes.
    4. Duplicate event IDs are ignored.
    5. State changes occur only after all validation succeeds.
    
    ## Relevant Code
    
    - `src/http/payments.ts`: public payment endpoints
    - `src/http/refunds.ts`: refund endpoints
    - `src/webhooks/provider.ts`: webhook validation
    - `src/workers/payment-events.ts`: asynchronous event processing
    - `src/auth/tenant.ts`: tenant authorization
    - `src/provider/client.ts`: provider API wrapper
    
    ## Security Assumptions
    
    - The identity service is trusted to authenticate users, but not to authorize
      access to payment records.
    - Queue publishers may be compromised; consumers must validate message content.
    - API-gateway authentication does not replace service-level tenant checks.
    - Provider webhook payloads are attacker-controlled until signature validation
      completes.
    
    ## Known Limitations
    
    - Legacy refunds created before 2025 do not have idempotency keys.
    - Webhook replay protection is local to one region.
    - The development payment-provider emulator does not validate signatures.

    執行掃描時,可以用以下指令指定包含這份文件的知識庫:

    codex-security scan . \
      --knowledge-base /path/to/security-policies

    這些文件可以按以下目錄結構整理:

    SECURITY.md
    docs/security/
    ├── threat-model.md
    ├── architecture.md
    ├── authentication.md
    └── deployment-boundaries.md

    建立初始威脅模型

    將威脅模型提交至程式碼庫,是讓 Codex 瞭解如何進行安全審查的重要步驟。你可以在 Codex 中呼叫威脅模型技能,建立初始威脅模型後再提交。

    Codex 程式碼庫專案中的威脅模型草稿範例。

    在 Codex 中輸入 $threat-model 即可呼叫威脅模型技能。建立威脅模型後,將它提交至程式碼庫的 /docs/security 目錄,再到所選程式碼庫的 Codex 雲端設定中加入威脅模型的連結。如果未指定威脅模型,Codex 每次進行安全審查時都會重新產生威脅模型。

    示範程式碼庫的安全審查設定範例。

    建立初始 SECURITY.md 檔案

    你可以使用 $define-security-policy 技能,在程式碼庫中產生初始安全政策。

    為 North Star Bank 範例制定安全政策的提示詞。

    完善的安全政策應詳細說明應用程式的運作方式。以下提示詞範例提供這些細節,讓 Codex 據此逐項列出並訂定安全要求:

    ### 身分驗證與授權
    
    - 每個非公開端點都必須驗證呼叫者的身分。
    - 驗證工作階段與 Token 時,必須核對簽發者、預期接收者及簽章,確認工作階段與 Token 均在有效期內、未遭撤銷,且符合預期的身分驗證情境。
    - 身分驗證一旦失敗,系統就必須拒絕存取。
    - 執行敏感操作前,應視情況要求使用者在近期內完成身分驗證,或採用強度更高的驗證方式。
    - 重設密碼、復原帳戶、MFA 及連結身分的流程,都不得讓攻擊者藉此接管帳戶。
    - 身分驗證用的機密資料與 Token 絕不可出現在日誌、網址、分析資料或錯誤回應中。
    - 每次讀取、變更、交易、匯出或執行管理操作前,都必須先確認呼叫者有權執行該操作。
    - 僅憑有效的帳戶或資源識別碼,不能認定呼叫者已獲授權。
    - 所有提供清單、明細、搜尋、批次處理、匯出或間接參照功能的端點,都必須維持客戶之間、帳戶之間及租戶之間的隔離。
    - 伺服器端執行授權檢查時,不得依賴用戶端提供的角色、所有權欄位、價格、餘額或核准狀態。
    - 管理操作與服務間呼叫都必須遵循最小權限原則。
    - 任何允許跨客戶存取的缺失,即使只影響一個端點,也屬於應回報的問題。
    
    ### 交易與帳本的完整性
    
    - 每筆交易都必須根據已驗證的客戶身分,確認該客戶有權使用符合交易條件的來源帳戶執行該筆交易。
    - 伺服器端必須驗證金額、幣別、目的地、費用、限額及核准狀態。
    - 處理交易請求時,必須防範重送攻擊、重複處理、競爭條件及等冪鍵混用。
    - 餘額檢查與帳本更新必須在同一個不可分割的操作中完成。
    - 已過帳的分錄必須保持不變。如需更正,必須另行登錄可供稽核的補償分錄。
    - 高風險交易必須依適用規定執行限額控管、加強身分驗證、取得核准或採取防詐措施。
    - 在任何失敗情況下,若交易狀態不明,都必須透過對帳確認最終狀態。
    
    ### 資料保護
    
    - 敏感資料在傳輸與儲存時,都必須採用經核准的措施加密。
    - 金鑰等機密資料必須從經核准的機密管理系統取得,不得取自原始碼或一般設定檔。
    - 日誌、追蹤紀錄、指標、支援工具及安全相關產出物都不得包含憑證,且所含的個人與財務資料必須減至最低。
    - 匯出資料與備份必須受到與主要資料同等的授權控管與保護。
    - 錯誤回應不得洩露系統內部細節、敏感紀錄、憑證或授權細節。
    - 資料保留與刪除作業必須符合系統已核准的資料治理要求。
    
    ### 輸入與輸出處理
    
    - 將請求標頭、路徑、查詢參數、請求主體、上傳的檔案、webhook 承載資料、第三方回應,以及已儲存的客戶內容,一律視為不受信任的輸入。
    - 將輸入用於涉及安全的操作前,必須先依結構描述進行驗證,並檢查型別、範圍、長度及格式。
    - 存取資料庫時必須使用參數化查詢。
    - 對外發送請求時,必須限制目的地、通訊協定、重新導向、DNS 解析行為及回應大小。
    - 必須限制剖析器、檔案上傳、解壓縮及序列化作業可使用的資源,以免耗盡系統資源。
    - 輸出客戶可控制的內容時,必須依實際輸出情境採用安全的編碼方式。
      \

    相關應用案例