Skip to main content

Security model

The agent's source is public at github.com/wakora-io/agent so that a security team can read exactly what runs on their boxes. This page summarizes the trust model. It is finance-grade by design, because the first clients include regulated finance.

Transport​

One outbound WebSocket, TLS with certificate pinning. The agent pins the server's public key (the SPKI hash), not the CA chain, so the pinned endpoint and key are baked into the binary at build time and there is no server address in any on-host file to tamper with. The pin is checked strictly against the certificate that owns the connection (the leaf, never a later certificate in the chain), and a release build refuses to start with a missing or malformed pin rather than falling back to CA trust. The release and update URL is derived from the same pinned endpoint and uses the same pinned client.

Probes that dial a remote database (a definition pointing at another machine rather than a local socket or loopback) require TLS by default; plaintext to a remote target takes an explicit opt-out in the signed definition. Local sockets and loopback stay plain, as they should.

Identity and the rotating key​

Registration exchanges a shared team key for a per-server key and a UUID. The team key is used once and never written to disk. The per-server key authenticates the WebSocket and rotates every 7 days with a short overlap, and an operator can rotate it on demand from the host's Manage card. A stolen host yields only its own short-lived, revocable key, not the team key. The server id is the UUID, never the hostname, so two hosts named the same do not collide.

Copied machines are a case of their own. The platform remembers the last few retired keys of every host, so a machine restored from a snapshot older than the last rotation is refused with a named reason rather than silently accepted: an old backup cannot take over the live host. Two live machines presenting one identity (a cloned disk with the machine id baked in) are separated within minutes: the one that connected first keeps the identity, the copy is registered as a host of its own through the normal registration gates, and the original's key is rotated so the copy can never reuse it. See Two machines, one identity.

Encryption at rest​

The per-server key and local secrets are stored as AES-GCM ciphertext with a key bound to the machine. The key derivation mixes the machine id with a root-only random seed file (/etc/wakora/.seed, 0600), so a leaked ciphertext plus a known (world-readable) machine id is not enough to decrypt. A copied identity or secrets file is useless on another box. This is machine-id-bound, not TPM-backed, and the docs say so honestly. Values written by an agent from before the seed existed are re-sealed with it at the next start, and the agent log says how many, so a long-lived host does not keep a weaker ciphertext around.

Identity and secret files are written atomically (write, fsync, rename), so a power cut in the middle of a key rotation cannot leave the host with a torn identity. On Windows, where unix file modes mean nothing, the agent's data directory is locked down with a DACL to SYSTEM and Administrators only.

Signed everything​

  • Definitions are ed25519-signed. Official ones verify against the publisher key baked into the binary; community and custom templates verify against a per-workspace key that the agent pins on first use (a later push with a different key is rejected), and they live in a separate namespace so they can never impersonate an official service. An invalid signature means the definition is rejected, on either tier.
  • Binaries are signed the same way, and each release ships a signed manifest with an issue timestamp; the agent refuses downgrades and manifest replays, so even write access to the release channel cannot roll the fleet back. See Updates.
  • APM artifacts (the OpenTelemetry extensions, SDK bundles, profiling tools) come from the same channel with a signed manifest, verified before anything is unpacked.
  • Even self-destruction is signed. A console-initiated removal reaches the agent as an uninstall order signed with the publisher key and scoped to that host's UUID; the agent wipes itself on nothing less. Orders also expire and cannot be replayed: a captured order is refused after a day, and one that was already honored never works twice.

Revocable capabilities​

Deep capabilities (eBPF, the CPU profiler, deep trace) are per-host grants controlled server-side. Revoking one stops the probes and tears down the running machinery within about a minute, with no reload of anything on the host. See Baseline mode.

Least privilege​

exec probes are restricted to an allow-list of binaries, with no shell. When a probe has to run a binary found through a running process (the PHP interpreter behind a pool, a node runtime), the agent runs it as that binary's owner and primary group, with no supplementary groups and never as root; on Windows the same path is refused unless the binary sits in an administrator-owned location. Device configuration backups fetched over SSH are masked on the collector before they are stored, and a device that answers with a non-zero exit or an endless stream fails the fetch rather than storing a partial file. Secrets are resolved locally and never sent to the server. The systemd unit is hardened (ProtectSystem=full, so /usr, /boot and /etc are read-only to it except /etc/wakora, plus ReadWritePaths for its own state, log and binary directories, and ProtectControlGroups). The agent runs as root today because Speed-2 features (eBPF, ptrace, allow-listed exec) require it. Baseline mode stops probes from running but is not a process-level privilege drop. See Baseline mode.

What leaves the host​

Metrics, discovery facts, check results, events, traces, and log lines. Not secret values: credentials are resolved locally, and log lines pass a redaction pass on the host (tokens, passwords, keys, card-like numbers) before transmission, so even logs that accidentally print a secret do not leak it upstream. Where discovery does carry a process command line, it is scrubbed of credential shapes (connection-string passwords, key-like flags) on the host first; the per-process resource meters travel with names only. This local-only handling is a structural compliance edge over cloud SaaS agents.

Two-speed onboarding​

The privilege boundary is also the paywall boundary. Speed 1 (baseline) is zero-privilege, zero-risk, and clears a security review fast. Speed 2 (deep and privileged) is opt-in per capability, each grant shown with its exact impact and audited. See Baseline mode.

Trust pack​

To shorten a security review, Wakora ships a trust pack a security team can verify on its own, before any certification is in place:

  • a threat model, what the agent can and cannot do,
  • an SBOM per release (CycloneDX, signed),
  • a reproducible-builds attestation (pinned toolchain, -trimpath, so anyone can rebuild the binary and match the signed release hash). This is not just a claim: a public CI job on the source repository rebuilds every published release from the public tree and verifies it byte for byte against the signed manifest, in the open, on infrastructure that is not ours,
  • a data-flow document (metrics and names leave the host, secret values never do),
  • the security review history and the operating policies (incident response, change management, risk, data classification).

The pack is public: download it from the Wakora website's trust page, no account needed. It is rebuilt and re-signed automatically with every agent release, each file ships with hashes and a signature, and workspaces on the compliance-enabled plans get the same pack inside the console with a per-client cover letter. Because the agent's source is public, a reviewer can also read exactly what runs on their boxes rather than take the pack on faith.

License​

The agent is licensed under the Elastic License 2.0: read it, run it, modify it, deploy it on machines you control. The one thing it does not allow is offering the agent to third parties as a hosted or managed service. For auditing what runs on your servers, which is what this page is about, nothing is held back: the repository carries the complete source the released binaries are built from, and the releases are reproducible from it. Partner and reseller arrangements are separate commercial agreements and are not affected by the license.