Diferenças entre modelos de ameaças, AGENTS.md, SECURITY.md e bases de conhecimento

O arquivo AGENTS.md reúne instruções de engenharia que definem o que se espera de toda a equipe. O SECURITY.md orienta o Codex sobre como sua organização quer que ele avalie a segurança do sistema e relate os resultados. O modelo de ameaças descreve o cenário de segurança do sistema. Esses documentos têm pontos em comum, mas o modelo de ameaças costuma fazer parte de uma política mais ampla.

Por exemplo, um modelo de ameaças pode detalhar os ativos, os pontos de entrada, as entradas controladas por invasores, as fronteiras de confiança, as premissas de autenticação, as operações privilegiadas e os componentes que apresentam riscos.

# 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.

O arquivo security.md orienta o Codex sobre como sua organização quer que ele avalie esse cenário e relate os resultados.

# 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.

Por fim, uma base de conhecimento fornece documentos de apoio para varreduras específicas. Ela pode incluir documentos de arquitetura, políticas, outros modelos de ameaças ou informações operacionais que a ferramenta de varredura da CLI deve considerar. Veja um exemplo de documento de arquitetura em Markdown preparado para essa ferramenta.

# 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.

Use o comando a seguir para fornecer a base de conhecimento à varredura.

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

Você pode organizar esses arquivos da seguinte forma.

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

Crie um modelo de ameaças inicial

Fazer commit de um modelo de ameaças é uma etapa fundamental para orientar as revisões de segurança do Codex. Para criar a versão inicial, execute a habilidade de modelagem de ameaças no Codex e faça commit do modelo gerado.

Para executar a habilidade de modelagem de ameaças no Codex, digite $threat-model. Depois de criar o modelo, faça commit dele no diretório /docs/security do repositório. Em seguida, adicione um link para o modelo nas configurações do repositório selecionado no Codex Cloud. Se você não especificar um modelo de ameaças, o Codex gerará um novo modelo a cada revisão de segurança.

Crie um SECURITY.md inicial

Você pode usar a habilidade $define-security-policy para gerar uma política de segurança inicial no repositório.

Uma boa política de segurança deve descrever em detalhes como o aplicativo funciona. O prompt de exemplo a seguir fornece esses detalhes para que o Codex possa identificar e definir os requisitos da política.

### 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.
  \