Deep Data Security

O Oracle Agent Memory se integra ao Oracle Deep Data Security (Deep Sec) para impor a autorização do usuário final dentro do Oracle AI Database. Deep Sec é um recurso de segurança: suas atribuições de dados, concessões de dados e contextos de segurança de usuário final determinam quais linhas de memória gerenciada uma solicitação pode ler ou modificar.

Importante: Trate as APIs nesta página como interfaces de segurança-administração e de segurança de solicitação. Use identidades de banco de dados separadas para administração de políticas, propriedade de esquema gerenciado e pool de conexões de runtime. A conta do pool de runtime não deve ter privilégios diretos que forneçam acesso de fallback às tabelas protegidas da Memória do Agente.

A visão geral do Deep Data Security da Oracle descreve o modelo de autorização do banco de dados. Para obter uma implantação completa do OCI IAM, consulte Impor o isolamento da memória do usuário final com o Deep Data Security.

Modelo de segurança

A integração da Memória do Agente suporta duas políticas:

Política Acesso efetivo
UserOwnRowsDeepDataSecurityPolicy Leia e grave linhas da Memória do Agente com escopo do usuário somente quando o proprietário corresponder a ORA_END_USER_CONTEXT.username. As leituras de link de memória exigem que ambas as memórias de ponto final sejam legíveis de acordo com as políticas designadas; as gravações de link exigem que ambas as memórias de ponto final pertençam a esse usuário.
GlobalMemoriesDeepDataSecurityPolicy Leia linhas de memória sem escopo cujo user_id é NULL. Esta política não concede gravações ou acesso a memórias com escopo de outro usuário. Ele expõe um link de memória quando ambas as memórias de ponto final são legíveis de acordo com as políticas ativas. Com apenas esta política, ambos os endpoints devem ser memórias globais; quando combinados com a política de linha própria, os links entre uma memória própria e uma memória global também são visíveis.

Os objetos de política são seleções opacas para as APIs de administração. Suas implementações de tabela gerenciada, atribuição de dados, concessão de dados e SQL permanecem privadas para que o Oracle Agent Memory possa evoluir seu esquema de banco de dados com segurança. Não há suporte para subclasses de política personalizadas. Use uma das duas classes de política acima.

As políticas têm como escopo a combinação de owner_schema e memory_store_id. A criação ou designação de uma política para uma loja não a atribui a outra loja, incluindo uma loja com o mesmo ID em um esquema de proprietário diferente.

A política UserOwnRowsDeepDataSecurityPolicy também limita as gravações por coluna. Os usuários finais podem definir colunas de identidade e propriedade ao inserir uma linha própria, mas não podem alterar essas colunas posteriormente. A política concede a seguinte superfície de gravação:

Permissões de gravação no nível da coluna para UserOwnRowsDeepDataSecurityPolicy

Tabela gerenciada Colunas inseríveis Colunas atualizáveis
Thread record_id, user_id, agent_id, metadata, runtime_config, runtime_state metadata, runtime_config, runtime_state
Resumo do tópico record_id, thread_id, user_id, agent_id, space_id, content, metadata, status content, metadata, status
Mensagem 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
Memória record_id, thread_id, user_id, agent_id, memory_type, content, timestamp, metadata, expires_at, status content, timestamp, metadata, expires_at, status
Link de memória 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 do ator do usuário actor_id, actor_type, information, metadata, status information, metadata
Gravar blocos source_id, source_record_type, source_emb_column, chunk_seq, chunk_text, thread_id, user_id, agent_id, status e embedding quando o armazenamento persistir vetores status

Os campos SELECT e DELETE permanecem no escopo da linha. As colunas geradas, em tempo de criação e reservadas, como chunk_id, created_at e order_seq, não podem ser inseridas ou atualizadas pelos usuários finais, a menos que sejam listadas explicitamente acima. O banco de dados também verifica se há inserções no predicado de linha; portanto, listar user_id como inserível não permite que um usuário final crie uma linha pertencente a outra identidade. Quando um UPDATE direciona uma coluna não atualizável em uma tabela que concede UPDATE em outras colunas, o Deep Sec pode deixar silenciosamente a linha inalterada em vez de gerar um erro. Os chunks de registro permitem apenas atualizações de status. O SDK substitui as alterações na identidade do chunk, no texto e nos valores de incorporação por operações de exclusão e inserção. Os aplicativos devem usar os métodos de mutação suportados pelo SDK e não devem tratar a execução direta de SQL sozinha como prova de que um valor protegido foi alterado.

Use as APIs de administração nesta ordem:

  1. Crie o armazenamento de Memória do Agente gerenciado como proprietário do esquema.
  2. Chame add_deep_data_security_policies() como administrador de segurança.
  3. Chame grant_agent_memory_policies() para cada grupo autorizado de IAM do OCI ou usuário final local de Deep Sec.
  4. No runtime, encapsule todas as operações de Memória do Agente em OracleMemoryEndUserSecurityContext.
  5. Revogue as atribuições antes de remover as políticas que não são mais necessárias.

Se as operações de runtime usarem OracleDBEmbedder com o provider="database" padrão e um modelo armazenado no Oracle AI Database, geralmente um modelo ONNX, as concessões de política acima autorizarão somente as tabelas de Memória do Agente. A atribuição de dados mapeada do grupo do IAM também deve ter acesso ao modelo de banco de dados residente. Configure esse acesso conforme descrito em Use um modelo de incorporação no banco de dados com Deep Sec antes de atender às solicitações.

O OracleDBEmbedder também pode usar um provedor remoto por meio do DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING. Essa configuração não usa um modelo de banco de dados residente e não requer SELECT ON MINING MODEL. Configure a credencial Oracle do provedor remoto e o acesso à rede separadamente. A operação Memória do Agente ainda deve ser executada dentro de OracleMemoryEndUserSecurityContext.

As chamadas de administração confirmam suas alterações no banco de dados antes de retornar. Para obter a atribuição subjacente e os conceitos de concessão, consulte a Configuração do Controle de Acesso a Dados da Oracle.

Verificações de uso do contexto

O SDK rejeita combinações inseguras antes de execuções de trabalho de aplicativos protegidos:

Essas verificações diagnosticam um caminho de execução SDK incorreto. As concessões de dados do Oracle AI Database permanecem o limite de autorização e continuam a determinar quais linhas e colunas um usuário final autenticado pode acessar.

Políticas

classe oracleagentmemory.core.deepsec.DeepDataSecurityPolicy

Bases: object

Identifique uma política de Segurança de Dados Profundos de Memória do Oracle Agent suportada.

Os objetos de política são seleções opacas transmitidas às funções de administração do Deep Data Security. Instancie UserOwnRowsDeepDataSecurityPolicy ou GlobalMemoriesDeepDataSecurityPolicy. Os detalhes de implementação da política, incluindo tabelas gerenciadas, atribuições de dados, concessões de dados e SQL, permanecem privados para a Memória do Agente da Oracle e podem mudar entre as releases.

Esta classe não é um ponto de extensão de política personalizada. Subclasses diferentes das duas classes de política fornecidas pela Memória do Agente Oracle são rejeitadas pelas funções de administração.

Exemplos

Crie o conjunto de políticas para linhas de usuário final e memórias globais sem escopo:

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

classe oracleagentmemory.core.deepsec.UserOwnRowsDeepDataSecurityPolicy

Bases: DeepDataSecurityPolicy

Conceder acesso a linhas pertencentes ao usuário final autenticado.

Esta política concede SELECT com escopo de linha, INSERT com escopo de coluna e UPDATE com escopo de linha e DELETE com escopo de linha em dados de propriedade do usuário. As colunas Propriedade, tipo de registro, gerado, tempo de criação e reservado não podem ser alteradas após a inserção. Os blocos de registro podem ser inseridos e excluídos, mas não podem ser atualizados porque o SDK os substitui como linhas completas. A política também concede a leitura de registro necessária para inicializar um armazenamento de runtime. O link de memória SELECT segue a regra de visibilidade de ponto final compartilhado, enquanto os links INSERT, UPDATE e DELETE exigem que ambas as memórias de ponto final pertençam ao usuário final.

Exemplos

policy = UserOwnRowsDeepDataSecurityPolicy()

classe oracleagentmemory.core.deepsec.GlobalMemoriesDeepDataSecurityPolicy

Bases: DeepDataSecurityPolicy

Conceder acesso de leitura a memórias globais e ligações entre memórias visíveis.

Esta política concede SELECT nas linhas da memória cujo user_id é NULL e concede a leitura do registro necessária para inicializar um armazenamento de runtime. Sua concessão de leitura de link de memória expõe um link quando ambas as memórias de ponto final são legíveis pelo usuário final de acordo com as políticas de Deep Data Security designadas. Com apenas esta política, ambos os endpoints devem, portanto, ser memórias globais; combinado com a política de linha própria, um link entre uma memória própria e uma memória global também é visível. Ele não permite gravações ou acesso a memórias com escopo de outro usuário.

Exemplos

policy = GlobalMemoriesDeepDataSecurityPolicy()

Principais

Uma designação tem como alvo um grupo do OCI IAM transportado na reivindicação personalizada group do token de acesso ou um usuário final local de Deep Sec. As informações do grupo do OCI IAM devem ser configuradas como uma reivindicação personalizada para que o Oracle AI Database possa mapeá-las para uma atribuição de dados externa. Consulte Configurar Reivindicações Personalizadas para Informações de Grupo no OCI IAM.

classe oracleagentmemory.core.deepsec.Principal

Bases: object

Tipo base que identifica quem recebe as atribuições da política de Memória do Agente.

Os principais são as identidades de segurança direcionadas por grant_agent_memory_policies() ou revoke_agent_memory_policies(). O principal identifica o favorecido cujas atribuições de dados de Segurança de Dados Profunda ou dados concedem acesso de controle a um armazenamento de Memória do Agente específico. Os tipos principais atuais suportados são grupos do OCI IAM e usuários finais do banco de dados local.

Use OciGroupPrincipal para um grupo do OCI IAM ou LocalEndUserPrincipal para um usuário final do Deep Data Security gerenciado pelo banco de dados. Não há suporte para a transmissão de uma instância direta do Principal a uma função de administração.

classe oracleagentmemory.core.deepsec.OciGroupPrincipal

Bases: Principal

Identificar um grupo do OCI IAM que recebe políticas de Memória do Agente.

classe oracleagentmemory.core.deepsec.LocalEndUserPrincipal

Bases: Principal

Identificar políticas de recebimento de usuários finais locais do Deep Data Security.

Administração

Execute essas funções por meio de uma conexão de administração de segurança dedicada. Para tabelas de Memória do Agente entre esquemas, essa conta precisa dos privilégios de administração de Deep Sec aplicáveis, incluindo CREATE ANY DATA GRANT, DROP ANY DATA GRANT e ADMINISTER ANY DATA GRANT, além de autoridade para criar e eliminar atribuições de dados. Não dê esses privilégios à conta de pool de runtime.

oracleagentmemory.core.deepsec.add_deep_data_security_policies

Crie as atribuições de dados e as concessões de dados para políticas de Memória do Agente.

As políticas têm como escopo um owner_schema e um memory_store_id. A adição deles permite a imposição obrigatória do Deep Data Security em suas tabelas gerenciadas protegidas. A readição de uma política substitui a atribuição de dados gerenciada pela Memória do Agente e concede a definição atual. Chamadas repetidas são idempotentes. Se o sistema Oracle fizer commit de parte do DDL da política antes de uma interrupção, a repetição da mesma chamada reparará as definições gerenciadas.

Esta função confirma a conexão antes de retornar. Use uma conexão de administração de segurança dedicada em vez de uma conexão de aplicativo de proprietário de esquema ou runtime.

Exemplos

Adicione políticas de acesso de linha própria e de memória 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

Remova as políticas do Agent Memory Deep Data Security.

A eliminação de uma atribuição de política também remove essa atribuição de suas concessões de dados e atribuições de usuário final local. As designações do OCI IAM criadas como concessões de dados externos devem ser removidas primeiro com revoke_agent_memory_policies(). A imposição obrigatória da concessão de dados é desativada para uma tabela gerenciada somente quando nenhuma concessão de dados permanece nessa tabela.

Esta função confirma a conexão antes de retornar.

Exemplos

Remova a política de linha própria:

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

Listar políticas de Memória do Agente criadas no momento no Oracle AI Database.

Exemplos

Inspecionar tipos de política configurados:

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

Conceder políticas de Memória do Agente a grupos do OCI IAM ou usuários finais locais.

Os grupos do OCI IAM são representados por atribuições de dados mapeadas externamente. As concessões de dados para cada política são anexadas diretamente a essa atribuição mapeada porque o Oracle AI Database não permite que atribuições de dados mapeadas externamente recebam atribuições de dados gerenciadas localmente.

Crie cada política para o armazenamento de destino com add_deep_data_security_policies() antes de designá-la. Esta função confirma a conexão antes de retornar. Chamadas repetidas são idempotentes. Se a Oracle fizer commit de parte de uma designação do OCI IAM antes de uma interrupção, a repetição da mesma chamada recriará as concessões de dados gerenciados ausentes.

Exemplos

Conceder acesso de linha própria a um grupo do 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

Revogar políticas de Memória do Agente de grupos do OCI IAM ou usuários finais locais.

O principal é preservado. Especificamente, a atribuição de dados mapeada externamente de um grupo do OCI IAM permanece disponível para atribuições deste ou de outro armazenamento da Memória do Agente.

A revogação altera o estado e os commits da política do banco de dados antes de retornar; portanto, as declarações subsequentes do banco de dados protegido não recebem mais a política revogada. Isso é diferente de remover um usuário de um grupo do OCI IAM: um token de acesso já emitido mantém sua reivindicação de grupo incorporado até que esse token expire.

Exemplos

Revogar o acesso de linha própria de um grupo do 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

Listar principais e políticas de Memória do Agente designadas a cada principal.

Exemplos

Listar designações de política:

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

Contexto de segurança de runtime

OracleMemoryEndUserSecurityContext faz o escopo do contexto de segurança python-oracledb para as operações de Memória do Agente. O contexto carrega o token de usuário final e o token de acesso ao banco de dados; o Oracle AI Database os valida e deriva atribuições de dados ativas de suas reivindicações. O SDK anexa o contexto a cada conexão física adquirida e o limpa antes de retornar essa conexão ao pool.

Consulte o Contexto de Segurança do Usuário Final da Oracle para obter o modelo de segurança e Como o Servidor de Banco de Dados Gerencia um Contexto de Segurança do Usuário Final para validação, resolução de atribuição, reutilização de conexão e limpeza de contexto.

classe oracleagentmemory.core.deepsec.OracleMemoryEndUserSecurityContext

Bases: object

Aplique um contexto de segurança de usuário final da Oracle às operações de Memória do Agente.

A entrada desse gerenciador de contexto torna security_context disponível para armazenamentos de Memória do Agente suportados pela Oracle usados no contexto de execução atual. Cada operação do banco de dados aplica o contexto após a aquisição de sua conexão física, verifica se uma identidade de usuário final está ativa e limpa o contexto antes de liberar a conexão. Este comportamento funciona com conexões diretas e pools de conexões.

O escopo se propaga para chamadas de Memória do Agente assíncronas aguardadas. As tarefas do chamador que sobrevivem ao bloco with ou async with não podem usar o escopo expirado. Os jobs de extração de memória em segundo plano aceitos dentro do bloco retêm um snapshot privado para que eles possam ser concluídos após a saída do bloco.

Use um novo oracledb.EndUserSecurityContext quando o token do usuário final ou do acesso ao banco de dados for alterado. O Oracle AI Database deriva as atribuições de dados ativadas das reivindicações no token fornecido; esse gerente não atualiza, revoga ou inspeciona tokens OAuth.

Observações

Esta classe faz o escopo das operações de Memória do Agente Oracle. Ele não modifica uma conexão arbitrária usada diretamente pelo SQL do aplicativo fora do SDK. O aninhamento é suportado, incluindo o aninhamento da mesma instância do gerente; cada saída restaura o contexto de sua entrada correspondente.

Exemplos

Aplicar um contexto derivado do OAuth a operações síncronas da Memória do 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",
    )

O mesmo gerenciador suporta chamadas assíncronas:

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

método __aenter__ (assíncrono)

Informe o escopo das operações de Memória do Agente aguardadas.

método __aexit__ (assíncrono)

Saia do escopo assíncrono sem suprimir exceções de bloco.

método __enter__

Insira o escopo e retorne este gerenciador de contexto.

As operações de Memória do Agente iniciadas no contexto de execução atual usam o contexto de segurança do usuário final deste gerenciador até a saída correspondente.

método __exit__

Saia do escopo e impeça que as tarefas herdadas do chamador as reutilizem.

Qualquer exceção do bloco gerenciado é propagada inalterada.

oracleagentmemory.core.deepsec.get_end_user_username

Retorna o nome de usuário final anexado a uma conexão do Oracle DB.

A Deep Data Security avalia as concessões de dados usando o contexto de segurança do usuário final anexado a uma conexão de banco de dados. Este auxiliar lê o atributo username desse contexto. Ele não retorna a conta de banco de dados usada para estabelecer a conexão física.

Exemplos

Verifique se uma conexão tem uma identidade de usuário final anexada:

get_end_user_username(conn) is None
True

Auditoria

A Deep Sec usa o Oracle AI Database Unified Auditing. Um administrador de banco de dados pode criar políticas de auditoria unificadas para operações de configuração de Deep Sec, como criar ou eliminar atribuições de dados e concessões de dados, conceder ou revogar atribuições de dados e criar ou eliminar usuários finais e contextos de usuário final. Os registros de auditoria estão disponíveis por meio do UNIFIED_AUDIT_TRAIL e podem incluir a identidade do usuário final e o identificador de contexto de segurança para a atividade executada em um contexto de segurança do usuário final.

A ação CREATE END USER SECURITY CONTEXT registra a criação de contexto de segurança. A Oracle observa que pode gerar muitos registros e não é incluída por ACTIONS ALL; especifique-a explicitamente quando esse evento de ciclo de vida deve ser auditado. Selecione ações de auditoria e retenção de acordo com os requisitos de segurança e conformidade da implantação. Os logs do aplicativo SDK são de diagnóstico e não substituem a trilha de auditoria do banco de dados.

Consulte Auditar Operações de Segurança de Dados Profundos da Oracle e a lista oficial de Ações Auditáveis de Segurança Profunda.

Contrato de tempo de revogação

A revogação da política de banco de dados e a remoção de associação em grupo do OCI IAM têm tempos efetivos diferentes:

Ação administrativa Ocupação efetiva
Ligue para revoke_agent_memory_policies() A função remove a atribuição do banco de dados específico do armazenamento e faz commit antes de retornar. As instruções de banco de dados protegido subsequentes não recebem mais essa política. Um demonstrativo já em execução não é cancelado retroativamente.
Remover um usuário do grupo de favorecidos no OCI IAM Os tokens de acesso recém-emitidos refletem a associação atualizada. Um token de acesso já emitido para o usuário ainda contém sua reivindicação group e pode continuar a autorizar a atribuição de dados de Deep Sec correspondente até que esse token expire.

O limite superior efetivo para revogação somente do IAM é, portanto, o tempo de vida restante na reivindicação exp do token emitido. O tempo de vida útil do token de acesso do OCI IAM é configurável; quando nenhum aplicativo de recurso, sessão de usuário ou expiração personalizada é definido, o padrão documentado é 3600 segundos. Os aplicativos devem parar de reutilizar um token expirado e obter um novo token cujas reivindicações refletem a associação atual.

Para revogação urgente, primeiro chame revoke_agent_memory_policies() para remover a designação do banco de dados imediatamente para instruções subsequentes e, em seguida, remova o usuário do grupo do OCI IAM. Conceda novamente a política de banco de dados somente quando o grupo como um todo tiver que recuperar o acesso. Se apenas um membro precisar ser removido enquanto o grupo permanecer autorizado, confie na expiração do token ou use uma política de tempo de vida e reautenticação de token de acesso mais curta específica da implantação.

Consulte a Gerenciamento de Autorização Usando a API e a Tabela de Expiração de Token do OCI IAM, juntamente com as referências de ciclo de vida de contexto de segurança de Securitização Profunda acima.