Skip to content

Commit e7b52a2

Browse files
tiffany76tiffany76
authored
[docs] Remove end-user content from security README (#12002)
#### Description The end-user security documentation was moved to the OTel website in open-telemetry/opentelemetry.io#5209 and open-telemetry/opentelemetry.io#5729. This PR removes the end-user content from [security-best-practices.md](https://github.com/swiatekm/opentelemetry-collector/blob/main/docs/security-best-practices.md), leaving only the component developer documentation. <!-- Issue number if applicable --> #### Link to tracking issue Fixes open-telemetry/opentelemetry.io#3479
1 parent e6a5aee commit e7b52a2

File tree

1 file changed

+31
-269
lines changed

1 file changed

+31
-269
lines changed

‎docs/security-best-practices.md

+31-269
Original file line numberDiff line numberDiff line change
@@ -1,324 +1,86 @@
11
# Security
22

3-
The OpenTelemetry Collector defaults to operating in a secure manner, but is
3+
The OpenTelemetry Collector defaults to operating in a secure manner but is
44
configuration driven. This document captures important security aspects and
5-
considerations for the Collector. This document is intended for both end-users
6-
and component developers. It assumes at least a basic understanding of the
7-
Collector architecture and functionality.
5+
considerations for the Collector. This document is intended for component
6+
developers. It assumes at least a basic understanding of the Collector
7+
architecture and functionality.
88

9-
> Note: Please review the [configuration
10-
> documentation](https://opentelemetry.io/docs/collector/configuration/)
9+
> Note: Please review the
10+
> [configuration documentation](https://opentelemetry.io/docs/collector/configuration/)
1111
> prior to this security document.
1212
13-
## TL;DR
14-
15-
### End-users
16-
17-
- Configuration
18-
- SHOULD only enable the minimum required components
19-
- SHOULD ensure sensitive configuration information is stored securely
20-
- Permissions
21-
- SHOULD not run Collector as root/admin user
22-
- MAY require privileged access for some components
23-
- Receivers/Exporters
24-
- SHOULD use encryption and authentication
25-
- SHOULD limit exposure of servers to authorized users
26-
- MAY pose a security risk if configuration parameters are modified improperly
27-
- Processors
28-
- SHOULD configure obfuscation/scrubbing of sensitive metadata
29-
- SHOULD configure recommended processors
30-
- Extensions
31-
- SHOULD NOT expose sensitive health or telemetry data
13+
Security documentation for end users can be found on the OpenTelemetry
14+
documentation website:
3215

33-
> For more information about securing the OpenTelemetry Collector, see
34-
> [this](https://medium.com/opentelemetry/securing-your-opentelemetry-collector-1a4f9fa5bd6f)
35-
> blog post.
16+
- [Collector configuration best practices](https://opentelemetry.io/docs/security/config-best-practices/)
17+
- [Collector hosting best practices](https://opentelemetry.io/docs/security/hosting-best-practices/)
3618

37-
### Component Developers
19+
## TL;DR
3820

3921
- Configuration
4022
- MUST come from the central configuration file
4123
- SHOULD use configuration helpers
4224
- Permissions
4325
- SHOULD minimize privileged access
44-
- MUST document what required privileged access and why
26+
- MUST document what requires privileged access and why
4527
- Receivers/Exporters
4628
- MUST default to encrypted connections
4729
- SHOULD leverage helper functions
4830
- Extensions
4931
- SHOULD NOT expose sensitive health or telemetry data by default
5032

33+
> For more information about securing the OpenTelemetry Collector, see
34+
> [this blog post](https://medium.com/opentelemetry/securing-your-opentelemetry-collector-1a4f9fa5bd6f).
35+
5136
## Configuration
5237

5338
The Collector binary does not contain an embedded or default configuration and
5439
MUST NOT start without a configuration file being specified. The configuration
55-
file passed to the Collector MUST be validated prior to be loaded. If an
40+
file passed to the Collector MUST be validated prior to being loaded. If an
5641
invalid configuration is detected, the Collector MUST fail to start as a
5742
protective mechanism.
5843

59-
> Note: Issue
60-
> [#886](https://github.com/open-telemetry/opentelemetry-collector/issues/886)
61-
> proposes adding a default configuration to the binary.
62-
63-
The configuration drives the Collector's behavior and care should be taken to
64-
ensure the configuration only enables the minimum set of capabilities and as
65-
such exposes the minimum set of required ports. In addition, any incoming or
66-
outgoing communication SHOULD leverage TLS and authentication.
67-
68-
The Collector keeps the configuration in memory, but where the configuration is
69-
loaded from at start time depends on the packaging used. For example, in
70-
Kubernetes secrets and configmaps CAN be leveraged. In comparison, the Docker
71-
image embeds the configuration in the container where is it not stored in an
72-
encrypted manner by default.
73-
74-
The configuration MAY contain sensitive information including:
75-
76-
- Authentication information such as API tokens
77-
- TLS certificates including private keys
44+
Component developers MUST get configuration information from the Collector's
45+
configuration file. Component developers SHOULD leverage
46+
[configuration helper functions](https://github.com/open-telemetry/opentelemetry-collector/tree/main/config).
7847

79-
Sensitive information SHOULD be stored securely such as on an encrypted
80-
filesystem or secret store. Environment variables CAN be used to handle
81-
sensitive and non-sensitive data as the Collector MUST support environment
82-
variable expansion.
48+
When defining Go structs for configuration data that may contain sensitive
49+
information, use the `configopaque` package to define fields with the
50+
`configopaque.String` type. This ensures that the data is masked when serialized
51+
to prevent accidental exposure.
8352

84-
> For more information on environment variable expansion, see
85-
> [this](https://opentelemetry.io/docs/collector/configuration/#environment-variables)
53+
> For more information, see the
54+
> [configopaque](https://pkg.go.dev/go.opentelemetry.io/collector/config/configopaque)
8655
> documentation.
8756
88-
When defining Go structs for configuration data that may contain sensitive information, use the `configopaque` package to define fields with the `configopaque.String` type. This ensures that the data is masked when serialized to prevent accidental exposure.
89-
90-
> For more information, see the [configopaque](https://pkg.go.dev/go.opentelemetry.io/collector/config/configopaque) documentation.
91-
92-
Component developers MUST get configuration information from the Collector's
93-
configuration file. Component developers SHOULD leverage [configuration helper
94-
functions](https://github.com/open-telemetry/opentelemetry-collector/tree/main/config).
95-
96-
More information about configuration is provided in the following sections.
97-
9857
## Permissions
9958

10059
The Collector supports running as a custom user and SHOULD NOT be run as a
10160
root/admin user. For the majority of use-cases, the Collector SHOULD NOT require
102-
privileged access to function. Some components MAY require privileged access
103-
and care should be taken before enabling these components. Collector components
104-
MAY require external permissions including network access or RBAC.
61+
privileged access to function. Some components MAY require privileged access or
62+
external permissions, including network access or RBAC.
10563

10664
Component developers SHOULD minimize privileged access requirements and MUST
10765
document what requires privileged access and why.
10866

109-
More information about permissions is provided in the following sections.
110-
11167
## Receivers and Exporters
11268

11369
Receivers and Exporters can be either push or pull-based. In either case, the
11470
connection established SHOULD be over a secure and authenticated channel.
115-
Unused receivers and exporters SHOULD be disabled to minimize the attack vector
116-
of the Collector.
117-
118-
Receivers and Exporters MAY expose buffer, queue, payload, and/or worker
119-
settings via configuration parameters. If these settings are available,
120-
end-users should proceed with caution before modifying the default values.
121-
Improperly setting these values may expose the Collector to additional attack
122-
vectors including resource exhaustion.
12371

124-
> It is possible that a receiver MAY require the Collector run in a privileged
125-
> mode in order to operate, which could be a security concern, but today this
126-
> is not the case.
127-
128-
Component developers MUST default to encrypted connections (via the `insecure:
129-
false` configuration setting) and SHOULD leverage
72+
Component developers MUST default to encrypted connections (using the
73+
`insecure: false` configuration setting) and SHOULD leverage
13074
[gRPC](https://github.com/open-telemetry/opentelemetry-collector/tree/main/config/configgrpc)
13175
and
13276
[http](https://github.com/open-telemetry/opentelemetry-collector/tree/main/config/confighttp)
13377
helper functions.
13478

135-
### Safeguards against denial of service attacks
136-
137-
Users SHOULD bind receivers' servers to addresses that limit connections to authorized users.
138-
For example, if the OTLP receiver OTLP/gRPC server only has local clients, the `endpoint` setting SHOULD be bound to `localhost`:
139-
140-
```yaml
141-
receivers:
142-
otlp:
143-
protocols:
144-
grpc:
145-
endpoint: localhost:4317
146-
```
147-
148-
Generally, `localhost`-like addresses should be preferred over the 0.0.0.0 address.
149-
For more information, see [CWE-1327](https://cwe.mitre.org/data/definitions/1327.html).
150-
151-
If `localhost` resolves to a different IP due to your DNS settings then explicitly use the loopback IP instead: `127.0.0.1` for IPv4 or `::1` for IPv6. In IPv6 setups, ensure your system supports both IPv4 and IPv6 loopback addresses to avoid issues.
152-
153-
Using `localhost` may not work in environments like Docker, Kubernetes, and other environments that have non-standard networking setups. We've documented a few working example setups for the OTLP receiver gRPC endpoint below, but other receivers and other Collector components may need similar configuration.
154-
155-
#### Docker
156-
You can run the Collector in Docker by binding to the correct address. An OTLP exporter in Docker might look something like this:
79+
## Safeguards against denial of service attacks
15780

158-
Collector config file
159-
160-
`config.yaml`:
161-
```yaml
162-
receivers:
163-
otlp:
164-
protocols:
165-
grpc:
166-
endpoint: my-hostname:4317 # the same hostname from your docker run command
167-
```
168-
Docker run command:
169-
`docker run --hostname my-hostname --name container-name -p 127.0.0.1:4567:4317 otel/opentelemetry-collector:0.104.0`
170-
171-
The key here is using the `--hostname` argument - that allows the collector to bind to the `my-hostname` address.
172-
You could access it from outside that Docker network (for example on a regular program running on the host) by connecting to `127.0.0.1:4567`.
173-
174-
#### Docker Compose
175-
Similarly to plain Docker, you can run the Collector in Docker by binding to the correct address.
176-
177-
`compose.yaml`:
178-
```yaml
179-
services:
180-
otel-collector:
181-
image: otel/opentelemetry-collector-contrib:0.104.0
182-
ports:
183-
- "4567:4317"
184-
```
185-
186-
Collector config file:
187-
188-
`config.yaml`:
189-
```yaml
190-
receivers:
191-
otlp:
192-
protocols:
193-
grpc:
194-
endpoint: otel-collector:4317 # Using the service name from your Docker compose file
195-
```
196-
197-
You can connect to this Collector from another Docker container running in the same network by connecting to `otel-collector:4317`. You could access it from outside that Docker network (for example on a regular program running on the host) by connecting to `127.0.0.1:4567`.
198-
199-
#### Kubernetes
200-
If you run the Collector as a `Daemonset`, you can use a configuration like below:
201-
```yaml
202-
apiVersion: apps/v1
203-
kind: DaemonSet
204-
metadata:
205-
name: collector
206-
spec:
207-
selector:
208-
matchLabels:
209-
name: collector
210-
template:
211-
metadata:
212-
labels:
213-
name: collector
214-
spec:
215-
containers:
216-
- name: collector
217-
image: otel/opentelemetry-collector:0.104.0
218-
ports:
219-
- containerPort: 4317
220-
hostPort: 4317
221-
protocol: TCP
222-
name: otlp-grpc
223-
- containerPort: 4318
224-
hostPort: 4318
225-
protocol: TCP
226-
name: otlp-http
227-
env:
228-
- name: MY_POD_IP
229-
valueFrom:
230-
fieldRef:
231-
fieldPath: status.podIP
232-
233-
```
234-
In this example, we use the [Kubernetes Downward API](https://kubernetes.io/docs/concepts/workloads/pods/downward-api/) to get your own Pod IP, then bind to that network interface. Then, we use the `hostPort` option to ensure that the Collector is exposed on the host. The Collector's config should look something like:
235-
236-
```yaml
237-
receivers:
238-
otlp:
239-
protocols:
240-
grpc:
241-
endpoint: ${env:MY_POD_IP}:4317
242-
http:
243-
endpoint: ${env:MY_POD_IP}:4318
244-
```
245-
246-
You can send OTLP data to this Collector from any Pod on the Node by accessing `${MY_HOST_IP}:4317` to send OTLP over gRPC and `${MY_HOST_IP}:4318` to send OTLP over HTTP, where `MY_HOST_IP` is the Node's IP address. You can get this IP from the Downwards API:
247-
248-
```yaml
249-
env:
250-
- name: MY_HOST_IP
251-
valueFrom:
252-
fieldRef:
253-
fieldPath: status.hostIP
254-
```
255-
256-
## Processors
257-
258-
Processors sit between receivers and exporters. They are responsible for
259-
processing the data in some way. From a security perspective, they are useful
260-
in a couple ways.
261-
262-
### Scrubbing sensitive data
263-
264-
It is common for a Collector to be used to scrub sensitive data before
265-
exporting it to a backend. This is especially important when sending the data
266-
to a third-party backend. The Collector SHOULD be configured to obfuscate or
267-
scrub sensitive data before exporting.
268-
269-
> Note: Issue
270-
> [#2466](https://github.com/open-telemetry/opentelemetry-collector/issues/2466)
271-
> proposes adding default obfuscation or scrubbing of known sensitive metadata.
272-
273-
### Safeguards around resource utilization
274-
275-
In addition, processors offer safeguards around resource utilization. The
276-
`batch` and especially `memory_limiter` processor help ensure that the
277-
Collector is resource efficient and does not run out of memory when overloaded. At
278-
least these two processors SHOULD be enabled on every defined pipeline.
279-
280-
> For more information on recommended processors and order, see
281-
> [this](https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor)
282-
> documentation.
81+
See the [Collector configuration security documentation](https://opentelemetry.io/docs/security/config-best-practices/#protect-against-denial-of-service-attacks) to learn how to safeguard against denial of service attacks.
28382

28483
## Extensions
28584

286-
While receivers, processors, and exporters handle telemetry data directly,
287-
extensions typical serve different needs.
288-
289-
### Health and Telemetry
290-
291-
The initial extensions provided health check information, Collector metrics and
292-
traces, and the ability to generate and collect profiling data. When enabled
293-
with their default settings, all of these extensions except the health check
294-
extension are only accessibly locally to the Collector. Care should be taken
295-
when configuring these extensions for remote access as sensitive information
296-
may be exposed as a result.
297-
29885
Component developers SHOULD NOT expose health or telemetry data outside the
29986
Collector by default.
300-
301-
### Forwarding
302-
303-
A forwarding extension is typically used when some telemetry data not natively
304-
supported by the Collector needs to be collected. For example, the
305-
`http_forwarder` extension can receive and forward HTTP payloads. Forwarding
306-
extensions are similar to receivers and exporters so the same security
307-
considerations apply.
308-
309-
### Observers
310-
311-
An observer is capable of performing service discovery of endpoints. Other
312-
components of the collector such as receivers MAY subscribe to these extensions
313-
to be notified of endpoints coming or going. Observers MAY require certain
314-
permissions in order to perform service discovery. For example, the
315-
`k8s_observer` requires certain RBAC permissions in Kubernetes, while the
316-
`host_observer` requires the Collector to run in privileged mode.
317-
318-
### Subprocesses
319-
320-
Extensions may also be used to run subprocesses. This can be useful when
321-
collection mechanisms that cannot natively be run by the Collector (e.g.
322-
FluentBit). Subprocesses expose a completely separate attack vector that would
323-
depend on the subprocess itself. In general, care should be taken before
324-
running any subprocesses alongside the Collector.

0 commit comments

Comments
 (0)