Diagnostiquer les incidents de l’API OpenAI sans exposer vos identifiants

Il est plus facile de diagnostiquer un incident de l’API OpenAI lorsque les journaux conservent des éléments opérationnels sans enregistrer d’identifiants ni de données client inutiles. Commencez par examiner le signal d’échec — par exemple, un statut autre qu’un succès, un délai d’attente dépassé ou une exception de l’application — puis associez-le à un identifiant de requête et au déploiement concerné. Ne laissez pas la clé API accessible dans un environnement où du code non fiable ou généré par un agent pourrait la lire.

Créer un relevé de diagnostic sécurisé

Pour chaque tentative d’appel à l’API, ne consignez que les éléments nécessaires pour répondre à quatre questions : quand l’événement s’est-il produit, quelle charge de travail a envoyé la requête, de quel type d’échec s’agit-il et peut-on établir une corrélation avec les données du fournisseur ?

Un relevé utile peut contenir un horodatage, un identifiant d’opération opaque propre à votre système, la catégorie du point de terminaison, le statut HTTP, la durée écoulée, le nombre de nouvelles tentatives et, si le fournisseur en renvoie un, un identifiant de requête. Consignez la classe de l’exception ou une catégorie d’erreur assainie au lieu de vider l’objet d’exception : certains SDK incluent des détails de requête dans le texte de l’exception. Dans les journaux courants, excluez les prompts, les réponses, les en-têtes d’autorisation ainsi que les corps bruts des requêtes et réponses, sauf si une procédure validée établit un besoin précis et prévoit les protections adaptées.

Le code Python suivant est un exemple illustratif, et non une intégration testée. La fonction de récupération du secret et le traitement de la réponse dépendent de votre application et de votre SDK. Cet exemple évite délibérément de journaliser le corps de la requête ou l’identifiant secret.

import logging
import time
import uuid

logger = logging.getLogger(__name__)


def send_request(client, payload):
    operation_id = str(uuid.uuid4())
    started = time.monotonic()

    try:
        result = client.responses.create(**payload)
        logger.info(
            "openai_request_succeeded",
            extra={
                "operation_id": operation_id,
                "elapsed_ms": round((time.monotonic() - started) * 1000),
                "provider_request_id": getattr(result, "_request_id", None),
            },
        )
        return result
    except Exception as exc:
        # Do not log str(exc), request headers, or payload here.
        logger.error(
            "openai_request_failed",
            extra={
                "operation_id": operation_id,
                "elapsed_ms": round((time.monotonic() - started) * 1000),
                "exception_type": type(exc).__name__,
            },
        )
        raise

Avant d’adopter cet exemple, vérifiez comment votre client expose les identifiants de requête et si ses messages d’exception peuvent contenir des données sensibles. Appliquez les mêmes règles de masquage aux traces, au signalement des erreurs, aux journaux de proxy et aux dossiers d’assistance : assainir uniquement les journaux de l’application ne suffit pas.

Exploiter les signaux d’échec pour cerner la cause

Un code d’état ou une exception fournit un indice, pas un diagnostic complet. Une hausse des échecs d’authentification après un déploiement peut signaler un identifiant manquant ou invalide, ou un identifiant transmis de manière incorrecte. Une augmentation des réponses de limitation de débit peut indiquer un changement du volume ou du niveau de concurrence des requêtes. Les délais d’attente dépassés peuvent être liés à l’accès réseau, à la latence en amont ou à un délai d’attente client trop court. Si le fournisseur répond avec succès, mais que la requête utilisateur échoue ensuite, le problème peut plutôt venir de l’analyse effectuée par l’application ou d’un service en aval.

Comparez le taux d’échec et la latence avant et après un déploiement, puis ventilez les résultats par charge de travail ou par environnement. Évitez de regrouper les données par valeur secrète ou de journaliser cette valeur pour « vérifier » si deux systèmes partagent la même clé. Pour vérifier quel identifiant un service utilise, consultez sa référence dans le gestionnaire de secrets et sa configuration de déploiement par une voie autorisée.

Séparer et limiter les identifiants

Les recommandations de sécurité d’OpenAI concernant les environnements sandbox préconisent l’isolation du calcul, la séparation des environnements pour les charges de travail qui ne doivent pas partager de données et l’utilisation d’un projet OpenAI dédié à chaque application ou charge de travail. Elles distinguent également une clé API d’application d’une clé d’environnement d’exécuteur : cette dernière sert à connecter des environnements et n’autorise pas d’autres actions API. Les recommandations énumèrent des permissions spécifiques pour les sessions de l’Agents API, l’inférence et la gestion de vault ; n’accordez que les permissions nécessaires à la charge de travail. Consultez les recommandations de sécurité d’OpenAI pour les environnements sandbox.

Conservez la clé de l’application hors des environnements où le code généré par un agent pourrait la lire. N’intégrez pas les clés au code source, aux images de conteneur ni aux journaux. Pour les identifiants de tiers, les recommandations conseillent de conserver les secrets à l’extérieur de l’environnement et de les fournir par un mécanisme de confiance, par exemple un proxy ou une solution reposant sur un vault, le cas échéant. Un secret injecté dans un environnement reste accessible au code qui s’y exécute : l’injection seule ne le rend donc pas inaccessible.

Définir une procédure de rotation des identifiants

Consignez et répétez les étapes suivantes avant qu’un incident ne survienne :

1. Préparer : Identifiez le propriétaire de l’identifiant, ses permissions, les services qui l’utilisent et son emplacement dans le gestionnaire de secrets. Déterminez qui peut créer, déployer et révoquer les identifiants.
2. Remplacer : Créez un nouvel identifiant doté des seules permissions nécessaires. Enregistrez-le dans le gestionnaire de secrets approuvé, et non dans un ticket, une conversation ou un dépôt de code source.
3. Déployer : Mettez à jour la charge de travail concernée selon le processus normal de mise en production. Si une période de chevauchement est autorisée, ne conservez l’ancien identifiant que pendant le délai minimal nécessaire à la vérification.
4. Vérifier : Effectuez une requête à faible risque, puis vérifiez sa réussite, le taux d’échec et les journaux. Assurez-vous qu’aucun service ne dépend encore de l’ancien identifiant.
5. Révoquer et examiner : Révoquez l’ancien identifiant. Si vous soupçonnez une exposition, donnez la priorité à sa révocation et examinez les charges de travail et les journaux concernés au lieu d’attendre la prochaine date de rotation prévue.

Si des requêtes échouent juste après la rotation, vérifiez que le service a bien reçu le nouveau secret, qu’il a redémarré ou actualisé son accès au secret et que le nouvel identifiant dispose des permissions appropriées. Ne réglez pas une erreur de permission en accordant un accès étendu sans avoir confirmé l’action nécessaire.

Liste de contrôle pour un incident

• L’échec touche-t-il une seule charge de travail, un seul environnement ou une seule version ?
• Le statut, la latence, le nombre de nouvelles tentatives et les identifiants de requête non sensibles révèlent-ils une tendance ?
• Les journaux ne contiennent-ils ni en-têtes d’autorisation, ni clés, ni contenu inutile de prompts ou de réponses ?
• L’identifiant est-il stocké et transmis par une voie approuvée de gestion des secrets ?
• Pouvez-vous remplacer et révoquer l’identifiant sans modifier des services non concernés ?

L’objectif n’est pas de tout journaliser. Il s’agit de conserver suffisamment d’éléments non sensibles pour distinguer les problèmes d’identifiants, de trafic, de réseau et d’application, et de pouvoir remplacer rapidement un identifiant si son exposition est suspectée.