Introduce documentation about required capabilities #1587
Conversation
rafaelroquetto
added
the
documentation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1587 +/- ##
==========================================
+ Coverage 63.86% 67.05% +3.19%
==========================================
Files 196 197 +1
Lines 19862 19871 +9
==========================================
+ Hits 12684 13325 +641
+ Misses 6381 5858 -523
+ Partials 797 688 -109
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
rafaelroquetto
force-pushed
the
security_docs
branch
from
8d9fe18 to
aef1019
Compare
rafaelroquetto
force-pushed
the
security_docs
branch
from
aef1019 to
0b47d08
Compare
rafaelroquetto
force-pushed
the
security_docs
branch
from
0b47d08 to
583cb14
Compare
docs/sources/security.md
Outdated
| | 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 | |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Got it, I will reshuffle this.
There was a problem hiding this comment.
So, revisiting this, the reason it's written this way is so that it also serves as a guide for power-users/developers. I feel just saying "required for network observability" does not tell the whole story for those who are actually interested on why Beyla needs a particular permission.
I will try to rephrase this to include both an user friendly explanation whilst keeping the technical details for those interested.
docs/sources/security.md
Outdated
| ### 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 |
There was a problem hiding this comment.
Again we need to say what this means for our end users.
docs/sources/security.md
Outdated
|
|
||
| # 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. |
There was a problem hiding this comment.
[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 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. |
docs/sources/security.md
Outdated
| | `CAP_BPF` | Enables general BPF functionality and socket filter (`BPF_PROG_TYPE_SOCK_FILTER`) programs, used for capturing network flows in *network observability mode*. | | ||
| | `CAP_NET_RAW` | Used to create `AF_PACKET` raw sockets, which is the mechanism used to attach socket filter programs used for capturing network flows in *network observability mode*. | | ||
| | `CAP_NET_ADMIN` | Required to load `BPF_PROG_TYPE_SCHED_CLS` TC programs - these programs are used for capturing network flows and for trace context propagation, both for *network and application observability*. | | ||
| | `CAP_PERFMON` | Used for trace context propagation, general *application observability* and network flow monitoring. Allows direct packet access by TC programs, loading eBPF probes in the kernel and pointer arithmetic used by these programs. | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Grafana.GoogleSpacing] 'g. A' should have one space.
For more information, refer to https://developers.google.com/style/sentence-spacing.
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.
docs/sources/security.md
Outdated
|
|
||
| ## Internal eBPF tracer capability requirement reference | ||
|
|
||
| Beyla's internal architecture is made of different "tracers" - a set of eBPF programs that implement the underlying functionality used by Beyla. A tracer may load and use different kinds of eBPF programs, each requiring their own set of capabilities. |
There was a problem hiding this comment.
[Grafana.ProductPossessives] Don't form a possessive from a feature name, product name, or trademark, regardless of who owns it. Instead, use the name as a modifier or rewrite to use a word like of to indicate the relationship.
For more information, refer to https://developers.google.com/style/possessives#product,-feature,-and-company-names.
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.
docs/sources/security.md
Outdated
|
|
||
| By carefully choosing and assigning capabilities you can lower the risk of privilege escalation while still letting processes do what they need to. | ||
|
|
||
| More information can be found in the [capabilities manpage](https://man7.org/linux/man-pages/man7/capabilities.7.html). |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Grafana.Spelling] Did you really mean 'manpage'? The Grafana dictionary might not know of this word yet. To add a new word, refer to Add words to the Grafana Labs dictionary. Alternatively, raise an issue and a maintainer will add it for you. For UI elements, use bold formatting. The spell checker doesn't check words with bold formatting. For paths; configuration; user input; code; class, method, and variable names; statuscodes; and console output, use code formatting. The spell checker doesn't check words with code formatting.
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
force-pushed
the
security_docs
branch
from
ffa45cb to
6312a33
Compare
|
@rafaelroquetto LGTM 🎉 |
rafaelroquetto
force-pushed
the
security_docs
branch
from
437ae21 to
9407e75
Compare
|
Rebased and resolved conflict. |
|
Hello @grafsean!
Please, if the current pull request addresses a bug fix, label it with the |
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