Rôles respectifs des modèles de menaces, d’AGENTS.md, de SECURITY.md et des bases de connaissances

Le fichier AGENTS.md rassemble les consignes de développement qui fixent des attentes communes à toute l’équipe. Le fichier SECURITY.md précise comment votre organisation souhaite que Codex évalue la sécurité du système et présente ses conclusions. Le modèle de menaces décrit les risques auxquels le système est exposé. Ces documents se recoupent, mais le modèle de menaces ne constitue généralement qu’un volet de la politique de sécurité.

Par exemple, un modèle de menaces détaille les actifs à protéger, les points d’entrée, les données d’entrée qu’un attaquant peut contrôler, les frontières de confiance, les hypothèses sur lesquelles repose l’authentification, les opérations privilégiées et les composants à risque.

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

Le fichier security.md précise comment votre organisation souhaite que Codex évalue ces risques et présente ses conclusions.

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

Enfin, une base de connaissances fournit des documents de référence pour certaines analyses. Elle peut contenir des documents d’architecture, des politiques, d’autres modèles de menaces ou des informations sur les conditions d’exploitation que l’outil d’analyse de la CLI doit prendre en compte. Voici un exemple de document d’architecture rédigé en Markdown pour cet outil.

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

Pour que l’analyse prenne en compte ce document, indiquez le chemin de la base de connaissances dans la commande suivante :

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

Vous pouvez organiser l’ensemble de ces fichiers comme suit :

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

Créez un premier modèle de menaces

L’ajout d’un modèle de menaces au dépôt est essentiel pour guider Codex dans ses revues de sécurité. Pour créer une première version, lancez le skill de modélisation des menaces dans Codex, puis enregistrez le modèle dans un commit.

Pour lancer le skill de modélisation des menaces dans Codex, saisissez $threat-model. Une fois le modèle créé, ajoutez-le au répertoire /docs/security du dépôt dans un commit, puis indiquez le lien vers le modèle dans les paramètres Codex Cloud du dépôt sélectionné. Si vous ne spécifiez aucun modèle de menaces, Codex en générera un nouveau à chaque revue de sécurité.

Créez un premier fichier SECURITY.md

Utilisez le skill $define-security-policy pour générer une première version de votre politique de sécurité dans le dépôt.

Une politique de sécurité solide doit décrire en détail le fonctionnement de l’application. Voici un exemple de prompt qui donne à Codex les précisions nécessaires pour énumérer et définir les exigences de sécurité :

### Authentification et autorisation

- Chaque point de terminaison non public doit authentifier l’appelant.
- Pour chaque session et chaque token, le service doit vérifier l’émetteur, le destinataire prévu, la signature, la date d’expiration, l’absence de révocation et le contexte d’authentification prévu.
- En cas d’échec de l’authentification, le service doit systématiquement refuser l’accès.
- Les opérations sensibles doivent exiger, selon le cas, une authentification récente ou renforcée.
- Les procédures de réinitialisation de mot de passe, de récupération de compte, d’authentification multifacteur (MFA) et d’association d’identités doivent empêcher toute prise de contrôle d’un compte par un tiers.
- Les secrets d’authentification et les tokens ne doivent jamais figurer dans les journaux, les URL, les données d’analyse ou les réponses d’erreur.
- Le service doit vérifier les autorisations avant chaque lecture, modification, transaction, exportation ou action d’administration.
- La possession d’un identifiant valide de compte ou de ressource ne constitue jamais une preuve d’autorisation.
- Tous les points de terminaison doivent garantir l’isolation entre clients, entre comptes et entre locataires, qu’ils servent à lister des ressources, à en consulter le détail, à effectuer des recherches, à traiter des ressources par lots, à les exporter ou à y accéder par référence indirecte.
- Pour autoriser une opération, le serveur ne doit pas se fier aux rôles, aux champs indiquant le propriétaire, aux prix, aux soldes ni aux états d’approbation fournis par le client.
- Les permissions d’administration et les permissions entre services doivent respecter le principe du moindre privilège.
- Toute faille permettant à un client d’accéder aux ressources d’un autre client doit être signalée, même si elle ne touche qu’un seul point de terminaison.

### Intégrité des transactions et du grand livre

- Pour chaque transaction, le service doit vérifier que le compte source est admissible et que le client authentifié est autorisé à y effectuer la transaction.
- Le serveur doit valider les montants, les devises, les destinations, les frais, les limites et l’état d’approbation.
- Le service doit protéger les demandes de transaction contre le rejeu, les doublons, les situations de concurrence et les confusions entre clés d’idempotence.
- La vérification du solde et la mise à jour du grand livre doivent former une opération atomique.
- Les écritures comptabilisées doivent rester immuables. Toute correction doit passer par des écritures de compensation auditables.
- Pour les transactions à haut risque, le service doit appliquer les mesures requises selon le cas : limites, authentification renforcée, approbation ou contrôles antifraude.
- Si une défaillance laisse l’état d’une transaction incertain, le service doit effectuer un rapprochement pour en déterminer l’état réel.

### Protection des données

- Le service doit chiffrer les données sensibles en transit et au repos à l’aide de mécanismes approuvés.
- Les secrets doivent provenir d’un système de gestion des secrets approuvé. Le code source et les fichiers de configuration ordinaires ne doivent pas les contenir.
- Les journaux, les traces, les métriques, les outils d’assistance et les artefacts de sécurité doivent exclure les informations d’authentification et limiter au strict nécessaire les données personnelles et financières.
- Les exportations et les sauvegardes doivent bénéficier de contrôles d’autorisation et de mesures de protection équivalents à ceux des données d’origine.
- Les réponses d’erreur ne doivent révéler aucun détail sur le fonctionnement interne du système, aucun enregistrement sensible, aucune information d’authentification ni aucun détail sur les autorisations.
- La conservation et la suppression des données doivent respecter les exigences de gouvernance des données approuvées pour le système.

### Traitement des entrées et des sorties

- Considérez comme non fiables les en-têtes, les chemins, les paramètres de requête, les corps de requête, les fichiers téléversés, les charges utiles des webhooks, les réponses de tiers et les contenus stockés provenant des clients.
- Avant toute utilisation ayant une incidence sur la sécurité, vérifiez que les données respectent le schéma, les types, les plages de valeurs, les longueurs et les formats attendus.
- Tout accès à la base de données doit passer par des requêtes paramétrées.
- Pour les requêtes sortantes, le service doit limiter les destinations, les protocoles, les redirections, les modes de résolution DNS et la taille des réponses.
- Imposez des limites de ressources aux analyseurs syntaxiques, aux téléversements, à la décompression et à la sérialisation afin d’éviter tout épuisement des ressources.
- Le service doit encoder tout contenu contrôlé par un client selon les règles de sécurité propres au contexte de sortie.
  \