Deep Data Security

Oracle Agent Memory 與 Oracle Deep Data Security (Deep Sec) 整合，在 Oracle AI Database 內強制執行一般使用者授權。Deep Sec 是一項安全功能：其資料角色、資料授予和一般使用者安全相關資訊環境決定要求可讀取或修改的受管理記憶體資料列。

重要事項：將此頁面上的 API 視為安全管理和要求安全介面。針對原則管理、受管理綱要擁有權以及程式實際執行連線集區使用個別的資料庫識別。程式實際執行集區帳戶不應有提供受保護「代理程式記憶體」表格後援存取權的直接權限。

Oracle 的深資料安全總覽描述資料庫授權模型。如需完整的 OCI IAM 部署，請參閱使用深資料安全性強制執行一般使用者記憶體隔離。

安全性模型

「代理程式記憶體」整合支援兩個原則：

保單 有效的存取
UserOwnRowsDeepDataSecurityPolicy 只有當使用者的擁有者符合 ORA_END_USER_CONTEXT.username 時，才能讀取和寫入使用者作用領域的「代理程式記憶體」資料列。記憶體連結讀取需要兩個端點記憶體才能在指派的原則下讀取；連結寫入需要兩個端點記憶體屬於該使用者。
GlobalMemoriesDeepDataSecurityPolicy 讀取 user_id 為 NULL 的未作用領域記憶體資料列。此原則不會授予寫入或存取其他使用者的作用領域記憶體。當兩個端點記憶體都可在作用中原則下讀取時，便會公開記憶體連結。如果只有這個原則，兩個端點都必須是全域記憶體；如果與自己的資料列原則結合，則也可看到自有記憶體與全域記憶體之間的連結。

原則物件是管理 API 的不通透選擇項目。它們的受管理表格、資料角色、資料授予以及 SQL 實行保持私密，因此 Oracle Agent Memory 可以安全地發展其資料庫綱要。不支援自訂原則子類別；請使用上述兩個原則類別中的其中一個。

政策的範圍為 owner_schema 與 memory_store_id 的組合。建立或指派一個存放區的原則並不會將它指派給其他存放區，包括在不同擁有者綱要中具有相同 ID 的存放區。

UserOwnRowsDeepDataSecurityPolicy 原則也會依資料欄限制寫入。一般使用者可以在插入擁有的資料列時設定識別和擁有權資料欄，但之後無法變更這些資料欄。原則會授予下列寫入曲面：

UserOwnRowsDeepDataSecurityPolicy 的資料欄層次寫入權限

受管理的表格 可插入的欄 可更新資料欄
執行緒 record_id, user_id, agent_id, metadata, runtime_config, runtime_state metadata, runtime_config, runtime_state
繫線摘要 record_id, thread_id, user_id, agent_id, space_id, content, metadata, status content, metadata, status
訊息 record_id, thread_id, user_id, agent_id, message_role, content, timestamp, metadata, expires_at, status content, timestamp, metadata, expires_at
文件 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
記憶體 record_id, thread_id, user_id, agent_id, memory_type, content, timestamp, metadata, expires_at, status content, timestamp, metadata, expires_at, status
記憶體連結 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
使用者動作者設定檔 actor_id, actor_type, information, metadata, status information, metadata
記錄區塊 當儲存保存向量時，source_id、source_record_type、source_emb_column、chunk_seq、chunk_text、thread_id、user_id、agent_id、status 及 embedding status

SELECT 和 DELETE 保持資料列作用領域。一般使用者無法插入或更新產生的、建立時間和保留的資料欄 (例如 chunk_id、created_at 和 order_seq)，除非在上面明確列出。資料庫也會檢查插入的資料列述詞，因此將 user_id 列為可插入，不允許一般使用者建立其他識別所擁有的資料列。當 UPDATE 在授予其他資料欄之 UPDATE 的表格上針對不可更新的資料欄時，Deep Sec 可以安靜地讓資料列維持不變，而不是發出錯誤。記錄區塊僅允許 status 更新。SDK 將區塊識別、文字和內嵌值的變更取代為刪除和插入作業。應用程式應使用 SDK 支援的變化方法，且不得單獨將直接 SQL 執行視為受保護值的變更證明。

以下列順序使用管理 API：

  1. 建立受管理「代理程式記憶體」存放區作為其綱要擁有者。
  2. 以安全管理員身分呼叫 add_deep_data_security_policies()。
  3. 為每個授權的 OCI IAM 群組或本機 Deep Sec 一般使用者呼叫 grant_agent_memory_policies()。
  4. 在程式實際執行時，包裝 OracleMemoryEndUserSecurityContext 中的每個「代理程式記憶體」作業。
  5. 移除不再需要的原則之前，請先撤銷指定項目。

如果執行時期作業使用 OracleDBEmbedder 搭配預設 provider="database"，且模型儲存在 Oracle AI Database 中 (通常是 ONNX 模型)，則上述原則授予僅授權「代理程式記憶體」表格。IAM 群組的對應資料角色也必須具備資料庫常駐模型的存取權。設定存取 (如使用含深度的資料庫內內嵌模型中所述) 後，再提供要求服務。

OracleDBEmbedder 也可以透過 DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING 使用遠端提供者。該組態不使用資料庫常駐模型，不需要 SELECT ON MINING MODEL。分別設定遠端提供者的 Oracle 證明資料和網路存取。「代理程式記憶體」作業仍必須在 OracleMemoryEndUserSecurityContext 內部執行。

管理呼叫會在傳回之前確認其資料庫變更。如需基本角色和授予概念，請參閱 Oracle 的資料存取控制組態。

內容使用檢查

在受保護的應用程式工作執行之前，SDK 會拒絕不安全的組合：

這些檢查會診斷不正確的 SDK 執行路徑。Oracle AI Database 資料授權保持授權界限，並繼續確定認證的一般使用者可以存取哪些資料列和資料欄。

保單

類別 oracleagentmemory.core.deepsec.DeepDataSecurityPolicy

基礎：object

識別支援的 Oracle Agent Memory Deep Data Security 原則。

原則物件是傳送給「Deep Data Security」管理功能的不透明選擇項目。建立 UserOwnRowsDeepDataSecurityPolicy 或 GlobalMemoriesDeepDataSecurityPolicy。原則實行詳細資訊 (包括受管理表格、資料角色、資料授予以及 SQL) 仍為 Oracle 代理程式記憶體的專用詳細資訊，而且版本之間可能會有所變更。

此類別不是自訂原則擴充點。管理功能會拒絕 Oracle Agent Memory 提供之兩個原則類別以外的子類別。

範例

建立一般使用者資料列和未作用領域全域記憶體的原則集：

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

類別 oracleagentmemory.core.deepsec.UserOwnRowsDeepDataSecurityPolicy

基本：DeepDataSecurityPolicy

授予已認證一般使用者擁有之資料列的存取權。

此原則會授予資料列範圍 SELECT、資料欄範圍 INSERT 和 UPDATE，以及使用者擁有的資料列範圍 DELETE。插入後即無法變更所有權、記錄類型、產生、建立時間及保留資料欄。記錄區塊可以插入和刪除，但無法更新，因為 SDK 將它們取代為完整資料列。此原則也會授與初始化程式實際執行存放區所需的登錄讀取。記憶體連結 SELECT 遵循共用端點可見性規則，而連結 INSERT、UPDATE 和 DELETE 則需要兩個端點記憶體都屬於一般使用者。

範例

policy = UserOwnRowsDeepDataSecurityPolicy()

類別 oracleagentmemory.core.deepsec.GlobalMemoriesDeepDataSecurityPolicy

基本：DeepDataSecurityPolicy

授予全域記憶體的讀取存取權，以及可見記憶體之間的連結。

此原則會針對 user_id 為 NULL 的記憶體資料列授與 SELECT，並授與初始化程式實際執行存放區所需的登錄讀取。當終端使用者可根據指派的 Deep Data Security 原則讀取兩個端點記憶體時，其記憶體連結讀取授權就會公開連結。只要使用此原則，兩個端點都必須是全域記憶體；再結合自己的資料列原則，也可看到自有記憶體與全域記憶體之間的連結。它不允許寫入或存取其他使用者的作用領域記憶體。

範例

policy = GlobalMemoriesDeepDataSecurityPolicy()

主要項目

指派目標可能是存取記號之 group 自訂宣告中包含的 OCI IAM 群組，或是本機 Deep Sec 一般使用者。必須先將 OCI IAM 群組資訊設定為自訂宣告，Oracle AI Database 才能將其對應至外部資料角色。請參閱在 OCI IAM 中設定群組資訊的自訂宣告。

類別 oracleagentmemory.core.deepsec.Principal

基礎：object

識別誰收到「代理程式記憶體」原則指定的基本類型。

主體為以 grant_agent_memory_policies() 或 revoke_agent_memory_policies() 為目標的安全識別。主要項目會識別受權者，其「深資料安全性」資料角色或資料會授予控制特定「代理程式記憶體」存放區之存取權限的權限。目前支援的主要類型包括 OCI IAM 群組和本機資料庫一般使用者。

對 OCI IAM 群組使用 OciGroupPrincipal，對資料庫管理的 Deep Data Security 一般使用者使用 LocalEndUserPrincipal。不支援將直接 Principal 執行處理傳送至管理功能。

類別 oracleagentmemory.core.deepsec.OciGroupPrincipal

基本：Principal

識別接收代理程式記憶體原則的 OCI IAM 群組。

類別 oracleagentmemory.core.deepsec.LocalEndUserPrincipal

基本：Principal

識別本機 Deep Data Security 一般使用者接收原則。

管理

透過專用的安全管理連線執行這些功能。對於跨綱要「代理程式記憶體」表格，該帳戶需要適用的「深層安全」管理權限 (包括 CREATE ANY DATA GRANT、DROP ANY DATA GRANT 和 ADMINISTER ANY DATA GRANT)，以及建立和刪除資料角色的權限。請勿將這些權限授與程式實際執行集區帳戶。

oracleagentmemory.core.deepsec.add_deep_data_security_policies

建立「代理程式記憶體」原則的資料角色和資料授權。

原則的範圍為一個 owner_schema 和 memory_store_id。若新增，會對受保護的受管理表格強制實行深層資料安全。重新新增原則會取代其「代理程式記憶體」管理的資料角色，並以目前的定義授權。重複的呼叫是等冪的。如果 Oracle 在中斷前確認部分原則 DDL，則重試相同的呼叫會修復受管理定義。

此函數會在傳回前確認連線。使用專用安全管理連線，而非綱要擁有者或程式實際執行應用程式連線。

範例

新增自有資料列和全域記憶體存取原則：

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

移除代理程式記憶體深資料安全性原則。

刪除原則角色也會從其資料授權和本機一般使用者指派項目中移除該角色。建立為外部資料授權的 OCI IAM 指定項目必須先移除 revoke_agent_memory_policies()。只有在該表格上沒有資料授予時，才會停用受管理表格的必要資料授予強制實行。

此函數會在傳回前確認連線。

範例

移除自己的資料列原則：

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

列出目前在 Oracle AI Database 中建立的代理程式記憶體原則。

範例

檢查設定的原則類型：

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

將代理程式記憶體原則授予 OCI IAM 群組或本機一般使用者。

OCI IAM 群組是以外部對應的資料角色表示。Oracle AI Database 不允許外部對應的資料角色接收本機管理的資料角色，因此每個原則的資料授權會直接附加至該對應角色。

先使用 add_deep_data_security_policies() 為目標存放區建立每個原則，再加以指派。此函數會在傳回前確認連線。重複的呼叫是等冪的。如果 Oracle 在中斷前確認部分 OCI IAM 指派，則重試相同的呼叫會重新建立遺漏的受管理資料授權。

範例

授予 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

撤銷 OCI IAM 群組或本機一般使用者的代理程式記憶體原則。

主體本身會被保留。特別是，OCI IAM 群組的外部對應資料角色仍可供此或其他「代理程式記憶體」存放區的指派使用。

撤銷會變更資料庫原則狀態並在傳回前確認，因此後續受保護的資料庫敘述句不會再收到撤銷的原則。這與從 OCI IAM 群組移除使用者不同：已核發的存取權杖會保留其內嵌群組宣告，直到該權杖到期為止。

範例

撤銷 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

列出指派給每個主要項目的主要項目和代理程式記憶體原則。

範例

列出原則指定：

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

程式實際執行安全相關資訊環境

OracleMemoryEndUserSecurityContext 會將 python-oracledb 安全相關資訊環境範圍複製到「代理程式記憶體」作業。相關資訊環境包含一般使用者記號和資料庫存取記號；Oracle AI Database 會驗證它們，並從其宣告衍生作用中資料角色。SDK 會將相關資訊環境連附至每個取得的實體連線，然後先將其清除，再將該連線傳回集區。

請參閱 Oracle 的一般使用者安全相關資訊環境瞭解安全模型，以及資料庫伺服器如何管理一般使用者安全相關資訊環境，瞭解驗證、角色解析、連線重複使用以及相關資訊環境清除。

類別 oracleagentmemory.core.deepsec.OracleMemoryEndUserSecurityContext

基礎：object

將 Oracle 一般使用者安全相關資訊環境套用至「代理程式記憶體」作業。

輸入此相關資訊環境管理程式可讓目前執行相關資訊環境中使用的 Oracle 備份「代理程式記憶體」存放區使用 security_context。每個資料庫作業都會在取得其實體連線之後套用相關資訊環境、驗證一般使用者識別是否作用中，並在釋出連線之前清除相關資訊環境。此行為同時適用於直接連線集區和連線集區。

範圍會傳輸至等待中的非同步「代理程式記憶體」呼叫。with 或 async with 區塊之外的呼叫程式作業無法使用過期的範圍。區塊內部接受的背景記憶體擷取工作會保留專用快照，讓它們在區塊結束後即可完成。

當一般使用者或資料庫存取記號變更時，請使用全新的 oracledb.EndUserSecurityContext。Oracle AI Database 會從提供之權杖中的宣告衍生已啟用的資料角色；此管理程式不會重新整理、撤銷或檢查 OAuth 權杖。

備註

此類別範圍包括 Oracle 代理程式記憶體作業。它不會修改 SDK 外部應用程式 SQL 直接使用的任意連線。支援巢狀，包括巢狀相同的管理程式執行處理；每個結束項目都會從其相符的項目回復相關資訊環境。

範例

將 OAuth 衍生的相關資訊環境套用至同步「代理程式記憶體」作業：

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

相同的管理程式支援非同步呼叫：

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

方法 __aenter__ (非同步)

輸入「等待的代理程式記憶體」作業的範圍。

方法 __aexit__ (非同步)

結束非同步範圍，但不抑制區塊異常狀況。

方法 __enter__

輸入範圍並傳回此環境定義管理程式。

在目前執行相關資訊環境中啟動的「代理程式記憶體」作業會使用此管理程式的一般使用者安全相關資訊環境，直到符合結束為止。

方法 __exit__

結束範圍並防止繼承的來電者工作重複使用。

受管理區塊的任何異常狀況都會以未變更的方式傳輸。

oracleagentmemory.core.deepsec.get_end_user_username

傳回連附至 Oracle DB 連線的一般使用者使用者名稱。

Deep Data Security 會使用附加至資料庫連線的一般使用者安全相關資訊環境評估資料授權。此協助程式會從該相關資訊環境讀取 username 屬性。它不會傳回用來建立實體連線的資料庫帳戶。

範例

檢查連線是否有連附的一般使用者識別：

get_end_user_username(conn) is None
True

稽核

Deep Sec 使用 Oracle AI Database Unified Auditing。資料庫管理員可以為 Deep Sec 組態作業建立統一稽核原則，例如建立或刪除資料角色和資料授予、授予或撤銷資料角色，以及建立或刪除一般使用者和一般使用者相關資訊環境。稽核記錄可透過 UNIFIED_AUDIT_TRAIL 取得，而且可以包含一般使用者安全相關資訊環境下執行之活動的一般使用者識別和安全相關資訊環境 ID。

CREATE END USER SECURITY CONTEXT 動作會記錄建立安全相關資訊環境。Oracle 請注意，它可以產生許多記錄，而且不包括在 ACTIONS ALL 中；請明確指定必須稽核該生命週期事件的時間。根據部署的安全和規範需求，選取稽核動作和保留。SDK 應用程式日誌為診斷日誌，不會取代資料庫稽核歷程檔。

請參閱稽核 Oracle Deep Data Security Operations 和深層安全可稽核動作的正式清單。

撤銷時間合約

資料庫原則撤銷和 OCI IAM 群組成員移除的有效時間不同：

管理作業 生效時間
致電 revoke_agent_memory_policies() 此函數會先移除存放區特定的資料庫指派，然後再傳回確認。後續的受保護資料庫敘述句不會再收到該原則。已執行的對帳單不會追溯取消。
移除 OCI IAM 中受權者群組的使用者 新發行的存取權杖反映更新的成員身分。已經發出給使用者的存取權杖仍然包含其 group 宣告，而且可以繼續授權對應的深層安全資料角色，直到該權杖到期為止。

因此，只撤銷 IAM 的有效上限，就是發出之記號的 exp 宣告中其餘的存留時間。OCI IAM 存取權杖存留時間可供設定；若未設定資源應用程式、使用者階段作業或自訂到期，文件的預設值為 3600 秒。應用程式必須停止重複使用已過期的權杖，並且取得宣告反映目前成員身分的新權杖。

若要進行緊急撤銷，請先呼叫 revoke_agent_memory_policies()，立即移除後續敘述句的資料庫指定，然後移除 OCI IAM 群組中的使用者。只有當整個群組應重新獲得存取權時，才重新授予資料庫原則。如果在群組保持授權時，僅必須移除一個成員，請依賴記號到期，或使用部署特定的短期存取記號存留時間和重新認證原則。

請參閱 OCI IAM 的使用 API 管理授權和權杖到期表格，以及上述的安全相關資訊環境生命週期參照。