Overview

The Capsule8 Sensor is a lightweight agent installed on Linux hosts, collecting events from the hosts to trigger alert generation and/or automated response. The Capsule8 sensor integrate with your existing logging and alerting infrastructure. The Sensor can be deployed wherever you have Linux – in public or private cloud enviroments, in containers or VMs, in on-premises bare metal hosts, each supporting a large number of kernel versions and Linux distributions.

Capsule8 maintains an external Docker registry where Docker images of the Capsule8 components are made available to customers.

You can run this Docker image in your desired environment to protect the host machine.

Requirements

• Docker is installed and running
• Ensure you have a Google Cloud Platform service account key file, which will be provided to you by your Capsule8 representative.
  • Save the key file locally to ~/.gcloud/key-file.json 
  • The gcloud command line tool has been installed. This will let you pull images from the Capsule8 Docker registry. gcloud is a tool included in the  Google Cloud SDK. 
• Kubernetes is not in use (If it is, follow these instructions instead)

Authorization

The Capsule8 Docker images are not publicly available; you must first configure authorization. 

Service Account Key File

Ask your Capsule8 representative for a service account key file to begin. Once you have the service account key file, save it to ~/.gcloud/key-file.json on a machine that will be used to pull and store the Capsule8 images and prepare them for use. Below is an example service account key file:

{
    "type": "service_account",
    "project_id": "cap8-docker",
    "private_key_id": "<>",
    "private_key": "-----BEGIN PRIVATE KEY-----\\abcde12345678910\\abcde12345678910\\n-----END PRIVATE KEY-----\\n",
    "client_email": "< client name >@cap8-build.iam.gserviceaccount.com",
    "client_id": "12345678910111213",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://accounts.google.com/o/oauth2/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/< client name >%40cap8-docker.iam.gserviceaccount.com"
}

GCloud

Once you have saved your service account key file, install gcloud, which will let you pull images from the Capsule8 registry. GCloud is a command-line tool included in the Google Cloud SDK.

Once GCloud is installed, authorization to gain access to the registry can be performed with the following command:

$ gcloud auth activate-service-account < your name >@cap8-docker.iam.gserviceaccount.com --key-file=~/.gcloud/key-file.json

Confirm successful authorization by pulling a Sensor image from our container registry using the gcloud CLI:

 $ gcloud docker -- pull us.gcr.io/cap8-docker/capsule8-sensor:4.10.1

Usage

The Sensor will not do anything useful if you just docker run us.gcr.io/cap8-docker/capsule8-sensor:4.10.1. It requires non-default access to the host, in order to protect more than its docker sandbox.

For all deployments:

On the host, create a folder for the Capsule8 Sensor configuration files, and create two files there. This documentation uses /etc/capsule8, but you can place these in any location, as long as you modify the host's mount point in the subsequent docker run command.

mkdir -p /etc/capsule8
$EDITOR /etc/capsule8/capsule8-analytics.yaml
$EDITOR /etc/capsule8/capsule8-sensor.yaml

Populate the configuration files. Suggested starting points:

capsule8-analytics.yaml

# blank or a comment

capsule8-sensor.yaml

debug: false
alert_output:
  outputs:
  - type: stdout
    enabled: true
    template: 'Fired: {{ .StrategyName}}'

For deployments where the Capsule8 Console configures the Sensor:

You don't need to create a file with Capsule8 Content, the Console will handle providing content information to the Sensor. Modify the capsule8-sensor.yaml file you just created to tell it how to communicate with your Console, by following steps 2 and 3 of Enabling Console control of the Sensor.

Proceed below to "Run the Sensor container".

For deployments where the Capsule8 Console does not configure the Sensor:

Create a folder on the host where Capsule8 Content yaml rules will go. This documentation uses /tmp/capsule8-content but you can place it in any location, as long as you modify the host's mount point in the subsequent docker run command.

mkdir /tmp/capsule8-content

Run the one-shot capsule8-content container; this will copy the detection rules into the folder we just created:

docker run \
-v /tmp/capsule8-content:/var/lib/capsule8/content:rw \
us.gcr.io/cap8-docker/capsule8-content:4.9.0

It's expected behavior that Docker reports this container in a state "Exited".

You can confirm that /tmp/capsule8-content/capsule8-content.yaml now exists, it should have thousands of lines.

Proceed below to "Run the Sensor container".

Run the Sensor container

On the host, run:

docker run \
--pid=host \
--privileged \
--user=0 \
--detach \
-v /etc/capsule8:/etc/capsule8:rw \
-v /tmp/capsule8-content:/var/lib/capsule8/content:rw \
-v /sys/fs/cgroup:/var/run/capsule8/mnt/sys/fs/cgroup:ro \
-v /sys/kernel/debug:/var/run/capsule8/mnt/sys/kernel/debug:rw \
-v /etc/hostname:/var/run/capsule8/mnt/hostname:ro \
-v /proc:/var/run/capsule8/mnt/proc:ro \
-v /var/lib/docker:/var/lib/docker:ro \
-v /var/run/docker:/var/run/docker:ro \
--cap-add SYS_ADMIN --cap-add SETUID --cap-add SETGID --cap-add SETPCAP \
--cap-add SYS_PTRACE --cap-add KILL --cap-add DAC_OVERRIDE --cap-add IPC_LOCK \
--cap-add FOWNER --cap-add CHOWN --cap-add SYSLOG \
us.gcr.io/cap8-docker/capsule8-sensor:4.10.1

Confirm Sensor Functionality

Both Capsule8 Content from the container, and Capsule8 Content from the Console, default to a set of protections that include the "Suspicious Interactive Shell" detection. We'll use this to confirm that the sensor can detect activity on the host.

Container is running?

On the host, run:

docker ps

Look for a capsule8-sensor container.

Confirm that its "STATUS" column contains "Up".

Copy the "CONTAINER ID" for the next step.

Startup logs are present?

On the host, run:

docker logs <containerID>

A typical startup will end with the line "Analytics started processing telemetry".

If you see "Zero policies configured" it means that the sensor does not have any enabled detection rules. It's likely that Console is not serving policies to the Sensor; and Sensor is not loading Capsule8 Content policies from disk. Contact Capsule8 technical support to resolve the issue. 

Detection can be triggered?

On the host, run:

/bin/sh -i
exit

This command triggers the Suspicious Interactive Shell detection. If the Sensor is configured correctly, it will report the activity.

The capsule8-sensor.yaml file in this documentation contains a "stdout" alert output type with a custom template, allowing us to check the logs to see the alert that was triggered. If you've customized your alert outputs, you may have to look elsewhere.

docker logs <containerID>
...
Fired: Suspicious Interactive Shell