Skip to main content

Signed definitions

The agent monitors what it monitors because the platform sends it definitions: which facts identify a service, which probes to run, how often, which metrics to derive. A definition that could run a command on your host is a remote-code-execution surface, and this page is about why it is not one in practice.

Every definition carries a signature​

A definition is a document signed with an ed25519 key. The agent verifies the signature against a public key baked into the binary at build time before it does anything with the document. A definition with no signature, or one signed by another key, is rejected and logged. There is no override, no "trust this once" flag, no unsigned mode. Whoever operates the endpoint cannot change what the agent runs without the publisher's private key, which never leaves the signing host and is not on any machine that serves traffic.

Nothing else that arrives over the connection carries code. Per-host configuration (capability grants, location overrides, a version pin) is data the agent applies within what the signed definitions allow. Commands are a fixed set: collect now, rotate key, check for an update, and a removal order that is itself signed by the publisher and names the one host it is for.

What a definition may do​

Definitions are built from a small set of primitives, and each has its own guard:

  • exec runs one binary from an allow-list compiled into the agent, with fixed arguments, and never through a shell. nginx -T, systemctl is-active, pvesh get ..., sshd -T are on it; bash, curl to arbitrary hosts and package installers are not.
  • sql runs a read-only query through the database driver; the credential comes from the host's own secret store, referenced by name.
  • http calls a local endpoint, with a named credential where one is needed.
  • file reads, hashes or stats a path; logtail and journal follow logs from a saved position.
  • snmp polls devices from a collector host with a named community or v3 credential.

Probes run under the agent's resource budget and with a timeout each. A probe cannot write a file, change a service, or contact anything but the local host and, for the collector role, the devices it was told to poll.

Three trust tiers​

Official definitions are written and signed by Wakora. They cover the services catalog and arrive automatically wherever their match rule holds.

Your own templates are definitions you write in the workspace (Marketplace, My templates). They are signed with a key that belongs to your workspace, and the agents in your workspace trust that key in addition to the publisher's. They live in their own community_ namespace and can never impersonate an official definition.

Community templates are other workspaces' published templates. They run in your workspace only after an explicit install, which shows the full definition and warns that it is unverified; installing one signs it with your workspace key. A template that passes review becomes verified and is signed by Wakora like an official one. A template found to be harmful is unpublished centrally, which withdraws it from every workspace that installed it, with an event in each.

See Definitions and marketplace.

Preview before it runs​

Settings, Definitions lists every definition that reaches your workspace with its version, its match rule, and each probe expanded to the exact command, query or URL it executes. The signing key's fingerprint is printed on the same page, so a security team can compare it with the key published in the trust pack and with the source of the agent that verifies it.

Switching things off​

A definition applies wherever its facts match, and you can narrow that per host: switch a service off on its host page (probes and log collection of that definition stop together), or deny a capability family (eBPF, process profiling, staged changes, log shipping) in the host's Manage card. Those switches are data the agent honours; they never loosen what the signatures allow.