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 |
Comments
0 comments
Please sign in to leave a comment.