Skip to content

Commit b37aa4c

Browse files
marwinskimarwinski
committed
New documentation
1 parent e75ac75 commit b37aa4c

5 files changed

Lines changed: 522 additions & 0 deletions

File tree

‎docs/FalcoExtension.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,10 @@ reviewers:
1111

1212
# GEP-27: Falco Extension - an extension to deploy and manage Falco in shoot clusters
1313

14+
Note: this is the original enhancement proposal for the Falco extension. It
15+
is kept for reference purposes only. The actual implemenetation has
16+
diverged from this original proposal.
17+
1418
## Table of Contents
1519

1620
- [Summary](#summary)

‎docs/README.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Gardener Falco Extension - Managed Falco in shoot clusters
2+
3+
## Introduction
4+
5+
This extension deploys and manages Falco in shoot clusters in a Gardener native
6+
way, offering options to persist runtime events for further processing. Users
7+
may enable it by adding an extension configuration to the shoot manifest.
8+
9+
Falco is a cloud-native runtime security tool for Linux, designed to detect
10+
and alert on abnormal behavior and potential security threats in real-time
11+
([falco.org](https://falco.org/)).
12+
In our Gardener landscapes, it effectively detects unusual runtime events,
13+
such as debugging activities, host configuration changes, or software
14+
installations in containers. If not detected as part of legitimate debugging
15+
activity, these events likely indicate malicious behavior.
16+
17+
Falco is a powerful runtime threat detection engine but comes with limited
18+
means to deploy on many Kubernetes clusters or sophisticated event analysis
19+
and visualization for many clusters. These features are usually provided by
20+
commercial products: some of them rely on Falco as the threat detection
21+
engine, for example from [Sysdig](https://sysdig.com/products/platform/) and
22+
[Trend Micro](https://www.trendmicro.com/en_us/business/products/one-platform.html).
23+
24+
## Getting Started
25+
26+
For the most basic setup add the following default configuration in `.spec.extensions`
27+
to the shoot manifest. It is sufficient to deploy Falco:
28+
29+
```yaml
30+
spec:
31+
extensions:
32+
- type: shoot-falco-service
33+
```
34+
35+
Based on this extension configuration the Falco extension will deploy the
36+
latest Falco version configured as `supported` and ensure it is kept
37+
up to date by always updating it to the latest available Falco version configured
38+
for the landscape. The ruleset will be managed by Gardener and will provide
39+
[standard rules](https://github.com/falcosecurity/rules/blob/main/rules/falco_rules.yaml)
40+
which are designed to offer basic detection capabilities.
41+
This is a tradeoff between sophisticated detection capabilities and the
42+
number of false positive events. More rules mean
43+
better threat detection capabilities but potentially tens of thousands of
44+
false-positive events. The standard Falco ruleset has been optimized not to emit
45+
any false positive events in an empty cluster managed by Gardener. Depending on
46+
the workload, rule exceptions may need to be defined.
47+
48+
To verify functionality, generate sample events by running the following command
49+
within the shoot cluster:
50+
51+
``` bash
52+
$ kubectl run sample-events -it --rm --image falcosecurity/event-generator -- run syscall --all
53+
54+
If you don't see a command prompt, try pressing enter.
55+
INFO action executed action=syscall.KubernetesClientToolLaunchedInContainer
56+
INFO sleep for 100ms action=syscall.ReadSshInformation
57+
INFO action executed action=syscall.ReadSshInformation
58+
INFO sleep for 100ms action=syscall.FindAwsCredentials
59+
INFO action executed action=syscall.FindAwsCredentials
60+
INFO sleep for 100ms action=syscall.DetectCryptoMinersUsingTheStratumProtocol
61+
INFO action executed action=syscall.DetectCryptoMinersUsingTheStratumProtocol
62+
INFO sleep for 100ms action=syscall.PotentialLocalPrivilegeEscalationViaEnvironmentVariablesMisuse
63+
INFO action executed action=syscall.PotentialLocalPrivilegeEscalationViaEnvironmentVariablesMisuse
64+
INFO sleep for 100ms action=syscall.DbProgramSpawnedProcess
65+
INFO spawn as "mysqld" action=syscall.DbProgramSpawnedProcess args="^helper.ExecLs$"
66+
INFO sleep for 100ms action=helper.ExecLs as=mysqld
67+
INFO action executed action=helper.ExecLs as=mysqld
68+
INFO sleep for 100ms action=syscall.WriteBelowRpmDatabase
69+
INFO action executed action=syscall.WriteBelowRpmDatabase
70+
INFO sleep for 100ms action=syscall.LaunchRemoteFileCopyToolsInContainer
71+
INFO sleep for 100ms action=syscall.LaunchIngressRemoteFileCopyToolsInContainer
72+
[...]
73+
```
74+
75+
Once messages appear, let it run for a few seconds, and then end it with Ctrl+C.
76+
77+
By default, events are forwarded to the cluster logging stack and stored in the
78+
Vali database. Query the database via Plutono using [LogQL queries](https://grafana.com/docs/loki/latest/query/),
79+
such as:
80+
81+
```
82+
{rule=~".+", tags=~".+", source=~".+"}
83+
```
84+
85+
## Further Details
86+
87+
This minimal configuration can be customized further. Users can select specific
88+
Falco versions, select from 3 rule files provided by the Falco community, add
89+
custom rules and specify event destinations. A full description of
90+
configuration options is available [here](falco-configuration.md).
91+
92+
[Falco profiles](falco-profile.md) contain information on available Falco
93+
versions and their support status.

‎docs/extension-configuration.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Gardener Falco Extension Configuration
2+
3+
The Gardner Falco extension consists of an extension binary
4+
(`gardener-extension-shoot-falco-service`) as well as an admission binary
5+
(`gardener-extension-admission-shoot-falco-service`) which contains a
6+
mutating- and validating webhook as well as the maintenacne controller.
7+
8+
## The extension `gardener-extension-shoot-falco-service`
9+
10+
The extension binary uses a non-standard configuration parameter
11+
`--config-file` whih points to a configuration YAML file as shown below:
12+
13+
```
14+
apiVersion: falco.extensions.config.gardener.cloud/v1alpha1
15+
kind: Configuration
16+
falco:
17+
certificateLifetime: 2100h
18+
cerfificateRenewAfter: 1600h
19+
priorityClassName: gardener-shoot-system-900
20+
centralStorage:
21+
tokenLifetime: "720h"
22+
url: << ingestor URL >>
23+
tokenIssuerPrivateKey: |
24+
-----BEGIN RSA PRIVATE KEY-----
25+
...
26+
```
27+
28+
* `certificateLifetime`: Lifetime of certificates generated for communication between Falco and Falcosidekick.
29+
* `certificateRenewAfter`: Time period after which certificates are renewed.
30+
* `priorityClassName`: Priority class used for Falco when deployed.
31+
* `centralStorage`: optional configuration for central event storage (see below)
32+
* `tokenLifetime`: Lifetime of the JWT token generated during each reconcile for sending events to central storage.
33+
* `ingestorURL`: URL of the Falco event ingestor
34+
* `tokenIssuerPrivateKey`: Private key used for issuing the JWT token.
35+
36+
## Central storage
37+
38+
Falcosidekick can optionally send events to a central storage location. This
39+
requires a central storage setup based on the following projects:
40+
41+
- [falco-event-ingestor](https://github.com/gardener/falco-event-ingestor)
42+
- [falco-event-provider](https://github.com/gardener/falco-event-provider)
43+
- [falco-event-db-schema](https://github.com/gardener/falco-event-db-schema)
44+
45+
If this is set users can configure `central` as the destination for Falco
46+
events.
47+
48+
## The webhook `gardener-extension-admission-shoot-falco-service`
49+
50+
The webhook can be configured to enforce usage restrictions:
51+
52+
- The extension may only deploy Falco in clusters where the gardener project
53+
namespace is annotated with
54+
55+
```yaml
56+
falco.gardener.cloud/enabled=true
57+
```
58+
59+
- The "central" storage option may only be configured from shoot clusters if
60+
their project namespace is annotated with
61+
62+
```yaml
63+
falco.gardener.cloud/centralized-logging=true
64+
```
65+
66+
The restrictions can be enabled by passing `--restricted-usage` and
67+
`--restricted-centralized-logging` to the webhook binary.

0 commit comments

Comments
 (0)