Introduce documentation about required capabilities #1587

rafaelroquetto · 2025-01-29T19:58:03Z

First iteration of the documentation that talks about the required capabilities to run Beyla. Whilst it could have been nice, a per-kernel list is out of the scope for this PR and could be added later.

I've also removed the mentions to mounting file systems, since Beyla no longer does that.

It would be good to get feedback on whether we still require container.apparmor.security.beta.kubernetes.io/beyla: "unconfined".

Resolves #1404

docs/sources/security.md

docs/sources/_index.md

docs/sources/security.md

codecov · 2025-01-29T20:06:04Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 71.02%. Comparing base (ab3c784) to head (021918b).
Report is 9 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1587      +/-   ##
==========================================
- Coverage   71.05%   71.02%   -0.04%     
==========================================
  Files         197      197              
  Lines       19753    19792      +39     
==========================================
+ Hits        14036    14057      +21     
- Misses       5041     5057      +16     
- Partials      676      678       +2

Flag	Coverage Δ
integration-test	`52.81% <ø> (-0.14%)`	⬇️
k8s-integration-test	`53.04% <ø> (-0.83%)`	⬇️
oats-test	`34.67% <ø> (-0.01%)`	⬇️
unittests	`46.95% <ø> (-0.09%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

docs/sources/security.md

github-actions · 2025-01-29T21:56:50Z

docs/sources/setup/kubernetes.md

- Set a modified AppArmour policy which allows Beyla to perform `mount`.
-
-**Note** Since the `beyla` container does not have the privileges required to mount or un-mount the BPF filesystem, this sample leaves the BPF filesystem mounted on the host, even after the sample is deleted. This samples uses a unique path for each namespace to ensure re-use the same mount if Beyla is re-deployed, but to avoid collisions if multiple instances of Beyla is run in different namespaces.
+Because of the AppArmour restriction, to run Beyla as unprivileged container, you may need to set `container.apparmor.security.beta.kubernetes.io/beyla: "unconfined"` in your Kubernetes deployment files in case you run into issues.


⚠️ [vale] _{reported by reviewdog 🐶}
[Grafana.Kubernetes] Use 'Kubernetes Deployment' instead of 'Kubernetes deployment'.

For more information, refer to https://grafana.com/docs/writers-toolkit/write/style-guide/capitalization-punctuation/#kubernetes-objects.

If the rule is incorrect or needs improving, report an issue.

If you have reason to diverge from the style guidance, to skip a rule, refer to Skip rules.

grcevski · 2025-01-29T21:48:40Z

docs/sources/security.md

+
+## Beyla operation modes
+
+Beyla can operate in two distinct modes: _application observability_ and _network observability_. These modes are not mutually exclusive and can be used together as needed. The former is typically enabled using the `BEYLA_OPEN_PORT` or `BEYLA_EXECUTABLE_NAME` options, while the latter is controlled via the `BEYLA_NETWORK_METRICS` option. For more details on enabling these modes, refer to the [configuration documentation](/docs/beyla/latest/configure/options/).


Instead of namig BEYLA_OPEN_PORT ... can we please refer to the docs on the discovery section.

grcevski · 2025-01-29T21:51:47Z

docs/sources/security.md

+| Capability               | Usage in Beyla                                                                                                             |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `CAP_BPF`                | enables general BPF functionality and `BPF_PROG_TYPE_SOCK_FILTER` programs                                                 |
+| `CAP_NET_RAW`            | used to create `AF_PACKET` raw sockets                                                                                     |


This one is needed for the socket filter program. I think we need to be more descriptive here about how the capabilities relate to Beyla features, I don't think our users would know what AF_PACKET means in terms of Beyla. Same for NET_ADMIN, we need to say network observability and context propagation.

Got it, I will reshuffle this.

docs/sources/security.md

grcevski · 2025-01-29T21:53:25Z

docs/sources/security.md

+* `CAP_DAC_READ_SEARCH`
+* `CAP_CHECKPOINT_RESTORE`
+* `CAP_PERFMON`
+* `CAP_NET_RAW`


I think NET_ADMIN assumes NET_RAW, maybe we don't need that one but it's fine to keep it.

I double checked the kernel sources, they are orthogonal to each other.

grcevski · 2025-01-29T21:54:15Z

docs/sources/security.md

+
+### Flow fetcher (tc)
+- `CAP_BPF` 
+- `CAP_NET_ADMIN` -> for `PROG_TYPE_SCHED_CLS`


I think we need to say what PROG_TYPE_SCHE... does, rather than saying it's for that.

grcevski · 2025-01-29T21:54:32Z

docs/sources/security.md

+### Flow fetcher (tc)
+- `CAP_BPF` 
+- `CAP_NET_ADMIN` -> for `PROG_TYPE_SCHED_CLS`
+- `CAP_PERFMON` -> direct access to `struct __sk_buff::data` and pointer arithmetic


Again we need to say what this means for our end users.

docs/sources/security.md

grcevski · 2025-01-29T21:56:13Z

docs/sources/setup/kubernetes.md

@@ -251,24 +251,13 @@ In all of the examples so far, `privileged:true` or the `SYS_ADMIN` Linux capabi

 The following guide is based on tests performed mainly by running `containerd` with `GKE`, `kubeadm`, `k3s`, `microk8s` and `kind`.

-To run Beyla unprivileged, you need to run a `privileged` init container which performs setup tasks which require elevated privileges. Then you need to replace the `privileged:true` setting with a set of Linux [capabilities](https://www.man7.org/linux/man-pages/man7/capabilities.7.html).
+To run Beyla unprivileged, you need to run a `privileged` init container which performs setup tasks which require elevated privileges. Then you need to replace the `privileged:true` setting with a set of Linux [capabilities](https://www.man7.org/linux/man-pages/man7/capabilities.7.html). A comprehensive list of capabilities required by Beyla can be found in [Security, permissions and capabilities]({{< relref "../security" >}}).


We don't need to run a privileged init container anymore, it should be removed as well.

grcevski · 2025-01-29T21:58:09Z

docs/sources/setup/kubernetes.md

- `CAP_DAC_READ_SEARCH` is required to open ELF files.
- `CAP_PERFMON` is required to load BPF programs, i.e. be able to perform `perf_event_open()`.
- `CAP_SYS_RESOURCE` is required only on kernels **< 5.11** so that Beyla can increase the amount of locked memory available.
+In addition to these Linux capabilities, many Kubernetes versions include [AppArmour](https://kubernetes.io/docs/tutorials/security/apparmor/), which tough policies adds additional restrictions to unprivileged containers. By [default](https://github.com/moby/moby/blob/master/profiles/apparmor/template.go), the AppArmour policy restricts the use of `mount` and the access to `/sys/fs/` directories. Beyla requires access to `/sys/fs/cgroup/`.


Based on what we saw, I think /cgroup is not restricted by the app armour default config. We need to confirm and remove this section too.

marctc · 2025-01-30T08:59:53Z

docs/sources/security.md

+
+## Linux kernel capabilities
+
+Linux kernel capabilities are a fine-grained system for controlling access to privileged operations on the system. They allow you to grant specific permissions to processes without giving them full root (superuser) access, which helps improve security by adhering to the principle of least privilege. Instead of relying on the traditional all-or-nothing root model, capabilities split the powerful privileges typically associated with root into smaller, more manageable units.


Can we add link some here to some official docs or so?

docs/sources/security.md

github-actions · 2025-02-03T14:33:31Z

docs/sources/security.md

+
+# Beyla security, permissions, and capabilities
+
+Beyla needs access to various Linux interfaces to instrument applications, such as reading from the `/proc` filesystem, loading eBPF programs, and managing network interface filters. Many of these operations require elevated permissions. The simplest solution is to run Beyla as `root`, however this might not work well in setups where full `root` access isn’t ideal. To address this, Beyla is designed to use only the specific Linux kernel capabilities needed for its current configuration.


⚠️ [vale] _{reported by reviewdog 🐶}
[Grafana.SmartQuotes] Avoid smart quotes in the source file, especially in code blocks. Replace all smart double quotes like “ or ” with ". Replace all smart single quotes like ‘, ’, or ʼ with '. In some contexts, Unicode characters aren't supported and break configurations. The website renders paired quotes using smart quotes in paragraphs.

If the rule is incorrect or needs improving, report an issue.

If you have reason to diverge from the style guidance, to skip a rule, refer to Skip rules.

grafsean · 2025-02-03T14:40:09Z

@rafaelroquetto I pushed a copy edit and addressed some of the non-technical feedback. It's ready for you to review and address the remaining technical feedback.

github-actions · 2025-02-03T14:42:22Z

docs/sources/security.md

+
+# Beyla security, permissions, and capabilities
+
+Beyla needs access to various Linux interfaces to instrument applications, such as reading from the `/proc` filesystem, loading eBPF programs, and managing network interface filters. Many of these operations require elevated permissions. The simplest solution is to run Beyla as root, however this might not work well in setups where full root access isn’t ideal. To address this, Beyla is designed to use only the specific Linux kernel capabilities needed for its current configuration.


⚠️ [vale] _{reported by reviewdog 🐶}
[Grafana.SmartQuotes] Avoid smart quotes in the source file, especially in code blocks. Replace all smart double quotes like “ or ” with ". Replace all smart single quotes like ‘, ’, or ʼ with '. In some contexts, Unicode characters aren't supported and break configurations. The website renders paired quotes using smart quotes in paragraphs.

If the rule is incorrect or needs improving, report an issue.

If you have reason to diverge from the style guidance, to skip a rule, refer to Skip rules.

rafaelroquetto added the documentation Improvements or additions to documentation label Jan 29, 2025

rafaelroquetto requested a review from grafsean as a code owner January 29, 2025 19:58

rafaelroquetto requested a review from a team January 29, 2025 19:58

github-actions bot reviewed Jan 29, 2025

View reviewed changes

docs/sources/security.md Outdated Show resolved Hide resolved

rafaelroquetto force-pushed the security_docs branch from 8d9fe18 to aef1019 Compare January 29, 2025 20:09

github-actions bot reviewed Jan 29, 2025

View reviewed changes

docs/sources/security.md Outdated Show resolved Hide resolved

docs/sources/security.md Outdated Show resolved Hide resolved

docs/sources/security.md Outdated Show resolved Hide resolved

docs/sources/security.md Outdated Show resolved Hide resolved

rafaelroquetto force-pushed the security_docs branch from aef1019 to 0b47d08 Compare January 29, 2025 20:14

github-actions bot reviewed Jan 29, 2025

View reviewed changes

docs/sources/security.md Outdated Show resolved Hide resolved

Introduce documentation about required capabilities

583cb14

rafaelroquetto force-pushed the security_docs branch from 0b47d08 to 583cb14 Compare January 29, 2025 21:56

github-actions bot reviewed Jan 29, 2025

View reviewed changes

grcevski reviewed Jan 29, 2025

View reviewed changes

marctc reviewed Jan 30, 2025

View reviewed changes

docs/sources/security.md Show resolved Hide resolved

marctc reviewed Jan 30, 2025

View reviewed changes

docs/sources/security.md Outdated Show resolved Hide resolved

grafsean self-assigned this Feb 3, 2025

Edits

bd339ee

github-actions bot reviewed Feb 3, 2025

View reviewed changes

grafsean added 2 commits February 3, 2025 14:34

Update heading

7370f87

Update heading

1df7588

Remove quotes and update code highlight

021918b

github-actions bot reviewed Feb 3, 2025

View reviewed changes

grafsean mentioned this pull request Feb 4, 2025

Beyla: inform that CAP_NET_ADMIN is required #1221

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Introduce documentation about required capabilities #1587

Introduce documentation about required capabilities #1587

rafaelroquetto commented Jan 29, 2025

codecov bot commented Jan 29, 2025 •

edited

Loading

github-actions bot Jan 29, 2025

grcevski Jan 29, 2025

rafaelroquetto Jan 29, 2025

grcevski Jan 29, 2025

rafaelroquetto Jan 29, 2025

grcevski Jan 29, 2025

rafaelroquetto Jan 29, 2025

grcevski Jan 29, 2025

grcevski Jan 29, 2025

grcevski Jan 29, 2025

grcevski Jan 29, 2025

marctc Jan 30, 2025

github-actions bot Feb 3, 2025

grafsean commented Feb 3, 2025

github-actions bot Feb 3, 2025


		## Beyla operation modes

		Beyla can operate in two distinct modes: _application observability_ and _network observability_. These modes are not mutually exclusive and can be used together as needed. The former is typically enabled using the `BEYLA_OPEN_PORT` or `BEYLA_EXECUTABLE_NAME` options, while the latter is controlled via the `BEYLA_NETWORK_METRICS` option. For more details on enabling these modes, refer to the [configuration documentation](/docs/beyla/latest/configure/options/).


		## Linux kernel capabilities

		Linux kernel capabilities are a fine-grained system for controlling access to privileged operations on the system. They allow you to grant specific permissions to processes without giving them full root (superuser) access, which helps improve security by adhering to the principle of least privilege. Instead of relying on the traditional all-or-nothing root model, capabilities split the powerful privileges typically associated with root into smaller, more manageable units.


		# Beyla security, permissions, and capabilities

		Beyla needs access to various Linux interfaces to instrument applications, such as reading from the `/proc` filesystem, loading eBPF programs, and managing network interface filters. Many of these operations require elevated permissions. The simplest solution is to run Beyla as `root`, however this might not work well in setups where full `root` access isn’t ideal. To address this, Beyla is designed to use only the specific Linux kernel capabilities needed for its current configuration.

Introduce documentation about required capabilities #1587

Are you sure you want to change the base?

Introduce documentation about required capabilities #1587

Conversation

rafaelroquetto commented Jan 29, 2025

codecov bot commented Jan 29, 2025 • edited Loading

Codecov Report

github-actions bot Jan 29, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot Feb 3, 2025

Choose a reason for hiding this comment

grafsean commented Feb 3, 2025

github-actions bot Feb 3, 2025

Choose a reason for hiding this comment

codecov bot commented Jan 29, 2025 •

edited

Loading