Skip to content

Commit

Permalink
docs(content): improve Alert Formatting and add suggested_output
Browse files Browse the repository at this point in the history 
Signed-off-by: Leonardo Grasso <me@leonardograsso.com>
  • Loading branch information
@leogr @poiana
leogr authored and poiana committed Jan 28, 2025
1 parent 5216fcb commit db59696
Showing 1 changed file with 82 additions and 45 deletions.
127 changes: 82 additions & 45 deletions content/en/docs/concepts/outputs/formatting.md
View file
Original file line number Diff line number Diff line change
@@ -1,25 +1,25 @@
---
title: Alters Formatting
description: Learn how to format and customize Falco Alerts
title: Alert Formatting
description: Learn how to format and customize Falco alerts
linktitle: Formatting
aliases:
- ../../alerts/formatting
- ../../outputs/formatting
weight: 20
---

Previous guides introduced the [Output Fields of Falco Rules](/docs/rules/basic-elements/#output) and provided [Guidelines](/docs/rules/style-guide/#output-fields) on how to use them. This section specifically highlights additional global formatting options for your deployment, complementing the information previously provided.
Previous guides introduced the [Output Fields of Falco Rules](/docs/concepts/rules/basic-elements/#output) and provided [Guidelines](/docs/concepts/rules/style-guide/#output-fields) on how to use them. This section highlights additional global formatting options for your deployment, complementing the information previously provided.

Adding the same output field to multiple rules by editing the rule files manually can be tedious. Thankfully, Falco offers several ways to make it easier:
Adding the same output field to multiple rules by manually editing rule files can be tedious. Fortunately, Falco provides several ways to simplify this process:

* Using the `append_output` configuration option in `falco.yaml` to add output text or fields to a subset of loaded rules
* Adding an override to a specific rule to replace its output
- Using the `append_output` configuration option in `falco.yaml` to add output text or fields to a subset of loaded rules
- Adding an override to a specific rule to replace its output

## Appending extra output and fields with `append_output`
## Appending Extra Output and Fields with `append_output`

Since Falco 0.39.0, the `append_output` option can be specified in the `falco.yaml` configuration file and it can be used to add extra output to rules specified by source, tag, name or to all rules unconditionally. The `append_output` section is a list of append entries which are applied in order.
The `append_output` option can be specified in the `falco.yaml` configuration file. You can use it to add extra output to rules specified by source, tag, name, or to all rules unconditionally. The `append_output` section is a list of items that are applied in the order they appear.

Example:
**Example:**

```yaml
append_output:
Expand All @@ -31,100 +31,137 @@ append_output:
- evt.hostname
```
In the example above, every rule with the `syscall` source will get `"on CPU %evt.cpu"` output appended at the end of the regular line and also gain additional fields only visible in the JSON output under the `output_fields` key which will not appear in the regular output. Environment variables are supported.
In this example:
The `match` section can be used to specify optional conditions:
- Every rule with the `syscall` source will have `on CPU %evt.cpu` appended at the end of the regular output line.
- The rule will also include the additional fields (`home_directory` and `evt.hostname`) in the JSON output under `output_fields`. These extra fields do not appear in the regular (text) output.
- Environment variables (like `$HOME`) expansion is supported in the configuration file, so for `extra_fields` as well.

* `source`: with `syscall` or plugin names
* `rule`: with a complete rule name
* `tags`: a list of tags that need to be all present in a rule in order to match
### Matching Rules

If multiple conditions are specified all need to be present in order to match. If none are specified or `match` is not present output is appended to all rules.
The `match` section allows you to filter which rules are modified:

This option can also be specified on the command line via `-o` such as:
- `source`: filters rules by source (e.g., `syscall` or plugin names)
- `rule`: filters by the complete rule name
- `tags`: filters by a list of tags (all listed tags must be present)

```sh
falco ... -o 'append_output[]={"match": {"source": "syscall"}, "extra_fields": ["evt.hostname"], "extra_output": "on CPU %evt.cpu"}'
```
If multiple conditions are specified under `match`, all must be met for the entry to apply. If no conditions are specified—or `match` is omitted—then the entry applies to all rules.

## Adding an override to a specific rule
## Adding an Override to a Specific Rule

Note that the `append_output` option allows to add output to a rule but not to remove or replace it. In order to do so you need to add another rule file, loaded in order after others, which contains [a replace override](/docs/rules/overriding/#append-and-replace-items-in-a-rule) for the output field, like in the example below:
Note that `append_output` only *adds* output to an existing rule; it does not remove or replace existing fields. To remove or replace output fields, you can add another rule file (loaded after the original) that uses an [override](/docs/rules/overriding/#append-and-replace-items-in-a-rule). For example:

```yaml
- rule: Read sensitive file trusted after startup
output: A file (user=%user.name command=%proc.cmdline file=%fd.name) was read after startup
override:
override:
output: replace
```

## Example Rule
### Suggested Output Fields

By default, Falco can also include "suggested" fields from plugins implementing the extraction capabilities. This is especially useful if certain plugins mark some fields as recommended for output. Those fields will appear automatically in your alerts.

Below is an example configuration entry that enables suggested output fields unconditionally for any source:

```yaml
append_output:
- suggested_output: true # Enable the use of extractor plugins' suggested fields for all matching sources.
```

When `suggested_output` is set to `true`, any extractor plugin that provides "suggested" fields will add them to the output in the form `plugin_field_name=$plugin.field`.

### Command-Line Usage

You can also specify this option on the command line via the `-o` flag, for example:

```bash
falco ... \
-o 'append_output[]={"match": {"source": "syscall"}, "extra_output": "on CPU %evt.cpu", "extra_fields": ["evt.hostname"]}'
```

## Example Rule and Various Scenarios

Consider the rule:

```yaml
- rule: Drop and execute new binary in container
desc: SKIPPED
condition:
condition: >
spawned_process
and container
and proc.is_exe_upper_layer=true
and proc.is_exe_upper_layer=true
and not container.image.repository in (known_drop_and_execute_containers)
output: Executing binary not part of base image (proc_sname=%proc.sname user=%user.name process=%proc.name proc_exepath=%proc.exepath parent=%proc.pname command=%proc.cmdline terminal=%proc.tty %container.info)
priority: CRITICAL
tags: [maturity_stable, container, process, mitre_persistence, TA0003, PCI_DSS_11.5.1]
```

*Scenario 1*
### Scenario 1

The rule outputs include `%container.info`, but Falco is started without any command line flags:
- The rule output includes `%container.info`.
- Falco is started without additional command-line flags:

```bash
sudo /usr/bin/falco -c /etc/falco/falco.yaml -r falco_rules_test.yaml
```bash
sudo /usr/bin/falco -c /etc/falco/falco.yaml -r falco_rules_test.yaml
```

In this case Falco will output `%container.id` and `%container.name` but no other container metadata will be displayed:
Output example:

```bash
03:00:45.104332605: Critical Executing binary not part of base image (proc_sname=bash user=root process=sleep proc_exepath=/tmp/sleep parent=bash command=sleep 10000 terminal=34816 container_id=0fdb3cd5b5fc container_name=optimistic_newton)
```

*Scenario 2*
By default, `%container.info` includes `%container.id` and `%container.name`, but no other container metadata is shown.

### Scenario 2

The rule outputs include `%container.info`, and Falco is started with the `-pc` flag:
- The rule output includes `%container.info`.
- Falco is started with the `-pc` flag:

```bash
sudo /usr/bin/falco -c /etc/falco/falco.yaml -r falco_rules_test.yaml -pc
```bash
sudo /usr/bin/falco -c /etc/falco/falco.yaml -r falco_rules_test.yaml -pc
```

The output includes the default container fields:
Output example:

```bash
03:02:52.019002207: Critical Executing binary not part of base image (proc_sname=bash user=root process=sleep proc_exepath=/tmp/sleep parent=bash command=sleep 10000 terminal=34816 container_id=0fdb3cd5b5fc container_image=ubuntu container_image_tag=latest container_name=optimistic_newton)
```

*Scenario 3*
Here, the default container fields (e.g., `%container.image`, `%container.image_tag`) are included.

The rule outputs include `%container.info`, and Falco is started with the `-pk` flag:
### Scenario 3

```bash
sudo /usr/bin/falco -c /etc/falco/falco.yaml -r falco_rules_test.yaml -pk
- The rule output includes `%container.info`.
- Falco is started with the `-pk` flag:

```bash
sudo /usr/bin/falco -c /etc/falco/falco.yaml -r falco_rules_test.yaml -pk
```

Output includes the default container fields and the default Kubernetes fields:
Output example:

```bash
03:03:23.573329751: Critical Executing binary not part of base image (proc_sname=bash user=root process=sleep proc_exepath=/tmp/sleep parent=bash command=sleep 10000 terminal=34816 container_id=0fdb3cd5b5fc container_image=ubuntu container_image_tag=latest container_name=optimistic_newton k8s_ns=my_ns k8s_pod_name=my_pod_name)
```

*Scenario 4*
In this case, the default container fields and Kubernetes fields are included.

### Scenario 4

The rule outputs include `%container.info`, and you run Falco with the `-p` flag while providing custom output fields:
- The rule output includes `%container.info`.
- Falco is started with the `-p` flag, providing custom output fields:

```bash
sudo /usr/bin/falco -c /etc/falco/falco.yaml -r falco_rules_test.yaml -p "k8s_pod_uid=%k8s.pod.uid proc_pexepath=%proc.pexepath"
```bash
sudo /usr/bin/falco -c /etc/falco/falco.yaml -r falco_rules_test.yaml \
-p "k8s_pod_uid=%k8s.pod.uid proc_pexepath=%proc.pexepath"
```

The output includes your custom output fields along with the default `%container.id` and `%container.name` because the rule still contained the `%container.info` placeholder field:
Output example:

```bash
03:05:34.475000383: Critical Executing binary not part of base image (proc_sname=bash user=root process=sleep proc_exepath=/tmp/sleep parent=bash command=sleep 10000 terminal=34816 container_id=0fdb3cd5b5fc container_name=optimistic_newton) k8s_pod_uid=my_pod_uid proc_pexepath=/usr/bin/bash
```

Here, your custom fields (`k8s_pod_uid` and `proc_pexepath`) appear along with `%container.id` and `%container.name`, which come from `%container.info` in the rule definition.

0 comments on commit db59696

Please sign in to comment.