The alert message template

Message templates determine the content of alerts. You can create multiple message templates from the Global Profile, and use them with different rules as required.

There are three types of message templates available, which define the following types of messages:
  • Audit process: Publish in audit process reports.
  • Real-time Alerts: Send an alert immediately when Guardium detects a problem.
  • Threshold Alerts: Send an alert when Guardium detects that a specified threshold is met or exceeded.

You can use the filtering checkboxes to filter the types of templates to view.

Several predefined message templates are available for ArcSight, enVision, and IBM QRadar (in LEEF format) security information and event management (SIEM) solutions. Guardium® includes two certified (agreed upon) templates to integrate with these SIEM solutions.

Creating or updating named messages

To add, modify, or delete named message templates:

  1. Click Edit to open the Named Template Finder window.
  2. Click New to open the Modify Named Template window. The current default message template displays in the Default message template text box.

    Alternatively, select one of the existing named templates and click Clone to clone that template. You can then rename and edit your new template.

  3. Enter a name and template type for your new template. Then, add or delete the message template variables to meet your requirements. For more information about the available message template variables, see Table 1.

    Select No wrap to see where the line breaks appear in the message.

  4. Click Save when you are done.
  5. Changes take effect after you restart the inspection engines from the managed unit.
    Note: To restart the inspection engines, browse to Manage > Activity Monitoring > Inspection Engines and then click Restart Inspection Engines.

Formatting real-time alerts

Customizing email for real-time alerts
Use the store alerter email append_name_subject and store alerter email append_subject_body CLI commands to customize emails from real-time alerts as follows:
  • Control the appearance of the Prefix email subject with Guardium appliance name.
  • Control the appearance of the email subject in the email body.
  • Add naming template parameter %%applianceHostName to add the appliance hostname to Name Templates (in either the subject or the body).
Setting sender encoding

To encode outgoing messages (email and SNMP traps) in an encoding scheme other than UTF8, use the store sender_encoding CLI command, as described in store sender_encoding.

Alert message template variables

Table 1. Alert message template variables
Variable Description
%%analyzedClientIP A client IP field populated by the Guardium Analyzer. Corresponds to GDM_ACCESS.ANALYZED_CLIENT_IP.
If the Analyzed Client IP is not available when the SQL event is processed:
  • If the policy rule action is set to Alert only and SYSLOG notification, then %%analyzedClientIp is blank.
  • A value for analyzedClientIp is not always available for encrypted Oracle traffic.
  • For any other alert policy rule actions, the alert message might be delayed and sent later in the session.
%%AppEventType The type of application event.
%%AppUserName Application username.
%%AuthorizationCode Authorization code.
%%BindVarVal Available for Db2 z/OS systems only. The bind variable value, which is replaced with the values from the "FULL SQL"."Bind Variables Values" in the FULL SQL entity. For more information, see the Attributes for Full SQL Entity (Db2 for z/OS) table.
%%category Category from the rule definition.
%%CICSUser Available for Db2 z/OS systems only. %%CICSUser is either:
  • The CICSEndUser.
  • The CICS user ID (same as %%EndUser), if the sysConType is CICS (value of 4).
%%classification Classification from the rule definition.
%%ClientAcctng Available for Db2 z/OS systems only. Contains information from the Db2 z/OS CURRENT CLIENT_ACCTNG special register. For more information, see the Special registers documentation for your version of Db2 for z/OS.
%%ClientApplname Available for Db2 z/OS systems only. Contains information from the Db2 z/OS CURRENT CLIENT_APPLNAME special register. For more information, see the Special registers documentation for your version of Db2 for z/OS.
%%clientHostname Client hostname.

For Db2 z/OS users: If the store snif_db2z_alert_use_client_ip_for_host_name CLI command is set to on, then %%clientHostname stores the client IP address. For more information, see store snif_db2z_alert_use_client_ip_for_host_name.
%%clientIP Client IP address.
%%clientPort Client port number.
%%ClientWrkstn Available for Db2 z/OS systems only. Contains information from the Db2 z/OS CURRENT CLIENT_WRKSTNNAME special register. For more information, see the Special registers documentation for your version of Db2 for z/OS.
%%compressed_uid_chain For Linux or UNIX systems only, the compressed UID chain that tracks a chain of users.

Messages that include this variable are delayed for 5 minutes by default. For more information, see the store alerter delay CLI command. The value is then replaced with the "Session"."Uid Chain Compressed" values from Guardium report attributes. For more information, see UID chains.

Note: This variable does not return a value when used with a message template, which uses an alert only policy rule action that specifies the syslog notification type. For more information, see Alerting rule actions.

%%ConstructID

 Construct ID in the SQL request associated with the alert message.
%%CurrentDBUser Available for Db2 for IBM® i only. %%CurrentDBUser is the name of the current Db2 for i user.
%%DBName Database name.
%%DBProtocol Database protocol.
%%DBProtocolVersion Database protocol version.

For Db2 z/OS users: %%DBProtocolVersion is populated only if your S-TAP version supports the DB Protocol Version parameter.
%%DBUser Database username.
%%EndUser Available for Db2 z/OS systems only. %%EndUser is either:
  • The Db2 application user.
  • The CICS user ID, if the z/OS Collector Agent is configured to collect the CICSUserID.

    For other databases, %%EndUser is blank.
%%EventDate The date of the App Event.
%%EventValueNum The App Event value number.
%%EventValueStr The App Event value string.
%%IMSPartArea Available for IMS only. Corresponds to "FULL SQL"."IMS PART/AREA". Can be either a HALDB partition name or a DEDB AREA name.
%%lastError Last error description: Available only when an SQL error request that triggers an exception rule contains a last error description field.
%%netProtocol Network protocol, for K-TAP on Oracle, which can display as either IPC or BEQ.
%%Object A list of objects matching the rule. List the number of objects is based on the value of the store alert_object_num_limit CLI command.
%%objectType The type of each object returned by the list of objects in %%Object.
%%OSUser Session information. (OS_USER in GDM_ACCESS).

For IMS z/OS systems, the %%OSUser is the same as the %%DBUser.
%%Program Available for Db2 for IBM® i only. The program schema/program.
%%ProcessID Available for Db2 for IBM® i only. The job number.
%%receiptTime Timestamp representing the time when the alert occurred. %%receiptTime displays in either seconds or milliseconds, based on the value of the store alert_timestamp_unit CLI command. The default is seconds.
%%receiptTimeMills Number representing the time when the alert occurred, in milliseconds, since the fixed date of Jan 1 1900.
%%RecordsAffected Records affected.

Messages that include this variable are delayed for 5 minutes by default. For more information, see the store alerter delay CLI command.

Note: This variable does not return a value when used with a message template, which uses an alert only policy rule action that specifies the syslog notification type. For more information, see Alerting rule actions.
%%requestType Request type.
%%ResponseLength Response length. Not supported for Db2 z/OS systems.

Messages that include this variable are delayed for 5 minutes by default. For more information, see the store alerter delay CLI command.

Note: This variable does not return a value when used with a message template, which uses an alert only policy rule action that specifies the syslog notification type. For more information, see Alerting rule actions.
%%ReturnedDataCount The returned data count for extrusion rules. Requires that the Inspect Returned Data flag is on.
%%ruleDescription The rule description from the policy rule definition.
%%ruleID The rule number from the rule definition.
%%SenderIP The IP address of the server where the S-TAP is installed.
%%serverHostname Server hostname.
%%serverIP Server IP address.
%%serverPort Server port number.
%%serverType The database server type.
%%serviceName Service name.
%%SessionID Session ID. The Session_id is the same as the MySQL auto-generated ID in GDM_SESSION on the collector.
%%sessionStart Session start time (login time).
%%sessionStartMills Number representing the start of the session where the alert occurred, in milliseconds since the fixed date of Jan 1 1900.
%%severity Severity from the rule definition.
%%SourceProgram Source program name. For Db2 for IBM i, the %%SourceProgram returns job_user/job_name.
%%SQLNoValue SQL string with masked values. The value of SQL is replaced by a question mark (?) in the syslog.

For IMS z/OS users: The following values are available, similar to the %%SQLString values: prog=; job=; step=; tran=; job#=.
%%SQLString SQL string (if any).
Note: For databases that generate custom queries, %%SQLString values are copied to %%SQLNoValue, where they are masked. These databases include, for Cloudera: HDFS, HBASE, and SOLR; for Hortonworks: HBASE, HDFS, KAFKA, SOLR, STORM, and YARN.
%%SQLTimestamp The time on the packet or request. %%SQLTimestamp displays in either seconds or milliseconds, based on the value of the alert_timestamp_unit CLI. The default is seconds.
%%Subject[ ] If you specify this variable, all of the text between the square brackets ([ ]), such as file name, email sender, or description, is included in the subject line of the email that is sent to the user.
%%succeeded Messages that include this variable are delayed for 5 minutes by default. For more information, see the store alerter delay CLI command. The value is replaced with the "FULL SQL"."Succeeded" value from Guardium report attributes.
Note: This variable does not return a value when used with a message template, which uses an alert only policy rule action that specifies the syslog notification type. For more information, see Alerting rule actions.
%%uid_chain For Linux or UNIX systems only, the UID chain that tracks a chain of users.

Messages that include this variable are delayed for 5 minutes by default. For more information, see the store alerter delay CLI command. The value is then replaced with the "Session"."Uid Chain" value from Guardium report attributes. For more information, see UID chains.

Note: This variable does not return a value when used with a message template, which uses an alert only policy rule action that specifies the syslog notification type. For more information, see Alerting rule actions.
%%UnitOfWork Computed attribute that contains the CICS Unit of Work ID in hex to correlate CICS traffic across multiple S-TAP Entities (IMS, data sets, and Db2).
%%Verb The SQL verbs that are relevant to the triggered rules in the alert messages. You can set the number of SQL verbs to include by setting the ALERT_VERB_NUM_LIMIT parameter from the modify_guard_param command. The default is 10. For more information, see Alerter parameters
%%violationID Numeric representing the POLICY_VIOLATION_LOG_ID of this alert in GDM_POLICY_VIOLATION_LOG (this is the same as the Violation Log ID in the Policy Violations / Incident Management report).

Example: Creating a real-time alert

The following example shows the general process of creating a Guardium real-time alert. Your process might be different.
  1. Create a message template for your alert:
    1. From the Named Template Finder in the Global Profile UI, select and clone a real-time alert template. You can use the filtering to select the template type that you want.
    2. Name your new template and click Save to save it.
    3. From the Named Template Finder, select your new template and click Edit to make changes. Add or remove the message template variables (described in Table 1) as needed, and then save the changes.
  2. Associate your alert with a policy:
    1. Open Security Policies (Policy Builder for Data) and select or create a policy.
    2. Create a rule for your policy (for example, a session level rule of Database type = ORACLE).
    3. Under Rule action, add an action and specify your template as the Message Template.
    4. Click OK to save the new Action, OK again to save the rule, and OK one more time to save the policy.
  3. From the Guardium Alerter page, make sure that the alerter is running.
  4. The next time Guardium starts, if Guardium fires the alert, a message is sent to the SYSLOG that contains the information that is specified in your alert message.