Deep Data Security

Oracle Agent Memory se integra con Oracle Deep Data Security (Deep Sec) para aplicar la autorización del usuario final dentro de Oracle AI Database. Deep Sec es una función de seguridad: sus roles de datos, permisos de datos y contextos de seguridad de usuario final determinan qué filas de memoria gestionada puede leer o modificar una solicitud.

Importante: trate las API de esta página como interfaces de seguridad-administración y solicitud-seguridad. Utilice identidades de base de datos independientes para la administración de políticas, la propiedad del esquema gestionado y el pool de conexiones en tiempo de ejecución. La cuenta de pool de tiempo de ejecución no debe tener privilegios directos que proporcionen acceso de reserva a las tablas de memoria de agente protegidas.

La visión general de la seguridad de datos profunda de Oracle describe el modelo de autorización de la base de datos. Para obtener un despliegue completo de OCI IAM, consulte Aplicación de aislamiento de memoria de usuario final con Deep Data Security.

Modelo de seguridad

La integración de memoria de agente soporta dos políticas:

Política Acceso efectivo
UserOwnRowsDeepDataSecurityPolicy Leer y escribir filas de memoria de agente de ámbito de usuario solo cuando su propietario coincida con ORA_END_USER_CONTEXT.username. Las lecturas de enlace de memoria requieren que ambas memorias de punto final sean legibles en las políticas asignadas; las escrituras de enlace requieren que ambas memorias de punto final pertenezcan a ese usuario.
GlobalMemoriesDeepDataSecurityPolicy Leer filas de memoria sin ámbito cuyo valor user_id es NULL. Esta política no otorga escrituras ni acceso a las memorias de ámbito de otro usuario. Expone un enlace de memoria cuando ambas memorias de punto final se pueden leer en las políticas activas. Con solo esta política, ambos puntos finales deben ser memorias globales; cuando se combinan con la política de fila propia, también se pueden ver los enlaces entre una memoria propia y una memoria global.

Los objetos de política son selecciones opacas para las API de administración. Sus implementaciones de tablas gestionadas, rol de datos, otorgamiento de datos y SQL siguen siendo privadas para que la memoria del agente de Oracle pueda evolucionar su esquema de base de datos de forma segura. Las subclases de política personalizadas no están soportadas; utilice una de las dos clases de política anteriores.

Las políticas tienen un ámbito para la combinación de owner_schema y memory_store_id. La creación o asignación de una política para un almacén no la asigna a otro almacén, incluido un almacén con el mismo ID en un esquema de propietario diferente.

La política UserOwnRowsDeepDataSecurityPolicy también limita las escrituras por columna. Los usuarios finales pueden definir columnas de identidad y propiedad al insertar una fila propia, pero no pueden cambiar esas columnas más adelante. La política otorga la siguiente superficie de escritura:

Permisos de escritura a nivel de columna para UserOwnRowsDeepDataSecurityPolicy

Tabla gestionada Columnas que se pueden insertar Columnas actualizables
Hilo record_id, user_id, agent_id, metadata, runtime_config, runtime_state metadata, runtime_config, runtime_state
Resumen de hilos record_id, thread_id, user_id, agent_id, space_id, content, metadata, status content, metadata, status
Mensaje 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
Enlace de 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
Perfil de actor de usuario actor_id, actor_type, information, metadata, status information, metadata
Grabar fragmentos source_id, source_record_type, source_emb_column, chunk_seq, chunk_text, thread_id, user_id, agent_id, status y embedding cuando el almacén persiste en vectores status

SELECT y DELETE permanecen en el ámbito de fila. Las columnas generadas, de tiempo de creación y reservadas, como chunk_id, created_at y order_seq, no pueden ser insertadas ni actualizadas por los usuarios finales, a menos que se enumeren explícitamente anteriormente. La base de datos también comprueba el predicado de fila en busca de inserciones, por lo que la enumeración de user_id como insertable no permite que un usuario final cree una fila propiedad de otra identidad. Cuando un UPDATE tiene como destino una columna no actualizable en una tabla que otorga UPDATE en otras columnas, Deep Sec puede dejar silenciosamente la fila sin cambios en lugar de emitir un error. Los fragmentos de registro solo permiten actualizaciones de status. El SDK sustituye los cambios en la identidad de fragmento, el texto y la incrustación de valores con operaciones de supresión e inserción. Las aplicaciones deben utilizar los métodos de mutación soportados por el SDK y no deben tratar la ejecución directa de SQL solo como prueba de que ha cambiado un valor protegido.

Utilice las API de administración en este orden:

  1. Cree el almacén de memoria de agente gestionado como propietario del esquema.
  2. Llame a add_deep_data_security_policies() como administrador de seguridad.
  3. Llame a grant_agent_memory_policies() para cada grupo autorizado de OCI IAM o usuario final de Deep Sec local.
  4. En tiempo de ejecución, ajuste todas las operaciones de memoria de agente en OracleMemoryEndUserSecurityContext.
  5. Revoca las asignaciones antes de eliminar las políticas que ya no son necesarias.

Si las operaciones de tiempo de ejecución utilizan OracleDBEmbedder con el valor por defecto provider="database" y un modelo almacenado en Oracle AI Database, normalmente un modelo ONNX, los permisos de política anteriores solo autorizan las tablas de memoria del agente. El rol de datos asignado del grupo de IAM también debe tener acceso al modelo residente en la base de datos. Configure ese acceso como se describe en Uso de un modelo de embebido en la base de datos con Deep Sec antes de servir solicitudes.

OracleDBEmbedder también puede utilizar un proveedor remoto mediante DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING. Esa configuración no utiliza un modelo que reside en la base de datos y no necesita SELECT ON MINING MODEL. Configure la credencial de Oracle del proveedor remoto y el acceso a la red por separado. La operación de memoria del agente debe seguir ejecutándose dentro de OracleMemoryEndUserSecurityContext.

Las llamadas de administración confirman los cambios de la base de datos antes de volver. Para conocer los conceptos de rol y permiso subyacentes, consulte Data Access Control Configuration de Oracle.

Comprobaciones de uso de contexto

El SDK rechaza las combinaciones no seguras antes de que se ejecute el trabajo de la aplicación protegida:

Estas comprobaciones diagnostican una ruta de ejecución de SDK incorrecta. Los permisos de datos de Oracle AI Database siguen siendo el límite de autorización y siguen determinando a qué filas y columnas puede acceder un usuario final autenticado.

Políticas

clase oracleagentmemory.core.deepsec.DeepDataSecurityPolicy

Bases: object

Identifique una política de seguridad de datos en profundidad de memoria de Oracle Agent soportada.

Los objetos de política son selecciones opacas que se transfieren a las funciones de administración de Deep Data Security. Instancie UserOwnRowsDeepDataSecurityPolicy o GlobalMemoriesDeepDataSecurityPolicy. Los detalles de implantación de políticas, incluidas las tablas gestionadas, los roles de datos, los permisos de datos y SQL, siguen siendo privados para la memoria del agente de Oracle y pueden cambiar entre versiones.

Esta clase no es un punto de extensión de política personalizada. Las funciones de administración rechazan subclases que no sean las dos clases de política proporcionadas por la memoria del agente de Oracle.

Ejemplos

Cree el juego de políticas para las filas de usuario final y las memorias globales sin ámbito:

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

clase oracleagentmemory.core.deepsec.UserOwnRowsDeepDataSecurityPolicy

Bases: DeepDataSecurityPolicy

Otorgue acceso a las filas propiedad del usuario final autenticado.

Esta política otorga el ámbito de fila SELECT, el ámbito de columna INSERT y UPDATE, y el ámbito de fila DELETE en los datos propiedad del usuario. Las columnas Propiedad, Tipo de registro, Generado, Tiempo de creación y Reservado no se pueden cambiar después de la inserción. Los fragmentos de registro se pueden insertar y suprimir, pero no se pueden actualizar porque el SDK los sustituye como filas completas. La política también otorga la lectura de registro necesaria para inicializar un almacén de tiempo de ejecución. El enlace de memoria SELECT sigue la regla de visibilidad de punto final compartido, mientras que el enlace INSERT, UPDATE y DELETE requieren que ambas memorias de punto final pertenezcan al usuario final.

Ejemplos

policy = UserOwnRowsDeepDataSecurityPolicy()

clase oracleagentmemory.core.deepsec.GlobalMemoriesDeepDataSecurityPolicy

Bases: DeepDataSecurityPolicy

Otorgar acceso de lectura a los recuerdos globales y los vínculos entre los recuerdos visibles.

Esta política otorga SELECT a las filas de memoria cuyo valor user_id es NULL y otorga la lectura de registro necesaria para inicializar un almacén de tiempo de ejecución. Su permiso de lectura de enlace de memoria expone un enlace cuando el usuario final puede leer ambas memorias de punto final en las políticas de seguridad de datos profunda asignadas. Con solo esta política, ambos puntos finales deben ser, por lo tanto, memorias globales; combinados con la política de fila propia, también se puede ver un vínculo entre una memoria propia y una memoria global. No permite la escritura ni el acceso a las memorias de ámbito de otro usuario.

Ejemplos

policy = GlobalMemoriesDeepDataSecurityPolicy()

Principales

Una asignación tiene como destino un grupo de OCI IAM incluido en la reclamación personalizada group del token de acceso o un usuario final de Deep Sec local. La información del grupo de OCI IAM se debe configurar como una reclamación personalizada antes de que Oracle AI Database pueda asignarla a un rol de datos externo. Consulte Configuración de reclamaciones personalizadas para información de grupo en OCI IAM.

clase oracleagentmemory.core.deepsec.Principal

Bases: object

Tipo base que identifica quién recibe las asignaciones de política de memoria del agente.

Los principales son las identidades de seguridad a las que se dirigen grant_agent_memory_policies() o revoke_agent_memory_policies(). El principal identifica al usuario con privilegios cuyos roles de datos o datos de Deep Data Security otorgan acceso de control a un almacén de memoria de agente específico. Los tipos de principales actuales soportados son los grupos de OCI IAM y los usuarios finales locales de la base de datos.

Utilice OciGroupPrincipal para un grupo de OCI IAM o LocalEndUserPrincipal para un usuario final de Deep Data Security gestionado por base de datos. No se soporta la transferencia de una instancia Principal directa a una función de administración.

clase oracleagentmemory.core.deepsec.OciGroupPrincipal

Bases: Principal

Identifique un grupo de OCI IAM que reciba políticas de memoria del agente.

clase oracleagentmemory.core.deepsec.LocalEndUserPrincipal

Bases: Principal

Identifique las políticas de recepción de usuarios finales de Deep Data Security locales.

Administración

Ejecute estas funciones mediante una conexión dedicada de administración de seguridad. Para las tablas de memoria de agente entre esquemas, esa cuenta necesita los privilegios de administración de Deep Sec aplicables, incluidos CREATE ANY DATA GRANT, DROP ANY DATA GRANT y ADMINISTER ANY DATA GRANT, además de la autoridad para crear y borrar roles de datos. No otorgue estos privilegios a la cuenta de pool de tiempo de ejecución.

oracleagentmemory.core.deepsec.add_deep_data_security_policies

Cree los roles de datos y los permisos de datos para las políticas de memoria del agente.

Las políticas tienen un ámbito de owner_schema y memory_store_id. Al agregarlos, se activa la aplicación obligatoria de Deep Data Security en sus tablas gestionadas protegidas. Al volver a agregar una política, se sustituye el rol de datos gestionado por memoria del agente y se otorga la definición actual. Las llamadas repetidas son idempotentes. Si Oracle confirma parte del DDL de política antes de una interrupción, al reintentar la misma llamada se reparan las definiciones gestionadas.

Esta función confirma la conexión antes de volver. Utilice una conexión dedicada de administración de seguridad en lugar de una conexión de aplicación de tiempo de ejecución o propietario de esquema.

Ejemplos

Agregue políticas de acceso de propia fila y memoria global:

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

Elimine las políticas de seguridad de datos profundos de memoria del agente.

Al borrar un rol de política, también se elimina ese rol de sus otorgamientos de datos y asignaciones de usuario final locales. Las asignaciones de OCI IAM creadas como permisos de datos externos se deben eliminar primero con revoke_agent_memory_policies(). La aplicación obligatoria de otorgamiento de datos está desactivada para una tabla gestionada solo cuando no quedan otorgamientos de datos en esa tabla.

Esta función confirma la conexión antes de volver.

Ejemplos

Elimine la política de fila propia:

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

Mostrar las políticas de memoria del agente creadas actualmente en Oracle AI Database.

Ejemplos

Inspeccionar tipos de políticas configuradas:

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

Otorgue políticas de memoria del agente a grupos de OCI IAM o usuarios finales locales.

Los grupos de OCI IAM están representados por roles de datos asignados externamente. Los otorgamientos de datos para cada política se asocian directamente a ese rol asignado porque Oracle AI Database no permite que los roles de datos asignados externamente reciban roles de datos gestionados localmente.

Cree cada política para el almacén de destino con add_deep_data_security_policies() antes de asignarla. Esta función confirma la conexión antes de volver. Las llamadas repetidas son idempotentes. Si Oracle confirma parte de una asignación de OCI IAM antes de una interrupción, al reintentar la misma llamada se vuelven a crear los permisos de datos gestionados que faltan.

Ejemplos

Otorgue acceso de fila propia a un grupo de OCI IAM:

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

Revocar políticas de memoria de agente de grupos de OCI IAM o usuarios finales locales.

El principio mismo se conserva. En particular, el rol de datos asignado externamente de un grupo de OCI IAM permanece disponible para las asignaciones de este u otro almacén de memoria de agente.

La revocación cambia el estado de la política de base de datos y se confirma antes de volver, por lo que las sentencias de base de datos protegidas posteriores ya no reciben la política revocada. Esto es distinto de eliminar un usuario de un grupo de OCI IAM: un token de acceso ya emitido conserva su reclamación de grupo embebido hasta que caduca ese token.

Ejemplos

Revoca el acceso a la propia fila desde un grupo de OCI IAM:

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

Enumere los principales y las políticas de memoria del agente asignadas a cada principal.

Ejemplos

Enumerar asignaciones de políticas:

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

Contexto de seguridad de tiempo de ejecución

OracleMemoryEndUserSecurityContext abarca el contexto de seguridad de python-oracledb para las operaciones de memoria del agente. El contexto incluye el token de usuario final y el token de acceso a la base de datos; Oracle AI Database los valida y deriva los roles de datos activos de sus reclamaciones. El SDK asocia el contexto a cada conexión física adquirida y la borra antes de devolver esa conexión al pool.

Consulte Contexto de Seguridad de Usuario Final de Oracle para conocer el modelo de seguridad y Cómo el Servidor de Base de Datos Gestiona un Contexto de Seguridad de Usuario Final para conocer la validación, la resolución de roles, la reutilización de conexiones y la limpieza de contexto.

clase oracleagentmemory.core.deepsec.OracleMemoryEndUserSecurityContext

Bases: object

Aplicar un contexto de seguridad de usuario final de Oracle a las operaciones de memoria del agente.

Al introducir este gestor de contexto, security_context queda disponible para los almacenes de memoria de agente respaldados por Oracle utilizados en el contexto de ejecución actual. Cada operación de base de datos aplica el contexto después de adquirir su conexión física, verifica que una identidad de usuario final está activa y borra el contexto antes de liberar la conexión. Este comportamiento funciona tanto con conexiones directas como con pools de conexiones.

El ámbito se propaga a llamadas de memoria de agente asíncronas en espera. Las tareas de llamada que superan el bloque with o async with no pueden utilizar el ámbito caducado. Los trabajos de extracción de memoria en segundo plano aceptados dentro del bloque conservan una instantánea privada para que se puedan completar después de que se cierre el bloque.

Utilice un nuevo oracledb.EndUserSecurityContext cuando cambie el token de acceso a la base de datos o al usuario final. Oracle AI Database deriva los roles de datos activados de las reclamaciones del token proporcionado; este gestor no refresca, revoca ni inspecciona los tokens de OAuth.

Notas

Esta clase abarca las operaciones de memoria del agente de Oracle. No modifica una conexión arbitraria utilizada directamente por la aplicación SQL fuera del SDK. El anidamiento está soportado, incluido el anidamiento de la misma instancia de gestor; cada salida restaura el contexto de su entrada coincidente.

Ejemplos

Aplique un contexto derivado de OAuth a las operaciones síncronas de memoria del agente:

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",
    )

El mismo gestor soporta llamadas asíncronas:

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

method __aenter__ (async)

Introduzca el ámbito para las operaciones de memoria de agente esperadas.

method __aexit__ (async)

Salga del ámbito asíncrono sin suprimir las excepciones de bloque.

método __enter__

Introduzca el ámbito y devuelva este gestor de contexto.

Las operaciones de memoria de agente iniciadas en el contexto de ejecución actual utilizan el contexto de seguridad de usuario final de este gestor hasta la salida coincidente.

método __exit__

Salga del ámbito y evite que las tareas del emisor de llamada heredadas lo reutilicen.

Cualquier excepción del bloque gestionado se propaga sin cambios.

oracleagentmemory.core.deepsec.get_end_user_username

Devolver el nombre de usuario de usuario final asociado a una conexión de Oracle DB.

Deep Data Security evalúa los permisos de datos mediante el contexto de seguridad del usuario final asociado a una conexión de base de datos. Este ayudante lee el atributo username de ese contexto. No devuelve la cuenta de base de datos utilizada para establecer la conexión física.

Ejemplos

Compruebe si una conexión tiene una identidad de usuario final asociada:

get_end_user_username(conn) is None
True

Auditoría

Deep Sec utiliza la auditoría unificada de Oracle AI Database. Un administrador de base de datos puede crear políticas de auditoría unificadas para operaciones de configuración de Deep Sec, como crear o borrar roles de datos y otorgamientos de datos, otorgar o revocar roles de datos, y crear o borrar usuarios finales y contextos de usuario final. Los registros de auditoría están disponibles a través de UNIFIED_AUDIT_TRAIL y pueden incluir la identidad del usuario final y el identificador de contexto de seguridad para la actividad realizada en un contexto de seguridad del usuario final.

La acción CREATE END USER SECURITY CONTEXT registra la creación del contexto de seguridad. Oracle señala que puede generar muchos registros y no está incluido en ACTIONS ALL; especifíquelo explícitamente cuando se deba auditar ese evento de ciclo de vida. Seleccione las acciones de auditoría y la retención según los requisitos de seguridad y conformidad del despliegue. Los logs de aplicaciones SDK son diagnósticos y no sustituyen a la pista de auditoría de la base de datos.

Consulte Auditoría de operaciones de seguridad de datos profunda de Oracle y la lista oficial de acciones auditables de seguridad profunda.

Contrato de tiempo de revocación

La revocación de la política de base de datos y la eliminación de la pertenencia a un grupo de OCI IAM tienen tiempos de vigencia diferentes:

Acción administrativa Hora de vigencia
Llame a revoke_agent_memory_policies() La función elimina la asignación de base de datos específica del almacén y se confirma antes de volver. Las sentencias de base de datos protegidas posteriores ya no reciben esa política. Una sentencia que ya se está ejecutando no se ha cancelado retroactivamente.
Eliminar un usuario del grupo de usuarios con privilegios en OCI IAM Los tokens de acceso recién emitidos reflejan la afiliación actualizada. Un token de acceso ya emitido al usuario aún contiene su reclamación group y puede seguir autorizando el rol de datos de Deep Sec correspondiente hasta que caduque ese token.

El límite superior efectivo para la revocación solo de IAM es, por lo tanto, la vida útil restante en la reclamación exp del token emitido. La duración del token de acceso de OCI IAM se puede configurar; cuando no se define ninguna aplicación de recursos, sesión de usuario o caducidad personalizada, el valor por defecto documentado es de 3600 segundos. Las aplicaciones deben dejar de reutilizar un token caducado y obtener un nuevo token cuyas reclamaciones reflejen la afiliación actual.

Para una revocación urgente, primero llame a revoke_agent_memory_policies() para eliminar la asignación de base de datos inmediatamente para las sentencias posteriores y, a continuación, elimine el usuario del grupo de OCI IAM. Vuelva a otorgar la política de base de datos solo cuando el grupo en su conjunto deba recuperar el acceso. Si solo se debe eliminar un miembro mientras el grupo permanece autorizado, confíe en la caducidad del token o utilice una política de reautenticación y duración de token de acceso más corta específica del despliegue.

Consulte Gestión de autorización mediante la API y la tabla de caducidad de token de OCI IAM, junto con las referencias de ciclo de vida de contexto de seguridad de Deep Sec anteriores.