Capsule8 Docs
Capsule8 Docs

Sensor Configuration

After you have installed the Capsule8 sensor, you can configure the sensor’s functionality as well as optionally pair the sensor with the Capsule8 server.

By default, the Capsule8 sensor looks in /etc/capsule8 for a capsule8-sensor.yaml file. This file is not automatically created upon installation, but can be created by the user to store configuration values.

The sensor can also be run with environment variables via command line. Most configuration options for the sensor can be set either as a variable or a value in capsule8-sensor.yaml, as documented in the table in the following section. If a configuration variable is set in both capsule8-sensor.yaml and in the command line, the command line value overrides. If a configuration variable is not set, it reverts to the default value.

For example, to turn on debug mode for the sensor, either run sensor as sudo CAPSULE8_DEBUG=true capsule8-sensor or set the following in capsule8-sensor.yaml:

debug: true

If sudo CAPSULE8_DEBUG=true capsule8-sensor is run and the yaml is:

debug: false

then debug will be set to true, as the command line value overrides. If neither is set, then debug will be set to false, which is the default.

Note: /etc/capsule8 contains two configuration files: capsule8-sensor.yaml for sensor configuration and capsule8-analytics.yaml for detection content. Editing the detections configuration file is discussed further in Adjusting Default Detections.

Configuring the Sensor

The following table describes the environment variables and configuration file values used by the Capsule8 sensor. Configuration file values are written as object.subobject. For example, the following yaml entry

   url: nats://localhost:4222

is written as console.url.

Variable Name Configuration File Value Type Meaning Default Example
CAPSULE8_CONFIG N/A string Alternate location and name of the capsule8-sensor.yaml file /etc/capsule8/capsule8-sensor.yaml CAPSULE8_CONFIG=/var/run/myconfig.yaml
CAPSULE8_LABELS service.metadata.labels string a string of key value pairs separated by = metadata about the sensor host “” CAPSULE8_LABELS=“mtahost=true”
CAPSULE8_DEBUG debug boolean whether or not to enable debugging / profiling features and logging false CAPSULE8_DEBUG=true
CAPSULE8_LOG_OUTPUT log_output string path which to write service logs “” CAPSULE8_LOG_OUTPUT=/var/log/capsule8-sensor.log
CAPSULE8_LOG_LEVEL log_level string message level at which to log info CAPSULE8_LOG_LEVEL=debug
CAPSULE8_CONSOLE_URL console.url string The address of the Capsule8 Console’s NATS instance nats://localhost:4222
CAPSULE8_CONSOLE_MAX_RECONNECTS console.max_reconnects integer number of times the client should attempt to reconnect after it’s already been connected 10000 CAPSULE8_CONSOLE_MAX_RECONNECTS=3
CAPSULE8_CONSOLE_RECONNECT_BUF_SIZE_IN_MB console.reconnect_buf_size_in_mb integer amount of data to buffer in the event of a disconnection in megabytes 10 CAPSULE8_CONSOLE_RECONNECT_BUF_SIZE_IN_MB=1
CAPSULE8_CONSOLE_RECONNECT_WAIT console.reconnect_wait integer number of seconds the the NATS client should wait between connection attempts 10 CAPSULE8_CONSOLE_RECONNECT_WAIT=3
CAPSULE8_CONSOLE_CLIENT_CERT_FILE console.client_cert_file string path to x509 certifate A TLS client certificate to present to the Capsule8 Console NATS instance ( must be used with CAPSULE8_CONSOLE_CLIENT_CERT_KEY_FILE) “” CAPSULE8_CONSOLE_CLIENT_CERT_FILE=/home/user/client.crt
CAPSULE8_CONSOLE_CLIENT_CERT_KEY_FILE console.client_cert_key_file string path to x509 certifate key The path to the key for the certificate in CAPSULE8_CONSOLE_CLIENT_CERT_FILE ( must be used with CAPSULE8_CONSOLE_CLIENT_CERT_FILE) “” CAPSULE8_CONSOLE_CLIENT_CERT_KEY_FILE=/home/user/client.crt
CAPSULE8_CONSOLE_CLIENT_CA_CERT console.client_ca_cert string path to x509 CA certifcate An additional TLS CA certificate to use to verify the client. By default the system CAs are used “” CAPSULE8_CONSOLE_CLIENT_CA_CERT=/usr/local/cas/myCA.crt
CAPSULE8_INITIAL_RECONNECT_ATTEMPTS initial_reconnect_attempts integer the number of times the sensor attempts to connect to the console before giving up at startup 3 CAPSULE8_INITIAL_RECONNECT_ATTEMPTS=8
CAPSULE8_MONITOR_PORT monitor_port integer TCP port to serve health checks, version, varz and profiling endpoints 9010 CAPSULE8_MONITOR_PORT=9999
CAPSULE8_LISTEN_ADDR listen_addr string socket address for the sensor telemetry service to listen on (can be a unix socket) unix://var/run/capsule8/sensor.sock CAPSULE8_LISTEN_ADDR=localhost:8443
CAPSULE8_EVENTS_PER_MESSAGE bundler.events_per_message integer number of telemetry events to send to the console at a time, useful for microbatching / controlling network impact of the sensor 1 CAPSULE8_EVENTS_PER_MESSAGE=250
CAPSULE8_EVENTS_FLUSH_TIMEOUT bundler.flush_timeout duration string maxmium amount of time Telemetry Events can stay buffered in the sensor before being sent to the Capsule8 Console “100ms” CAPSULE8_EVENTS_FLUSH_TIMEOUT=“250ms”
CAPSULE8_OPENTRACING_TRACER_TYPE opentracing.tracer_type string a supported open tracing implementation right now only jaeger is supported “” CAPSULE8_OPENTRACING_TRACER_TYPE=jaeger
CAPSULE8_OPENTRACING_TRACER_LOG opentracing.tracer_log boolean log opentracing information to standard out false CAPSULE8_OPENTRACING_TRACER_LOG=true
CAPSULE8_USE_ANALYTICS use_analytics boolean activate embedded analytics package (activate’s further configuration for analytics) true CAPSULE8_USE_ANALYTICS=false
CAPSULE8_FLIGHT_RECORDER_ENABLED investigations.flight_recorder.enabled boolean activate the embedded flight recorder (and enable investigations) false CAPSULE8_FLIGHT_RECORDER_ENABLED=true
N/A investigations.flight_recorder.tables list the tables and configurations to use when flushing data “” (see example config below)
N/A investigations.sinks list the sinks to use when flushing data “” (see example config below)
N/A investigations.reporting_interval string the time duration that describes the flusher’s intervals between reports “” investigations.reporting_interval: “30s”
CAPSULE8_FLUSHER_SERVER_MAX_PAYLOAD_SIZE investigations.max_payload_size int maximum number of bytes for a single flushed payload 4194304 CAPSULE8_FLUSHER_SERVER_MAX_PAYLOAD_SIZE=true
CAPSULE8_FLUSHER_SERVER_TIMEOUT investigations.timeout string the time duration string that sets the flusher’s timeour 5s CAPSULE8_FLUSHER_SERVER_TIMEOUT=“2h45m”
CAPSULE8_TRIGGER_INTERVAL trigger_interval time.Duration set the event trigger interval 10s CAPSULE8_TRIGGER_INTERVAL=1s
CAPSULE8_TRIGGER_SYSCALL trigger_syscall enum string set the event trigger syscall “setxattr” CAPSULE8_TRIGGER_SYSCALL=setxattr
CAPSULE8_RUN_PREFLIGHT_CHECK run_preflight_check boolean Run the sensor preflight check true CAPSULE8_RUN_PREFLIGHT_CHECK=false
CAPSULE8_EVENT_REORDER_WINDOW event_reorder_window time.Duration set the delay over which events will be reordered 75ms CAPSULE8_EVENT_REORDER_WINDOW=0ms
CAPSULE8_INOTIFY_REQUEST_QUEUE_SIZE inotify_request_queue_size int specify the queue size to use for attaching inotify watchers and checking for lost writes 1024 CAPSULE8_INOTIFY_REQUEST_QUEUE_SIZE=0
CAPSULE8_RUNTIME_DIR runtime_dir string location for runtime use /var/run/capsule8 CAPSULE8_RUNTIME_DIR=/var/run/capsule8
CAPSULE8_SUPPORT_DIR support_dir string location for support files /var/lib/capsule8 CAPSULE8_SUPPORT_DIR=/var/lib/capsule8
CAPSULE8_SENSOR_DOCKER_DATA_ROOT docker_data_root string Docker’s configured data root path /var/lib/docker CAPSULE8_SENSOR_DOCKER_DATA_ROOT=/var/lib/docker
CAPSULE8_SENSOR_USE_TLS use_tls boolean Set to use TLS for the gRPC telemetry service false CAPSULE8_SENSOR_USE_TLS=true
CAPSULE8_SENSOR_TLSCACERT_PATH tlscacert_path string location of CA certs for the gRPC telemetry service /var/lib/capsule8/ca.crt CAPSULE8_SENSOR_TLSCACERT_PATH=/var/lib/capsule8/ca.crt
CAPSULE8_SENSOR_TLSSERVER_CERT_PATH tlsserver_cert_path string location of the server cert to use for the gRPC telemetry service /var/lib/capsule8/server.crt CAPSULE8_SENSOR_TLSSERVER_CERT_PATH=/var/lib/capsule8/server.crt
CAPSULE8_SENSOR_TLSSERVER_KEY_PATH tlsserver_kery_path string location of the server private key to use for the gRPC telemetry service /var/lib/capsule8/server.key CAPSULE8_SENSOR_TLSSERVER_KEY_PATH=/var/lib/capsule8/server.key

Example /etc/capsule8/capsule8-sensor.yaml file

Below is an example config file containing all of the config options.

# port
monitor_port: 9010
# number of times to connect to nats on boot
initial_reconnect_attempts: 3

listen_addr: "unix://var/run/capsule8/sensor.sock"

  # arbitrary metadata as a string of key value pairs separated by an equal
      - "region=US-EAST-1"
      - "az=US-EAST-1A"

  url: nats://capsule8-console:4222
  client_cert_file: /etc/capsule8/client.crt
  client_cert_key_file: /etc/capsule8/client.key
  client_ca_cert: /etc/capsule8/nats_ca.crt
  # number of seconds to wait between reconnection attempts
  reconnect_wait: 5
  # number of reconnection attempts to try
  max_reconnects: 120
  # amount of telemetry data to buffer before droping events when disconnected
  # from the console in megabytes
  reconnect_buf_size_in_mb: 10

  # number of telemetry events to bundle together into a single message that is
  # sent to the console
  events_per_message: 250
  # largest amount of latency
  flush_timeout: 100ms

  # log spans to a jaeger instance (note we expect the agent to be configured locally)
  tracer_type: jaeger
  # log tracer information to standard out
  tracer_log: false

debug: false

# embedded analytics package (must be coordinated with console)
use_analytics: true

# investigations are enabled by the flight recorder's enabled variable
  reporting_interval: 10s
    # sink names are the bucket name or directory path for the data to be flushed
    # (eg. metaevents flushes to s3://metaevents)
    - name: metaevents
      # valid backends are aws, gcp and local
      # credentials for the backend must be configured for access to any cloud
      backend: aws
      automated: true
      # parquet is the default file data type
      type: parquet
  # embedded flight recorder
    enabled: true
      - name: "shell_commands"
        rows: 50
        enabled: true
      - name: "tty_data"
        rows: 100
        enabled: true
      - name: "file_events"
        rows: 500
        enabled: false
      - name: "connections"
        rows: 100
        enabled: true
      - name: "sensor_metadata"
        rows: 60
        enabled: true
      - name: "alerts"
        rows: 50
        enabled: true
      - name: "sensors"
        rows: 10
        enabled: true
      - name: "process_events"
        rows: 600
        enabled: true
      - name: "container_events"
        rows: 50
        enabled: true

# optionally change alert timestamp format
alert_timestamp_format: RFC3339

Pairing with the Capsule8 Server

Note: the following section is out of date

The sensor configuration should include a list of API servers used by the Capsule8 server so the two components can be paired. For test installations where the sensor is running on the same host as the API server, a sensor configuration deployment is not required.

Ask your Capsule8 representative for your sensor configuration file. Then, install the capsule8-sensor.yaml file to /etc/capsule8 to finish installation. An example configuration is as follows:

  #url of the capsule8-server with nats prefix, note: can use tls:// to use
  #tls and validate the server.
  url: nats://localhost:4222
  #client_cert_file: /etc/capsule8/client.crt
  #client_cert_key_file: /etc/capsule8/client.key
  #ca_cert: /etc/capsule8/ca.crt