위협 모델, 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가 보안 요구 사항을 항목별로 정리하고 정책에 명시할 수 있도록 세부 정보를 제공하는 프롬프트 예시입니다.

### Authentication and Authorization

- Every non-public endpoint must authenticate the caller.
- Sessions and tokens must be validated for issuer, audience, signature, expiry, revocation, and intended authentication context.
- Authentication failures must fail closed.
- Sensitive operations must require recent or stronger authentication where appropriate.
- Password-reset, account-recovery, MFA, and identity-linking flows must not permit account takeover.
- Authentication secrets and tokens must never appear in logs, URLs, analytics, or error responses.
- Authorization must occur before every read, mutation, transaction, export, or administrative action.
- Possession of a valid account or resource identifier never proves authorization.
- Customer, account, and tenant isolation must hold across list, detail, search, bulk, export, and indirect-reference endpoints.
- Server-side authorization must not rely on client-supplied roles, ownership fields, prices, balances, or approval state.
- Administrative and service-to-service permissions must use least privilege.
- Failures allowing cross-customer access are reportable even when only one endpoint is affected.

### Transaction and ledger integrity

- Transactions must be authorized against the authenticated customer and eligible source account.
- Amounts, currencies, destinations, fees, limits, and approval state must be validated server-side.
- Transaction requests must be protected against replay, duplication, race conditions, and idempotency-key confusion.
- Balance checks and ledger updates must be atomic.
- Posted ledger entries must be immutable or corrected through auditable compensating entries.
- High-risk transactions must enforce applicable limits, step-up authentication, approval, or fraud controls.
- No failure path may produce an ambiguous transaction state without reconciliation.

### Data protection

- Sensitive data must be encrypted in transit and at rest using approved controls.
- Secret material must come from an approved secret-management system rather than source code or ordinary configuration files.
- Logs, traces, metrics, support tooling, and security artifacts must exclude credentials and minimize personal and financial data.
- Data exports and backups must receive equivalent authorization and protection to primary data.
- Error responses must not expose internals, sensitive records, credentials, or authorization details.
- Retention and deletion behavior must follow the system’s approved data-governance requirements.

### Input and output handling

- Treat headers, paths, query parameters, bodies, uploaded files, webhook payloads, third-party responses, and stored customer content as untrusted.
- Apply schema, type, range, length, and format validation before security-sensitive use.
- Database access must use parameterized queries.
- Outbound requests must restrict destinations, protocols, redirects, DNS behavior, and response sizes.
- Parsers, uploads, decompression, and serialization must be bounded against resource exhaustion.
- Customer-controlled content must be safely encoded for its output context.
  \