| 1 | # Configure Netdata for cybersecurity platforms |
| 2 | |
| 3 | This guide is intended to help you place Netdata behind enterprise security controls such as reverse proxies, firewalls, VPN gateways, or secure-access platforms. The UI differs by product, but the Netdata-side configuration and network design remain the same. |
| 4 | |
| 5 | ## Choose how users should access Netdata |
| 6 | |
| 7 | Before you configure your security platform, choose the Netdata access model that fits your environment: |
| 8 | |
| 9 | | Access model | Best for | Netdata configuration | |
| 10 | |-----------------------------------------------------|------------------------------------------------------------------------------------|----------------------------------------------------------------------------| |
| 11 | | Cloud-only access | Environments that do not allow inbound access to the Agent | Disable the local dashboard with `mode = none` | |
| 12 | | Access through a security platform or reverse proxy | Environments that publish Netdata through HTTPS, SSO, VPN, or application gateways | Keep Netdata on a private interface and allow only the gateway path | |
| 13 | | Access on a private management network | Environments with a dedicated admin network | Bind Netdata only to the management interface and restrict allowed clients | |
| 14 | |
| 15 | If you are not sure which model to use, start with the smallest exposed surface: |
| 16 | |
| 17 | 1. Use **Cloud-only access** to give users dashboard access through Netdata Cloud without exposing the Agent directly. |
| 18 | 2. Use **access through a security platform** if you must publish the local dashboard to users. |
| 19 | 3. Use **private management network access** only when you already have a trusted admin network. |
| 20 | |
| 21 | ## Configure Cloud-only access |
| 22 | |
| 23 | Use this pattern when your security platform mainly controls outbound traffic and users access dashboards via Netdata Cloud instead of connecting directly to port `19999`. |
| 24 | |
| 25 | ### Prerequisites |
| 26 | |
| 27 | - Your Agent is [claimed to Netdata Cloud](/src/claim/README.md) |
| 28 | - Your environment allows the Agent to maintain its secure outbound Cloud connection |
| 29 | |
| 30 | 1. Edit `netdata.conf` with the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) script. |
| 31 | |
| 32 | 2. Disable the local dashboard: |
| 33 | |
| 34 | ```ini |
| 35 | [web] |
| 36 | mode = none |
| 37 | ``` |
| 38 | |
| 39 | 3. Restart the Agent. For platform-specific steps, see [Edit Configuration Files](/docs/netdata-agent/configuration/README.md#edit-configuration-files). |
| 40 | |
| 41 | 4. Verify that dashboards remain available from Netdata Cloud. |
| 42 | |
| 43 | For step-by-step operational details, see: |
| 44 | |
| 45 | - [Edit Configuration Files](/docs/netdata-agent/configuration/README.md#edit-configuration-files) |
| 46 | - [Secure Your Netdata Agent with Bearer Token Protection](/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) |
| 47 | |
| 48 | The Agent web server stops accepting inbound requests. This reduces exposure, but it also disables inbound streaming. Do not use this setting on Parent Agents that receive data from Child Agents. |
| 49 | |
| 50 | ## Configure access through a cybersecurity platform |
| 51 | |
| 52 | Use this pattern when a platform such as Sophos, an authenticating reverse proxy, or a secure-access gateway publishes Netdata to users over HTTPS. |
| 53 | |
| 54 | ### Prerequisites |
| 55 | |
| 56 | - A private IP address or loopback interface that the Netdata Agent can bind to |
| 57 | - A gateway, reverse proxy, firewall portal, or secure-access platform that can reach the Agent on that private address |
| 58 | - A decision on authentication: |
| 59 | - Use the external platform for authentication, or |
| 60 | - Use Netdata bearer token protection with Netdata Cloud identities |
| 61 | |
| 62 | 1. Bind Netdata to a private interface instead of exposing it on every address: |
| 63 | |
| 64 | ```ini |
| 65 | [web] |
| 66 | bind to = 10.0.0.15:19999 localhost:19999 |
| 67 | ``` |
| 68 | |
| 69 | Replace `10.0.0.15` with the private interface your security platform can reach. |
| 70 | |
| 71 | 2. If you want direct Netdata authorization through Netdata Cloud, enable bearer token protection: |
| 72 | |
| 73 | ```ini |
| 74 | [web] |
| 75 | bind to = 10.0.0.15:19999 localhost:19999 |
| 76 | bearer token protection = yes |
| 77 | ``` |
| 78 | |
| 79 | This keeps the dashboard available only on the private interface while requiring Cloud authentication for data access. |
| 80 | |
| 81 | 3. Restart the Agent. For platform-specific steps, see [Edit Configuration Files](/docs/netdata-agent/configuration/README.md#edit-configuration-files). |
| 82 | |
| 83 | 4. Publish the Agent through your security platform using the private Netdata address as the upstream target. |
| 84 | |
| 85 | Use an internal upstream such as: |
| 86 | |
| 87 | ```text |
| 88 | http://10.0.0.15:19999 |
| 89 | ``` |
| 90 | |
| 91 | The platform should terminate HTTPS, apply your organization's authentication and policy controls, and forward requests only to this private Netdata endpoint. |
| 92 | |
| 93 | 5. Restrict network access so only the security platform path can reach Netdata on port `19999`. |
| 94 | |
| 95 | In practice, this usually means: |
| 96 | |
| 97 | - No direct public inbound access to `19999` |
| 98 | - Only the reverse proxy, VPN users, or management network can reach the private Netdata address |
| 99 | - Firewall rules block all other sources |
| 100 | |
| 101 | For implementation details and hardening examples, see: |
| 102 | |
| 103 | - [Running Netdata Behind a Reverse Proxy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/README.md) |
| 104 | - [Secure Your Netdata Agent with Bearer Token Protection](/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) |
| 105 | |
| 106 | ### Authentication choices for published access |
| 107 | |
| 108 | If the external platform already authenticates users, you can rely on it and keep Netdata on a private address. If you want Netdata Cloud roles and permissions to apply when users open the Agent directly through the published URL, enable [bearer token protection](/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md). |
| 109 | |
| 110 | Use bearer token protection when: |
| 111 | |
| 112 | - You want Netdata Cloud SSO and role-based permissions |
| 113 | - You do not want to manage per-proxy password files |
| 114 | - Your Agent is claimed and connected to Netdata Cloud |
| 115 | |
| 116 | Use external-platform authentication only when: |
| 117 | |
| 118 | - The platform must remain the primary identity provider for the published application |
| 119 | - You need an access path that does not depend on Netdata Cloud authentication |
| 120 | |
| 121 | ## Configure private management network access |
| 122 | |
| 123 | Use this pattern when administrators already use a private LAN, VPN, or bastion network and you do not want to publish Netdata through a broader application gateway. |
| 124 | |
| 125 | 1. Bind Netdata to the management interface: |
| 126 | |
| 127 | ```ini |
| 128 | [web] |
| 129 | bind to = 10.1.1.1:19999 localhost:19999 |
| 130 | ``` |
| 131 | |
| 132 | 2. Restrict who can connect: |
| 133 | |
| 134 | ```ini |
| 135 | [web] |
| 136 | bind to = 10.1.1.1:19999 localhost:19999 |
| 137 | allow connections from = localhost 10.* |
| 138 | ``` |
| 139 | |
| 140 | 3. Restart the Agent. For platform-specific steps, see [Edit Configuration Files](/docs/netdata-agent/configuration/README.md#edit-configuration-files). |
| 141 | |
| 142 | 4. Verify that the dashboard is reachable only from the management network. |
| 143 | |
| 144 | For detailed operational steps, see: |
| 145 | |
| 146 | - [Edit Configuration Files](/docs/netdata-agent/configuration/README.md#edit-configuration-files) |
| 147 | - [Securing Netdata Agents](/docs/netdata-agent/securing-netdata-agents.md) |
| 148 | |
| 149 | ## Network rules your cybersecurity platform should enforce |
| 150 | |
| 151 | No matter which product you use, your platform design should follow these rules: |
| 152 | |
| 153 | - Do not expose `19999` directly to the public internet |
| 154 | - Prefer HTTPS on the published entry point |
| 155 | - Allow inbound access only through your approved gateway, VPN, proxy, or management network |
| 156 | - Allow outbound Agent connectivity to Netdata Cloud if you use claiming, Cloud dashboards, or bearer token protection |
| 157 | - Keep Netdata on private IPs whenever possible |
| 158 | |
| 159 | If you deploy Netdata Parents, apply the same principle to the Parent dashboard. Child Agents should stream to Parents over trusted paths instead of being individually exposed. |
| 160 | |
| 161 | ### Example architecture for platforms such as Sophos |
| 162 | |
| 163 | Platforms such as Sophos are typically used to enforce one or more of these controls: |
| 164 | |
| 165 | - Reverse-proxy publishing |
| 166 | - Web access policies |
| 167 | - VPN-based access |
| 168 | - Firewall-based source restrictions |
| 169 | |
| 170 | The exact product workflow differs, but the architecture usually looks like this: |
| 171 | |
| 172 | 1. Users authenticate to the organization's approved security platform. |
| 173 | 2. The platform forwards approved requests to a private Netdata address such as `http://10.0.0.15:19999`. |
| 174 | 3. Netdata accepts traffic only from that controlled path. |
| 175 | 4. Netdata Cloud remains the preferred dashboard path when direct local access is not required. |
| 176 | |
| 177 | This approach keeps Netdata aligned with enterprise security controls without requiring public exposure of the Agent. |
| 178 | |
| 179 | ## Sophos Central example for Windows exclusions |
| 180 | |
| 181 | :::note |
| 182 | |
| 183 | This is a **vendor-specific example**. Use it as a pattern and adapt it to your platform's equivalent exclusion workflow and policy controls. |
| 184 | |
| 185 | ::: |
| 186 | |
| 187 | If you run the Netdata Agent on Windows and Sophos Central blocks or interferes with the Netdata executable, add a global exclusion for the Netdata binary. |
| 188 | |
| 189 | In our testing, Sophos did not flag the Netdata binary as malicious. Sophos may still block Netdata because the Agent monitors network traffic and CPU activity on the host, which can trigger behavior-based protections. |
| 190 | |
| 191 | :::note |
| 192 | |
| 193 | Sophos Central labels and layout may change over time. The steps below reflect the current workflow. |
| 194 | |
| 195 | ::: |
| 196 | |
| 197 | 1. Open **Global Settings** in Sophos Central: |
| 198 | |
| 199 | ```text |
| 200 | https://central.sophos.com/manage/overview/settings-list |
| 201 | ``` |
| 202 | |
| 203 | 2. Open **Global Exclusions**. |
| 204 | |
| 205 | 3. Select **Add exclusions**. |
| 206 | |
| 207 | 4. In the new window, add an exclusion for: |
| 208 | |
| 209 | - **Exploit Mitigation Activity Monitoring (Windows)** |
| 210 | |
| 211 | 5. When Sophos asks for the path, enter: |
| 212 | |
| 213 | ```text |
| 214 | C:\Program Files\Netdata\usr\bin\netdata.exe |
| 215 | ``` |
| 216 | |
| 217 | 6. Clear **Protect Application**. |
| 218 | |
| 219 | 7. Select **Save**. |
| 220 | |
| 221 | This exclusion applies to the Windows Netdata executable path shown above. |
| 222 | |
| 223 | Map this exclusion into your broader access model and network controls in [Network rules your cybersecurity platform should enforce](#network-rules-your-cybersecurity-platform-should-enforce). |
| 224 | |
| 225 | ## What's next? |
| 226 | |
| 227 | - Review [Securing Netdata Agents](/docs/netdata-agent/securing-netdata-agents.md) for the broader list of supported hardening options |
| 228 | - Use [Secure Your Netdata Agent with Bearer Token Protection](/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) if you want Netdata Cloud SSO on published Agent URLs |
| 229 | - Use [Running the Agent behind a reverse proxy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/README.md) for web-server-specific proxy examples |