Installing the Sensor on Kubernetes

Overview

The Sensor is a lightweight agent installed on Linux hosts, collecting events from the hosts to trigger alert generation or automated response. The Capsule8 sensor integrates with your existing logging and alerting infrastructure. The Sensor can be deployed wherever you have Linux – in public or private cloud, containers or VMs, on-prem bare metal, and across different kernel versions and Linux distributions.

Requirements

• kubectl v1.18 or higher
• eksctl (optional)
• Google Cloud Platform service account key file which will be provided to you by Capsule8
  • Save the key file provided to you by Capsule8 file locally to ~/.capsule8/service-account.json 
  • Make a note of the email address in that file. 
• Additional requirement can be found here 

The Kubernetes manifest yaml file contain a ConfigMap and a DaemonSet for the Capsule8 Sensor and along with the associated Capsule8 Analytics config file. This will install the Capsule8 Sensor, Capsule8 Console, and a Postgres database for evaluation purposes.

Installation

1. Initial Setup Verification

Before starting, verify that kubectl is configured to point to your target installation cluster:

$ kubectl config current-context

Note:

If you do not already have a test cluster already Capsule8 recommends using eksctl to spin up an EKS cluster which can be as simple as running the command:

$ eksctl create cluster

For more information on eksctl, see the official AWS documentation.

2. Create Kubernetes Secret

Set an environment variable in the terminal that you plan on using:

$ export CAPSULE8_SERVICE_ACCOUNT_EMAIL=${SERVICE_ACCOUNT_EMAIL}

Replace ${SERVICE_ACCOUNT_EMAIL} with the email from your service account key file before running the following kubectl command to create a new Kubernetes Secret. This secret will be used to authenticate your kubelet so that it can pull from our private container registry.

$ kubectl create secret docker-registry capsule8-registry-secret  \
  --docker-username=_json_key                                     \
  --docker-server=https://us.gcr.io                               \
  --docker-email=$CAPSULE8_SERVICE_ACCOUNT_EMAIL                  \
  --docker-password="$(cat ~/.capsule8/service-account.json)"

Now run the below command to see your new Secret:

$ kubectl get secrets

You should now see your new Secret. This secret will be used to authenticate your kubelet so that it can pull from our private container registry although other registries can be used.

Note: Please note that access is granted specifically for our manifests which references the K8s docker-registry capsule8-registry-secret

3. Apply the Manifest

Download a copy of the manifest provided by Capsule8 and apply it:

$ kubectl apply -f https://capsule8-assets.s3.amazonaws.com/latest/capsule8-sensor-manifest.yaml
$ kubectl get pods -l app=capsule8-sensor

The manifest should create a capsule8-sensor DaemonSet and capsule8-sensor-config ConfigMap.

You should now see Capsule8 Sensor pods starting up. If you do not see them be sure to check your cluster’s pod security policy and, if necessary, grant exceptions for the capabilities required by the sensor. For a full list of these capabilities, please see the DaemonSet or reach out to Capsule8.

4. Generate an Alert

The logs for the sensor pods should list all the configured policies:

$ kubectl logs $SENSOR_POD_NAME

To generate a quick test alert, exec into one of the sensor pods:

$ kubectl exec -it $SENSOR_POD_NAME -- /bin/sh  

Starting an interactive shell not spawned by sshd or screen violates the interactiveShell policy, which will trigger an alert. Currently, the sensor is configured to print alerts out to standard out, which can be seen if you view the logs from the pod that generated the alert:

$ kubectl logs $SENSOR_POD_NAME

Alerts can also be sent out to webhooks, written directly to cloud blob storage buckets, written to local files on the file system with log rotation, and sent to syslog. See the Alert Dispatcher Guide for documentation on the various other ways the sensor can send alerts.