Configure system alerts

Contents

Overview
Configure an alert destination
Configure an alert filter

Overview

This topic shows the API Gateway system alert capabilities. System alerts and events are usually sent when a filter fails, but they can also be used for notification purposes. API Gateway can send system alerts to several alert destinations, including a Windows Event Log, UNIX/Linux syslog, SNMP Network Management System, Check Point Firewall-1, email recipient, Amazon Simple Notification Service (SNS), or Twitter.

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

  1. Configure an alert destination

  2. Configure an alert filter

Configure an alert destination

Syslog (local or remote)
Windows Event Log
Check Point FireWall-1 (OPSEC)
SNMP Network Management System
Email recipient
Amazon SNS
Twitter

The first step in configuring API Gateway to send alerts is to configure an alert destination. This section describes the destinations to which the API Gateway can send alerts to. 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 used by site-specific processes. For example, 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. Click the Libraries > Alerts node, and then Add > Syslog Remote at the bottom on the right.

  2. The Syslog Server dialog enables you to specify details about the machine on which the syslog daemon is running. 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 API Gateway sends alerts to.

  3. Click OK.

Local syslog (UNIX only)

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

  1. Click the Libraries > Alerts node, and then click Add > Syslog Local (UNIX only) at the bottom of the window 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 API Gateway sends alerts to.

  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. Click the Libraries > Alerts node in the Policy Studio tree, and then click Add > Windows Event Log at the bottom of the window on the right.

  2. The Windows Event Log Alerting dialog enables you to specify the machine of the event log 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)

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, 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. Click the Libraries > Alerts node in the Policy Studio tree, and then click Add > OPSEC at the bottom of the window 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 Secure Internal Communications (SIC) 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 Check Point Firewall.

    • sam_server opsec_entity_sic_name:

      The firewall's SIC name.

    • opsec_sic_name:

      The OPSEC application SIC Name (application's full DName 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 load it using the Browse button. Alternatively, use the Template button to load the required settings into the text area, and add the configuration values manually.

For API Gateway to establish the SSL connection to the firewall, the opsec_sslca_file specified must be uploaded to the API Gateway machine. To do this, click Add at the bottom of the window.

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

SNMP Network Management System

This alert destination enables 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. Click the Libraries > Alerts node in the Policy Studio tree, and then click Add > SNMP at the bottom of the window on the right.

  2. The SNMP Alerting dialog enables you to specify details about the NMS that API Gateway sends alerts to. Complete the following fields:

    • Host:

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

    • Port:

      The port on which the NMS is listening.

    • Timeout:

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

    • Retries:

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

    • SNMP Version:

      Select the version of SNMP to use for this alert.

  3. Click OK.

Email recipient

This alert destination enables alert messages to be sent by email. To add an email alert destination, perform the following steps:

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

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

    • 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 specified in this field.

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

    • Outgoing Mail Server (SMTP):

      Specify the SMTP server that 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 API Gateway when attempting to send email alerts. All trace files are written to the /trace directory of your API Gateway installation. This setting is not selected by default.

  6. Click OK.

Amazon SNS

This alert destination enables alert messages to be sent to the Amazon Simple Notification Service (SNS). Amazon SNS is a managed push messaging service that can be used to push to mobile devices and Internet connected smart devices, as well as to other distributed services. For more information on Amazon SNS, go to http://aws.amazon.com/sns/.

To add an Amazon SNS alert destination, perform the following steps:

  1. Click the Libraries > Alerts node in the Policy Studio tree.

  2. Click Add > Amazon SNS at the bottom of the window on the right.

  3. Complete the following fields on the AWS SNS Alert dialog:

    • Name:

      Enter a name for this alert destination.

    • AWS Credential:

      Click the browse button to select your AWS security credentials (API key and secret) to be used by API Gateway when connecting to Amazon SNS.

    • Region:

      Select the region appropriate for your deployment. You can choose from the following options:

      • US East (Northern Virginia)

      • US West (Oregon)

      • US West (Northern California)

      • EU (Ireland)

      • Asia Pacific (Singapore)

      • Asia Pacific (Tokyo)

      • Asia Pacific (Sydney)

      • South America (Sao Paulo)

      • US GovCloud

    • Client settings:

      Click the browse button to select the AWS client configuration to be used by API Gateway when connecting to Amazon SNS. For more details, see the section called “Configure AWS client settings”.

    • Topic ARN:

      Enter the topic Amazon Resource Name (ARN) to send alerts to.

      When you create a topic, Amazon SNS assigns a unique ARN to the topic, which includes the service name (for example, SNS), the region, the AWS ID of the user, and the topic name. Whenever a publisher or subscriber needs to perform any action on the topic, they should reference the unique topic ARN. The ARN is returned as part of the API call to create the topic. For example, arn:aws:sns:us-east-1:1234567890123456:mytopic is the ARN for a topic named mytopic created by a user with the AWS account ID 123456789012 and hosted in the US East region.

    • Subject:

      Enter the subject of the alert to be sent to Amazon SNS.

  4. Click OK.

Twitter

This alert destination enables API Gateway to send tweet alerts to Twitter. Twitter uses the OAuth open authentication standard. To enable 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.

Register a client application

To use the Twitter API, you must create a Twitter account, and register a client application for 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 an account, register a client application for API Gateway:

  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 might 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.

Configure a Twitter alert destination

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

  1. Click the Libraries > Alerts node in the Policy Studio tree.

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

  3. The Twitter Alerting dialog enables you to specify credentials for the Twitter user that 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.

Configure an alert filter

General settings
Notifications settings
Tracking settings
Default message settings

Typically, an Alert filter is placed on the failure path of another filter in the policy. For example, to 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 example.

Example of a policy with an alert filter

When editing policies, you can drag and drop the Alert filter from the Monitoring filter group.

General settings

Configure the following settings on the Alert filter window:

Name:

Enter a descriptive name for the filter.

Alert Type:

Select the severity level of the alert. The options are Error, Warn, and Info. This option is only relevant for alert destinations that support severity levels, such as the Windows Event Log.

Notifications settings

The Notifications tab enables you to configure the alert destinations. Any alert destinations that are already configured are shown under the respective alert destination type on the left of the window. You can also create new alert destinations, and edit or delete existing alert destinations directly from this window.

Select an existing alert destination

To select an existing alert destination, follow these steps:

  1. Click the check box next to the alert destination on the left of the window. Alternatively, click the check box next to the alert destination type to select all alert destinations of that type (for example, all Email destinations).

  2. Choose the message to use for the alert destination on the right side of the window.

    • To set the message for an email destination, select Use the Default Message to use the message from the Default Message tab, select Use the following message to enter a custom message, or select Load from file to load a message from a file.

      You can select the Content type of a custom message or a message loaded from a file (for example, as text/html). You can also register new MIME/DIME content types by clicking the Registered Types button.

    • To set the message for all other destinations, select Use the Default Message to use the message from the Default Message tab, or select Use the following message to enter a custom message.

The following figure shows an example of an email alert destination with a text/html custom message.

Example of email alert destination

The following figure shows an example of an SNMP alert destination that uses the default message.

Example of SNMP alert destination

Create a new alert destination

To create a new alert destination, click Add at the top left and choose from the following options:

  • Email

  • OPSEC

  • Syslog Local (UNIX only)

  • SNMP

  • Windows Event Log

  • Syslog Remote

  • Twitter

For more information on configuring alert destinations see the section called “Configure an alert destination”.

Edit or delete an existing alert destination

To edit or delete an existing alert destination, select the destination on the left and click Edit or Delete.

Call this policy when alert is triggered:

Click the browse button to select a policy to be used by API Gateway when an alert is triggered.

Tracking settings

The Tracking tab enables you to configure how often alerts are sent. Configure the following settings:

Accumulated number of messages:

Enter the number of times this filter can be invoked before the alert is sent. The default value is 1.

In time period (secs):

Enter the time period in which the accumulated number of messages can occur before an alert is triggered. The default is 60 seconds.

Track per client:

Select this option to record the accumulated number of messages in the specified time period for each client. This option is selected by default.

Default message settings

The Default Message tab enables you to configure a default message for alerts. Enter the message text to appear in the alert in the Message to send field.

You can enter message attributes using selectors, which API Gateway looks up and expands at runtime. For example, instead of sending a generic alert stating Authentication Failed, you can use a message attribute to include the ID of the user whose authentication failed. 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}.

For more information on selectors, see Select configuration values at runtime.

[Note] Note

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

Prev  Up  Next
  Home