Security model

Shardkeep runs a certificate authority and controls Docker on the machines it manages, so it is built to limit what any one compromise can do.

Nodes

• Agents connect out. The Controller never connects to a Node, and a Node’s Docker Engine is never exposed.
• Enrollment uses a one-time token that expires within the hour. The token also carries a hash of the Controller’s CA, so the Agent talks only to the right Controller from its very first connection, with no trust-on-first-use.
• Private keys never leave the Node. The Agent generates its key and sends a certificate request; the Controller’s CA signs it. Certificates last 90 days and Agents renew them automatically.
• Mutual TLS on every session: the Controller accepts only certificates it issued, and the Agent trusts only the CA it stored at enrollment.
• Revocation reaches Agents even when they were offline: a revoked Agent stops its servers and does nothing more.
• An Agent never stops servers just because connections fail, so a network or CA fault cannot take your network down.

Files and data

• The Agent confines file operations to each server’s data itself. It never relies on the Controller or the web UI for this. File operations run in throwaway containers with only that server’s volume, no network and no privileges, so links in a server’s data can never reach the Node’s files.
• Archives imported by restores, migration and copies are rewritten: only regular files and folders, no links or devices, no paths outside the server’s data.
• Backups are encrypted with age before they leave the Node. Destination secrets are never shown again after creation and never logged.
• The network’s forwarding secret is never shown in the UI or API, and it is masked in file downloads, backups and exports.

Software

• Server software and plugins come from a signed catalog. Controllers verify its signature and refuse older snapshots, so a mirror cannot roll the catalog back.
• Every download is checked against the catalog’s published hash before it is stored, and Agents check it again before use.
• Servers run only from Shardkeep’s templates, never from arbitrary images.

Accounts

• Passwords are hashed with Argon2id; sessions are server-side, in an HttpOnly cookie.
• Sign-ins are rate limited per account and per address, and every authentication event is audited.
• API tokens can be limited to some permissions and given an expiry.
• Every change is recorded in the audit log.

What to protect

• The Controller’s data volume (controller-data) holds the CA’s private key. Treat it, and its backups, as secrets.
• .env holds the database password.
• Each Agent’s volume holds that Node’s identity.
• Backup recovery keys decrypt your backups.

Reporting a vulnerability

Do not open a public issue. Email security@shardkeep.gg, or open a GitLab issue marked confidential. See the security policy.