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. 👍

reyang · 2024-09-20T00:52:04Z

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

+
+We recommend enabling only the minimum required components for a Collector
+configuration: one receiver and one exporter. Configuring only the minimum set
+of components exposes a minimum set of required ports.


"Ports" seem to be too specific, consider rephrasing it to "exposes a minimum attack surface" - it could be TCP/UDP ports, component dependency (SBOM), etc.

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?

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?

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).

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 ..."

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?

jpkrohling · 2024-09-20T07:14:04Z

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

+of components exposes a minimum set of required ports.
+
+- Receivers and exporters can be either push- or pull-based. In either case, the
+  connection established should be over a secure and authenticated channel.


Suggested change

connection established should be over a secure and authenticated channel.

connection established should at least be over a secure channel, potentially authenticated as well.

The idea is: always secure (even on networks that you deem as trusted), and while authentication is recommended, it can be waived on internal network communications.

jpkrohling · 2024-09-20T07:15:22Z

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

+
+- Receivers and exporters can be either push- or pull-based. In either case, the
+  connection established should be over a secure and authenticated channel.
+- Unused receivers and exporters should be disabled to minimize the attack


How? What does that mean concretely? Just by not invoking those components via config file? The current recommendation is to use OCB to only have the required components as part of the binary, effectively reducing the attack surface. But this might have been mentioned later already?

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).

jpkrohling · 2024-09-20T08:38:39Z

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

+
+### Forwarding
+
+A forwarding extension is used when you need to collect telemetry that's not


I feel like this is misplaced here... I don't think the forwarding extension is related to security, nor is a best practice.

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.

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?

jpkrohling · 2024-09-20T08:46:07Z

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

+
+To limit the exposure of servers to authorized users:
+
+- Enable authentication, using bearer token authentication extensions and basic


Suggested change

- Enable authentication, using bearer token authentication extensions and basic

- Enable authentication, for instance by using bearer token authentication extensions and basic

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

jpkrohling reviewed Sep 20, 2024

View reviewed changes

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

reyang Sep 20, 2024

jpkrohling Sep 20, 2024

reyang Sep 20, 2024

reyang Sep 20, 2024

jpkrohling Sep 20, 2024

jpkrohling Sep 20, 2024

jpkrohling Sep 20, 2024

jpkrohling Sep 20, 2024

jpkrohling Sep 20, 2024

jpkrohling Sep 20, 2024

jpkrohling Sep 20, 2024

jpkrohling Sep 20, 2024

jpkrohling Sep 20, 2024

jpkrohling Sep 20, 2024

jpkrohling Sep 20, 2024

	connection established should be over a secure and authenticated channel.
	connection established should at least be over a secure channel, potentially authenticated as well.


		### Forwarding

		A forwarding extension is used when you need to collect telemetry that's not


		## Storing configuration information securely

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


		To limit the exposure of servers to authorized users:

		- Enable authentication, using bearer token authentication extensions and basic

	- Enable authentication, using bearer token authentication extensions and basic
	- Enable authentication, for instance by using bearer token authentication extensions and basic

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

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