How to integrate custom rules with Guardium policy

Show how to automatically modify/derive Guardium policy from a custom entitlement system.

This example will take a sample Oracle table (CUSTOM_ENTITLEMENT) as an example of a custom entitlement data, use an Oracle script to select data from this table, and then generate a file with GuardAPI commands. The file will include commands for the creation of new or modification of existing policy rules, change of a policy rule order, and policy reinstallation. We’ll then show you how to execute the generated script and then view the policy changes in the Guardium GUI.

Value-added: Guardium API provides access to Guardium functionality from the command line or script. This allows for the automation of repetitive tasks which is especially valuable in larger implementations. Calling these GuardAPI functions enables a user to quickly perform operations such as maintenance of the Guardium policy.

Follow these steps.

Define a rule structure which logs full details for all database manipulation (DML) Commands. It will be used as a template for a creating new rules creation. The rule will belong to the template policy.
Create the Oracle script that will generate a file with the following GuardAPI commands:
- copy_rule - add new rules to the installed policies as a copy of rule template
- update_rule - update the copied rules with the relevant data from CUSTOM_ENTITLEMENT Oracle table
- update_rule - update the existing rule with the data from that table
- change_rule_order - change rule position
- policy_install, reinstall_policy– install /re-install policy
Run the generated script.
View installed policy changes.

Steps:

Define a rule template
As many actions are permitted for a given policy rule, it becomes very difficult to define the complex hierarchical structure that a rule has using the Guard API. However, in most cases rules differ by the conditions and the action/receiver structures usually fall into a small set of different options. Therefore, the APIs are based on cloning an existing rule which acts as a rule template – this defines the actions/receiver structure and then conditions are changed using APIs.

Here we create a rule template (HowToTemplate), which includes rule action definition and will then be cloned and updated each time a new rule of that kind has to be added to a policy.

Click Protect > Security Policies > Policy Builder to open the Policy Finder and create a template policy. S

Click New to create the template policy; entering a Policy description, checking the Selective audit trail check-box, and clicking the Save button.

Click Edit Rules button to add a template rule to this policy

Click on the Add Access Rule button to display the Access Rule Definition panel and add a rule.

To add the rule, enter DML Command - Log Full Details Templatein the Description box; choose (Public) DML Commandsfrom the Commands box; highlight LOG FULL DETAILS WITH VALUESin the Action section; and then click the Save button.

Create the Oracle script that will generate a file with GuardAPI commands.

Key items to know before writing the script:

GuardAPI is a set of CLI commands, all of which begin with the keyword grdapi. To list all GuardAPI commands available, enter the command 'grdapi' with no arguments. To display the parameters for a particular command, enter the command followed by '--help=yes'.

For example

CLI>grdapi copy_rule --help=yes

ID=0

function parameters :

fromPolicy - required

ruleDesc - required

toPolicy - required

Both the keyword and value components of parameters are case sensitive.
If a parameter value contains one or more spaces, it must be enclosed in double quote characters. For example:

grdapi copy_rule ruleDesc="DMLCommand - Log Full Details Template" ...

There is no need to use all available parameters that a function supports. In addition to the required parameters, use the parameters that you want to change.
Scripts, which invoke GuardAPI, may contain sensitive information, such as passwords for datasources. To ensure that sensitive information is kept encrypted at all times, the grdapi command supports passing of one encrypted parameter to an API Function. This encryption is done using the System's Shared Secret which is set by the administrator and can be shared by many systems, and between all units of a central management and/or aggregation cluster; allowing scripts with encrypted parameters to run on machines that have the same shared secret. For more details about this issue please see Guardium Help.
If multiple policies are installed, then install policy command (policy_install) must include all installed policies descriptions delimited by pipe character. This must be done even if only one policy has changes. The policy descriptions should be in the order you want the policies to be installed.

Example of the command for installation of policies HowTo 1 and HowTo 2:

grdapi policy_install policy="HowTo 1|HowTo 2"

Logic behind writing of the script; changing the currently installed policy HowTo in the following way:

For each record in the CUSTOM_ENTITLEMENT table with IS_NEW_FLAG equals ‘1’, a new access rule with description saved in RULE_DESC column will be added to the “HowTo” policy. The rule logs full details for all DML Commands from OS user (OS_USER field value), client IP (CLIENT_IP), server IP (SERVER_IP) with service name (SERVICE_NAME).
If IS_NEW_FLAG value is ‘0’, the rule with description equals to the value of RULE_DESC column will be changed based on the relevant data from this record of the table.
Rule3 will be set as the first rule – to show how to use change_rule_order function.
In order to apply all of the changes, the policy will be reinstalled.

Data in custom_entitlement table

Table 1. Custom entitlement
os_user	client_ip	server_ip	rule_desc	service_name	is_new_rule	seq
User1	192.168.7.101	192.168.7.201	Rule1	PROD1	1	1
User2	192.168.7.102	192.168.7.202	Rule2	PROD2	1	2
User3	192.168.7.103	192.168.7.203	Rule3	PROD3	1	3
User4	192.168.7.104	192.168.7.204	Rule2	PROD4	0	4

Changes, based on logic and table data, can be described as:

Add a new access rule: Rule1. The rule logs full details for all DML Commands from user “user1”, client IP “192.168.7.101” to Oracle database on “192.168.7.201” server with service name “PROD1”.
Add a new access rule: Rule2. The rule logs full details for all DML Commands from user “user2”, client IP “192.168.7.102” to Oracle database on “192.168.7.202” server with service name “PROD2”.
Add a new access rule: Rule3. The rule logs full details for all DML Commands from user “user3”, client IP “192.168.7.103” to Oracle database on “192.168.7.203” server with service name “PROD3”.
Change Rule2 – set OS user to “user4”, client IP to “192.168.7.104”, server IP to “192.168.7.204”, service name to “PROD4”.
Set Rule3 to be the first rule in the policy.
In order to apply all of the changes, re-install the policy

Oracle script

SET LINESIZE 2000
SET TERMOUT OFF
SET FEEDBACK OFF 
 
SET SERVEROUTPUT ON SIZE 1000000
spool update_policy.txt
 
declare cursor CUSTOM_TABLE is
select OS_USER,CLIENT_IP,SERVER_IP,SERVICE_NAME,RULE_DESC,IS_NEW_RULE
  from CUSTOM_ENTITLEMENT order by SEQ;
S_RULE_DESC VARCHAR2(100);
BEGIN
    FOR CUR_W IN CUSTOM_TABLE
    LOOP
        IF NVL(CUR_W.IS_NEW_RULE,'0') = '1' THEN
           -- copy rule
           DBMS_OUTPUT.PUT_LINE('grdapi copy_rule ruleDesc="DMLCommand - Log Full Details Template" fromPolicy=HowToTemplate toPolicy=HowTo ');
           S_RULE_DESC := 'DMLCommand - Log Full Details Template';
        ELSE
           S_RULE_DESC := CUR_W.RULE_DESC;
        END IF;
        -- update rule
        DBMS_OUTPUT.PUT_LINE(
        'grdapi update_rule ruleDesc="'||S_RULE_DESC||'"'||
        ' fromPolicy=HowTo newDesc="'|| CUR_W.RULE_DESC ||'" clientIP='||CUR_W.CLIENT_IP ||
        ' clientNetMask=255.255.255.0 serverIP='||CUR_W.SERVER_IP||' serverNetMask=255.255.255.0 '||
        ' serviceName='||CUR_W.SERVICE_NAME ||' osUser='||CUR_W.OS_USER||' dbType=ORACLE');
    END LOOP;
    -- set Rule3 to be the first one
    DBMS_OUTPUT.PUT_LINE('grdapi change_rule_order ruleDesc=Rule3 fromPolicy=HowTo order=1');
    -- reinstall policy
    DBMS_OUTPUT.PUT_LINE('grdapi policy_install policy=HowTo');
END;
/
spool off

Generated script with GuardAPI commands

When the Oracle script is run within SQL*Plus, and spooled accordingly, will produce a file (update_policy.txt) that looks like:

grdapi copy_rule ruleDesc="DMLCommand - Log Full Details Template" fromPolicy=HowToTemplate toPolicy=HowTo
grdapi update_rule ruleDesc="DMLCommand - Log Full Details Template" fromPolicy=HowTo newDesc="Rule1" clientIP=192.168.7.101 clientNetMask=255.255.255.0 serverIP=192.168.7.201 serverNetMask=255.255.255.0  serviceName=PROD1 osUser=user1 dbType=ORACLE
grdapi copy_rule ruleDesc="DMLCommand - Log Full Details Template" fromPolicy=HowToTemplate toPolicy=HowTo
grdapi update_rule ruleDesc="DMLCommand - Log Full Details Template" fromPolicy=HowTo newDesc="Rule2" clientIP=192.168.7.102 clientNetMask=255.255.255.0 serverIP=192.168.7.202 serverNetMask=255.255.255.0  serviceName=PROD2 osUser=user2 dbType=ORACLE
grdapi copy_rule ruleDesc="DMLCommand - Log Full Details Template" fromPolicy=HowToTemplate toPolicy=HowTo
grdapi update_rule ruleDesc="DMLCommand - Log Full Details Template" fromPolicy=HowTo newDesc="Rule3" clientIP=192.168.7.103 clientNetMask=255.255.255.0 serverIP=192.168.7.203 serverNetMask=255.255.255.0  serviceName=PROD3 osUser=user3 dbType=ORACLE
grdapi update_rule ruleDesc="Rule2" fromPolicy=HowTo newDesc="Rule2" clientIP=192.168.7.104 clientNetMask=255.255.255.0 serverIP=192.168.7.204 serverNetMask=255.255.255.0  serviceName=PROD4 osUser=user4 dbType=ORACLE
grdapi change_rule_order ruleDesc=Rule3 fromPolicy=HowTo order=1
grdapi policy_install policy=HowTo

Note: The last grdapi command which re-installs the policy to apply the rules to the system

Run the generated script.
To run this script use the following command structure:

ssh cli@[Guardium appliance name] < [script name]

For example, to run update_policy.txt script on host 192.168.12.5 (password will be prompted for)

ssh cli@192.168.12.5 <update_policy.txt

Sample output:

192.168.12.5> ok

ID=20002

192.168.12.5> 192.168.12.5> ok

ID=20015

192.168.12.5> 192.168.12.5> ok

ID=20002

192.168.12.5> 192.168.12.5> ok

ID=20016

192.168.12.5> 192.168.12.5> ok

ID=20002

192.168.12.5> 192.168.12.5> ok

ID=20017

192.168.12.5> 192.168.12.5> ok

ID=20016

192.168.12.5> 192.168.12.5> ok

ID=20002

192.168.12.5> 192.168.12.5>
View installed policy changes.
Before running the script, there were no rules defined in the HowTo policy as shown in this preview

After running the script:

As a result of the copy_rule, the HowTo policy now has three Access Rules.

As a result of the change_rule_order command, Rule3 is now first.

Expanding any of the policy rules, Rule1 here, we can validate the various fields that have been altered with the update_rule commands.

As a result of the update_rule command, Rule2 has been change.

And as a result of the policy_install command, the currently installed policy is now the HowTo policy with three installed rules.