Capsule8 performs advanced behavioral monitoring for cloud-native, containers, and traditional Linux-based servers. This repository contains the open-source components of the Capsule8 platform, including the Sensor, example API client code, and command-line interface.
Capsule8 is current in alpha and under active development. The gRPC
API is v0 and subject to change at any time, but we strive to keep the
sample code in examples/
updated with any changes to the API.
For a quick demonstration of the capsule8 sensor's capabilities, start up three terminal sessions to run the sensor, example telemetry client, and target container as described below.
$ git clone https://github.com/capsule8/capsule8.git
$ git submodule init && git submodule update
$ make
Start the Sensor and listen for API clients on the default local unix socket:
$ sudo ./bin/sensor
I1004 18:55:23.111094 9617 version.go:33] Starting sensor (0.0.0+9b149e4)
I1004 18:55:23.111736 9617 sensor.go:121] Starting servers...
I1004 18:55:23.111746 9617 sensor.go:135] Sensor is ready
I1004 18:55:23.111761 9617 telemetry.go:29] Serving gRPC API on unix:/var/run/capsule8/sensor.sock
[...]
The example telemetry client in examples/telemetry
provides a
demonstration of how to use the Telemetry API. It subscribes to the
following telemetry:
- process lifecycle events (
fork
,execve
, andexit
) open(2)
system call return values- file open events for any file name matching the glob
*foo*
- kernel function calls to
SyS_connect
involving IPv4 addresses and returning the parsed outsockaddr
structure elements - container lifecycle events (created, running, exited, destroyed)
If the -image <glob>
argument is specified on the command-line, then
events will be filtered to only containers running images with names
matching the specified glob.
$ go build examples/telemetry/main.go
$ sudo ./examples/telemetry/telemetry -image busy*
Watching for container images matching busy*
event:<id:"978eec0f976c5c5b7867d9d3793bdb89e50e7d920ce3dc816659a4861722fc56" container_id:"4265413fa321921b3c6014f564811a17c9e376a17ade3e7026611ceba48ed955" sensor_id:"52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c649" sensor_sequence_number:3208 sensor_monotime_nanos:208974918639853 container:<type:CONTAINER_EVENT_TYPE_CREATED name:"/nostalgic_galileo" image_id:"c30178c5239f2937c21c261b0365efcda25be4921ccb95acd63beeeb78786f27" image_name:"busybox" > >
event:<id:"8fa21518ff0a2babaa72e6e07c760c0e6573d50787d351b57f47fd1da3606810" container_id:"4265413fa321921b3c6014f564811a17c9e376a17ade3e7026611ceba48ed955" sensor_id:"52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c649" sensor_sequence_number:5130 sensor_monotime_nanos:208975053166529 container:<type:CONTAINER_EVENT_TYPE_RUNNING host_pid:15217 > >
event:<id:"b631682fc0d56ff38e992f8b8afd2e964fc3a61377055bcb5abf46fd4038f37c" process_id:"fafb8d19c3ab7b6934b1fab8354decb50f2d982351984d81bb1b0ef8e6fcf586" process_pid:15217 container_id:"4265413fa321921b3c6014f564811a17c9e376a17ade3e7026611ceba48ed955" sensor_id:"52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c649" sensor_sequence_number:5164 sensor_monotime_nanos:208977310484246 container_name:"/nostalgic_galileo" image_id:"c30178c5239f2937c21c261b0365efcda25be4921ccb95acd63beeeb78786f27" image_name:"busybox" syscall:<type:SYSCALL_EVENT_TYPE_EXIT id:2 ret:3 > process_tid:15217 cpu:5 >
event:<id:"4095d65d394a23be9b574f36c92d9acb1c4ded13955e000657e5aac8570f1926" process_id:"fafb8d19c3ab7b6934b1fab8354decb50f2d982351984d81bb1b0ef8e6fcf586" process_pid:15217 container_id:"4265413fa321921b3c6014f564811a17c9e376a17ade3e7026611ceba48ed955" sensor_id:"52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c649" sensor_sequence_number:5170 sensor_monotime_nanos:208977310715127 container_name:"/nostalgic_galileo" image_id:"c30178c5239f2937c21c261b0365efcda25be4921ccb95acd63beeeb78786f27" image_name:"busybox" process:<type:PROCESS_EVENT_TYPE_FORK fork_child_pid:15298 > process_tid:15217 cpu:5 >
event:<id:"065d00a4e53195b0b8abdd71a1f1abdf1d233e98656f92f750f0661b1a145e92" process_id:"2a7536fb3b396281e05e4602f546745819a34741462a8aaeff7aca514f3b2898" process_pid:15298 container_id:"4265413fa321921b3c6014f564811a17c9e376a17ade3e7026611ceba48ed955" sensor_id:"52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c649" sensor_sequence_number:5196 sensor_monotime_nanos:208977312517716 container_name:"/nostalgic_galileo" image_id:"c30178c5239f2937c21c261b0365efcda25be4921ccb95acd63beeeb78786f27" image_name:"busybox" process:<type:PROCESS_EVENT_TYPE_EXEC exec_filename:"/bin/ls" > process_tid:15298 cpu:7 >
event:<id:"b7b23c45ad2c1d868be4754933bc8ad8af09ee473292a54ca1f077bd2a08c5ba" process_id:"2a7536fb3b396281e05e4602f546745819a34741462a8aaeff7aca514f3b2898" process_pid:15298 container_id:"4265413fa321921b3c6014f564811a17c9e376a17ade3e7026611ceba48ed955" sensor_id:"52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c649" sensor_sequence_number:5197 sensor_monotime_nanos:208977312711734 container_name:"/nostalgic_galileo" image_id:"c30178c5239f2937c21c261b0365efcda25be4921ccb95acd63beeeb78786f27" image_name:"busybox" syscall:<type:SYSCALL_EVENT_TYPE_EXIT id:2 ret:3 > process_tid:15298 cpu:7 >
[...]
event:<id:"faf7110112131d6797f7edb75f053926f05026792da1cf72b4efed50b2cf04a2" container_id:"4265413fa321921b3c6014f564811a17c9e376a17ade3e7026611ceba48ed955" sensor_id:"52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c649" sensor_sequence_number:6043 sensor_monotime_nanos:208979802583554 container:<type:CONTAINER_EVENT_TYPE_EXITED name:"/nostalgic_galileo" image_id:"c30178c5239f2937c21c261b0365efcda25be4921ccb95acd63beeeb78786f27" image_name:"busybox" exit_code:1 > >
event:<id:"ba6a5118c6314209ec317472355638106a127ccfb75c45adf00fc8c7d8c778ea" container_id:"4265413fa321921b3c6014f564811a17c9e376a17ade3e7026611ceba48ed955" sensor_id:"52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c649" sensor_sequence_number:6044 sensor_monotime_nanos:208979811686154 container:<type:CONTAINER_EVENT_TYPE_DESTROYED > >
In order to generate matching telemetry, start a busybox container in another terminal:
$ docker run --rm -it busybox
docker run --rm -it busybox
/ # ls
bin dev etc home proc root sys tmp usr var
/ # cat /foo
cat: can't open '/foo': No such file or directory
/ # exit
For contributing guidelines see CONTRIBUTING.
The Sensor is intended to be run on a Linux host persistently and ideally before the host begins running application workloads. It is designed to support API clients subscribing and unsubcribing from telemetry dynamically to implement various security incident detection strategies.
Container lifecycle, process lifecycle, raw system calls, file opens, network activity, and kernel function calls.
You can subscribe to calls to a chosen exported function symbol and receive telemetry events with named values of the data requested. This data can include function call arguments, return values, register values, and even values dereferences via offsets from any of them. For a more detailed description of what's possible, see the Linux kernel kprobe docs.
The Sensor provides telemetry events on a best-effort
basis. System-level events are intentionally monitored through
perf_event_open(2)
such that an excessive volume of events causes
them to be dropped by the kernel rather than blocking the kernel as
the audit subsystem may do. This means that telemetry events, and even
some of the information within them, is "lossy" by design. We believe
that this is the right trade-off for monitoring production
environments where stability and performance are critical.