@cryptotaxi247 / netdata-1 / commits / d55cd6b15

Security and Privacy Design (#20208)

Co-authored-by: Ilya Mashchenko <ilya@netdata.cloud>

kanelatechnical committed Apr 30, 2025 at 14:54 UTC d55cd6b15f913534329000749fc4e27f63ee015a
4 files changed +459 -368
docs/security-and-privacy-design/README.md
+163 -188
@@ -1,272 +1,247 @@
1 # Security and Privacy Design
2
3 -This document serves as the relevant Annex to the [Terms of Service](https://www.netdata.cloud/service-terms/),
4 -the [Privacy Policy](https://www.netdata.cloud/privacy/) and the Data Processing Addendum, when applicable.
5 -It provides more information regarding Netdata’s technical and organizational security and privacy measures.
3 +:::tip
4
7 -We have given special attention to all aspects of Netdata, ensuring that everything throughout its operation is as
8 -secure as possible. Netdata has been designed with security in mind.
5 +**Executive Summary**
6 +
7 +- Netdata is built with security-first principles to protect user data across all systems.
8 +- Observability data remains local, while minimal metadata travels securely to Netdata Cloud.
9 +- We follow best practices to support GDPR, CCPA, PCI DSS, SOC 2, and HIPAA compliance.
10 +
11 +:::
12 +
13 +## Introduction
14 +
15 +This page explains how Netdata designs and operates secure, privacy-respecting services across the Netdata Agent and Netdata Cloud.
16 +
17 +Netdata builds security into every layer. You retain control over your observability data while benefiting from powerful real-time monitoring and insights.
18 +
19 +---
20
21 ## Netdata's Security Principles
22
23 ### Security by Design
24
14 -Netdata, an open-source software widely installed across the globe, prioritizes security by design, showcasing our
15 -commitment to safeguarding user data. The entire structure and internal architecture of the software is built to ensure
16 -maximum security. We aim to provide a secure environment from the ground up, rather than as an afterthought.
25 +Netdata separates your system information into two categories:
26 +
27 +| **Type** | **Description** | **Where It Lives** |
28 +|:-----------------------|:--------------------------------|:------------------------------------------------------------------|
29 +| Observability Data | Metrics and logs | Stored locally, fully under your control |
30 +| Observability Metadata | Hostnames, metric names, alerts | Routed securely to Netdata Cloud for dashboards and notifications |
31 +
32 +This ensures that your critical system insights remain private, and only minimal metadata flows to the cloud.
33 +
34 +### Observability Data and Metadata Flow
35 +
36 +Here is how your data flows through Netdata:
37 +
38 +```mermaid
39 +flowchart TD
40 + A[Your System] -->|Collect metrics and logs| B(Netdata Agent)
41 + B --> C[Observability Data<br/>Stored locally]
42 + B --> D[Observability Metadata<br/>securely routed to Cloud]
43 + D --> E[Cloud dashboards, routing<br/>& notifications]
44 +```
45 +
46 +:::tip
47 +
48 +Observability data (metrics and logs) never leaves your system. Only essential metadata flows securely to Netdata Cloud.
49
18 -Netdata Cloud ensures a secure, user-centric environment for monitoring and troubleshooting, treating
19 -observability data and observability metadata distinctly to maintain user control over system insights and
20 -personal information. **Observability data**, which includes metric values (time series) and log events, remains
21 -fully under user control, stored locally on the user's premises. **Observability metadata**, including hostnames,
22 -metric names, alert names, and alert transitions, is minimally required by Netdata Cloud and securely managed
23 -for routing and platform usage purposes.
50 +:::
51
25 -### Compliance with Open Source Security Foundation Best Practices
52 +### Compliance with Open Source Security Foundation (OSSF) Best Practices
53
27 -Netdata is committed to adhering to the best practices laid out by the Open Source Security Foundation (OSSF).
28 -Currently, the Netdata Agent follows the OSSF best practices at the passing level. Feel free to audit our approach to
29 -the [OSSF guidelines](https://bestpractices.coreinfrastructure.org/en/projects/2231)
54 +Netdata follows [OSSF best practices](https://bestpractices.coreinfrastructure.org/en/projects/2231), including:
55
31 -Netdata Cloud boasts of comprehensive end-to-end automated testing, encompassing the UI, back-end, and Agents, where
32 -involved. In addition, the Netdata Agent uses an array of third-party services for static code analysis,
33 -security analysis, and CI/CD integrations to ensure code quality on a per pull request basis. Tools like GitHub's
34 -CodeQL, GitHub's Dependabot, our own unit tests, various types of linters,
35 -and [Coverity](https://scan.coverity.com/projects/netdata-netdata?tab=overview) are utilized to this end.
56 +- Automated testing across the UI, backend, and Agent
57 +- Static and security code analysis with GitHub CodeQL, Dependabot, linters, and [Coverity](https://scan.coverity.com/projects/netdata-netdata?tab=overview)
58 +- Two senior engineer reviews per pull request
59 +- Continuous stress testing in production-like environments
60
37 -Moreover, each PR requires two code reviews from our senior engineers before being merged. We also maintain two
38 -high-performance environments (a production-like kubernetes cluster and a highly demanding stress lab) for
39 -stress-testing our entire solution. This robust pipeline ensures the delivery of high-quality software consistently.
61 +### Third-Party Testing and Isolation
62
41 -### Regular Third-Party Testing and Isolation
63 +Netdata Agents undergo regular external security audits.
64 +All reports are prioritized for quick investigation and resolution.
65
43 -While Netdata doesn't have a dedicated internal security team, the open-source Netdata Agent undergoes regular testing
44 -by third parties. Any security reports received are addressed immediately. In contrast, Netdata Cloud operates in a
45 -fully automated and isolated environment with Infrastructure as Code (IaC), ensuring no direct access to production
46 -applications. Monitoring and reporting are also fully automated.
66 +Netdata Cloud operates in isolated environments with Infrastructure as Code (IaC). No manual production access exists, and monitoring is fully automated.
67
68 ### Security Vulnerability Response
69
50 -Netdata has a transparent and structured process for handling security vulnerabilities. We appreciate and value the
51 -contributions of security researchers and users who report vulnerabilities to us. All reports are thoroughly
52 -investigated, and any identified vulnerabilities trigger a Security Release Process.
70 +Netdata handles vulnerabilities with a clear process:
71
54 -We aim to fully disclose any bugs as soon as user mitigation is available, typically within a week of the report. In
55 -case of security fixes, we promptly release a new version of the software. Users can subscribe to our releases on GitHub
56 -to stay updated about all security incidents. More details about our vulnerability response process can be
57 -found [here](https://github.com/netdata/netdata/security/policy).
72 +- Full investigation of reported issues
73 +- Mitigation typically within one week
74 +- Immediate patch releases when necessary
75
59 -### Adherence to Open Source Security Foundation Best Practices
76 +:::tip
77
61 -In line with our commitment to security, we uphold the best practices as outlined by the Open Source Security
62 -Foundation. This commitment reflects in every aspect of our operations, from the design phase to the release process,
63 -ensuring the delivery of a secure and reliable product to our users. For more information, check [here](https://bestpractices.coreinfrastructure.org/en/projects/2231).
78 +Stay updated by subscribing to [Netdata’s GitHub releases](https://github.com/netdata/netdata/security/policy).
79 +
80 +:::
81 +
82 +---
83
84 ## Compliance with Regulations
85
67 -Netdata is committed to the highest standards of data security and privacy, complying with the EU's General Data Protection Regulation (GDPR) and California's Consumer Privacy Act (CCPA).
86 +Netdata complies with major data privacy laws, including GDPR and CCPA.
87 +
88 +### GDPR and CCPA Compliance
89 +
90 +Netdata conducts internal audits to ensure compliance and offers Data Processing Agreements (DPAs) upon request.
91
69 -### Compliance with GDPR and CCPA
92 +:::tip
93
71 -Compliance with GDPR and CCPA are self-assessment processes, and Netdata has undertaken thorough internal audits and
72 -controls to ensure it meets all requirements.
94 +Contact Netdata Support to request a DPA.
95
74 -Netdata offers Data Processing Agreements (DPAs) upon request, allowing customers to process personal data in compliance with applicable privacy regulations, including GDPR and CCPA.
96 +:::
97
98 ### Data Transfers
99
78 -While Netdata Agent itself does not engage in any cross-border data transfers, certain **observability metadata** (e.g.,
79 -hostnames, metric names, alert names, and alert transitions) is transferred to Netdata Cloud solely to provide routing
80 -and alert notifications. **Observability data**, consisting of metric values (time series) and log events, stays
81 -strictly within the user's infrastructure, mitigating cross-border data transfer concerns.
100 +| **Type** | **Handling** |
101 +|:-----------------------|:-----------------------------------------------------------------------------|
102 +| Observability Data | Remains on your infrastructure |
103 +| Observability Metadata | Securely transferred and stored in US-based data centers (Google Cloud, AWS) |
104
83 -For users leveraging Netdata Cloud, **observability data** is securely tunneled through Netdata Cloud for real-time
84 -viewing, similar to a VPN, without being stored on Netdata Cloud servers. This approach ensures that Netdata Cloud
85 -maintains only necessary metadata, while full control of observability data remains with the user.
105 +Data is tunneled securely in real-time without being stored on Netdata Cloud servers.
106
87 -Netdata Cloud only stores Netdata Cloud users identification data (such as observability users' email addresses) and
88 -infrastructure metadata (such as infrastructure hostnames) necessary for Netdata Cloud's operation. All these metadata
89 -is stored in data centers in the United States, using compliant infrastructure providers such as Google Cloud and
90 -Amazon Web Services. These transfers and storage are carried out in full compliance with applicable data protection
91 -laws, including GDPR and CCPA.
107 +Data processing complies with GDPR and CCPA requirements.
108
109 ### Privacy Rights
110
95 -Netdata ensures user privacy rights as mandated by the GDPR and CCPA. This includes the right to access, correct, and
96 -delete personal data. These functions are all available online via the Netdata Cloud User Interface (UI). In case a user
97 -wants to remove all personal information (email and activities), they can delete their Netdata Cloud account by logging
98 -into <https://app.netdata.cloud> and accessing their profile, at the bottom left of the screen.
111 +You can manage your privacy rights easily:
112 +
113 +| **Right** | **How to Access** |
114 +|:---------------------------------------|:-------------------------------------------------------------------------------------------------|
115 +| Access, correct, or delete your data | Use the Netdata Cloud UI |
116 +| Fully delete your account and all data | Log in to [app.netdata.cloud](https://app.netdata.cloud), go to Profile, and delete your account |
117 +
118 +:::tip
119 +
120 +Deleting your account removes all associated personal data, including email and activity records.
121
100 -### Regular Review and Updates
122 +:::
123
102 -Netdata is dedicated to keeping its practices up to date with the latest developments in data protection regulations.
103 -Therefore, as soon as updates or changes are made to these regulations, Netdata reviews and updates its policies and
104 -practices accordingly to ensure continual compliance.
124 +### Regular Reviews and Updates
125
106 -While Netdata is confident in its compliance with GDPR and CCPA, users are encouraged to review Netdata's privacy policy
107 -and reach out with any questions or concerns they may have about data protection and privacy.
126 +Netdata continuously updates its policies and technical controls to stay aligned with evolving regulations.
127 +
128 +---
129
130 ## Anonymous Statistics
131
111 -The anonymous statistics collected by the Netdata Agent pertain to installations rather than individual users,
112 -capturing general information such as community size, plugin types, crashes, operating systems, and feature usage.
113 -Importantly, **observability data** — metric values and log events — remain local to the user's infrastructure and
114 -are not collected in this process. **Observability metadata**, including unique IDs for installations, is anonymized
115 -and stored solely to support product development and community understanding.
132 +Netdata collects anonymous installation and telemetry statistics to improve its services.
133 +
134 +| **Collected** | **Used For** |
135 +|:--------------------------------------------------------------|:------------------------------------------------------|
136 +| Installation info (plugins, operating systems, feature usage) | Guide product development and prioritize improvements |
137 +| Telemetry events (errors, performance metrics) | Identify issues and enhance stability |
138 +
139 +- Observability data (metrics and logs) is never collected.
140 +- Metadata is anonymized before storage.
141
117 -Netdata also collects anonymous telemetry events, which provide information on the usage of various features, errors,
118 -and performance metrics. This data is used to understand how the software is being used and to identify areas for
119 -improvement.
142 +### Opting Out
143
121 -The purpose of collecting these statistics and telemetry data is to guide the development of the open-source Agent,
122 -focusing on areas that are most beneficial to users.
144 +You can disable anonymous telemetry:
145
124 -Users can opt out of this data collection during the installation of the Agent, or at any time by
125 -removing a specific file from their system.
146 +- During installation
147 +- Anytime after, by removing the telemetry opt-in file
148
127 -Netdata retains this data indefinitely to track changes and trends within the community over time.
149 +:::tip
150
129 -Netdata doesn’t share these anonymous statistics or telemetry data with any third parties.
151 +See [installation documentation](https://learn.netdata.cloud/docs/agent/packaging/overview) for detailed opt-out steps.
152
131 -By collecting this data, Netdata is able to continuously improve their service and identify any issues or areas for
132 -improvement, while respecting user privacy and maintaining transparency.
153 +:::
154 +
155 +Netdata does not sell or share anonymous statistics with any third parties.
156 +
157 +---
158
159 ## Internal Security Measures
160
136 -Internal Security Measures at Netdata are designed with an emphasis on data privacy and protection. The measures
137 -include:
138 -
139 -1. **Observability data and metadata distinction**
140 - Netdata Cloud securely handles observability metadata in isolated environments, while observability data remains
141 - exclusively within user premises, stored locally and managed by the user. This distinction ensures that only
142 - minimal metadata is required for routing and system identification.
143 -2. **Infrastructure as Code (IaC)** :
144 - Netdata Cloud follows the IaC model, which means it is a microservices environment that is completely isolated. All
145 - changes are managed through Terraform, an open-source IaC software tool that provides a consistent CLI workflow for
146 - managing cloud services.
147 -3. **TLS Termination and IAM Service** :
148 - At the edge of Netdata Cloud, there is a TLS termination, which provides the decryption point for incoming TLS
149 - connections. Additionally, an Identity Access Management (IAM) service validates JWT tokens included in request
150 - cookies or denies access to them.
151 -4. **Session Identification** :
152 - Once inside the microservices environment, all requests are associated with session IDs that identify the user making
153 - the request. This approach provides additional layers of security and traceability.
154 -5. **Data Storage** :
155 - Data is stored in various NoSQL and SQL databases and message brokers. The entire environment is fully isolated,
156 - providing a secure space for data management.
157 -6. **Authentication** :
158 - Netdata Cloud does not store credentials. It offers three types of authentication: GitHub Single Sign-On (SSO),
159 - Google SSO, and email validation.
160 -7. **DDoS Protection** :
161 - Netdata Cloud has multiple protection mechanisms against Distributed Denial of Service (DDoS) attacks, including
162 - rate-limiting and automated blacklisting.
163 -8. **Security-Focused Development Process** :
164 - To ensure a secure environment, Netdata employs a security-focused development process. This includes the use of
165 - static code analyzers to identify potential security vulnerabilities in the codebase.
166 -9. **High Security Standards** :
167 - Netdata Cloud maintains high security standards and can provide additional customization on a per-contract basis.
168 -10. **Employee Security Practices** :
169 - Netdata ensures its employees follow security best practices, including role-based access, periodic access review,
170 - and multifactor authentication. This helps to minimize the risk of unauthorized access to sensitive data.
171 -11. **Experienced Developers** :
172 - Netdata hires senior developers with vast experience in security-related matters. It enforces two code reviews for
173 - every Pull Request (PR), ensuring that any potential issues are identified and addressed promptly.
174 -12. **DevOps Methodologies** :
175 - Netdata's DevOps methodologies use the highest standards in access control in all places, using the best
176 - practices available.
177 -13. **Risk-Based Security Program** :
178 - Netdata has a risk-based security program that continually assesses and mitigates risks associated with data
179 - security. This program helps maintain a secure environment for user data.
161 +Netdata enforces layered security controls:
162
181 -These security measures ensure that Netdata Cloud is a secure environment for users to monitor and troubleshoot their
182 -systems. The company remains committed to continuously improving its security practices to safeguard user data
183 -effectively.
163 +| **Area** | **Control** |
164 +|:--------------------------|:------------------------------------------------|
165 +| Infrastructure Management | Infrastructure as Code (Terraform) |
166 +| Authentication | GitHub SSO, Google SSO, email validation |
167 +| Data Handling | TLS encryption, session tracking |
168 +| Access Control | Role-based access, multi-factor authentication |
169 +| Threat Defense | DDoS protection, vulnerability scanning |
170 +| Developer Process | Static analyzers, mandatory senior code reviews |
171 +| Production Isolation | No direct access to production environments |
172
185 -## PCI DSS
173 +:::tip
174
187 -PCI DSS (Payment Card Industry Data Security Standard) is a set of security standards designed to ensure that all
188 -companies that accept, process, store or transmit credit card information maintain a secure environment.
175 +Need additional security configurations? Contact Netdata Support.
176
190 -Netdata is committed to secure, privacy-focused services that align with key PCI DSS (Payment Card Industry Data Security Standard) principles.
177 +:::
178
192 -Netdata is committed to secure, privacy-focused services that align with key PCI DSS (Payment Card Industry Data Security Standard) principles.
193 -However, it's important to clarify that Netdata is not officially certified as PCI DSS-compliant. While Netdata follows practices that align with PCI DSS's key principles, the company itself has not undergone the formal certification process for PCI DSS compliance.
179 +---
180
195 -PCI DSS compliance is not just about the technical controls but also involves a range of administrative and procedural
196 -safeguards that go beyond the scope of Netdata's services. These include, among other things, maintaining a secure
197 -network, implementing strong access control measures, regularly monitoring and testing networks, and maintaining an
198 -information security policy.
181 +## Standards Alignment
182
200 -Therefore, while Netdata can support entities with their data security needs in relation to PCI DSS, it is ultimately
201 -the responsibility of the entity to ensure full PCI DSS compliance across all of their operations. Entities should
202 -always consult with a legal expert or a PCI DSS compliance consultant to ensure that their use of any product, including
203 -Netdata, aligns with PCI DSS regulations.
183 +### PCI DSS Alignment
184
205 -## HIPAA
185 +Netdata applies practices that align with PCI DSS security principles:
186
207 -HIPAA stands for the Health Insurance Portability and Accountability Act, which is a United States federal law enacted
208 -in 1996. HIPAA is primarily focused on protecting the privacy and security of individuals' health information.
187 +- Secure infrastructure
188 +- Access control
189 +- Encryption practices
190
210 -Netdata is committed to providing secure and privacy-respecting services, and it aligns its practices with many key
211 -principles of HIPAA. However, it's important to clarify that Netdata is not officially certified as HIPAA-compliant.
212 -While Netdata follows practices that align with HIPAA's key principles, the company itself has not undergone the formal
213 -certification process for HIPAA compliance.
191 +However, Netdata is **not officially PCI DSS certified**.
192 +Entities needing full PCI DSS compliance must perform additional assessments.
193
215 -HIPAA compliance is not just about technical controls but also involves a range of administrative and procedural
216 -safeguards that go beyond the scope of Netdata's services. These include, among other things, employee training,
217 -physical security, and contingency planning.
194 +:::tip
195
219 -While Netdata supports HIPAA compliance and offers Business Associate Agreements (BAAs), healthcare entities are responsible for ensuring their overall HIPAA compliance, including their use of Netdata. We recommend consulting HIPAA compliance experts for comprehensive guidance.
196 +Consult a PCI DSS compliance expert if you use Netdata as part of your PCI environment.
197
221 -## SOC 2 Compliance
198 +:::
199
223 -Service Organization Control 2 (SOC 2) is a framework for managing data to ensure the security, availability, processing integrity, confidentiality, and privacy of customer data. Developed by the American Institute of CPAs (AICPA), SOC 2 is specifically designed for service providers storing customer data in the cloud. It requires companies to establish and follow strict information security policies and procedures.
200 +---
201
225 -While Netdata is not currently SOC 2 certified, our commitment to security and privacy aligns closely with the principles of SOC 2. Here’s how Netdata's practices resonate with the key components of SOC 2 compliance:
202 +### HIPAA Alignment
203
227 -### Security
204 +Netdata aligns with HIPAA security practices:
205
229 -Netdata has implemented robust security measures, including infrastructure as code, TLS termination, DDoS protection, and a security-focused development process. These measures echo the SOC 2 principle of ensuring the security of customer data against unauthorized access and potential threats.
206 +- Minimized data handling
207 +- Secure authentication and encryption
208
231 -### Availability
209 +Netdata provides **Business Associate Agreements (BAAs)** for healthcare organizations but is **not HIPAA-certified**.
210
233 -Netdata's commitment to system monitoring and troubleshooting ensures the availability of our service, consistent with the availability principle of SOC 2. Our infrastructure is designed to be resilient and reliable, providing users with continuous access to our services.
211 +:::tip
212
235 -### Processing Integrity
213 +Request a BAA through Netdata Support if required.
214
237 -Although Netdata primarily focuses on system monitoring and doesn’t typically process customer data in a way that alters it, our commitment to accurate, timely, and valid delivery of services aligns with the processing integrity principle of SOC 2.
215 +:::
216
239 -### Confidentiality
217 +---
218
241 -Netdata's measures to protect data—such as data encryption, strict access controls, and data isolation—demonstrate our commitment to confidentiality, ensuring that customer data is accessed only by authorized personnel and for authorized reasons.
219 +### SOC 2 Alignment
220
243 -### Privacy
221 +Netdata’s operations align with SOC 2 Trust Service Criteria:
222
245 -Aligning with the privacy principle of SOC 2, Netdata adheres to GDPR and CCPA regulations, ensuring the protection and proper handling of personal data. Our privacy policies and practices are transparent, giving users control over their data.
223 +| **Principle** | **Practices** |
224 +|:---------------------|:-----------------------------------------|
225 +| Security | TLS encryption, strict access controls |
226 +| Availability | Resilient systems, continuous monitoring |
227 +| Processing Integrity | Reliable metric collection |
228 +| Confidentiality | Metadata isolation, role-based access |
229 +| Privacy | GDPR and CCPA-compliant data handling |
230
247 -### Continuous Improvement and Future Considerations
231 +Netdata is not currently SOC 2 certified but applies equivalent controls.
232
249 -Netdata is committed to continuous improvement in security and privacy. While we aren’t currently SOC 2 certified, we understand the importance of this framework and are continuously evaluating our processes and controls against industry best practices. As Netdata grows and evolves, we remain open to pursuing SOC 2 certification or other similar standards to further demonstrate our dedication to data security and privacy.
233 +---
234
235 ## Conclusion
236
253 -Netdata Cloud is designed to secure observability insights for users, maintaining a clear separation between
254 -observability data and observability metadata. All observability data — metric values and log events — are stored locally,
255 -entirely under user control, while only essential metadata (hostnames, metric names, alert details) is managed by Netdata
256 -Cloud for system routing and alerting.
237 +Netdata gives you a secure and transparent way to monitor your systems.
238 +
239 +With clear separation of observability data and metadata, strong encryption, secure authentication, and compliance with international standards, you retain full ownership and control of your system insights.
240
258 -Netdata Cloud's commitment to data security and user privacy is paramount. From the careful design of the
259 -infrastructure and stringent internal security measures to compliance with international regulations and standards like
260 -GDPR and CCPA, Netdata Cloud ensures a secure environment for users to monitor and troubleshoot their systems.
241 +:::tip
242
262 -The use of advanced encryption techniques, role-based access control, and robust authentication methods further
263 -strengthen the security of user data. Netdata Cloud also maintains transparency in its data handling practices, giving
264 -users control over their data and the ability to easily access, retrieve, correct, and delete their personal data.
243 +**You** are always in control of your data with Netdata.
244
266 -Netdata's approach to an anonymous statistics collection respects user privacy while enabling the company to improve its
267 -product based on real-world usage data. Even in such cases, users have the choice to opt-out, underlining Netdata's
268 -respect for user autonomy.
245 +:::
246
270 -In summary, Netdata Cloud offers a highly secure, user-centric environment for system monitoring and troubleshooting.
271 -The company's emphasis on continuous security improvement and commitment to user privacy make it a trusted choice in the
272 -data monitoring landscape.
247 +Netdata’s commitment to **security, privacy, and transparency** ensures that your monitoring environment stays **protected** and **trusted** at every step.
docs/security-and-privacy-design/netdata-agent-security.md
+125 -44
@@ -1,72 +1,153 @@
1 # Netdata Agent Security and Privacy Design
2
3 -## Security by Design
3 +:::tip
4
5 -Netdata Agent is designed with a security-first approach. Its structure ensures data safety by only exposing chart
6 -metadata and metric values, not the raw data collected. This design principle allows Netdata to be used in environments
7 -requiring the highest level of data isolation, such as PCI Level 1. Even though Netdata plugins connect to a user's
8 -database server or read application log files to collect raw data, only the processed metrics are stored in Netdata
9 -databases, sent to upstream Netdata servers, or archived to external time-series databases.
5 +**Executive Summary**
6 +
7 +- Netdata Agent is designed with a security-first approach to protect system data.
8 +- Raw data never leaves the system where Netdata is installed.
9 +- Only processed metrics and minimal metadata are stored, streamed, or archived.
10 +- Communications are secured with TLS, authentication uses API keys and cryptographic validation, and Agent architecture enforces isolation and resilience.
11 +- Netdata Agent follows best practices supporting PCI DSS, HIPAA, GDPR, and CCPA compliance, and is continuously audited and improved for security.
12 +
13 +:::
14 +
15 +## Introduction
16 +
17 +Netdata Agent uses a security-first design.
18 +It protects data by exposing only chart metadata and metric values, never raw system or application data.
19 +
20 +This design allows Netdata to operate in high-security environments, including PCI Level 1 compliance.
21 +
22 +When plugins collect data from databases or logs, only **processed metrics** are:
23 +
24 +- Stored in Netdata databases
25 +- Sent to upstream Netdata servers
26 +- Archived to external time-series databases
27 +
28 +Raw data remains local and is never transmitted.
29 +
30 +---
31
32 ## User Data Protection
33
13 -> **Note**
14 ->
15 -> Users are responsible for backing up, recovering, and ensuring their data's availability because Netdata stores data locally on each system due to its decentralized architecture.
34 +Netdata Agent safeguards your data at every stage.
35 +
36 +| **Aspect** | **Protection Mechanism** |
37 +|:------------------|:--------------------------------------------------------------------------------------|
38 +| Raw Data | Stays on your system |
39 +| Plugins | Hard-coded for collection only, reject external commands |
40 +| Functions Feature | Predefined plugin functions, UI only calls these |
41 +| Privileges | Most plugins run without escalated privileges; the main process does not require them |
42 +
43 +Plugins needing escalated privileges are isolated:
44 +
45 +- Perform only predefined collection tasks
46 +- Keep raw data inside the local process
47 +- Never save, transfer, or expose raw data to the Netdata daemon
48
17 -The Netdata Agent is programmed to safeguard user data. When collecting data, the raw data does not leave the host. All
18 -plugins, even those running with escalated capabilities or privileges, perform a hard-coded data collection job. They do
19 -not accept commands from Netdata, and the original application data collected do not leave the process they are
20 -collected in, are not saved, and are not transferred to the Netdata daemon. For the “Functions” feature, the data
21 -collection plugins offer Functions, and the user interface merely calls them back as defined by the data collector. The
22 -Netdata Agent main process does not require any escalated capabilities or privileges from the operating system, and
23 -neither do most of the data collecting plugins.
49 +:::tip
50 +
51 +Netdata's decentralized design keeps all data local.
52 +**You are responsible for backing up and managing your system data.**
53 +
54 +:::
55 +
56 +---
57
58 ## Communication and Data Encryption
59
27 -Data collection plugins communicate with the main Netdata process via ephemeral, in-memory, pipes that are inaccessible
28 -to any other process.
60 +Netdata secures all internal and external communications:
61 +
62 +| **Communication** | **Protection** |
63 +|:------------------|:--------------------------------------------------------------------|
64 +| Plugins to Daemon | Ephemeral in-memory pipes, isolated from other processes |
65 +| Streaming Metrics | Requires API keys, optional TLS encryption |
66 +| Web API | Supports TLS if configured |
67 +| Cloud Connection | MQTT over WebSockets over TLS with public/private key authorization |
68
30 -Streaming of metrics between Netdata Agents requires an API key and can also be encrypted with TLS if the user
31 -configures it.
69 +Public and private keys are exchanged securely during Cloud provisioning.
70
33 -The Netdata Agent's web API can also use TLS if configured.
71 +### Netdata Agent Security Flow
72
35 -When Netdata Agents are connected to the Cloud, the communication happens via MQTT over Web Sockets over TLS, and
36 -public/private keys are used for authorizing access. These keys are exchanged during the connecting process (usually
37 -during the provisioning of each Agent).
73 +```mermaid
74 +flowchart TD
75 + A[Netdata Plugin] -->|Collects raw data| B[In-memory Processing]
76 + B -->|Processes into metrics| C[Netdata Daemon]
77 + C -->|Stores metrics locally| D[Netdata Database]
78 + C -->|Optionally streams metrics| E[Another Netdata Agent]
79 + C -->|Optionally sends metadata| F[Netdata Cloud]
80 + F --> G[Dashboards <br/>&<br/> Notifications]
81 +```
82 +
83 +---
84
85 ## Authentication
86
41 -Direct user access to the Agent is not authenticated, considering that users should either use Netdata Cloud, or they
42 -are already on the same LAN, or they have configured proper firewall policies. However, Netdata Agents can be hidden
43 -behind an authenticating web proxy if required.
87 +Netdata supports multiple authentication methods depending on the connection type:
88 +
89 +| **Connection** | **Authentication Method** |
90 +|:-------------------------|:------------------------------------------------------------------------|
91 +| Direct Agent Access | Typically unauthenticated, relies on LAN isolation or firewall policies |
92 +| Streaming Between Agents | Requires API key authentication, optional TLS |
93 +| Agent-to-Cloud | Public/private key cryptography with mandatory TLS |
94 +
95 +:::tip
96 +
97 +For additional access control, place Netdata Agents behind an authenticating web proxy.
98
45 -For other Netdata Agents streaming metrics to an Agent, authentication via API keys is required and TLS can be used if
46 -configured.
99 +:::
100
48 -For Netdata Cloud accessing Netdata Agents, public/private key cryptography is used and TLS is mandatory.
101 +---
102
103 ## Security Vulnerability Response
104
52 -If a security vulnerability is found in the Netdata Agent, the Netdata team acknowledges and analyzes each report within
53 -three working days, kicking off a Security Release Process. Any vulnerability information shared with the Netdata team
54 -stays within the Netdata project and is not disseminated to other projects unless necessary for fixing the issue. The
55 -reporter is kept updated as the security issue moves from triage to identified fix, to release planning. More
56 -information can be found [here](https://github.com/netdata/netdata/security/policy).
105 +Netdata follows a structured vulnerability response process:
106 +
107 +- Acknowledges reports within three business days
108 +- Initiates a Security Release Process for verified issues
109 +- Releases patches promptly
110 +- Handles vulnerability information confidentially
111 +- Keeps reporters updated throughout the process
112 +
113 +:::tip
114 +
115 +Learn more in [Netdata's GitHub Security Policy](https://github.com/netdata/netdata/security/policy).
116 +
117 +:::
118 +
119 +---
120
121 ## Protection Against Common Security Threats
122
60 -The Netdata Agent is resilient against common security threats such as DDoS attacks and SQL injections. For DDoS, the Agent uses a fixed number of threads for processing requests, providing a cap on the resources that can be
61 -consumed. It also automatically manages its memory to prevent over-utilization. SQL injections are prevented as nothing
62 -from the UI is passed back to the data collection plugins accessing databases.
123 +Netdata Agent is resilient against major security threats:
124 +
125 +| **Threat** | **Defense Mechanism** |
126 +|:---------------------------|:---------------------------------------------------------------------------|
127 +| DDoS Attacks | Fixed thread counts, automatic memory management, resource prioritization |
128 +| SQL Injections | No UI data passed back to database-accessing plugins |
129 +| System Resource Starvation | Nice priority protects production apps, early termination in OS-OOM events |
130 +
131 +Additional protections include:
132 +
133 +- Running as an unprivileged user by default
134 +- Isolating escalated privileges to specific collectors
135 +- Proactive CPU and memory management
136
64 -Additionally, the Agent is running as a normal, unprivileged, operating system user (a few data collections
65 -require escalated privileges, but these privileges are isolated to just them), every netdata process runs by default
66 -with a nice priority to protect production applications in case the system is starving for CPU resources, and Netdata
67 -agents are configured by default to be the first processes to be killed by the operating system in case the operating
68 -system starves for memory resources (OS-OOM - Operating System Out Of Memory events).
137 +---
138
139 ## User-Customizable Security Settings
140
72 -Netdata provides users with the flexibility to customize the Agent's security settings. Users can configure TLS across the system, and the Agent provides extensive access control lists on all its interfaces to limit access to its endpoints based on IP. Additionally, users can configure the CPU and Memory priority of Netdata Agents.
141 +You can tailor the Agent's security settings:
142 +
143 +| **Setting** | **Options Available** |
144 +|:----------------------------|:-------------------------------------------------|
145 +| TLS Encryption | Configurable for web API and streaming |
146 +| Access Control Lists (ACLs) | Limit endpoint access by IP address |
147 +| CPU/Memory Priority | Adjust scheduling priority and memory thresholds |
148 +
149 +:::tip
150 +
151 +Use Netdata configuration files to apply custom security settings.
152 +
153 +:::
docs/security-and-privacy-design/netdata-cloud-security.md
+105 -74
@@ -1,116 +1,147 @@
1 # Netdata Cloud Security and Privacy Design
2
3 -Netdata Cloud is designed with a security-first approach to ensure the highest level of protection for user data. When
4 -using Netdata Cloud in environments that require compliance with standards like PCI DSS, SOC 2, or HIPAA, users can be
5 -confident that all collected data is stored within their infrastructure. Data viewed on dashboards and alert
6 -notifications travel over Netdata Cloud, but aren’t stored—instead, they're transformed in transit, aggregated from
7 -multiple Agents and parents (centralization points), to appear as one data source in the user's browser.
3 +:::tip
4 +
5 +**Executive Summary**
6 +
7 +- Netdata Cloud offers secure real-time monitoring without storing raw metrics.
8 +- Only minimal metadata passes securely through Netdata Cloud.
9 + Users retain full control of their data.
10 +- Infrastructure is protected with strong encryption, access control, and compliance with GDPR, CCPA, PCI DSS, SOC 2, and HIPAA standards.
11 +- Netdata Cloud continuously evolves its security and privacy practices to meet the highest industry standards.
12 +
13 +:::
14 +
15 +## Introduction
16 +
17 +Netdata Cloud enables secure real-time system insights without storing raw metrics.
18 +
19 +Data passes through Netdata Cloud securely but isn't retained. Metric views and alerts from multiple Agents display as a unified dashboard in your browser.
20
21 ## User Identification and Authorization
22
11 -Netdata Cloud requires only an email address to create an account and use the service. User identification and
12 -authorization are conducted either via third-party integrations (Google, GitHub accounts) or through short-lived access
13 -tokens sent to the user’s email account. Email addresses are stored securely in our production database on AWS and are
14 -also used for product and marketing communications. Netdata Cloud doesn’t store user credentials.
23 +Netdata Cloud requires only an email address for accounts.
24 +
25 +| **Method** | **Details** |
26 +|:---------------|:---------------------------------------------------|
27 +| Identification | Email via Google, GitHub, or short-lived tokens |
28 +| Credentials | No passwords stored |
29 +| Storage | Secure AWS storage; used for product and marketing |
30 +
31 +Authentication uses third-party integrations or secure tokens. Netdata Cloud never stores credentials.
32
33 ## Data Storage and Transfer
34
18 -Although Netdata Cloud doesn’t store metric data, it does keep some metadata for each node connected to user spaces.
19 -This metadata includes the hostname, information from the `/api/v1/info` endpoint, metric metadata
20 -from `/api/v1/contexts`, and alerts configurations from `/api/v1/alarms`. This data is securely stored in our production
21 -database on AWS and copied to Google BigQuery for analytics purposes.
35 +Netdata Cloud stores no raw metrics, only essential metadata:
36
23 -All data visible on Netdata Cloud is transferred through the Agent-Cloud link (ACLK) mechanism, which securely connects
24 -a Netdata Agent to Netdata Cloud. The ACLK is encrypted and safe, and is only established if the user connects/claims
25 -their node. Data in transit between a user and Netdata Cloud is encrypted using TLS.
37 +| **Metadata Stored** | **Source** |
38 +|:---------------------|:----------------------------|
39 +| Hostname | `/api/v1/info` endpoint |
40 +| Metric Metadata | `/api/v1/contexts` endpoint |
41 +| Alerts Configuration | `/api/v1/alarms` endpoint |
42
27 -## Data Retention and Erasure
43 +All metadata is stored in AWS and copied to Google BigQuery for analytics.
44
29 -Netdata Cloud retains deleted customer content for 90 days. Users can access, modify, and delete their personal data through self-service tools. If needed, users can request data deletion in writing, which Netdata will process in accordance with data protection laws.
45 +Metric data travels via secure Agent-Cloud Link (ACLK):
46
31 -## Infrastructure and Authentication
47 +- ACLK encrypts data and activates only for claimed nodes
48 +- All user-Cloud communication uses TLS encryption
49
33 -Netdata Cloud operates on an Infrastructure as Code (IaC) model. Its microservices environment is completely isolated,
34 -and all changes occur through Terraform. At the edge of Netdata Cloud, there is a TLS termination and an Identity and
35 -Access Management (IAM) service that validates JWT tokens included in request cookies.
50 +### ACLK Secure Data Flow
51
37 -Netdata Cloud does not store user credentials.
52 +```mermaid
53 +flowchart TD
54 + A[Netdata Agent] -->|Encrypts metrics<br/>and minimal metadata| B[Agent-Cloud Link ACLK]
55 + B -->|TLS Encryption| C[Netdata Cloud]
56 + C -->|Aggregates metadata<br/>for dashboards and alerts| D[User Browser]
57
39 -## Security Features and Response
58 +```
59
41 -Netdata Cloud offers a variety of security features, including infrastructure-level dashboards, centralized alert notifications, auditing logs, and role-based access to different segments of the infrastructure. It employs several protection mechanisms against DDoS attacks, such as rate-limiting and automated blocklisting. It also uses static code analyzers to prevent other types of attacks.
60 +## Data Retention and Erasure
61
43 -In the event of potential security vulnerabilities or incidents, Netdata Cloud follows the same process as the Netdata
44 -agent. Every report is acknowledged and analyzed by the Netdata team within three working days, and the team keeps the
45 -reporter updated throughout the process.
62 +| **Process** | **Details** |
63 +|:----------------|:----------------------------------------------------|
64 +| Retention | Deleted content kept 90 days |
65 +| Self-Service | Modify/delete personal data via Cloud UI |
66 +| Manual Requests | Written deletion requests processed under data laws |
67
47 -## User Customization
68 +:::tip
69
49 -Netdata Cloud uses the highest level of security. There is no user customization available out of the box. Its security
50 -settings are designed to provide maximum protection for all users. We are offering customization (like custom SSO
51 -integrations, custom data retention policies, advanced user access controls, tailored audit logs, integration with other
52 -security tools, etc.) on a per-contract basis.
70 +Users can delete accounts and data directly from their Netdata Cloud profile.
71
54 -## Deleting Personal Data
72 +:::
73
56 -Users who wish to remove all personal data (including email and activities) can delete their account by logging into Netdata Cloud and accessing their profile.
74 +## Infrastructure and Authentication
75
58 -## User Privacy and Data Protection
76 +Netdata Cloud uses Infrastructure as Code (IaC).
77
60 -Netdata Cloud is built with an unwavering commitment to user privacy and data protection. We understand that our users'
61 -data is both sensitive and valuable, and we’ve implemented stringent measures to ensure its safety.
78 +| **Feature** | **Implementation** |
79 +|:------------------------|:-------------------------------------|
80 +| Infrastructure Changes | Managed via Terraform |
81 +| Authentication | JWT tokens at TLS termination points |
82 +| Microservices Isolation | Complete environment separation |
83
63 -### Data Collection
84 +Netdata Cloud never stores user credentials.
85
65 -Netdata Cloud collects minimal personal information from its users. The only personal data required to create an account
66 -and use the service is an email address. This email address is used for product and marketing communications.
67 -Additionally, the IP address used to access Netdata Cloud is stored in web proxy access logs.
86 +## Security Features and Incident Response
87
69 -### Data Usage
88 +Built-in security protections include:
89
71 -The collected email addresses are stored in our production database on Amazon Web Services (AWS) and copied to Google
72 -BigQuery, our data lake, for analytics purposes. These analytics are crucial for our product development process. If a
73 -user accepts the use of analytical cookies, their email address and IP are stored in the systems we use to track
74 -application usage (Google Analytics, Posthog, and Gainsight PX). Stripe handles subscriptions and Payments data.
90 +| **Feature** | **Details** |
91 +|:--------------------------|:-----------------------------------|
92 +| Infrastructure Dashboards | Centralized monitoring/alerting |
93 +| Audit Logs | Role-based access tracking |
94 +| DDoS Protection | Rate-limiting and blacklisting |
95 +| Secure Development | Static analyzers and secure coding |
96
76 -### Data Sharing
97 +Security vulnerabilities follow a structured process:
98
78 -Netdata Cloud does not share any personal data with third parties, ensuring the privacy of our users' data, but Netdata
79 -Cloud does use third parties for its services, including, but not limited to, Google Cloud and Amazon Web Services for
80 -its infrastructure, Stripe for payment processing, Google Analytics, Posthog and Gainsight PX for analytics.
99 +- Acknowledge within three business days
100 +- Analyze and fix promptly
101 +- Maintain communication with reporters
102
82 -### Data Protection
103 +:::tip
104
84 -We use the newest security measures to protect user data from unauthorized access, use, or disclosure. All
85 -infrastructure data visible on Netdata Cloud passes through the Agent-Cloud Link (ACLK) mechanism, which securely
86 -connects a Netdata Agent to Netdata Cloud. The ACLK is encrypted, safe, and is only established if the user connects
87 -their node. All data in transit between a user and Netdata Cloud is encrypted using TLS.
105 +See [Netdata's GitHub Security Policy](https://github.com/netdata/netdata/security/policy) for details.
106
89 -### User Control over Data
107 +:::
108
91 -Netdata provides its users with the ability to access, retrieve, correct, and delete their personal data stored in Netdata Cloud.
92 -This ability may occasionally be limited due to temporary service outages for maintenance or other updates to Netdata Cloud, or when it is technically not possible.
93 -If self-service data deletion isn't possible, Netdata will process written deletion requests within DPA-specified timeframes, in compliance with data protection laws.
109 +## User Customization
110 +
111 +Netdata Cloud uses maximum security defaults without out-of-box customization.
112
95 -### Compliance with Data Protection Laws
113 +Per-contract customization options include:
114
97 -Netdata Cloud is fully compliant with data protection laws like the General Data Protection Regulation (GDPR) and the
98 -California Consumer Privacy Act (CCPA).
115 +- Custom SSO
116 +- Custom retention policies
117 +- Advanced access controls
118 +- Tailored audit logs
119 +- Third-party security tool integration
120
100 -### Data Transfer
121 +Contact Netdata Sales for enterprise solutions.
122
102 -Data transfer within Netdata Cloud is secure and respects the privacy of the user data. The Netdata Agent establishes an
103 -outgoing secure WebSocket (WSS) connection to Netdata Cloud, ensuring that the data is encrypted when in transit.
123 +## Deleting Personal Data
124
105 -### Use of Tracking Technologies
125 +Users can delete personal data by:
126
107 -Netdata Cloud uses analytical cookies if a user consents to their use. These cookies are used to track the usage of the
108 -application and are stored in systems like Google Analytics, Posthog and Gainsight PX.
127 +- Logging into Netdata Cloud
128 +- Accessing Profile settings
129 +- Initiating account deletion
130
110 -### Data Breach Notification Process
131 +If self-service isn't available, submit written requests processed under applicable laws.
132
112 -In the event of a data breach, Netdata has a well-defined process in place for notifying users. The details of this
113 -process align with the standard procedures and timelines defined in the Data Protection Agreement (DPA).
133 +## User Privacy and Data Protection
134
115 -We continually review and update our privacy and data protection practices to ensure the highest level of data safety
116 -and privacy for our users.
135 +Netdata Cloud prioritizes privacy and data protection, continuously reviewing and updating privacy and security practices.
136 +
137 +| **Category** | **Details** |
138 +|:--------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
139 +| **Data Collection** | • Email Address (account, communication, analytics)<br/>• IP Address (web proxy access logs) |
140 +| **Data Usage** | • Stored in AWS databases<br/>• Copied to BigQuery for analytics<br/>• Used for product improvement<br/>• With consent, tracking via Google Analytics, Posthog, and Gainsight PX<br/>• Stripe for secure payment handling |
141 +| **Data Sharing** | • No selling or sharing of personal data<br/>• Third-party services: Google Cloud/AWS (infrastructure), Stripe (payments), Analytics services |
142 +| **Data Protection** | • Encrypted ACLK for all infrastructure data<br/>• TLS encryption for all user-Cloud communication |
143 +| **User Control** | • Access personal data<br/>• Correct inaccuracies<br/>• Retrieve personal data<br/>• Delete accounts<br/>• Note: Temporary maintenance may limit access |
144 +| **Compliance** | • Full compliance with GDPR and CCPA |
145 +| **Data Transfer** | • Secure, encrypted WebSocket (WSS) connections for all transfers |
146 +| **Tracking Technologies** | • With consent: analytical cookies tracked via Google Analytics, Posthog, and Gainsight PX |
147 +| **Data Breach Protocol** | • Follows DPA guidelines and industry timelines<br/>• User notifications as required by data protection laws<br/>• Continuous review and updates to privacy and security practices |
docs/security-and-privacy-design/netdata-kubernetes.md
+66 -62
@@ -1,4 +1,3 @@
1 -
1 # Netdata Container Security Considerations
2
3 Netdata provides powerful, real-time performance monitoring and health visibility, offering deep insights essential for managing modern infrastructure, particularly dynamic containerized environments like Kubernetes. Its high-granularity metrics and comprehensive system overview help teams troubleshoot issues quickly and optimize performance effectively.
@@ -14,56 +13,62 @@ The goal is to enable organizations to tailor their Netdata deployment, striking
13 Netdata is architected with security as a core consideration, employing a robust privilege separation model designed to minimize attack surfaces and isolate operations that require elevated permissions. This model applies both to the overall deployment architecture and the internal workings of the Netdata agent itself.
14
15 ### Parent / Child Deployment Architecture
16 +
17 In typical Kubernetes deployments, Netdata utilizes a hierarchical structure with two main roles:
18
19 -- **`Parent` Pods:** These act as central aggregation points. They receive data streams from multiple child pods. Crucially, `Parent` pods are designed to run as **completely unprivileged containers**. They do not require access to host paths, host namespaces, or any special Linux capabilities. Their primary role is data aggregation, storage, and exposing Netdata's API and dashboard or connecting to Netdata Cloud for servicing the dashboard.
20 -- **`Child` Pods (Agents):** A `child` pod runs as a DaemonSet on each monitored node. Its responsibility is to collect detailed metrics, query logs, and other information directly from the node it resides on. To achieve comprehensive host and container monitoring, the `child` pod is the component that may require specific host resource access (mounts, namespaces) and potentially elevated Linux capabilities.
19 +- **`Parent` Pods:** These act as central aggregation points. They receive data streams from multiple child pods. Crucially, `Parent` pods are designed to run as **completely unprivileged containers**. They do not require access to host paths, host namespaces, or any special Linux capabilities. Their primary role is data aggregation, storage, and exposing Netdata's API and dashboard or connecting to Netdata Cloud for servicing the dashboard.
20 +- **`Child` Pods (Agents):** A `child` pod runs as a DaemonSet on each monitored node. Its responsibility is to collect detailed metrics, query logs, and other information directly from the node it resides on. To achieve comprehensive host and container monitoring, the `child` pod is the component that may require specific host resource access (mounts, namespaces) and potentially elevated Linux capabilities.
21
22 This architecture ensures that the components responsible for broader network exposure and data storage (Parents) run with minimal privileges, while the necessary host access is confined to the node-local `child` agents.
23
24 ### Internal Privilege Separation within `Child` Agents
25 +
26 Even within the `child` agent container, which might be granted elevated permissions by Kubernetes (e.g., host mounts, capabilities), Netdata enforces strict internal privilege separation:
27
27 -- **Unprivileged Core Daemon:** The main `netdata` daemon process, which orchestrates data collection, communicates with the parent, and handles basic tasks, runs as a **non-root user** (typically the `netdata` user). Key internal plugins responsible for collecting core metrics, such as `proc.plugin` (for `/proc` based metrics) and `cgroups.plugin` (for container metrics via `/sys/fs/cgroup`), also run as threads within this unprivileged daemon process.
28 -- **Dedicated Privileged Helpers/Plugins:** Operations that require elevated privileges or specific capabilities to access protected host resources (e.g., detailed process information via `apps.plugin`, certain network operations via `network-viewer.plugin` or `cgroup-network`, logs querying via `systemd-journal.plugin`) are delegated to **dedicated external plugins or helper processes**.
29 -- **Isolation via `setuid`:** These external plugins/helpers run as separate, isolated processes spawned by the main daemon. Within the container, the specific helper executables requiring elevated rights are configured with the **`setuid` root** permission bit. This standard Linux mechanism allows only these designated programs to execute specific, pre-defined tasks with root privileges _within the container's environment_.
30 -- **Contained Capabilities:** Consequently, even if the _container_ is granted capabilities like `SYS_ADMIN` or `SYS_PTRACE`, the unprivileged main `netdata` daemon and its non-`setuid` plugins **cannot** directly utilize these capabilities. Only the specific `setuid` root helpers designed for tasks needing those privileges can effectively leverage them.
31 -- **Narrowly Scoped Tasks:** Each privileged helper is designed to perform a narrow, hard-coded task – typically reading specific system information and passing it back to the main daemon.
32 -- **Text-Based Communication:** Communication between the main daemon and its external plugins occurs over a simple, text-based protocol, further reducing the risk associated with potentially malicious binary data exchange.
28 +- **Unprivileged Core Daemon:** The main `netdata` daemon process, which orchestrates data collection, communicates with the parent, and handles basic tasks, runs as a **non-root user** (typically the `netdata` user). Key internal plugins responsible for collecting core metrics, such as `proc.plugin` (for `/proc` based metrics) and `cgroups.plugin` (for container metrics via `/sys/fs/cgroup`), also run as threads within this unprivileged daemon process.
29 +- **Dedicated Privileged Helpers/Plugins:** Operations that require elevated privileges or specific capabilities to access protected host resources (e.g., detailed process information via `apps.plugin`, certain network operations via `network-viewer.plugin` or `cgroup-network`, logs querying via `systemd-journal.plugin`) are delegated to **dedicated external plugins or helper processes**.
30 +- **Isolation via `setuid`:** These external plugins/helpers run as separate, isolated processes spawned by the main daemon. Within the container, the specific helper executables requiring elevated rights are configured with the **`setuid` root** permission bit. This standard Linux mechanism allows only these designated programs to execute specific, pre-defined tasks with root privileges _within the container's environment_.
31 +- **Contained Capabilities:** Consequently, even if the _container_ is granted capabilities like `SYS_ADMIN` or `SYS_PTRACE`, the unprivileged main `netdata` daemon and its non-`setuid` plugins **cannot** directly utilize these capabilities. Only the specific `setuid` root helpers designed for tasks needing those privileges can effectively leverage them.
32 +- **Narrowly Scoped Tasks:** Each privileged helper is designed to perform a narrow, hard-coded task – typically reading specific system information and passing it back to the main daemon.
33 +- **Text-Based Communication:** Communication between the main daemon and its external plugins occurs over a simple, text-based protocol, further reducing the risk associated with potentially malicious binary data exchange.
34
35 ### Security Benefit
36 +
37 This multi-layered privilege separation model significantly minimizes the attack surface. The vast majority of the Netdata agent's code, including the core daemon and primary metric collectors, runs without root privileges. Elevated permissions are isolated to specific, purpose-built helper processes with limited scope. This design helps contain the risk even when the Netdata `child` container requires privileged access to the host system for comprehensive monitoring. Compromising the main unprivileged daemon does not automatically grant an attacker root access or the ability to use the container's granted capabilities.
38
39 ## Network Exposure and Access Control
40 +
41 Beyond internal process separation within the agent, Netdata's deployment architecture incorporates several features designed to limit network exposure and manage data access securely, particularly in the recommended parent/child configuration.
42
43 ### Child Agent Network Limitations
44 +
45 Netdata `child` agents (running on each monitored node) are designed with minimal required network interaction to reduce their direct attack surface:
46
43 -- **Outbound-Only to Parent:** Their primary network function is to stream collected data **outbound** exclusively to their designated `parent` pod(s) within the cluster. This connection can be further secured using transport layer security (TLS) and optional mutual TLS (mTLS) for certificate-based authentication between child and parent.
44 -- **Restricted Inbound Connections:** By default, standard configurations (like the official Helm chart) configure `child` agents to listen **only on the localhost interface (127.0.0.1)**. This prevents them from accepting incoming network connections from other pods, nodes, or external sources.
45 -- **No Direct Cloud Connectivity Needed:** `Child` agents **do not require** direct internet connectivity to the Netdata Cloud service. All communication is proxied through the parent(s).
47 +- **Outbound-Only to Parent:** Their primary network function is to stream collected data **outbound** exclusively to their designated `parent` pod(s) within the cluster. This connection can be further secured using transport layer security (TLS) and optional mutual TLS (mTLS) for certificate-based authentication between child and parent.
48 +- **Restricted Inbound Connections:** By default, standard configurations (like the official Helm chart) configure `child` agents to listen **only on the localhost interface (127.0.0.1)**. This prevents them from accepting incoming network connections from other pods, nodes, or external sources.
49 +- **No Direct Cloud Connectivity Needed:** `Child` agents **do not require** direct internet connectivity to the Netdata Cloud service. All communication is proxied through the parent(s).
50
51 ### Parent Agent Role and Centralized Access via Netdata Cloud
52 +
53 `Parent` pods act as the aggregation points and data access gateways:
54
50 -- **Central Aggregation:** They receive data streams from multiple child agents.
51 -- **Optional Direct Access:** Parents expose the Netdata API and dashboard. While direct access is possible, it requires careful network policy configuration within the cluster.
52 -- **Recommended Cloud Integration:** The typical and recommended approach, especially for managing multiple nodes or clusters, involves securely connecting the `parent` pods **outbound** to Netdata Cloud.
53 -- **Centralized RBAC via Cloud:** Netdata Cloud serves as the primary user interface and provides essential access control mechanisms. This includes **Role-Based Access Control (RBAC)**, allowing administrators to:
54 - - Manage users and team memberships.
55 - - Segment the infrastructure into "rooms" (by service, component type, location, etc)
56 - - Assign roles with differing permission levels.
57 - - Associate users with infrastructure, by granting users access to specific "rooms".
55 +- **Central Aggregation:** They receive data streams from multiple child agents.
56 +- **Optional Direct Access:** Parents expose the Netdata API and dashboard. While direct access is possible, it requires careful network policy configuration within the cluster.
57 +- **Recommended Cloud Integration:** The typical and recommended approach, especially for managing multiple nodes or clusters, involves securely connecting the `parent` pods **outbound** to Netdata Cloud.
58 +- **Centralized RBAC via Cloud:** Netdata Cloud serves as the primary user interface and provides essential access control mechanisms. This includes **Role-Based Access Control (RBAC)**, allowing administrators to:
59 + - Manage users and team memberships.
60 + - Segment the infrastructure into "rooms" (by service, component type, location, etc)
61 + - Assign roles with differing permission levels.
62 + - Associate users with infrastructure, by granting users access to specific "rooms".
63
64 ### Security Benefits
65
66 This layered network architecture significantly enhances security:
67
63 -- It drastically limits the direct network exposure of the potentially privileged `child` agents.
64 -- It centralizes data egress and user access points at the `parent` level.
65 -- It leverages Netdata Cloud for robust, centralized authentication and Role-Based Access Control, moving access management off the individual nodes.
66 -- It supports encrypted and mutually authenticated communication channels between agents and parents.
68 +- It drastically limits the direct network exposure of the potentially privileged `child` agents.
69 +- It centralizes data egress and user access points at the `parent` level.
70 +- It leverages Netdata Cloud for robust, centralized authentication and Role-Based Access Control, moving access management off the individual nodes.
71 +- It supports encrypted and mutually authenticated communication channels between agents and parents.
72
73 ## Permissions for Complete Host and Container Monitoring
74
@@ -73,54 +78,54 @@ The following sections describe all the possible mounts, capabilities and host n
78
79 Mounting specific host directories into the Netdata container provides essential data access for various collection plugins.
80
76 -| Mount | Type | Role | Component | Why |
77 -|:---:|:---:|:---:|:---:|:---|
78 -| `/`| hostPath | child | `diskspace.plugin` | Detect host mount points (only in Docker deployments, not in Kubernetes deployments). |
79 -| `/etc/os-release` | hostPath | child | `netdata` | Collect host labels. |
80 -| `/etc/passwd`<br/>`/etc/group` | hostPath | child | `apps.plugin` | Resolve numeric users and groups to names. |
81 -| `/etc/passwd`<br/>`/etc/group` | hostPath | child | `network-viewer.plugin` | Resolve numeric users and groups to names. |
82 -| `/proc` | hostPath | child | `proc.plugin` | Monitor host system resources (CPU, Memory, Network, uptime, etc). |
83 -| `/proc` | hostPath | child | `apps.plugin` | Monitor all running processes. |
84 -| `/proc` | hostPath | child | `cgroups.plugin` | Detect available memory to calculate container memory limits. Detect paused containers in k8s to improve discovery performance. |
85 -| `/proc` | hostPath | child | `cgroup-network` | Discover container virtual network interfaces and associates them with running containers. |
86 -| `/proc` | hostPath | child | `network-viewer.plugin` | Monitor all TCP/UDP sockets of running processes, including the ones outside containers, or inside sibling containers. |
87 -| `/proc` | hostPath | child<br/>k8sState | `netdata` | Collect system information and detect various system characteristics like number of CPU cores, total and available memory protection, and more. |
88 -| `/sys` | hostPath | child | `cgroups.plugin` | Monitor containers. |
89 -| `/sys` | hostPath | child<br/>k8sState | `netdata` | Detect `netdata` container limits. Detect host hardware (part of system info). |
90 -| `/sys` | hostPath | child | `proc.plugin` | Detect network interface types. Monitor software RAID block devices. Detect ZRAM, GPUs, Numa Nodes, Infiniband, BTRFS, PCI AEC, EDAC MC, KSM, BCACHE, CPU thermal throttling. |
91 -| `/sys` | hostPath | child | `debugfs.plugin` | Monitor hardware sensors, ZSWAP, Numa Memory Fragmentation, PowerCap. |
92 -| `/var/log` | hostPath | child | `systemd-journal.plugin` | Enable the Logs pipeline of Netdata to process and query system logs. |
93 -| `/var/lib/netdata`* | hostPath | child | `netdata` | Persist of Netdata's private data. |
81 +| Mount | Type | Role | Component | Why |
82 +|:------------------------------:|:--------:|:------------------:|:------------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
83 +| `/` | hostPath | child | `diskspace.plugin` | Detect host mount points (only in Docker deployments, not in Kubernetes deployments). |
84 +| `/etc/os-release` | hostPath | child | `netdata` | Collect host labels. |
85 +| `/etc/passwd`<br/>`/etc/group` | hostPath | child | `apps.plugin` | Resolve numeric users and groups to names. |
86 +| `/etc/passwd`<br/>`/etc/group` | hostPath | child | `network-viewer.plugin` | Resolve numeric users and groups to names. |
87 +| `/proc` | hostPath | child | `proc.plugin` | Monitor host system resources (CPU, Memory, Network, uptime, etc). |
88 +| `/proc` | hostPath | child | `apps.plugin` | Monitor all running processes. |
89 +| `/proc` | hostPath | child | `cgroups.plugin` | Detect available memory to calculate container memory limits. Detect paused containers in k8s to improve discovery performance. |
90 +| `/proc` | hostPath | child | `cgroup-network` | Discover container virtual network interfaces and associates them with running containers. |
91 +| `/proc` | hostPath | child | `network-viewer.plugin` | Monitor all TCP/UDP sockets of running processes, including the ones outside containers, or inside sibling containers. |
92 +| `/proc` | hostPath | child<br/>k8sState | `netdata` | Collect system information and detect various system characteristics like number of CPU cores, total and available memory protection, and more. |
93 +| `/sys` | hostPath | child | `cgroups.plugin` | Monitor containers. |
94 +| `/sys` | hostPath | child<br/>k8sState | `netdata` | Detect `netdata` container limits. Detect host hardware (part of system info). |
95 +| `/sys` | hostPath | child | `proc.plugin` | Detect network interface types. Monitor software RAID block devices. Detect ZRAM, GPUs, Numa Nodes, Infiniband, BTRFS, PCI AEC, EDAC MC, KSM, BCACHE, CPU thermal throttling. |
96 +| `/sys` | hostPath | child | `debugfs.plugin` | Monitor hardware sensors, ZSWAP, Numa Memory Fragmentation, PowerCap. |
97 +| `/var/log` | hostPath | child | `systemd-journal.plugin` | Enable the Logs pipeline of Netdata to process and query system logs. |
98 +| `/var/lib/netdata`* | hostPath | child | `netdata` | Persist of Netdata's private data. |
99
100 Notes:
101
97 -- **Persistence Note:** The `/var/lib/netdata` host path mount (configurable via `{{ .Values.child.persistence.hostPath }}/var/lib/netdata` in Helm charts) is critical for maintaining node identity across restarts. This directory stores metadata, _not_ the time-series database, and is relatively small. Without this persistence, each pod restart registers as a new node.
102 +- **Persistence Note:** The `/var/lib/netdata` host path mount (configurable via `{{ .Values.child.persistence.hostPath }}/var/lib/netdata` in Helm charts) is critical for maintaining node identity across restarts. This directory stores metadata, _not_ the time-series database, and is relatively small. Without this persistence, each pod restart registers as a new node.
103 - **Read-Only Mounts**: All the mounts described above, except `/var/lib/netdata`, are mounted read-only.
104
105 ### Host Namespaces
106
107 Utilizing host namespaces allows Netdata to observe network activity and processes as they appear on the host, rather than being confined to the container's isolated view.
108
104 -| Namespace | Role | Component | Type | Why |
105 -|:---:|:---:|:---:|:---:|:---|
106 -| Host Network Namespace | child | `proc.plugin` | Internal Plugin | Monitor host's networking stack (the IPv4 and IPv6 Networking Stack). <br/>`proc.plugin` runs unprivileged.<br/>&nbsp;<br/>Without this, Netdata will monitor the networking stack of the container it runs, not the one of the host. |
107 -| Host Network Namespace | child | `cgroup-network` | External Helper | Used by `cgroups.plugin` to map virtual network interfaces to the containers they belong. The helper requires also special capabilities. <br/>`cgroups.plugin` runs unprivileged.<br/>&nbsp;<br/>Without this, Netdata will monitor only the network interfaces of the container it runs, not the network interfaces of its sibling containers (or the host). |
108 -| Host Network Namespace | child | `local-listeners` | External Helper | Used by `go.d.plugin` to discover applications running at the host (including sibling containers). It requires also special capabilities. <br/>`go.d.plugin` runs unprivileged.<br/>&nbsp;<br/>Without this, Netdata will not be able to auto-detect and monitor applications running at the host or its sibling containers. Kubernetes based service discovery is not affected. |
109 -| Host Network Namespace | child | `network-viewer.plugin` | External Plugin | Discover and continuously monitor the host's network connections (including the ones of sibling containers). It requires also special capabilities. <br/>`network-viewer.plugin` runs with escalated privileges.<br/>&nbsp;<br/>Without this, Netdata will monitor only the connections of the container it runs, not the connections of the host or its sibling containers. |
110 -| Host PID Namespace | child | `cgroup-network` | External Helper | Used by `cgroups.plugin` to detect containers' network interfaces.<br/>`cgroups.plugin` runs unprivileged.<br/>&nbsp;<br/>Without this, Netdata will not be able to associate virtual network interfaces to the containers they belong. |
109 +| Namespace | Role | Component | Type | Why |
110 +|:----------------------:|:-----:|:-----------------------:|:---------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
111 +| Host Network Namespace | child | `proc.plugin` | Internal Plugin | Monitor host's networking stack (the IPv4 and IPv6 Networking Stack). <br/>`proc.plugin` runs unprivileged.<br/>&nbsp;<br/>Without this, Netdata will monitor the networking stack of the container it runs, not the one of the host. |
112 +| Host Network Namespace | child | `cgroup-network` | External Helper | Used by `cgroups.plugin` to map virtual network interfaces to the containers they belong. The helper requires also special capabilities. <br/>`cgroups.plugin` runs unprivileged.<br/>&nbsp;<br/>Without this, Netdata will monitor only the network interfaces of the container it runs, not the network interfaces of its sibling containers (or the host). |
113 +| Host Network Namespace | child | `local-listeners` | External Helper | Used by `go.d.plugin` to discover applications running at the host (including sibling containers). It requires also special capabilities. <br/>`go.d.plugin` runs unprivileged.<br/>&nbsp;<br/>Without this, Netdata will not be able to auto-detect and monitor applications running at the host or its sibling containers. Kubernetes based service discovery is not affected. |
114 +| Host Network Namespace | child | `network-viewer.plugin` | External Plugin | Discover and continuously monitor the host's network connections (including the ones of sibling containers). It requires also special capabilities. <br/>`network-viewer.plugin` runs with escalated privileges.<br/>&nbsp;<br/>Without this, Netdata will monitor only the connections of the container it runs, not the connections of the host or its sibling containers. |
115 +| Host PID Namespace | child | `cgroup-network` | External Helper | Used by `cgroups.plugin` to detect containers' network interfaces.<br/>`cgroups.plugin` runs unprivileged.<br/>&nbsp;<br/>Without this, Netdata will not be able to associate virtual network interfaces to the containers they belong. |
116
117 ### Linux Capabilities
118
119 Specific Linux capabilities grant elevated privileges necessary for certain monitoring functions, particularly those involving process inspection and namespace manipulation.
120
116 -| Capability | Role | Component | Type | Why |
117 -|:---:|:---:|:---:|:---:|:---|
118 -| SYS_ADMIN | child | `cgroup-network` | External Helper | Used by `cgroups.plugin` to associate virtual network interfaces to the containers the belong.<br/>&nbsp;<br/>Without this, virtual network interfaces will not be associated to their respective containers, so they will be monitored as host network interfaces. |
119 -| SYS_ADMIN | child | `network-viewer.plugin` | External Plugin | Discover containers' network connections (it does so by switching Network Namespaces).<br/>&nbsp;<br/>Without this, Netdata will not be able to associate Network connections with processes. |
120 -| SYS_ADMIN | child | `local-listeners` | External Helper | Helper used by `go.d.plugin` to discover listening applications running at the host.<br/>&nbsp;<br/>Without this, localhost service discovery (not the kubernetes one) will not work. |
121 -| SYS_PTRACE | child | `apps.plugin` | External Plugin | Collect the I/O per running process at the host (including the ones in containers).<br/>&nbsp;<br/>Without this, processes will be monitored excluding their physical or logical disk I/O. |
122 -| SYS_PTRACE | child | `local-listeners` | External Helper | Helper used by `go.d.plugin` to discover listening applications running at the host.<br/>&nbsp;<br/>Without this, localhost service discovery (not the kubernetes one) will be based only on port number, without the process name. |
123 -| SYS_PTRACE | child | `network-viewer.plugin` | External Plugin | Discover host's network connections per application. Without it all host network connections will still be monitored, but Netdata will not be able to associate them with processes. |
121 +| Capability | Role | Component | Type | Why |
122 +|:----------:|:-----:|:-----------------------:|:---------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
123 +| SYS_ADMIN | child | `cgroup-network` | External Helper | Used by `cgroups.plugin` to associate virtual network interfaces to the containers the belong.<br/>&nbsp;<br/>Without this, virtual network interfaces will not be associated to their respective containers, so they will be monitored as host network interfaces. |
124 +| SYS_ADMIN | child | `network-viewer.plugin` | External Plugin | Discover containers' network connections (it does so by switching Network Namespaces).<br/>&nbsp;<br/>Without this, Netdata will not be able to associate Network connections with processes. |
125 +| SYS_ADMIN | child | `local-listeners` | External Helper | Helper used by `go.d.plugin` to discover listening applications running at the host.<br/>&nbsp;<br/>Without this, localhost service discovery (not the kubernetes one) will not work. |
126 +| SYS_PTRACE | child | `apps.plugin` | External Plugin | Collect the I/O per running process at the host (including the ones in containers).<br/>&nbsp;<br/>Without this, processes will be monitored excluding their physical or logical disk I/O. |
127 +| SYS_PTRACE | child | `local-listeners` | External Helper | Helper used by `go.d.plugin` to discover listening applications running at the host.<br/>&nbsp;<br/>Without this, localhost service discovery (not the kubernetes one) will be based only on port number, without the process name. |
128 +| SYS_PTRACE | child | `network-viewer.plugin` | External Plugin | Discover host's network connections per application. Without it all host network connections will still be monitored, but Netdata will not be able to associate them with processes. |
129
130 IMPORTANT: All the plugins or helpers that utilize these capabilities are isolated from the rest of Netdata. This means that all the other plugins of Netdata and the main Netdata daemon cannot utilize these capabilities, even when the capabilities have been given to the whole container Netdata is installed.
131
@@ -301,7 +306,7 @@ This configuration runs the Netdata `child` agent with **minimal privileges**, m
306
307 **Monitoring Scope (Limitation):** **Severely limited.** Netdata primarily monitors **only its own container's resource consumption** (CPU, memory, its own processes, network traffic within its isolated namespace). It gains **no visibility** into the host's overall performance, other containers, host processes, host network stack, or host system logs.
308
304 - _Note:_ If Kubernetes RBAC permissions are granted, Netdata can still collect **Kubernetes state metrics** (node/pod counts, status, etc.) via the K8s API. Application metrics might be collected if exposed by other pods and reachable via standard K8s networking, but without host-level correlation.
309 +_Note:_ If Kubernetes RBAC permissions are granted, Netdata can still collect **Kubernetes state metrics** (node/pod counts, status, etc.) via the K8s API. Application metrics might be collected if exposed by other pods and reachable via standard K8s networking, but without host-level correlation.
310
311 **Security Risk Profile:** **Lowest.** This configuration offers the best security isolation for the Netdata agent, posing minimal direct risk to the host or other containers from the agent itself.
312
@@ -311,9 +316,9 @@ This configuration runs the Netdata `child` agent with **minimal privileges**, m
316
317 This configuration aims for substantial observability while mitigating the highest risks, assuming Netdata is the primary observability platform and acknowledging its security practices.
318
314 - - **Permissions Included:** Host path mounts `/proc` (ro), `/sys` (ro), `/etc/os-release` (ro), `/etc/passwd` (ro), `/etc/group` (ro), `/var/log` (ro), `/var/lib/netdata` (rw); Host PID and Network Namespace.
319 +- **Permissions Included:** Host path mounts `/proc` (ro), `/sys` (ro), `/etc/os-release` (ro), `/etc/passwd` (ro), `/etc/group` (ro), `/var/log` (ro), `/var/lib/netdata` (rw); Host PID and Network Namespace.
320
316 - - **Permissions Excluded (by Default):** Linux capabilities `SYS_ADMIN` and `SYS_PTRACE`; Host path mount `/` (for K8s).
321 +- **Permissions Excluded (by Default):** Linux capabilities `SYS_ADMIN` and `SYS_PTRACE`; Host path mount `/` (for K8s).
322
323 **Monitoring Scope (Benefit):** Provides **comprehensive core monitoring** capabilities: host system performance (CPU, Mem, Disk, Basic Net I/O via `/proc`), container discovery and resource usage (via cgroups in `/sys`), host-wide process listing (via Host PID and `/proc`), and integrated host system log analysis (via `/var/log` mount). Agent persistence is maintained.
324
@@ -323,7 +328,6 @@ This configuration aims for substantial observability while mitigating the highe
328
329 **Use Case:** A **sensible default baseline** for organizations deploying Netdata as their primary observability platform in security-conscious environments. It offers a strong balance of visibility and risk reduction. Enabling the excluded higher-risk permissions should be a conscious decision, requiring justification and formal risk acceptance if specific advanced features are deemed essential.
330
326 -
331 ## Conclusion
332
333 Netdata offers extensive real-time visibility into containerized environments like Kubernetes, providing invaluable data for performance optimization, troubleshooting, and understanding system health. Achieving this deep level of insight, however, inherently requires granting the Netdata agent specific permissions to access host resources, including file system mounts, host namespaces, and potentially powerful Linux capabilities.