This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Actionners

Actionners are the built-it actions to react to the events

1: List of Actionners
2: Contexts

The Actionners define the actions to apply when an event matches a rule, they are named with pattern category:action.

The category allows to group actions and avoid multiple initializations (eg, multi Kubernetes API client, multi AWS clients, …).

Each actionner is configured with parameters, a map of values passed to the action. The values can be a string, a list (array) or a map (map[string]string).

Example:

- action: Terminate the pod
  actionner: kubernetes:terminate
  parameters:
    grace_period_seconds: 5
    ignore_daemonsets: true
    ignore_statefulsets: true
    min_healthy_replicas: 33%

- action: Label the pod
  actionner: kubernetes:label
  parameters:
    labels:
      suspicious: true

- action: Get logs
  actionner: kubernetes:log
  output:
    target: minio:s3
    parameters:
      bucket: my-bucket
      prefix: /logs/

- action: Run Lambda
  actionner: aws:lambda
  parameters:
    aws_lambda_name: my-function
    aws_lambda_alias_or_version: $LATEST
  contexts:
    - aws
    - k8snode

Warning

Some actionners have by default the setting Continue set by default to false, this stops the evaluation of the next actions of the rule. It can be overridden.

Contexts

Some actionners allow to specify which sources to use to inject elements in the context field of the event payload, before triggering the action. The context of Falco Talon (the rule name, the action name, the action parameters, etc) are injected anyway.

Outputs

Some actionners allow or require to specify a destination for the generated/collected artifacts. See here to know more.

aws

Warning

You must configure the aws section of the config.yaml to enable this injection.

Elements:

aws.instance_profile_arn
aws.instance_profile_id
aws.region

k8snode

Elements:

node.hostname
node.instancetype
node.role
node.topology.region
node.topology.zone
node.spec.providerid

1 - List of Actionners

Available actionners

The required fields are the field elements that must be present in your Falco event to allow the actionner to do its work.

`kubernetes`

The category kubernetes can be initialized with a kubeconfig file when Falco Talon runs outside Kubernetes.

`kubernetes:terminate`

Name: terminate
Category: kubernetes
Description: Terminate the pod
Continue: false
Required fields:
- k8s.pod.name
- k8s.ns.name
Use context: false
Output: n/a
Source: syscalls

Parameters

grace_period_seconds: The duration in seconds before the pod should be deleted. The value zero indicates delete immediately.
ignore_daemonsets: If true, the pods which belong to a Daemonset are not terminated.
ignore_statefulsets: If true, the pods which belong to a Statefulset are not terminated.
ignore_standalone_pods: If true, standalone pods (not belonging to any controller) are not terminated.
min_healthy_replicas: Minimum number of healthy pods to allow the termination, can be an absolute or % value (the value must be a quoted string).

Permissions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: falco-talon
rules:
  - apiGroups:
    - ""
    resources:
    - pods
    verbs:
    - get
    - delete
    - list
  - apiGroups:
    - apps
    resources:
    - replicasets
    verbs:
    - get

Example

- action: Terminate the pod
  actionner: kubernetes:terminate
  parameters:
    grace_period_seconds: 5
    ignore_daemonsets: true
    ignore_statefulsets: true
    min_healthy_replicas: 33%

`kubernetes:label`

Name: label
Category: kubernetes
Description: Add, modify or delete the labels of the pod/node
Continue: true
Required fields:
- k8s.pod.name
- k8s.ns.name
Use context: false
Output: n/a
Source: syscalls

Parameters

level: level to apply the apply the labels, can be node or pod (default)
labels: (required) key:value map of labels to add/modify/delete (empty value means label deletion)

Permissions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: falco-talon
rules:
  - apiGroups:
    - ""
    resources:
    - pods
    - nodes
    verbs:
    - get
    - update
    - patch
    - list

Example

- action: Label the pod
  actionner: kubernetes:label
  parameters:
    level: pod
    labels:
      suspicious: true

`kubernetes:annotation`

Name: annotation
Category: kubernetes
Description: Add, modify or delete the annotations of the pod/node
Continue: true
Required fields:
- k8s.pod.name
- k8s.ns.name
Use context: false
Output: n/a
Source: syscalls

Parameters

level: level to apply the apply the annotations, can be node or pod (default)
annotations: (required) key:value map of annotations to add/modify/delete (empty value means annotation deletion)

Permissions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: falco-talon
rules:
  - apiGroups:
    - ""
    resources:
    - pods
    - nodes
    verbs:
    - get
    - update
    - patch
    - list

Example

- action: Annotate the pod
  actionner: kubernetes:annotation
  parameters:
    level: pod
    annotations:
      suspicious: true

`kubernetes:networkpolicy`

Name: networkpolicy
Category: kubernetes
Description: Create, update a network policy to block all egress traffic for pod
Continue: true
Required fields:
- k8s.pod.name
- k8s.ns.name
Use context: false
Output: n/a
Source: syscalls

Parameters

allow_cidr: list of CIDR to allow anyway (eg: private subnets)
allow_namespaces: list of namespaces to allow anyway

Permissions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: falco-talon
rules:
  - apiGroups:
    - ""
    resources:
    - pods
    verbs:
    - get
    - list
  - apiGroups:
    - networking.k8s.io
    resources:
    - networkpolicies
    verbs:
    - get
    - update
    - patch
    - create
  - apiGroups:
    - apps
    resources:
    - daemonsets
    verbs:
    - get
  - apiGroups:
    - apps
    resources:
    - deployments
    verbs:
    - get
  - apiGroups:
    - apps
    resources:
    - replicasets
    verbs:
    - get
  - apiGroups:
    - apps
    resources:
    - statefulsets
    verbs:
    - get

Example

- action: Create a network policy
  actionner: kubernetes:networkpolicy
  parameters:
    allow_cidr:
      - "192.168.1.0/24"
      - "172.17.0.0/16"
    allow_namespaces:
      - "green-ns"
      - "blue-ns"

`kubernetes:exec`

Name: exec
Category: kubernetes
Description: Exec a command in a pod
Continue: true
Required fields:
- k8s.pod.name
- k8s.ns.name
Use context: true
Output: n/a
Source: syscalls

Parameters

shell: SHELL used to run the command (default: /bin/sh)
command: (required) Command to run

Permissions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: falco-talon
rules:
  - apiGroups:
    - ""
    resources:
    - pods
    verbs:
    - get
    - list
  - apiGroups:
    - ""
    resources:
    - pods/exec
    verbs:
    - get
    - create

Example

- action: Exec a command into the pod
  actionner: kubernetes:exec
  parameters:
    shell: /bin/bash
    command: "cat ${FD_NAME}"

Info

For the available contexts, see here.

`kubernetes:script`

Name: script
Category: kubernetes
Description: Run a script in a pod
Continue: true
Required fields:
- k8s.pod.name
- k8s.ns.name
Use context: true
Output: n/a
Source: syscalls

Parameters

shell: SHELL used to run the script (default; /bin/sh)
script: Script to run (use | to use multilines) (can’t be used at the same time than file)
file: Shell script file (can’t be used at the same time than script)

Permissions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: falco-talon
rules:
  - apiGroups:
    - ""
    resources:
    - pods
    verbs:
    - get
    - list
  - apiGroups:
    - ""
    resources:
    - pods/exec
    verbs:
    - get
    - create

Example

- action: Run a script into the pod
  actionner: kubernetes:script
  parameters:
    shell: /bin/bash
    script: |
      ps awxuf
      netstat -lpauten
      top -n 1
      cat ${FD_NAME}

Info

For the available contexts, see here.

`kubernetes:log`

Name: log
Category: kubernetes
Description: Get logs from a pod
Continue: true
Required fields:
- k8s.pod.name
- k8s.ns.name
Use context: false
Output: optionnal (if no output is specified, the logs are printed in the log line)
Source: syscalls

Parameters

tail_lines: The number of lines from the end of the logs to show (default: 20)

Permissions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: falco-talon
rules:
  - apiGroups:
    - ""
    resources:
    - pods
    verbs:
    - get
    - list
  - apiGroups:
    - ""
    resources:
    - pods/log
    verbs:
    - get

Example

- action: Get logs of the pod
  actionner: kubernetes:log
  parameters:
    tail_lines: 200
  output:
    target: aws:s3
    parameters:
      bucket: my-bucket
      prefix: /logs/

`kubernetes:download`

Name: download
Category: kubernetes
Description: Download a file from a pod
Continue: true
Required fields:
- k8s.pod.name
- k8s.ns.name
Use context: true
Output: required
Source: syscalls

Parameters

file: (required) The full path of the file to download

Permissions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: falco-talon
rules:
  - apiGroups:
    - ""
    resources:
    - pods
    verbs:
    - get
    - list
  - apiGroups:
    - ""
    resources:
    - pods/exec
    verbs:
    - get
    - create

Example

- action: Get logs of the pod
  actionner: kubernetes:download
  parameters:
    tail_lines: 200
  output:
    target: aws:s3
    parameters:
      bucket: my-bucket
      prefix: /files/

`kubernetes:tcpdump`

Name: tcpdump
Category: kubernetes
Description: Capture the network packets for the pod
Continue: true
Required fields:
- k8s.pod.name
- k8s.ns.name
Use context: false
Output: required
Source: syscalls

Parameters

duration: duration in seconds of the capture (default: 5)
snaplen: number of bytes captured for each packet (default: 4096)

Permissions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: falco-talon
rules:
  - apiGroups:
    - ""
    resources:
    - pods
    verbs:
    - get
    - update
    - patch
    - list
  - apiGroups:
    - ""
    resources:
    - pods/ephemeralcontainers
    verbs:
    - patch
    - create
  - apiGroups:
    - ""
    resources:
    - pods/exec
    verbs:
    - get
    - create

Example

- action: Get logs of the pod
  actionner: kubernetes:tcpdump
  parameters:
    duration: 10
    snaplen: 1024
  output:
    target: aws:s3
    parameters:
      bucket: my-bucket
      prefix: /captures/

`kubernetes:delete`

Name: delete
Category: kubernetes
Description: Delete the resource
Continue: false
Required fields:
- ka.target.resource
- ka.target.name
- ka.target.namespace
Use context: false
Output: n/a
Source: k8saudit

Parameters

N/A

Permissions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: falco-talon
rules:
  - apiGroups:
    - ""
    resources:
    - namespaces
    verbs:
    - get
    - delete
  - apiGroups:
    - ""
    resources:
    - pods
    verbs:
    - get
    - delete
    - list
  - apiGroups:
    - apps
    resources:
    - daemonsets
    verbs:
    - get
    - delete
  - apiGroups:
    - apps
    resources:
    - deployments
    verbs:
    - get
    - delete
  - apiGroups:
    - apps
    resources:
    - replicasets
    verbs:
    - get
    - delete
  - apiGroups:
    - apps
    resources:
    - statefulsets
    verbs:
    - get
    - delete
  - apiGroups:
    - rbac.authorization.k8s.io
    resources:
    - roles
    verbs:
    - get
    - delete
  - apiGroups:
    - rbac.authorization.k8s.io
    resources:
    - clusterroles
    verbs:
    - get
    - delete
  - apiGroups:
    - ""
    resources:
    - configmaps
    verbs:
    - get
    - delete
  - apiGroups:
    - ""
    resources:
    - secrets
    verbs:
    - get
    - delete

Example

- action: Delete the suspicious resource
  actionner: kubernetes:delete
  parameters:
    tail_lines: 200

Info

The managed resources are:

namespace
configmap
secret
deployment
daemonset
service
serviceaccount
replicaset
statefulset
role
clusterole

`kubernetes:cordon`

Name: cordon
Category: kubernetes
Description: Cordon a node
Continue: true
Required fields:
- k8s.pod.name
- k8s.ns.name
Use context: false
Output: n/a
Source: syscalls

Parameters

N/A

Permissions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: falco-talon
rules:
  - apiGroups:
    - ""
    resources:
    - pods
    verbs:
    - get
    - list
  - apiGroups:
    - ""
    resources:
    - nodes
    verbs:
    - get
    - update
    - patch

Example

- action: Cordon the node
  actionner: kubernetes:cordon

`kubernetes:drain`

Name: drain
Category: kubernetes
Description: Drain a node
Continue: true
Required fields:
- k8s.pod.name
- k8s.ns.name
Use context: false
Output: n/a
Source: syscalls

Parameters

ignore_daemonsets: If true, the pods which belong to a Daemonset are not terminated.
ignore_statefulsets: If true, the pods which belong to a Statefulset are not terminated.
min_healthy_replicas: Minimum number of healthy pods to allow the termination, can be an absolute or % value (the value must be a quoted string).
ignore_error: If true, errors during the drain will be ignored, resulting in a successful action call. Used to control subsequent actions flow.
max_wait_period: Amount of time to wait for eviction. If not set, the actionner will immediately return after calling the API for eviction.
wait_period_excluded_namespaces: List of namespaces to exclude from the waiting period. If set, pods on those namespaces won’t be part of the waiting process.

Permissions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: falco-talon
rules:
  - apiGroups:
    - ""
    resources:
    - pods
    verbs:
    - get
    - list
  - apiGroups:
    - ""
    resources:
    - pods/eviction
    verbs:
    - get
    - create
  - apiGroups:
    - apps
    resources:
    - replicasets
    verbs:
    - get

Example

- action: Drain the node
  actionner: kubernetes:drain

`calico`

The category calico can be initialized with a kubeconfig file when Falco Talon runs outside Kubernetes.

`calico:networkpolicy`

Name: networkpolicy
Category: calico
Description: Create a Calico Network Policy to block the egress traffic to a specific IP
Continue: true
Required fields:
- fd.sip or fd.rip
Use context: false
Output: n/a
Source: syscalls

Parameters

allow_cidr: list of CIDR to allow anyway (eg: private subnets) (default: 0.0.0.0/0)
allow_namespaces: list of namespaces to allow anyway
order: order of the network policy

Permissions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: falco-talon
rules:
  - apiGroups:
    - ""
    resources:
    - pods
    verbs:
    - get
    - list
  - apiGroups:
    - projectcalico.org
    resources:
    - caliconetworkpolicies
    verbs:
    - get
    - update
    - patch
    - create
  - apiGroups:
    - apps
    resources:
    - daemonsets
    verbs:
    - get
  - apiGroups:
    - apps
    resources:
    - deployments
    verbs:
    - get
  - apiGroups:
    - apps
    resources:
    - replicasets
    verbs:
    - get
  - apiGroups:
    - apps
    resources:
    - statefulsets
    verbs:
    - get

Example

- action: Create Calico netpol
  actionner: calico:networkpolicy
  parameters:
    order: 20
    allow_cidr:
      - "192.168.1.0/24"
      - "172.17.0.0/16"
    allow_namespaces:
      - "green-ns"
      - "blue-ns"

`cilium`

The category cilium can be initialized with a kubeconfig file when Falco Talon runs outside Kubernetes.

`cilium:networkpolicy`

Name: networkpolicy
Category: cilium
Description: Create a Cilium Network Policy to block the egress traffic to a specific IP
Continue: true
Required fields:
- fd.sip or fd.rip
Use context: false
Output: n/a
Source: syscalls

Parameters

allow_cidr: list of CIDR to allow anyway (eg: private subnets) (default: 0.0.0.0/0)
allow_namespaces: list of namespaces to allow anyway
order: order of the network policy

Permissions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: falco-talon
rules:
  - apiGroups:
    - ""
    resources:
    - pods
    verbs:
    - get
    - list
  - apiGroups:
    - cilium.io
    resources:
    - ciliumnetworkpolicies
    verbs:
    - get
    - update
    - patch
    - create
  - apiGroups:
    - apps
    resources:
    - daemonsets
    verbs:
    - get
  - apiGroups:
    - apps
    resources:
    - deployments
    verbs:
    - get
  - apiGroups:
    - apps
    resources:
    - replicasets
    verbs:
    - get
  - apiGroups:
    - apps
    resources:
    - statefulsets
    verbs:
    - get

Example

- action: Create Cilium netpol
  actionner: cilium:networkpolicy
  parameters:
    allow_cidr:
      - "192.168.1.0/24"
      - "172.17.0.0/16"
    allow_namespaces:
      - "green-ns"
      - "blue-ns"

`aws`

`aws:lambda`

Name: lambda
Category: aws
Description: Invoke an AWS lambda forwarding the Falco event payload
Continue: true
Required AWS access:
- sts:getCallerIdentity
- lambda:InvokeFunction
- lambda:GetFunction
Use context: true
Output: n/a
Source: any

Parameters

aws_lambda_name: Lambda name to call. Lambda must reside in the same region as your default credential provider or static region provided in configuration.
aws_lambda_alias_or_version: Lambda alias or version to call. (default: $LATEST)
aws_lambda_invocation_type: Invocation type for Lambda. Accepted values: RequestResponse, Event, DryRun. (default: RequestResponse)

Permissions

{
    "Version": "2012-10-17",
    "Sta<tement": [
        {
            "Sid": "AllowInvokeLambdaFunction",
            "Effect": "Allow",
            "Action": "lambda:InvokeFunction",
            "Resource": "arn:aws:lambda:<region>:<account_id>:function:<function_name>"
        },
        {
            "Sid": "AllowSTSGetCallerIdentity",
            "Effect": "Allow",
            "Action": "sts:GetCallerIdentity"
        }
    ]
}

Example

- action: Invoke Lambda function
  actionner: aws:lambda
  parameters:
    aws_lambda_name: sample-function
    aws_lambda_alias_or_version: $LATEST
    aws_lambda_invocation_type: RequestResponse

Info

For the available contexts, see here.

`gcp`

`gcp:function`

Name: function
Category: gcp
Description: Invoke an GCP Function forwarding the Falco event payload
Continue: true
Required GCP access:
- cloudfunctions.functions.call
- cloudfunctions.functions.get
Use context: true
Output: n/a
Source: any

Parameters

gcp_function_name: Function name to call.
gcp_function_location: Function location.
gcp_function_timeout: Timeout configuration for HTTP server when calling the function.

Permissions

cloudfunctions.functions.call
cloudfunctions.functions.get

Example

- action: Invoke GCP function
  actionner: gcp:function
  parameters:
    gcp_function_name: sample-function
    gcp_function_location: us-central1
    gcp_function_timeout: 10

Info

For the available contexts, see here.

2 - Contexts

Available contexts for the actionners

The context is composed of elements from the original Falco event, from Falco Talon and other sources, these elements can be used to dynamically configure the actions to perform. They are all exposed as environment variables that can be used as tokens to replace in the parameters of the actions.

Except those from Falco, all the informations are also injected into a context section in the original payload (JSON) before the run of the action, it’s useful for the actionners using a third party system (ie: aws:lambda) to have the original Falco event and the context of what Falco Talon did.

Example:

{
    "output": "14:37:27.505989596: Warning Detected ptrace PTRACE_ATTACH attempt (proc_pcmdline=%proc.pcmdline evt_type=%evt.type user=%user.name user_uid=%user.uid user_loginuid=%user.loginuid process=%proc.name proc_exepath=%proc.exepath parent=%proc.pname command=%proc.cmdline terminal=%proc.tty exe_flags=%evt.arg.flags %container.info)",
    "priority": "WARNING",
    "rule": "PTRACE attached to process",
    "time": "2023-12-20T14:37:27.505989596Z",
    "output_fields": {
        "container.info": "container.info",
        "evt.arg.flags": "evt.arg.flags",
        "evt.type": "evt.type",
        "proc.cmdline": "proc.cmdline",
        "proc.exepath": "proc.exepath",
        "proc.name": "proc.name",
        "proc.pcmdline": "proc.pcmdline",
        "proc.pname": "proc.pname",
        "proc.tty": "proc.tty",
        "user.loginuid": "user.loginuid",
        "user.name": "user.name",
        "user.uid": "user.uid"
    },
    "hostname": "host-7.local",
    "source": "syscalls",
    "tags": [
        "maturity_stable",
        "host",
        "container",
        "process",
        "mitre_privilege_escalation",
        "T1055.008"
    ],
    "context": {
        "falco-talon.rule": "myrule",
        "falco-talon.rule.continue": true,
        "falco-talon.rule.dryrun": false,
        "falco-talon.rule.action": "myaction",
        "falco-talon.rule.actionner": "category:action",
        "falco-talon.rule.action.continue": true,
        "falco-talon.rule.action.ignore_errors": false,
        "falco-talon.rule.action.parameters": "{\"param1\": true, \"param2\": \"value2\", \"param3\": 10}",
    }
}

Info

Having the information exposed as environment variables allows to use them as tokens to replace in some actionners like kubernetes:script, kubernetes:download, … Their presences in the context section of the payload (JSON) is useful for the actionners based on third parties like aws:lambda.

Falco

The exposed env vars concerning Falco are exported as environment variables:

PRIORITY: the priority of the Falco events
HOSTNAME: the hostname where the Falco event occured
SOURCE: the source for the Falco event
RULE: the name of the rule that created the Falco event
TAGS: a comma separated list of the tags associated with the Falco event
All the OutputFields of the Falco event are exported, in uppercase, with the dots replaced by _ and the brackets [ ] removed, examples:
- fd.name > FD_NAME
- proc.args[0] > PROC_ARGS_0

Falco Talon

The exposed env vars concerning Falco are:

FALCO-TALON_RULE: the name of the Falco Talon rule that matches
FALCO-TALON_RULE_CONTINUE: if the Falco Talon rule allows to continue or not
FALCO-TALON_RULE_DRYRUN: if the Falco Talon rule dry runs or not
FALCO-TALON_RULE_ACTION: the name of the action triggered by the Falco Rule
FALCO-TALON_RULE_ACTION_CONTINUE: if the action triggered by the Falco Rule allows to continue or not
FALCO-TALON_RULE_ACTION_IGNORE_ERRORS: if the action triggered by the Falco Rule ignores the errors or not
FALCO-TALON_RULE_ACTION_PARAMETERS: a json payload with parameters of the action triggered by the Falco Rule
FALCO-TALON_RULE_ACTIONNER: the actionner used by the action triggered by the Falco Rule

Moreover, some actionners allow also to specify extra sources of information.

Other sources (optionnal)

AWS

For injecting some informations retrieved from AWS IMDS, use the source: aws (lower case).

In the context section of the payload:

    "context": {
        "aws.intance.profile": "myprofile",
        "aws.instance.profile.id": "myprofileid",
        "aws.region": "us-east-1",
    }

As env vars:

AWS_INSTANCE_PROFILE_ARN
AWS_INSTANCE_PROFILE_ID
AWS_REGION

k8snode

For injecting some informations retrieved from the node, use the source: k8snode.

In the context section of the payload:

    "context": {
        "node.hostname": "hostname",
        "node.instancetype": "instancetype",
        "node.role": "worker",
        "node.topology.zone": "zonea",
        "node.topology.region": "region",
        "node.spec.providedid": "id",
    }

As env vars:

NODE_HOSTNAME
NODE_INSTANCETYPE
NODE_ROLE
NODE_TOPOLOGY_ZONE
NODE_TOPOLOGY_REGION
NODE_SPEC_PROVIDEDID