Using GuardAPI commands

Learn how to use the GuardAPI commands.

Accessing GuardAPI commands

GuardAPI is a set of commands that you can use to automate repetitive tasks, which is especially valuable in larger implementations. Use the GuardAPI functions to quickly perform operations such as creating datasources, maintaining user hierarchies, or maintaining Guardium® features such as S-TAP®, just to name a few. For a list of the available GuardAPI commands, see Guardium API A- Z Reference.

Before you can use GuardAPI commands, you need a local user and password (or an LDAP username) with appropriate roles and permissions. The GuardAPI commands that are available to you depend on your roles. For more information, see Creating a user who can run GuardAPI commands.

To access GuardAPI commands:

From the CLI, log in as one of the guardclin users (that is, guardcli1 to guardcli9 ). For example:
```
ssh guardcli2@company.com
```
Run the set guiuser CLI command to associate the new user with the guardcli user. The first time you log in, you must change your password (except for LDAP users). For example:
```
company.com> set guiuser Hadrian.Swall
Enter current password:
First login as Hadrian.Swall. Please change the default password.
Enter new password:
Re-enter new password:
ok
```
Note: When you change the password, you cannot reuse the last 10 passwords.

For more information about set guiuser, see Authenticating GuardAPI commands with set guiuser.

If your system has multi-factor authentication enabled, Guardium will request that you provide secondary authentication. Select the notification type by its number. For example:

mycompany.com> set guiuser Hadrian
Enter current password:
Secondary authentication is required for Hadrian
Please select a notification method:
0: cell phone (XXX-XXX-8846) : auto
1: cell phone (XXX-XXX-8846) : push
2: cell phone (XXX-XXX-8846) : sms
3: cell phone (XXX-XXX-8846) : phone
Q/q: Quit 

2
Enter SMS passcode:
ok

Note: The available notification methods depend on how multi-factor authentication is configured for your site.

In this case, the user, Hadrian Swall, can now use any GuardAPI commands that are available for the associated roles.

Finding GuardAPI command information

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

To list all GuardAPI commands available for your role, enter grdapi or grdapi commands with no arguments. For example:
```
> grdapi 
or
> grdapi commands
```
You can also find information about all of the GuardAPI commands in the Guardium API A- Z Reference.
To display information 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
```
Note: For some parameters, the available options depend on factors such as your operating system, available databases, or licenses. In these cases, look for the complete parameter list for your system by running --help=true for that GuardAPI in the CLI.

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
Audit Process Builder
Classifier
DB2 zOS Groups
Express Security
IMS zOS Groups
Policy Builder
Security Assessment Builder
ID=0
ok

To search for GuardAPI commands given a search string use 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

GuardAPI syntax

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 quotation marks, for example,
```
grdapi create_datasource type ="MS SQL SERVER" ... 
```
NULL values and empty strings: In general, when a value for a non-required parameter is not specified or is set to an empty string ("") GuardAPI converts the parameter to NULL when the function is called. That is, the parameter is ignored as if it were not specified.
If for example, you want to clear out a group from a policy rule, you might set that group to space (" ") and not an empty string (""). Using an empty string ("") signals that GuardAPI can ignore that group and not change that group selection.
For example,
```
grdapi update_rule fromPolicy=V8 ruleDesc="LogFull Details" dbUserGroup=" " 
dbUser=" " objectGroup=" " commandsGroup=" " 
```

Return Codes

The GuardAPI always returns a code in the first line of output, in one of the following formats:

Table 1. Return Codes
Return Code	Description
ID=identifier	Success. The identifier is the ID of the object that is operated upon; for example, the ID of a group that was just defined.
ERR=error_code	Error. The error_code identifies the error, and one or more additional lines provide a text description of the error. See Table 2 for a list of common error codes.

For example, if you use create_group 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>

You can then 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
Tuple Group
ok

If the GuardAPI fails, an error code is returned. For example, if you enter the list_group_by_id command again with an invalid ID, you 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 less than 100 are for common error conditions. Error codes greater than 100 apply to specific functions.

For a complete list of GuardAPI error codes, enter grdapi-errors at the CLI command prompt.

Table 2. Common Error Codes
Error	Description
0	Missing parameters or unknown errors such as unexpected exceptions
1	An Exception has occurred, please contact Guardium support
2	Could not retrieve requested function - check function name. To list all functions call either the "grdapi" or "grdapi commands" with no arguments. To search by function name given a search string, use the "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
13	Target host must be the ip address of the central manager
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 GuardAPI 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 GuardAPI activity is attributed to the cli user. Double-click the cli row in that report, and select the Detailed Guardium User Activity drill-down report.For each row, the report lists the following information:

Every command entered.
Any changes made.
The IP address from which the command was issued.

Encrypted Parameters

GuardAPI is intended to be invoked by scripts, which 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 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; enabling scripts with encrypted parameters to run on machines that have the same shared secret.

Note: Trying to run an API call with encrypted parameter on a system where shared secret was not set results in the following error message:

Parameter Encryption not enabled - shared secret not set

For Guard API scripts generated through the GUI, if encryption is required it is done using the shared secret of the system where script generation is performed.

The optional parameter encryptedParam is available on every grdapi call. This parameter can be used to pass an encrypted value for another parameter.

The procedure for manual encryption is as follows:

Use the Parameter Encryption API.

The encrypt_value API accepts a value to encrypt and the target system's shared secret (key) and then prints out the encrypted value. If the key is not the system's shared secret it will print out a warning.

a1.corp.com> grdapi encrypt_value --help=true
ID=0
function parameters :
key - required
valueToEncrypt - required
api_target_host
ok

Table 3. Encrypted Parameter
Parameter	Description
key	The target system's shared secret.
valueToEncrypt	The value to be encrypted.
api_target_host	In a central management configuration only, allows the user to specify a target host where the API will execute. On a Central Manager (CM) the value is the host name or IP of any managed units. On a managed unit it is the host name or IP of the CM.

Example

a1.corp.com> grdapi encrypt_value valueToEncrypt="some value" key=guard
ID=0
-----BEGIN PGP MESSAGE-----
Version: GnuPG v1.4.7 (GNU/Linux)
jA0EAgMCTEIUShudn0tgyTB9GL7wR79UL9X9DCAa6RkUQRbegG52olA4gwOzmpHF
0qEhsd6Uz7l8rUsheUyX9v4=
=c1Cq
-----END PGP MESSAGE-----

Copy the generated content and embed within your CLI script.

example of cli.gsh  code :
set guiuser johny_smith password 3wel9s887s
 grdapi create_datasource type=oracle name=myOra host=somehost application=AuditTask owner=admin user=sa serviceName=ora encryptedParam=password
-----BEGIN PGP MESSAGE-----
Version: GnuPG v1.4.7 (GNU/Linux)
jA0EAgMCTEIUShudn0tgyTB9GL7wR79UL9X9DCAa6RkUQRbegG52olA4gwOzmpHF
0qEhsd6Uz7l8rUsheUyX9v4=
=c1Cq
-----END PGP MESSAGE-----

Run the script to invoke GrdApi:

user> ssh cli@a1.corp.comuser> ssh cli@a1.corp.com

Role validation 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.

For example, a user with the appropriate roles for Policy Builder can run the delete_rule API on any policy, regardless of the roles of this specific policy.

If you try to run an API for which you do not have the appropriate role or permissions, the CLI returns an error message.

Display attributes for certain users in Query-Report Builder

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

There are some entities (such as FULL SQL) that have large numbers of attributes in them. By default, all attributes display for all users (admin and non-admin).

Two GuardAPI commands, enable_special_attributes and disable _special_attributes determine whether certain attributes display for certain users. For more information, see enable_special_attributes and disable_special_attributes.

Note: When using GuardAPI in a central manager environment, be sure that you understand which components are defined on the central manager, and which components are defined on managed units. For information, see Central Management.