Overview

Starting with release 6.4, Ceptor supports sending out Alerts.

Alerts are generated when various conditions occur, such as servers going down (or back up) or when loaded are close to expiring or have expired already.

These alerts are generated by the various modules and are all sent to the Ceptor Configuration Server which can then process them.

To process them, you can configure any number of Alert Actions, which are then triggered when alerts occur. An Alert Action can optionally have a set of conditions for which it is triggered - conditions could be specific alerts or specific content within the alerts.

Alert Types

Ceptor currently has these types of alerts:

• A certificate will expire soon
• A certificate has expired
• A server is down
• A server is back up after going down previously

Alert Actions

An Alert Action can e.g. send an SMS/Text message or an Email when it encounters a specific alert.

All configured Alert Handlers are executed once an Alert occurs.

Conditions

An Alert Handler can define a set of conditions under which it is triggered - if conditions are set, at least one of the conditions must match or the Alert Handler is not executed.

Configuration

Within Ceptor Console, you configure Alert Actions / Handlers.

You can add an action, give it a name and select the type from the list of available types.

Conditions

For each type, you can choose the conditions - if any conditions are defined for an Alert Action, at least one condition must match before the alert action is done.

In the condition, you can give it a name (which is required but has no meaning other than to identify it) - and you can optionally choose a specific type of alert to match.

If the alert refers to a certificate, you can limit to certain subject or issuer names, and if the alert refers to a server down/up alert, you can put some conditions on the gateway, destination, hostname and/or port number.

In addition, you can add condition scripts where you make a decision by writing a script that looks deeper into the individual  alert. See Scripts

Logging alerts

For Alert Actions of the type "Write Log Message", you can define the log level and an optional logger name - this can then be used together with the logback configuration to route specific loggers to specific logging destinations, e.g. alerts in Splunk, databases or whatever needs suit your environment.

Sending SMS/Text messages

For Alert Actions of the type "SMS/Text Message", you can specify a mobil phone number to send the alert to.

Sending emails

For Alert Actions of the type "Send email" you can specify the receiving email address and an optional Subject Prefix which the email subject will be prefixed with to make it easily recognizable.
The actual text in the subject and message body depends on the type of alert issued.

Create Action in Console

This will create an action in the console -see Actions for more information.

Execute Script

Instead of using one of the predefined actions, you can also create a script where you do processing of your own - this processing could include calling existing SIEM systems, sending SMS messages to non-standard SMS gateways or other any other actions you might take for a given alert.

Scripts

When a script is called, it is called with a variable context in scope - this context looks like this:

public class ScriptContext {
	public Properties configuration;
	public Alert alert;
}

public interface Alert extends JSONAware, Serializable {
	/**
	 * Type of alert
	 */
	public enum Type {
		certificateexpires_soon, certificate_is_expired, server_down, server_up
	}
	
	/** Type of alert */
	public Alert.Type getType();
	
	/** Unique ID of alert */
	public String getID();
	
	/** Alert title */
	public String getTitle();
	
	/** Alert message */
	public String getMessage();
	
	/** Exception, if available */
	public Throwable getThrowable();
}

In addition, the Alert implements the JSONAware interface, which gives it 2 additional methods;

• toJSON() - returns a JSON Object
• toJSONString() - returns the alert as a JSON String.

Below is an example javascript which simply prints out the alert to stdout:

print(context.configuration);
print(context.alert.getType());
print(context.alert.getID());
print(context.alert.getTitle() + ' - ' + context.alert.getMessage());
print(context.alert.toJSONString());

When a script is called as a condition, it needs to return a value - either true or false depending if the condition matches or not.

Configuration - JSON Structure

Alerts are stored as JSON configuration, in Ceptor's configuration as a property named "alerts_JSON_" in the abstract server configuration named "alerts" (the Ceptor Console will create it for you if it does not already exists - but if you need to change it using APIs, you need to know the naming).

{"actions": [
  {
    "name": "Log the alert",
    "type": "log",
    "conditions": [],
    "level": "WARN"
  },
  {
    "name": "Alert Administrator",
    "type": "sms",
    "conditions": [],
    "mobile": "+4526164023"
  },
  {
    "name": "Send email to admin",
    "type": "email",
    "conditions": [],
    "email": "kr@asseco.dk",
    "email.prefix": "[Alert !!!]"
  },
  {
    "name": "Create an action",
    "type": "log",
    "conditions": [{
      "name": "Only server down",
      "type": "server_down"
    }],
    "logger": "alerts",
    "level": "ERROR"
  },
  {
    "name": "Run a script",
    "type": "script",
    "conditions": [],
    "script": "%{script}//\r\n// Example javascript that simply writes both the configuration and alerts to stdout\r\n//\r\n\r\nprint(context.configuration);\r\nprint(context.alert.getType());\r\nprint(context.alert.getID());\r\nprint(context.alert.getTitle() + ' - ' + context.alert.getMessage());\r\nprint(context.alert.toJSONString());"
  }
]}

The "alerts_JSON_" property contains a JSON array called "actions", and each action looks like this:

For conditions, each condition is a JSON object within the conditions array in an Alert Action

Configuration - Properties

In order to be able to send emails / SMS messages, some configuration is required - this configuration must be set for the Ceptor Configuration Server which processes the alert actions defined.

Example configuration:

<group name="alerts" description="Alert actions related configuration">
	<property name="mail.from" value="" description=""/>
	<property name="mail.replyto" value="" description=""/>
	<property name="mail.smtp.host" value="" description=""/>
	<property name="mail.smtp.password" value="" description=""/>
	<property name="mail.smtp.port" value="25" description=""/>
	<property name="mail.smtp.protocol" value="smtps" description=""/>
	<property name="mail.smtp.user" value="" description=""/>
	<property name="sms.apikey" value="" description="For CPSMS, if present, sms.password is not used"/>
	<property name="sms.appnr" value="1231" description="For unwire, specify from phone number"/>
	<property name="sms.flashsms" value="false" description="If true, SMS is sent as flash SMS"/>
	<property name="sms.from" value="Ceptor" description="Max 11 characters from name or number"/>
	<property name="sms.httpProxyHost" value="" description="HTTP Proxy Server"/>
	<property name="sms.httpProxyPassword" value="" description="HTTP Proxy Password for proxy authentication"/>
	<property name="sms.httpProxyPort" value="8080" description="HTTP Proxy Port"/>
	<property name="sms.httpProxyUser" value="" description="HTTP Proxy Userid to use for authentication"/>
	<property name="sms.mediacode" value="" description="For unwire, specify mediacode"/>
	<property name="sms.password" value="" description="Password for SMS gateway"/>
	<property name="sms.provider" value="cpsms" description="cpsms or unwire depending on which SMS provider to use (locallogging for logging codes to log file)"/>
	<property name="sms.smsc" value="dk.tdc" description="For unwire, specify operator to use"/>
	<property name="sms.username" value="portalprotect" description="Username for SMS gateway"/>
	<property name="sms.verifysslhostname" value="true" description="Set to false to turn off hostname verification"/>
	<property name="sms.verifysslservercert" value="true" description="Set to false to turn SSL server certificate validation"/>
</group>

Alerts - JSON Structure

Each Alert has its own JSON Structure

{
  "type": "server_up",
  "id": "63ba3e15-0275-4c8b-aa0f-b2340873cc1e",
  "title": "Server api.worldbank.org:80 up",
  "message": "Server worldbank_sandbox (api.worldbank.org@api.worldbank.org:80) is back up after 42 minutes",
  "gateway": "gateway1",
  "destination": "worldbank_sandbox",
  "host": "api.worldbank.org",
  "port": 80,
  "duration": 2520512
}

This is a list of the keys / attributes that the alert can contain: