Falco Talon is currently under active development and remains in the alpha stage, therefore, breaking changes may occur at any time, and the documentation may not always be up to date.

What is the Falco Talon project?

Falco Talon is a Response Engine for managing threats in Kubernetes clusters. It enhances the solutions proposed by the Falco community with a no-code tailor-made solution. With easy rules, you can react to events from Falco in milliseconds.

Why having created Falco Talon?

Over the years, the Falco community proposed different methods to react to the Falco Events, what we call a response engine. All these methods rely on a 3rd party FaaS (Function as a Service) and come with drawbacks:

all actions must be developped by the users to manage:
- the errors
- the Falco event format
- the authentication
- the K8s SDK complexity
- the security
- the upgrades of the deps
latency
complexity to manage sequential actions
intrication between the function and its configuration

This is why we started to develop a custom solution specifically built for Falco: Falco Talon.

Tailor made for the Falco events
No-code implementation for end-users
UX close to Falco with the rules (yaml files with append, override mechanisms)
Allow to set up sequential actions to run
Structured logs (with a trace id)
An official Helm chart for the deployment in K8s

The match for the rule can be based on the:

Falco rule name (=)
priority (=, >=)
tags (=)
output fields (=, !=)

What is it good for?:

React in real-time to the Falco Events
Allow fine granularity to match the events to react to
Responding to default rules with specific overrides

What is it not good for?:

Complex reaction worflows with conditions between the steps

What is it not yet good for?

See this issue on Github to know more about the upcoming features.

Where should I go next?

Start by learning the Concepts.

2 - Concepts

Understand the concepts of Falco Talon

Why we created Talon

Custom-designed for immediate response to Falco events.
Implement response actions without coding.
User experience aligned with Falco, utilizing YAML for rule customization.
Enables configuration of action sequences triggered by Falco rules.
Provides structured logging complete with trace identification.
Simplified deployment through Helm charts.
Actions can be triggered on the below Falco criteria matches:
- rule name (=)
- priority (=, >=)
- tags (=)
- output fields (=, !=)

Architecture

Falco Talon can receive the events from Falco or Falcosidekick:

┌──────────┐      ┌───────────────┐      ┌─────────────┐
│  Falco   ├──────► Falcosidekick ├──────► Falco Talon │
└──────────┘      └───────────────┘      └─────────────┘
or
┌──────────┐      ┌─────────────┐
│  Falco   ├──────► Falco Talon │
└──────────┘      └─────────────┘

Keywords

Event

Represents a possible threat or suspicious action detected by Falco and forwarded to its outputs (file, http, program, stdout).

For example:

Rule

The rule define the criteria for linking the events with the actions to run.

See here to know more.

Action

Each rule can sequentially run actions, each action refers to an actionner to know what to do.

See here to know more.

Actionner

It defines what the action will do.

For example:

See here to know more.

Notifier

It defines what outputs to notify with the result of the action.

See here to know more.

Output

Some actionners allow or require an output section. The output is the where target to store the resulting artifact that might has been created by the actionner. For example, the actionner kubernetes:log just allows to set an output to store the collected logs, if nothing is set, then they are printed in the stdout inside the log line; the kubernetes:download on its side requires an output to store the downloaded file from the pod.

See here to know more.

Context

The context is composed of elements from the original Falco event, from Falco Talon and other sources, that can be used to dynamically configure the actions. Some actionners allow also to specify extra sources of information.

See here to know more.

Deduplication

Falco Talon is able to de-duplicate the received events from Falco. It may happen Falco triggers the same rule multiple times for the same origin action (eg: change of thread.id) and Falco Talon can de-duplicate these events to avoid to run several times the same action.

The de-deduplication function can also work in a multi pods in Kubernetes context, Falco Talon will create a lease to elect a leader that will aggregate all events from the other Falco Talon pods. In case of any issue, a new leader is automatically elected.

See here for the settings.

3 - Configuration

Configuration file

Configuration

The static configuration of Falco Talon is set with a .yaml file (default: ./config.yaml) or with environment variables.

Setting	Env var	Default	Description
`listen_address`	`LISTEN_ADDRESS`	`0.0.0.0`	Listten Address
`listen_port`	`LISTEN_PORT`	`2803`	Listten Port
`rules_files`	`RULES_FILES`	n/a	File with rules
`watch_rules`	`WATCH_RULES`	`true`	Reload rules if they change
`print_all_events`	`PRINT_ALL_EVENTS`	`true`	Print in logs all received events, not only those which matches
`kubeconfig`	`KUBECONFIG`	n/a	Kube config file, only if `Falco Talon` runs outside Kubernetes
`log_format`	`LOG_FORMAT`	`color`	Log Format: text, color, json
`otel.traces_enabled`	`OTEL_TRACES_ENABLED`	`false`	Enable traces
`otel.metrics_enabled`	`OTEL_METRICS_ENABLED`	`false`	Enable metrics
`otel.collector_endpoint`	`OTEL_COLLECTOR_ENDPOINT`	`localhost`	Listen address of the OTEL Collector
`otel.collector_port`	`OTEL_COLLECTOR_PORT`	`localhost`	Listen port of the OTEL Collector
`otel.use_insecure_grpc`	`OTEL_USE_INSECURE_GRPC`	`false`	Enable insecure gRPC connection
`otel.timeout`	`OTEL_TIMEOUT`	`10`	Timeout in seconds
`deduplication.leader_election`	`DEDUPLICATION_LEADER_ELECTION`	`true`	enable the leader election for cluster mode (in k8s only)
`deduplication.time_window_seconds`	`DEDUPLICATION_TIME_WINDOW_SECONDS`	`5`	Duration in seconds for the deduplication time window
`default_notifiers`	`DEFAULT_NOTIFIERS`	n/a	List of `notifiers` which are enabled for all rules
`notifiers_x`	`NOTIFIERS_X`	n/a	List of `notifiers` with their settings
`aws.role_arn`	`AWS_ROLE_ARN`	n/a	AWS Role ARN to use with AWS actions
`aws.external_id`	`AWS_ROLE_EXTERNAL_ID`	n/a	AWS External ID used to assume roles with AWS actions. This field is ignored if aws.role_arn is not set
`aws.region`	`AWS_REGION`	n/a	AWS Region to use, it should be specified along aws.access_key and aws.secret_key
`aws.access_key`	`AWS_ACCESS_KEY`	n/a	AWS Access Key to use, it should be specified along aws.region and aws.secret_key
`aws.secret_key`	`AWS_SECRET_KEY`	n/a	AWS Secret Key to use, it should be specified along aws.region and aws.access_key
`minio.endpoint`	`MINIO_ENDPOINT`	n/a	Minio endpoint address
`minio.access_key`	`MINIO_ACCESS_KEY`	n/a	Access Key to use, it should be specified along minio.secret_key
`minio.secret_key`	`MINIO_SECRET_KEY`	n/a	Secret Key to use, it should be specified along minio.access_key
`minio.use_ssl`	`MINIO_USE_SSL`	`false`	Use SSL

Example

listen_address: "0.0.0.0" # default: "0.0.0.0"
listen_port: "2803" # default: "2803"
rules_file:
  - "./rules.yaml" # default: "./rules.yaml"
# kubeConfig: "~/.kube/config" # only if Falco Talon is running outside Kubernetes
log_format: "color" # log format: text, color, json (default: color)
watch_rules: true # reload if the rules file changes (default: true)
print_all_events: true # print in logs all received events, not only those which match

otel: # OTEL
  traces_enabled: true # enable the traces
  metrics_enabled: true # enables the metrics
  collector_endpoint: localhost # listen address of the OTEL Collector
  collector_port: 4317 # listen port of the OTEL Collector
  collector_use_insecure_grpc: false # enable insecure gRPC connection
  timeout: 10 # timeout in seconds

deduplication:
  leader_election: true # enable the leader election for cluster mode (in k8s only)
  time_window_seconds: 5 # duration in seconds for the deduplication time window (default: 5)

default_notifiers: # these notifiers will be enabled for all rules
  - k8sevents

aws:
  role_arn: arn:aws:iam::<account_number>:role/<role_name> # role to assume
  external_id: <external_id> # external id
  region: <region> # if not specified, default region from provider credential chain will be used
  access_key: <access_key> # if not specified, default access_key from provider credential chain will be used
  secret_key: <secret_key> # if not specified, default secret_key from provider credential chain will be used

minio:
  endpoint: <endpoint> # endpoint
  access_key: <access_key> # access key
  secret_key: <secret_key> # secret key
  use_ssl: false # use SSL

notifiers:
  slack:
    webhook_url: "https://hooks.slack.com/services/XXXX" # Slack webhook
    icon: "" # default: "https://upload.wikimedia.org/wikipedia/commons/2/26/Circaetus_gallicus_claw.jpg"
    username: "" # default: "Falco Talon"
    footer: "" # default: "https://github.com/falco-talon/falco-talon"
    format: long # default: long
  webhook:
    url: "" # address of the webhook endpoint
  smtp:
    host_port: "" # host:port of the SMTP server
    from: "" # from header
    to: "" # to
    user: "" # user
    password: "" # password
    format: "html" # format: html or text

See here for the settings of the notifers.

4 - Installation and Usage

How to install and use Falco Talon

4.1 - Usage

How to use Falco Talon

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])

4.2 - Connect Falcosidekick to Falco Talon

How to receive the Falco Events from Falcosidekick

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

4.3 - Installation from the sources

How to install Falco Talon locally from the sources

Todo

4.4 - Installation in k8s with Helm

How to install Falco Talon in Kubernetes with Helm

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

4.5 - Metrics

Metrics

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

4.6 - Traces

Traces

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

images/traces_grafana.png

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

5 - Rules

The rules define the mapping between the Falco events and the actions to run

Info

The rules are evaluated from top to bottom.

Multiple rules files can be used (repeat the -r flag), the first file is overriden by the following ones (strings are replaced, lists are appended, …).

Info

If the setting watch_rules is set to true, Falco Talon watches the rules updates and automatically hot reloads them.

Syntax

The syntax for the rules files is:

- action: <string,required>
  description: <string>
  actionner: <string,required>
  continue: <bool>
  ignore_errors: <bool>
  parameters:
    <string>: <string>
    <string>:
      - <string>
      - <string>
    <string>:
      <string>: <string>
      <string>: <string>

- rule: <string,required>
  description: <string>
  match:
    rules:
      - <string>
      - <string>
    priority: <string>
    tags:
      - <string>, <string>, <string>
      - <string>, <string>
    output_fields:
      - <string>=<string>, <string>=<string>
      - <string>!=<string>, <string>=<string>
  continue: <bool>
  dry_run: <bool>
  actions:
    - action: <string,required>
    - action: <string,required>
      description: <string>
      actionner: <string,required>
      continue: <bool>
      ignore_errors: <bool>
      parameters:
        <string>: <any>
        <string>:
          - <any>
          - <any>
        <string>:
          <string>: <any>
          <string>: <any>
      output:
        target: <string,required>
        parameters:
          <string>: <any>
          <string>: <any>
  notifiers:
    - <string>
    - <string>

The rules files contain 2 types of blocks:

action: defines an action that can be reused by different rules
rule: defines a rule to match with events and run actions

Action

For the action block, the settings are:

action: (required) name of action to trigger
description: description of the action (for user only)
actionner: name of the actionner to use
continue: if true, no more action are applied after this one (each actionner has its own default value)
ignore_errors: if true, ignore the errors and avoid to stop at this action.
parameters: key:value map of parameters for the action. value can be a string, an array (slice) or a map
output: defines where to store the artifact that might have been created/downloaded by the actionner
- target: the name of the target used as output
- parameters: key:value map of parameters for the output. value can be a string, an array (slice) or a map

Rule

For the rule block, the settings are:

rule: (required) Name of your rule
description: description of the action (for user only)
match: the section to define the criterias to match
- rules: (list) (OR logic) Falco rules to match. If empty, all rules match.
- priority: Priority to match. If empty, all priorities match. Syntax is like: >=Critical, <Warning, Debug
- tags: (list) (OR logic) Comma separated lists of Tags to match (AND logic). If empty, all tags match.
- output_fields: (list) (OR logic) Comma separated lists of key:comparison:value for Output fields to match (AND logic). If emtpy, all output fields match
actions: the list of actions to sequentially run, they can refer to an action block or be defined locally
- action: (required) name of action to trigger, can refer to an action block
- description: description of the action (for user only)
- actionner: name of the actionner to use
- continue: if true, no more action are applied after this one (each actionner has its own default value)
- ignore_errors: if true, ignore the errors and avoid to stop at this action
- parameters: key:value map of parameters for the action. value can be a string, an array (slice) or a map
- output: defines where to store the artifact that might have been created/downloaded by the actionner
  - target: the name of the target used as output
  - parameters: key:value map of parameters for the output. value can be a string, an array (slice) or a map
continue: if true, no more rule are compared after the rule has been triggered (default is true)
dry_run: if true: the actions are not ran (default: false)
notifiers: list of notifiers to enabled for the action, in addition with the defaults

Example

In the below YAML manifest, we can see two different Talon actions - Terminate Pod and Disable outbound connections.

The Terminate Pod action has a matching actionner to gracefully terminate a running workload with kubernetes:terminate.
The Disable outbound connections action enforces a Kubernetes NetworkPolicy through kubernetes:networkpolicy.

Finally, the two actions are initiated as instant response actions when the matching Falco rule Unexpected outbound connection destination is triggered.

- action: Terminate Pod
  description: terminate the pod if it doesn't belong to a statefulset
  actionner: kubernetes:terminate
  parameters:
    ignoreDaemonsets: false
    ignoreStatefulsets: true

- action: Disable outbound connections
  actionner: kubernetes:networkpolicy
  parameters:
    allow:
      - "192.168.1.0/24"
      - "172.17.0.0/16"
      - "10.0.0.0/32"

- rule: Suspicious outbound connection
  description: Block suspicious outbound connections and terminate the pod
  match:
    rules:
      - Unexpected outbound connection destination
  actions:
    - action: Get last logs
      actionner: kubernetes:log
      parameters:
        tail_lines: 10
      output:
        target: aws:s3
        parameters:
          bucket: my-bucket
          prefix: /logs/
    - action: Disable outbound connections
      ignore_errors: true
    - action: Terminate Pod # ref to a re-usable action
      parameters:
        gracePeriods: 2

6 - Actionners

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

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

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

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

7 - Notifiers

Notifiers are the built-it outputs to forward the result of the Falco Talon actions

The Notifiers define which outputs to notify with the result of the actions.

The configuration file contains the list of notifiers to enable by default and the settings for each notifier.

Example:

default_notifiers: # these notifiers will be enabled for all rules
  - k8sevents
  - loki
  - smtp
  - elasticsearch

notifiers:
  loki:
    host_port: https://logs-prod-eu-west-0.grafana.net
    user: 99999
    api_key: xxxxx
  smtp:
    host_port: localhost:1025
    from: falco@falcosecurity.org
    to: user@test.com, other@test.com
    # user: test
    # password: test
    format: html
    tls: false
  elasticsearch:
    url: http://localhost:9200
    create_index_template: true
    number_of_shards: 1
    number_of_replicas: 1

7.1 - List of Notifiers

Available notifiers

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

images/slack_short.png

with format: long:

images/slack_long.png

`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

images/loki_grafana.png

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:

./images/smtp_html.png

with format: text:

images/smtp_text.png

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

8 - Outputs

Outputs are the targets where to store the artifacts generated by some actionners

Some actionners allow or require an output section. The output is the target where to store the resulting artifact that might has been created by the actionner.

For example:

the actionner kubernetes:log just allows to set an output to store the collected logs, if nothing is set, then they are printed in the stdout inside the log line
the kubernetes:download requires an output to store the downloaded file from the pod.

The targets used by the Outputs as storage are named with the pattern category:service.

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

Warning

The clients/sessions used by some actionners and some outputs are the same, eg: aws:lambda (actionner) and aws:s3 (output). This is why the category is the same, it avoids multiple initializations.

8.1 - List of Outputs

Available outputs

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

9 - Reference

Reference

Todo

10 - Contribution Guidelines

How to contribute to the docs

These basic sample guidelines assume that your Docsy site is deployed using Netlify and your files are stored in GitHub. You can use the guidelines “as is” or adapt them with your own instructions: for example, other deployment options, information about your doc project’s file structure, project-specific review guidelines, versioning guidelines, or any other information your users might find useful when updating your site. Kubeflow has a great example.

Don’t forget to link to your own doc repo rather than our example site! Also make sure users can find these guidelines from your doc repo README: either add them there and link to them from this page, add them here and link to them from the README, or include them in both locations.

We use Hugo to format and generate our website, the Docsy theme for styling and site structure, and Netlify to manage the deployment of the site. Hugo is an open-source static site generator that provides us with templates, content organisation in a standard directory structure, and a website generation engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Quick start with Netlify

Here’s a quick guide to updating the docs. It assumes you’re familiar with the GitHub workflow and you’re happy to use the automated preview of your doc updates:

Fork the Goldydocs repo on GitHub.
Make your changes and send a pull request (PR).
If you’re not yet ready for a review, add “WIP” to the PR name to indicate it’s a work in progress. (Don’t add the Hugo property “draft = true” to the page front matter, because that prevents the auto-deployment of the content preview described in the next point.)
Wait for the automated PR workflow to do some checks. When it’s ready, you should see a comment like this: deploy/netlify — Deploy preview ready!
Click Details to the right of “Deploy preview ready” to see a preview of your updates.
Continue updating your doc and pushing your changes until you’re happy with the content.
When you’re ready for a review, add a comment to the PR, and remove any “WIP” markers.

Updating a single page

If you’ve just spotted something you’d like to change while using the docs, Docsy has a shortcut for you:

Click Edit this page in the top right hand corner of the page.
If you don’t already have an up to date fork of the project repo, you are prompted to get one - click Fork this repository and propose changes or Update your Fork to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
Follow the rest of the Quick start with Netlify process above to make, preview, and propose your changes.

Previewing your changes locally

If you want to run your own local Hugo server to preview your changes as you work:

Follow the instructions in Getting started to install Hugo and any other tools you need. You’ll need at least Hugo version 0.45 (we recommend using the most recent available version), and it must be the extended version, which supports SCSS.
Fork the Goldydocs repo repo into your own project, then create a local copy using git clone. Don’t forget to use --recurse-submodules or you won’t pull down some of the code you need to generate a working site.
```
git clone --recurse-submodules --depth 1 https://github.com/google/docsy-example.git
```
Run hugo server in the site root directory. By default your site will be available at http://localhost:1313/. Now that you’re serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.
Continue with the usual GitHub workflow to edit files, commit them, push the changes up to your fork, and create a pull request.

Creating an issue

If you’ve found a problem in the docs, but you’re not sure how to fix it yourself, please create an issue in the Goldydocs repo. You can also create an issue about a specific page by clicking the Create Issue button in the top right hand corner of the page.

Useful resources

Docsy user guide: All about Docsy, including how it manages navigation, look and feel, and multi-language support.
Hugo documentation: Comprehensive reference for Hugo.
Github Hello World!: A basic introduction to GitHub concepts and workflow.