Let relays verify the site certificate during registration

When a relay joins a Checkmk site it can now confirm it is
really talking to that site, instead of trusting whatever
certificate is presented during setup.

The site provides the expected certificate fingerprint
as part of the install command, and the relay checks it
before registering. Administrators using the Setup GUI
get this automatically; the previous "trust on first use"
behavior remains available where a fingerprint cannot be used.

Change-Id: Ied703e3f5433c6cbc3de4f7c96c161f586eaac5f
JIRA-Ref: CMK-35793

Author: Cornel-Craveta

.werks/19542.md

@@ -0,0 +1,34 @@
+[//]: # (werk v3)
+# Establish relay trust explicitly via the site certificate fingerprint
+
+key        | value
+---------- | ---
+date       | 2026-07-14T09:33:09.144244+00:00
+version    | 3.0.0b1
+class      | feature
+edition    | ultimate
+component  | relay
+level      | 2
+compatible | yes
+
+When a relay registers with a Checkmk site, it connects to the site's agent
+receiver over TLS. Until now the relay accepted whatever certificate the site
+presented during registration (trust on first use), with no way to confirm out
+of band that it was really talking to the intended site, leaving registration
+open to a man-in-the-middle.
+
+Relay registration now supports establishing that trust explicitly.
+`cmk-relay register` accepts a new `--cert-fingerprint` option that checks the
+presented certificate against a known SHA-256 fingerprint and stops
+registration if it does not match. The fingerprint is delivered through a
+trusted channel: the relay setup in the Setup GUI computes it from the site
+certificate and includes it in the generated Linux installation command, so
+these installs pin the certificate automatically with nothing extra to
+configure.
+
+`--cert-fingerprint` is mutually exclusive with the existing `--trust-cert`
+option, which keeps the previous "accept the presented certificate" behavior
+for cases where a fingerprint cannot be used (for example, when a
+TLS-terminating proxy in front of the site presents a different certificate).
+The interactive confirmation prompt, which shows the certificate fingerprint
+before accepting it, is unchanged.

module_layers.toml

@@ -929,6 +929,7 @@ excludes = ["cmk.gui.nonfree.pro.plugins", "cmk.gui.plugins"]
 [components."cmk.gui.nonfree.ultimate"]
 allows = [
   "@ccc",
+  "@crypto",
   "@livestatus_client",
   "@metric_backend",
   "@plugin_apis",

packages/cmk-frontend-vue/src/mode-relay/ModeCreateRelayApp.vue

@@ -85,6 +85,7 @@ const openRelayOverviewPage = () => {
           :domain="props.domain"
           :agent-receiver-port="props.agent_receiver_port"
           :site-version="props.site_version"
+          :cert-fingerprint="props.cert_fingerprint"
           :index="4"
           :is-completed="() => currentStep > 4"
         />

packages/cmk-frontend-vue/src/mode-relay/add-relay-configuration-steps/ExecuteInstallationScript.vue

@@ -35,6 +35,7 @@ const props = defineProps<
     domain: string
     agentReceiverPort: number
     siteVersion: string
+    certFingerprint: string
   }
 >()
 
@@ -49,6 +50,7 @@ const installCommand = computed(() => {
     `  --initial-tag-version ${props.siteVersion} \\`,
     `  --target-server ${props.domain}:${props.agentReceiverPort} \\`,
     `  --target-site-name ${props.siteName} \\`,
+    `  --cert-fingerprint ${escapeShellArg(props.certFingerprint)} \\`,
     `  --token ${token}`
   ].join('\n')
 })

packages/cmk-frontend-vue/tests/mode-relay/ModeCreateRelayApp.test.ts

@@ -16,6 +16,7 @@ const mockProps: CreateRelay = {
     documentation: 'https://docs.checkmk.com/relay'
   },
   site_name: 'test_site',
+  cert_fingerprint: 'AB:CD:EF:00:11',
   domain: 'localhost',
   agent_receiver_port: 8000,
   site_version: '2.5.0',

packages/cmk-frontend-vue/tests/mode-relay/add-relay-configuration-steps/ExecuteInstallationScript.test.ts

@@ -18,7 +18,8 @@ const baseProps = {
   siteName: 'my_site',
   domain: 'checkmk.example.com',
   agentReceiverPort: 8000,
-  siteVersion: '2.5.0'
+  siteVersion: '2.5.0',
+  certFingerprint: 'AB:CD:EF:00:11'
 }
 
 const mockTokenResponse = {
@@ -83,6 +84,19 @@ describe('ExecuteInstallationScript', () => {
     expect(cmd).toContain('mock-token-abc')
   })
 
+  test('install command pins the certificate fingerprint', async () => {
+    vi.spyOn(Api.prototype, 'post').mockResolvedValue(mockTokenResponse)
+    mountWithWizardContext(ExecuteInstallationScript, baseProps)
+
+    await fireEvent.click(screen.getByRole('button', { name: /generate one-time token/i }))
+    await screen.findByText(/This token remains valid for/)
+
+    const cmd = screen.getByTestId('run-relay-install-script').textContent ?? ''
+    expect(cmd).toContain('--cert-fingerprint')
+    expect(cmd).toContain('AB:CD:EF:00:11')
+    expect(cmd).not.toContain('--trust-cert')
+  })
+
   test('Next button is blocked until a valid token is generated', async () => {
     const { navigation } = mountWithWizardContext(ExecuteInstallationScript, baseProps)
 

packages/cmk-shared-typing/source/create_relay.json

@@ -21,6 +21,9 @@
     "site_name": {
       "type": "string"
     },
+    "cert_fingerprint": {
+      "type": "string"
+    },
     "domain": {
       "type": "string"
     },
@@ -40,5 +43,13 @@
       "type": ["integer", "null"]
     }
   },
-  "required": ["urls", "site_name", "domain", "agent_receiver_port", "site_version", "supported_os"]
+  "required": [
+    "urls",
+    "site_name",
+    "cert_fingerprint",
+    "domain",
+    "agent_receiver_port",
+    "site_version",
+    "supported_os"
+  ]
 }