General

The Anomaly Rules Engine is a powerful tool CAST AI provided as part of our Kubernetes runtime security feature set. It allows you to define custom rules to detect and classify events as anomalies based on specific criteria. This enables proactive monitoring and alerting for potential security threats or unusual behavior within your Kubernetes cluster.

Rule types

The Anomaly Rules Engine supports two types of rules:

• Built-In Rules: These rules are pre-defined by CAST AI and cover common security scenarios. They are readily available for use and can be quickly enabled or disabled as needed.
• User-Defined CEL Rules: These rules are custom-defined by you using the Common Expression Language (CEL). CEL provides a flexible and expressive way to define complex matching criteria based on event properties and resource attributes.

Each rule consists of two main components:

• Resource Selectors: Used to filter and select the relevant resources to which the rule should be applied.
• Event Matching: Defines the conditions and criteria for identifying anomalous events.

📘

Note

Only the resource selectors can be modified for Built-In rules, while the event-matching logic is pre-defined by CAST AI. For User-Defined CEL rules, you have full control over both the resource selectors and event-matching logic.

Resource selectors

Resource selectors allow you to filter events based on specific resource attributes before applying the rule. This helps narrow down the scope of events to be analyzed.

Resource selectors are defined using CEL expressions. The CEL program has access to two variables:

• cluster of type types.Cluster: Represents the Kubernetes cluster.
• resource of type types.KubernetesObject: Represents the Kubernetes resource associated with the event.

These variables expose various properties that can be used in the CEL expressions to select the desired resources. Refer to the corresponding sections below for more details on the available properties.

Resource selectors examples

Include only some clusters and namespaces:

cluster.name in ["dev", "testing"] && resource.namespace == "apps"

Exclude pods with prefixes:

resource.namespace == "castai-agent" && resource.pod.startsWith("castai-imgscan")

User-defined CEL rules

User-defined CEL rules provide the flexibility to define custom anomaly detection logic based on your specific requirements. You can write CEL expressions to match events and trigger anomalies based on various conditions.

CEL rules Examples

Detect OOM:

event.type == event_process_oom_killed

Detect that container dropped new executed binary and process started with the name nginx:

event.type == event_magic_write && event.process.name.startsWith("nginx")

Detect TCP connection to non-standard ports for public IP:

event.type == event_tcp_connect &&
event.tcp.destination.ip.public() && 
!(event.tcp.destination.port in [80, 443])

Detect exec arguments matches:

cel.bind(bad_args, ["tigervnc", "novnc", "--vnc", "rfbport"],
event.type == event_exec &&
bad_args.exists_one(bad_arg, 
	event.exec.args.exists_one(arg, arg.lowerAscii().contains(bad_arg))
))

Allow dropped binary by hash:

event.type == event_exec && event.exec.is_upper_layer && 
!(hex(event.exec.sha256) in [
  "9f64a747e1b97f131fabb6b447296c9b6f0201e79fb3c5356e6c77e89b6a806a",
])

Allow dropped binary by hash from custom list:

event.type == event_exec && event.exec.is_upper_layer && 
  !customLists("allowed-binaries").contains(match_sha256, event.exec.sha256)

NOTE: The allowed-binaries list need to be created before. See the custom list sections of the docs for more details.

Detect SSH:

event.type == event_ssh

Exposed variables

In a User-defined CEL rule, the program has access to the event through the event variable of type types.Event. This variable represents the current event being evaluated and provides access to its properties.

Refer to the sections below for more information on the available exposed properties.

Helper Functions

The Anomaly Rules Engine provides several helper functions that can be used in CEL expressions to perform common operations:

These functions can be used in your CEL expressions to parse and manipulate data related to events and resources. They provide convenient ways to work with IP addresses, CIDR notations, hexadecimal representations, and UUIDs.

Common Types

The Anomaly Rules Engine uses various types to represent events, resources, and their associated properties. These types expose properties that can be accessed and used in CEL expressions to define resource selectors and event-matching logic. Here are the commonly used types.

types.Event

The types.Event type represents an event observed in the Kubernetes cluster. It contains information about the event type, timestamp, associated cluster, resource, and other event-specific details.

types.EventType

The types.EventType type represents the different types of events that can be observed by the Anomaly Rules Engine. Each event type corresponds to a specific action or occurrence in the Kubernetes cluster.

types.Cluster

The types.Cluster type represents a Kubernetes cluster and contains information about the cluster's identity and organization.

types.KubernetesObject

The types.KubernetesObject type represents a Kubernetes resource associated with an event. It provides details about the container, pod, namespace, and workload related to the event.

types.Process

types.DNSPayload

The types.DNSPayload type represents details about an observed DNS query. If the observed event was triggered by a DNS server, flow_direction will be set to flow_egress.

types.DNSAnswer

The types.DNSAnswer type represents the answer received for a DNS query. It contains information about the type of the answer and the associated data.

types.DNSAnswerType

The types.DNSAnswerType type represents the different types of DNS answers that can be received.

types.ExecPayload

The types.ExecPayload type contains additional information about an observed command execution event.

types.FilePayload

The types.FilePayload type represents additional information about a file related to the event.

types.TCPPayload

The types.TCPPayload type contains additional information about observed TCP actions

types.StdioViaSocketPayload

The types.StdioViaSocketPayload type represents additional information about a potential reverse shell event.

types.SSHPayload

The types.SOCKS5Role type represents the role of the observed process in SOCKS5 communication.

types.AddrPort

The types.AddrPort type represents an IP address and port combination.

types.NetworkDetails

The types.NetworkDetails type contains additional information about a network.

types.FlowDirection

The types.FlowDirection type represents the direction of network flow.

types.Category

The types.Category type represents different categories to which events can be classified.

types.FileDetails

The types.FileDetails type contains additional details about a file.

types.IPDetails

The types.IPDetails type represents additional information about an IP address.

types.SOCKS5Payload

The types.SOCKS5Payload type contains additional information about observed SOCKS5 actions.

types.SOCKS5CmdOrReply

The types.SOCKS5CmdOrReply type represents the different address types used in SOCKS5 commands or replies.

types.SOCKS5Role

The types.SOCKS5Role type represents the role of the observed process in SOCKS5 communication.

Custom Lists

It often can be useful to specify a list of values that can be quickly probed to e.g. test if a given binary hash is malicious. Within the CAST.AI security product, this can be achieved by so called CustomLists.

As of right now, Custom Lists can only be managed via the corresponding REST API endpoints. To create a custom list, use the /v1/security/runtime/list endpoint. All it expects is the name of the list, that will also be used to reference them from within CEL rules. On that note, list names are required to be unique (the API will return an error if one tries to create a list with an already existing name).

Now that we have a list, we can add entries to it. Those can then later be probed from within the CEL rule. Adding items to list is achieved by calling the /v1/security/runtime/list/{id}/add endpoint. As of right now, the following types of entries are supported:

Items from lists can be removed via the /v1/security/runtime/list/{id}/remove endpoint. All fields of the entry you want to delete must be specified and match.

To delete a whole custom list, you can use the /v1/security/runtime/list/delete endpoint. The ID to be used in any of the list related endpoints can be retrieved by either storing it after a list create, or by querying via the /v1/security/runtime/list endpoint. NOTE: Lists that are referenced in CEL rules cannot be deleted.

Now that we created a custom list, lets have a look how to use it as part of a CEL rule. Lets have a look at a quick example:

event.type == event_exec &&
  customLists("known-malware", "likely-malware").contains(match_sha256, event.exec.sha256)

Custom lists can be loaded via the customLists function. This returns a custom list matcher, that offers a contains method. The first argument specifies what type of value to match. Here is a list of all currently available matchers:

You can feed any value into the contains function, as long as it matches the argument type required by the matcher.