update_engine_config

Use the update_engine_config command to change inspection engine settings.

An inspection engine monitors the traffic between servers and clients by using a specific database protocol (such as Oracle or Sybase). Configure an inspection engine from the Inspection Engine Configuration page. After the inspection engine is configured, you can use the update_engine_config command to change the parameters. For more information, see Configuring inspection engines.

This API is available in Guardium V11.0 and later.

REST API syntax

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

GuardAPI syntax

update_engine_config parameter=value

Parameters

See Inspection Engine Configuration for details about each parameter.

Parameter Value type Description
computeAverage Boolean When enabled, for each SQL construct logged, the average response time is computed. Valid values:
  • 0 (false)
  • 1 (true)
defaultAutoCommit Boolean Due to various auto-commit models for different databases, this value is used by Replay function to explicitly mark up the transactions and auto commit after each command. When enabled, commits and rollbacks are ignored. Databases currently supported include DB2®, Informix®, and Oracle. Valid values:
  • 0 (false)
  • 1 (true)
defaultCapture Boolean Used by Replay function to distinguish between transactions and capture values, meaning that if you have a prepared statement, assigned values are captured and replayed. Enable this if you want to replay your captured prepared statements as prepared statements. Valid values:
  • 0 (false)
  • 1 (true)
excludePorts String A list of ports to be ignored. Add values to this list if you know your database servers are processing non-database protocols, and you don't want Guardium® to waste cycles analyzing non-database traffic. For example, if you know the host on which your database resides also runs an HTTP server on port 80, you can add 80 to the ignored ports list, ensuring that Guardium does not process these streams. Separate multiple values with commas, and use a hyphen to specify an inclusive range of ports. For example: 101,105,110-223
granularity Integer The number of minutes in a logging unit. If requested in a report, Guardium summarizes request data at this granularity. For example, if the logging granularity is 60, and a certain request occurred "n" times in a given hour. If disabled, the exact time when the command occurred within the hour is not recorded. But, if a rule in a policy is triggered by a request, a real time alert can indicate the exact time. When you define exception rules for a policy, those rules can also apply to the logging unit. For example, you might want to ignore 5 login failures per hour, but send an alert on the sixth login failure. Valid values:
  • 1
  • 2
  • 5
  • 10
  • 15
  • 30
  • 60
inspectData Boolean When enabled, data returned by SQL requests are inspected, and the ingress and egress counts are updated. If rules are used in the security policy, this parameter must be enabled. Valid values:
  • 0 (false)
  • 1 (true)
logExceptionSql Boolean If enabled, when exceptions are logged, the entire SQL statement is logged. Valid values:
  • 0 (false)
  • 1 (true)
logRecords Boolean When enabled, the number of records affected is recorded for each SQL statement (when applicable). Valid values:
  • 0 (false)
  • 1 (true)
Default = 0

The records affected option is a sniffer operation which requires sniffer to process additional response packets and postpone logging of impacted data. This increases the buffer size and might potentially have an adverse effect on overall sniffer performance. Significant impact comes from really large responses. To prevent large amount of overhead associated with this operation, Guardium uses a set of default thresholds that allows sniffer to decide to skip processing operation when exceeded.

Refer to Configuration and Control CLI Commands store max_results_set_size, store max_result_set_packet_size and store max_tds_response_packets, to set levels of granularity.

Records Affected feature is not supported for:
  • DB2 when streaming is used to send the results.
  • AWS
  • Couchbase
  • Hadoop integration
Example of result set values:
  • Case 1, record affected value, positive number. This represents correct size of the result set.
  • Case 2, record affected value, -2. This means number of records exceeded configurable limit (This can be tuned through CLI commands).
  • Case 3, record affected value, -1. This shows any unsupported cases of packets configurations by Guardium.
  • Case 4, record affected value, -2. If the result set is sent by streaming mode.
  • Case 5, record affected value, less than -2. Intermediate result during record count to update user about current value, ends up with positive number of total records. For example, the server returns 1000 records in 4 packets:
    • Packet #1 250
    • Packet #2 200
    • Packet #3 250
    • Packet #4 200

    Then records affected are reported as

    • Packet #1 -250
    • Packet #2 -500
    • Packet #3 -750
    • Packet #4 1000
logSequencing Boolean When enabled, a record is made of the immediately previous SQL statement, as well as the current SQL statement, provided that the previous construct occurs within a short enough time period. Valid values:
  • 0 (false)
  • 1 (true)
maxHits Integer When returned data is being inspected, indicate how many hits (policy rule violations) are to be recorded.
parseXml Boolean The Inspection Engine does not normally parse XML traffic. Enable to parse XML traffic. Valid values:
  • 0 (false)
  • 1 (true)
recordEmpty Boolean When enabled, sessions containing no SQL statements are logged. When disabled, these sessions are ignored. Valid values:
  • 0 (false)
  • 1 (true)
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

The following GuardAPI example changes three inspection engine parameters. 

grdapi update_engine_config defaultCapture=true logExceptionSql=false maxHits=32

If successful, the command returns the following information:

ID=0
ok