Event Sinks

Event Sink Configuration

Secrets Safe supports multiple event sink providers. Event sink configuration can be modified at runtime by using the CLI.

Manage Event Sink Configurations

List Event Sink Configurations

ssrun event-sink get

This will give you a list of configured event sinks as JSON.

Example Output:

  {
      "Enabled": true,
      "IsAudit": true,
      "Level": "information",
      "Name": "kibana",
      "Options": {
          "uri": "http://elk:9200"
      },
      "Type": "elasticsearch"
      "uri": "/system/event_sink/kibana"
  }

Delete an Event Sink Configuration

ssrun event-sink delete -n <event-sink-name>

This deletes the event sink with the given name.

Creating an Event Sink Configuration

ssrun event-sink create -f elk.json

This will create an event sink configuration using the values in the file elk.json. Details on the structure of the configuration file will be outlined in the section below.

Event Sink Configuration

Configurations are defined in JSON formatted files. Event sink configurations have the following structure:

{
  "name": "string",
  "enabled": bool,
  "IsAudit": bool,
  "level": "string",
  "type": "string",
  "options": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

Required Parameters

  • name - (Required) Friendly name for the event sink. This is the name that you would provide to ssrun event-sink delete if you were to delete the event sink later.
  • level - (Required) This is the minimum event sink event level that this event sink configuration will process. Valid levels, in ascending order, are:
    • verbose
    • debug
    • information
    • warning
    • error
    • fatal
  • type - (Required) The event sink provider type to use. The following are supported event sink types:
    • console
    • elasticsearch
    • syslog

Optional Parameters

  • enabled - (Optional, defaults to false) This is a flag to enable the event sink configuration. All configurations with enabled set to false will ignore all event sink events
  • IsAudit - (Optional, defaults to false) This is a flag used to instruct DevOps Secrets Safe to send audit events to this sink in addition to logs. Auditing provides details of events in the application and can create some overhead in requests so audit logging configurations are given their own flag.
  • options - (Optional) This is an array of key-value pairs to provide extra arguments for the event sink configuration. Some event sink types require specific options.

For example, if you provided an event sink configuration with a level of "warning" then a log event with the level "error" would be processed by your event sink but an event with the level of "information" would not. It should be noted that setting the IsAudit field to true will result in this field being ignored when determining if an event sink should process an event.

Event Sink Provider Specific Options

All event sinks have the following fields in common:

  • name
  • enabled
  • IsAudit
  • level
  • type

The type field is what determines what, if any, options are required.

Console configuration does not require or support any additional options beyond the common fields listed above

  • Uri - (Required) The uri of the syslog server the logs will be shipped to
  • Authentication (optional) the type of authentication on the syslog instance. Currently only one supported value is certificate
  • Certificate - (required if authentication type certificate) base64 encoded PKCS#12 formatted keystore used by server to authenticate client
  • ValidateServerCertificate (optional) boolean indicating special client-side certificate verification should be enforced.
    • Warning: setting this to false will disable client-side validation.
  • TrustedCaCertificate - (Required if ValidateServerCertificate is true) - base64 encoded public certificate of the certificate authority that has signed the server certificates

Example Syslog logger configuration:

	"Name": "external_syslog",
	"Enabled": true,
	"IsAudit": false,
	"Level": "information",
	"Type": "syslog",
	"Options": {
		"uri": tcp://127.0.0.1:9200",
		"Authentication": "Certificate",
		"Certificate": "SGVsbG8gY3Vy",
		"ValidateServerCertificate": true,
		"TrustedCaCertificate": "LS0tLS1CRUdJ=="
	}
  • Uri - (Required) The uri of the elasticsearch instance the logs will be shipped to.
  • Authentication (optional) the type of authentication on the elasticsearch instance. Supported values are basic and certificate
  • Username - (Required if authentication type basic. Can also be used with certificate authentication but is optional) username to use for authentication
  • Password - (Required only if authentication type basic. Can also be used with certificate authentication but is optional) password to use for authentication
  • Certificate - (Optional) base64 encoded PKCS#12 formatted keystore used by server to authenticate client
  • ValidateServerCertificate (optional) boolean indicating client-side certificate verification should be enforced
  • TrustedCaCertificate - (Required if ValidateServerCertificate is true) - base64 encoded public certificate of the certificate authority that has signed the server certificates

Example Elasticsearch logger configuration:

{
	"Name": "external_elasticsearch",
	"Enabled": true,
	"IsAudit": false,
	"Level": "information",
	"Type": "elasticsearch",
	"Options": {
		"uri": "https://127.0.0.1:9200",
		"Authentication": "Certificate",
		"Username": "elastic",
		"Password": "elasticPass",
		"Certificate": "SGVsbG8gY3Vy",
		"ValidateServerCertificate": true,
		"TrustedCaCertificate": "LS0tLS1CRUdJ=="
	}
}