Add Collector security documentation #5209

tiffany76 · 2024-09-17T01:09:55Z

This PR moves end user security documentation from a README in the Collector core repository to the OTel docs website.

Based on decisions in previous issues and PRs, the following are assumed:

Security documentation intended for component developers will remain in the README, which will be amended in a follow-up PR.
Both documents will cross-reference the other.
The top-level Collector landing page and the Collector configuration page will link to the security documents.

Tracking issue: #3479
Related to: #3227

NOTE: Much of the work for this PR was done by @mjingle in #3652. With her permission, I am building on her efforts.

tiffany76 · 2024-09-17T01:23:14Z

Still lots to do. I'll let everyone know when it's in a state fit for reviewing. 👍

content/en/docs/security/config-best-practices.md

reyang · 2024-09-20T00:53:20Z

content/en/docs/security/config-best-practices.md

+## Receivers and exporters
+
+We recommend enabling only the minimum required components for a Collector
+configuration: one receiver and one exporter. Configuring only the minimum set


"one receiver and one exporter" seems very strict, what if the user wants to fork the data to two different targets? (e.g. are we suggesting that forking data is not recommended from security perspective?)

I agree with @reyang -- where is this coming from?

Thanks, all! The content so far has been copied from an earlier draft of this documentation. I think this sentence was an edit of the following statement in the core respository's README:

The configuration drives the Collector's behavior and care should be taken to ensure the configuration only enables the minimum set of capabilities and as such exposes the minimum set of required ports.

I will remove the "one receiver and one exporter" restriction from this PR.

I've reworked the intro to this section (Receivers and exporters) based on the comments. Please let me know what you think. No rush. I still have lots to do. Thanks!

reyang · 2024-09-20T00:55:57Z

content/en/docs/security/config-best-practices.md

+ settings using configuration parameters. If these settings are available, you
+ should proceed with caution before modifying the default configuration values.
+ Improperly setting these values might expose the OpenTelemetry Collector to
+ additional attack vectors including resource exhaustion.


Resource exhaustion is a great topic, I feel the current description is a bit misleading - even if the settings are correct, OpenTelemetry Collector can still cause resource exhaustion - is this the current state or there is already a solid solution for resource governance?

Hi @reyang, I removed the mention of resource exhaustion here. The topic is addressed in more detail in the Processors section. I'll let you know once I start work on it. Thanks!

Hi again. I updated the resource utilization section in 8605abb.

reyang · 2024-09-20T00:58:48Z

content/en/docs/security/config-best-practices.md

+ otlp:
+ protocols:
+ grpc:
+ endpoint: localhost:4317


I don't recall the exact details, would this bind to both IPv4 and IPv6, or the Collector has a recommendation regarding how to specify IPv4/v6 explicitly?

IIRC, "localhost" binds to both. In fact, localhost is the default today already, so this recommendation might need to be reworded, as it's probably reminiscent from the days where we bound to all IPs (0.0.0.0).

I've rewritten the DOS safeguard section as well, with updated information about localhost.

Rather than provide an example of binding to a pod's IP, I linked to the README section. Unless you think that content (Docker, Kubernetes, etc.) is relevant to end users and belongs on the website? I was trying to draw a line between end user and developer content, but I'm happy to make changes.

jpkrohling · 2024-09-20T07:11:05Z

content/en/docs/security/_index.md

+Collector configuration. Running a secure Collector can help you
+
+- Protect telemetry that might contain sensitive information, such as personally
+ identifiable information (PII), application-specific data, or network traffic


I'm pretty sure we have a guidance somewhere stating that people should not store PII in telemetry data. Perhaps we should reinforce it here, and add a link to that place? Something like: "help you protect telemetry that shouldn't, but might contain sensitive information, such ..."

Still searching for the existing guidance, but I've updated the wording as suggested. I'll keep looking for the PII reference.

jpkrohling · 2024-09-20T07:11:58Z

content/en/docs/security/config-best-practices.md

+## Receivers and exporters
+
+We recommend enabling only the minimum required components for a Collector
+configuration: one receiver and one exporter. Configuring only the minimum set


I agree with @reyang -- where is this coming from?

content/en/docs/security/config-best-practices.md

jpkrohling · 2024-09-20T07:17:07Z

content/en/docs/security/config-best-practices.md

+ otlp:
+ protocols:
+ grpc:
+ endpoint: localhost:4317


IIRC, "localhost" binds to both. In fact, localhost is the default today already, so this recommendation might need to be reworded, as it's probably reminiscent from the days where we bound to all IPs (0.0.0.0).

content/en/docs/security/config-best-practices.md

content/en/docs/security/hosting-best-practices.md

Co-authored-by: Juraci Paixão Kröhling <[email protected]>

content/en/docs/security/_index.md

content/en/docs/security/config-best-practices.md

Co-authored-by: Pablo Baeyens <[email protected]>

tiffany76 · 2024-10-18T04:00:33Z

Hi folks! I'm moving this PR out of draft. It's ready for review (finally)!

Just a couple thoughts:

I think I have addressed all the comments so far, but I did rewrite most of the content, so you might have trouble finding your comments in the changed files. I'm sorry about that.
I just reread @jpkrohling's comment about keeping these docs closer to the Collector getting started docs. I know there was some back and forth about it. I don't have a preference either way and will move the files to the Collector docs, if that's what everyone agrees on.
I will be AFK next week, so that will be a prime time for everyone to pile on the reviews. 😃

EDIT to add preview links:
Security landing page
Configuration best practices
Hosting best practices

svrnm

minor comment, but looks good to me overall, great work! 🎉

svrnm · 2024-10-18T07:43:54Z

content/en/docs/security/_index.md

+Learn how the OpenTelemetry project discloses vulnerabilities and responds to
+incidents. Find out how to ensure your observability data is collected and
+transmitted in a secure manner.


should we move that into the frontmatter description, it reads like one

It might be a little long for the description. Let me take another shot at making the wording more intro-like.

content/en/docs/security/hosting-best-practices.md

mx-psi · 2024-10-18T07:46:13Z

content/en/docs/security/hosting-best-practices.md

+The Collector should not require privileged access, except where the data it's
+collecting is in a privileged location. For example, in order to get pod logs by
+mounting a node volume, the Collector daemonset needs enough privileges to get
+that data.


This section is worded differently from the others, I would rephrase it so that it more explicitly tells you what to do (use the least amount of privilege required).

Good catch on the change in wording! I used the example that @jpkrohling gave in a comment that I can't find now. I will work on rephrasing it to match the other examples on the page.

content/en/docs/security/hosting-best-practices.md

Co-authored-by: Pablo Baeyens <[email protected]>

tiffany76 added 2 commits September 16, 2024 17:52

Edit security index.md

631930d

Copy content into config-best-practices.md

2dc2e17

opentelemetrybot requested a review from a team September 17, 2024 01:10

github-actions bot added the sig:security label Sep 17, 2024

tiffany76 added the sig:collector label Sep 17, 2024

mx-psi self-requested a review September 17, 2024 07:49

Merge branch 'main' into collector-security

0d88c24

opentelemetrybot requested a review from a team September 19, 2024 22:24

tiffany76 added 7 commits September 19, 2024 15:41

Fix spelling issues

135fc1d

Make linter fixes

6063b77

Update links on index.md

2de00e2

Copy content into hosting-best-practices.md

7cbbcf6

Add TODO

b4987c3

Edits to config and hosting best practices

79688ec

Make Prettier fix

be0d8ee

reyang reviewed Sep 20, 2024

View reviewed changes

content/en/docs/security/config-best-practices.md Outdated Show resolved Hide resolved

reyang reviewed Sep 20, 2024

View reviewed changes

jpkrohling reviewed Sep 20, 2024

View reviewed changes

Apply suggestions from Juraci

3e7c3c9

Co-authored-by: Juraci Paixão Kröhling <[email protected]>

opentelemetrybot requested a review from a team September 23, 2024 22:52

tiffany76 added 7 commits September 23, 2024 15:52

Merge branch 'main' into collector-security

932a3d5

Update index.md with PII no-no

a1427f2

Add headings for child pages to index.md

cc131a8

Update config receivers and exporters section

cbf67a9

Make link and linter fixes

02d0944

Merge branch 'main' into collector-security

3cee030

Update DOS safeguard section

500d331

tiffany76 added 13 commits September 24, 2024 15:56

Adjust info architecture of all pages

0a05a95

Merge branch 'main' into collector-security

b53353a

Edit protocol section

18283d5

Change headings and info arch

bb8852f

Edit scrubbing sensitive data section

0532e02

Merge branch 'main' into collector-security

92eccee

Create new top level section and rework content

36d55c1

Create 'specific risk' section

c95ba0c

Remove forwarding section

dbfd1b6

Merge branch 'main' into collector-security

2a582e7

Edit resource utlization section

8605abb

Minor edits

44ae838

Make cSpell happy

2e606e2

mx-psi reviewed Oct 17, 2024

View reviewed changes

tiffany76 and others added 4 commits October 17, 2024 18:00

Apply suggestions from Pablo's review

fb566d1

Co-authored-by: Pablo Baeyens <[email protected]>

Merge branch 'main' into collector-security

6d9150f

Fix formatting and remove sections

961ac47

Rewrite and move observers section

af95741

tiffany76 mentioned this pull request Oct 18, 2024

Add section on internal telemetry to Collector security docs #5429

Open

Rewrite hosting best practices

73f4c38

tiffany76 marked this pull request as ready for review October 18, 2024 04:00

tiffany76 requested a review from a team as a code owner October 18, 2024 04:00

tiffany76 requested review from jpkrohling, mx-psi and reyang October 18, 2024 04:01

svrnm approved these changes Oct 18, 2024

View reviewed changes

mx-psi reviewed Oct 18, 2024

View reviewed changes

Apply suggestions from Pablo's second review

3f856e9

Co-authored-by: Pablo Baeyens <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Collector security documentation #5209

Add Collector security documentation #5209

tiffany76 commented Sep 17, 2024

tiffany76 commented Sep 17, 2024

reyang Sep 20, 2024

jpkrohling Sep 20, 2024

tiffany76 Sep 23, 2024

tiffany76 Sep 24, 2024 •

edited

Loading

reyang Sep 20, 2024

tiffany76 Sep 24, 2024

tiffany76 Oct 15, 2024

reyang Sep 20, 2024

jpkrohling Sep 20, 2024

tiffany76 Sep 24, 2024

jpkrohling Sep 20, 2024

tiffany76 Sep 23, 2024

jpkrohling Sep 20, 2024

jpkrohling Sep 20, 2024

tiffany76 commented Oct 18, 2024 •

edited

Loading

svrnm left a comment

svrnm Oct 18, 2024

tiffany76 Oct 19, 2024

mx-psi Oct 18, 2024

tiffany76 Oct 19, 2024

Add Collector security documentation #5209

Are you sure you want to change the base?

Add Collector security documentation #5209

Conversation

tiffany76 commented Sep 17, 2024

tiffany76 commented Sep 17, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tiffany76 Sep 24, 2024 • edited Loading

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

tiffany76 commented Oct 18, 2024 • edited Loading

svrnm left a 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

tiffany76 Sep 24, 2024 •

edited

Loading

tiffany76 commented Oct 18, 2024 •

edited

Loading