GuardAPI Reference

GuardAPI provides access to Guardium® functionality from the command line.

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 create datasources, maintain user hierarchies, or maintain the Guardium features such as S-TAP® just to name a few.

Proper login to the CLI for the purpose of using GuardAPI requires the login with one of the five CLI accounts (guardcli1,...,guardcli5) and an additional login (issuing the 'set guiuser' command) with a user (GUI username/guiuser) that has been created by access manager and given either the admin or cli role. See Set guiuser Authentication for more information.

GuardAPI is a set of CLI commands, all of which begin with the keyword grdapi.

To list all GuardAPI commands available, enter the grdapi command with no arguments or use the 'grdapi commands' command with no search argument. For example:
```
CLI> grdapi 
or
CLI> grdapi commands
```

To display the parameters for a particular command, enter the command followed by '--help=true'. For example:

CLI> grdapi list_entry_location --help=true
ID=0
function parameters :
fileName
hostName - required
path - required
ok

To search for GuardAPI commands given a search string use the CLI command, grdapi commands <search-string>. For example:

CLI> grdapi commands user
ID=0
Matching API Function list :
create_db_user_mapping
create_user_hierarchy
delete_allowed_db_by_user
delete_db_user_mapping
delete_user_hierarchy_by_entry_id
delete_user_hierarchy_by_user
execute_appUserTranslation
execute_ldap_user_import
list_allowed_db_by_user
list_db_user_mapping
list_user_hierarchy_by_parent_user
update_user_db

To display a values list for a parameter, enter the command followed by '--get_param_values=<parameter>;'. For example:
```
CLI> grdapi create_group --get_param_values=appid
Value for parameter 'appid' of function 'create_group' must be one of:
Public
Baseline
Access_policy
Classifier
Db2_zos
ID=0
ok
```
Table 1. Current® APIs that support the –get_param_values command structure
API Function Parameter

create_datasource

application, type, severity, shared

create_group

appid, type

Table 1. Current® APIs that support the –get_param_values command structure
API Function	Parameter
create_datasource	application, type, severity, shared
create_group	appid, type

Case Sensitivity

Both the keyword and value components of parameters are case sensitive.

Parameter Values with Spaces

If a parameter value contains one or more spaces, it must be enclosed in double quote characters.

For example:

grdapi create_datasource type ="MS SQL SERVER" ...

NULL Values and Empty Strings

In general, when calling a GuardAPI function and a value for a non-required parameter is not specified or is set to an empty string ("""") GuardAPI will convert that parameter to a NULL value when calling the GuardAPI function. This translates into GuardAPI ignoring the parameter just as if it were not specified.

If, for example, you wanted to clear out a group from a policy rule you instead would set that group to space ("" "") and not an empty string (""""). Using an empty string ("""") would signal GuardAPI to ignore that group and not change that group selection.

Example for clearing out a group from a policy value

grdapi update_rule fromPolicy=V8 ruleDesc="LogFull Details" dbUserGroup=" " dbUser=" " objectGroup=" " commandsGroup=" "

Return Codes

Regardless of the outcome of the GuardAPI command, a return code is always returned in the first line of output, in the following format:

Table 2. Return Codes
Return Code	Description
ID=identifier	Successful. The identifier is the ID of the object operated upon; for example, the ID of a group that has just been defined.
ERR=error_code	Error. The error_code identifies the error, and one or more additional lines provide a text description of the error. There is a table of common errors in the Overview and a complete listing of error codes in GuardAPI Error Codes.

For example, if we use the create_group command to successfully define an objects group named agroup, the ID of that group is returned:

CLI> grdapi create_group desc=agroup type=objects appid=Public
ID=20001
ok
CLI>

We could use that ID in the list_group_by_id command to display the group definition

CLI> grdapi list_group_by_id id=20001
ID=20001
Group GroupId=20001
Group GroupTypeId=3
Group ApplicationId=0
Group GroupDescription=agroup
Group GroupSubtype=null
Group CategoryName=null
Group ClassificationName=null
Group Timestamp=2008-05-10 07:34:11.0
Group type = OBJECTS
Application Type = Public
Touple Group
ok

For an unsuccessful execution, an error code is returned. For example, if we enter the list_group_by_id command again with an invalid ID, we receive the following message:

a1.corp.com> grdapi list_group_by_id id=20123
ERR=140
Could not retrieve Group - check Id.
ok

Common Error Codes

Error codes with a value fewer than 100 are for common error conditions. Error codes greater than 100 apply to specific functions, and those are described following each function.

To see a complete list of GuardAPI error codes, type grdapi-errors, at the CLI command prompt.

Table 3. Common Error Codes
Error	Description
0	Missing parameters or unknown errors such as unexpected exceptions.
1	An Exception has occurred, please contact Guardium's support
2	Could not retrieve requested function - check function name. To list all functions, type either the CLI command, grdapi, or grdapi commands, with no arguments. To search by function name given a search string, use the CLI command, grdapi commands <search-string>
3	Too many arguments. To get the list of parameters for this function call the function --help=true
4	Missing required parameter. To get the list of parameters for this function call the function with --help=true
5	Could not decrypt parameter, check if encrypted with the correct shared secret.
6	Wrong parameter format, specify a function name followed by a list of parameters using <name=value> format.
7	Wrong parameter value for parameter type.
8	Wrong parameter name, please note, parameters are case sensitive.
9	User has insufficient privileges for the requested API function
10	Parameter Encryption not enabled - shared secret not set.
11	Failed sending API call request to targetHost
12	Error Validating Parameter
14	Target host is not managed by this manager
15	Target host is not online
16	Target host cannot be specified on a standalone unit
17	User is not allowed to operate on the specified object
18	Target host cannot be specified
19	Missing end quote
20	User is not allowed to run grdapi commands
21	--username and --source-host are grdapi reserved words and cannot be passed on the command line.
22	A parameter name cannot be specified more than once, please check the command line for duplicate parameters.
23	Value not in constant list.
24	Not a valid encrypted value.
25	Not a valid parameter format - parameters should be specified as <name=value>, spaces are not allowed.

GuardAPI Activity Log

The Guardium Activity Log records all grdapi commands that are executed on the system. To view the commands from the administrator portal, navigate to the User Activity Audit Trail report on the Guardium Monitor tab.

All grdapi activity will be attributed to the cli user. Double-click on the cli row in that report, and select the Detailed Guardium User Activity drill-down report. Every command entered will be listed, along with any and all changes made. In addition, the IP address from which the command was issued is listed.

Display attributes for certain users in Query Builder

The admin user can see all query attributes in Query Builder and non-admin users can see query attributes in Query Builder, except those that are designed as admin only (IDs, for example).

There are some entities (like FULL SQL) that have large numbers of attributes in them.

By default, all attributes will show up for all users (admin and non-admin).

Two GuardAPI commands have been added to display or not display certain attributes for certain users.

These GuardAPI commands will enable disable/enable ONLY specific groups of attributes in Full SQL: VSAM, ISAM, MApReduce, APEX, Hive and BigInsight.

Two New GuardAPIs named: grdapi enable_special_attributes and grdapi disable_special_attributes

Both receive only one parameter: attributesGroup.

The valid values for this parameter are: VSAM, IMS, MapReduce, APEX, Hive, BI (BigInsights), IMS/VSAM, DB2 i, F5 (Not case sensitive).

Each Grdapi will enable (disable) all the correspondent attributes for the group, for example VSAM will enable (disable) the following attributes:

VSAM records
VSAM records delected
VSAM records inserted
VSAM records retrieved
VSAM records updated
VSAM User Group ID

Hive will enable (disable) the following attributes:

Hive command
Hive database
Hive error
Hive parsed SQL
Hive table name
Hive user

Note: The attributes will still be displayed if the user has the admin role; enabling or disabling these attributes applies ONLY to non-admin users (with no admin role).

Note: The GUI does not have to be restarted for the change to take effect. With this exception: If a report with the attributes of group F5 has been created and added it to My New Reports, even though the attributes have been enabled, the no admin-user does not have the privilege to view the report. The GUI needs to be restarted to see the report fields.