Remarques concernant la sécurité

Portée : ce document traite des considérations de sécurité liées au kit SDK Python de mémoire d'agent Oracle AI. Elle s'applique aux applications qui utilisent les fonctionnalités de mémoire active du kit SDK ou la couche de stockage uniquement.

Pourquoi cela compte : la mémoire de l'agent Oracle AI peut rendre persistants les enregistrements de contenu et de mémoire de thread dans Oracle Database et, lorsque les fonctionnalités soutenues par le LLM sont activées, envoyer du contenu aux adresses de modèle configurées pour l'agrégation, l'extraction de mémoire ou les incorporations. Le déploiement sécurisé dépend donc d'un traitement minutieux des données d'application, de la portée de l'extraction, de l'accès à la base de données, des adresses de modèle externe et des stratégies de conservation.

Remarques concernant le traitement de la mémoire sauvegardée par LLM

La mémoire de l'agent Oracle AI prend en charge des fonctionnalités de mémoire active telles que la synthèse des threads et l'extraction automatique de la mémoire. Lorsque ces fonctionnalités sont activées, le kit SDK peut envoyer des messages récents, des récapitulatifs de threads, des mémoires extraites ou du texte de recherche au LLM configuré ou à l'adresse d'intégration.

Important : envoyez uniquement le contenu à la mémoire de l'agent Oracle AI approprié à l'adresse de modèle configurée et aux stratégies de déploiement. Si la mémoire active est activée pour les données qui semblent inclure des clés secrètes, des informations d'identification ou des données confidentielles inutiles, réduisez ou occultez ce contenu avant que les messages n'entrent dans le pipeline de mémoire. Traiter les mémoires extraites, les résumés, les cartes de contexte et tout autre texte dérivé du modèle comme une sortie non fiable qui doit être examinée et gérée en toute sécurité par l'application d'intégration.

Avertissement : le texte dérivé d'un modèle peut devenir un état de mémoire persistant. Lorsque les fonctionnalités d'extraction automatique, d'agrégation ou de carte contextuelle sont activées, le kit SDK peut insérer un enregistrement récapitulatif, extrait ou extrait dans des invites ultérieures, telles que l'extraction de mémoire, l'agrégation, la carte contextuelle ou les invites d'agent, avant que l'application puisse vérifier cette valeur intermédiaire spécifique. Traitez cela comme un flux de données LLM non sécurisé normal : vérifiez et validez les sorties consommées par votre application, et ne laissez pas le contenu dérivé de la mémoire autoriser des actions privilégiées ou contourner la stratégie.

Suivez les recommandations suivantes lors de l'utilisation des fonctionnalités de mémoire active :

Valider et réduire les données d'application : vérifiez les messages, métadonnées et ID que votre application envoie au kit SDK. Évitez de transmettre plus de données que le workflow de mémoire n'en a besoin.
Utiliser des adresses de modèle sécurisé : configurez le LLM et intégrez des adresses qui répondent à vos exigences en matière de sécurité du transport, de résidence des données, de conservation et de surveillance opérationnelle.
Traiter la mémoire générée en tant que données d'application et sortie non sécurisée : les mémoires extraites, les résumés et les cartes de contexte sont des sorties dérivées. Examinez comment votre application les utilise, en particulier avant qu'elles n'influencent les actions privilégiées, les appels d'outils externes ou les décisions visibles par le client.
Choisir l'extraction asynchrone uniquement lorsque les écritures dérivées retardées sont acceptables : en mode arrière-plan, les écritures de message brut peuvent se terminer avant que les mémoires dérivées, les récapitulatifs ou l'état d'exécution associé ne soient écrits. Si un workflow nécessite une révision ou une limite de validation plus stricte avant que l'état dérivé du modèle ne devienne durable, utilisez l'extraction en ligne ou désactivez l'extraction automatique pour ce workflow.
Compte pour l'injection d'invite persistante : le texte fourni par l'appelant, extrait ou dérivé du modèle stocké en mémoire peut être réexécuté dans des invites d'agrégation, d'extraction, de carte contextuelle ou d'agent ultérieures. Les délimiteurs d'invite, les instructions d'échappement et d'extraction peuvent aider à structurer l'entrée du modèle, mais ils ne constituent pas une limite de sécurité. Passez en revue les mémoires extraites, les résumés, les cartes de contexte et tout autre texte intermédiaire persistant ou lié à une invite avant de compter sur elles. Si votre workflow nécessite une révision avant que le texte dérivé du modèle puisse influencer l'extraction future ou la construction du contexte, désactivez l'extraction automatique et utilisez des écritures de mémoire explicites ou une autre porte de révision contrôlée par l'application.
Sanitize ou texte dérivé d'échappement pour sa destination : si des mémoires, des résumés, des cartes de contexte ou tout autre texte dérivé d'un modèle sont extraits dans HTML, Markdown, des modèles, des journaux ou d'autres surfaces de sortie, appliquez une évacuation ou un nettoyage adapté au contexte. Faites attention avant de réutiliser du texte dérivé dans des invites en aval, des entrées d'outil, des commandes ou d'autres contextes de type interprète.
Choisir le bon mode de fonctionnement : si votre application doit être vérifiée avant que le texte dérivé du modèle puisse influencer l'extraction ultérieure ou la construction du contexte, envisagez d'utiliser des écritures de mémoire explicites, des intégrations en magasin uniquement ou memory_extraction_config=MemoryExtractionConfig(extract_memories=False) pour les workflows qui ne doivent pas effectuer d'extraction automatique.

Remarques concernant la persistance et la minimisation des données

La mémoire de l'agent Oracle AI est conçue pour rendre persistants les messages, les mémoires, les métadonnées et les incorporations dans Oracle Database lorsque l'emplacement de stockage sauvegardé par la base de données est utilisé. Cela permet une extraction durable et une mémoire intersession, mais cela signifie également que l'application doit planifier les données à conserver.

Les conseils suivants vous aident à aligner les déploiements sur les pratiques de gestion des données sécurisées :

Pour une utilisation en mode "store-only", ne conserver que ce qui est nécessaire : concevez votre application de sorte que seul le contenu utile et adapté à l'entreprise soit écrit dans la banque de mémoire.
Lorsque les fonctions de mémoire active sont activées, planifier les enregistrements dérivés : outre le contenu fourni par l'appelant, tel que les messages et les métadonnées, un workflow peut également rendre persistantes les mémoires extraites, les récapitulatifs ou les incorporations.
Traiter les chemins de mémoire pouvant faire l'objet d'une écriture comme sécurisés : les informations d'identification de base de données et les chemins de code back-end qui peuvent écrire des messages, des récapitulatifs, des mémoires, des métadonnées, des intégrations ou l'état d'exécution des threads peuvent avoir une incidence sur les invites futures et les résultats d'extraction. Les fonctionnalités de mémoire active conservent intentionnellement l'état dérivé du modèle. Si cela n'est pas approprié pour un workflow, désactivez l'extraction automatique ou utilisez une intégration de stockage uniquement/écriture manuelle avec des contrôles d'application plus étroits.
Choisir la portée de suppression appropriée pour le travail de conservation : delete_message() enlève uniquement l'enregistrement de message brut. Les mémoires dérivées ou d'autres artefacts de portée thread en aval créés à partir de ce message peuvent rester consultables car les mémoires extraites ne persistent pas actuellement par provenance de message. Lorsque vous avez besoin d'un nettoyage de portée thread qui supprime également les mémoires associées et les données d'extraction gérées, utilisez OracleAgentMemory.delete_thread().
Planification autour de la limite de suppression et d'arrêt pour le travail en arrière-plan : delete_thread(), delete_user(cascade=True) et delete_agent(cascade=True) n'attendent que l'extraction en arrière-plan acceptée antérieurement déjà connue de ce client au démarrage de l'attente. Il ne s'agit pas d'une barrière globale de simultanéité entre les autres descripteurs, composants ou processus, et les écritures simultanées pendant la suppression ne sont pas prises en charge. Lorsqu'une limite de conservation ou d'arrêt nécessite une extraction en arrière-plan déjà acceptée à partir du client en cours pour terminer en premier, appelez wait_for_memory_extraction() avant l'arrêt du processus ou les opérations d'administration associées.
Définir les stratégies de conservation et de suppression à l'avance : si votre application propose des engagements de suppression ou de conservation, assurez-vous qu'ils couvrent les messages bruts, les mémoires extraites, les métadonnées et les autres enregistrements associés créés par le workflow. Choisissez les valeurs ttl_days par enregistrement et le schéma memory_retention_config en fonction du type d'informations attendu dans chaque enregistrement, de la raison pour laquelle l'application doit la conserver et des engagements de conservation applicables. Utilisez l'expiration automatique lorsque les enregistrements doivent être purgés par ancienneté et vérifiez que le travail de purge Oracle géré est présent dans les déploiements soutenus par la base de données, en particulier lorsque l'utilisateur de configuration de schéma ne dispose pas des privilèges de travail de planificateur.
Planification du chargement de la base de données des travaux de purge : le travail de purge Oracle géré s'exécute selon une programmation et supprime les lignes expirées des tables gérées par le kit SDK par lots plutôt qu'en tant que suppression volumineuse. Surveillez l'exécution, la génération des informations de journalisation/annulation, l'historique des exécutions ignorées et le volume de lignes dans des environnements avec des taux d'écriture élevés ou des lots d'expiration importants, et ajustez les paramètres de conservation ou les plans de déploiement opérationnel si l'activité de purge peut chevaucher les charges globales de base de données sensibles à la latence. Le travail géré définit une valeur schedule_limit d'un jour afin que les exécutions retardées trop longues puissent être ignorées au lieu de commencer arbitrairement en retard.
Evitez de compter sur la mémoire comme source d'informations fiables : les mémoires stockées sont destinées à améliorer le contexte et l'extraction. Les applications devraient continuer à s'appuyer sur des systèmes faisant autorité pour prendre des décisions importantes.

Remarques concernant la portée de l'extraction et le contrôle d'accès

La mémoire de l'agent Oracle AI utilise les valeurs user_id, agent_id et thread_id fournies par l'appelant pour extraire la portée. Il s'agit d'un modèle de filtrage puissant, mais il ne doit pas être le seul contrôle sur lequel repose votre application lorsque vous décidez de la façon dont le contenu extrait est utilisé ou affiché.

Par défaut, l'extraction de niveau thread utilise une correspondance exacte pour user_id et agent_id, ainsi qu'une correspondance plus large pour thread_id afin que les résultats pertinents puissent couvrir les threads passés pour la même paire utilisateur-agent. Les appels de niveau supérieur OracleAgentMemory.search() et search_async() nécessitent également une portée explicite de l'utilisateur et une correspondance exacte de l'utilisateur. Ils rejettent la portée utilisateur omise et exact_user_match=False afin que l'API client publique ne recherche pas accidentellement sur plusieurs utilisateurs. La transmission de user_id=None est autorisée uniquement avec une correspondance utilisateur exacte et cible uniquement les enregistrements non ciblés.

Utilisez les exercices suivants lors de la conception de l'extraction :

Mettre en correspondance les règles d'application avec la portée de mémoire : assurez-vous que les portées transmises à l'application au kit SDK correspondent aux règles de locataire, d'utilisateur et de partage de données.
Transmettre une portée utilisateur explicite à chaque recherche de client : dériver le paramètre user_id du contexte de demande authentifiée plutôt que de la demande JSON ou d'une autre entrée contrôlée par l'appelant, et le fournir sur chaque appel de niveau supérieur OracleAgentMemory.search() ou search_async(). Utilisez user_id=None uniquement pour les workflows intentionnellement limités aux enregistrements non ciblés.
Préférer la portée la plus étroite qui satisfait le cas d'emploi : utilisez des filtres de correspondance et de resserrement exacts pour les workflows qui gèrent des données plus sensibles.
Vérifier l'extraction inter-thread intentionnellement : l'extraction plus large peut améliorer la continuité entre les sessions, mais les applications ne doivent l'activer que lorsque ce comportement est approprié.
Traiter les résultats de la recherche en fonction du contenu extrait, et non des décisions finales : les mémoires renvoyées peuvent être pertinentes, mais l'application reste responsable de décider si et comment elles doivent être affichées ou traitées.
Gérer le texte extrait en toute sécurité au niveau de la limite d'intégration : les enregistrements extraits peuvent inclure du texte fourni par l'appelant ou dérivé du modèle. Si des mémoires récupérées ou d'autres textes renvoyés sont affichés en HTML, Markdown, des modèles, des journaux ou d'autres surfaces de sortie, appliquez une évacuation ou une désinfection appropriée au contexte avant de l'afficher, de le transformer ou de le transmettre aux systèmes en aval.

Remarques concernant l'intégration des applications et la confiance des appelants

La mémoire de l'agent Oracle AI est destinée à être appelée par l'application d'intégration ou par un autre code back-end sécurisé, et non directement par les utilisateurs finaux. Il ne s'agit pas d'une limite de sécurité orientée utilisateur final, et il n'effectue pas d'authentification ou d'autorisation de l'utilisateur final par lui-même. Le package fait confiance à l'appelant pour fournir la portée d'extraction user_id, agent_id, thread_id et la portée d'extraction correcte pour chaque opération.

Important : l'application d'intégration est responsable de l'authentification de l'utilisateur final, de l'autorisation de l'accès et de la dérivation du paramètre user_id et de la portée appropriés avant d'appeler les API de mémoire d'agent Oracle AI. Une valeur user_id fournie par l'appelant est une valeur de portée et non une preuve d'identité.

Utilisez les exercices suivants lors de l'intégration du kit SDK dans une application agénétique :

Traiter user_id en tant qu'entrée d'application sensible à la sécurité : si l'application d'intégration dérive user_id de la demande JSON ou d'une autre entrée contrôlée par l'appelant au lieu du contexte authentifié, cela peut autoriser l'accès à la mémoire inter-utilisateur. Dérivez user_id de votre contexte d'application authentifié au lieu de laisser les utilisateurs finaux choisir des valeurs arbitraires.
Appliquer l'autorisation de l'application avant chaque appel de mémoire : l'application d'intégration doit décider quelles valeurs user_id, agent_id, thread_id et portée de recherche sont valides pour la demande en cours et conserver les lectures et écritures dans les limites du locataire et de l'utilisateur prévus.
Ne pas exposer les API de mémoire brute aux utilisateurs finals : les API de package telles que add_memory ou les aides à la recherche doivent être encapsulées dans une logique d'application qui valide l'appelant, applique la stratégie et contrôle les données pouvant être écrites ou renvoyées.
Conserver le repérage et l'énumération des ID utilisateur privilégiés : si le package ajoute des assistants pour répertorier ou énumérer les valeurs user_id, traitez-les uniquement en tant que fonctionnalités d'administration et ne les exposez jamais aux utilisateurs finaux via l'application d'intégration.
Examinez attentivement les remplacements de portée : tout workflow qui élargit la portée des threads, désactive la mise en correspondance exacte ou abandonne les API de stockage de niveau inférieur doit être limité aux composants sécurisés et vérifié pour les effets inter-utilisateurs ou colocatifs.

Remarques concernant la journalisation et les diagnostics

La mémoire de l'agent Oracle AI utilise la journalisation Python standard et ne configure pas de gestionnaires de journaux d'application ni de niveaux de journalisation pour l'application d'intégration. Les applications peuvent activer le journaliseur oracleagentmemory et acheminer les journaux du kit SDK via leur configuration de journalisation existante.

Utilisez les exercices suivants lors de l'utilisation des journaux SDK :

Garder les déploiements de production à un niveau autre que DEBUG : la journalisation DEBUG est destinée uniquement au développement contrôlé ou aux diagnostics de prise en charge et ne convient pas à la collecte de journaux de production.
Limiter l'accès aux journaux de diagnostic : stockez les journaux dans des puits protégés avec des stratégies appropriées de contrôle d'accès, de conservation et de partage. Consultez les lots d'informations pour le support avant d'envoyer des journaux en dehors de l'environnement d'exploitation.
Evitez d'ajouter un contexte sensible dans les wrappers de journalisation d'application : n'enrichissez pas les enregistrements de journal SDK avec des invites, du contenu de mémoire, des informations d'identification, des métadonnées brutes, des valeurs de ligne de base de données ou des identificateurs contrôlés par l'appelant.
Traiter le texte du journal en tant que sortie de diagnostic et non en tant qu'interface d'audit : les messages de journal peuvent aider à dépanner le comportement du kit SDK, mais les applications doivent utiliser leurs propres événements d'audit explicites pour les workflows de sécurité et de conformité.

Remarques concernant l'accès à la base de données, la gestion des schémas et les clés secrètes

La mémoire de l'agent Oracle AI utilise une connexion ou un pool Oracle Database fourni par l'appelant. Le package ne crée ni ne gère les informations d'identification et de connexion à la base de données. Il ne crée, ne négocie ni ne met à niveau le cryptage réseau de base de données pour le compte de l'appelant.

Important : le code de production doit transmettre une connexion ou un pool Oracle Database avec TLS dans la mémoire de l'agent Oracle AI. Le kit SDK utilise la connexion ou le pool fourni par l'appelant tel quel et ne met pas à niveau un DSN en texte brut. N'utilisez pas de connexions de base de données en texte clair sur des réseaux non sécurisés, partagés ou externes. Lorsque vous utilisez python-oracledb, suivez la section officielle Cryptage sécurisé du trafic réseau vers Oracle Database et configurez TLS ou un autre transport crypté approuvé dans le cadre de la création de connexions ou de pools.

Important : n'intégrez jamais de clés d'API, de mots de passe ou d'autres clés secrètes directement dans le code d'application, la configuration réinsérée ou les artefacts exportés. Utilisez toujours des mécanismes d'injection sécurisés et respectez le principe du moindre privilège pour l'accès aux informations d'identification.

Les pratiques de déploiement suivantes sont recommandées :

Utiliser les utilisateurs de base de données avec uniquement les privilèges requis : octroyez uniquement ce qui est nécessaire pour le modèle de déploiement et la stratégie de schéma sélectionnés.
Utilisez un utilisateur de base de données distinct pour les workflows de suppression lorsque cela est possible : si votre application doit enlever des enregistrements, préférez une connexion ou un pool dédié pour ces chemins et accordez DELETE aux tables de mémoire d'agent Oracle AI gérées uniquement à cet utilisateur de base de données. Conservez la connexion d'exécution principale limitée aux privilèges de non-suppression requis pour ses opérations normales afin que les suppressions accidentelles ou indésirables aient un rayon d'impact plus étroit. Si un appelant appelle delete() via une connexion qui ne dispose pas du droit d'accès DELETE, Oracle Database rejette l'instruction.
Créer des pools et des connexions de base de données cryptées : le code de production doit transmettre une connexion ou un pool Oracle Database compatible TLS au kit SDK. La mémoire de l'agent Oracle AI utilise la connexion ou le pool fourni par l'appelant exactement comme indiqué. Par conséquent, pour python-oracledb, préférez les connexions compatibles TLS telles que protocol="tcps" ou un DSN TCPS équivalent, configurez le portefeuille ou le matériel d'autorité de certification requis et maintenez la validation du certificat de serveur activée.
Conservez la stratégie de schéma par défaut, sauf si vous avez explicitement besoin de modifications LDD : SchemaPolicy.REQUIRE_EXISTING est la valeur par défaut et évite de créer, de modifier ou de supprimer des objets de schéma au démarrage normal de l'application.
Limiter les modes de configuration destructifs : SchemaPolicy.RECREATE est destiné aux workflows de configuration, de test ou d'administration et ne doit pas être utilisé dans des chemins de production normaux.
S'appuyer sur des chemins SQL gérés par package et non sur un assemblage SQL dynamique dans le code d'application : dans les chemins de base de données gérés, les valeurs d'enregistrement et les filtres de recherche sont envoyés avec des variables attachées et les noms d'objet géré sont dérivés de préfixes validés.
Protéger les informations d'identification de connexion et de fournisseur : stockez la base de données, le LLM et l'intégration des informations d'identification dans un gestionnaire de clés secrètes tel qu'OCI Vault, et effectuez une rotation régulière.
Préférer le protocole TLS validé en mode léger et épais : la documentation python-oracledb officielle indique que les modes léger et épais prennent en charge le protocole TLS, et que le mode épais peut également utiliser le cryptage réseau natif Oracle, où il s'agit de votre norme approuvée.
Utiliser le transport sécurisé vers la base de données : la sécurité réseau de la base de données, la configuration TLS et la méthode d'authentification sont déterminées par la connexion fournie par l'appelant et doivent respecter les normes de votre organisation.

Remarques concernant la communication réseau et les adresses externes

La mémoire de l'agent Oracle AI peut communiquer avec des services externes lorsque le déploiement configure un LLM distant ou des fournisseurs d'intégration. Le kit SDK transmet les invites et les paramètres de demande via le chemin du client configuré, mais l'application et le déploiement environnants restent responsables de la sécurisation de ces connexions.

Nous recommandons de suivre les points suivants :

Utilisez HTTPS pour les adresses de modèle et préférez les chemins réseau privés ou restreints, le cas échéant.
Surveillez le trafic sortant et l'utilisation du fournisseur pour les destinations inattendues, le volume de demandes inhabituel ou la consommation de jetons anormale.
Choisissez les fournisseurs qui répondent à vos besoins en matière de conformité et de résidence avant d'activer les fonctionnalités de mémoire active sur les workflows réglementés ou sensibles.

Considérations relatives aux vecteurs d'épuisement des ressources

Les workflows de mémoire peuvent augmenter l'utilisation de la base de données, l'intégration du trafic et la consommation de jetons LLM au fil du temps. Cela est vrai à la fois pour une utilisation excessive malveillante et pour des erreurs de mise en œuvre innocentes telles que des messages surdimensionnés ou des modèles de récupération trop larges.

Utilisez les commandes suivantes dans le cadre de votre durcissement de production :

Définir des limites d'invite et de message pratiques : configurez des valeurs telles que max_message_token_length et memory_extraction_token_limit pour qu'elles correspondent aux limites de charge globale et de fournisseur. max_message_token_length limite la copie d'invite utilisée par les workflows d'extraction ; les messages stockés restent inchangés.
Tailles d'extraction liées : utilisez des valeurs max_results et des filtres de type d'enregistrement raisonnables pour les recherches d'application.
Appliquer les limites d'infrastructure en dehors du kit SDK : utilisez les quotas de base de données, les limites de connexion, les contrôles réseau, les délais d'expiration d'adresse et la limitation de débit dans le déploiement environnant.
Surveiller la croissance au fil du temps : suivez le volume de messages stocké, la croissance durable de la mémoire, l'utilisation des fournisseurs et la latence des requêtes afin que les modifications de conservation ou de réglage puissent être apportées avant qu'elles n'affectent la fiabilité.