脅威モデル、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 で $threat-model と入力すると、脅威モデル用のスキルを呼び出せます。脅威モデルを作成したら、リポジトリの /docs/security 配下にコミットします。次に、Codex Cloud で対象リポジトリの設定を開き、脅威モデルへのリンクを指定します。脅威モデルを指定しない場合、Codex はセキュリティレビューのたびに脅威モデルを生成し直します。

SECURITY.md の準備

$define-security-policy スキルを使うと、リポジトリ内にセキュリティポリシーの初稿を生成できます。

実効性のあるセキュリティポリシーには、アプリケーションの動作を詳しく記述する必要があります。以下は、具体的な動作要件を Codex に伝え、ポリシーの各項目として明文化するためのプロンプトの例です。

### 認証と認可

- すべての非公開エンドポイントで、呼び出し元を認証してください。
- セッションとトークンについて、発行者、対象者、署名、有効期限、失効の有無を検証し、想定する認証コンテキストに合致することを確認してください。
- 認証に失敗した場合は、必ずアクセスを拒否してください。
- 機密性の高い操作では、必要に応じて、直近の認証またはより強力な認証を必須にしてください。
- パスワードのリセット、アカウントの復旧、MFA、ID 連携の各手順で、アカウントの乗っ取りを防いでください。
- 認証用の秘密情報やトークンは、ログ、URL、分析データ、エラーレスポンスに一切含めないでください。
- 読み取り、データの変更、取引、エクスポート、管理操作のいずれも、実行前に毎回、呼び出し元にその操作を行う権限があることを確認してください。
- 有効なアカウントを持っていることや、リソースの識別子を知っていることだけで、操作の権限があると判断しないでください。
- 一覧取得、詳細取得、検索、一括処理、エクスポート、間接参照のすべてのエンドポイントで、顧客間、アカウント間、テナント間の分離を維持してください。
- サーバー側の認可では、クライアントから渡されたロール、所有者を示すフィールド、価格、残高、承認状態に依存しないでください。
- 管理操作やサービス間通信に付与する権限は、必要最小限にしてください。
- 他の顧客のデータにアクセスできてしまう不備は、影響が 1 つのエンドポイントに限られる場合も報告対象にしてください。

### 取引と元帳の整合性

- 取引ごとに、出金元口座がその取引に利用可能であることと、認証済みの顧客にその口座で取引を行う権限があることを確認してください。
- 金額、通貨、送金先、手数料、取引限度額、承認状態をサーバー側で検証してください。
- 取引リクエストのリプレイ、重複処理、競合状態、冪等性キーの取り違えを防いでください。
- 残高の確認と元帳の更新は、ひとまとまりの不可分な処理として実行してください。
- 記帳済みの仕訳は変更できないようにし、訂正が必要な場合は、監査で追跡できる訂正仕訳を追加してください。
- リスクの高い取引では、限度額、ステップアップ認証、承認、不正防止策のうち、その取引に適用される要件を必ず満たしてください。
- どの段階で処理が失敗しても、取引状態が不明確になった場合は、必ず照合して状態を確定してください。

### データ保護

- 機密データは、転送時も保存時も、承認済みの手段で暗号化してください。
- 秘密情報は、承認済みのシークレット管理システムから取得してください。ソースコードや通常の設定ファイルを取得元にしないでください。
- ログ、トレース、メトリクス、サポート用ツール、セキュリティ関連の成果物には認証情報を含めず、個人情報と金融データも必要最小限にとどめてください。
- エクスポートしたデータとバックアップにも、元のデータと同等の認可要件と保護措置を適用してください。
- エラーレスポンスに、システムの内部情報、機密性の高いレコード、認証情報、認可の詳細を含めないでください。
- データの保持と削除は、そのシステムで承認されているデータガバナンス要件に従ってください。

### 入出力の処理

- ヘッダー、パス、クエリパラメーター、リクエスト本文、アップロードされたファイル、Webhook のペイロード、外部サービスからの応答、保存済みの顧客コンテンツは、すべて信頼できない入力として扱ってください。
- セキュリティに関わる処理で入力を使用する前に、スキーマ、型、値の範囲、長さ、形式を検証してください。
- データベースへのアクセスには、パラメーター化クエリを使用してください。
- 外部にリクエストを送信する際は、宛先、プロトコル、リダイレクト、DNS 名前解決の動作、レスポンスサイズを制限してください。
- リソースの枯渇を防ぐため、解析、アップロード、圧縮データの展開、シリアライズで使用できるリソースに上限を設けてください。
- 顧客が内容を制御できるコンテンツは、出力先のコンテキストに合わせて安全にエンコードしてください。
  \