Capsule8: open-source cloud-native behavioral security monitoring
orangematt Merge pull request #232 from capsule8/mmessier/tracepoint-decoder-fix
Separate trace event decoders from format information
Latest commit 5593078 Aug 17, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Simplify golint go get command in circle ci pipeline Apr 25, 2018
.github Replace dino with brandon as code owner Jun 5, 2018
api Surface hardware/software performance events through the sensor API May 22, 2018
cmd/sensor Apply copyright and license to all source files. Dec 15, 2017
docs Surface hardware/software performance events through the sensor API May 22, 2018
examples Refactor to remove the use of protobuf structs internally Jul 26, 2018
pkg Separate trace event decoders from format information Aug 17, 2018
scripts Improve/fix tracking of execve events for all kernel versions Aug 17, 2018
test Refactor to remove the use of protobuf structs internally Jul 26, 2018
third_party Add google protobuf as submodule since older versions of protoc Dec 28, 2017
vendor @ ca4295e Update golang.org/x/sys Apr 16, 2018
.dockerignore Refactor CI build to enable more testing. Nov 13, 2017
.gitignore Add the example command-line-tool binary to .gitignore Mar 8, 2018
.gitmodules Add google protobuf as submodule since older versions of protoc Dec 28, 2017
CHANGELOG.md Update CHANGELOG Jul 5, 2018
Dockerfile Apply consistency to network endpoint address naming. Dec 28, 2017
Dockerfile.builder Refactor CI to use CircleCI. Dec 28, 2017
Gopkg.lock Update golang.org/x/sys Apr 16, 2018
Gopkg.toml Bump to gRPC 1.11.2. Apr 5, 2018
HACKING.md Refactor CI to use CircleCI. Dec 28, 2017
LICENSE Adding Apache 2.0 as LICENSE. Oct 5, 2017
Makefile Refactor the sensor to not use protobuf structures internally Jul 26, 2018
README.md Add link in README to api protocol docs Feb 27, 2018
Vagrantfile Add Vagrantfile for basic VM testing. Oct 13, 2017

README.md

Capsule8

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.

Go Report Card GoDoc License

CircleCI

Status

Capsule8 is currently 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.

Docs

Contributing

For contributing guidelines see CONTRIBUTING.

Quickstart

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.

Checkout latest code

$ git clone https://github.com/capsule8/capsule8.git
$ git submodule init && git submodule update

Build the sensor

$ make

Start the sensor

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
[...]

Subscribe to telemetry for specified container images

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, and exit)
  • 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 out sockaddr 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 > > 

Generate events in a matching container

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