| 1 | # Netdata Agent Security and Privacy Design |
| 2 | |
| 3 | :::tip |
| 4 | |
| 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 | ## User Data Protection |
| 31 | |
| 32 | Netdata Agent safeguards your data at every stage. |
| 33 | |
| 34 | | **Aspect** | **Protection Mechanism** | |
| 35 | |:------------------|:--------------------------------------------------------------------------------------| |
| 36 | | Raw Data | Stays on your system | |
| 37 | | Plugins | Hard-coded for collection only, reject external commands | |
| 38 | | Functions Feature | Predefined plugin functions, UI only calls these | |
| 39 | | Privileges | Most plugins run without escalated privileges; the main process does not require them | |
| 40 | |
| 41 | Plugins needing escalated privileges are isolated: |
| 42 | |
| 43 | - Perform only predefined collection tasks |
| 44 | - Keep raw data inside the local process |
| 45 | - Never save, transfer, or expose raw data to the Netdata daemon |
| 46 | |
| 47 | :::tip |
| 48 | |
| 49 | Netdata's decentralized design keeps all data local. |
| 50 | **You are responsible for backing up and managing your system data.** |
| 51 | |
| 52 | ::: |
| 53 | |
| 54 | ## Communication and Data Encryption |
| 55 | |
| 56 | Netdata secures all internal and external communications: |
| 57 | |
| 58 | | **Communication** | **Protection** | |
| 59 | |:------------------|:--------------------------------------------------------------------| |
| 60 | | Plugins to Daemon | Ephemeral in-memory pipes, isolated from other processes | |
| 61 | | Streaming Metrics | Requires API keys, optional TLS encryption | |
| 62 | | Web API | Supports TLS if configured | |
| 63 | | Cloud Connection | MQTT over WebSockets over TLS with public/private key authorization | |
| 64 | |
| 65 | Public and private keys are exchanged securely during Cloud provisioning. |
| 66 | |
| 67 | ### Netdata Agent Security Flow |
| 68 | |
| 69 | ```mermaid |
| 70 | flowchart TD |
| 71 | A("Netdata Plugin") -->|"Collects raw data"| B("In-memory Processing") |
| 72 | B -->|"Processes into metrics"| C("Netdata Daemon") |
| 73 | C -->|"Stores metrics locally"| D("Netdata Database") |
| 74 | C -->|"Optionally streams metrics"| E("Another Netdata Agent") |
| 75 | C -->|"Optionally sends metadata"| F("Netdata Cloud") |
| 76 | F --> G("Dashboards<br/>& Notifications") |
| 77 | |
| 78 | %% Style definitions |
| 79 | classDef alert fill:#ffeb3b,stroke:#000000,stroke-width:3px,color:#000000,font-size:14px |
| 80 | classDef neutral fill:#f9f9f9,stroke:#000000,stroke-width:3px,color:#000000,font-size:14px |
| 81 | classDef complete fill:#4caf50,stroke:#000000,stroke-width:3px,color:#000000,font-size:14px |
| 82 | classDef database fill:#2196F3,stroke:#000000,stroke-width:3px,color:#000000,font-size:14px |
| 83 | |
| 84 | %% Apply styles |
| 85 | class A alert |
| 86 | class B,C neutral |
| 87 | class D,E complete |
| 88 | class F,G database |
| 89 | ``` |
| 90 | |
| 91 | ## Authentication |
| 92 | |
| 93 | Netdata supports multiple authentication methods depending on the connection type: |
| 94 | |
| 95 | | **Connection** | **Authentication Method** | |
| 96 | |:-------------------------|:------------------------------------------------------------------------| |
| 97 | | Direct Agent Access | Typically unauthenticated, relies on LAN isolation or firewall policies | |
| 98 | | Streaming Between Agents | Requires API key authentication, optional TLS | |
| 99 | | Agent-to-Cloud | Public/private key cryptography with mandatory TLS | |
| 100 | |
| 101 | :::tip |
| 102 | |
| 103 | For additional access control, place Netdata Agents behind an authenticating web proxy. |
| 104 | |
| 105 | ::: |
| 106 | |
| 107 | ## Security Vulnerability Response |
| 108 | |
| 109 | Netdata follows a structured vulnerability response process: |
| 110 | |
| 111 | - Acknowledges reports within three business days |
| 112 | - Initiates a Security Release Process for verified issues |
| 113 | - Releases patches promptly |
| 114 | - Handles vulnerability information confidentially |
| 115 | - Keeps reporters updated throughout the process |
| 116 | |
| 117 | :::tip |
| 118 | |
| 119 | Learn more in [Netdata's GitHub Security Policy](https://github.com/netdata/netdata/security/policy). |
| 120 | |
| 121 | ::: |
| 122 | |
| 123 | ## Protection Against Common Security Threats |
| 124 | |
| 125 | Netdata Agent is resilient against major security threats: |
| 126 | |
| 127 | | **Threat** | **Defense Mechanism** | |
| 128 | |:---------------------------|:---------------------------------------------------------------------------| |
| 129 | | DDoS Attacks | Fixed thread counts, automatic memory management, resource prioritization | |
| 130 | | SQL Injections | No UI data passed back to database-accessing plugins | |
| 131 | | System Resource Starvation | Nice priority protects production apps, early termination in OS-OOM events | |
| 132 | |
| 133 | Additional protections include: |
| 134 | |
| 135 | - Running as an unprivileged user by default |
| 136 | - Isolating escalated privileges to specific collectors |
| 137 | - Proactive CPU and memory management |
| 138 | |
| 139 | ## User-Customizable Security Settings |
| 140 | |
| 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 | ::: |