GuardAPI Reference Overview

GuardAPI Overview

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.

GuardAPI is a set of CLI commands, all of which begin with the keyword grdapi. To list all GuardAPI commands available, enter the command with no arguments. To display the parameters for a particular command, enter only part of the command. For example:

g4.guardium.com> grdapi list_entry_location

ID=0

function parameters :

fileName

hostName - required

path - required

ok

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" ...

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:

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, below, and following each command description, there is a description of errors for that command.

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

g3.guardium.com> grdapi create_group desc=agroup type=objects appid=Public

ID=20001

ok

g3.guardium.com>

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

g3.guardium.com> 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:

g3.guardium.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 lower than 100 are for common error conditions, as described below. Error codes higher than 100 apply to specific functions, and those are described following each function.

ERR

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 GrdApi with no function name and no parameters.

3

Too many arguments.
To get the list of parameters for this function call the function with no parameters

4

Missing required parameter.
To get the list of parameters for this function call the function with no parameters.

5

Could not decrypt parameter - check if key belongs to SqlGuard machine.

6

Wrong parameter format - specify 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.

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.

Encrypted Parameter

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.

The parameter must be encrypted using the target Guardium appliance's public key.

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

Note that the encrypted value is only valid for the specific Guardium appliance whose public key was used to encrypt it.

The following procedure explains how to use generate a public key and use an encrypted parameter.

  1. Log on to the Guardium appliance as the cli user and run the following command to generate a public key for this appliance:

  2. After the required keys are generated, run the following command:

  3. Copy the generated public key output (including the BEGIN and END lines)

  4. Import the public key into your local machine key-ring, by entering the following command:

  5. Encrypt the sensitive information (e.g., the password) using the imported public key:

  6. Embed the encrypted password in your script file:

  1. Run the script to invoke GrdApi:

Central Management Caution

When using GuardAPI in a Central Management environment, be sure that you understand what components are defined on the Central Manager, and what components are defined on managed units (See the Overview topic in the Aggregation & Central Management help book.)