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:
  1. From the CLI, log in as one of the guardclin users (that is, guardcli1 to guardcli5 ). For example:
  2. 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:> set guiuser Hadrian.Swall
    Enter current password:
    First login as Hadrian.Swall. Please change the default password.
    Enter new password:
    Re-enter new password:
    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.

  3. 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:> 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 
    Enter SMS passcode:
    Note: The available notification methods depend on how multi-factor authentication is configured for your site.
  4. 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 
    > 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
    function parameters :
    hostName - required
    path - required
    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:
    Audit Process Builder
    DB2 zOS Groups
    Express Security
    IMS zOS Groups
    Policy Builder
    Security Assessment Builder
  • To search for GuardAPI commands given a search string use grdapi commands <search-string>. For example:
    CLI> grdapi commands user
    Matching API Function list :

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

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

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:> grdapi list_group_by_id id=20123
Could not retrieve Group - check Id.

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:

  1. 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.> grdapi encrypt_value --help=true
    function parameters :
    key - required
    valueToEncrypt - required
    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> grdapi encrypt_value valueToEncrypt="some value" key=guard
    -----BEGIN PGP MESSAGE-----
    Version: GnuPG v1.4.7 (GNU/Linux)
    -----END PGP MESSAGE-----
  2. 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)
    -----END PGP MESSAGE-----
  3. Run the script to invoke GrdApi:
    user> ssh cli@a1.corp.comuser> ssh

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.