Event Sinks

Event Sink Configuration

DevOps Secrets Safe supports multiple event sink providers. Event sink configuration can be modified at runtime by using the command line interface.

Create an Event Sink Configuration

ssrun event-sink create -f elk.json

This command creates an event sink configuration using the values in the file elk.json. Details on the structure of the configuration file are outlined in the section below.

List Event Sink Configurations

ssrun event-sink get

This command gives you a list of configured event sinks as JSON.

 
  {
      "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 command deletes the event sink with the given name.

Event Sink Configuration File Structure

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: Friendly name for the event sink. This is the name that you provide to ssrun event-sink delete if you delete the event sink later.
  • level: This is the minimum event sink event level that this event sink configuration processes. Valid levels, in ascending order, are:
    • verbose
    • debug
    • information
    • warning
    • error
    • fatal
  • type: The event sink provider type to use. The following are supported event sink types:
    • console
    • Elasticsearch
    • syslog
  • If you using the Elasticsearch or syslog event sink provider type, there are additional required and optional parameters, as listed below.

Optional Parameters

  • enabled: (defaults to false). This is a flag to enable the event sink configuration. All configurations with enabled set to false ignore all event sink events
  • IsAudit: (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: 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 provide an event sink configuration with a level of warning, a log event with the level error is processed by your event sink; however, an event with the level of information is not processed.

Setting the IsAudit field to true results in this field being ignored when determining if an event sink will process an event.

Paramter Required Description
uri Yes This is the URI of the syslog server the logs are shipped to.
Authentication Optional The type of authentication on the syslog instance. Currently the only supported value is certificate.
Certificate Yes, if authentication type is certificate
  • Base64 encoded PKCS#12 formatted keystore used by server to authenticate client.
  • ValidateServerCertificate Optional Boolean indicating special client-side certificate verification will be enforced.
    TrustedCaCertificate Yes, if ValidateServerCertificate is true Base64 encoded public certificate of the certificate authority that has signed the server certificates.

     

    Setting ValidateServerCertificate to false disables client-side validation.

     
    {
    	"Name": "external_syslog",
    	"Enabled": true,
    	"IsAudit": false,
    	"Level": "information",
    	"Type": "syslog",
    	"Options": {
    		"uri": tcp://sysloghost:514",
    		"Authentication": "Certificate",
    		"Certificate": "SGVsbG8gY3VyaW91cyBkZXZlbG9wZXIuIFBsZWFzZSBwcmV0ZW5kIEknbSBhIHBrMTIgZm9ybWF0ZWQgY29udGFpbmVyISBUaGFua3MgZm9yIGxvb2tpbmch",
    		"ValidateServerCertificate": true,
    		"TrustedCaCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURJekNDQWd1Z0F3SUJBZ0lWQU43c0VHT005Z3JtZFpZd2txNnBxTTZsbWdNdE1BMAotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg=="
    	}
    }
    Paramter Required Description
    uri Yes The URI of the Elasticsearch instance the logs are shipped to.
    Authentication Optional The type of authentication on the Elasticsearch instance. Supported values are basic and certificate.
    Username:
  • Yes, if authentication type is basic.
  • Optional with certificate authentication.
  • User name for authentication.
    Password Yes, if authentication type is basic.
    Optional with certificate authentication.
    Password for authentication.
    Certificate Optional
  • Base64 encoded PKCS#12 formatted keystore used by server to authenticate client.
  • ValidateServerCertificate Optional Boolean indicating special client-side certificate verification will be enforced.
    TrustedCaCertificate Yes, if ValidateServerCertificate is true Base64 encoded public certificate of the certificate authority that has signed the server certificates.
     Elasticsearch Logger Configuration Using Certificate Authentication
    {
    	"Name": "external_elasticsearch",
    	"Enabled": true,
    	"IsAudit": false,
    	"Level": "information",
    	"Type": "elasticsearch",
    	"Options": {
    		"uri": "https://elkhost:9200",
    		"Authentication": "Certificate",
    		"Username": "elastic",
    		"Password": "elasticPass",
    		"Certificate": "SGVsbG8gY3VyaW91cyBkZXZlbG9wZXIuIFBsZWFzZSBwcmV0ZW5kIEknbSBhIHBrMTIgZm9ybWF0ZWQgY29udGFpbmVyISBUaGFua3MgZm9yIGxvb2tpbmch",
    		"ValidateServerCertificate": "true",
    		"TrustedCaCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURJekNDQWd1Z0F3SUJBZ0lWQU43c0VHT005Z3JtZFpZd2txNnBxTTZsbWdNdE1BMAotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg=="
    	}
    }
     Elasticsearch Logger Configuration Using No Authentication
    {
    	"Name": "external_elasticsearch",
    	"Enabled": true,
    	"IsAudit": false,
    	"Level": "information",
    	"Type": "elasticsearch",
    	"Options": {
    		"uri": "http://elkhost:9200"
    	}
    }