Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Correct registration authentication and token setup guidance
pulse-triage[bot]4dfd6699360e
diff --git a/SECURITY.md b/SECURITY.mdindex 5d2c1bf3f9..69f23bda35 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -616,15 +616,29 @@ Endpoints enforce scope checks before processing. A token without the required s### Auto-Registration Security-#### Default Mode-- All access requires authentication-- Nodes can auto-register with the API token-- Setup scripts work without additional configuration--#### Secure Mode-- Require API token for all operations-- Protects auto-registration endpoint-- Enable by creating at least one API token (UI or legacy env seeding)+Registration always authenticates its request; there is no separate registration+"secure mode" to enable. `/api/auto-register` validates its own credentials even+when no long-lived API token is configured. A reachable endpoint does not mean+that an unauthenticated caller can register a node.++Use the normal authenticated add-connection or agent installation flow for the+intended Pulse destination:++- **Initial setup:** the add-connection flow issues a short-lived, node-type-specific+ setup token. Registration consumes it; keep the token and setup URL private.+- **Existing Proxmox source:** an appropriate `agent:report` token can maintain+ an already registered source. An ordinary reporting token does not authorise+ arbitrary new connections. Installer-issued Proxmox tokens can carry a+ separate, limited bootstrap grant; not every API token is a setup credential.++Manage long-lived tokens in **Settings → API Access**, in the **Security** group,+using the [API token guidance](docs/CONFIGURATION.md#-api-tokens). The legacy+`API_TOKEN` and `API_TOKENS` environment variables are ignored in v6: setting+them does not create a token, secure an installation or repair registration.+Follow the [agent installation guidance](docs/UNIFIED_AGENT.md#quick-start)+instead of widening scopes, disabling authentication or reinstalling an existing+agent to clear a registration error. Keep HTTPS verification and existing saved+connections intact.### Runtime Logging Configurationdiff --git a/frontend-modern/public/docs/SECURITY.md b/frontend-modern/public/docs/SECURITY.mdindex 5d2c1bf3f9..69f23bda35 100644--- a/frontend-modern/public/docs/SECURITY.md+++ b/frontend-modern/public/docs/SECURITY.md@@ -616,15 +616,29 @@ Endpoints enforce scope checks before processing. A token without the required s### Auto-Registration Security-#### Default Mode-- All access requires authentication-- Nodes can auto-register with the API token-- Setup scripts work without additional configuration--#### Secure Mode-- Require API token for all operations-- Protects auto-registration endpoint-- Enable by creating at least one API token (UI or legacy env seeding)+Registration always authenticates its request; there is no separate registration+"secure mode" to enable. `/api/auto-register` validates its own credentials even+when no long-lived API token is configured. A reachable endpoint does not mean+that an unauthenticated caller can register a node.++Use the normal authenticated add-connection or agent installation flow for the+intended Pulse destination:++- **Initial setup:** the add-connection flow issues a short-lived, node-type-specific+ setup token. Registration consumes it; keep the token and setup URL private.+- **Existing Proxmox source:** an appropriate `agent:report` token can maintain+ an already registered source. An ordinary reporting token does not authorise+ arbitrary new connections. Installer-issued Proxmox tokens can carry a+ separate, limited bootstrap grant; not every API token is a setup credential.++Manage long-lived tokens in **Settings → API Access**, in the **Security** group,+using the [API token guidance](docs/CONFIGURATION.md#-api-tokens). The legacy+`API_TOKEN` and `API_TOKENS` environment variables are ignored in v6: setting+them does not create a token, secure an installation or repair registration.+Follow the [agent installation guidance](docs/UNIFIED_AGENT.md#quick-start)+instead of widening scopes, disabling authentication or reinstalling an existing+agent to clear a registration error. Keep HTTPS verification and existing saved+connections intact.### Runtime Logging Configurationdiff --git a/frontend-modern/src/features/docs/__tests__/registrationSecurityGuide.test.ts b/frontend-modern/src/features/docs/__tests__/registrationSecurityGuide.test.tsnew file mode 100644index 0000000000..11eb8578fe--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/registrationSecurityGuide.test.ts@@ -0,0 +1,66 @@+import { readFileSync } from 'node:fs';+import { resolve } from 'node:path';+import { describe, expect, it } from 'vitest';+import { createGuideFixture } from './guideFixture';++const read = (name: string) =>+ readFileSync(+ resolve(process.cwd(), '..', name === 'SECURITY' ? 'SECURITY.md' : `docs/${name}.md`),+ 'utf8',+ );+const article = createGuideFixture(read);+const text = (element: Element) => element.textContent!.replace(/\s+/g, ' ').trim();+const registration = () => {+ const guide = article('SECURITY');+ const heading = guide.querySelector('#auto-registration-security')!;+ const section = document.createElement('section');+ for (+ let next = heading.nextElementSibling;+ next && !['H2', 'H3'].includes(next.tagName);+ next = next.nextElementSibling+ ) {+ section.append(next.cloneNode(true));+ }+ return section;+};++describe('registration security guidance', () => {+ it('explains always-authenticated registration instead of invented security modes', () => {+ const section = registration();+ expect(text(section)).toContain('Registration always authenticates its request');+ expect(text(section)).toContain('even when no long-lived API token is configured');+ expect(text(section)).toContain('does not mean that an unauthenticated caller can register');+ expect(section.querySelector('h4')).toBeNull();+ expect(text(section)).not.toContain('legacy env seeding');+ });++ it('distinguishes one-time setup, reporting and limited Proxmox bootstrap credentials', () => {+ const items = [...registration().querySelectorAll('li')];+ expect(items).toHaveLength(2);+ expect(text(items[0])).toContain('short-lived, node-type-specific setup token');+ expect(text(items[0])).toContain('Registration consumes it');+ expect(text(items[1])).toContain('agent:report');+ expect(text(items[1])).toContain('does not authorise arbitrary new connections');+ expect(text(items[1])).toContain('separate, limited bootstrap grant');+ });++ it('routes readers away from ignored environment variables without weakening access', () => {+ const section = registration();+ expect(text(section)).toContain('Settings → API Access');+ expect(text(section)).toContain('API_TOKEN and API_TOKENS environment variables are ignored');+ expect(text(section)).toContain('does not create a token, secure an installation');+ expect(text(section)).toContain('instead of widening scopes, disabling authentication');+ expect(text(section)).toContain('Keep HTTPS verification and existing saved connections intact');+ for (const [name, fragment] of [+ ['CONFIGURATION', '-api-tokens'],+ ['UNIFIED_AGENT', 'quick-start'],+ ]) {+ expect(section.querySelector(`a[href="/docs/${name}#${fragment}"]`)).not.toBeNull();+ expect(article(name).querySelector(`[id="${fragment}"]`)).not.toBeNull();+ }+ expect(section.querySelector('pre, form, input, button')).toBeNull();+ expect(readFileSync(resolve(process.cwd(), 'public/docs/SECURITY.md'), 'utf8')).toBe(+ read('SECURITY'),+ );+ });+});