Falco Talon – Documentation

Docs: Usage

Mon, 01 Jan 0001 00:00:00 +0000

Falco Talon can also be used as a CLI to help you to manage your rules by checking their validities (useful in a CI), printing the result of their merges or by listing the available actionners, outputs and notifiers.

$ falco-talon --help

Falco Talon is a Response Engine for managing threats in Kubernetes
It enhances the solutions proposed by Falco community with a dedicated,
no-code solution. With easy rules, you can perform actions over compromised pods.

Usage:
 falco-talon [command]

Available Commands:
 actionners Manage the actionners
 completion Generate the autocompletion script for the specified shell
 help Help about any command
 notifiers Manage the Notifiers
 outputs Manage the Outputs
 rules Manage Falco Talon rules
 server Start Falco Talon server
 version Print version of Falco Talon.

Flags:
 -c, --config string Falco Talon Config File (default "/etc/falco-talon/config.yaml")
 -h, --help help for falco-talon
 -r, --rules stringArray Falco Talon Rules File (default [/etc/falco-talon/rules.yaml])

Use "falco-talon [command] --help" for more information about a command.

Start the server listening the events

$ falco-talon server --help
Start Falco Talon

Usage:
 falco-talon server [flags]

Flags:
 -h, --help help for server

Global Flags:
 -c, --config string Falco Talon Config File (default "/etc/falco-talon/config.yaml")
 -r, --rules stringArray Falco Talon Rules File (default [/etc/falco-talon/rules.yaml])

Manage the rules

$ falco-talon rules --help

Manage the rules loaded by Falco Talon. You can print them in the stdout or check their validity.

Usage:
 falco-talon rules [command]

Available Commands:
 check Check Falco Talon Rules file
 print Print the loaded by Falco Talon in the stdout

Flags:
 -h, --help help for rules

Global Flags:
 -c, --config string Falco Talon Config File (default "/etc/falco-talon/config.yaml")
 -r, --rules stringArray Falco Talon Rules File (default [/etc/falco-talon/rules.yaml])

Use "falco-talon rules [command] --help" for more information about a command.

Check the validity of the rules

$ falco-talon rules check --help
Check Falco Talon Rules file

Usage:
 falco-talon rules check [flags]

Flags:
 -h, --help help for check

Global Flags:
 -c, --config string Falco Talon Config File (default "/etc/falco-talon/config.yaml")
 -r, --rules stringArray Falco Talon Rules File (default [/etc/falco-talon/rules.yaml])

Examples

$ falco-talon rules check -r rules.yaml -r rules_override.yaml

2024-09-03T16:03:51+02:00 INF rules result="rules file valid"

falco-talon rules check -r rules.yaml -r rules_override.yaml

2024-09-03T16:04:53+02:00 ERR rules error="unknown actionner" action="Tests" actionner=kubernetes:wrong rule="Test bad actionner"
2024-09-03T16:04:53+02:00 FTL rules error="invalid rules"

Print the result of the merge of the rules files

$ falco-talon rules print --help

Print the result of the merge of the rules files by Falco Talon in the stdout.

Usage:
 falco-talon rules print [flags]

Flags:
 -h, --help help for print

Global Flags:
 -c, --config string Falco Talon Config File (default "/etc/falco-talon/config.yaml")
 -r, --rules stringArray Falco Talon Rules File (default [/etc/falco-talon/rules.yaml])

Lists

List the available actionners

$ falco-talon actionners list --help

List the available Actionners.

Usage:
 falco-talon actionners list [flags]

Flags:
 -h, --help help for list

Global Flags:
 -c, --config string Falco Talon Config File (default "/etc/falco-talon/config.yaml")
 -r, --rules stringArray Falco Talon Rules File (default [/etc/falco-talon/rules.yaml])

List the available outputs

$ falco-talon outputs list --help

List the available Outputs.

Usage:
 falco-talon outputs list [flags]

Flags:
 -h, --help help for list

Global Flags:
 -c, --config string Falco Talon Config File (default "/etc/falco-talon/config.yaml")
 -r, --rules stringArray Falco Talon Rules File (default [/etc/falco-talon/rules.yaml])

List the available notifiers

$ falco-talon notifiers list --help

List the available Notifiers.

Usage:
 falco-talon notifiers list [flags]

Flags:
 -h, --help help for list

Global Flags:
 -c, --config string Falco Talon Config File (default "/etc/falco-talon/config.yaml")
 -r, --rules stringArray Falco Talon Rules File (default [/etc/falco-talon/rules.yaml])

Docs: List of Actionners

Mon, 01 Jan 0001 00:00:00 +0000

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. (default: 0)
ignore_daemonsets: If true, the pods which belong to a Daemonset are not terminated. (default: false)
ignore_statefulsets: If true, the pods which belong to a Statefulset are not terminated. (default: false)
ignore_standalone_pods: If true, standalone pods (not belonging to any controller) are not terminated. (default: false)
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) (default: 0.0.0.0/0)
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. (default: false)
ignore_statefulsets: If true, the pods which belong to a Statefulset are not terminated. (default: false)
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. (default: false)
max_wait_period: Amount of time to wait for eviction. If not set, the actionner will immediately return after calling the API for eviction. (default: 0)
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

`kubernetes:sysdig`

Name: sydig
Category: kubernetes
Description: Capture the syscalls packets in a pod
Continue: true
Required fields:
- k8s.pod.name
- k8s.ns.name
Use context: false
Output: n/a
Source: syscalls, k8s_audit

Parameters

buffer_size: Size of the buffer to record for each event (default: 2048)
duration: Duration of the capture in seconds (default: 5)
image: Image to use (default: image/sysdig:latest)
scope: Scope of the capture, node ou pod (default)

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
 - apiGroups:
 - "batch"
 resources:
 - jobs
 verbs:
 - get
 - list
 - create

Example

- action: Capture the syscalls
 actionner: kubernetes:sysdig
 parameters:
 buffer_size: 2048
 duration: 20
 image: issif/sysdig:latest
 scope: pod
 output:
 target: aws:s3
 parameters:
 bucket: my-bucket
 prefix: /captures/

`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.

Docs: List of Notifiers

Mon, 01 Jan 0001 00:00:00 +0000

`k8sevents`

This notifiers creates a k8s event in the target resource namespace.

Parameters

No configuration is requested.

Permissions

- apiGroups:
 - ""
 resources:
 - events
 verbs:
 - get
 - update
 - patch
 - create

Result

LAST SEEN TYPE REASON OBJECT MESSAGE
18s Normal falco-talon:kubernetes:label:success pod/cncf-55696bc998-ql5qd Status: success...

action: kubernetes:label
apiVersion: v1
eventTime: "2024-02-27T13:54:30.008721Z"
firstTimestamp: null
involvedObject:
 kind: Pod
 name: cncf-55696bc998-ql5qd
 namespace: default
kind: Event
lastTimestamp: null
message: "Status: success\nMessage: action\nRule: Terminal shell in container\nAction:
 Label Pod as Suspicious\nActionner: kubernetes:label\nEvent: A shell was spawned
 in a container with an attached terminal (evt_type=execve user=root user_uid=0 user_loginuid=-1
 process=sh proc_exepath=/usr/bin/dash parent=runc command=sh -c command -v bash
 >/dev/null && exec bash || exec sh terminal=34817 exe_flags=EXE_WRITABLE container_id=f13c72275fd4
 container_image=docker.io/library/debian container_image_tag=latest container_name=cncf
 k8s_ns=default k8s_pod_name=cncf-55696bc998-ql5qd)\nnamespace: default\npod: cncf-55696bc998-ql5qd\nOutput:
 \nthe pod \"cncf-55696bc998-ql5qd\" in the namespace \"default\" has been labelled\nTraceID:
 cc84de57-7617-4359-ad40-1a7a8d854743\n"
metadata:
 creationTimestamp: "2024-02-27T13:54:30Z"
 generateName: falco-talon-
 name: falco-talon-rf2dz
 namespace: default
 resourceVersion: "32141229"
 uid: a407b246-f2b5-46ba-8146-ebe474302604
reason: falco-talon:kubernetes:label:success
reportingComponent: falcosecurity.org/falco-talon
reportingInstance: falco-talon
source:
 component: falco-talon
type: Normal

`slack`

Parameters

Setting	Default	Description
`webhook_url`	n/a	Webhook URL
`icon`	`https://upload.wikimedia.org/wikipedia/commons/2/26/Circaetus_gallicus_claw.jpg`	Avatar for messages
`username`	`Falco Talon`	Username for messages
`footer`	`https://github.com/Issif/falco-talon`	Footer for messages
`format`	`long`	Format for messages (`long	short`)

Example

notifiers:
 slack:
 webhook_url: "https://hooks.slack.com/services/XXXX"
 icon: "https://upload.wikimedia.org/wikipedia/commons/2/26/Circaetus_gallicus_claw.jpg"
 username: "Falco Talon"
 footer: "https://github.com/Falco-Talon/falco-talon"
 format: long

Results

with format: short:

with format: long:

`loki`

Parameters

Setting	Default	Description
`url`	n/a	http://{domain or ip}:{port}
`user`	n/a	User for Grafana Logs
`api_key`	n/a	API Key for Grafana Logs
`tenant`	n/a	Add the Tenant header
`custom_headers`	n/a	Custom HTTP Headers

Example

notifiers:
 loki:
 host_port: "https://xxxxx"
 user: "xxxx"
 api_key: "xxxxx"

Result

Elasticsearch

Parameters

Setting	Default	Description
`host_port`	n/a	http://{domain or ip}:{port}
`user`	n/a	User
`password`	n/a	Password
`index`	`falco-talon`	Elasticsearch index
`suffix`	`daily`	Date suffix for index rotation : `daily` (default), `monthly`, `annually`, `none`
`create_index_template`	`true`	Create the index template at the init if it doesn’t exist
`number_of_shards`	`3`	Number of shards for the index (if `create_index_template` is `true`)
`number_of_replicas`	`3`	Number of replicas for the index (if `create_index_template` is `true`)
`custom_headers`	n/a	Custom HTTP Headers

Example

notifiers:
 elasticsearch:
 url: "http://localhost:9200"
 create_index_template: true
 number_of_shards: 1
 number_of_replicas: 1

`smtp`

Parameters

Setting	Default	Description
`host_port`	n/a	Host:Port of SMTP server
`user`	n/a	User for SMTP
`password`	n/a	Password for SMTP
`from`	n/a	From
`to`	n/a	To (comma separated list of adresses)
`format`	`html`	Format of the email (`text`, `html`)
`tls`	`false`	Use TLS connection

Example

notifiers:
 smtp:
 host_port: "localhost:1025"
 from: "falco@falcosecurity.org"
 to: "user@test.com, other@test.com"
 user: "xxxx"
 password: "xxxxx"
 format: "html"
 tls: false

Results

with format: html:

with format: text:

`webhook`

Parameters

Setting	Default	Description
`url`	n/a	URL
`http_method`	`POST`	HTTP Method
`user_agent`	`Falco-Talon`	User Agent
`content_type`	`application/json; charset=utf-8`	Content Type
`custom_headers`	n/a	Custom HTTP Headers

Example

notifiers:
 webhook:
 url: "http://xxxx"
 http_method: "POST"
 user_agent: "Falco-Talon"
 content_type: "application/json; charset=utf-8"
 custom_headers:
 Authorization: "Bearer xxxxx"

Docs: List of Outputs

Mon, 01 Jan 0001 00:00:00 +0000

The name of the output has to be used as value for the target field of the output section of the action.

`local:file`

Name: file
Category: local
Description: Store on local filesystem

Parameters

destination: (required) Destination folder for the file

Example

- action: Get logs of the pod
 actionner: kubernetes:download
 parameters:
 tail_lines: 200
 output:
 target: local:file
 parameters:
 destination: /var/logs/falco-talon/

`aws:s3`

Name: s3
Category: aws
Description: Store on AWS S3

Parameters

bucket: (required) Destination bucket
prefix: Prefix for the key
region: Region of the bucket

Permissions

{
 "Id": "Policy1724925555994",
 "Version": "2012-10-17",
 "Statement": [
 {
 "Sid": "Stmt1724925537082",
 "Action": [
 "s3:PutObject",
 "s3:PutObjectAcl"
 ],
 "Effect": "Allow",
 "Resource": [
 "arn:aws:s3:::${BucketName}/",
 "arn:aws:s3:::${BucketName}/*"
 ]
 }
 ]
}

Example

- action: Get logs of the pod
 actionner: kubernetes:download
 parameters:
 tail_lines: 200
 output:
 target: aws:s3
 parameters:
 bucket: falco-talon
 prefix: files
 region: eu-west-1

`gcp:gcs`

Name: gcs
Category: gcp
Description: Store on Google Cloud Storage

Parameters

bucket: (required) Destination bucket
prefix: Prefix for the object

Permissions

storage.objects.create
storage.objects.get
storage.objects.list
storage.objects.update

Example

- action: Get logs of the pod
 actionner: kubernetes:download
 parameters:
 tail_lines: 200
 output:
 target: gcp:gcs
 parameters:
 bucket: falco-talon
 prefix: files

`minio:s3`

Name: s3
Category: minio
Description: Store on Minio

Parameters

bucket: (required) Destination bucket
prefix: Prefix for the key

Example

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

Docs: Contexts

Mon, 01 Jan 0001 00:00:00 +0000

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

Docs: Connect Falcosidekick to Falco Talon

Mon, 01 Jan 0001 00:00:00 +0000

Once you have installed Falco Talon with Helm in the falco namespace, you have to connect Falcosidekick by adding the flag --set falcosidekick.config.talon.address=http://falco-talon:2803

helm install falco falcosecurity/falco --namespace falco \
 --create-namespace \
 --set tty=true \
 --set falcosidekick.enabled=true \
 --set falcosidekick.config.talon.address=http://falco-talon:2803

Docs: Installation from the sources

Mon, 01 Jan 0001 00:00:00 +0000

Todo

Docs: Installation in k8s with Helm

Mon, 01 Jan 0001 00:00:00 +0000

Helm

The helm chart is available on the official falcosecurity/charts repository. Two main config files are provided:

values.yaml allows you to configure the static settings of Falcon Talon and its deployment
rules.yaml contains the rules to set

Info

If your values.yaml contains watchRules: true, the changes in the rules are detected and the Falco Talon pods will automatically reload their configuration.

Install

To install Falco Talon, first add the chart repository:

helm repo add falcosecurity https://falcosecurity.github.io/charts

In case you already have the remote repository configured, updated it:

helm repo update falcosecurity

Now, just deploy falcosecurity/falco-talon chart:

helm upgrade --install falco-talon falcosecurity/falco-talon

After deploying, you can check if pods are running properly:

kubectl get pods -n <namespace> | grep falco-talon

Installing as a Falco sub-dependency

To install Talon as a Falco sub-dependency like Sidekick, simply change your Falco values.yaml:

responseActions:
 enabled: true

falco-talon:
 ## example configuration with rulesOverride
 config:
 rulesOverride: |
 - action: Terminate Pod
 actionner: kubernetes:terminate
 parameters:
 ignore_daemonsets: true
 ignore_statefulsets: true
 grace_period_seconds: 20
 - rule: Terminal shell in container
 description: >
 Label the pod outside kube-system and falco namespaces if a shell is started inside
 match:
 rules:
 - Terminal shell in container
 output_fields:
 - k8s.ns.name!=kube-system, k8s.ns.name!=falco
 actions:
 - action: Terminate Pod

OBS: This requires version 6.0.0 at least of Falco chart.

Docs: Metrics

Mon, 01 Jan 0001 00:00:00 +0000

Prometheus metrics

Falco Talon exposes a /metrics endpoint with some metrics in the Prometheus format.

# HELP action_total number of actions
# TYPE action_total counter
action_total{action="Disable outbound connections",actionner="kubernetes:networkpolicy",event="Test logs",namespace="falco",otel_scope_name="github.com/Falco-Talon/falco-talon",otel_scope_version="devel",pod="falco-5b7kc",rule="Suspicious outbound connection",status="failure"} 6
action_total{action="Terminate Pod",actionner="kubernetes:terminate",event="Test logs",namespace="falco",otel_scope_name="github.com/Falco-Talon/falco-talon",otel_scope_version="devel",pod="falco-5b7kc",rule="Suspicious outbound connection",status="failure"} 6
# HELP event_total number of received events
# TYPE event_total counter
event_total{event="Unexpected outbound connection destination",otel_scope_name="github.com/Falco-Talon/falco-talon",otel_scope_version="devel",priority="Critical",source="syscalls"} 2
# HELP match_total number of matched events
# TYPE match_total counter
match_total{event="Unexpected outbound connection destination",otel_scope_name="github.com/Falco-Talon/falco-talon",otel_scope_version="devel",priority="Critical",rule="Suspicious outbound connection",source="syscalls"} 2

OTEL metrics

If you use OTEL Collector, you can configure Falco Talon to push its metrics to:

otel:
 metrics_enabled: true
 collector_port: 4317
 collector_endpoint: localhost
 collector_use_insecure_grpc: true
 timeout: 10

Docs: Traces

Mon, 01 Jan 0001 00:00:00 +0000

Falco Talon can export traces which are very useful to have observability over its performed actions.

You can enable the traces by enabling them in the config.yaml and setting the address and port of the OTEL collector.

otel:
 traces_enabled: true
 collector_port: 4317
 collector_endpoint: localhost
 collector_use_insecure_grpc: true
 timeout: 10

Information

A trace is emitted for every events received by Falco Talon, you can configure the OTEL Collector to do some tail sampling and only store the traces with actions.

...
processors:
 batch:
 tail_sampling:
 decision_wait: 1s
 num_traces: 200
 policies:
 [
 {
 name: ignore-unmatched,
 type: ottl_condition,
 ottl_condition: {
 error_mode: ignore,
 span: [
 "IsMatch(name, \"match\")"
 ]
 }
 }
 ]
service:
 pipelines:
 traces:
 ...
 processors: [tail_sampling, batch]
 ...
...