GuardAPI Input Generation

Generate Input for Guard API Calls

The generation of Guard API calls from reports can be invoked in one of two ways, either from a single row within a report or multi-rows that is based on a whole report (what is seen on the screen).  See the how-to topic, Generate API Call From Reports, for an example.

When a report is displayed:

Mapping GuardAPI to Report Results

Guardium comes with a battery of predefined reports and many of them have already been mapped to GuardAPI functions to ease configuration. In addition, Guardium offers users the capability to define additional reports, even their own custom made reports, and map them to GuardAPI functions per report.

1. Go to any predefined report in the Daily Monitor tab, Guardium Monitor tab, or Tap Monitor tab.
2. Click the Invoke ... button.
3. Choose the Add API mapping selection.
4. At the new window, Add API mapping shows the name of the report, for example, Guardium Logins; a search/filter mechanism to find the appropriate GuardAPI command; and, selection choices for API functions available under the Predefined Report. Choose the API function, and then click Map Report Attributes.
5. At the new window, API-Report Parameter Mapping, map the parameter name to the Report field. Sometimes there might be data that is not supplied with a Guardium report. For these instances, a constant can be created, added to the report and used within the API parameter mappings.
   Note: Save overrides the current mapping.
   Note: If the Guardium report, with a constant added, is exported, the constant will not be exported.

To simplify the mapping between the GuardAPI parameters and Guardium attributes, Guardium created the predefined report Query Entities & Attributes that list all the Guardium attributes; giving users a GUI interface and allowing them to easily drill down from that report and create the linkages quickly.

Existing Guardium attributes or user-defined constants may be mapped to the GuardAPI parameters of Existing Attributes or Constants.

Existing Attributes

1. Go to the Query Entities & Attributes report to add the API parameter mappings. (Guardium Monitor -> Query Entities & Attributes)
2. The Query Entities & Attributes report is long because it lists all the Guardium attributes. Narrow down the records you are interested in by using the Customize button.
3. To create the mapping, double-click the attribute row you would like to assign to a parameter name
4. Click the Invoke... option
5. Select the create_api_parameter_mapping API function
6. Fill in the functionName and parameterName in the API Call Form
7. Click the Invoke now button to create the API to Report Parameter Mapping

See how-to topic, Using API Calls From Custom Reports, for a full scenario that maps GuardAPI parameters through the GUI.

Constants

Sometimes there may be data that is not supplied within a Guardium report. For these instances, a constant can be created, added to the report, and then used within the API parameter mappings.

1. Go to the Query Entities & Attributes report to add the API parameter mappings. (Guardium Monitor -> Query Entities & Attributes)
2. The Query Entities & Attributes report is long because it lists all the Guardium attributes. Narrow down the records you are interested in by using the Customize button.
3. To create a constant attribute, double-click any row for the entity you would like to create a constant attribute for
4. Click the Invoke... option
5. Select the create_constant_attribute API function
6. Fill in the constant value to use and an attributeLabel you like to name it
7. Click the Invoke now button to create the constant
8. To create the mapping, double-click the newly created attribute row
9. Click the Invoke... option
10. Select the create_api_parameter_mapping API function
11. Fill in the functionName and parameterName in the API Call Form
12. Click the Invoke now button to create the API to Report Parameter Mapping
13. The newly created attribute must be added to the report. Modify the Query through Query Builder and add the field.

See how-to topic, Using Constants within API Calls, for a full scenario that creates and maps a constant attribute through the GUI.

Note: If the Guardium report, with a constant added, is exported, the constant will not be exported.

Note: When using API mapping, table columns in a report appears in the report field as long as the table column is an attribute of an entity. Some of the columns such as count column will not be displayed in the report field because it cannot be mapped.

Object Security for Certain GuardAPI commands

Role validation implements controls on selected GuardAPI commands to consider the roles of the specific components (and not only the application) and disallow actions if the roles do not match.

This means a user that has the appropriate roles for Policy Builder is able to execute the GuardAPI command, delete_rule, on any policy, regardless of the roles of this specific policy.

Role validation exists for the following Policy rules GuardAPI commands: change_rule_order; copy_rule; copy_rules, delete_rule; update_rule.

Role validation exists for the following Group Description GuardAPI commands: create_member_to_group_by_desc; create_member_to_group_by_id; delete_group_by_desc; delete_group_by_id; delete_member_from_group_by_desc; delete_member_from_group_by_id; update_group_by_id; update_group_by_desc.

Role validation exists for the following Datasource GuardAPI commands: delete_datasource_by_id; delete_datasource_by_name; update_datasource_by_id; update_datasource_by_name.

Role validation exists for the following Audit Process GuardAPI commands: stop_audit_process.

API to run an audit process from tabular and graphical reports

An GuardAPI can be invoked automatically from any report portlet. When the GuardAPI is invoked, it creates a new audit process report.

If such process for the user exists, then the parameters are updated and the same process is used.

The behavior of the GuardAPI is as follows:

1 - If new process, it creates one receiver per email in the list (if any) with <p>a content type as indicated in the emailContentType parameter. It will also create a user receiver for the user that is logged in (invoking the API) if the includeUserReceiver parameter is true.

2 - If existing process,  all email receivers are removed and replaced with the emails from the new list (if any) with the content type as defined in the emailContentType parameter. If the list is empty, it removes all email address receivers. If there is already a receiver for the user it will NOT be removed even if the includeUserreceiver is false, however if the parameter is true and there is no such receiver then it is added.

Once the audit process is generated, it is automatically executed (similar to a Run Once Now) and users should expect an item on their to-do list for that audit process.

create_ad_hoc_audit_and_run_once

Parameters:

1 - reportId - The ID on the report to be used for the only task in the Audit process

2 - isForReportRunOnce boolean indicates whether the process should be run once after it is created.

3 - changeParIfExist boolean indicates whether the task parameters should be updated if the process exists

4 - taskParameter All task parameters and the value for each concatenated with the characters ^^ should be like: PAR1=Val1^^PAR2=Val2^^ etc it is valid to leave a parameter empty, for example if PAR2 should remain empty it looks like: PAR1=VAL1^^PAR2=^^PAR3=VAL3^^...

5 - processNamePar - Name of the process if empty it creates a process with the name.

6 - sendToEmails: A comma-separated list of email addresses

7 - emailContentType 0-PDF or 1-CSV (applies ONLY to email receivers

8 - includeUserReceiver boolean indicates whether to create a receiver for the user that is logged in

An GuardAPI can be invoked automatically from any report portlet. When the GuardAPI is invoked, it creates a new audit process report.

Schedule APIs

modify_schedule parameters jobName jobGroup cronString startTime optional

list schedule

delete_schedule parameters jobName jobGroup deleteJob optional

schedule_job parameters jobType objectName optional cronString startTime optional

grdapi schedule_job --get_param_values=jobType - Value for parameter 'jobType' of function 'schedule_job' must be one of: CustomTableDataUpload; AutoDetectProbeJob; AppUserTranslation; InstallPolicy: AuditJob; ResultArchive; AutoDetectScanJob; CustomTableDataPurge; CSVExport; DataExport; DataArchive; DataImport; PopulateGrpFromQry; SystemBackup; PopulateAlias; IpHostToAlias; UnitUtilization

grdapi set_purge_batch_size

Set the batch size that is used during purge, aids in performance of purge and has a default setting of 200,000. A trade-off in performance and disk space usage should be noted as setting to a larger batch size increases the speed of the purge but consumes more disk space and setting to a low batch size decreases the speed of the purge but not consume as much disk space.

function parameters: batchSize - required api_target_host Example vx29> grdapi set_purge_batch_size batchSize=200000 ID=0 ok

grdapi get_purge_batch_size

Gets the current setting for the purge batch size

function parameters: api_target_host Example vx29> grdapi get_purge_batch_size ID=0 Purge Batch Size = 200000 ok

grdapi patch_install

function parameters: patch_date patch_number - required

grdapi populate_from_dependencies

function parameters: descOfEndingGroup - required descOfStartingGroup - required flattenNamespace getFunctions getJavaClasses getPackages getProcedures getSynonyms getTables getTriggers getViews isAppend - required isEndingGroupQualified owner - required reverseIt selectedDataSourceName - required api_target_host

create_computed_attribute

Use in Reports.

grdapi create_computed_attribute attributeLabel="CustomUserName" entityLabel="App User Name" expression="SUBSTRING_INDEX(GDM_CONSTRUCT_INSTANCE.APP_USER_NAME,'.',1)"

delete_computed_attribute

Use in Reports.

update_computed_attribute

Use in Reports.

create_constant_attribute

Use in Reports.

delete_constant_attribute

Use in Reports.

update_constant_attribute

Use in Reports.

create_ad_hoc_audit_and_run_once

Use in Reports.

REST API

JSON (JavaScript Object Notation) output option supports GuardAPI functions. This is part of REST APIs. REST stands for Representational State Transfer. It relies on a stateless, client/server, cacheable communications protocol, and in virtually all cases, the HTTP protocol is used. REST is an architecture style for designing networked applications. The idea is that, rather than using complex mechanisms such as CORBA, RPC, or SOAP to connect between machines, simple HTTP is used to make calls between machines. RESTful applications use HTTP requests to post data (create and/or update), read data (for example, make queries), and delete data. Thus, REST uses HTTP for all four Create/Read/Update/Delete operations. REST is a lightweight alternative to mechanisms like RPC (Remote Procedure Calls) and Web Services (SOAP, WSDL).

Guardium’s Implementation of REST

1. Register Application (only once) and get Client Secret.

2. Store Client Secret in secure place.

3. Request Access Token for authorization.

4. Store Access Token so grdAPI command is authenticated properly.

5. Use Access Tokens to submit GuardAPI commands.

Example use cases

• I want the ability to dynamically get a small amount of audit data for a certain IP address without having to login to the Guardium GUI.

• I want to populate an existing group, so I can update my policy to prevent unauthorized access to sensitive information.

• I want to get a list of all users within a certain authorized access group.

• I want my application development team to help identify what sensitive tables to monitor.

• I want to script access to grdAPI’s without using “expect” scripting language, which requires me to code response text from the target system.

HTTP has a vocabulary of operations (request methods)

• GET (pass parameters in the URL)

• POST (pass parameters in JSON object)

• PUT (pass parameters to change as JSON object)

• DELETE (pass parameters as JSON object)

Special user for internal REST API requests

For internal REST API requests, there is a special ROLE and USER predefined in the system.

This user cannot be removed or modified through the accessmgr UI and cannot be used to log in the UI.

This user's password will never expire, but is revoked if client ID is revoked.

On OAuth client registration, a new function accepts this user and client ID. It generates a random strong password for the user and store it in the TURBINE_USER table.

It returns a client secret and the generated password.

The internal (S-TAP, maybe others) client must secure the client secret and password.

Permissions for different functions can be assigned to the role through accessmgr UI.

RestAPI vs. GuardAPI

GET = List

POST = Create

PUT = Update

DELETE = Delete

GuardAPIs

list_datasourcename_by_name (parameters - ?name="MSSQL_1")

-X GET https://10.10.9.239:8443/restAPI/datasource/?name="MSSQL_1"

create_datasource

-X POST https://10.10.9.239:8443/restAPI/datasource

update_datasource_by_name - JSON Object '{password:guardium}‘

-X PUT -d '{password:guardium, name:"MSSQL_1}‘

delete_datasource_by_id - JSON Object '{"id":20020}‘

-X DELETE -d '{"id":20020}‘

For further information, go to the Using the IBM Security Guardium REST API article on DeveloperWorks.

http://www.ibm.com/developerworks/data/library/techarticle/dm-1404guardrestapi/index.html

Query and restart internal UnitPinger thread

Use this GuardAPI command to query and restart internal UnitPinger thread.

NOTE: This GuardAPIs command needs to be called with api_target_host=127.0.0.1 parameter.

Example

grdapi get_unit_pinger api_target_host=127.0.0.1

register_oauth_client

Use this GuardAPI command to wrap supported GuardAPI functions in a RESTful API that uses JSON (JavaScript Object Notation) for input and output.

Use the GrdAPI command, grdapi register_oauth_client, to register the client and obtain the necessary access token to call the REST services.

REST stands for Representational State Transfer. It relies on a stateless, client/server, cacheable communications protocol, and in virtually all cases, the HTTP protocol is used.

REST is an architecture style for designing networked applications. The idea is that, rather than using complex mechanisms such as CORBA, RPC, or SOAP to connect between machines, simple HTTP is used to make calls between machines.

RESTful applications use HTTP requests to post data (create and/or update), read data (for example, make queries), and delete data. Thus, REST uses HTTP for all four Create/Read/Update/Delete operations. REST is a lightweight alternative to mechanisms like RPC (Remote Procedure Calls) and Web Services (SOAP, WSDL).

function parameters:

client_id - String - required

grant_types - String - required. The only grant type that is supported is password.

redirect_uris - String - required

scope - String - required.

fetchSize - String- optional (default is 20 recores to retain backward compatibility, maximum value is 30000.

sortColumn - optional - If specified must be the column title of one of the report fields.

sortType - optional - asc or desc

Syntax

grdapi register_oauth_client <client_id> <grant_types> <redirect_uris> <scope>

getOAuthTokenExpirationTime

Use this GuardAPI command to get the expiration time of the REST API token

function parameters:

api_target_host - String

setOAuthTokenExpirationTime

Use this GuardAPI command to set the expiration time of the REST API token.

function parameters:

expirationTime - Integer - required

api_target_host - String

Syntax

grdapi setOAuthTokenExpirationTime ExpirationTime=10000