16 Oracle Database Vault Rule Set APIs

You can use the DBMS_MACADM PL/SQL package and a set of Oracle Database Vault rule functions to manage rule sets.

• DBMS_MACADM Rule Set Procedures
  The DBMS_MACADM rule set procedures enable you to configure both rule sets and individual rules that go within these rule sets.
• Oracle Database Vault PL/SQL Rule Set Functions
  Oracle Database Vault provides functions to use in rule sets to inspect the SQL statement that the rule set protects.

16.1 DBMS_MACADM Rule Set Procedures

The DBMS_MACADM rule set procedures enable you to configure both rule sets and individual rules that go within these rule sets.

Only users who have been granted the DV_OWNER or DV_ADMIN role can use these procedures.

• ADD_RULE_TO_RULE_SET Procedure
  The ADD_RULE_TO_RULE_SET procedure adds rule to a rule set; you can enable having the rule checked when the rule set is evaluated.
• CREATE_RULE Procedure
  The CREATE_RULE procedure creates both common and local rules, which afterward, can be added to a rule set.
• CREATE_RULE_SET Procedure
  The CREATE_RULE_SET procedure creates a rule set.
• DELETE_RULE Procedure
  The DELETE_RULE procedure deletes a rule.
• DELETE_RULE_FROM_RULE_SET Procedure
  The DELETE_RULE_FROM_RULE_SET procedure deletes a rule from a rule set.
• DELETE_RULE_SET Procedure
  The DELETE_RULE_SET procedure deletes a rule set.
• RENAME_RULE Procedure
  The RENAME_RULE procedure renames a rule and causes the name change to take effect everywhere the rule is used
• RENAME_RULE_SET Procedure
  The RENAME_RULE_SET procedure renames a rule set and causes the name change to take effect everywhere the rule set is used.
• UPDATE_RULE Procedure
  The UPDATE_RULE procedure updates a rule.
• UPDATE_RULE_SET Procedure
  The UPDATE_RULE_SET procedure updates a rule set.

16.1.1 ADD_RULE_TO_RULE_SET Procedure

The ADD_RULE_TO_RULE_SET procedure adds rule to a rule set; you can enable having the rule checked when the rule set is evaluated.

Syntax

DBMS_MACADM.ADD_RULE_TO_RULE_SET(
 rule_set_name  IN VARCHAR2, 
 rule_name      IN VARCHAR2);

Parameters

Table 16-1 ADD_RULE_TO_RULE_SET Parameters

Parameter	Description
rule_set_name	Rule set name. To find existing rule sets in the current database instance, query the DBA_DV_RULE_SET view.
rule_name	Rule to add to the rule set. To find existing rules, query the DBA_DV_RULE view. To find rules that have been associated with rule sets, query DBA_DV_RULE_SET_RULE.

Example

The following example adds a rule to a rule set, and by omitting the enabled parameter, automatically enables the rule to be checked when the rule set is evaluated.

BEGIN
 DBMS_MACADM.ADD_RULE_TO_RULE_SET(
  rule_set_name => 'Limit_DBA_Access', 
  rule_name     => 'Restrict DROP TABLE operations');
END;
/

16.1.2 CREATE_RULE Procedure

The CREATE_RULE procedure creates both common and local rules, which afterward, can be added to a rule set.

Syntax

DBMS_MACADM.CREATE_RULE(
 rule_name  IN VARCHAR2, 
 rule_expr  IN VARCHAR2
 scope      IN NUMBER DEFAULT,
 is_static  IN BOOLEAN DEFAULT FALSE);

Parameters

Table 16-2 CREATE_RULE Parameters

Parameter	Description
rule_name	Rule name, up to 128 characters in mixed-case. Spaces are allowed. Oracle suggests that you start the name with a verb and complete the name with the purpose of the rule. For example: Prevent non-admin access to SQL*Plus. Because rules do not have a description parameter, make the name explicit but be sure to not exceed over 128 characters. To find existing rules in the current database instance, query the DBA_DV_RULE view. To find rules that have been associated with rule sets, query DBA_DV_RULE_SET_RULE.
rule_expr	PL/SQL BOOLEAN expression. It must follow these guidelines: It is valid in a SQL WHERE clause. It can be a freestanding and valid PL/SQL Boolean expression such as the following: TO_CHAR(SYSDATE,'HH24') = '12' It must evaluate to a Boolean (TRUE or FALSE) value. It must be no more than 1024 characters long. If the expression contains quotation marks, do not use double quotation marks. Instead, use two single quotation marks. Enclose the entire expression within single quotation marks. For example: 'TO_CHAR(SYSDATE,''HH24'') = ''12''' It can contain existing and compiled PL/SQL functions from the current database instance. Ensure that these are fully qualified functions (such as schema. function_name). Do not include any other form of SQL statements. Be aware that you cannot use invoker's rights procedures with rule expressions. Doing so will cause the rule evaluation to fail unexpectedly. Only use definer's rights procedures with rule expressions. If you want to use application package functions or standalone functions, you must grant the DVSYS account the EXECUTE privilege on the function. Doing so reduces the chances of errors when you add new rules. Ensure that the rule works. You can test the syntax by running the following statement in SQL*Plus: SELECT rule_expression FROM DUAL; For example, suppose you have created the following the rule expression: SYS_CONTEXT('USERENV','SESSION_USER') != 'TSMITH' You could test this expression as follows: SELECT SYS_CONTEXT('USERENV','SESSION_USER') FROM DUAL; For the Boolean example listed earlier, you would enter the following: SELECT TO_CHAR(SYSDATE,'HH24') FROM DUAL;
scope	Determines how to execute this procedure. If you omit this setting, then it defaults to DBMS_MACUTL.G_SCOPE_LOCAL. DBMS_MACUTL.G_SCOPE_LOCAL (or 1) if the rule is local in the current PDB. (Default) DBMS_MACUTL.G_SCOPE_COMMON (or 2) if the rule is in the application root
is_static	Specifies whether the evaluation of a rule should be static or dynamic. If you omit this setting, then it defaults to FALSE. TRUE evaluates the rule set once during the user session. After that, the value is re-used. FALSE sets the rule to be dynamic. The result of the rule will be evaluated each time the rule is triggered. (Default)

Examples

The following example shows how to create a local rule expression that checks if the current session user is SYSADM. The scope setting is omitted to default it to DBMS_MACUTL.G_SCOPE_LOCAL. The user running this procedure must be in the same PDB in which the rule and its rule set reside. To find the existing PDBs, run the show pdbs command. The rule and rule set must be local.

BEGIN
 DBMS_MACADM.CREATE_RULE(
  rule_name  => 'Check UPDATE operations', 
  rule_expr  =>'SYS_CONTEXT(''USERENV'',''SESSION_USER'') = ''SYSADM''',
  is_static  => TRUE);
END;
/

This example shows a multitenant environment common version of the preceding example. The user running this procedure must be in the CDB root, and the rule and its associated rule set must be common. The rule will reside in the application root.

BEGIN
 DBMS_MACADM.CREATE_RULE(
  rule_name  => 'Check UPDATE operations', 
  rule_expr  =>'SYS_CONTEXT(''USERENV'',''SESSION_USER'') = ''SYSADM''',
  scope      => DBMS_MACUTL.G_SCOPE_COMMON,
  is_static  => TRUE);
END;
/

This example shows how to create a rule expression that uses the public standalone function OLS_LABEL_DOMINATES to find if the session label of the hr_ols_pol Oracle Label Security policy dominates or is equal to the hs label. The value 0 indicates if it is false. (To check if it is equal, you would specify 1.) The scope (default is local) and is_static (default is FALSE) parameters are omitted; their default values will be used.

BEGIN
 DBMS_MACADM.CREATE_RULE(
  rule_name  => 'Check OLS Factor', 
  rule_expr  => 'OLS_LABEL_DOMINATES(''hr_ols_pol'', ''hs'') = 1');
END;
/

16.1.3 CREATE_RULE_SET Procedure

The CREATE_RULE_SET procedure creates a rule set.

After you create a rule set, you can use the CREATE_RULE and ADD_RULE_TO_RULE_SET procedures to create and add rules to the rule set.

Syntax

DBMS_MACADM.CREATE_RULE_SET(
 rule_set_name    IN VARCHAR2, 
 description      IN VARCHAR2 DEFAULT, 
 enabled          IN VARCHAR2 DEFAULT, 
 eval_options     IN NUMBER DEFAULT, 
 audit_options    IN NUMBER DEFAULT, 
 fail_options     IN NUMBER DEFAULT, 
 fail_message     IN VARCHAR2 DEFAULT, 
 fail_code        IN NUMBER DEFAULT, 
 handler_options  IN NUMBER DEFAULT, 
 handler          IN VARCHAR2 DEFAULT,
 is_static        IN BOOLEAN DEFAULT,
 scope            IN NUMBER DEFAULT);

Parameters

Table 16-3 CREATE_RULE_SET Parameters

Parameter	Description
rule_set_name	Rule set name, up to 128 characters in mixed-case. Spaces are allowed. Oracle suggests that you start the name with a verb and complete it with the realm or command rule name to which the rule set is attached. To find existing rule sets in the current database instance, query the DBA_DV_RULE_SET view.
description	Description of the purpose of the rule set, up to 1024 characters in mixed-case. If you omit this setting, then it defaults to an empty string.
enabled	Controls realm checking. If you omit this setting, then it defaults to DBMS_MACUTL.G_YES. DBMS_MACUTL.G_YES (or 'y') enables the rule set. (Default) DBMS_MACUTL.G_NO (or 'n') to disable all realm checking, including the capture of violations in the simulation log
eval_options	For multiple rules being added to a rule set, determines if any or all rules are evaluated. If you omit this setting, then it defaults to DBMS_MACUTL.G_RULESET_EVAL_ALL. DBMS_MACUTL.G_RULESET_EVAL_ALL: All rules in the rule set must evaluate to true for the rule set itself to evaluate to true. (Default) DBMS_MACUTL.G_RULESET_EVAL_ANY: At least one rule in the rule set must evaluate to true for the rule set itself to evaluate to true.
audit_options	Specify DBMS_MACUTL.G_REALM_AUDIT_OFF (or NULL). (Default) Traditional auditing is desupported in Oracle AI Database 26ai. Oracle recommends that you use unified auditing. To audit a rule set, you must use unified auditing. See Oracle AI Database Security Guide for an example of how to create a unified audit policy for a rule set.
fail_options	Determines whether to show or not show errors if the rule set evaluation fails. If you omit this setting, then it defaults to DBMS_MACUTL.G_RULESET_FAIL_SHOW. DBMS_MACUTL.G_RULESET_FAIL_SHOW shows the custom error code and message when the rule set evaluation fails. (Default) DBMS_MACUTL.G_RULESET_FAIL_SILENT does not show the custom error code and message when the rule set evaluation fails. Instead, it uses the default error message. An advantage of selecting DBMS_MACUTL.G_RULESET_FAIL_SILENT and then enabling auditing is that you can track the activities of a potential intruder. The audit report reveals the detailed activities of the intruder, but the intruder only sees a default error message (for example, ORA-01031: insufficient privileges), without knowing why the action failed.
fail_message	Enter an error message for failure, up to 80 characters in mixed-case, to associate with the fail code you specify for fail_code. The default is NULL, which means no custom fail message. If you omit this setting, then it defaults to no custom fail message.
fail_code	Enter a number in the range of -20000 to -20999 or 20000 to 20999 to associate with the fail_message parameter. The default is NULL, which means no fail code. If you omit this setting, then it defaults to no fail code.
handler_options	Controls the behavior of the handler. If you omit this setting, then it defaults to DBMS_MACUTL.G_RULESET_HANDLER_OFF. DBMS_MACUTL.G_RULESET_HANDLER_OFF: Disables error handling. (Default) DBMS_MACUTL.G_RULESET_HANDLER_FAIL: Calls handler on rule set failure DBMS_MACUTL.G_RULESET_HANDLER_SUCCESS: Calls handler on rule set success
handler	Name of the PL/SQL function or procedure that defines the custom event handler logic. If you omit this setting, then it defaults to NULL, which means no handler. You can create a custom event method to provide special processing outside the standard Oracle Database Vault rule set auditing features. For example, you can use an event handler to initiate a workflow process or send event information to an external system. Write the expression as a fully qualified procedure (such as schema.procedure_name). Do not include any other form of SQL statements. If you are using application package procedures or standalone procedures, you must provide DVSYS with the EXECUTE privilege on the object. The procedure signature can be in one of the following two forms: PROCEDURE my_ruleset_handler(p_ruleset_name IN VARCHAR2, p_ruleset_rules IN BOOLEAN): Use this form when the name of the rule set and its return value are required in the handler processing. PROCEDURE my_ruleset_handler: Use this form when the name of the rule set and its return value are not required in the handler processing. Be aware that you cannot use invoker's rights procedures as event handlers. Doing so can cause the rule set evaluation to fail unexpectedly. Only use definer's rights procedures as event handlers. Use the following syntax: my_schema.my_ruleset_handler
is_static	Optional. Determines if the rule set is re-evaluated when it is accessed. If you omit this setting, then it defaults to FALSE. TRUE sets the rule set to be static. When a rule set is specified as static, then the result of the first rule evaluation in a session will be cached and used whenever the rule needs to be evaluated again in the session. FALSE sets the rule set to be dynamic. The result of the rule set will be evaluated each time the rule set is triggered. (Default)
scope	Determines whether the rule set should be common or local. If you omit this setting, then it defaults to DBMS_MACUTL.G_SCOPE_LOCAL. DBMS_MACUTL.G_SCOPE_LOCAL (or 1) if the rule set is to be local in the current PDB. (Default) DBMS_MACUTL.G_SCOPE_COMMON (or 2) if the rule set is to be in the application root

Examples

The following example creates a rule set that is enabled and is set so that at least one rule must evaluate to true for the rule set itself to evaluate to true. The enabled setting is omitted, which defaults the rule set's enablement status to DBMS_MACUTL.G_YES. It shows an error message and uses the fail code 20461 to track failures. It also uses a handler to send email alerts to the appropriate users if their are violations to the rule set.

BEGIN
 DBMS_MACADM.CREATE_RULE_SET(
  rule_set_name    => 'Limit_DBA_Access', 
  description      => 'DBA access through predefined processes', 
  eval_options     => DBMS_MACUTL.G_RULESET_EVAL_ANY,
  audit_options    => DBMS_MACUTL.G_RULESET_AUDIT_OFF,
  fail_options     => DBMS_MACUTL.G_RULESET_FAIL_SILENT,
  fail_message     => 'Configuration failed; check settings',
  fail_code        => 20461,
  handler_options  => DBMS_MACUTL.G_RULESET_HANDLER_FAIL, 
  handler          => 'dbavowner.email_alert',
  is_static        => TRUE);
END;
/

This rule set uses no fail messages or fail codes, nor does it use any handlers. This rule set will be in the application root of a multitenant environment, so the user running this procedure must be in the application root. It has no fail message or fail code, so the fail_message and fail_code settings are omitted. Any rules or command rules that are associated with this rule set must be common.

BEGIN
 DBMS_MACADM.CREATE_RULE_SET(
 rule_set_name    => 'Check_HR_Access', 
 description      => 'Checks for failed access attempts to the HR schema', 
 enabled          => DBMS_MACUTL.G_YES,
 eval_options     => DBMS_MACUTL.G_RULESET_EVAL_ANY,
 audit_options    => DBMS_MACUTL.G_RULESET_AUDIT_OFF,
 fail_options     => DBMS_MACUTL.G_RULESET_FAIL_SILENT,
 is_static        => TRUE,
 scope            => DBMS_MACUTL.G_SCOPE_COMMON);
END;
/

This rule set is a local version of the preceding rule set. The user who creates this rule set must be in the PDB in which this rule set will reside. The fail_message, fail_code, handler_options, and handler settings are omitted because this rule set has no error messages or handler. Any rules or command rules that are associated with this rule set must be local.

BEGIN
 DBMS_MACADM.CREATE_RULE_SET(
 rule_set_name    => 'Check_HR_Access', 
 description      => 'Checks for failed access attempts to the HR schema', 
 enabled          => DBMS_MACUTL.G_YES,
 eval_options     => DBMS_MACUTL.G_RULESET_EVAL_ANY,
 audit_options    => DBMS_MACUTL.G_RULESET_AUDIT_OFF,
 fail_options     => DBMS_MACUTL.G_RULESET_FAIL_SILENT,
 is_static        => TRUE,
 scope            => DBMS_MACUTL.G_SCOPE_LOCAL);
END;
/

16.1.4 DELETE_RULE Procedure

The DELETE_RULE procedure deletes a rule.

Syntax

DBMS_MACADM.DELETE_RULE(
 rule_name IN VARCHAR2); 

Parameter

Table 16-4 DELETE_RULE Parameter

Parameter	Description
rule_name	Rule name. To find existing rules in the current database instance, query the DBA_DV_RULE view. To find rules that have been associated with rule sets, query DBA_DV_RULE_SET_RULE.

Example

EXEC DBMS_MACADM.DELETE_RULE('Check UPDATE operations'); 

16.1.5 DELETE_RULE_FROM_RULE_SET Procedure

The DELETE_RULE_FROM_RULE_SET procedure deletes a rule from a rule set.

Syntax

DBMS_MACADM.DELETE_RULE_FROM_RULE_SET(
 rule_set_name IN VARCHAR2, 
 rule_name     IN VARCHAR2);

Parameters

Table 16-5 DELETE_RULE_FROM_RULE_SET Parameters

Parameter	Description
rule_set_name	Rule set name. To find existing rule sets in the current database instance, query the DBA_DV_RULE_SET view.
rule_name	Rule to remove from the rule set. To find existing rules in the current database instance, query the DBA_DV_RULE view. To find rules that have been associated with rule sets, query DBA_DV_RULE_SET_RULE.

Example

BEGIN
 DBMS_MACADM.DELETE_RULE_FROM_RULE_SET(
  rule_set_name => 'Limit_DBA_Access', 
  rule_name     => 'Check UPDATE operations');
END;
/

16.1.6 DELETE_RULE_SET Procedure

The DELETE_RULE_SET procedure deletes a rule set.

Syntax

DBMS_MACADM.DELETE_RULE_SET(
 rule_set_name IN VARCHAR2); 

Parameters

Table 16-6 DELETE_RULE_SET Parameter

Parameter	Description
rule_set_name	Rule set name. To find existing rule sets in the current database instance, query the DBA_DV_RULE_SET view.

Example

EXEC DBMS_MACADM.DELETE_RULE_SET('Limit_DBA_Access'); 

16.1.7 RENAME_RULE Procedure

The RENAME_RULE procedure renames a rule and causes the name change to take effect everywhere the rule is used

Syntax

DBMS_MACADM.RENAME_RULE(
 rule_name  IN VARCHAR2, 
 new_name   IN VARCHAR2); 

Parameters

Table 16-7 RENAME_RULE Parameters

Parameter	Description
rule_name	Current rule name. To find existing rules in the current database instance, query the DBA_DV_RULE view. To find rules that have been associated with rule sets, query DBA_DV_RULE_SET_RULE.
new_name	New rule name, up to 128 characters in mixed-case.

Example

BEGIN
 DBMS_MACADM.RENAME_RULE(
  rule_name  => 'Check UPDATE operations', 
  new_name   => 'Check Sector 2 Processes');
END; 
/

16.1.8 RENAME_RULE_SET Procedure

The RENAME_RULE_SET procedure renames a rule set and causes the name change to take effect everywhere the rule set is used.

Syntax

DBMS_MACADM.RENAME_RULE_SET(
 rule_set_name IN VARCHAR2, 
 new_name      IN VARCHAR2); 

Parameters

Table 16-8 RENAME_RULE_SET Parameters

Parameter	Description
rule_set_name	Current rule set name. To find existing rule sets in the current database instance, query the DBA_DV_RULE_SET view.
new_name	New rule set name, up to 128 characters in mixed-case. Spaces are allowed.

Example

BEGIN
 DBMS_MACADM.RENAME_RULE_SET(
  rule_set_name => 'Limit_DBA_Access', 
  new_name      => 'Limit Sector 2 Access'); 
END;
/

16.1.9 UPDATE_RULE Procedure

The UPDATE_RULE procedure updates a rule.

Syntax

DBMS_MACADM.UPDATE_RULE(
 rule_name  IN VARCHAR2, 
 rule_expr  IN VARCHAR2 DEFAULT,
 is_static  IN BOOLEAN DEFAULT);

Parameters

Table 16-9 UPDATE_RULE Parameters

Parameter	Description
rule_name	Rule name. To find existing rules in the current database instance. To find rules that have been associated with rule sets, query DBA_DV_RULE_SET_RULE.
rule_expr	PL/SQL BOOLEAN expression. If you do not want to change this setting, then omit it or set it to NULL. If the expression contains quotation marks, do not use double quotation marks. Instead, use two single quotation marks. Enclose the entire expression within single quotation marks. For example: 'TO_CHAR(SYSDATE,''HH24'') = ''12''' NULL or omitted leaves the current setting unchanged. (Default) To find existing rule expressions, query the DBA_DV_RULE view.
is_static	Specifies whether the evaluation of a rule should be static or dynamic. If you do not want to change this setting, then omit it or set it to NULL. TRUE sets the rule to be static. When a rule is specified as static, then the result of the first rule evaluation in a session will be cached and used whenever the rule needs to be evaluated again in the session. FALSE sets the rule to be dynamic. The result of the rule will be evaluated each time the rule is triggered. NULL leaves the current setting unchanged. (Default)

Example

BEGIN
DBMS_MACADM.UPDATE_RULE(
  rule_name  => 'Check UPDATE operations',
  rule_expr  =>'SYS_CONTEXT(''USERENV'',''SESSION_USER'') = ''SYSADM'' AND
               (
                 UPPER(SYS_CONTEXT(''USERENV'',''MODULE'')) LIKE ''APPSRVR%'' OR
                 UPPER(SYS_CONTEXT(''USERENV'',''MODULE'')) LIKE ''DBAPP%''
               )',
  is_static  => TRUE);
END;
/

16.1.10 UPDATE_RULE_SET Procedure

The UPDATE_RULE_SET procedure updates a rule set.

When you update a rule set, the existing traditional audit records are disabled. You must create a unified audit policy to capture new audit records. To find the current values, query the DBA_DV_RULE_SET data dictionary view.

Syntax

DBMS_MACADM.UPDATE_RULE_SET(
 rule_set_name    IN VARCHAR2,
 description      IN VARCHAR2 DEFAULT, 
 enabled          IN VARCHAR2 DEFAULT, 
 eval_options     IN NUMBER DEFAULT,
 audit_options    IN NUMBER DEFAULT, 
 fail_options     IN NUMBER DEFAULT, 
 fail_message     IN VARCHAR2 DEFAULT, 
 fail_code        IN NUMBER DEFAULT, 
 handler_options  IN NUMBER DEFAULT, 
 handler          IN VARCHAR2 DEFAULT,
 is_static        IN BOOLEAN DEFAULT); 

Parameters

Table 16-10 UPDATE_RULE_SET Parameters

Parameter	Description
rule_set_name	Rule set name. To find existing rule sets in the current database instance.
description	Description of the purpose of the rule set, up to 1024 characters in mixed-case. If you do not want to change this setting, then omit it or set it to NULL.
enabled	Controls the enablement of the rule set. If you do not want to change this setting, then omit it or set it to NULL. DBMS_MACUTL.G_YES enables rule set checking. DBMS_MACUTL.G_NO disables rule set checking. NULL leaves the current value unchanged. (Default)
eval_options	For multiple rules that have been added to a rule set, determines if any or all rules are evaluated. If you do not want to change this setting, then omit it or set it to NULL. DBMS_MACUTL.G_RULESET_EVAL_ALL: All rules in the rule set must evaluate to true for the rule set itself to evaluate to true. DBMS_MACUTL.G_RULESET_EVAL_ANY: At least one rule in the rule set must evaluate to true for the rule set itself to evaluate to true. NULL leaves the current setting unchanged. (Default)
audit_options	Perform one of the following actions: Set DBMS_MACUTL.G_RULESET_AUDIT_OFF to disable traditional auditing for this rule set policy. Leave the current audit_options setting as is if you want to continue using this traditional auditing setting. To do so, you can specify the same setting as the current existing audit_options for this rule set, or do not specify audit_options (NULL). Traditional auditing is desupported in Oracle AI Database 26ai. Oracle recommends that you use unified auditing. To audit a rule set, you must use unified auditing. See Oracle AI Database Security Guide for an example of how to create a unified audit policy for a rule set.
fail_options	Options for reporting errors. If you do not want to change this setting, then omit it or set it to NULL. DBMS_MACUTL.G_RULESET_FAIL_SHOW shows the custom error code and message when the rule set evaluation fails. DBMS_MACUTL.G_RULESET_FAIL_SILENT does not show the custom error code and message when the rule set evaluation fails. Instead, it uses the default error message. NULL leaves the current setting unchanged. (Default)
fail_message	Error message for failure, up to 80 characters in mixed-case, to associate with the fail code you specify for fail_code. If you do not want to change this setting, then omit it or set it to NULL.
fail_code	Enter a number in the range of -20000 to -20999 or 20000 to 20999 to associate with the fail_message parameter. If you do not want to change this setting, then omit it or set it to NULL.
handler_options	Controls the behavior of the handler. If you do not want to change this setting, then omit it or set it to NULL. DBMS_MACUTL.G_RULESET_HANDLER_OFF disables error handling. DBMS_MACUTL.G_RULESET_HANDLER_FAIL calls the handler on rule set failure. DBMS_MACUTL.G_RULESET_HANDLER_SUCCESS calls the handler on rule set success. NULL or omitted leaves the current setting unchanged. (Default)
handler	Name of the PL/SQL function or procedure that defines the custom event handler logic. If you do not want to change this setting, then omit it or set it to NULL.
is_static	Optional. Determines how often a rule set is evaluated when it is accessed by a SQL statement. If you do not want to change this setting, then omit it or set it to NULL. TRUE sets the rule set to be static. When a rule set is specified as static, then the result of the first rule evaluation in a session will be cached and used whenever the rule needs to be evaluated again in the session. FALSE sets the rule set to be dynamic. The result of the rule set will be evaluated each time the rule set is triggered. NULL leaves the current setting unchanged. (Default)

Example

In this example, enabled is omitted because this value did not need to change.

BEGIN
 DBMS_MACADM.UPDATE_RULE_SET(
  rule_set_name    => 'Limit_DBA_Access', 
  description      => 'DBA access through predefined processes', 
  eval_options     => DBMS_MACUTL.G_RULESET_EVAL_ANY,
  audit_options    => DBMS_MACUTL.G_RULESET_AUDIT_OFF,
  fail_options     => DBMS_MACUTL.G_RULESET_FAIL_SHOW,
  fail_message     => 'Access denied!',
  fail_code        => 20900,
  handler_options  => DBMS_MACUTL.G_RULESET_HANDLER_OFF, 
  handler          => '',
  is_static        => TRUE);
END;
/

If you did not make any modifications to the audit_options parameter of your rule set, then the existing traditional audit policy will still be in place. If you updated the audit_options parameter of the rule set, then this auditing will be disabled because traditional auditing is desupported starting in Oracle AI Database 26ai. To capture new audit records, as a user who has been granted the AUDIT_ADMIN Oracle AI Database role and AUDIT_ADMIN Oracle Database Vault authorization, create and enable a unified audit policy. For example:

CREATE AUDIT POLICY Limit_DBA_Access_pol 
 ACTIONS COMPONENT=DV RULE SET FAILURE ON "Limit_DBA_Access";

AUDIT POLICY Limit_DBA_Access_pol;

You can view the audit records by querying the UNIFIED_AUDIT_TRAIL data dictionary view. See Oracle AI Database Security Guide for how this works.

16.2 Oracle Database Vault PL/SQL Rule Set Functions

Oracle Database Vault provides functions to use in rule sets to inspect the SQL statement that the rule set protects.

• DV_SYSEVENT Function
  The DV_SYSEVENT function returns the system event firing the rule set. .
• DV_LOGIN_USER Function
  The DV_LOGIN_USER function returns the session user name, in VARCHAR2 data type.
• DV_INSTANCE_NUM Function
  The DV_INSTANCE_NUM function returns the database instance number, in NUMBER data type.
• DV_DATABASE_NAME Function
  The DV_DATABASE_NAME function returns the database name, in VARCHAR2 data type.
• DV_DICT_OBJ_TYPE Function
  The DV_DICT_OBJ_TYPE function returns the type of the dictionary object on which the database operation occurred.
• DV_DICT_OBJ_OWNER Function
  The DV_DICT_OBJ_OWNER function returns the name of the owner of the dictionary object on which the database operation occurred.
• DV_DICT_OBJ_NAME Function
  The DV_DICT_OBJ_NAME function returns the name of the dictionary object on which the database operation occurred.
• DV_SQL_TEXT Function
  The DV_SQL_TEXT function returns the first 4000 characters of SQL text of the database statement used in the operation.

16.2.1 DV_SYSEVENT Function

The DV_SYSEVENT function returns the system event firing the rule set. .

The event name is the same as that in the syntax of the SQL statement (for example, INSERT, CREATE.) The return type is VARCHAR2.

Syntax

DV_SYSEVENT ()
RETURN VARCHAR2;

Parameters

None

Example

BEGIN 
 DBMS_MACADM.CREATE_RULE(
  rule_name => 'Get System Event Firing the Maintenance Rule Set',
  rule_expr => 'DV_SYSEVENT = ''CREATE''');
END;
/

16.2.2 DV_LOGIN_USER Function

The DV_LOGIN_USER function returns the session user name, in VARCHAR2 data type.

Syntax

DV_LOGIN_USER ()
RETURN VARCHAR2;

Parameters

None

Example

BEGIN 
 DBMS_MACADM.CREATE_RULE(
  rule_name => 'Check Session User Name',
  rule_expr => 'DV_LOGIN_USER = ''SEBASTIAN''');
END;
/

16.2.3 DV_INSTANCE_NUM Function

The DV_INSTANCE_NUM function returns the database instance number, in NUMBER data type.

Syntax

DV_INSTANCE_NUM ()
RETURN NUMBER;

Parameters

None

Example

BEGIN 
 DBMS_MACADM.CREATE_RULE(
  rule_name => 'Check Database Instance Number',
  rule_expr => 'DV_INSTANCE_NUM BETWEEN 6 AND 9');
END;
/

16.2.4 DV_DATABASE_NAME Function

The DV_DATABASE_NAME function returns the database name, in VARCHAR2 data type.

Syntax

DV_DATABASE_NAME ()
RETURN VARCHAR2;

Parameters

None

Example

BEGIN 
 DBMS_MACADM.CREATE_RULE(
  rule_name => 'Check Database Name',
  rule_expr => 'DV_DATABASE_NAME = ''ORCL''');
END;
/

16.2.5 DV_DICT_OBJ_TYPE Function

The DV_DICT_OBJ_TYPE function returns the type of the dictionary object on which the database operation occurred.

For example, dictionary objects it returns are table, procedure, or view. The return type is VARCHAR2.

Syntax

DV_DICT_OBJ_TYPE ()
RETURN VARCHAR2;

Parameters

None

Example

BEGIN 
 DBMS_MACADM.CREATE_RULE(
  rule_name => 'Check Dictionary Object Type',
  rule_expr => 'DV_DICT_OBJ_TYPE IN (''TABLE'', ''VIEW'')');
END;
/

16.2.6 DV_DICT_OBJ_OWNER Function

The DV_DICT_OBJ_OWNER function returns the name of the owner of the dictionary object on which the database operation occurred.

The return type is VARCHAR2.

Syntax

DV_DICT_OBJ_OWNER ()
RETURN VARCHAR2;

Parameters

None

Example

BEGIN 
 DBMS_MACADM.CREATE_RULE(
  rule_name => 'Check Dictionary Object Owner',
  rule_expr => 'DV_DICT_OBJ_OWNER = ''JSMITH''');
END;
/

16.2.7 DV_DICT_OBJ_NAME Function

The DV_DICT_OBJ_NAME function returns the name of the dictionary object on which the database operation occurred.

The return type is VARCHAR2.

Syntax

DV_DICT_OBJ_NAME ()
RETURN VARCHAR2;

Parameters

None

Example

BEGIN 
 DBMS_MACADM.CREATE_RULE(
  rule_name => 'Check Dictionary Object Name',
  rule_expr => 'DV_DICT_OBJ_NAME = ''SALES''');
END;
/

16.2.8 DV_SQL_TEXT Function

The DV_SQL_TEXT function returns the first 4000 characters of SQL text of the database statement used in the operation.

The return type is VARCHAR2.

Syntax

DV_SQL_TEXT ()
RETURN VARCHAR2;

Parameters

None

Example

BEGIN 
 DBMS_MACADM.CREATE_RULE(
  rule_name => 'Check SQL Text',
  rule_expr => 'DV_SQL_TEXT = ''SELECT SALARY FROM HR.EMPLOYEES''');
END;
/