Sicherheitsbetrachtungen

Geltungsbereich: Dieser Artikel behandelt Sicherheitsaspekte im Zusammenhang mit dem Agent-Speicher-Python-SDK. Sie gilt nur für Anwendungen, die entweder die Active-Memory-Features des SDK oder die Speicherebene verwenden.

Warum dies wichtig ist: Agent Memory kann Threadinhalte und Speicherdatensätze in Oracle AI Database persistieren und, wenn LLM-gestützte Features aktiviert sind, Inhalte an konfigurierte Modellendpunkte zur Zusammenfassung, Speicherextraktion oder Einbettung senden. Ein sicheres Deployment hängt daher von der sorgfältigen Verarbeitung von Anwendungsdaten, dem Abrufumfang, dem Datenbankzugriff, externen Modellendpunkten und Aufbewahrungs-Policys ab.

Überlegungen zur Verarbeitung von LLM-gesichertem Speicher

Agent Memory unterstützt Active-Memory-Features wie Threadzusammenfassung und automatische Speicherextraktion. Wenn diese Features aktiviert sind, kann das SDK aktuelle Nachrichten, Threadzusammenfassungen, abgerufene Speicher oder Suchtext an den konfigurierten LLM- oder Einbettungsendpunkt senden.

Hinweis: Senden Sie nur Inhalte an den Agent-Speicher, die für den konfigurierten Modellendpunkt und Ihre Deployment-Policys geeignet sind. Wenn active-memory für Daten aktiviert ist, die anscheinend Secrets, Zugangsdaten oder unnötige sensible Daten enthalten, minimieren oder verdecken Sie diesen Inhalt, bevor Nachrichten in die Speicherpipeline gelangen. Behandeln Sie extrahierte Speicher, Zusammenfassungen, Kontextkarten und anderen vom Modell abgeleiteten Text als nicht vertrauenswürdige Ausgabe, die von der integrierenden Anwendung sicher geprüft und verarbeitet werden muss.

Warnung: Der vom Modell abgeleitete Text kann zu einem persistenten Speicherstatus werden. Wenn automatische Extraktions-, Zusammenfassungs- oder Kontextkartenfunktionen aktiviert sind, kann eine Zusammenfassung, ein extrahierter Speicher oder ein abgerufener Datensatz vom SDK in spätere Prompts wie Speicherextraktion, Zusammenfassung, Kontextkarte oder Agent-Prompts eingefügt werden, bevor die Anwendung diesen bestimmten Zwischenwert prüfen kann. Behandeln Sie dies als normalen, nicht vertrauenswürdigen LLM-Datenfluss: Prüfen und validieren Sie die Ausgaben, die Ihre Anwendung verbraucht, und lassen Sie nicht zu, dass vom Speicher abgeleiteter Inhalt privilegierte Aktionen autorisiert oder die Policy umgeht.

Befolgen Sie diese Empfehlungen, wenn Sie Active-Memory-Features verwenden:

• Anwendungsdaten validieren und minimieren: Prüfen Sie, welche Nachrichten, Metadaten und IDs Ihre Anwendung an das SDK sendet. Vermeiden Sie die Weitergabe von mehr Daten, als der Speicher-Workflow benötigt.

• Trusted Model-Endpunkte verwenden: Konfigurieren Sie LLM und Einbettungsendpunkte, die Ihren Anforderungen an Transportsicherheit, Datenresidenz, Aufbewahrung und Betriebsüberwachung entsprechen.

• Generierten Speicher als Anwendungsdaten und nicht vertrauenswürdige Ausgabe behandeln: Extrahierte Speicher, Zusammenfassungen und Kontextkarten sind abgeleitete Ausgaben. Überprüfen Sie, wie Ihre Anwendung sie verwendet, insbesondere bevor sie privilegierte Aktionen, externe Toolanrufe oder kundensichtbare Entscheidungen beeinflussen.

• Account für persistente Prompt-Injection: Vom Aufrufer bereitgestellter, abgerufener oder vom Modell abgeleiteter Text, der im Speicher gespeichert ist, kann in spätere Zusammenfassungs-, Extraktions-, Kontextkarten- oder Agent-Prompts wiedergegeben werden. Prompt-Trennzeichen, Escape- und Extraktionsanweisungen können die Modelleingabe strukturieren, sind jedoch keine Sicherheitsgrenze. Überprüfen Sie extrahierte Speicher, Zusammenfassungen, Kontextkarten und anderen persistenten oder zeitaufforderungsgebundenen Zwischentext, bevor Sie sich darauf verlassen. Wenn Ihr Workflow eine Prüfung erfordert, bevor modellbasierter Text die zukünftige Extraktion oder Kontexterstellung beeinflussen kann, deaktivieren Sie die automatische Extraktion, und verwenden Sie explizite Speicherschreibvorgänge oder ein anderes anwendungsgesteuertes Prüfgate.

• Abgeleiteten Text für das Ziel "Sanitisieren" oder "Escape" verwenden: Wenn extrahierte Speicher, Zusammenfassungen, Kontextkarten oder anderer vom Modell abgeleiteter Text in HTML, Markdown, Vorlagen, Logs oder anderen Ausgabeoberflächen gerendert werden, wenden Sie kontextbezogene Escaping oder Desinfektion an. Verwenden Sie dieselbe Sorgfalt, bevor Sie abgeleiteten Text in nachgelagerten Prompts, Werkzeugeingaben, Befehlen oder anderen interpretatorähnlichen Kontexten wiederverwenden.

• Wählen Sie den richtigen Betriebsmodus aus: Wenn Ihre Anwendung geprüft werden muss, bevor vom Modell abgeleiteter Text die spätere Extraktion oder Kontexterstellung beeinflussen kann, sollten Sie explizite Speicherschreibvorgänge, Nur-Speicher-Integrationen oder extract_memories=False für Workflows verwenden, die keine automatische Extraktion ausführen sollten.

Überlegungen zu Persistenz und Datenminimierung

Agent Memory ist so konzipiert, dass Nachrichten, Speicher, Metadaten und Einbettungen in Oracle AI Database persistiert werden, wenn der DB-backed Store verwendet wird. Dies ermöglicht einen dauerhaften Abruf und Speicher für mehrere Sitzungen, bedeutet aber auch, dass die Anwendung planen sollte, welche Daten für die Aufbewahrung geeignet sind.

Die folgende Anleitung hilft dabei, Deployments auf sichere Datenbehandlungspraktiken abzustimmen:

• Persistieren Sie bei der Nur-Shop-Nutzung nur das, was benötigt wird: Entwerfen Sie Ihre Anwendung so, dass nur nützliche, geschäftsgerechte Inhalte in den Arbeitsspeicher geschrieben werden.

• Wenn Active-Memory-Features aktiviert sind, abgeleitete Datensätze planen: Neben vom Aufrufer bereitgestellten Inhalten wie Nachrichten und Metadaten kann ein Workflow auch extrahierte Speicher, Zusammenfassungen oder Einbettungen persistieren.

• Schreibfähige Speicherpfade als vertrauenswürdig behandeln: Datenbankzugangsdaten und Backend-Codepfade, die Nachrichten, Zusammenfassungen, Speicher, Metadaten, Einbettungen oder Thread-Laufzeitstatus schreiben können, können sich auf zukünftige Eingabeaufforderungen und Abrufergebnisse auswirken. Active-Memory-Features persistieren absichtlich den vom Modell abgeleiteten Status. Wenn dies nicht für einen Workflow geeignet ist, deaktivieren Sie die automatische Extraktion, oder verwenden Sie eine Store-Only-/Manual-Write-Integration mit engeren Anwendungssteuerelementen.

• Wählen Sie den richtigen Löschbereich für Aufbewahrungsarbeiten aus: delete_message() entfernt nur den Raw-Nachrichtendatensatz. Abgeleitete Speicher oder andere nachgelagerte Thread-bezogene Artefakte, die aus dieser Nachricht erstellt wurden, können weiterhin durchsucht werden, da extrahierte Speicher derzeit nicht pro Nachrichtenherkunft beibehalten werden. Wenn Sie eine Thread-bezogene Bereinigung benötigen, die auch zugehörige Speicher und verwaltete Vektor-/Chunk-Daten entfernt, verwenden Sie OracleAgentMemory.delete_thread().

• Aufbewahrungs- und Lösch-Policys im Voraus definieren: Wenn Ihre Anwendung Lösch- oder Aufbewahrungszusagen anbietet, stellen Sie sicher, dass sie Raw-Nachrichten, extrahierte Speicher, Metadaten und andere zugehörige Datensätze abdecken, die vom Workflow erstellt wurden.

• Verhindern Sie, dass Sie sich auf Speicher als Quelle der Wahrheit verlassen: Gespeicherte Speicher sollen den Kontext und den Abruf verbessern. Die Anwendungen sollten weiterhin auf verbindliche Systeme für wichtige Entscheidungen zurückgreifen.

Überlegungen zum Abrufumfang und zur Zugriffskontrolle

Der Agent-Speicher verwendet die vom Aufrufer bereitgestellten Werte user_id, agent_id und thread_id, um den Geltungsbereich für den Abruf festzulegen. Dies ist ein leistungsstarkes Filtermodell, aber es sollte nicht das einzige Steuerelement sein, auf das Ihre Anwendung angewiesen ist, wenn sie entscheidet, wie abgerufener Inhalt verwendet oder angezeigt wird.

Standardmäßig verwendet der Thread-Bereichsabruf den exakten Abgleich für user_id und agent_id und eine breitere Übereinstimmung für thread_id, sodass relevante Ergebnisse vergangene Threads für dasselbe Benutzer-Agent-Paar umfassen können. OracleAgentMemory.search()- und search_async()-Aufrufe der obersten Ebene erfordern auch expliziten Benutzergeltungsbereich und exakten Benutzerabgleich. Sie lehnen den ausgelassenen Benutzergeltungsbereich und exact_user_match=False ab, sodass die öffentliche Client-API nicht versehentlich über mehrere Benutzer hinweg sucht. Das Übergeben von user_id=None ist nur mit genauer Benutzerübereinstimmung zulässig, und Ziele sind nur nicht kopierte Datensätze.

Verwenden Sie die folgenden Übungen beim Entwerfen des Abrufs:

• Anwendungsregeln dem Speicherbereich zuordnen: Stellen Sie sicher, dass die Geltungsbereiche, die Ihre Anwendung an das SDK übergibt, mit Ihren Mandanten-, Benutzer- und Datenfreigaberegeln übereinstimmen.

• Bei jeder Clientsuche einen expliziten Benutzergeltungsbereich übergeben: Leiten Sie die user_id aus dem authentifizierten Anforderungskontext und nicht aus der JSON-Anforderung oder einer anderen aufrufergesteuerten Eingabe ab, und geben Sie sie bei jedem Aufruf der obersten Ebene OracleAgentMemory.search() oder search_async() an. Verwenden Sie user_id=None nur für Workflows, die absichtlich auf nicht kopierte Datensätze beschränkt sind.

• Vorziehen Sie den engsten Geltungsbereich, der den Anwendungsfall erfüllt: Verwenden Sie exakte Abgleichs- und engere Filter für Workflows, die vertraulichere Daten verarbeiten.

• Cross-Thread-Abruf absichtlich prüfen: Ein umfassenderer Abruf kann die Kontinuität über Sessions hinweg verbessern. Anwendungen sollten ihn jedoch nur dort aktivieren, wo dieser Ansatz angemessen ist.

• Suchergebnisse als abgerufener Inhalt behandeln, nicht als endgültige Entscheidungen: Zurückgegebene Speicher sind möglicherweise relevant, aber die Anwendung bleibt für die Entscheidung verantwortlich, ob und wie sie angezeigt oder bearbeitet werden sollen.

• Gesicherten Umgang mit abgerufenem Text an der Integrationsgrenze: Abgerufene Datensätze können vom Aufrufer bereitgestellten oder vom Modell abgeleiteten Text enthalten. Wenn abgerufene Speicher oder anderer zurückgegebener Text in HTML, Markdown, Vorlagen, Protokolle oder andere Ausgabeoberflächen gerendert werden, wenden Sie vor der Anzeige, Umwandlung, Protokollierung oder Weitergabe an nachgelagerte Systeme eine kontextgerechte Escaping- oder Desinfektion an.

Überlegungen zur Anwendungsintegration und zum Caller Trust

Agent Memory soll von der integrierenden Anwendung oder einem anderen vertrauenswürdigen Backend-Code aufgerufen werden, nicht direkt von den Endbenutzern. Raw-Speicher-APIs sind keine Sicherheitsgrenze für Endbenutzer, und sie führen keine Endbenutzerauthentifizierung oder -autorisierung allein aus. Das Package vertraut dem Aufrufer, dass er für jeden Vorgang den korrekten Geltungsbereich user_id, agent_id, thread_id und Retrieval angibt.

Hinweis: Die Integrationsanwendung ist dafür verantwortlich, den Endbenutzer zu authentifizieren, den Zugriff zu autorisieren und den richtigen user_id und Geltungsbereich abzuleiten, bevor sie Agent-Speicher-APIs aufruft. Ein vom Aufrufer bereitgestelltes user_id ist ein Geltungsbereichswert, kein Identitätsnachweis.

Verwenden Sie die folgenden Übungen, wenn Sie das SDK in eine Agent-Anwendung integrieren:

• user_id als sicherheitsrelevante Anwendungseingabe behandeln: Wenn die integrierende Anwendung user_id aus einer JSON-Anforderung oder einer anderen aufrufergesteuerten Eingabe anstelle eines authentifizierten Kontexts ableitet, kann dies den nutzerübergreifenden Speicherzugriff ermöglichen. Leiten Sie user_id aus dem authentifizierten Anwendungskontext ab, anstatt dass Endbenutzer beliebige Werte auswählen können.

• Anwendungsautorisierung vor jedem Speicheraufruf anwenden: Die integrierende Anwendung muss entscheiden, welche Werte für user_id, agent_id, thread_id und Suchgeltungsbereich für die aktuelle Anforderung gültig sind, und Lese- und Schreibvorgänge innerhalb der beabsichtigten Mandanten- und Benutzergrenze beibehalten.

• Raw-Speicher-APIs für Endbenutzer nicht verfügbar machen: Package-APIs wie add_memory oder Such-Helfer sollten in Anwendungslogik gewrappt werden, die den Aufrufer validiert, die Policy durchsetzt und kontrolliert, welche Daten geschrieben oder zurückgegeben werden können.

• Benutzer-ID-Discovery und Aufzählungsberechtigung beibehalten: Wenn das Package Helfer zum Auflisten oder Auflisten von user_id-Werten hinzufügt, behandeln Sie diese nur als administrative Funktionen und stellen sie Endbenutzern über die integrierende Anwendung niemals zur Verfügung.

• Überschreibungen des Geltungsbereichs sorgfältig prüfen: Jeder Workflow, der den Thread-Geltungsbereich erweitert, den exakten Abgleich deaktiviert oder auf Filial-APIs der unteren Ebene löscht, sollte auf vertrauenswürdige Komponenten beschränkt und auf nutzer- oder mandantenübergreifende Effekte geprüft werden.

Überlegungen zu Logging und Diagnose

Agent-Speicher verwendet Python-Standardlogging und konfiguriert keine Anwendungslog-Handler oder Logebenen für die integrierende Anwendung. Wenn die Integrationsanwendung das DEBUG-Logging für das SDK aktiviert, können Debuglogs zusätzliche Details zur Fehlerbehebung enthalten. Behalten Sie Produktions-Deployments auf einer Nicht-DEBUG-Ebene bei. Das DEBUG-Logging dient nur zur kontrollierten Entwicklung oder Supportdiagnose und ist nicht für die Erfassung von Produktionslogs geeignet.

Überlegungen zu Datenbankzugriff, Schemaverwaltung und Secrets

Agent-Speicher verwendet eine vom Aufrufer bereitgestellte Oracle AI Database-Verbindung oder einen Pool. Das Package erstellt oder verwaltet keine Datenbankzugangsdaten selbst. Außerdem wird keine Datenbanknetzwerkverschlüsselung im Namen des Aufrufers erstellt, ausgehandelt oder aktualisiert.

Hinweis:

• Erstellen Sie für Produktions-Deployments die Oracle AI Database-Verbindung oder den Pool mit aktiviertem verschlüsseltem Transport, bevor Sie ihn an den Agent-Speicher übergeben. Verwenden Sie keine Klartext-Datenbankverbindungen über nicht vertrauenswürdige, freigegebene oder externe Netzwerke hinweg. Befolgen Sie bei der Verwendung von python-oracledb den offiziellen Abschnitt Securely Encrypting Network Traffic to Oracle AI Database, und konfigurieren Sie TLS oder einen anderen genehmigten verschlüsselten Transport im Rahmen der Verbindungs- oder Poolerstellung.

• Niemals API-Schlüssel, Kennwörter oder andere Secrets direkt in Anwendungscode, eingecheckte Konfiguration oder exportierte Artefakte einbetten. Verwenden Sie immer sichere Injection-Mechanismen und befolgen Sie das Prinzip der geringsten Berechtigung für den Zugangsdatenzugriff.

Die folgenden Deployment-Praktiken werden empfohlen:

• Datenbankbenutzer nur mit den erforderlichen Berechtigungen verwenden: Erteilen Sie nur das, was für das ausgewählte Deployment-Modell und die ausgewählte Schema-Policy erforderlich ist.

• Beim Löschen von Workflows einen separaten Datenbankbenutzer verwenden: Wenn Ihre Anwendung Datensätze entfernen muss, bevorzugen Sie eine dedizierte Verbindung oder einen dedizierten Pool für diese Pfade, und erteilen Sie DELETE in den verwalteten Agent-Speichertabellen nur diesem Datenbankbenutzer. Begrenzen Sie die Hauptlaufzeitverbindung auf die für die normalen Vorgänge erforderlichen Nicht-Löschberechtigungen, sodass versehentliche oder unerwünschte Löschvorgänge einen engeren Strahlungsradius aufweisen. Wenn ein Aufrufer delete() über eine Verbindung aufruft, die keine Berechtigung DELETE hat, lehnt Oracle AI Database die Anweisung ab.

• Verschlüsselte Datenbankverbindungen und Pools erstellen: Produktionscode muss eine TLS-fähige Oracle AI Database-Verbindung oder einen TLS-fähigen Pool an das SDK übergeben. Der Agent-Speicher verwendet die Verbindung oder den Pool genau so, wie vom Aufrufer angegeben. Bei python-oracledb sollten Sie TLS-fähige Verbindungen wie protocol="tcps" oder einen entsprechenden TCPS-DSN bevorzugen, das erforderliche Wallet oder CA-Material konfigurieren und die Validierung des Serverzertifikats aktivieren.

• Behalten Sie die Standardschema-Policy bei, es sei denn, Sie benötigen explizit DDL-Änderungen: SchemaPolicy.REQUIRE_EXISTING ist der Standardwert und vermeidet das Erstellen, Ändern oder Löschen von Schemaobjekten beim Hochfahren der Standardanwendung.

• Beschränken Sie destruktive Setupmodi: SchemaPolicy.RECREATE ist für Setup-, Test- oder administrative Workflows gedacht und darf nicht in Standard-Produktionspfaden verwendet werden.

• Verlassen Sie sich auf Package-verwaltete SQL-Pfade, nicht auf dynamische SQL-Assemblierung im Anwendungscode: In den verwalteten DB-Pfaden werden Datensatzwerte und Suchfilter mit Bind-Variablen gesendet, und verwaltete Objektnamen werden aus validierten Präfixen abgeleitet.

• Verbindungs- und Providerzugangsdaten schützen: Speichern Sie Datenbank, LLM und Einbetten von Zugangsdaten in einen Secrets-Manager wie OCI Vault, und rotieren Sie sie regelmäßig.

• Validierte TLS sowohl im Thin- als auch im Thick-Modus bevorzugen: Die offiziellen python-oracledb-Dokumente weisen darauf hin, dass sowohl der Thin- als auch der Thick-Modus TLS unterstützen und der Thick-Modus auch die Oracle Native Network Encryption verwenden kann, wobei dies Ihr genehmigter Standard ist.

• Sicheren Transport zur Datenbank verwenden: Datenbanknetzwerksicherheit, TLS-Konfiguration und Authentifizierungsmethode werden von der vom Aufrufer bereitgestellten Verbindung bestimmt und müssen den Standards Ihrer Organisation entsprechen.

Überlegungen zur Netzwerkkommunikation und zu externen Endpunkten

Agent Memory kann mit externen Services kommunizieren, wenn das Deployment Remote-LLM oder Einbettungsprovider konfiguriert. Das SDK leitet Prompts und Anforderungsparameter über den konfigurierten Clientpfad weiter, aber die umgebende Anwendung und das Deployment bleiben für die Sicherung dieser Verbindungen verantwortlich.

Folgende Einstellungen werden empfohlen:

• HTTPS für Modellendpunkte verwenden und private oder eingeschränkte Netzwerkpfade bevorzugen, sofern verfügbar.

• Überwachen Sie ausgehenden Traffic und Providerauslastung für unerwartete Ziele, ungewöhnliches Anforderungs-Volume oder anomale Tokenauslastung.

• Wählen Sie Provider aus, die Ihren Compliance- und Residenzanforderungen entsprechen, bevor Sie Active-Memory-Features für regulierte oder sensible Workflows aktivieren.

Überlegungen zu Ressourcen-Erschöpfungs-Vektoren

Speicherworkflows können die Datenbanknutzung erhöhen, den Datenverkehr einbetten und den LLM-Tokenverbrauch im Laufe der Zeit erhöhen. Dies gilt sowohl für böswillige Übernutzung als auch für unschuldige Implementierungsfehler wie übergroße Nachrichten oder zu breite Abrufmuster.

Verwenden Sie diese Steuerelemente als Teil Ihrer Produktionshärtung:

• Praktische Prompt- und Meldungsgrenzen festlegen: Konfigurieren Sie Werte wie max_message_token_length und memory_extraction_token_limit entsprechend Ihren Workload- und Providerlimits. max_message_token_length begrenzt die von Extraktionsworkflows verwendete Prompt-Time-Kopie. Gespeicherte Nachrichten bleiben unverändert.

• Bound Retrieval-Größen: Verwenden Sie angemessene max_results-Werte und Datensatztypfilter für Anwendungssuchen.

• Infrastrukturlimits außerhalb des SDK anwenden: Verwenden Sie Datenbankkontingente, Verbindungslimits, Netzwerkkontrollen, Endpunkttimeouts und Ratenbegrenzung im umgebenden Deployment.

• Wachstum im Zeitverlauf überwachen: Verfolgen Sie das gespeicherte Nachrichtenvolumen, das dauerhafte Speicherwachstum, die Providernutzung und die Abfragelatenz, sodass Änderungen an der Aufbewahrung oder Optimierung vorgenommen werden können, bevor sie sich auf die Zuverlässigkeit auswirken.