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 group ID of the alert.	{{.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	Task	The information about the process that generated the Alert (if available).	{{.ProcessInfo}}
Lineage	[]Task	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}}
AuditGroupID	string	The audit group id of the alert.	{{.AuditGroupID}}

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}}
ContainerLabels	map[string]string	Describes the labels assigned to the container by the container runtime.	{{.Location.ContainerLabels}}

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}}
MechanismDisableSucceeded	bool	Whether the affected security mechanisms referenced in DisabledMechanism were actually disabled.	{{range .Notifications}} {{.MessageFields.MechanismDisableSucceeded}} {{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}}
RunCmdArg	string	The argument passed to run_cmd.	{{range .Notifications}} {{.MessageFields.RunCmdArg}} {{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}}
InterfaceIP	string	The IP address used in network service.	{{range .Notifications}} {{.MessageFields.InterfaceIP}} {{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}}
NewCapabilities	string	String list of the new capabilities for the program.	{{range .Notifications}} {{.MessageFields.NewCapabilities}} {{end}}
InHostUserNamespace	bool	Whether the capabilities are in host user namespace.	{{range .Notifications}} {{.MessageFields.InHostUserNamespace}} {{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}}
FileContainerID	string	The container ID in which the file resides.	{{range .Notifications}} {{.MessageFields.FileContainerID}} {{end}}
LostRecordsType	string	The type of events lost.	{{range .Notifications}} {{.MessageFields.LostRecordsType}} {{end}}
CreatorName	string	Name of the process that created or modified the target.	{{range .Notifications}} {{.MessageFields.CreatorName}} {{end}}
CreatorProcessInfo	*info.task	The full Task info of the process that created or modified the target.	{{range .Notifications}} {{.MessageFields.CreatorProcessInfo}} {{end}}
CreatorLineage	[]info.Task	The full lineage of the process that created or modified the target.	{{range .Notifications}} {{.MessageFields.CreatorLineage}} {{end}}
TimeSinceModify	string	The string representation of the duration from target file modification to now.	{{range .Notifications}} {{.MessageFields.TimeSinceModify}} {{end}}
BatchedAlertsCount	int32	The number of alerts that were batched into this one.	{{range .Notifications}} {{.MessageFields.BatchedAlertsCount}} {{end}}
MemoryRegion	string	The string representation of the region of memory that is relevant to the alert.	{{range .Notifications}} {{.MessageFields.MemoryRegion}} {{end}}
SignatureRule	string	Name of the signature that matched.	{{range .Notifications}} {{.MessageFields.SignatureRule}} {{end}}
SignaturePath	string	Path to the signature bundle that matched.	{{range .Notifications}} {{.MessageFields.SignaturePath}} {{end}}
SignatureEventType	string	The type event the alert signifies, such as start, complete, alert, or error.	{{range .Notifications}} {{.MessageFields.SignatureEventType}} {{end}}
CustomFields	map[string]interface{}	Any custom fields specified by a custom kprobe policy.	{{range .Notifications}} {{.MessageFields.CustomFields}} {{end}}
TargetProcessInfo	*info.Task	The full Task info of the process that was targeted.	{{range .Notifications}} {{.MessageFields.TargetProcessInfo}} {{end}}
TargetLineage	[]info.Task	The full lineage of the process that was targeted.	{{range .Notifications}} {{.MessageFields.TargetLineage}} {{end}}
TagName	string	Tag name from tag event.	{{range .Notifications}} {{.MessageFields.TagName}} {{end}}
TagCount	int64	Count from tag event.	{{range .Notifications}} {{.MessageFields.TagCount}} {{end}}
CommandLine	string	The command line data that matched.	{{range .Notifications}} {{.MessageFields.CommandLine}} {{end}}
CommandLineSource	string	The source of the command line data that matched.	{{range .Notifications}} {{.MessageFields.CommandLineSource}} {{end}}
CacheMissRatio	float64	The ratio of cache misses to cache references in the spectre/meltdown strategy.	{{range .Notifications}} {{.MessageFields.CacheMissRatio}} {{end}}
L1DStallCycleRatio	float64	The ratio of l1d miss stall cycles to cache references in the spectre/meltdown strategy.	{{range .Notifications}} {{.MessageFields.L1DStallCycleRatio}} {{end}}
CacheLineFlushRatio	float64	The ratio of cache line flushes to cache references in the spectre/meltdown strategy.	{{range .Notifications}} {{.MessageFields.CacheLineFlushRatio}} {{end}}
CPU	*int32	CPU/core which that spectre/meltdown event happened on.	{{range .Notifications}} {{.MessageFields.CPU}} {{end}}
EntityID	*int32	ID of entity that was operated on.	{{range .Notifications}} {{.MessageFields.EntityID}} {{end}}
EntityName	string	Name of entity that was operated on.	{{range .Notifications}} {{.MessageFields.EntityName}} {{end}}
EntityType	string	Type of entity that was operated on.	{{range .Notifications}} {{.MessageFields.EntityType}} {{end}}
UnixSocketPath	string	Targeted socket path.	{{range .Notifications}} {{.MessageFields.UnixSocketPath}} {{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}}
Tgid	uint32	The process' ID in userland. same as .ThreadGroup.Tgid	{{.ProcessInfo.Tgid}}
Tid	uint32	The process' ID in kerneland	{{.ProcessInfo.Tid}}
WorkingDirectory	*string	The current working directory of this process.	{{.ProcessInfo.WorkingDirectory}}
Privileges	[]int	The process’ privileges.	{{.ProcessInfo.Privileges}}
Capabilities	unit64	Capabilities of this thread.	{{.ProcessInfo.Capabilities}}
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}}
ThreadGroup	*ThreadGroup	The process this thread belongs to	{{.ThreadGroup}}
Program	*Program	The current program.	{{.ProcessInfo.Program}}

ThreadGroup

ThreadGroup 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 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	{{.ProcessInfo.ThreadGroup.Uuid}}
TimestampHostMono	uint64	The Unix timestamp fork mono, or first seen host mono for this process.	{{.ProcessInfo.ThreadGroup.TimestampHostMono}}
Container	*Container	The container of the thread group.	{{.ProcessInfo.ThreadGroup.Container}}
Parent	*ThreadGroup	The current parent, not necessarily creator	{{.ProcessInfo.ThreadGroup.Parent}}
PreviousState	*ThreadGroup	The possible previous state of this process (e.g. before an execve(2)).	{{.ProcessInfo.ThreadGroup.PreviousState}}
Tgid	uint32	The process' ID in userland	{{.ProcessInfo.ThreadGroup.Tgid}}
Leader	*Task	The leading thread	{{.ProcessInfo.ThreadGroup.Leader}}
Program	*Program	The current program.	{{.ProcessInfo.ThreadGroup.Program}}

Program

Program 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}}
Arguments	[]string	The program’s arguments.	{{.Program.Arguments}}
TimestampHostMono	uint64	The timestamp of exec or first seen program event time.	{{.Program.TimestampHostMono}}
SHA256Hash	string	Computed SHA256 hash of the program's main binary.	{{.Program.SHA256Hash}}

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

ThreadGroup

Program

Enum Types

Related articles