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

jpkrohling · 2024-09-20T08:41:36Z

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

+while the `host_observer` requires the OpenTelemetry Collector to run in
+privileged mode.
+
+<!--- But what about Juraci's comment here: https://github.com/open-telemetry/opentelemetry.io/pull/3652/files?diff=unified&w=0#r1417409370 --->


It's OK -- what we shouldn't be telling people is to run things as root or blindly disable security protections (like selinux).

jpkrohling · 2024-09-20T08:43:42Z

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

+### Subprocesses
+
+Extensions can also be used to run subprocesses when the Collector can't
+natively run the collection mechanisms (for example, FluentBit). Subprocesses


I'm also not sure where this is coming from: the only component that I know of spawning new processes is the jmx receiver.

This section comes directly from the security README. Should I remove it?

jpkrohling · 2024-09-20T08:44:32Z

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

+
+## Storing configuration information securely
+
+<!--- TODO: SHOULD ensure sensitive configuration information is stored securely. How? -->


Perhaps add a reference to the secrets management practices for Kubernetes?

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

Co-authored-by: Juraci Paixão Kröhling <juraci.github@kroehling.de>

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 <juraci.github@kroehling.de>

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

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

jpkrohling Sep 20, 2024

jpkrohling Sep 20, 2024

tiffany76 Oct 6, 2024

jpkrohling Sep 20, 2024


		## Storing configuration information securely

		<!--- TODO: SHOULD ensure sensitive configuration information is stored securely. How? -->

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

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