GuardAPI S-TAP® functions
Use these CLI commands to create, list, delete, restart, and set S-TAP functions.
create_stap_inspection_engine
Add an inspection engine to the specified S-TAP. S-TAP configurations can be modified only from the active Guardium® host for that S-TAP, and only when the S-TAP is online.
| Parameter | Value | Description |
|---|---|---|
stapHost |
Required. The host name or IP address of the database server on which the S-TAP is installed. |
|
protocol |
Required. The database protocol, which must be one of the these values: DB2® DB2 Exit (DB2 version 10) FTP Informix® Kerberos Mysql Netezza® Oracle PostgreSQL Sybase Teradata Teradata Exit (v10.1.3 and up) Windows File Share exclude IE Windows S-TAP hosts can also use the following protocols: MSSQL named pipes |
|
portMin |
Required (integer). Starting port number of the range of listening ports that are configured for the database. (Do not use large inclusive ranges, as this degrades the performance of the S-TAP.) |
|
portMax |
Required (integer). Ending port number of the range of listening ports for the database. |
|
teeListenPort teeRealPort |
Optional (integer). Not used for Windows. Under UNIX, replaced by the KTAP DB Real Port when the K-TAP monitoring mechanism is used. Required when the TEE monitoring mechanism is used. The Listen Port is the port on which the S-TAP listens for and accepts local database traffic. The Real Port is the port onto which S-TAP forwards traffic. |
|
connectToIp |
Optional (integer). The IP address for the S-TAP to use to connect to the database. Some databases accept local connection only on the “real” IP address of the machine, and not on the default (127.0.0.1). |
|
client |
Required. A list of Client IP addresses and corresponding masks to specify which clients to monitor. If the IP address is the same as the IP address for the database server, and a mask of 255.255.255.255 is used, only local traffic is monitored. A client address/mask value of 1.1.1.1/0.0.0.0 monitors all clients. (See the example.) |
|
encryption |
Optional. Activate ASO encrypted traffic where encryption=0 (no) or encryption=1 (yes). |
|
excludeClient |
Optional. A list of Client IP addresses and corresponding masks to specify which clients to exclude. This option enables you to configure the S-TAP to monitor all clients, except for a certain client or subnet (or a collection of these options). |
|
procNames |
For a Windows Server: For Oracle or MS SQL Server only, when named pipes are used. For Oracle, the list usually has two entries: oracle.exe,tnslsnr.exe. For MS SQL Server, the list is usually just one entry: sqlservr.exe. |
|
namedPipe |
Windows only. Specifies the name of a named pipe. If a named pipe is used, but nothing is specified here, the S-TAP retrieves the named pipe name from the registry. |
|
ktapDbPort |
Optional (integer). Not used for Windows. Under UNIX, used only when the K-TAP monitoring mechanism is used. Identifies the database port to be monitored by the K-TAP mechanism. |
|
dbInstallDir |
UNIX only. Enter the full path name for the database installation directory. For example: /home/oracle10 |
|
procName |
For a UNIX Server: For a DB2, Oracle, or Informix database, enter the full path name for the database executable. For example: /home/oracle10/prod/10.2.0/db_1/bin/oracle |
|
| procNames | Optional | |
db2SharedMemAdjustment db2SharedMemClientPosition db2SharedMemSize |
These three parameters are used for a DB2 inspection engine, only under the following conditions:
When these parameters are used, grdapi verifies only that the protocol is db2; it does not verify that the conditions have been met. See the DB2 Linux S-TAP Configuration Parameters topic for a detailed explanation of how to use these parameters. |
|
instanceName |
Optional (string). Used only for MSSQL or Oracle encrypted traffic. Either the MSSQL or ORACLE encryption flag must be turned on before this parameter can be used. |
|
informixVersion |
Informix Version. |
|
| ieIdentifier | Optional (string). | |
| interceptTypes | Optional (string). | |
api_target_host |
Optional parameter that specifies the target host(s) to execute the API. When
not specified, it defaults to the unit on which command is executed. Valid values:
Guardium V10.1 and 10.1.2: In a central management configuration only, specifies 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 create_stap_inspection_engine stapHost=192.168.2.118 protocol=Oracle portMin=1521 portMax=1521 dbInstallDir=/data/oracle10 procName=/data/oracle10/oracle/product/10.2.0/db_1/bin/oracle client=192.168.0.0/255.255.0.0 ktapDbPort=1521 Sometimes, when adding an inspection engine, a false message of Configuration rejected by S-TAP- see S-TAP event log for details, is displayed even though the configuration was not rejected and installed correctly.
Client IP/mask is required for UNIX S-TAP, optional for Windows S-TAP.
list_inspection_engines
Display the properties of all S-TAPs on the specified host, optionally for a specific database type only.
| Parameter | Value | Description |
|---|---|---|
stapHost |
Required. The host name or IP address of a database server on which S-TAPs are installed (and configured to report to this Guardium appliance). |
|
type |
Optional. If used, inspection engines for the specified database type only will be listed. Type must be one of the following: db2 informix mssql mssql-np oracle sybase |
|
api_target_host |
Optional parameter that specifies the target host(s) to execute the API. When
not specified, it defaults to the unit on which command is executed. Valid values:
Guardium V10.1 and 10.1.2: In a central management configuration only, specifies 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 list_inspection_engines stapHost=192.168.2.33 type=oracle
ID=20162
Stap Host: 192.168.2.33 - Not Active
oracle Inspection Engines:
name =ORACLE2
type =ORACLE
connect to IP=127.0.0.1
install dir = /home/oracle10
exec file = /home/oracle10/product/10.2.0/db_1/bin/oracle-guard
instance name = MSSQLSERVER
encrypted = no
port range = 1521 - 1521
tee listen port = null, tee rel port = 1521
client = 127.0.0.1/255.255.255.255
client = 192.168.0.0/255.255.0.0
name =ORACLE3
type =ORACLE
connect to IP=127.0.0.1
install dir = /home/oracle9
exec file = /home/oracle9/bin/oracle
instance name = MSSQLSERVER
encrypted = no
port range = 1521 - 1521
ok
list_staps
Display the database servers from which S-TAPs report to this Guardium system, optionally listing only the servers that have S-TAPs for which this Guardium system is the active host (that is, the one to which the S-TAP is sending data and the one from which the S-TAP configuration can be modified).
| Parameter | Value | Description |
|---|---|---|
onlyActive |
Optional (Boolean). Enter true, or omit this parameter, to list only those hosts having S-TAPs for which this Guardium system is the active host. Enter false to list all hosts on which S-TAPs have been configured to use this Guardium system as either a primary or secondary host. |
|
api_target_host |
Optional parameter that specifies the target host(s) to execute the API. When
not specified, it defaults to the unit on which command is executed. Valid values:
Guardium V10.1 and 10.1.2: In a central management configuration only, specifies 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 list_staps onlyActive=false
ID=0
staps:
stap host = FALCON
stap host = 192.168.2.33
stap host = 192.168.2.173
stap host = 192.168.2.248
stap host = jumbo
ok
delete_stap_inspection_engine
Remove an S-TAP inspection engine. This Guardium system must be the active host for the S-TAP from which the inspection engine will be removed.
| Parameter | Value | Description |
|---|---|---|
stapHost |
Required. The host name or IP address of the database server on which the S-TAP is installed. |
|
type |
Required. Identifies the type of inspection to be removed. Type must be one of the following: Cassandra, CouchDB, DB2, DB2 Exit, FTP, GreenPlumDB, Hadoop, HTTP, iSERIES, Informix, KERBEROS, MongoDB, MS SQL, mssql-np, Mysql, Named Pipes, Netezza, Oracle, PostgreSQL, SAP Hana, Sybase, Teradata, Teradata Exit (v10.1.3 and up), or Windows File Share |
|
sequence |
Required (integer). The sequence number of the inspection engine to be removed within the set of inspection engines of the specified type. You can use the grdapi list_inspection_engines command with the type option first, to verify the sequence number of the inspection engine to be removed. |
|
waitForResponse |
Optional. Specifies whether the API will wait for a response from the S-TAP. Valid values are 0 (do not wait) and 1 (wait for a response). The default is 1 when stapHost is a single host name or IP address and 0 in all other cases. |
|
api_target_host |
Optional parameter that specifies the target host(s) to execute the API. When
not specified, it defaults to the unit on which command is executed. Valid values:
Guardium V10.1 and 10.1.2: In a central management configuration only, specifies 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 delete_stap_inspection_engine stapHost=192.168.2.118 type=Oracle sequence=1 restart_stap
Restart an S-TAP inspection engine.
| Parameter | Value | Description |
|---|---|---|
stapHost |
Required. The host name or IP address of the database server on which the S-TAP is installed. |
|
api_target_host |
Optional parameter that specifies the target host(s) to execute the API. When
not specified, it defaults to the unit on which command is executed. Valid values:
Guardium V10.1 and 10.1.2: In a central management configuration only, specifies 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 restart_stap stapHost=192.168.2.118 set_stap_debug
Filter log content by database, protocol, client information, instead of dumping all traffic to the log.
function parameters :
stapDebugInterval - required
stapDebugLevel - required
stapDebugOn - required
stapHost - required
api_target_host
store_stap_approval
Use this function to block unauthorized S-TAPs from connecting to the Guardium system.
If ON, then S-TAPs can not connect until they are specifically approved.
If an unapproved S-TAP connects, it is immediately disconnected until the specific authorization of the IP address of that S-TAP.
There is a pre-defined report for approved clients, Approved TAP clients. It is available on the Daily Monitor tab.
A valid IP address is required, not the host name.
The store_stap_approval command does not work within an environment where there is an IP load balancer.
Within a Central Managed environment, after adding the IP addresses to approved S-TAPs, there is a wait time associated with synchronization that might take up to an hour. After synchronization is complete, the status of the approved S-TAP will appear green in the GUI.
Function: store_stap_approval
function parameters :
isNeeded - Boolean - required
api_target_host - String
Syntax
grdapi store_stap_approval ON | OFF
CLI command
store stap approval and show stap approval
add_approved_stap_client
Use this GuardAPI command to add an approved S-TAP client.
Use of this GuardAPI command does not restart the sniffer and does not affect already connected S-TAPs. This command affects only new S-TAP connections.
Function: add_approved_stap_client
function parameters :
stapHost - String - required
api_target_host - String
Syntax
grdapi add_approved_stap_client <stapHost>
list_approved_stap_client
Use this GuardAPI command to list approved S-TAP clients.
Function: add_approved_stap_client
function parameters :
api_target_host - String
Syntax
grdapi list_approved_stap_client
list_stap_verification_results
Use this GuardAPI command to list S-TAP verification results.
function parameters:
stapHost - String. The host name or IP address of the database server on which the S-TAP is installed.
Syntax
grdapi list_stap_verification_results <stapHost>
delete_approved_stap_client
Use this GuardAPI command to remove an approved S-TAP client.
Use of this GuardAPI command does not restart the sniffer and does not affect other already connected S-TAPs. This command affects only the specified S-TAP connections.
Function: add_approved_stap_client
function parameters :
stapHost - String - required
api_target_host - String
Syntax
grdapi delete_approved_stap_client <stapHost - String - required>
set_ktap_debug
ID=0
function parameters :
ktapDebugInterval - required
ktapFunctionNames
stapHost - required
api_target_host
display_stap_config
Display all the properties of all S-TAPs on the specified host.
| Parameter | Value | Description |
|---|---|---|
stapHost |
Required. The host name or IP address of a database server on which S-TAPs are installed and
configured to report to this Guardium
system, or a comma-separated list of host names or IP addresses. You can also use these values:
|
|
grdapi display_stap_config stapHost=myhost1,myhost2
grdapi display_stap_config stapHost=all_activeupdate_stap_config
Update properties of all S-TAPs on the specified host.
| Parameter | Value | Description |
|---|---|---|
| stapHost | Required. The host name or IP address of a database server on which Guardium
system, or a comma-separated list of host names or IP addresses. You can also use these values:
|
|
| updateValue | Required. One or more key-value pairs, in this format: section.parameter_name:new_value. section indicates the section of the guard_tap.ini file in which the parameter is contained, and can be TAP or DB_x, where DB_x is a designation for an inspection engine that appears as a section header in the file. You can specify new values for multiple parameters by separating the entries with an ampersand (&) . | |
| waitForResponse | Optional. Specifies whether the API will wait for a response from the S-TAP. Valid values are 0 (do not wait) and 1 (wait for a response). The default is 1 when stapHost is a single host name or IP address and 0 in all other cases. |
grdapi update_stap_config stapHost=all_windows_active updateValue=TAP.XXXXverify_stap_inspection_engine_with_sequence
Use this command to verify the S-TAP inspection engine.
| Parameter | Value | Description |
|---|---|---|
| addToSchedule | String. Constant values list; valid values are Yes and No. | |
| datasourceName | String. If this parameter is specified, advanced verification is performed against the specified datasource. If this parameter is omitted, standard verification is performed. | |
| sequence | Required. Integer. The sequence number of the existing inspection engine for verification. You can use the grdapi list_inspection_engines command with the type option first, to verify the sequence number of the inspection engine to be verified. | |
| stapHost | Required. String. The host name or IP address of the database server on which the S-TAP is installed. | |
| protocol | Required. The database protocol, which must be one of the these values: DB2, DB2 Exit (DB2 version 10), FTP, Informix, Kerberos, Mysql, Netezza, Oracle, PostgreSQL, Sybase, Teradata, Teradata Exit (v10.1.3 and up), exclude IE. Windows S-TAP hosts can also use the following protocols: MSSQL, named pipes. |
grdapi verify_stap_inspection_engine_with_sequence stapHost=9.70.144.212
sequence=3revoke_ignore_stap
This command revokes existing IGNORE S-TAP SESSION (REVOKABLE) policy rule actions that ignore S-TAP session traffic. This command only revokes soft ignore rules (marked as REVOKABLE) and cannot revoke hard rules (not marked as REVOKABLE).
| Parameter | Value | Description |
|---|---|---|
| stapHost | Required. The host name or IP address of a database server on which S-TAPs are
installed and configured to report to this Guardium
system, or a comma-separated list of host names or IP addresses. You can also use these values:
|
|
| api_target_host |
Optional parameter that specifies the target host(s) to execute the API. When
not specified, it defaults to the unit on which command is executed. Valid values:
Guardium V10.1 and 10.1.2: In a central management configuration only, specifies 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 revoke_ignore_stap stapHost=myhost1set_ztap_logging_config
This command controls the logging parameters described below.
Syntax: grdapi set_stap_logging_config parameter=[parameter] value=[value].
| Parameter | Value | Description |
|---|---|---|
| log_db2z_target | 0 to disable 1 to enable Parameter is disabled by default. |
When enabled using log_db2z_target=1, targets in db2z protobuf message are logged to GDM_OBJECT in addition to objects from the parser. |
| log_zkey_to_full_sql | 0 to disable 1 to enable Parameter is disabled by default. |
When enabled using log_zkey_to_full_sql=1, VSAM or IMS Key values will be logged in the full SQL statement for policies using "Log full details." |
grdapi set_ztap_logging_config parameter=log_db2z_target value=1Show values: grdapi get_ztap_logging_config.