Skip to content

Latest commit

 

History

History
1465 lines (819 loc) · 57.4 KB

API.md

File metadata and controls

1465 lines (819 loc) · 57.4 KB

Protocol Documentation

Top

capsule8/api/v0/types.proto

Process credentials (uid, gid, etc.)

Field Type Label Description
uid uint32 The real user ID
gid uint32 The real group ID
euid uint32 The effective user ID
egid uint32 The effective group ID
suid uint32 The saved user ID
sgid uint32 The saved group ID
fsuid uint32 The user ID for filesystem operations
fsgid uint32 The group ID for filesystem operations

An IPv4 address

Field Type Label Description
address fixed32 The IPv4 address is network byte order (big endian)

An IPv4 address and port

Field Type Label Description
address IPv4Address The IPv4 address
port uint32 The port

An IPv6 address

Field Type Label Description
high fixed64 The high-order bytes of the IPv6 address
low fixed64 The low-order bytes of the IPv6 address

An IPv6 address and port

Field Type Label Description
address IPv6Address The IPv6 address
port uint32 The port

A network address

Field Type Label Description
family NetworkAddressFamily The address family that specifies which address format is in use
ipv4_address IPv4AddressAndPort Used when family is NETWORK_ADDRESS_INET
ipv6_address IPv6AddressAndPort Used when family is NETWORK_ADDRESS_INET6
local_address string Used when family is NETWORK_ADDRESS_LOCAL

Supported network address families

Name Number Description
NETWORK_ADDRESS_FAMILY_UNKNOWN 0 The network address family is unknown
NETWORK_ADDRESS_FAMILY_INET 1 AF_INET; IPv4 address formats
NETWORK_ADDRESS_FAMILY_INET6 2 AF_INET6; IPv6 address formats
NETWORK_ADDRESS_FAMILY_LOCAL 3 AF_LOCAL / AF_UNIX; local filesystem address formats

Top

capsule8/api/v0/telemetry_event.proto

Field Type Label Description
index uint64 Index of the first character in this Event in relation to all of the characters that have been generated in this stream.
characters string The next one or more characters in the autogenerated stream

ContainerEvent describes a Docker container or Rkt App lifecycle event

Field Type Label Description
type ContainerEventType
name string
image_id string Unique identifier of the container image
image_name string Name of the container image (i.e. "busybox" or "gcr.io/google_containers/nginx-ingress-controller")
host_pid sint32 Host process identifier of the container's init process.
exit_code sint32 Optional, only included on CONTAINER_EVENT_TYPE_EXIT events
exit_status uint32 The exit status will typically one of the values defined in stdlib.h like EXIT_SUCCESS, EXIT_FAILURE, or EXIT_USAGE.
exit_signal uint32 If non-zero, this is the signal number that the process was terminated with.
exit_core_dumped bool If true, indicates that the process dumped a core when it terminated.
docker_config_json string Docker container configuration file
oci_config_json string OCI container configuration file

FileEvent describes an event that occurred related to file operations occurring as detected by the Sensor.

Field Type Label Description
type FileEventType The type of event described by this FileEvent message
filename string Present when the event is a file create, delete, link, modify, or open event. This is the filename of the file being affected.
open_flags sint32 Present when the event is a file open event. This is the set of flags with which the file was opened (e.g., O_RDONLY, O_NONBLOCK, etc.).
open_mode sint32 Present when the event is a file create or open event. This is the set of file permissions used in a creat(2) system call.
source_file string Present when the event is a file link event. This is the name of the file being linked to.
target_file string Present when the event is a file link event. This is the name of the file linking to source the source file.
symlink bool Present when the event is a file link event. This is true if the link is a symlink; otherwise, it is a hard link.
oldname string Present when the event is a file rename event. This is the original name of the file being renamed.
newname string Present when the event is a file rename event. This is the new name of the file being renamed.

KernelFunctionCallEvent describes an event that occurred related to kernel functions being entered or exited.

Field Type Label Description
arguments KernelFunctionCallEvent.ArgumentsEntry repeated This is a map of argument names and values. The keys are strings that are the names of the arguments, and the values are the actual values for each field.
Field Type Label Description
key string
value KernelFunctionCallEvent.FieldValue

The representation of a field value, which is composed of type information and the value itself.

Field Type Label Description
field_type KernelFunctionCallEvent.FieldType The type represented by this field value.
bytes_value bytes An array of bytes
string_value string A string
signed_value sint64 A signed value (8-bit, 16-bit, 32-bit, or 64-bit)
unsigned_value uint64 An unsigned value (8-bit, 16--bit, 32-bit, or 64-bit)
Field Type Label Description
lost uint64 Number of lost records observed
type LostRecordEventType Type of events lost

NetworkEvent describes an event that occurred related to network activity occurring as detected by the Sensor.

Field Type Label Description
type NetworkEventType The type of event described by this NetworkEvent message.
sockfd uint64 Present when the event describes a network event that is an attempt to perform a network related action. This is the socket descriptor used to perform the action.
address NetworkAddress Present when the event describes a network event that is an attempt to perform a network related action that includes an address. This is that address.
result sint64 Present when the event describes a network event that is the result of an attempted network related action. This is the return code from the system call.
backlog uint64 Present only when the event describes a listen attempt. This is the value of the backlog argument passed to listen(2).

PerformanceEvent describes an event that occurred related to performance event activity in the Sensor.

Field Type Label Description
total_time_enabled uint64 The total amount of time that the event has been enabled in the sensor. This corresponds to PERF_FORMAT_TOTAL_TIME_ENABLED that is reported by the kernel with the event sample.
total_time_running uint64 The total amount of time that the event subscription has been running in the sensor. This corresponds to PERF_FORMAT_TOTAL_TIME_RUNNING that is reported by the kernel with the event sample.
values PerformanceEventValue repeated These are the counter values reported by the kernel with the event sample.

PerformanceEventValue is a single performance event counter. It contains the perf config value and its associated counter value.

Field Type Label Description
type PerformanceEventType The type of performance event counter.
config uint64 The config value used in the registration of the event group.
value uint64 The current value of the counter associated with the type and config value pair.
Field Type Label Description
pid sint32
command string

ProcessEvent describes an event that occurred related to processes starting and exiting as detected by the Sensor.

Field Type Label Description
type ProcessEventType The type of event described by this ProcessEvent message
fork_child_pid sint32 Present when the event is a fork event. This is the PID of the new child process.
fork_child_id string Present when the event is a fork event. This is the Sensor's process ID of the new child process.
fork_clone_flags uint64 Present when the event is a fork event. This is the flags parameter passed to sys_clone.
fork_stack_start uint64 Present when the event is a fork event. This is the stack_start parameter passed to sys_clone.
exec_filename string Present when the event is an exec event. This is the filename of the executable that was executed.
exec_command_line string repeated Present when the event is an exec event. Repeated for each argument passed to the executable on the command-line.
exit_code sint32 Present when the event is an exit event. This is the exit code that the process exited with.
exit_status uint32 Present when the event is an exit event. This will typically be one9 of the values defined in stdlib.h like EXIT_SUCCESS, EXIT_FAILURE, or EXIT_USAGE.
exit_signal uint32 Present when the event is an exit event. If non-zero, this is the signal number that the process was terminated with.
exit_core_dumped bool Present when the event is an exit event. If true, indicates that the process dumped a core when it terminated.
update_cwd string Present when the event is an update event that informs of an update to the process's current working directory.

SyscallEvent describes an event that occurred related to system calls being made or returning as detected by the Sensor.

Field Type Label Description
type SyscallEventType The type of event described by this SyscallEvent message
id int64 The syscall number for either enter or exit events.
arg0 uint64 Present when the event is an enter event. This is the first argument passed to the system call.
arg1 uint64 Present when the event is an enter event. This is the second argument passed to the system call.
arg2 uint64 Present when the event is an enter event. This is the third argument passed to the system call.
arg3 uint64 Present when the event is an enter event. This is the fourth argument passed to the system call.
arg4 uint64 Present when the event is an enter event. This is the fifth argument passed to the system call.
arg5 uint64 Present when the event is an enter event. This is the sixth argument passed to the system call.
ret int64 Present when the event is an exit event. This is the value that was returned from the system call.

An event observed by the Sensor.

Field Type Label Description
id string Unique identifier for the event
process_id string Unique process identifier associated with the event to differentiate reused values of the pid below.
process_pid int32 Kernel's PID of the task associated with the event. This corresponds the userland's TID.
container_id string Container identifier associated with the event
sensor_id string Sensor identifier of the sensor instance that observed the event
sensor_sequence_number uint64 Sequence number from some unspecified starting point unique to the Sensor. Provides a strict linear ordering of events with the same sensor_id where no two events can have the same sequence number. If it is present, it must be greater than zero. A zero value indicates that there is no sequence number associated with the event.
sensor_monotime_nanos int64 Monotonic nanosecond timestamp from some unspecified starting point unique to the Sensor. Can only be used to calculate time intervals between events with the same sensor_id.
process_lineage Process repeated Process Lineage contains one process context for each process in the hierarchy, starting with the current process, up to the root of the process namespace.
container_name string Name of container associated with the event
image_id string Unique identifier of the container image
image_name string Name of the container image (i.e. "busybox" or "gcr.io/google_containers/nginx-ingress-controller")
syscall SyscallEvent
process ProcessEvent
file FileEvent
kernel_call KernelFunctionCallEvent
network NetworkEvent
performance PerformanceEvent
user_call UserFunctionCallEvent
container ContainerEvent
chargen ChargenEvent Debugging events (>= 100)
ticker TickerEvent
lost LostRecordEvent
cpu int32 CPU on which the event occurred
credentials Credentials Credentials for the process associated with the event
process_tgid int32 Kernel's TGID of the task associated with the event. This corresponds the userland's PID.
Field Type Label Description
seconds int64 The number of seconds elapsed since January 1, 1970 UTC.

https://golang.org/pkg/time/#Time.Unix | | nanoseconds | int64 | | The number of nanoseconds elapsed since January 1, 1970 UTC

https://golang.org/pkg/time/#Time.UnixNano |

UserFunctionCallEvent describes an event that occurred related to user functions being entered or exited.

Field Type Label Description
arguments UserFunctionCallEvent.ArgumentsEntry repeated This is a map of argument names and values. The keys are strings that are the names of the arguments, and the values are the actual values for each field.
Field Type Label Description
key string
value UserFunctionCallEvent.FieldValue

The representation of a field value, which is composed of type information and the value itself.

Field Type Label Description
field_type UserFunctionCallEvent.FieldType The type represented by this field value.
bytes_value bytes An array of bytes
string_value string A string
signed_value sint64 A signed value (8-bit, 16-bit, 32-bit, or 64-bit)
unsigned_value uint64 An unsigned value (8-bit, 16--bit, 32-bit, or 64-bit)
Name Number Description
CONTAINER_EVENT_TYPE_UNKNOWN 0
CONTAINER_EVENT_TYPE_CREATED 1
CONTAINER_EVENT_TYPE_RUNNING 2
CONTAINER_EVENT_TYPE_EXITED 3
CONTAINER_EVENT_TYPE_DESTROYED 4
CONTAINER_EVENT_TYPE_UPDATED 5

Possible FileEvent types

Name Number Description
FILE_EVENT_TYPE_UNKNOWN 0 The type of event is unknown
FILE_EVENT_TYPE_OPEN 1 The event is a file open event
FILE_EVENT_TYPE_CREATE 2 The event is a file create event
FILE_EVENT_TYPE_DELETE 3 The event is a file delete event
FILE_EVENT_TYPE_LINK 4 The event is a file link event
FILE_EVENT_TYPE_OPEN_FOR_MODIFY 5 The event is a file open for modify event
FILE_EVENT_TYPE_RENAME 6 The event is a file rename event
FILE_EVENT_TYPE_MODIFY 7 The event is a file modify event
FILE_EVENT_TYPE_CLOSE_FOR_MODIFY 8 The event is a file close for modify event
FILE_EVENT_TYPE_ATTRIBUTE_CHANGE 9 The event is a attribute change event

Possible field types

Name Number Description
UNKNOWN 0 The field type is unknown
BYTES 1 The field type is an array of bytes
STRING 2 The field type is a string
SINT8 3 The field type is a signed 8-bit integer
SINT16 4 The field type is a signed 16-bit integer
SINT32 5 The field type is a signed 32-bit integer
SINT64 6 The field type is a signed 64-bit integer
UINT8 7 The field type is an unsigned 8-bit integer
UINT16 8 The field type is an unsigned 16-bit integer
UINT32 9 The field type is an unsigned 32-bit integer
UINT64 10 The field type is an unsigned 64-bit integer

Possible KernelFunctionCallEvent types

Name Number Description
KERNEL_FUNCTION_CALL_EVENT_TYPE_UNKNOWN 0 The type of event is unknown
KERNEL_FUNCTION_CALL_EVENT_TYPE_ENTER 1 The event is a kernel function being entered.
KERNEL_FUNCTION_CALL_EVENT_TYPE_EXIT 2 The event is a kernel function being exited.
Name Number Description
LOST_RECORD_EVENT_TYPE_UNKNOWN 0 LOST_RECORD_EVENT_TYPE_UNKNOWN is a lost record of unknown type.
LOST_RECORD_EVENT_TYPE_SUBSCRIPTION 1 LOST_RECORD_EVENT_TYPE_SUBSCRIPTION is a lost record from a subscription. It may include kprobes, uprobes, network events, syscalls, etc. but it does not include meta events like process, container, or file monitoring events. This type is only ever sent to a specific subscription that has lost a kernel generated event.
LOST_RECORD_EVENT_TYPE_PROCESS 2 LOST_RECORD_EVENT_TYPE_PROCESS is a lost record relating to process meta events. This type is broadcast to all subscriptions, regardless of whether they've explicitly subscribed to process events or not, because it affects everything.
LOST_RECORD_EVENT_TYPE_CONTAINER 3 LOST_RECORD_EVENT_TYPE_CONTAINER is a lost record relating to container meta events. This type is broadcast to all subscriptions, regardless of whether they've explicitly subscribed to process events or not, because it affects everything.
LOST_RECORD_EVENT_TYPE_FILE_CREATE 4 LOST_RECORD_EVENT_TYPE_FILE_CREATE is a lost record relating to file create events. It is only sent to subscriptions that are subscribed to file create events.
LOST_RECORD_EVENT_TYPE_FILE_DELETE 5 LOST_RECORD_EVENT_TYPE_FILE_DELETE is a lost record relating to file delete events. It is only sent to subscriptions that are subscribed to file delete events.
LOST_RECORD_EVENT_TYPE_FILE_LINK 6 LOST_RECORD_EVENT_TYPE_FILE_LINK is a lost record relating to file link events. It is only sent to subscriptions that are subscribed to file link events.
LOST_RECORD_EVENT_TYPE_FILE_SYMLINK 7 LOST_RECORD_EVENT_TYPE_FILE_SYMLINK is a lost record relating to file symlink events. It is only sent to subscriptions that are subscribed to file link events.
LOST_RECORD_EVENT_TYPE_FILE_OPEN_MODIFY 8 LOST_RECORD_EVENT_TYPE_FILE_OPEN_MODIFY is a lost record relating to file open modify events. It is only sent to subscriptions that are subscribed to file open modify events.
LOST_RECORD_EVENT_TYPE_FILE_CLOSE_MODIFY 9 LOST_RECORD_EVENT_TYPE_FILE_CLOSE_MODIY is a lost record relating to file close modify events. It is only sent to subscriptions that are subscribed to file close modify events.
LOST_RECORD_EVENT_TYPE_FILE_MODIFY 10 LOST_RECORD_EVENT_TYPE_FILE_MODIFY is a lost record relating to file modify events. It is only sent to subscriptions that are subscribed to file modify events.
LOST_RECORD_EVENT_TYPE_FILE_RENAME 11 LOST_RECORD_EVENT_TYPE_FILE_RENAME is a lost record relating to file rename events. It is only sent to subscriptions that are subscribed to file rename events.
LOST_RECORD_EVENT_TYPE_FILE_ATTRIBUTE_CHANGE 12 LOST_RECORD_EVENT_TYPE_FILE_ATTRIBUTE_CHANGE is a lost record relating to file attribute change events. It is only sent to subscriptions that are subscribed to file attribute change events.

Possible network event types

Name Number Description
NETWORK_EVENT_TYPE_UNKNOWN 0 The type of event is unknown
NETWORK_EVENT_TYPE_CONNECT_ATTEMPT 1 The event is an attempt to connect to an address
NETWORK_EVENT_TYPE_CONNECT_RESULT 2 The event is the result of an attempt to connect to an address
NETWORK_EVENT_TYPE_BIND_ATTEMPT 3 The event is an attempt to bind to a local address
NETWORK_EVENT_TYPE_BIND_RESULT 4 The event is the result of an attempt to bind to a local address
NETWORK_EVENT_TYPE_LISTEN_ATTEMPT 5 The event is an attempt to listen for connections
NETWORK_EVENT_TYPE_LISTEN_RESULT 6 The event is the result of an attempt to listen for connections
NETWORK_EVENT_TYPE_ACCEPT_ATTEMPT 7 The event is an attempt to accept an incoming connection
NETWORK_EVENT_TYPE_ACCEPT_RESULT 8 The event is the result of an attempt to accept an incoming connection
NETWORK_EVENT_TYPE_SENDTO_ATTEMPT 9 The event is an attempt to send data to a specific address
NETWORK_EVENT_TYPE_SENDTO_RESULT 10 The event is the result of an attempt to send data to a specific address
NETWORK_EVENT_TYPE_RECVFROM_ATTEMPT 11 The event is an attempt to receive data from a specific address
NETWORK_EVENT_TYPE_RECVFROM_RESULT 12 The event is the result of an attempt to receive data from a specific address

Possible performance event types

Name Number Description
PERFORMANCE_EVENT_TYPE_UNKNOWN 0 The type of event is unknown
PERFORMANCE_EVENT_TYPE_HARDWARE 1 The event is a hardware based event (PERF_TYPE_HARDWARE)
PERFORMANCE_EVENT_TYPE_HARDWARE_CACHE 2 The event is a hardware cache based event (PERF_TYPE_HW_CACHE)
PERFORMANCE_EVENT_TYPE_SOFTWARE 3 The event is a software based event (PERF_TYPE_SOFTWARE)

Possible ProcessEvent types

Name Number Description
PROCESS_EVENT_TYPE_UNKNOWN 0 The type of event is unknown
PROCESS_EVENT_TYPE_FORK 1 The event is a process fork event
PROCESS_EVENT_TYPE_EXEC 2 The event is a process exec event
PROCESS_EVENT_TYPE_EXIT 3 The event is a process exit event
PROCESS_EVENT_TYPE_UPDATE 4 The event is a process update event

Possible SyscallEvent types

Name Number Description
SYSCALL_EVENT_TYPE_UNKNOWN 0 The type of event is unknown
SYSCALL_EVENT_TYPE_ENTER 1 The event is a syscall enter event
SYSCALL_EVENT_TYPE_EXIT 2 The event is a syscall exit event

Possible field types

Name Number Description
UNKNOWN 0 The field type is unknown
BYTES 1 The field type is an array of bytes
STRING 2 The field type is a string
SINT8 3 The field type is a signed 8-bit integer
SINT16 4 The field type is a signed 16-bit integer
SINT32 5 The field type is a signed 32-bit integer
SINT64 6 The field type is a signed 64-bit integer
UINT8 7 The field type is an unsigned 8-bit integer
UINT16 8 The field type is an unsigned 16-bit integer
UINT32 9 The field type is an unsigned 32-bit integer
UINT64 10 The field type is an unsigned 64-bit integer

Possible UserFunctionCallEvent types

Name Number Description
USER_FUNCTION_CALL_EVENT_TYPE_UNKNOWN 0 The type of event is unknown
USER_FUNCTION_CALL_EVENT_TYPE_ENTER 1 The event is a user function being entered.
USER_FUNCTION_CALL_EVENT_TYPE_EXIT 2 The event is a user function being exited.

Top

capsule8/api/v0/telemetry_service.proto

A request message to initiate the streaming of telemetry events

Field Type Label Description
subscription Subscription The Subscription message defines which events should be returned in the stream.

A response message containing telemetry events

Field Type Label Description
events ReceivedTelemetryEvent repeated Can publish one or more message(s) at a time
statuses google.rpc.Status repeated Can publish one or more status(es) at a time

A telemetry event received from a Sensor or Recorder.

Field Type Label Description
publish_time_micros int64 The time that the event was received by the backplane (in micros since Unix epoch)
event TelemetryEvent The actual event observed by the Sensor. For historical event subscriptions, this event may be sent from the Recorder.
ack bytes An opaque ack for the event. If present, this ack must be sent to the PubsubService's Acknowledge method or else the TelemetryService will re-transmit the event.
Method Name Request Type Response Type Description
GetEvents GetEventsRequest GetEventsResponse Opens a new stream of telemetry events

Top

capsule8/api/v0/subscription.proto

The ChargenEventFilter configures a character stream generator and includes events from it in the Subscription.

Field Type Label Description
length uint64 Required; the length of character sequence strings to generate

The ContainerEventFilter specifies which container lifecycle events to include in the Subscription. In order to restrict them to specific containers, use the ContainerFilter.

Field Type Label Description
type ContainerEventType Required, specify the particular type of event type to match
view ContainerEventView Optional, specifies how much detail to include in container events
filter_expression Expression Optional; a filter to apply to events. Only events for which the evaluation of the filter expression is true will be returned.

The ContainerFilter restricts events in the Subscription to the running containers indicated. All of the fields in this message are effectively "ORed" together to create the list of containers to monitor for the subscription.

Field Type Label Description
ids string repeated Zero or more container IDs (e.g. 254dd98a7bf1581560ddace9f98b7933bfb3c2f5fc0504ec1b8dcc9614bc7062)
names string repeated Zero or more container names (e.g. /ecstatic_darwin)
image_ids string repeated Zero or more container image IDs (e.g. d462265d362c919b7dd37f8ba80caa822d13704695f47c8fc42a1c2266ecd164)
image_names string repeated Container image name (shell-style globs are supported). May be of the form "busybox", "foo/bar" or "sha256:d462265d362c919b7dd37f8ba80caa822d13704695f47c8fc42a1c2266ecd164"

The EventFilter specifies events to include. All of the specified fields are effectively "ORed" together to create the list of events included in the Subscription.

Kernel-level events

Field Type Label Description
syscall_events SyscallEventFilter repeated Zero or more filters specifying which system calls to include
process_events ProcessEventFilter repeated Zero or more filters specifying which process events to include
file_events FileEventFilter repeated Zero or more filters specifying which file events to include
kernel_events KernelFunctionCallFilter repeated Zero or more kernel function calls to include
network_events NetworkEventFilter repeated Zero or more network events to include
performance_events PerformanceEventFilter repeated Zero or more performance events to include
user_events UserFunctionCallFilter repeated Zero or more user function calls to include
container_events ContainerEventFilter repeated Zero or more container events to include
chargen_events ChargenEventFilter repeated Zero or more character generators to configure and return events from (for debugging)
ticker_events TickerEventFilter repeated Zero or more ticker generators to configure and return events from (for debugging)

The FileEventFilter specifies which file events to include in the Subscription. The specified fields are effectively "ANDed" to specify a matching event.

Field Type Label Description
type FileEventType Required; the file event type to match
filter_expression Expression
filename google.protobuf.StringValue Optional; require exact match on the filename being acted upon
filename_pattern google.protobuf.StringValue Optional; require pattern match on the filename being acted upon
open_flags_mask google.protobuf.Int32Value Optional; for file open events, require a match of the bits set for the open(2) flags argument
create_mode_mask google.protobuf.Int32Value Optional; for file open events, require a match of the bits set for the open(2) or creat(2) mode argument

The KernelFunctionCallFilter specifies which kernel function call events to include in the Subscription. The arguments map defines values that will be fetched at each call and returned along with the event. In order to minimize event volume, a filter may be included that filters the kernel function calls based on the observed values of the specified arguments at the time of the kernel function call.

Field Type Label Description
type KernelFunctionCallEventType Required; the kernel function call event type to match
symbol string Required; the kernel symbol to match on
arguments KernelFunctionCallFilter.ArgumentsEntry repeated Optional; the field names and data to be returned by the kernel when the event triggers. Note that this is a map. The keys are the names to assign to the returned fields, and the values are a string describing the data to return, usually an expression involving the register containing the desired data and a suffix indicating the type of the data (e.g., "s32", "string", "u64", etc.). This map is used to construct the "fetchargs" passed to the kernel when creating the kernel probe.
filter_expression Expression Optional; a filter to apply to kernel probe.
Field Type Label Description
key string
value string

The LimitModifier cancels the subscription on each Sensor after the specified number of events. The entire Subscription may return more events than this depending on how many active Sensors there are.

Field Type Label Description
limit int64 Limit the number of events

Modifier specifies which stream modifiers to apply if any. For a given stream, a modifier can apply a throttle or limit etc. Modifiers can be used together.

Field Type Label Description
throttle ThrottleModifier
limit LimitModifier

The NetworkEventFilter specifies which network events to include in the Subscription. The included filter can be used to specify precisely which network events should be included.

Field Type Label Description
type NetworkEventType Required; the network event type to match
filter_expression Expression Optional; a filter to apply to events. Only events for which the evaluation of the filter expression is true will be returned.

PerformanceEventCounter represents a single performance event counter group member, where each member may have a different type and configuration.

Field Type Label Description
type PerformanceEventType Required; the performance event type.
config uint64 Required; the performance event type's configuration, which is defined by the Linux perf interface. This corresponds to the config field in a struct perf_event_attr that is documented in the perf_event_open(2) man page.

The PerformanceEventFilter specifies which performance events to include in the Subscription.

Field Type Label Description
events PerformanceEventCounter repeated Required; the performance events to monitor for. The sensor will create a new group with the order of the events preserved.
sample_rate_type SampleRateType Required; the sample rate type to use, which may be either period or frequency as described for SampleRateType.
period uint64 If sample_rate_type is SAMPLE_RATE_TYPE_PERIOD, this is the value for the sample rate period to use.
frequency uint64 If sample_rate_type is SAMPLE_RATE_TYPE_FREQUENCY, this is the value for the sample rate frequency to use.

The ProcessEventFilter specifies which process events to include in the Subscription. The specified fields are effectively "ANDed" to specify a matching event.

Field Type Label Description
type ProcessEventType Required; the process event type to match
filter_expression Expression
exec_filename google.protobuf.StringValue Optional; require exact match on the filename passed to execve(2)
exec_filename_pattern google.protobuf.StringValue Optional; require pattern match on the filename passed to execve(2)
exit_code google.protobuf.Int32Value Optional; require exact match on exit code

The Subscription message identifies a subscriber's interest in telemetry events.

Field Type Label Description
event_filter EventFilter Return events matching one or more of the specified event filters. If no event filters are specified, then no events will be returned.
container_filter ContainerFilter If not empty, then only return events from containers matched by one or more of the specified container filters.
since_duration google.protobuf.Int64Value If not empty, then only return events that occurred after the specified relative duration subtracted from the current time (recorder time). If the resulting time is in the past, then the subscription will search for historic events before streaming live ones. Sensors do not honor this field.
for_duration google.protobuf.Int64Value If not empty, then only return events that occurred before the specified relative duration added to since_duration. If since_duration is not supplied, return events from now and until the specified relative duration is hit. Sensors do not honor this field.
modifier Modifier If not empty, apply the specified modifier to the subscription.

The SyscallEventFilter specifies which system call events to include in the Subscription. The specified fields are effectively "ANDed" to specify a matching event.

Field Type Label Description
type SyscallEventType Required; type of system call event (entry or exit)
filter_expression Expression
id google.protobuf.Int64Value Required; system call number from arch/x86/entry/syscalls/syscall_64.tbl
arg0 google.protobuf.UInt64Value Optional; precise value of a particular system call argument
arg1 google.protobuf.UInt64Value
arg2 google.protobuf.UInt64Value
arg3 google.protobuf.UInt64Value
arg4 google.protobuf.UInt64Value
arg5 google.protobuf.UInt64Value
ret google.protobuf.Int64Value Optional; return value of the system call (if type indicates exit).

The ThrottleModifier modulates events sent by the Sensor to one per time interval specified.

Field Type Label Description
interval int64 Required; the interval to use
interval_type ThrottleModifier.IntervalType Required; the interval type (milliseconds, seconds, etc.)

The TickerEventFilter configures a ticker stream generator and includes events from it in the Subscription.

Field Type Label Description
interval int64 Required; the interval at which ticker events are generated

The UserFunctionCallFilter specifies which user mode function call events to include in the Subscription. User mode function call events are functions in running user mode binaries that must be specified with both the executable name and symbol to monitor. They otherwise work the same as kernel function call events. The arguments map defines values that will be fetched at each call and returned along with the event. In order to minimize event volume, a filter may be included that filters the user function calls based on the observed values of the specified arguments at the time of the user function call.

Field Type Label Description
type UserFunctionCallEventType Required; the user function call event type to match
executable string Required; the executable binary in which calls are to be hooked.
symbol string Required; the executable symbol to match on
arguments UserFunctionCallFilter.ArgumentsEntry repeated Option; the field names and data to be returned by the kernel when the event triggers. Note that this is a map. The keys are the names to assign to the returned fields, and the values are a string describing the data to return, usually an expression involving the register containing the desired data and a suffix indicating the type of the data (e.g., "s32", "string", "u64", etc.). This map is used to construct the "fetchargs" passed to the kernel when creating the user probe.
filter_expression Expression Optional; a filter to apply to the user probe.
Field Type Label Description
key string
value string

The ContainerEventView specifies the level of detail to include for ContainerEvents.

Name Number Description
BASIC 0 Default view of a ContainerEvent includes just basic information
FULL 1 Full view of a ContainerEvent includes raw Docker and OCI config JSON payloads

SampleRateType describes the type of sample rate to use, either by the # of generated events (SAMPLE_RATE_TYPE_PERIOD) or by time (SAMPLE_RATE_TYPE_FREQUENCY), which is expressed in units of kernel timer ticks.

Name Number Description
SAMPLE_RATE_TYPE_UNKNOWN 0
SAMPLE_RATE_TYPE_PERIOD 1
SAMPLE_RATE_TYPE_FREQUENCY 2

Possible interval types

Name Number Description
MILLISECOND 0 milliseconds
SECOND 1 seconds
MINUTE 2 minutes
HOUR 3 hours

Top

capsule8/api/v0/expression.proto

Field Type Label Description
lhs Expression
rhs Expression
Field Type Label Description
type Expression.ExpressionType
identifier string
value Value
binary_op BinaryOp
unary_op Expression
Field Type Label Description
type ValueType
signed_value sint64
unsigned_value uint64
string_value string
bool_value bool
double_value double
timestamp_value google.protobuf.Timestamp
Name Number Description
EXPRESSIONTYPE_UNSPECIFIED 0
IDENTIFIER 1
VALUE 2
LOGICAL_AND 10
LOGICAL_OR 11
EQ 20
NE 21
LT 22
LE 23
GT 24
GE 25
LIKE 26
IS_NULL 27 unary comparison
IS_NOT_NULL 28 unary comparison
BITWISE_AND 30
Name Number Description
VALUETYPE_UNSPECIFIED 0
STRING 1
SINT8 2
SINT16 3
SINT32 4
SINT64 5
UINT8 6
UINT16 7
UINT32 8
UINT64 9
BOOL 10
DOUBLE 11
TIMESTAMP 12

Scalar Value Types

.proto Type Notes C++ Type Java Type Python Type
double double double float
float float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long
uint32 Uses variable-length encoding. uint32 int int/long
uint64 Uses variable-length encoding. uint64 long int/long
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long
sfixed32 Always four bytes. int32 int int
sfixed64 Always eight bytes. int64 long int/long
bool bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode
bytes May contain any arbitrary sequence of bytes. string ByteString str