Whiskers is infrastructure-management software with an AI interface — security is a first-class concern of the design, not an afterthought. This page describes the model and its trade-offs honestly; it is not a claim of perfect security.
Threat model (high level)
The classic risk is a single stored SSH key on the controller: compromise it and every managed host falls, because that key is arbitrary-shell “god mode”. Whiskers is designed to remove that standing credential and to bound what any actor — human or AI — can do to explicit, permissioned, audited tools.
Authentication & roles
Local accounts (email + password) or Google / generic OIDC, with an email allow-list and three roles (Viewer / Operator / Admin). Authorization is fail-closed: every endpoint requires authentication unless it explicitly opts out. MCP access is gated per API key (Read / Write / Admin) and the acting agent can never exceed the rights of whoever triggered it.
Secrets & vault
Stored secrets are encrypted at rest in a vault (AES-256-GCM, key derived from VAULT_KEY). Sensitive values are redacted before logging and persistence. Secrets live under the data volume and the .env, never baked into the image or committed to the repository.
Webhooks (HMAC)
Incoming webhooks require a mandatory secret; requests must be signed over the raw body with an HMAC signature (X-Hub-Signature-256) — compatible with GitHub, GitLab and Gitea. The secret is shown once.
SSH bootstrap & host-key verification
Onboarding a host uses a one-time bootstrap SSH connection; the bootstrap credentials are removed afterwards. Every SSH path pins host keys (trust-on-first-use); a changed key fails hard instead of silently talking to a man-in-the-middle. We do not claim SSH is never used — the goal is a steady state without a standing private key.
Mesh + mTLS for steady-state operation
After bootstrap, hosts are reached over a private WireGuard mesh (Tailscale / NetBird). Docker control runs over mutual TLS (ghostunnel + a verb-whitelisting socket-proxy) instead of SSH tunnels; management ports are bound to the mesh, never the public internet. See the architecture document.
Docker socket & container profiles
The default profile is privileged so Whiskers can manage its own host (firewall / Nginx / systemd via a one-shot nsenter helper). For monitoring remote hosts only, a hardened profile runs non-root, non-privileged, read-only rootfs, with Docker access through a verb-restricted socket-proxy — a much smaller attack surface.
Supply chain
Release images are scanned by Trivy before they ship (the run fails on any CRITICAL), built multi-arch with SLSA provenance and an SBOM, and keyless-signed with cosign (Sigstore, logged in Rekor). You can verify a signature before running the image.
Limits & beta
Whiskers is beta and not yet API-stable; it is single-replica by design. No software is unbreakable — run it on a trusted network, keep guardrails restrictive, and grant least privilege. Please report vulnerabilities privately via the repository’s security policy.
In the product
