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.

Explain endpoint certificate pins and safe renewal in the trust editor

pulse-triage[bot]f8deb4c3e9de
diff --git a/frontend-modern/browser-tests/proxmox-collection-safety.tsx b/frontend-modern/browser-tests/proxmox-collection-safety.tsx
index d8610aab12..3d0eb5654e 100644
--- a/frontend-modern/browser-tests/proxmox-collection-safety.tsx
+++ b/frontend-modern/browser-tests/proxmox-collection-safety.tsx
@@ -7,7 +7,8 @@ import type { NodeConfigWithStatus } from '../src/types/nodes';
import '../src/index.css';
function Fixture() {
- const requestedType = new URLSearchParams(location.search).get('type');
+ const parameters = new URLSearchParams(location.search);
+ const requestedType = parameters.get('type');
const type = requestedType === 'pbs' || requestedType === 'pmg' ? requestedType : 'pve';
const [saved, setSaved] = createSignal<unknown>(null);
const [finished, setFinished] = createSignal(false);
@@ -19,7 +20,8 @@ function Fixture() {
user: 'monitoring@pam',
tokenName: 'monitoring@pam!fixture',
hasToken: true,
- verifySSL: true,
+ verifySSL: parameters.get('verify') !== 'false',
+ fingerprint: parameters.get('pin') === 'fixture' ? 'ab:'.repeat(31) + 'ab' : '',
monitorVMs: true,
monitorContainers: true,
monitorStorage: true,
diff --git a/frontend-modern/src/components/Settings/ConnectionEditor/CredentialSlots/__tests__/NodeCredentialSlot.test.tsx b/frontend-modern/src/components/Settings/ConnectionEditor/CredentialSlots/__tests__/NodeCredentialSlot.test.tsx
index c36fb7276d..30f21bfaf6 100644
--- a/frontend-modern/src/components/Settings/ConnectionEditor/CredentialSlots/__tests__/NodeCredentialSlot.test.tsx
+++ b/frontend-modern/src/components/Settings/ConnectionEditor/CredentialSlots/__tests__/NodeCredentialSlot.test.tsx
@@ -53,6 +53,9 @@ describe('NodeCredentialSlot', () => {
expect(screen.getByLabelText(/^Endpoint URL/)).toHaveValue('https://pve1.local:8006');
expect(screen.getByRole('checkbox', { name: 'Verify SSL certificate' })).not.toBeChecked();
+ expect(screen.getByRole('status', { name: 'Form TLS policy' })).toHaveTextContent(
+ 'Certificate identity not verified',
+ );
setEditingNode({
...initialNode,
@@ -65,6 +68,9 @@ describe('NodeCredentialSlot', () => {
'https://pve1-refreshed.local:8006',
);
expect(screen.getByRole('checkbox', { name: 'Verify SSL certificate' })).toBeChecked();
+ expect(screen.getByRole('status', { name: 'Form TLS policy' })).toHaveTextContent(
+ 'Trusted certificate chain required',
+ );
});
});
@@ -80,6 +86,7 @@ describe('NodeCredentialSlot', () => {
tokenName: 'root@pam!pulse',
hasToken: true,
verifySSL: true,
+ fingerprint: 'ab'.repeat(32),
status: 'connected',
} as unknown as NodeConfigWithStatus;
const [editingNode, setEditingNode] = createSignal(initialNode);
@@ -98,16 +105,24 @@ describe('NodeCredentialSlot', () => {
const verifySSL = screen.getByRole('checkbox', { name: 'Verify SSL certificate' });
fireEvent.input(endpoint, { target: { value: 'https://operator-edit.local:8006' } });
fireEvent.click(verifySSL);
+ expect(screen.getByRole('status', { name: 'Form TLS policy' })).toHaveTextContent(
+ 'Certificate fingerprint required',
+ );
for (let poll = 1; poll <= 2; poll += 1) {
setEditingNode({
...initialNode,
host: `https://server-poll-${poll}.local:8006`,
+ fingerprint: 'cd'.repeat(32),
});
await waitFor(() => {
expect(screen.getByLabelText(/^Endpoint URL/)).toBe(endpoint);
expect(endpoint).toHaveValue('https://operator-edit.local:8006');
expect(verifySSL).not.toBeChecked();
+ expect(screen.getByLabelText('SSL Fingerprint (optional)')).toHaveValue('ab'.repeat(32));
+ expect(screen.getByRole('status', { name: 'Form TLS policy' })).toHaveTextContent(
+ 'Certificate fingerprint required',
+ );
});
}
@@ -115,7 +130,11 @@ describe('NodeCredentialSlot', () => {
fireEvent.submit(endpoint.closest('form')!);
await waitFor(() => expect(onSaved).toHaveBeenCalledTimes(1));
expect(settings.saveNode).toHaveBeenCalledExactlyOnceWith(
- expect.objectContaining({ host: 'https://operator-edit.local:8006', verifySSL: false }),
+ expect.objectContaining({
+ host: 'https://operator-edit.local:8006',
+ verifySSL: false,
+ fingerprint: 'ab'.repeat(32),
+ }),
editingNode(),
);
});
diff --git a/frontend-modern/src/components/Settings/NodeModalMonitoringSection.tsx b/frontend-modern/src/components/Settings/NodeModalMonitoringSection.tsx
index 07c1257a6f..97731c57ae 100644
--- a/frontend-modern/src/components/Settings/NodeModalMonitoringSection.tsx
+++ b/frontend-modern/src/components/Settings/NodeModalMonitoringSection.tsx
@@ -1,4 +1,4 @@
-import { Component, createUniqueId, Show } from 'solid-js';
+import { Component, createMemo, createUniqueId, Show } from 'solid-js';
import type { NodeModalProps } from '@/components/Settings/nodeModalModel';
import type { NodeModalState } from '@/components/Settings/useNodeModalState';
import { FormSelect } from '@/components/shared/FormSelect';
@@ -25,40 +25,88 @@ interface NodeModalMonitoringSectionProps {
export const NodeModalMonitoringSection: Component<NodeModalMonitoringSectionProps> = (props) => {
const { modalProps, state } = props;
const descriptionId = createUniqueId();
+ const tlsPolicy = createMemo(() => {
+ // Match the TLS client's precedence, not the checkbox alone. This is a
+ // description of form inputs, never evidence that a peer was verified.
+ if (state.formData().fingerprint !== '') {
+ return {
+ title: 'Certificate fingerprint required',
+ description:
+ 'The fingerprint takes precedence over the checkbox. This endpoint must present the matching certificate, even if its certificate chain is trusted or verification is unchecked.',
+ };
+ }
+ if (state.formData().verifySSL) {
+ return {
+ title: 'Trusted certificate chain required',
+ description:
+ 'With no fingerprint set, this endpoint must present a valid, hostname-matching certificate with a chain trusted by the Pulse runtime.',
+ };
+ }
+ return {
+ title: 'Certificate identity not verified',
+ description:
+ 'With no fingerprint and verification unchecked, these settings do not authenticate the server. Encryption alone does not protect credentials from an impersonated endpoint.',
+ };
+ });
return (
<>
- <div>
+ <section aria-label="TLS trust">
<SectionHeader title="SSL settings" size="sm" class="mb-4" titleClass="text-base-content" />
<div class="space-y-3">
- <label class="flex items-center gap-2 text-sm text-base-content">
+ <label class="flex min-h-11 items-center gap-2 text-sm text-base-content">
<input
type="checkbox"
checked={state.formData().verifySSL}
onChange={(event) => state.updateField('verifySSL', event.currentTarget.checked)}
+ aria-describedby={`${descriptionId}-tls-policy`}
class={formCheckbox}
/>
Verify SSL certificate
</label>
<div class={formField}>
- <label for="node-ssl-fingerprint" class={labelClass()}>
+ <label for={`${descriptionId}-ssl-fingerprint`} class={labelClass()}>
SSL Fingerprint (optional)
</label>
<input
- id="node-ssl-fingerprint"
+ id={`${descriptionId}-ssl-fingerprint`}
type="text"
value={state.formData().fingerprint}
onInput={(event) => state.updateField('fingerprint', event.currentTarget.value)}
+ aria-describedby={`${descriptionId}-fingerprint-help ${descriptionId}-tls-policy`}
placeholder="AA:BB:CC:DD:EE:FF:..."
class={controlClass('font-mono')}
/>
- <p class={formHelpText}>
- Useful when connecting to servers with self-signed certificates.
+ <p id={`${descriptionId}-fingerprint-help`} class={formHelpText}>
+ Pins the SHA-256 fingerprint of this endpoint's certificate instead of checking its
+ certificate chain. Certificate renewal can change the fingerprint, including with ACME
+ or Let's Encrypt. Independently verify the replacement through an already-trusted
+ administration channel before updating a pin. Do not disable verification or clear a
+ pin to bypass an error.
</p>
</div>
+ <InlineNotice
+ tone={
+ state.formData().fingerprint === '' && !state.formData().verifySSL ? 'danger' : 'info'
+ }
+ role="status"
+ aria-label="Form TLS policy"
+ aria-live="polite"
+ aria-atomic="true"
+ >
+ <p class="font-medium">{tlsPolicy().title}</p>
+ <p id={`${descriptionId}-tls-policy`}>{tlsPolicy().description}</p>
+ </InlineNotice>
+ <p class={formHelpText}>
+ Form settings only, not a connection-test result.
+ <Show when={modalProps.nodeType === 'pve'}>
+ {' '}
+ Cluster members may have their own saved fingerprints.
+ </Show>
+ </p>
</div>
- </div>
+ </section>
{/* For PVE the Collection scope section below carries both the
coverage description and the per-collector toggles, so the
diff --git a/frontend-modern/src/components/Settings/__tests__/NodeModalMonitoringSection.test.tsx b/frontend-modern/src/components/Settings/__tests__/NodeModalMonitoringSection.test.tsx
index d8abdb0429..f6cccb71f3 100644
--- a/frontend-modern/src/components/Settings/__tests__/NodeModalMonitoringSection.test.tsx
+++ b/frontend-modern/src/components/Settings/__tests__/NodeModalMonitoringSection.test.tsx
@@ -5,7 +5,10 @@ import type { NodeModalProps } from '../nodeModalModel';
import { useNodeModalState } from '../useNodeModalState';
import { NodeModalMonitoringSection } from '../NodeModalMonitoringSection';
-function renderMonitoring(nodeType: NodeModalProps['nodeType'] = 'pve') {
+function renderMonitoring(
+ nodeType: NodeModalProps['nodeType'] = 'pve',
+ trust: { verifySSL?: boolean; fingerprint?: string } = {},
+) {
const onSave = vi.fn();
const fetch = vi.fn();
vi.stubGlobal('fetch', fetch);
@@ -17,6 +20,7 @@ function renderMonitoring(nodeType: NodeModalProps['nodeType'] = 'pve') {
tokenName: 'monitoring@pam!fixture',
hasToken: true,
verifySSL: true,
+ ...trust,
};
const editingNode: NodeConfig =
nodeType === 'pve'
@@ -187,4 +191,117 @@ describe('NodeModalMonitoringSection collection safety', () => {
expect(screen.queryByText(/Guest details depend on guest-agent/)).not.toBeInTheDocument();
expect(fetch).not.toHaveBeenCalled();
});
+
+ it.each(['pve', 'pbs', 'pmg'] as const)(
+ 'explains all four %s trust combinations without changing them or testing the endpoint',
+ (nodeType) => {
+ const pin = 'ab:'.repeat(31) + 'ab';
+ for (const verifySSL of [true, false]) {
+ for (const fingerprint of ['', pin]) {
+ const { fetch, onSave } = renderMonitoring(nodeType, { verifySSL, fingerprint });
+ const region = within(screen.getByRole('region', { name: 'TLS trust' }));
+ const policy = region.getByRole('status', { name: 'Form TLS policy' });
+ expect(policy).toHaveAttribute('aria-live', 'polite');
+ expect(policy).toHaveAttribute('aria-atomic', 'true');
+ expect(policy).toHaveTextContent(
+ fingerprint
+ ? 'Certificate fingerprint required'
+ : verifySSL
+ ? 'Trusted certificate chain required'
+ : 'Certificate identity not verified',
+ );
+ if (fingerprint) {
+ expect(policy).toHaveTextContent('The fingerprint takes precedence over the checkbox');
+ expect(policy).toHaveTextContent('even if its certificate chain is trusted');
+ } else if (verifySSL) {
+ expect(policy).toHaveTextContent('a chain trusted by the Pulse runtime');
+ } else {
+ expect(policy).toHaveTextContent('do not authenticate the server');
+ expect(policy).toHaveTextContent('impersonated endpoint');
+ }
+ expect(region.getByText(/Form settings only/)).toHaveTextContent(
+ 'not a connection-test result',
+ );
+ if (nodeType === 'pve') {
+ expect(region.getByText(/Cluster members may have/)).toBeInTheDocument();
+ } else {
+ expect(region.queryByText(/Cluster members may have/)).not.toBeInTheDocument();
+ }
+ const verification = region.getByRole('checkbox', { name: 'Verify SSL certificate' });
+ expect(verification).toHaveAccessibleDescription(
+ policy.querySelector('[id]')!.textContent!,
+ );
+ expect(verification).toHaveProperty('checked', verifySSL);
+ expect(region.getByRole('textbox', { name: 'SSL Fingerprint (optional)' })).toHaveValue(
+ fingerprint,
+ );
+ fireEvent.click(screen.getByRole('button', { name: 'Save fixture' }));
+ expect(onSave).toHaveBeenCalledOnce();
+ expect(onSave.mock.calls[0][0]).toMatchObject({
+ type: nodeType,
+ verifySSL,
+ fingerprint,
+ });
+ expect(onSave.mock.calls[0][0]).not.toHaveProperty('password');
+ expect(onSave.mock.calls[0][0]).not.toHaveProperty('tokenValue');
+ expect(fetch).not.toHaveBeenCalled();
+ cleanup();
+ }
+ }
+ },
+ );
+
+ it('keeps a supplied pin authoritative when the checkbox changes, including an invalid pin', () => {
+ const { fetch, onSave } = renderMonitoring('pve', { fingerprint: 'not-a-valid-pin' });
+ const verification = screen.getByRole('checkbox', { name: 'Verify SSL certificate' });
+ fireEvent.click(verification);
+ expect(verification).not.toBeChecked();
+ expect(screen.getByRole('status', { name: 'Form TLS policy' })).toHaveTextContent(
+ 'Certificate fingerprint required',
+ );
+ fireEvent.click(screen.getByRole('button', { name: 'Save fixture' }));
+ expect(onSave.mock.calls[0][0]).toMatchObject({
+ verifySSL: false,
+ fingerprint: 'not-a-valid-pin',
+ });
+ expect(fetch).not.toHaveBeenCalled();
+ });
+
+ it('updates the policy and descriptions as the operator edits, without silently changing trust', () => {
+ const { fetch } = renderMonitoring();
+ const policy = screen.getByRole('status', { name: 'Form TLS policy' });
+ const verification = screen.getByRole('checkbox', { name: 'Verify SSL certificate' });
+ const fingerprint = screen.getByRole('textbox', { name: 'SSL Fingerprint (optional)' });
+ const safeHelp = /Independently verify the replacement through an already-trusted/;
+ expect(screen.getByText(safeHelp)).toHaveTextContent(
+ 'Do not disable verification or clear a pin to bypass an error',
+ );
+ expect(fingerprint).toHaveAccessibleDescription(/ACME or Let's Encrypt/);
+ fireEvent.click(verification);
+ expect(policy).toHaveTextContent('Certificate identity not verified');
+ fireEvent.input(fingerprint, { target: { value: 'ab'.repeat(32) } });
+ expect(policy).toHaveTextContent('Certificate fingerprint required');
+ expect(verification).not.toBeChecked();
+ fireEvent.input(fingerprint, { target: { value: '' } });
+ expect(policy).toHaveTextContent('Certificate identity not verified');
+ fireEvent.click(verification);
+ expect(policy).toHaveTextContent('Trusted certificate chain required');
+ expect(fingerprint).toHaveValue('');
+ expect(fetch).not.toHaveBeenCalled();
+ });
+
+ it('keeps TLS labels and descriptions local to each editor', () => {
+ renderMonitoring('pve', { fingerprint: 'ab'.repeat(32) });
+ renderMonitoring('pbs', { verifySSL: false });
+ const ids = screen.getAllByRole('region', { name: 'TLS trust' }).map((region) => {
+ const editor = within(region);
+ const pin = editor.getByRole('textbox', { name: 'SSL Fingerprint (optional)' });
+ const checkbox = editor.getByRole('checkbox', { name: 'Verify SSL certificate' });
+ const descriptionId = checkbox.getAttribute('aria-describedby')!;
+ expect(region.querySelector(`[id="${descriptionId}"]`)).toBeInTheDocument();
+ expect(pin).toHaveAccessibleDescription(/Independently verify/);
+ return pin.id;
+ });
+ expect(new Set(ids).size).toBe(2);
+ });
});