Reference: Alert Template Schema – Capsule8

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 Policy.	{{.Description}}
Comments	string	The comments on the Alert from Policy.	{{.Comments}}
UUID	string	The Universally Unique ID for this Alert.	{{.UUID}}
AlertLabels	map[string]string	The Alert labels from Policy.	{{.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 Policy.	{{.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}}
ThreadGroup	*ThreadGroupInfo	The process this thread belongs to	{{.ThreadGroup}}
Tgid	uint32	The process' ID in userland. same as .ThreadGroup.Tgid	{{.ProcessInfo.Tgid}}
Tid	uint32	The process' ID in kerneland	{{.ProcessInfo.Tid}}
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}}

ThreadGroupInfo

ThreadGroupInfo is accessible through the Alert ThreadGroupInfo field and the Alert Lineage's ThreadGroupInfo field.

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

For access through the Alert Lineage field do the following:

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

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

Field	Type	Description	Usage Example
Uuid	string	The thread uuid of the thread group leader	{{.Uuid}}
TimestampHostMono	uint64	The Unix timestamp fork mono, or first seen host mono for this process.	{{.TimestampHostMono}}
Parent	*ThreadGroupInfo	The current parent, not necessarily creator	{{.Parent}}
PreviousState	*ThreadGroupInfo	The possible previous state of this process (e.g. before an execve(2)).	{{.PreviousState}}
Tgid	uint32	The process' ID in userland	{{.Tgid}}
Leader	*ProcessInfo	The leading thread	{{.Leader}}
Program	*ProgramInfo	The current program.	{{.ProcessInfo.Program}}

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}}

Enum Types

Priority

String	Integer
Unknown	0
Info	1
Low	2
Medium	3
High	4

Confidence

String	Integer
Zero	0
Low	1
MediumLow	2
MediumHigh	4
High	5
Max	6

PolicyType

String	Integer
AppArmor	0
BPFExec	1
Chmod	2
Connect	3
ContainerEscape	4
CloudMetadata	5
File	6
FileMonitor	7
FileAccess	8
Filter	9
InteractiveShell	10
KernelPayload	11
LoadKernelModule	12
MemoryProtection	13
NewFileExec	14
UnauthorizedKernelCredentialChange	15
Program	16
Ptrace	17
RemoteInteractiveShell	18
Segfault	19
SELinux	20
Sendto	21
SetPrivilege	22
Setrlimit	23
SmepSmap	24
SpectreMeltdown	25
StackPivotDetection	26
NetworkService	27
YaraScan	28
UserFaultFD	29
ShellCommand	30
Heartbeat	31
CoverageDrop	32
Kprobe	33
TagEvent	34
Uprobe	35

Scope

String	Integer
Other	0
Process	1
RootProcess	2
Container	3
Node	4
Subnet	5
Socket	6

GroupingScope

String	Integer
None	0
Process	1
ParentProcess	2
Container	3
Host	4

Alert

AlertLocation

AlertNotification

AlertMessageFields

ModifiedElement

AlertFilterMatch

ProcessInfo

ThreadGroupInfo

ProgramInfo

Enum Types

Related articles