Information Management

GuardAPI Automation
InfoSphere Guardium Technical Document
Contents

1.OVERVIEW..........................................................................................................3

2.GRDAPI ENTITLEMENTS..................................................................................3

3.GRDAPI AUTOMATION USE CASES................................................................8

4.GRDAPI AND SSH AUXILIARY TOOLS............................................................9

4.1INSTALLING SSHPASS.................................................................................10

2
1. Overview

This techdoc explains a scripting method that allows the user to quickly automate
and schedule the execution of GuardAPI commands from remote server.
Smaller implementations of Guardium can be accomplished easly through the GUI, but
for large installations, a scripting method can save quite a bit of time eg. changing or
installing inspection-engines for 100 servers. If we can not run some tasks at the present
moment, we can easily also schedule script to run on the collector using auxiliary tools
for ssh. Let's imagine the situation in your company that we have centralized scheduling
server, which is a cron service on the linux box. Then if we would like to issue GuardAPI
commands we have to use ssh tool to log in as CLI user or other account to the
collector remotely. As we know SSH can not be used itself in non-interactive mode
without providing password manually to log in. For this purpose we need auxiliary
programs, which can capture interaction with ssh inserting parameter(s) like password to
automate connection process and fire a script. No other methods at this time like
exchange of the generated encryption keys or collector's internal cron can be applied to
issue self-prepared GuardAPI commands in scheduled time and with some frequence.

2. Grdapi entitlements
This section provides knowledge how to set and tailor entitlements before using
grdapi in guardium administration. Guardium is designed for automation administration
tasks from command line interface, which in some situations is definitely faster than
using GUI and Grdapi commands can be executed only through the CLI (Command
Line Interface). Most of those commands are associated with a specific application and
therefore with the roles. Having the standard CLI user (who has a hard coded 'admin'
role and is used as default) we cannot run many of the grdapi commands because it
doesn't have the appropriate roles. Of course we can grant other functions
(applications) to admin role, it is doable, but this is not best practice in the companies,
especially in the corporations. Besides CLI user, guardium is shipped with five additional
CLI accounts (guardcli1, guardcli2, guardcli2, guardcli4, guardcli5) for separate
administration duties as we decide to use them.
If we log in first time to the collector for one of the mentioned users, the default password
for each is 'guardium' and first logging forces us to change it.

3
CLI account always is associated with guardium GUI user, who has appropriate access
to the functions and applications of the guardium. As was mentioned CLI is assigned
'admin' role in the code of the system, but other guardcli1,...,guardcli5 users must first
set gui user before issuing any grdapi commands.
set guiuser <gui_user> password <password>
if we don't do that after logging we will not able to issue any commands and we get
following message:

For our purpose access manager (accessmgr) can define as many users in the system
and give them the CLI role. These users will have access to the CLI and all activities of
their CLI sessions are associated with this user.

Example: Setting of the gui user without CLI role assigned

If the gui user attempting to use CLI has a "CLI" role, CLI will start and we
can use grdapi commands according to assigned entitlements.

4
Let's see how it works switching gui users and what gradpi commands are accessible for
each of these users with different roles. We will be changing between 3 users (roles):
robert (cli), admin (admin) and accessmgr (accessmgr). Each of them will issue the
same command to compare access to guardium API functions:

grdapi commands user

- this instruction looks for the functions containing specific string as input, in our
example 'user'
CLI role:

Admin role:

5
Accessmgr role:

According to the above print screens, accessmgr role is responsible for management of
users and gets access to bunch of these grdapi commands to manage them and their
entitlements. Those commands can be run only by users with this role. For instance of
Admin and CLI roles, they don't have such capability and can be used for other
operations and administration taks.
Finally let's check what other possibilities using grdapi has got CLI role if we know it
cannot be used to manage users, bc we already know it's a feature of guardium to
separate duties. To do that we can issue simply:
grdapi commands

It's is going to list all available API functions:

6
]

Summarizing topic, to use grdapi commands we have to fulfill two prerequisites,

create a gui user and make sure to assign the proper entitlements and use predefined
guardium cli user who has capability to switch immediate user using 'set guiuser'
depending on required situation to issue commands.
Note! Option 'set guiuser' is not available for standard CLI user, who can only act
with 'admin' role. Changing entitlements for admin role we change also privileges
for standard CLI user.

7
3. Grdapi automation use cases
Grdapi is a great functionality which saves a lot of time in deploying changes for large
installation. Let's imagine that for some reason company is forced to change network
settings, update inspection-engines or turn on different debug levels for troubleshooting.
Are we going to do that manually from GUI let's say for 100 servers ? The answer
comes immediately, NO! For that purpose we can use grdapi scripting and automate
certain tasks.

Let's see few examples of implementation:

1. Setup debugging level to run for specific time period for all agents in few
seconds

grdapi set_stap_debug stapHost=10.10.9.22 stapDebugOn=1 stapDebugLevel=4

stapDebugInterval=60

grdapi set_stap_debug stapHost=10.10.9.25 stapDebugOn=1 stapDebugLevel=4

stapDebugInterval=60

grdapi set_stap_debug stapHost=10.10.9.28 stapDebugOn=1 stapDebugLevel=4

stapDebugInterval=60

grdapi set_stap_debug stapHost=10.10.9.100 stapDebugOn=1 stapDebugLevel=4

stapDebugInterval=60

Value-added: We don't have to change a debug level for a short time for each agent
through the GUI manually, because we would like to troubleshoot some activity For
large installation it is even impossible to reach this situation and not exaggerating it
could take even few days , that way we can loose objective of our research. This is
possible only with a scripting method which can save our precious time and to help
getting the goal.

2. Rapid and easy Inspection engines deployment

grdapi delete_stap_inspection_engine stapHost=10.10.9.28 type=Oracle sequence=1

grdapi delete_stap_inspection_engine stapHost=10.10.9.29 type=Oracle sequence=1
grdapi delete_stap_inspection_engine stapHost=10.10.9.30 type=Oracle sequence=1

8
grdapi create_stap_inspection_engine stapHost=10.10.9.28 protocol=Oracle
portMin=1521 portMax=1521 dbInstallDir=/home/oracle/product/10.2.0/ora10
grdapi create_stap_inspection_engine stapHost=10.10.9.29 protocol=Oracle
portMin=1521 portMax=1521 dbInstallDir=/home/oracle/product/10.2.0/ora10
grdapi create_stap_inspection_engine stapHost=10.10.9.28 protocol=DB2
portMin=1521 portMax=1521 dbInstallDir=/home/oracle/product/10.2.0/ora10
grdapi delete_stap_inspection_engine stapHost=192.168.2.118 type=Oracle
sequence=1

Value-added: Changing configuration for large installation is definitely easier and faster.

3. Agent maintenance - restarting

grdapi restart_stap stapHost=10.10.9.21
grdapi restart_stap stapHost=10.10.9.22
grdapi restart_stap stapHost=10.10.9.25
grdapi restart_stap stapHost=10.10.9.26
grdapi restart_stap stapHost=10.10.9.28
…
…
grdapi restart_stap stapHost=10.10.9.144
grdapi restart_stap stapHost=10.10.9.145

Value-added: Administration and maintenance of guardium using grdapi automation is

getting very easy and efficient.

4. GrdApi and SSH auxiliary tools

According to our scenario we can distinguish two tools which can be used in
grdapi automation and remote administration tasks, such as SSHPASS or EXPECT.
First tool SSHPASS is for non-interactively performing password authentication with
SSH's so called "interactive keyboard password authentication".
Second of them EXPECT is a Linux/Unix automation and testing tool as an extension to
the Tcl scripting language, for interactive applications such as telnet, ftp, passwd, fsck,
rlogin, tip, ssh, and others.
Of course in both tools have the same usage, therefore we will show application only the
sshpass in the next subsection.

To accomplish this small lab we will use following credentials for our virtual machines:

9
Login for dataserver:
user: guard
password: password

Login for collector :

user: cli
password: guardium

4.1 Installing SSHPASS

Following topic describes step by step how to implement SSHPASS in

conjunction with ssh. We assume that SSHPASS is already downloaded from the
website http://sourceforge.net/projects/sshpass
All grdapi commands during this exercise are issued by CLI user, so we don't have to
use 'set guiuser' option.

1. Let's install SSHPASS first which we will use later for login automation to the
collector or aggregator.

Open console Gnome Terminal double clicking on icon on the Desktop or other
localization

go to ~guard/Scripts/ directory, untar and decompress sshpass sources

cd ~guard/Scripts/
tar zxvf sshpass-1.04.tar.gz

10
Next, we'd like to compile and install our package. To do that change your folder to
sshpass-1.04/ and issue following commands

cd sshpass-1.04/
./configure
make
sudo make install

when asked for root password type password

2. Let's now prepare our script Grdapi_commands.txt which will be used as a set
of grdapi commands and an input for scheduler. In our case we are going to restart
STAP on the selected host.

cd ~guard/Scripts/

echo "grdapi restart_stap stapHost=10.10.9.28" >> Grdapi_commands.txt

Make sure we created script Grdapi commands.txt properly issuing

cat Grdapi_commands.txt

And you should see following output

3. Now we would like to prepare command using sshpass to automate non-interactive

logging to the collector and to make it more elegant we put entire instruction into the
shell script Grdapi_autologin.txt which will be executed from a cron.

11
Follow with the instructions:
cd ~guard/Scripts/
vi Grdapi_autologin.txt
press [ESCAPE] and “i”, rewrite or copy/paste the 2 lines below

#!/bin/sh
/usr/local/bin/sshpass -p 'guardium' ssh [email protected] <
/home/guard/Scripts/Grdapi_commands.txt

Next, press [ESCAPE] and :wq [ENTER]

chmod +x Grdapi_autologin.txt

Let's check created file, you should see pasted 2 lines

cat Grdapi_autologin.txt

Note that provided password guardium for sshpass program will be passed to ssh after
establishing the connection.

To make sure that this command is correct let's run our script once from the console
If this is a first logging attempt it would be good to log manually using sshto the collector
to let generate ssh a RSA key and add host to the known hosts.

After that the above message will not appear anymore.

Launch sshpass -p 'guardium' ssh [email protected] <
/home/guard/Scripts/Grdapi_commands.txt
Now you should see following screen which means that command was issued
automatically, without interaction.

Finally fire ./Grdapi_autologin.txt script to check you receive the same result as above

12
As we can see command is invoked properly and we didn't have to provide password
also, it was done without interaction once again.

4. Now we are going to configure cron to run the script each 30 minutes on the
collector

Input configuration for cron looks as the following line:

*/30 * * * * /home/guard/Scripts/Grdapi_autologin.txt

To add this line we have to do few steps, first open crontab file:

crontab -e

press [ESCAPE] and “i”

rewrite or copy/paste the line

*/30 * * * * /home/guard/Scripts/Grdapi_autologin.txt

You should see following view. Note, there can be more existing entries, in our example
we have only one.

Let's close and save crontab file entering

press [ESCAPE] :wq [ENTER]

We'd like to make sure it is saved properly and to verify it

crontab -l

13
Congratulations ! Our GuardAPI command will be issued each 30 minutes on the
collector.
This is of course simple scenario how you may use GuardAPI commands which we
can to use in scheduled time. We can add more commands to our script
Grdapi_commands.txt for other purpose simplifying administration.

14
© Copyright IBM Corporation 2011
All Rights Reserved.

IBM Canada
8200 Warden Avenue
Markham, ON
L6G 1C7
Canada

IBM, the IBM logo, ibm.com and Tivoli are trademarks or

registered trademarks of International Business Machines
Corporation in the United States, other countries, or both. If
these and other IBM trademarked terms are marked on their
first occurrence in this information with a trademark symbol
(® or ™), these symbols indicate U.S. registered or common
law trademarks owned by IBM at the time this information
was published. Such trademarks may also be registered or
common law trademarks in other countries. A current list of
IBM trademarks is available on the Web at “Copyright and
trademark information” at ibm.com/legal/copytrade.shtml

Other company, product and service names may be

trademarks or service marks of others.

References in this publication to IBM products and services

do not imply that IBM intends to make them available in all
countries in which IBM operates.

No part of this document may be reproduced or transmitted

in any form without written permission from IBM
Corporation.

Product data has been reviewed for accuracy as of the date

of initial publication. Product data is subject to change
without notice. Any statements regarding IBM’s future
direction and intent are subject to change or withdrawal
without notice, and represent goals and objectives only.

THE INFORMATION PROVIDED IN THIS DOCUMENT IS

DISTRIBUTED “AS IS” WITHOUT ANY WARRANTY,
EITHER EXPRESS OR IMPLIED. IBM EXPRESSLY
DISCLAIMS ANY WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE OR NON-
INFRINGEMENT.

IBM products are warranted according to the terms and

conditions of the agreements (e.g. IBM Customer
Agreement, Statement of Limited Warranty, International
Program License Agreement, etc.) under which they are
provided.

15