Allow empty startup checks in a Wazuh key-request service

Bottom line: Separate a startup connection check from a request for a credential-bearing agent record. Test both the socket contract and its configured fallback before relying on automatic enrollment.

Source fact: documented behavior

The Agent key request guide documents socket requests as option:value, with id or ip identifying the lookup type.

It requires allowing empty input because the startup health check connects to the socket and immediately closes a successful connection.

If the configured socket is unavailable, the guide says a specified executable is called; its script-output contract is a JSON object on standard output.

What the source does not establish

This article reviews the documented request and health-check boundary. It does not supply a production database adapter, approve the example SQL or credential handling, or treat an empty successful connection as a completed enrollment lookup.

Applicability questions

• Is the deployment using a socket, an executable or both?
• How is an empty startup connection distinguished from a populated request?
• Which test identities represent ID and IP lookups?
• What happens when the socket is unavailable?

DSE recommendation: controlled next steps

The following steps are DSE recommendations based on the cited source.

DSE recommends separate contract tests for empty startup connections, populated lookups and the explicitly configured fallback.

1. Write the integration contract before connecting it to the production key store. Give the empty startup connection its own proposed case and keep it separate from valid lookup inputs. Identify who owns the external service and the Wazuh manager configuration. Do not return a fabricated agent record merely to make a health-check connection look like a successful enrollment request.
2. Prepare approved disposable lookup identities for the ID and IP branches. Review how the adapter returns its JSON result and how errors are handled without exposing the stored key in ordinary diagnostics. Have the integration owner assess input validation and database parameter binding independently of this socket exercise. Treat sample source code as an example to review, not a ready-made production credential service.
3. Review the actual configured fallback before simulating a socket outage. If an executable is specified, include its path, ownership and expected test behavior in the plan. Keep an unavailable socket, a missing record and a failed adapter as separate observations. Restore the reviewed test configuration before connecting the integration to real enrollment traffic or enabling it for a larger manager population.

Verification and evidence

Proposed verification: observe the empty connect-and-close case without supplying an enrollment identity. Then issue the separately reviewed ID and IP test lookups and inspect their redacted structured results. Record which case was executed so successful socket connectivity cannot be substituted for proof that the external key lookup works.

Exercise an unavailable socket only in the approved isolated arrangement and compare the actual fallback behavior with the configuration. Preserve service and manager observations without retaining usable agent keys in the report. No key retrieval, socket service or automatic enrollment was tested for this article; production adapter safety and credential custody remain separate acceptance requirements.

Official references

• Agent key request — Wazuh; official product documentation.

Source review completed October 30, 2026. Recheck the official source and deployment-specific applicability before changing production settings.