Deep Data Security

Oracle Agent Memory si integra con Oracle Deep Data Security (Deep Sec) per applicare l'autorizzazione dell'utente finale all'interno di Oracle AI Database. Deep Sec è una funzione di sicurezza: i relativi ruoli di dati, le concessioni di dati e i contesti di sicurezza dell'utente finale determinano quali righe di memoria gestita una richiesta può leggere o modificare.

Importante: considerare le interfacce API in questa pagina come interfacce di amministrazione della sicurezza e di sicurezza delle richieste. Utilizza identità di database separate per l'amministrazione dei criteri, la proprietà dello schema gestito e il connection pooling runtime. L'account del pool di runtime non deve disporre di privilegi diretti che forniscono l'accesso di fallback alle tabelle di memoria agente protette.

La Panoramica di Deep Data Security di Oracle descrive il modello di autorizzazione del database. Per una distribuzione IAM OCI completa, vedere Applica l'isolamento della memoria dell'utente finale con Deep Data Security.

Modello di sicurezza

L'integrazione della memoria agente supporta due criteri:

Criterio Accesso effettivo
UserOwnRowsDeepDataSecurityPolicy Leggere e scrivere righe di memoria agente con ambito utente solo quando il relativo proprietario corrisponde a ORA_END_USER_CONTEXT.username. Le letture dei collegamenti di memoria richiedono che entrambe le memorie degli endpoint siano leggibili in base ai criteri assegnati; le scritture dei collegamenti richiedono che entrambe le memorie degli endpoint appartengano a tale utente.
GlobalMemoriesDeepDataSecurityPolicy Leggere le righe di memoria con ambito il cui user_id è NULL. Questo criterio non concede scritture o accesso alle memorie definite da un altro utente. Espone un collegamento di memoria quando entrambe le memorie endpoint sono leggibili in base ai criteri attivi. Solo con questa politica, entrambi gli endpoint devono essere memorie globali; se combinati con la politica della propria riga, sono visibili anche i collegamenti tra una memoria di proprietà e una memoria globale.

Gli oggetti criteri sono selezioni opache per le API di amministrazione. Le loro implementazioni Managed-table, Data-role, Data-Grant e SQL rimangono private in modo che Oracle Agent Memory possa evolvere il proprio schema di database in modo sicuro. Le sottoclassi dei criteri personalizzati non sono supportate. Utilizzare una delle due classi di criteri precedenti.

I criteri vengono applicati alla combinazione di owner_schema e memory_store_id. La creazione o l'assegnazione di un criterio per un negozio non lo assegna a un altro negozio, incluso un negozio con lo stesso ID in uno schema proprietario diverso.

Il criterio UserOwnRowsDeepDataSecurityPolicy limita anche le scritture in base alla colonna. Gli utenti finali possono impostare le colonne di identità e proprietà quando inseriscono una riga di proprietà, ma non possono modificarle in un secondo momento. Il criterio concede la seguente superficie di scrittura:

Autorizzazioni di scrittura a livello di colonna per UserOwnRowsDeepDataSecurityPolicy

Tabella gestita Colonne inseribili Colonne aggiornabile
Thread record_id, user_id, agent_id, metadata, runtime_config, runtime_state metadata, runtime_config, runtime_state
Riepilogo thread record_id, thread_id, user_id, agent_id, space_id, content, metadata, status content, metadata, status
Messaggio record_id, thread_id, user_id, agent_id, message_role, content, timestamp, metadata, expires_at, status content, timestamp, metadata, expires_at
Documento record_id, message_id, thread_id, user_id, agent_id, space_id, document_type, description, blob, timestamp, metadata, document_metadata, expires_at, status description, blob, timestamp, metadata, document_metadata, expires_at
Memoria record_id, thread_id, user_id, agent_id, memory_type, content, timestamp, metadata, expires_at, status content, timestamp, metadata, expires_at, status
Collegamento memoria relation_id, source_memory_id, source_memory_user_id, target_memory_id, target_memory_user_id, relation_type, opposite_relation_type, timestamp, metadata relation_type, opposite_relation_type, timestamp, metadata
Profilo dell'attore utente actor_id, actor_type, information, metadata, status information, metadata
Registra chunk source_id, source_record_type, source_emb_column, chunk_seq, chunk_text, thread_id, user_id, agent_id, status e embedding quando il negozio persiste nei vettori status

SELECT e DELETE rimangono con ambito row-scoped. Le colonne generate, in fase di creazione e riservate, come chunk_id, created_at e order_seq, non possono essere inserite o aggiornate dagli utenti finali a meno che non siano elencate esplicitamente sopra. Il database controlla inoltre la presenza di inserimenti nel predicato riga, pertanto l'elenco user_id come inseribile non consente a un utente finale di creare una riga di proprietà di un'altra identità. Quando un UPDATE si rivolge a una colonna non aggiornabile in una tabella che concede UPDATE su altre colonne, Deep Sec può lasciare in silenzio la riga invariata invece di generare un errore. I chunk di record consentono solo aggiornamenti status. L'SDK sostituisce le modifiche all'identità chunk, al testo e ai valori di incorporamento con le operazioni di eliminazione e inserimento. Le applicazioni devono utilizzare i metodi di mutazione supportati dall'SDK e non devono considerare la sola esecuzione SQL diretta come prova della modifica di un valore protetto.

Utilizzare le API di amministrazione in questo ordine:

  1. Creare l'area di memorizzazione memoria agente gestita come proprietario dello schema.
  2. Chiamare add_deep_data_security_policies() come amministratore della sicurezza.
  3. Chiama grant_agent_memory_policies() per ogni gruppo IAM OCI autorizzato o utente finale Deep Sec locale.
  4. In fase di esecuzione, eseguire il wrapping di ogni operazione di memoria agente in OracleMemoryEndUserSecurityContext.
  5. Revocare le assegnazioni prima di rimuovere i criteri non più necessari.

Se le operazioni di runtime utilizzano OracleDBEmbedder con il provider="database" predefinito e un modello memorizzato in Oracle AI Database, in genere un modello ONNX, i criteri concessi in precedenza autorizzano solo le tabelle di memoria agente. Anche il ruolo dati mappato del gruppo IAM deve avere accesso al modello residente nel database. Configurare tale accesso come descritto in Utilizzare un modello di incorporamento nel database con Deep Sec prima di soddisfare le richieste.

OracleDBEmbedder può anche utilizzare un provider remoto tramite DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING. Tale configurazione non utilizza un modello residente nel database e non richiede SELECT ON MINING MODEL. Configurare separatamente le credenziali Oracle e l'accesso di rete del provider remoto. L'operazione Memoria agente deve essere ancora eseguita all'interno di OracleMemoryEndUserSecurityContext.

Le chiamate di amministrazione eseguono il commit delle modifiche al database prima di tornare. Per il ruolo di base e i concetti di concessione, vedere Configurazione del controllo dell'accesso ai dati di Oracle.

Controlli di utilizzo del contesto

L'SDK rifiuta le combinazioni non sicure prima dell'esecuzione del lavoro dell'applicazione protetta:

Questi controlli diagnosticano un percorso di esecuzione SDK errato. Le autorizzazioni per i dati di Oracle AI Database rimangono il limite di autorizzazione e continuano a determinare a quali righe e colonne può accedere un utente finale autenticato.

Criteri

classe oracleagentmemory.core.deepsec.DeepDataSecurityPolicy

Basi: object

Identificare un criterio di sicurezza Deep Data della memoria dell'agente Oracle supportato.

Gli oggetti criteri sono selezioni opache passate alle funzioni di amministrazione di Deep Data Security. Istanza di UserOwnRowsDeepDataSecurityPolicy o GlobalMemoriesDeepDataSecurityPolicy. I dettagli di implementazione dei criteri, tra cui tabelle gestite, ruoli dati, autorizzazioni di accesso ai dati e SQL, rimangono privati per la memoria dell'agente Oracle e possono variare tra le release.

Questa classe non è un punto di estensione custom-policy. Le sottoclassi diverse dalle due classi di criteri fornite da Oracle Agent Memory vengono rifiutate dalle funzioni di amministrazione.

Esempi

Creare il set di criteri per le righe dell'utente finale e le memorie globali senza ambito:

policies = [
    UserOwnRowsDeepDataSecurityPolicy(),
    GlobalMemoriesDeepDataSecurityPolicy(),
]

classe oracleagentmemory.core.deepsec.UserOwnRowsDeepDataSecurityPolicy

Basi: DeepDataSecurityPolicy

Concedere l'accesso alle righe di proprietà dell'utente finale autenticato.

Questo criterio concede SELECT con ambito di riga, INSERT con ambito di colonna e UPDATE e DELETE con ambito di riga sui dati di proprietà dell'utente. Impossibile modificare la proprietà, il tipo di record, le colonne generate, il tempo di creazione e le colonne riservate dopo l'inserimento. I chunk di record possono essere inseriti ed eliminati, ma non possono essere aggiornati perché l'SDK li sostituisce come righe complete. Il criterio concede inoltre la lettura del registro necessaria per inizializzare un'area di memorizzazione runtime. Il collegamento alla memoria SELECT segue la regola di visibilità dell'endpoint condivisa, mentre il collegamento INSERT, UPDATE e DELETE richiede che entrambe le memorie dell'endpoint appartengano all'utente finale.

Esempi

policy = UserOwnRowsDeepDataSecurityPolicy()

classe oracleagentmemory.core.deepsec.GlobalMemoriesDeepDataSecurityPolicy

Basi: DeepDataSecurityPolicy

Concedi l'accesso in lettura ai ricordi globali e ai collegamenti tra i ricordi visibili.

Questo criterio concede a SELECT le righe di memoria il cui user_id è NULL e concede la lettura del registro necessaria per inizializzare un'area di memorizzazione runtime. La concessione di lettura del collegamento alla memoria espone un collegamento quando entrambe le memorie degli endpoint sono leggibili dall'utente finale in base ai criteri di sicurezza Deep Data assegnati. Con solo questa politica, entrambi gli endpoint devono quindi essere memorie globali; combinato con la politica della propria fila, è anche visibile un collegamento tra una memoria di proprietà e una memoria globale. Non consente la scrittura o l'accesso alle memorie definite da un altro utente.

Esempi

policy = GlobalMemoriesDeepDataSecurityPolicy()

Capitali

Un'assegnazione è destinata a un gruppo IAM OCI inserito nella richiesta personalizzata group del token di accesso o a un utente finale Deep Sec locale. Le informazioni sul gruppo IAM OCI devono essere configurate come richiesta personalizzata prima che Oracle AI Database possa eseguirne il mapping a un ruolo dati esterno. Vedere Configura richieste di risarcimento personalizzate per informazioni di gruppo in OCI IAM.

classe oracleagentmemory.core.deepsec.Principal

Basi: object

Tipo di base che identifica chi riceve le assegnazioni dei criteri memoria agente.

Le identità principali sono le identità di sicurezza interessate da grant_agent_memory_policies() o revoke_agent_memory_policies(). Il principal identifica l'assegnatario i cui ruoli o dati di Deep Data Security concedono il controllo dell'accesso a un'area di memorizzazione della memoria agente specifica. I tipi di principal correnti supportati sono i gruppi IAM OCI e gli utenti finali DB locali.

Utilizzare OciGroupPrincipal per un gruppo IAM OCI o LocalEndUserPrincipal per un utente finale Deep Data Security gestito dal database. Il passaggio di un'istanza Principal diretta a una funzione di amministrazione non è supportato.

classe oracleagentmemory.core.deepsec.OciGroupPrincipal

Basi: Principal

Identificare un gruppo IAM OCI che riceve i criteri di memoria dell'agente.

classe oracleagentmemory.core.deepsec.LocalEndUserPrincipal

Basi: Principal

Identifica un utente finale di Deep Data Security locale che riceve i criteri.

Amministrazione

Eseguire queste funzioni tramite una connessione dedicata all'amministrazione della sicurezza. Per le tabelle di memoria agente cross-schema, tale account richiede i privilegi di amministrazione Deep Sec applicabili, tra cui CREATE ANY DATA GRANT, DROP ANY DATA GRANT e ADMINISTER ANY DATA GRANT, oltre all'autorità per creare ed eliminare i ruoli dati. Non concedere questi privilegi all'account del pool di runtime.

oracleagentmemory.core.deepsec.add_deep_data_security_policies

Creare i ruoli dati e le autorizzazioni dati per i criteri di memoria agente.

I criteri sono definiti con un ambito owner_schema e memory_store_id. L'aggiunta consente l'applicazione obbligatoria di Deep Data Security nelle tabelle gestite protette. La riaggiunta di un criterio sostituisce il ruolo dati gestito dalla memoria dell'agente e concede con la definizione corrente. Le chiamate ripetute sono idempotenti. Se Oracle esegue il commit di parte della DDL della policy prima di un'interruzione, il nuovo tentativo di chiamata risolve le definizioni gestite.

Questa funzione esegue il commit della connessione prima di tornare. Utilizzare una connessione dedicata all'amministrazione della sicurezza anziché una connessione a un proprietario dello schema o a un'applicazione runtime.

Esempi

Aggiungere i criteri di accesso della propria riga e della memoria globale:

add_deep_data_security_policies(
    connection,
    owner_schema="MY_OWNER_SCHEMA",
    memory_store_id="MEMORY",
    policies=[
        UserOwnRowsDeepDataSecurityPolicy(),
        GlobalMemoriesDeepDataSecurityPolicy(),
    ],
)

oracleagentmemory.core.deepsec.remove_deep_data_security_policies

Rimuovere i criteri di sicurezza Deep Data della memoria agente.

L'eliminazione di un ruolo criterio comporta anche la rimozione di tale ruolo dalle autorizzazioni dati e dalle assegnazioni di utenti finali locali. Le assegnazioni IAM OCI create come concessioni dati esterne devono prima essere rimosse con revoke_agent_memory_policies(). L'applicazione della concessione dei dati obbligatoria è disabilitata per una tabella gestita solo quando non rimangono autorizzazioni dati su tale tabella.

Questa funzione esegue il commit della connessione prima di tornare.

Esempi

Rimuovere il criterio della propria riga:

remove_deep_data_security_policies(
    connection,
    owner_schema="MY_OWNER_SCHEMA",
    memory_store_id="MEMORY",
    policies=[UserOwnRowsDeepDataSecurityPolicy()],
)

oracleagentmemory.core.deepsec.list_deep_data_security_policies

Elenca i criteri di memoria agente attualmente creati in Oracle AI Database.

Esempi

Ispezionare i tipi di criteri configurati:

policies = list_deep_data_security_policies(
    connection,
    owner_schema="MY_OWNER_SCHEMA",
    memory_store_id="MEMORY",
)
[type(policy).__name__ for policy in policies]
['UserOwnRowsDeepDataSecurityPolicy']

oracleagentmemory.core.deepsec.grant_agent_memory_policies

Concedere i criteri di memoria agente ai gruppi IAM OCI o agli utenti finali locali.

I gruppi IAM OCI sono rappresentati da ruoli dati mappati esternamente. Le autorizzazioni di accesso ai dati per ogni criterio vengono collegate direttamente al ruolo mappato perché Oracle AI Database non consente ai ruoli dati mappati esternamente di ricevere ruoli dati gestiti localmente.

Creare ogni criterio per l'area di memorizzazione di destinazione con add_deep_data_security_policies() prima di assegnarlo. Questa funzione esegue il commit della connessione prima di tornare. Le chiamate ripetute sono idempotenti. Se Oracle esegue il commit di parte di un'assegnazione IAM OCI prima di un'interruzione, un nuovo tentativo di chiamata ricrea le autorizzazioni di accesso ai dati gestiti mancanti.

Esempi

Concedere l'accesso in proprio a un gruppo IAM OCI:

grant_agent_memory_policies(
    connection,
    memory_store_id="MEMORY",
    owner_schema="MY_OWNER_SCHEMA",
    principals=[OciGroupPrincipal("ORACLEAGENTMEMORY_USERS")],
    policies=[UserOwnRowsDeepDataSecurityPolicy()],
)

oracleagentmemory.core.deepsec.revoke_agent_memory_policies

Revoca i criteri di memoria agente ai gruppi IAM OCI o agli utenti finali locali.

Il principio stesso è preservato. In particolare, il ruolo dati mappato esternamente di un gruppo IAM OCI rimane disponibile per le assegnazioni da questa o da un'altra area di memorizzazione della memoria agente.

La revoca modifica lo stato dei criteri del database e i commit prima della restituzione, pertanto le istruzioni del database protetto successive non ricevono più il criterio revocato. Questa operazione è diversa dalla rimozione di un utente da un gruppo IAM OCI: un token di accesso già emesso conserva la relativa richiesta di gruppo incorporata fino alla scadenza del token.

Esempi

Revocare l'accesso della propria riga da un gruppo IAM OCI:

revoke_agent_memory_policies(
    connection,
    memory_store_id="MEMORY",
    owner_schema="MY_OWNER_SCHEMA",
    principals=[OciGroupPrincipal("ORACLEAGENTMEMORY_USERS")],
    policies=[UserOwnRowsDeepDataSecurityPolicy()],
)

oracleagentmemory.core.deepsec.list_agent_memory_granted_policies

Elenca i principal e i criteri di memoria agente assegnati a ciascun principal.

Esempi

Elenca assegnazioni criteri:

assignments = list_agent_memory_granted_policies(
    connection,
    memory_store_id="MEMORY",
    owner_schema="MY_OWNER_SCHEMA",
)
len(assignments) >= 0
True

Contesto di sicurezza runtime

OracleMemoryEndUserSecurityContext applica il contesto di sicurezza python-oracledb alle operazioni di memoria agente. Il contesto contiene il token dell'utente finale e il token di accesso al database; Oracle AI Database li convalida e ricava i ruoli dati attivi dalle richieste. L'SDK collega il contesto a ogni connessione fisica acquisita e lo cancella prima di restituire tale connessione al pool.

Vedere Contesto di sicurezza utente finale di Oracle per il modello di sicurezza e Modalità di gestione di un contesto di sicurezza utente finale per la convalida, la risoluzione dei ruoli, il riutilizzo della connessione e il cleanup del contesto.

classe oracleagentmemory.core.deepsec.OracleMemoryEndUserSecurityContext

Basi: object

Applicare un contesto di sicurezza dell'utente finale Oracle alle operazioni di memoria agente.

L'immissione di questo gestore di contesto rende security_context disponibile per le aree di memorizzazione della memoria dell'agente supportate da Oracle utilizzate nel contesto di esecuzione corrente. Ogni operazione del database applica il contesto dopo aver acquisito la connessione fisica, verifica che sia attiva un'identità dell'utente finale e cancella il contesto prima di rilasciare la connessione. Questo comportamento funziona sia con le connessioni dirette che con i connection pool.

L'ambito si propaga alle chiamate di memoria dell'agente asincrono attese. I task del chiamante che superano il blocco with o async with non possono utilizzare l'ambito scaduto. I job di estrazione della memoria in background accettati all'interno del blocco conservano uno snapshot privato in modo che possano essere completati dopo l'uscita dal blocco.

Utilizzare un nuovo oracledb.EndUserSecurityContext quando l'utente finale o il token di accesso al database cambia. Oracle AI Database deriva i ruoli dati abilitati dalle richieste nel token fornito; questo manager non aggiorna, revoca o ispeziona i token OAuth.

Note

Questa classe fa riferimento alle operazioni di memoria dell'agente Oracle. Non modifica una connessione arbitraria utilizzata direttamente da SQL dell'applicazione al di fuori dell'SDK. La nidificazione è supportata, inclusa la nidificazione della stessa istanza di manager; ogni uscita ripristina il contesto dalla voce corrispondente.

Esempi

Applicare un contesto derivato da OAuth alle operazioni di memoria agente sincrona:

import oracledb
from oracleagentmemory.core.deepsec import (
    OracleMemoryEndUserSecurityContext,
)
user_context = oracledb.create_end_user_security_context(
    end_user_identity=end_user_token,
    database_access_token=database_access_token,
)
with OracleMemoryEndUserSecurityContext(user_context):
    memory_store.add(
        ["Remember this preference."],
        record_type="memory",
    )

Lo stesso manager supporta le chiamate asincrone:

async with OracleMemoryEndUserSecurityContext(user_context):
    await memory_store.add_async(
        ["Remember this preference."],
        record_type="memory",
    )

metodo __aenter__ (asincrono)

Immettere l'ambito per le operazioni di memoria agente in attesa.

metodo __aexit__ (asincrono)

Uscire dall'ambito asincrono senza sopprimere le eccezioni di blocco.

metodo __enter__

Immettere l'ambito e restituire questo manager contesto.

Le operazioni di memoria dell'agente avviate nel contesto di esecuzione corrente utilizzano il contesto di sicurezza dell'utente finale di questo manager fino all'uscita corrispondente.

metodo __exit__

Uscire dall'ambito e impedire il riutilizzo dei task del chiamante ereditati.

Qualsiasi eccezione del blocco gestito viene propagata invariata.

oracleagentmemory.core.deepsec.get_end_user_username

Restituisce il nome utente dell'utente finale collegato a una connessione Oracle DB.

Deep Data Security valuta le autorizzazioni dei dati utilizzando il contesto di sicurezza dell'utente finale collegato a una connessione al database. Questa applicazione di supporto legge l'attributo username da tale contesto. Non restituisce l'account di database utilizzato per stabilire la connessione fisica.

Esempi

Verificare se una connessione dispone di un'identità utente finale collegata:

get_end_user_username(conn) is None
True

Audit

Deep Sec utilizza Oracle AI Database Unified Auditing. Un amministratore di database può creare criteri di audit unificati per le operazioni di configurazione Deep Sec, ad esempio la creazione o l'eliminazione di ruoli dati e autorizzazioni dati, la concessione o la revoca di ruoli dati e la creazione o l'eliminazione di utenti finali e contesti utente finale. I record di audit sono disponibili tramite UNIFIED_AUDIT_TRAIL e possono includere l'identificativo di identità e contesto di sicurezza dell'utente finale per l'attività eseguita in un contesto di sicurezza dell'utente finale.

L'azione CREATE END USER SECURITY CONTEXT registra la creazione del contesto di sicurezza. Oracle rileva che può generare molti record e non è incluso in ACTIONS ALL; specificarlo in modo esplicito quando è necessario eseguire l'audit di tale evento del ciclo di vita. Seleziona le azioni di audit e la conservazione in base ai requisiti di sicurezza e conformità della distribuzione. I log dell'applicazione SDK sono diagnostici e non sostituiscono l'audit trail del database.

Vedere Audit delle operazioni di sicurezza Deep Data di Oracle e l'elenco ufficiale delle azioni verificabili Deep Sec.

Contratto tempo di revoca

La revoca dei criteri del database e la rimozione dell'appartenenza al gruppo IAM OCI hanno tempi di validità diversi:

Azione amministrativa Ora validità
Chiama revoke_agent_memory_policies() La funzione rimuove l'assegnazione e i commit del database specifico dell'area di memorizzazione prima della restituzione. Le istruzioni del database protetto successive non ricevono più tale criterio. Un'istruzione già in esecuzione non viene annullata retroattivamente.
Rimuovere un utente dal gruppo di assegnatari in OCI IAM I token di accesso appena emessi riflettono l'appartenenza aggiornata. Un token di accesso già emesso all'utente contiene ancora la richiesta group e può continuare ad autorizzare il ruolo dati Deep Sec corrispondente fino alla scadenza del token.

Il limite superiore effettivo per la revoca solo per IAM è pertanto la durata rimanente nella richiesta exp del token emesso. La durata del token di accesso IAM OCI è configurabile; quando non viene impostata alcuna applicazione delle risorse, sessione utente o scadenza personalizzata, il valore predefinito documentato è di 3600 secondi. Le applicazioni devono interrompere il riutilizzo di un token scaduto e ottenere un nuovo token le cui richieste riflettono l'appartenenza corrente.

Per la revoca urgente, chiamare in primo luogo revoke_agent_memory_policies() per rimuovere immediatamente l'assegnazione del database per le istruzioni successive, quindi rimuovere l'utente dal gruppo IAM OCI. Concedere nuovamente il criterio di database solo quando il gruppo nel suo complesso deve riottenere l'accesso. Se è necessario rimuovere solo un membro mentre il gruppo rimane autorizzato, fare affidamento sulla scadenza del token o utilizzare una durata del token di accesso più breve specifica della distribuzione e un criterio di riautenticazione.

Vedere la sezione relativa alla gestione dell'autorizzazione mediante l'API e la tabella di scadenza dei token di OCI IAM, insieme ai riferimenti al ciclo di vita del contesto di sicurezza Deep Sec sopra riportati.