Diferencias entre los modelos de amenazas, AGENTS.md, SECURITY.md y las bases de conocimiento

AGENTS.md reúne las instrucciones de ingeniería que establecen criterios comunes para el equipo. SECURITY.md le indica a Codex cómo quiere tu organización que evalúe la seguridad del sistema y comunique sus hallazgos. Un modelo de amenazas describe las condiciones de seguridad del sistema. Estos documentos tienen puntos en común, pero el modelo de amenazas suele ser solo una parte de la política de seguridad.

Por ejemplo, un modelo de amenazas incluiría detalles sobre los activos, los puntos de entrada, los datos de entrada que controla un atacante, los límites de confianza, los supuestos de autenticación, las operaciones que requieren privilegios y los componentes que presentan riesgos.

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

El archivo security.md le indica a Codex cómo quiere tu organización que evalúe esas condiciones y comunique sus hallazgos.

# 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 último, una base de conocimiento aporta documentos de referencia para análisis específicos. Puede incluir documentos de arquitectura, políticas, otros modelos de amenazas o información operativa que el escáner de la CLI deba tener en cuenta. Este es un ejemplo de un documento de arquitectura en Markdown preparado para el escáner de la CLI.

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

Puedes incluirlo en el análisis con el siguiente comando:

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

Puedes organizar los archivos de esta manera:

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

Crear un modelo de amenazas inicial

Incorporar un modelo de amenazas al repositorio mediante un commit es fundamental para orientar las revisiones de seguridad de Codex. Para empezar, puedes invocar la habilidad de modelado de amenazas en Codex y hacer un commit con el modelo que genere.

Para invocar la habilidad de modelado de amenazas en Codex, escribe $threat-model. Una vez creado el modelo, agrégalo al repositorio en /docs/security mediante un commit. Luego, incluye un enlace al modelo en la configuración de Codex Cloud del repositorio seleccionado. Si no especificas un modelo de amenazas, Codex generará uno nuevo en cada revisión de seguridad.

Crear un archivo SECURITY.md inicial

Puedes usar la habilidad $define-security-policy para generar una política de seguridad inicial en el repositorio.

Una política de seguridad sólida debe describir en detalle cómo funciona la aplicación. Este es un ejemplo de un prompt que le da a Codex los detalles necesarios para enumerar y establecer los requisitos de seguridad:

### Autenticación y autorización

- Todo punto de acceso que no sea público debe autenticar a quien realiza la solicitud.
- Para cada sesión y cada token, se deben validar el emisor, la audiencia, la firma, el vencimiento, el estado de revocación y el contexto de autenticación previsto.
- Si falla la autenticación, el sistema debe denegar el acceso.
- Las operaciones sensibles deben exigir una autenticación reciente o más robusta cuando corresponda.
- Los flujos de restablecimiento de contraseñas, recuperación de cuentas, MFA y vinculación de identidades deben impedir que terceros tomen el control de una cuenta.
- Los secretos de autenticación y los tokens nunca deben aparecer en registros, URL, datos de analítica ni respuestas de error.
- El sistema debe verificar la autorización antes de cada lectura, modificación, transacción, exportación o acción administrativa.
- Tener un identificador válido de una cuenta o un recurso nunca demuestra que se tenga autorización.
- Todos los puntos de acceso de listado, detalle, búsqueda, operaciones masivas, exportación y referencias indirectas deben mantener el aislamiento entre clientes, entre cuentas y entre inquilinos.
- Al decidir si autoriza una operación, el servidor no debe basarse en roles, campos de titularidad, precios, saldos ni estados de aprobación proporcionados por el cliente.
- Los permisos administrativos y los permisos entre servicios deben ajustarse al principio de mínimo privilegio.
- Se deben reportar las fallas que permitan a un cliente acceder a recursos de otro, aunque solo afecten a un punto de acceso.

### Integridad de las transacciones y del libro mayor

- Para autorizar cada transacción, el sistema debe comprobar que el cliente autenticado tenga permiso para realizarla y que la cuenta de origen reúna los requisitos.
- El servidor debe validar los montos, las monedas, los destinos, las comisiones, los límites y el estado de aprobación.
- Las solicitudes de transacción deben contar con protección contra ataques de repetición, duplicados, condiciones de carrera y confusiones entre claves de idempotencia.
- La comprobación del saldo y la actualización del libro mayor deben realizarse como una operación atómica.
- Los asientos registrados en el libro mayor deben ser inmutables o corregirse mediante asientos compensatorios que se puedan auditar.
- En las transacciones de alto riesgo, el sistema debe aplicar los límites, la autenticación reforzada, los requisitos de aprobación o los controles antifraude que correspondan.
- Si una falla deja una transacción en un estado ambiguo, el sistema debe resolverlo mediante la conciliación.

### Protección de datos

- Los datos sensibles deben cifrarse tanto en tránsito como en reposo mediante controles aprobados.
- Los secretos deben obtenerse de un sistema de gestión de secretos aprobado. No deben extraerse del código fuente ni de archivos de configuración ordinarios.
- Los registros, las trazas, las métricas, las herramientas de soporte y los artefactos de seguridad deben excluir las credenciales y limitar al mínimo los datos personales y financieros que contienen.
- Las exportaciones de datos y las copias de seguridad deben estar sujetas a medidas de autorización y protección equivalentes a las de los datos primarios.
- Las respuestas de error no deben revelar detalles internos del sistema, registros sensibles, credenciales ni detalles de autorización.
- La retención y la eliminación de datos deben cumplir los requisitos de gobernanza de datos aprobados para el sistema.

### Manejo de entradas y salidas

- Trata como datos no confiables los encabezados, las rutas, los parámetros de consulta, los cuerpos de las solicitudes, los archivos cargados, las cargas útiles de los webhooks, las respuestas de terceros y el contenido almacenado de los clientes.
- Valida el esquema, el tipo, el rango, la longitud y el formato de los datos antes de usarlos en operaciones sensibles para la seguridad.
- El acceso a la base de datos debe realizarse mediante consultas parametrizadas.
- En las solicitudes salientes, el sistema debe restringir los destinos, los protocolos, las redirecciones, el comportamiento del DNS y el tamaño de las respuestas.
- Se deben imponer límites al uso de recursos durante el análisis sintáctico, la carga de archivos, la descompresión y la serialización para evitar que esos recursos se agoten.
- El contenido que controle el cliente debe codificarse de forma segura para el contexto de salida en el que se utilice.
  \