Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

Correct registration authentication and token setup guidance

pulse-triage[bot]4dfd6699360e
diff --git a/SECURITY.md b/SECURITY.md
index 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 Configuration
diff --git a/frontend-modern/public/docs/SECURITY.md b/frontend-modern/public/docs/SECURITY.md
index 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 Configuration
diff --git a/frontend-modern/src/features/docs/__tests__/registrationSecurityGuide.test.ts b/frontend-modern/src/features/docs/__tests__/registrationSecurityGuide.test.ts
new file mode 100644
index 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'),
+ );
+ });
+});