Skip to main content

Architecture

Components​

One binary, deaconguard, provides every role:

RoleServiceListens onData
Serverdeaconguard-server0.0.0.0:8443 (HTTPS)/var/lib/deaconguard/
Agentdeaconguard-agentnothing/etc/deaconguard/agent.json
Local modedeaconguard serve127.0.0.1:7480 (HTTP)~/.local/share/deaconguard/

How a scan works​

The agent never evaluates vulnerabilities itself. It sends the package list, and the server decides which packages are vulnerable. A modified agent could report false check results, but it can't supply its own vulnerability verdicts.

Enrollment​

  1. An administrator creates a token. The token contains the server's URL, the SHA-256 fingerprint of its certificate's public key, and a random secret.
  2. The agent connects to that URL, accepts only a certificate with that fingerprint, and presents the secret.
  3. The server checks the secret (it stores only its hash), marks the token used, and gives the agent its own credential.
  4. From then on the agent authenticates with that credential. Removing the host revokes it at once.

Certificate pinning​

An agent accepts the server's certificate in one of two ways:

  1. Its public key matches the fingerprint from the enrollment token. This is how a self-signed certificate works safely: no certificate authority is involved, and a certificate re-issued for the same key keeps working.
  2. The agent machine's trusted certificate authorities vouch for it for the server's name, as a browser would. This lets you move the server to your own certificate, for example from your company CA or Let's Encrypt, without enrolling every agent again.

Anything else is refused, and the agent reports that the server's certificate doesn't match the one it enrolled with.

Because of the second rule, someone who could obtain a certificate for your server's name from a CA the agents trust could impersonate the server. In practice that means controlling the server's DNS name. If your server uses a public DNS name, protect that domain, for example with a CAA record and registrar lock.

What is stored​

  • Passwords: PBKDF2 hashes.
  • Tokens and agent credentials: SHA-256 hashes on the server; the agent's own credential lives in /etc/deaconguard/agent.json, readable by root only.
  • Sudo passwords: in memory for one scan only, never written or logged.
  • Scan logs: steps, commands and timings, never command output or credentials.