Using BMC Defender Thread Custom Email plug-in

The Thread E-Mail Adapter program is one of the more complex adapters to configure and work with and requires a good understanding of correlation threads, match expressions, parse functions, and the message content of your system. Although some configurations can be put together very simply, other configurations can become quite complex and highly specific. 

BMC Defender does not specify or require an exact format for messages. The content of the e-mail message is completely under your control. The content might be a simple relay of the message to an e-mail recipient, or a more complex message with many different parsing features to supply precise content for e-mail recipients and end users. 

Specifically, you can configure up to twelve different parse functions per e-mail message. The operator configures the particular fields (or message text) that must get displayed in the e-mail message and specifies a subject and e-mail recipients. When the thread records a message, the message is formatted according to these rules and then sent to the specified recipients. 

A detailed explanation of match patterns and parse functions are available in documentation for other BMC Defender products. In particular, the BMC Security Correlation Server Parse Expression Reference Manual is available on most systems by clicking the More link in the upper right corner of the display, then select User Manuals. This parse reference manual furnishes a complete description of the various parse functions along with detailed examples and discussions.

Parser configuration screen

After enabling e-mail actions and clicking Edit on the Correlation > Threads Edit screen (discussed at the end of the previous section), the operator is presented with a screen permitting configuration of the e-mail message that got sent when a thread records a message. This screen contains multiple controls and features, as depicted in the following image:

The preceding screen is a familiar BMC Defender Server parameter editor screen. You can fill in the form, then click Save to save the settings, or click Delete to delete the entire specification. Prev makes you return to the previous Edit Thread screen, whereas Cancel makes you return to the top-level Threads screen. Reset is identical to clicking Prev and then clicking Edit again (and discards all changes to the screen).

Additional notes

• The Thread E-Mail Adapter allows you to create custom e-mail messages when the thread logs a message.
• Not all threads are appropriate for use with the adapter. Only those threads that log occasional messages are good candidates for use with this adapter.
• To configure the adapter, the operator performs the following specific actions: 
  1. The operator clicks Edit for an existing thread.
  2. On the Edit screen for the thread, the operator sets the Enable Custom E-Mail Notifications input to Yes.
  3. The operator clicks Edit > Custom E-Mail Notifications. This accesses the Parser Configuration screen for the thread.
• The Parser Configuration screen allows you to configure an e-mail subject, e-mail recipients, and various fields that appear in the e-mail when the thread records a message.
• The Parser Configuration screen provides a Hold-Off and Max E-Mail Messages Per Hour setting that limits the amount of e-mails that get sent when the thread collects messages.
• The Max E-Mail Messages Per Hour setting limits the number of messages that are sent by the thread per hour. The operator can view the details (and reset the throttle) using the View / Clear Throttle link next to this value on the Parser Configuration screen.
• The Hold-Off value prevents the system from sending another e-mail for the thread until the specified time has elapsed (by default 10 seconds, but adjustable from 0 to 60 seconds). This prevents a burst of messages from tripping the Max E-Mail Messages Per Hour setting.
• Each field has a Field Type that describes the format of the field, either static string, parse expression, time value, or environmental variable.
• The system sets various environmental variables that can be used to put the device, facility, severity, and message content into the e-mail message.
• The S_ADDRESS environmental variable (used with an EnvVar field type) is the only way to get the address of the device into the main content portion of the e-mail. For BMC Defender Agent for Windows, the operator can also specify a ParseSpec value of Location: * (to match the device name contained in the windows message, assuming a standard configuration for the agent).
• You can configure parse values easily by viewing samples of the messages, and test these sample messages using Test option (to see what the e-mail message looks like based on the format specifications for the thread).
• The Sample Messages displayed by the screen are sanitized and might be slightly different than the messages in the thread, with special punctuation characters removed. The operator should use the sample messages as a guideline for creating parse specifications (and not the actual messages in the thread catalog).
• Up to three different parse expressions can be specified for a field (although normally one parse expression is sufficient).
• The operator can click Browse to browse the specifications that might exist for other threads can cut and paste these specifications, or click Select to overwrite the existing specifications. This assists with the configuration of e-mail associated with threads containing similar messages.
• If the operator clicks Select on the Browse screen, any existing specifications for the threat get replaced with the selected thread. The original specifications are lost and have to be recreated.
• The operator can debug the system using the View Debug Log link at the lower right of the Parser Configuration screen. This log might provide a reason for failure and contains a transcript of the SMTP session (if any).
• The View Debug Log link furnishes a log for the last e-mail notification attempt by the thread, and this log does not otherwise contain any history.
• All information retained by the system, including logs, status files, and configuration data, resides in the thread-e folder of the BMC Defender Server home directory.

This section provides information about the following topics: