Capsule8 Docs
Capsule8 Docs

Installing the Sensor on AWS EC2

This is a quick start guide for installing the Capsule8 Sensor on AWS EC2.

Before you begin

In order to use this guide, you will need to have a Packagecloud access token that will be provided by Capsule8. This will give you access to Capsule8’s Debian and RPM packages.


The Capsule8 Sensor is a security agent that runs in Linux production environments. It supports everything from cloud-native workloads through containerized environments down to bare metal.

Within AWS there are a number of different ways this environment can be architected depending on an organization’s security requirements, service preference, and workflows. This guide will focus on a straightforward manual installation using one EC2 instance to illustrate how the components fit together. It can be adapted or expanded as needed from there.

Each Sensor instance can run on a t2.micro instance type. This guide is written for 64-bit x86 Ubuntu Server 16.04 LTS. Capsule8 supports a number of other Debian- and RPM-based distros. Please contact Capsule8 to verify support for distros/versions.


Create Security Groups

In this section, we are going to create a security group for the Capsule8 Sensor. For the sake of simplicity, the Source values are set to Any here, but it is recommended that the asterisks below are replaced with the security group ID to ensure that only resources in your security group can access these ports.

SSH is recommended for direct access, however, it is not required. Configuration can optionally be handled through a configuration management system or through features like EC2 user data.

Capsule8 Sensor

Type Protocol Port Range Source Description
Custom TCP TCP 9010 Any* Healthz

Launch the EC2 Instance

In this section, we are going to create one EC2 instance for the Capsule8 Sensor. No custom IAM role is needed for the instance unless you want to authorize sending Alerts from the Capsule8 Sensor instances to S3 using an IAM role. This authorization can also be provided without the use of an IAM role by setting an access key ID and secret access key in either environment variables or the Capsule8 Analytics configuration file on each instance.

Capsule8 Sensor

Launch a t2.micro instance with 64-bit x86 Ubuntu Server 16.04 LTS.

Configure the EC2 Instance

In this section, we are going to install and configure Capsule8. In a production deployment none of this would be done manually, however, for the sake of simplicity this guide will assume you have manually accessed the instances via SSH. There are two YAML configuration files that control the Capsule8 Sensor. One holds the Capsule8 Analytics security rules and the other is specifically for the Capsule8 Sensor settings. By default, these files are kept in /etc/capsule8 but this location can change if desired. Environment variable configuration is also possible.

Install the Package Repository

Capsule8 will provide you with a Packagecloud access token that will be used to install the package repository locally on the instance. Export the token as an environment variable before running the following command. Be sure to replace ${PACKAGECLOUD_TOKEN} with your token.

    $ curl -s https://$ | sudo bash

Capsule8 Sensor

Run the following to install the latest release of the Capsule8 Sensor package:

	$ sudo apt-get install capsule8-sensor-systemd=4.1.0

Create the directory for your Capsule8 Sensor and Capsule8 Analytics configuration files:

  $ mkdir -p /etc/capsule8

To configure Capsule8 Analytics open `/etc/capsule8/capsule8-analytics.yaml` and add:

# Print alerts to stdout and write them to a file
 - type: stdout
   enabled: true
 - type: file
   enabled: true
   file: /var/log/capsule8-alerts.json

# Define an example policy as a proof of concept
Blacklist wget:
policy: program
alertMessage: Unauthorized execution of wget
comments: This policy detects the use of wget
priority: High
enabled: true
- match programName == "*/wget"
- default ignore

Finally, restart the Capsule8 Sensor to load the new configuration and check the startup logs:

$ sudo systemctl restart capsule8-sensor
$ sudo journalctl -ef -u capsule8-sensor

You should see 1 strategies configured in the Capsule8 Sensor logs. If you run wget now, a JSON Alert should be logged out. You’re deployed!

Installing Standard Detections

Next update to a recommended set of detections by installing the content package:

$ sudo apt-get install capsule8-content=4.1.0
$ sudo systemctl restart capsule8-sensor