Exporting Alerts to ELK – Capsule8

Overview

Elasticsearch allows users to capture data that is sent from the Capsule8 sensor in JSON format. Kibana also allows users to select the way they want to visualize the data coming from the Capsule8 sensor, enabling users to build interactive dashboards based on needs. In this ELK walkthrough, we will use a simple deployment scenario of a Capsule8 Sensor deployed to a non-containerized Linux production server.

This article will also address how Filebeat, which is a lightweight shipper for forwarding and centralizing log data can be used to ingest Capsule8 alerts from a Capsule8 Sensor into an ELK Stack. In addition, we will also cover sending alert data to ELK via webhook from the Capsule8 Sensor.

Requirements

FIlebeat v7.0 (minimum version)
ELK Stack (Elasticsearch, Logstash & Kibana)
Capsule8 Sensor

Note: It is very important that before performing any of these steps in the article users have the Capsule8 sensor running in their environment. If users have not already, see the Capsule8 Installation Guide for instructions on installing the Capsule8 Sensor in the deployment environment.

1. Configuring the Capsule8 Sensor to Log Alerts

We will be configuring the Capsule8 Sensor to log alert data to a file called /var/log/capsule8-alerts.json with a simple program blacklist which will generate an alert every time users run the program wget. To do that navigate into the below file using your preferred text editor.

/etc/capsule8/capsule8-analytics.yaml

then add the below:

alert_output:
  outputs:
    - type: file
      enabled: true
      name: /var/log/capsule8-alerts.json

Wget Program Blacklist:
  policy: program
  enabled: true
  alertMessage: Unauthorized Program Execution
  priority: High
  rules:
  - match programName == "*/wget"
  - default ignore
  comments: Alert on usage of the wget command

Ensure that Capsule Sensor is restarted

$ sudo systemctl restart capsule8-sensor   # Recommended to restart when changes are made to the sensor configuration

2. Exporting Capsule8 Sensor Alerts to Filebeat

Now that the Capsule8 sensor has been configured to log alerts users can proceed with exporting the alerts to Filebeat. Using the Elastic’s Filebeat users can ingest Capsule8 Alerts from a Capsule8 Sensor into the ELK Stack.

To do that, locate your system’s Filebeat yaml file which is this /etc/filebeat/filebeat.yml and add the below input:

filebeat.inputs:
- type: log
  paths:
    - /var/log/capsule8-alerts.json
  json.keys_under_root: true
  json.add_error_key: true

This will not only ingest alerts but will also parse the JSON data for you so that the individual top-level alert fields are easily indexed.

Restart Filebeat and you are done! Any alerts generated on the server should now show up in your Elastic deployment.

Test

To generate an alert with our example policy, run a wget command on your server. User should see a resulting alert for Unauthorized Program Execution

3. Exporting Capsule8 Sensor Alerts Directly to Elasticsearch

With Elasticsearch users can automatically search and retrieve data using the Elasticsearch API. Elasticsearch will allow users to store, search and analyze data coming from Capsule8 sensor at near real time. This article assumes that users already have Elasticsearch running. Therefore, to configure Elasticsearch to receive alerts from the Capsule8 sensor users will have to edit this file using preferred text editor.

/etc/capsule8/capsule8-analytics.yaml

and add the below content:

alert_output:
   outputs:
     - type: webhook
       enabled: true
       url: http://elasticservice.customer.com:9200/capsule8-alerts/documents
       headers:
         "Content-Type": "application/json"

Wget Program Blacklist:
   policy: program
   enabled: true
   alertMessage: Unauthorized Program Execution
   priority: High
   rules:
   - match programName == "*/wget"
   - default ignore
   comments: Alert on usage of the wget command

Please see below on how to set your configs:

Setting the URL

url: # http://yourURL:9200/capsule8-alerts/documents

Once again, this will not only ingest alerts but will also parse the JSON data for you so that the individual top-level alert fields are easily indexed. Any alerts generated on the server should now show up in your Elastic deployment.

Test

To generate an alert with our example policy, run a wget command on your sensor server. User should see a resulting alert for Unauthorized Program Execution

4. Visualizing the Capsule8 Sensor Alerts on Kibana

Using Kibana users can visualize the logs coming from the Capsule8 sensor. Kibana provides a visual interface that allows users to detect, monitor behaviors and build dashboards thereby providing visibility for understanding and analyzing alerts coming from Capsule8 sensor.

From the previous steps covered in this article and assuming that users have Kibana set up to consume or ingest alert coming from either the Filebeat and/or Elastisearch. Users should be able to see the test alert that was generated using our example policy when wget command was executed on their server as shown in the image:

If a user haven't created an index please do that by following the steps below. Users should ignore the steps below if index is already created or have a suitable way of creating indexes.

Steps

1. On your Kibana dashboard navigate to Settings --> Elasticsearch --> Index Management. Create an index called Capsule8-alerts. On next page select Timestamp (although depends on users preference)

2. After index (capsul8-alerts) has been created users can manipulate the data and decide from the Available Fields what your organization want to visualize. We also recommend that users add in their field description, linage,uuid, policy_type etc.