Netdata API Permissions and Access Control Analysis

Generated: 2025-10-02 Purpose: Document ACL and HTTP_ACCESS requirements for all 68 Netdata APIs

Permission System Overview

HTTP_ACL (Access Control List)

Controls HOW the API can be accessed (transport/source):

• HTTP_ACL_NOCHECK - No ACL checking (always allow based on other criteria)
• HTTP_ACL_API - Via HTTP/HTTPS web server (TCP port 19999)
• HTTP_ACL_ACLK - Via ACLK only (Netdata Cloud connection)
• HTTP_ACL_WEBRTC - Via WebRTC connection
• HTTP_ACL_METRICS - Metrics data access category
• HTTP_ACL_FUNCTIONS - Functions execution category
• HTTP_ACL_NODES - Node information category
• HTTP_ACL_ALERTS - Alerts access category
• HTTP_ACL_DYNCFG - Dynamic configuration category
• HTTP_ACL_REGISTRY - Registry access category
• HTTP_ACL_BADGES - Badges generation category
• HTTP_ACL_MANAGEMENT - Management operations category
• HTTP_ACL_STREAMING - Streaming category
• HTTP_ACL_NETDATACONF - Netdata configuration category

HTTP_ACCESS (Permission Flags)

Controls WHAT the authenticated user can do (capabilities):

• HTTP_ACCESS_NONE - No specific access required (public)
• HTTP_ACCESS_SIGNED_ID - User must be authenticated
• HTTP_ACCESS_SAME_SPACE - User and agent must be in same Netdata Cloud space
• HTTP_ACCESS_COMMERCIAL_SPACE - Requires commercial plan
• HTTP_ACCESS_ANONYMOUS_DATA - Can view basic metrics/data
• HTTP_ACCESS_SENSITIVE_DATA - Can view sensitive information
• HTTP_ACCESS_VIEW_AGENT_CONFIG - Can read agent configuration
• HTTP_ACCESS_EDIT_AGENT_CONFIG - Can modify agent configuration
• HTTP_ACCESS_VIEW_NOTIFICATIONS_CONFIG - Can read notifications config
• HTTP_ACCESS_EDIT_NOTIFICATIONS_CONFIG - Can modify notifications config
• HTTP_ACCESS_VIEW_ALERTS_SILENCING - Can read silencing rules
• HTTP_ACCESS_EDIT_ALERTS_SILENCING - Can modify silencing rules

HTTP_USER_ROLE

User roles with hierarchical permissions (lower number = more permissions):

1. HTTP_USER_ROLE_ADMIN - Full administrative access
2. HTTP_USER_ROLE_MANAGER - Management access
3. HTTP_USER_ROLE_TROUBLESHOOTER - Diagnostic access
4. HTTP_USER_ROLE_OBSERVER - Read-only access
5. HTTP_USER_ROLE_MEMBER - Basic member access
6. HTTP_USER_ROLE_BILLING - Billing-related access
7. HTTP_USER_ROLE_ANY - Any authenticated user

V3 APIs (27 total) - CURRENT/LATEST

Public Data APIs (Accessible by anyone, local or cloud)

These require only HTTP_ACCESS_ANONYMOUS_DATA - available to all users including unauthenticated:

Public Info APIs (No authentication required)

These have HTTP_ACL_NOCHECK and HTTP_ACCESS_NONE:

ACLK-Only APIs (Netdata Cloud Access Required)

These require HTTP_ACL_ACLK - ONLY accessible via Netdata Cloud (ACLK):

Note: ACL_DEV_OPEN_ACCESS flag makes these available in dev mode without ACLK restriction.

V2 APIs (17 total) - DEPRECATED

All V2 APIs have same ACL/access as their V3 equivalents:

Public Data APIs

Public Info APIs

ACLK-Only APIs

V1 APIs (24 total) - DEPRECATED

Public Data APIs

Alert APIs

Node Info APIs

Special APIs

Security Summary by Category

1. ACLK-Only APIs (Cloud Access Required)

Count: 6 APIs (3 v3, 3 v2)

These APIs are ONLY accessible through Netdata Cloud (ACLK connection):

• rtc_offer - WebRTC setup (Experimental feature, not compiled by default)
• bearer_protection - Requires admin/manager permissions
• bearer_get_token - Generate authentication tokens

Access Requirement: User must be authenticated (SIGNED_ID) and in the same Netdata Cloud space as the agent (SAME_SPACE)

Cannot be accessed via: Direct HTTP/HTTPS to agent (even with bearer token)

Note: WebRTC (rtc_offer) is an experimental feature and is not compiled by default. It requires special build configuration.

2. Optionally Protected Data APIs (Bearer Protection Configurable)

Count: 47 APIs across all versions

These provide read access to metrics, alerts, and metadata with HTTP_ACCESS_ANONYMOUS_DATA.

Default Mode (Public):

• No authentication required
• Available to local dashboard, cloud users, external tools
• Subject to IP-based ACL restrictions in netdata.conf

Bearer Protection Mode (when enabled):

• Requires valid bearer token for access
• Bearer tokens obtained via /api/v*/bearer_get_token (ACLK-only)
• Still subject to IP-based ACL restrictions
• Provides token-based authentication layer

Configuration: Set bearer protection via /api/v*/bearer_protection API or netdata.conf

3. Configuration APIs (Permissions Checked Per-Action)

Count: 3 APIs

• /api/v*/config - Read operations allowed for all, write operations check permissions internally
• /api/v*/function - Execution permissions checked per-function by plugins
• /api/v1/manage - Manages permissions internally

Note: These respect bearer protection if enabled (they have HTTP_ACCESS_ANONYMOUS_DATA)

4. Always Public APIs (Cannot Be Restricted)

Count: 12 APIs

These have HTTP_ACL_NOCHECK meaning they bypass ALL security:

• Agent info
• Version info
• Progress tracking
• Current user info
• Settings (user preferences)
• Claiming (protected by security key mechanism, not ACL/bearer)

Important: These are ALWAYS accessible:

• NOT affected by bearer protection
• NOT subject to IP-based ACL
• Cannot be restricted by any configuration

Important: These APIs are ALWAYS public and cannot be restricted:

• NOT subject to IP-based ACL restrictions
• NOT subject to bearer protection
• Always accessible without authentication

Permission Checking Flow

1. ACL Check (web_api.c:65-67)

   cCopy

   bool acl_allows = ((w->acl & api_commands[i].acl) == api_commands[i].acl)
                     || (api_commands[i].acl & HTTP_ACL_NOCHECK);
   

   • Verifies request came through allowed transport (API, ACLK, WebRTC)
   • Verifies request matches allowed feature category

2. Access Check (web_api.c:69-72)

   cCopy

   bool permissions_allows =
       http_access_user_has_enough_access_level_for_endpoint(
           w->user_auth.access, api_commands[i].access);
   

   • Verifies user has required permission flags
   • Checks user role has sufficient access level

3. Internal Permission Checks

   • Some APIs (config, function, registry, manage) perform additional permission validation within their implementation
   • These check specific actions or function-level permissions

Configuration Impact

netdata.conf ACL Settings

IP-based ACL restrictions can be applied to feature categories:

[web]
    allow connections from = localhost *
    allow dashboard from = *
    allow badges from = *
    allow streaming from = *
    allow netdata.conf from = localhost fd* 10.* 192.168.* 172.16.* 172.17.* 172.18.* 172.19.* 172.20.* 172.21.* 172.22.* 172.23.* 172.24.* 172.25.* 172.26.* 172.27.* 172.28.* 172.29.* 172.30.* 172.31.* UNKNOWN
    allow management from = localhost

These settings affect which IP addresses can access APIs in each category.

Bearer Protection

When enabled via bearer_protection API or netdata.conf, APIs with HTTP_ACCESS_ANONYMOUS_DATA require bearer token authentication.

Effect:

• Changes security model from public/IP-based to token-based
• Only affects APIs with HTTP_ACCESS_ANONYMOUS_DATA (47 APIs)
• Does NOT affect HTTP_ACL_NOCHECK APIs (always public)
• Does NOT affect ACLK-only APIs (already require cloud authentication)

Token Management:

• Tokens obtained via /api/v*/bearer_get_token (requires ACLK access)
• Tokens are time-limited with expiration
• Tokens include role-based access control (admin, manager, etc.)

Use Cases:

• Securing public-facing Netdata agents
• Controlling access to metrics/alerts APIs
• Integrating with external authentication systems

Recommendations for Swagger Documentation

Each API should document:

1. Access Type (Primary Classification):

For ACLK-Only APIs:

⚠️ **ACLK-Only API - Cloud Access Required**

This API is ONLY accessible via Netdata Cloud (ACLK). Direct HTTP/HTTPS access to the agent is not allowed.

**Requirements:**
- User must be authenticated via Netdata Cloud
- User and agent must be in the same Netdata Cloud space
- [Additional role requirements if applicable]

For HTTP_ACCESS_ANONYMOUS_DATA APIs:

📊 **Public Data API (Bearer Protection Configurable)**

**Default Mode:** Publicly accessible without authentication
**Bearer Protection Mode:** Requires valid bearer token when enabled

**Access Methods:**
- Direct HTTP/HTTPS to agent (default: public, configurable)
- Netdata Cloud (authenticated)
- External tools/integrations

**IP Restrictions:** Subject to [ACL category] restrictions in netdata.conf
**Bearer Protection:** Can be enabled via netdata.conf or `/api/v3/bearer_protection`

For HTTP_ACL_NOCHECK APIs:

🔓 **Always Public API**

This API is always publicly accessible and cannot be restricted.

**No Security:**
- Not subject to bearer protection
- Not subject to IP-based ACL restrictions
- No authentication required or possible

2. ACL Category:

Document which ACL category applies (for IP restriction):

• HTTP_ACL_METRICS → "allow dashboard from" in netdata.conf
• HTTP_ACL_ALERTS → "allow dashboard from" in netdata.conf
• HTTP_ACL_NODES → "allow dashboard from" in netdata.conf
• HTTP_ACL_FUNCTIONS → "allow dashboard from" in netdata.conf
• HTTP_ACL_DYNCFG → "allow dashboard from" in netdata.conf
• HTTP_ACL_BADGES → "allow badges from" in netdata.conf
• HTTP_ACL_MANAGEMENT → "allow management from" in netdata.conf

3. Permission Details:

• List required HTTP_ACCESS flags when applicable
• Note minimum user role for ACLK-only APIs
• Explain any per-action or per-function permission checks

4. Bearer Protection Impact:

**When Bearer Protection is Enabled:**
- Requires valid bearer token in Authorization header
- Token format: `Authorization: Bearer <token>`
- Tokens obtained via `/api/v3/bearer_get_token` (ACLK-only)
- Token expiration and renewal required

Last Updated: 2025-10-02 Next Action: Add security documentation to all 68 APIs in swagger.yaml