create_stap_inspection_engine

This command adds 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.

This API is available in Guardium V9.5 and later.

REST API syntax

This API is available as a REST service with the POST method. Call this API as follows: 
POST https://[Guardium hostname or IP address]:8443/restAPI/inspection_engine

GuardAPI syntax

create_stap_inspection_engine parameter=value

Parameters

Parameter Value type Description
client String Restricts S-TAP to monitor traffic only from the specified sets of IP address and mask pairs, by using a list of addresses in IP address/mask format: n.n.n.n/m.m.m.m. If an improper IP address/mask is entered, the S-TAP does not start. Valid values:
  • User-defined list
  • 0.0.0.0/0.0.0.0,::/0: select all clients.
  • 127.0.0.1/255.255.255.255,::1/0: local traffic only
Client Ip/Mask (networks) and Exclude Client Ip/Mask (exclude networks) cannot be specified simultaneously.
connectToIp String IP address for S-TAP to use to connect to the database. Some databases accept local connection only on the real IP address of the Guardium system, and not on the default (127.0.0.1,::1). When K-TAP is enabled, this parameter is used for Solaris zones and AIX® WPARs. Set it to the zone IP address to capture traffic.
db2SharedMemAdjustment Integer Required when Db2® is selected as the database type, and shared memory connections are monitored. The offset to the server's portion of the shared memory area. Offset to the beginning of the Db2 shared memory packet, depends on the Db2 version: 32 in pre-8.2.1, and 80 in 8.2.1 and higher.
db2SharedMemClientPosition
(DB2® only)		 Integer The offset to the client's portion of the shared memory area. Required when Db2 is selected as the database type, and shared memory connections are monitored. Linux: Use the script find_db2_shmem_parameters.sh to find the value. The script is located in stap_directory/bin, and outputs what the Db2 shared memory parameters that are defined in the Inspection Engines should be. Run it either as root or Db2 user, by using the syntax: find_db2_shmem_parameters.sh <instance name>. You can run it from any directory.
Windows: The client offset can be calculated by taking the value of the Db2 parameter ASLHEAPSZ and multiplying by 4096 to get the appropriate offset. The default for this parameter is 61440 decimal. This parameter is calculated by taking the Db2 database configuration value of ASLHEAPSZ and multiplying by 4096. To get the value for ASLHEAPSZ, erunxecute the following Db2 command: db2 get dbm cfg and look for the value of ASLHEAPSZ. This value is typically 15, which yields the 61440 default. If it's not 15, take the value and multiply by 4096 to get the appropriate client offset.
db2SharedMemSize Integer Db2 shared memory segment size. Required when Db2 is selected as the database type, and shared memory connections are monitored.
dbInstallDir
(Linux only)		 String
  • Db2, Informix®: The full path name for the database installation directory.
  • Db2 exit and Informix exit: value must be the same as the $HOME value in the database (or $Db2_HOME for Db2 Exit); otherwise tap_identifier does not function properly.
  • Oracle: Database owner HOME directory. It must match db_base in the ATAP configuration. See Oracle-specific guardctl parameters.
  • All other database types: NULL.
dbUser String OS username (case-sensitive) of the owner of the DB server process (for example, oracle). This parameter specifies which user is allowed to use the db_request_handler socket. It is required if you are not using the user root. If set to an invalid value, A-TAP cannot access the socket to retrieve permission for accessing K-TAP. In this case, it requires authorization with a group membership to log decrypted traffic to K-TAP (by using the guardctl authorize-user command). You can define a comma-separated string of multiple users.
dbVersion String The database version. The string must start with a numeral and not a letter.
encryption
(Linux only)		 Boolean Valid values:
  • 0: Unencrypted
  • 1: Encrypted
Default = 0 (false)

Activate ASO or SSL encrypted traffic for Oracle (versions 11 and 12) and Sybase on Solaris, HPUX, and AIX.

For Oracle, specify db_version in the guard_tap.ini file (for example, db_version=12)

For Oracle12 SSL, instrument on all platforms. For Oracle11 SSL, instrument on AIX.

For any Oracle requiring instrumentation, if you are using encryption=1 in the guard_tap.ini (which is not supported on Linux®), you must instrument before setting that parameter.

Some DBs require restart after enabling encryption.

When using GIM to configure the S-TAP, GIM_ROOT_DIR must be set to the absolute path to the modules, for example /usr/local/guardium/modules
excludeClient String A list of client IP addresses and corresponding masks that are excluded from monitoring. Use this option to configure the S-TAP to monitor all clients, except for a certain client or subnet (or a collection thereof). Client Ip/Mask (networks) and Exclude Client Ip/Mask (exclude networks) cannot be specified simultaneously.
ieIdentifier String Used to distinguish inspection engines from one another. If unspecified, Guardium auto-populates the field with a unique name that uses the database type and sequence number.
informixVersion Integer Informix version.
instanceName
(Windows only)		 String The name of the database instance on this server. Required for MS SQL Server that uses encryption; MS SQL Server that uses Kerberos Authentication; Db2 Exit traffic collection; Db2 SHM traffic. (Default is MSSQLSERVER.)
interceptTypes
(Linux only)		 String DO NOT change this parameter unless it is absolutely necessary. Protocol types that are intercepted by the IE. Valid values:
  • NULL: auto intercepts all protocols the Database supports
  • Comma-separated list: IE intercepts these protocol types only.
ktapDbPort
(Linux only)		 String With K-TAP and PCAP, identifies the database port or range of ports to be monitored. For exit libraries, use its value for db_home.
namedPipe
(Windows only)		 String Specifies the named pipe that is used by MS SQL Server local access. If a named pipe is used, but nothing is specified in this parameter, S-TAP attempts to retrieve the named pipe name from the registry.
portMax String For monitoring network traffic only, the highest numbered port on which to listen for database traffic.
portMin String For monitoring network traffic only, the lowest numbered port on which to listen for database traffic. Together with portMax, this parameter defines the range of ports that are monitored for this database instance. Usually the range contains only a single port. For a Kerberos inspection engine, set the start and end values to 88-88. If a range is used, do not include extra ports in the range. Extra ports might result in excessive resource consumption while the S-TAP attempts to analyze unwanted traffic.
Examples:
To monitor range 1521-1525 (five ports) with no port forwarding:
  • portMin=1521
  • portMax=1525
  • ktapDbPort=1521
To monitor range 2000-2004 (5 ports) where network port 2000 is mapped to local port 1521:
  • portMin=2000
  • portMax=2004
  • ktapDbPort=1521
priorityCount Integer Reduces the instances of a blank DB_USER or ? in the tables. At session creation, the first priority_count packets are marked with a high priority flag and are transferred to a special high priority queue on the collector. Valid values:
  • 0: Disabled
  • Protocol 7: 1-2048: Number of packets
  • Protocol 8: positive integer: Number of packets
Default = 20
procName
(Linux only)		 String The value of this parameter depends on whether it's in an exit, and whether there is A-TAP.
  • Exit libraries: see Configuring Exit libraries
  • With A-TAP: see Database-specific guardctl parameters
  • Without A-TAP: The full path name for the database executable. For example:
    • Oracle: /$ORACLE_HOME/bin/oracle
    • Informix: /INFORMIXTMP/.inf.sqlexec. Applies to all Informix platforms but Linux.
    • Informix with Linux, example: /home/informix11/bin/oninit
    • MYSQL: mysql
procNames
(Windows only)		 String Database service executables that are to be monitored. For example, a Db2 IE would be TAP_DB_PROCESS_NAMES=Db2SYSCS.EXE. 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 one entry: sqlservr.exe.
protocol String Required. The type of data repository that is monitored.
Linux-UNIX: ASTERDB, Cassandra, CockroachDB, CouchDB, Db2, Db2 Exit, ElasticSearch, exclude IE, FTP, GreenplumDB, HADOOP, HIVE, HP-Vertica, HTTP, HUE, IMPALA, Informix, Informix Exit, KERBEROS, MariaDB, MemSQL, MongoDB, Mysql, Netezza®, Oracle, PostgreSQL, REDIS, SAP Hana, Sybase, Teradata, Teradata Exit, WebHDFS, Windows File Share
Windows: ASTER, Cassandra, CouchDB, Db2, Db2 Exit, exclude IE, FTP, GreenplumDB, HIVE, HTTP, HUE, IMPALA, Informix, Informix Exit, MariaDB, MongoDB, MSSQL, Mysql, Oracle, PostgreSQL, Sybase, Teradata, WebHDFS, Windows File Share.
stapHost String Required. The host name or IP address of the database server on which the S-TAP is installed.
teeListenPort String Deprecated. Replaced by the parameter real_db_port when the K-TAP monitoring mechanism is used.
teeRealPort String Deprecated.
unixSocketMarker(Linux only) String Specifies UNIX domain sockets marker for Oracle, MySQL, and Postgres. Usually the default is correct, but when the named pipe or UNIX domain socket traffic does not work then you need to make sure that this value is set correctly. For example, for Oracle, set unix_domain_socket_marker to the KEY of IPC defined in tnsnames.ora. If it is NULL or not set, the S-TAP uses defined default markers identified as: * MySQL - "mysql.sock" * Oracle - "/.oracle/" * Postgres - ".s.PGSQL.5432"
api_target_host String

Specifies the target hosts where the API executes. Valid values:
  • all_managed: execute on all managed units but not the central manager
  • all: execute on all managed units and the central manager
  • group:<group name>: execute on all managed units identified by <group name>
  • host name or IP address of a managed unit: specified from the central manager to execute on a managed unit.  For example, api_target_host=10.0.1.123.
  • host name or IP address of the central manager: specified from a managed unit to execute on the central manager. For example, api_target_host=10.0.1.123.

IP addresses must conform to the IP mode of your network. For dual IP mode, use the same IP protocol with which the managed unit is registered with the central manager. For example, if the registration uses IPv6, specify an IPv6 address. The hostname is independent of IP mode and can be used with any mode.

Examples

To create an inspection engine on an MYSQL database with IP 127.0.0.1:

grdapi create_stap_inspection_engine connectToIp=127.0.0.1 db2SharedMemAdjustment=80 db2SharedMemClientPosition=0 db2SharedMemSize=131072 procName=/home/mysq57/mysql/bin/mysqld dbInstallDir=/home/mysql57 protocol=Mysql dbUser=mysq57 encryption=0 dbVersion=9