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.
- From the CLI, log in as one of the guardclin users (that is, guardcli1 to guardcli5
- 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
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: okNote: 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: okNote: 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 okNote: 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
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
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
- 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,
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=" "
The GuardAPI always returns a code in the first line of output, in one of the following formats:
|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.
|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.
- Every command entered.
- Any changes made.
- The IP address from which the command was issued.
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.
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.
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 email@example.com> ssh firstname.lastname@example.org
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.