System Alerting

Contents

Overview
Configuring an Alert Destination
Configuring an Alert Filter

Overview

This tutorial shows the API Gateway's enhanced logging capabilities. System alerts are usually sent when a filter fails, but they can also be used for notification purposes. The API Gateway can send system alerts to several alert destinations, including a Windows Event Log, UNIX/Linux sylsog, SNMP Network Management System, Check Point Firewall-1, email recipient, or Twitter.

There are two main steps involved in configuring the API Gateway to send system alerts:

  1. Configuring an alert destination

  2. Configuring an Alert filter

Configuring an Alert Destination

The first step in configuring the API Gateway to send alerts is to configure an alert destination. The API Gateway can send alerts to the following destinations:

You can configure these alert destinations under the Libraries -> Alerts node in the Policy Studio tree.

Syslog (Local or Remote)

Many types of UNIX and Linux provide a general purpose logging utility called syslog. Both local and remote processes can send logging messages to a centralized system logging daemon, known as syslog, which in turn writes the messages to the appropriate log files. You can configure the level of detail at which syslog logs information. This enables administrators to centrally manage how log files are handled, rather than separately configuring logging for each process.

Each type of process logs to a different syslog facility. There are facilities for the kernel, user processes, authorization processes, daemons, and a number of place-holders that can be used by site-specific processes. For example, the API Gateway enables you to log to facilities such as auth, daemon, ftp, local0-7, and syslog itself.

Remote Syslog

To configure a remote syslog alert destination, perform the following steps:

  1. Right-click the Libraries -> Alerts node, and click Add -> Syslog Remote at the bottom of the screen on the right.

  2. The Syslog Server dialog enables you to specify details about the machine on which the syslog daemon is running. The API Gateway connects to this daemon and logs to the specified facility when the alert event is triggered. Complete the following fields on the Syslog Server dialog:

    • Name:

      Enter a name for this alert destination.

    • Host:

      Enter the host name or IP address of the machine where the syslog daemon is running.

    • Facility:

      Select the facility that the API Gateway sends alerts to from the drop-down list.

  3. Click OK.

Local Syslog (UNIX only)

To configure a local syslog alert destination, perform the following steps:

  1. Right-click the Libraries -> Alerts node, and click Add -> Syslog Local (UNIX only) at the bottom of the screen on the right.

  2. The Syslog Server dialog enables you to specify where the alert is sent when the alert event is triggered. Complete the following fields on the Syslog Server dialog:

    • Name:

      Enter a name for this alert destination.

    • Facility:

      Select the facility that the API Gateway sends alerts to from the drop-down list.

  3. Click OK.

Windows Event Log

This alert destination enables alert messages to be written to the local or a remote Windows Event Log. To add a Windows Event Log alert destination, perform the following steps:

  1. Right-click the Libraries -> Alerts node in the Policy Studio tree, and click Add -> Windows Event Log at the bottom of the screen on the right.

  2. The Windows Event Log Alerting dialog enables you to specify the machine of the Event Log the API Gateway sends alerts to. Complete the following fields on this dialog:

    • Name:

      Enter a name for this alert destination.

    • UNC Server name:

      Enter the UNC (Universal Naming Code) of the machine where the event log resides. For example, to send alerts to the event log running on a machine called \\NT_SERVER, enter \\NT_SERVER as the UNC name for this host.

  3. Click OK.

Check Point FireWall-1 (OPSEC)

The API Gateway complies with Open Platform for Security (OPSEC). OPSEC compliance is awarded by Check Point Software Technologies to products that have been successfully integrated with at least one of their products. In this case, the API Gateway has been integrated with the Check Point FireWall-1 product.

FireWall-1 is the industry leading firewall that provides network security based on a security policy created by an administrator. Although OPSEC is not an open standard, the platform is recognized worldwide as the standard for interoperability of network security, and the alliance contains over 300 different companies. OPSEC integration is achieved through a number of published APIs, which enable third-party vendors to interoperate with Check Point products.

To configure a FireWall-1 alert destination, perform the following steps:

  1. Right-click the Libraries -> Alerts node in the Policy Studio tree, and click Add -> OPSEC at the bottom of the screen on the right.

  2. The OPSEC Alerting dialog enables you to specify details about the machine on which FireWall-1 is installed, the port it is listening on, and how to authenticate to the firewall. The API Gateway connects to the specified firewall when the alert event is triggered and prevents further requests for the particular client that triggered the alert. The following configuration settings must be set:

    • sam_server auth_port:

      The port number used to establish SIC (Secure Internal Communications) based connections with the firewall.

    • sam_server auth_type:

      The authentication method used to connect to the firewall.

    • sam_server ip:

      The host name or IP address of the machine that hosts the Check Point Firewall.

    • sam_server opsec_entity_sic_name:

      The firewall's SIC name.

    • opsec_sic_name:

      The OPSEC application's SIC Name, which is the application's full DName as defined by the VPN-1 SmartCenter Server.

    • opsec_sslca_file:

      The name of the file containing the OPSEC application's digital certificate.

  3. Click OK.

You can store configuration information in a file and then load it using the Browse button. Alternatively, you can use the Template button to load the required settings into the text area, and add the configuration values manually.

For the API Gateway to establish the SSL connection to the firewall, the opsec_sslca_file specified must be uploaded to the API Gateway machine. You can do this by clicking the Add button at the bottom of the screen.

For more information on OPSEC settings, see the documentation for your OPSEC application.

SNMP Network Management System

This alert destination enables the API Gateway to send Simple Network Management Protocol (SNMP) traps to a Network Management System (NMS).

To configure an SNMP alert destination, perform the following steps:

  1. Right-click the Libraries -> Alerts node in the Policy Studio tree, and click Add -> SNMP at the bottom of the screen on the right.

  2. The SNMP Alerting dialog enables you to specify details about the NMS that the API Gateway should send an alert to. Complete the following fields:

    • Host:

      The host name or IP address of the machine on which the NMS system resides.

    • Port:

      The port on which the NMS system is listening.

    • Timeout:

      The timeout in seconds for connections from the API Gateway to the NMS system.

    • Retries:

      The number of retries that should be attempted whenever a connection failure occurs.

    • SNMP Version:

      Select the version of SNMP that you wish to use for this alert.

  3. Click OK.

Email Recipient

This alert destination enables alert messages to be sent by email. To add a Windows Event Log alert destination, perform the following steps:

  1. Right-click the Libraries -> Alerts node in the Policy Studio tree, and click Add -> Email at the bottom of the screen on the right.

  2. The Email Alerting dialog enables you to configure how the email alert is to be sent. Complete the following fields:

    • Name:

      Enter a name for this alert destination.

    • Email Recipient (To):

      Enter the recipient of the alert mail in this field. Use a semicolon-separated list of email addresses to send alerts to multiple recipients.

    • Email Sender (From):

      Email alerts appear from the sender email address specified here.

      [Important] Important

      Some mail servers do not allow relaying mail when the sender in the From field is not recognized by the server.

    • Email Subject:

      Email alerts use the subject specifed in this field.

  3. In the SMTP Server Settings, specify the following fields:

    • Outgoing Mail Server (SMTP):

      Specify the SMTP server that the API Gateway uses to relay the alert email.

    • Port:

      Specify the SMTP server port to connect to. Defaults to port 25.

    • Connection Security:

      Select the connection security used to send the alert email (SSL, TLS, or NONE). Defaults to NONE.

  4. If you are required to authenticate to the SMTP server, specify the following fields in Log on Using:

    • User Name:

      Enter the user name for authentication.

    • Password:

      Enter the password for the user name specified.

  5. Finally, you can select the Email Debugging setting to find out more information about errors encountered by the API Gateway when attempting to send email alerts. All trace files are written to the /trace directory of your the API Gateway installation. This setting is not selected by default.

  6. Click OK.

Twitter

This alert destination enables the API Gateway to send tweet alerts to Twitter. Twitter uses the OAuth open authentication standard. To enable the API Gateway to send tweet alerts using the Twitter API, you first need to do the following:

  • Create a Twitter account to represent you as the user

  • Register a custom application for your API Gateway instance, which posts alerts on the user’s behalf

Twitter requires that API calls are made for both the user and the application. The Twitter API requires the following credentials:

  • Consumer Key of registered applications

  • Consumer Secret Key of registered application

  • Access Token allowing application to post on behalf of a user

  • Access Token Secret to verify the Access Token

Twitter uses this information to determine which application is calling the API, and verifies that the Twitter user you are attempting to make API requests on behalf of has authorized access to their account using the specified application. Twitter identifies and authenticates all requests as coming from both the user performing the request and the registered API Gateway application working on the user’s behalf.

Registering a client application

To use the Twitter API, you must create a Twitter account, and register a client application for the API Gateway. If you have not already created a Twitter account, register a new account using the instructions on http://www.twitter.com. When you have created the account, register a client application for the API Gateway as follows:

  1. Go to http://dev.twitter.com/.

  2. On the Twitter toolbar, select Your apps.

  3. Click the Register a new app button.

  4. Enter the details for your custom application. Some details are arbitrary, but you must specify the following values:

    • Application Type:

      Select the Client radio button.

    • Default Access Type:

      Select the Read & Write radio button.

    [Note] Note

    The Application Name may already be registered to another user, so you may need to specify a different unique name.

  5. Click Register Application. Each client application you register is provisioned a consumer key and consumer secret. These are used, in conjunction with the OAuth library, to sign every request you make to the API. Using this signing process, Twitter trusts that the traffic identifying itself as you is indeed you.

  6. Select your registered application, and select My Access Token. This provides you with an access token and an access token secret. You must store these safely.

Configuring a Twitter alert destination

To configure a Twitter alert destination, perform the following steps:

  1. Right-click the Libraries -> Alerts node in the Policy Studio tree.

  2. Click Add -> Twitter at the bottom of the screen on the right.

  3. The Twitter Alerting dialog enables you to specify credentials for the Twitter user that the API Gateway uses to send an alert to. Complete the following fields on this dialog:

    • Consumer Key:

      The Consumer Key of your registered application.

    • Consumer Secret:

      The Consumer Secret of your registered application.

    • Access Token:

      The Access Token that represents you.

    • Access Token Secret:

      The Access Token Secret that represents you.

Configuring an Alert Filter

Typically, an Alert filter is placed on the failure path of another filter in the policy. For example, you could configure an alert if a schema validation fails 10 times within a 5000 millisecond period for a specified Web Service. In this case, you would place the Alert filter on the failure path from the Schema Validation filter, as shown in the following policy screen shot:

Example of a Policy with an Alert Filter

When editing policies, you can drag and drop the Alert filter from the Monitoring filter group. To configure an alert filter, specify the following settings on the Alert filter screen:

Name:

Enter a descriptive name for the filter.

Message:

Configure the following settings on the Message tab:

Alert Type Select the severity level of the alert. This option is only relevant for alert destinations that support severity levels, such as the Windows Event Log.
Alert Message Enter the text that appears in the alert. You can enter message attributes using selectors, which are looked up and expanded to values at runtime. For example, instead of sending a generic alert stating Authentication Failed, you can use a message attribute to give the ID of the user that was not authenticated. To do this, use the following syntax:

${name_of_attribute}

The following examples show how to use message attributes in alert messages:

  • Authentication failure for user: ${authentication.subject.id}.

  • {alert.number.failures} authentication failures have occurred in ${alert.time.period} seconds.

  • ${alert.number.failures} exceptions have occurred in policy ${circuit.name}.

  • The last exception was ${circuit.exception} with path ${circuit.path}.

[Note] Note

An alert message is not required for alerts sent to an OPSEC firewall.


Tracking:

Configure the following settings on the Tracking tab:

Accumulated number of messages Enter the number of times this filter can be invoked before the alert is sent.
In time period (secs) Enter the time period in which the accumulated number of messages can occur before and alert is triggered.
Track per client Select this option if you want to record the accumulated number of messages in the specified time period for each client.


Destination:

All pre-configured alert destinations are displayed in the Alert Name table. Select the destinations that the API Gateway sends alerts to if the criteria specified for this filter are met. You can click Add to configure an alert destination. For more details, see the section called “Configuring an Alert Destination”.

Prev  Up  Next
  Home