Capsule8 Docs
Capsule8 Docs
Help

Alert Schema

This section documents the Alert schema for use with Alert Templates.

The types defined in the Type column are either native Go types or are custom types that Capsule8 defined. This document uses lowercase names for native Go types and capitalized names for custom Capsule8 types. Every custom Capsule8 type defined below has its own section. The Usage Example column provides a template example that can be copy and pasted into your template for certain use cases. In the case of nested fields, the names of the parent fields required for access are included (e.g. {{.ProcessInfo.Program}}). In the case of slices, data is accessible through either the range action or the index function (e.g. {{range .Lineage}} {{.Program.Path}} {{end}}). Keep in mind that the provided usage examples are not the only way to use the Alert fields in an Alert Template. See the Alert Templates section for complete usage instructions. The Alert schema is not exactly the same between the JSON and Alert Template formats. For that reason it is important to consult this documentation.

Alert

Alert is the top-level Capsule8 Alert type.

Field Type Description Usage Example
GroupID string The Unix group ID. {{.GroupID}}
Timestamp int64 The Unix timestamp of when the Alert was generated. {{.Timestamp}}
Description string The description of the Alert from Strategy. {{.Description}}
Comments string The comments on the Alert from Strategy. {{.Comments}}
UUID string The Universally Unique ID for this Alert. {{.UUID}}
AlertLabels map[string]string The Alert labels from Strategy. {{.AlertLabels}}
Priority Priority The Alert’s priority. {{.Priority}}
Confidence Confidence The confidence that the Alert is not a false positive. {{.Confidence}}
Location AlertLocation The location of where the Alert was generated. {{.Location}}
ProcessInfo ProcessInfo The information about the process that generated the Alert (if available). {{.ProcessInfo}}
Lineage []ProcessInfo The information about both the process and program’s lineage (if enabled). {{.Lineage}}
StrategyName string The name and Capsule8 release version of the Strategy. {{.StrategyName}}
PolicyType Policy The Policy’s type (e.g. Program). {{.PolicyType}}
Scope Scope The scope of the Alert’s process. {{.Scope}}
Notifications []AlertNotification The notifications associated with the Alert and its response actions. {{.Notifications}}
MatchedObjects []AlertFilterMatch The objects that were matched that caused the Alert. {{.MatchedObjects}}
MatchedRule string The policy rule that was matched that caused the Alert. {{.MatchedRule}}
Metadata map[string]string The system metadata from the Alert process’ host. {{.Metadata}}
Categories string The Capsule8 and MITRE categories this Alert belongs to. {{.Categories}}
ConsoleURL string The Capsule8 Console URL the Alert is available at (if configured). {{.ConsoleURL}}

AlertLocation

AlertLocation is accessible through the Alert Location field.

Field Type Description Usage Example
NodeName string Node name is the host name of the underlying node. {{.Location.NodeName}}
PodName string Pod name from Kubernetes. {{.Location.PodName}}
K8sNamespace string K8sNamespace is the kubernetes name space for the pod. {{.Location.K8sNamespace}}
ContainerID string Unique Identifier for a running Container Instance. {{.Location.ContainerID}}
ContainerName string Container Name a string name assigned to the container. {{.Location.ContainerName}}
ImageID string Unique Image ID that the container was built from. {{.Location.ImageID}}
ImageName string String name of the Image that the Container was built from. {{.Location.ImageName}}
SensorID string The unique identifier for the sensor that this container is running on. {{.Location.SensorID}}

AlertNotification

AlertNotification is accessible through the Alert Notifications field which is a slice.

Field Type Description Usage Example
Timestamp int64 The timestamp of the notification. {{range .Notifications}} {{.Timestamp}} {{end}}
Name string The name of the notification. {{range .Notifications}} {{.Name}} {{end}}
ActorUUID string The UUID of the notification’s actor. {{range .Notifications}} {{.ActorUUID}} {{end}}
Message string The message associated with the notification. {{range .Notifications}} {{.Message}} {{end}}
MessageFields AlertMessageFields The message fields associated with the notification. {{range .Notifications}} {{.MessageFields}} {{end}}

AlertMessageFields

AlertMessageFields are accessible through the Alert Notification's MessageFields.

Field Type Description Usage Example
ActionType string The type of response action taken e.g. “kill” or “stop”. {{range .Notifications}} {{.MessageFields.ActionType}} {{end}}
ActionTargetType string The type of target a response action is being taken against e.g. “process” or “container”. {{range .Notifications}} {{.MessageFields.ActionTargetType}} {{end}}
ActionResult string The outcome of a given action e.g. “successful” or “unsuccessful”. {{range .Notifications}} {{.MessageFields.ActionResult}} {{end}}
ActionResultDetails string Additional messages about the action’s outcome. {{range .Notifications}} {{.MessageFields.ActionResultDetails}} {{end}}
ConnectionDirection string The inbound/outbound nature of a network event. {{range .Notifications}} {{.MessageFields.ConnectionDirection}} {{end}}
DisabledMechanism string The disabled security mechanism referenced in an alert. {{range .Notifications}} {{.MessageFields.DisabledMechanism}} {{end}}
FilePath string The file path in a relevant event. {{range .Notifications}} {{.MessageFields.FilePath}} {{end}}
FileSHA256Hash string The calculated content hash of the file at FilePath. {{range .Notifications}} {{.MessageFields.FileSHA256Hash}} {{end}}
SourceFilePath string The source file path that was linked or moved into FilePath in a relevant event. {{range .Notifications}} {{.MessageFields.SourceFilePath}} {{end}}
InstanceCount int32 The number of times the relevant event occurred. {{range .Notifications}} {{.MessageFields.InstanceCount}} {{end}}
KernelFunction string The kernel function in a kernel payload event. {{range .Notifications}} {{.MessageFields.KernelFunction}} {{end}}
LocalPort uint16 The local port in a network event. {{range .Notifications}} {{.MessageFields.LocalPort}} {{end}}
ModifiedCredentialFields string The lists cred struct members that changed. {{range .Notifications}} {{.MessageFields.ModifiedCredentialFields}} {{end}}
ModuleName string The kernel module loaded. {{range .Notifications}} {{.MessageFields.ModuleName}} {{end}}
NewPermissionsMask string The octal version of new file permissions. {{range .Notifications}} {{.MessageFields.NewPermissionsMask}} {{end}}
NewPermissionsStrings string The string list of new file permissions. {{range .Notifications}} {{.MessageFields.NewPermissionsStrings}} {{end}}
NewUid int32 The newly assigned uid. {{range .Notifications}} {{.MessageFields.NewUid}} {{end}}
NewEuid int32 The newly assigned euid. {{range .Notifications}} {{.MessageFields.NewEuid}} {{end}}
NewSuid int32 The newly assigned suid. {{range .Notifications}} {{.MessageFields.NewSuid}} {{end}}
NewFsuid int32 The newly assigned fsuid. {{range .Notifications}} {{.MessageFields.NewFsuid}} {{end}}
NewGid int32 The newly assigned gid. {{range .Notifications}} {{.MessageFields.NewGid}} {{end}}
NewEgid int32 The newly assigned egid. {{range .Notifications}} {{.MessageFields.NewEgid}} {{end}}
NewSgid int32 The newly assigned sgid. {{range .Notifications}} {{.MessageFields.NewSgid}} {{end}}
NewFsgid int32 The newly assigned fsgid. {{range .Notifications}} {{.MessageFields.NewFsgid}} {{end}}
PtraceAction string The ptrace method used against a process. {{range .Notifications}} {{.MessageFields.PtraceAction}} {{end}}
RemoteHost string The remote host in a network event. {{range .Notifications}} {{.MessageFields.RemoteHost}} {{end}}
RemotePort uint16 The remote port in a network event. {{range .Notifications}} {{.MessageFields.RemotePort}} {{end}}
SystemCall string The syscall name referenced in an alert. {{range .Notifications}} {{.MessageFields.SystemCall}} {{end}}
DurationUnits string The time unit in which relevant events occurred. {{range .Notifications}} {{.MessageFields.DurationUnits}} {{end}}
DurationValue float64 The number of time units in which relevant events occurred. {{range .Notifications}} {{.MessageFields.DurationValue}} {{end}}
ModifiedElements []ModifiedElement A map of elements that have changed, along with their old and new values. {{range .Notifications}} {{.MessageFields.ModifiedElements}} {{end}}
Operations string The list of operations that were performed during the event. {{range .Notifications}} {{.MessageFields.Operations}} {{end}}

ModifiedElement

ModifiedElement is accessible through the Alert Notification's MessageFields.ModifiedElements field which is a slice.

Field Type Description Usage Example
ElementName string The element’s name. {{range .Notifications}} {{range .MessageFields.ModifiedElements}} {{.ElementName}} {{end}} {{end}}
ExpectedValue string The “normal” value. {{range .Notifications}} {{range .MessageFields.ModifiedElements}} {{.ExpectedValue}} {{end}} {{end}}
PreviousValue string The element’s old value. {{range .Notifications}} {{range .MessageFields.ModifiedElements}} {{.PreviousValue}} {{end}} {{end}}
NewValue string The element’s new value. {{range .Notifications}} {{range .MessageFields.ModifiedElements}} {{.NewValue}} {{end}} {{end}}

AlertFilterMatch

AlertFilterMatch is accessible through the Alert MatchedObjects field which is a slice.

Field Type Description Usage Example
MatchedField string The field name. {{range .MatchedObjects}} {{.MatchedField}} {{end}}
MatchedValue string The field value. {{range .MatchedObjects}} {{.MatchedValue}} {{end}}
MatchOperator string The operator used in the comparison. {{range .MatchedObjects}} {{.MatchOperator}} {{end}}
MatchedPattern string What the field name was matched to. {{range .MatchedObjects}} {{.MatchedPattern}} {{end}}
MatchedDescription string The user-supplied description of the pattern. {{range .MatchedObjects}} {{.MatchedDescription}} {{end}}

ProcessInfo

ProcessInfo is accessible through the Alert ProcessInfo field and the Alert Lineage field which is a slice.

The usage examples below illustrate the simpler path through the Alert ProcessInfo field.

For access through the Alert Lineage field do the following:

{{range .Lineage}} {{.$FIELD}} {{end}}

Replace $FIELD with your field name of choice (e.g. Uuid).

Field Type Description Usage Example
Uuid string The UUID of this process. {{.ProcessInfo.Uuid}}
TimestampHostMono uint64 The Unix timestamp fork mono, or first seen host mono for this process. {{.ProcessInfo.TimestampHostMono}}
Parent *ProcessInfo The process information about the parent who forked. {{.ProcessInfo.Parent}}
PreviousState *ProcessInfo The possible previous state of this process (e.g. before an execve(2)). {{.ProcessInfo.PreviousState}}
Pid uint32 The process’ ID. {{.ProcessInfo.Pid}}
Program *ProgramInfo The current program. {{.ProcessInfo.Program}}
CurrentWorkingDirectory string The current working directory of this process. {{.ProcessInfo.CurrentWorkingDirectory}}
Privileges []int The process’ privileges. {{.ProcessInfo.Privileges}}
Username string The username for user ID of the task/thread. {{.ProcessInfo.Username}}
Group string The group name for group ID of the task/thread. {{.ProcessInfo.Group}}
EffectiveUsername string The effective username for user ID of the task/thread. {{.ProcessInfo.EffectiveUsername}}
EffectiveGroup string The effective group for group ID of the task/thread. {{.ProcessInfo.EffectiveGroup}}
SavedUsername string The saved username for saved user ID of the task/thread. {{.ProcessInfo.SavedUsername}}
SavedGroupname string The saved group name for saved group ID of the task/thread. {{.ProcessInfo.SavedGroupname}}
FileSystemUsername string The filesystem username for the FsUID of the task/thread. {{.ProcessInfo.FileSystemUsername}}
FileSystemGroup string The filesystem group for the FsGID of the task/thread. {{.ProcessInfo.FileSystemGroup}}
ExitTimestampHostMono uint64 The time the process exited. {{.ProcessInfo.ExitTimestampHostMono}}

ProgramInfo

ProgramInfo is accessible through the Alert ProcessInfo field and the Alert Lineage's ProcessInfo field.

The usage examples below illustrate the simpler path through the Alert ProcessInfo field.

For access through the Alert Lineage field do the following:

{{range .Lineage}} {{.Program.$FIELD}} {{end}}

Replace $FIELD with your field name of choice (e.g. Path).

Field Type Description Usage Example
Path string The path to the program’s executable. {{.Program.Path}}
CmdLine string The command line. {{.Program.CmdLine}}
Arguments []string The program’s arguments. {{.Program.Arguments}}
TimestampHostMono uint64 The timestamp of exec or first seen program event time. {{.Program.TimestampHostMono}}
Complete bool Determines if the program exec event was not observed such as if this program existed before program tracking began. {{.Program.Complete}}

Priority

Priority is an enum accessible through the Alert Priority field.

It can be one of the following strings:

  • Unknown
  • Low
  • Medium
  • High

Confidence

Confidence is an enum accessible through the Alert Confidence field.

It can be one of the following strings:

  • Zero
  • Low
  • MediumLow
  • MediumHigh
  • High
  • Max

Policy

Policy is an enum accessible through the Alert PolicyType field.

It can be one of the following strings:

  • AppArmor
  • BPFExec
  • Chmod
  • Connect
  • CloudMetadata
  • File
  • FileMonitor
  • Filter
  • InteractiveShell
  • KernelPayload
  • LoadKernelModule
  • MemoryProtection
  • NewFileExec
  • PrivilegeEscalation
  • Program
  • Ptrace
  • RemoteInteractiveShell
  • Segfault
  • SELinux
  • Sendto
  • SensorTimeout
  • SetPrivilege
  • Setrlimit
  • SmepSmap
  • SpectreMeltdown
  • StackPivotDetection
  • NetworkService
  • YaraScan

Scope

Scope is an enum accessible through the Alert Scope field.

It can be one of the following strings:

  • Other
  • Process
  • RootProcess
  • Container
  • Node
  • Subnet
  • Socket