VirtRigaud Security Guide¶

This is the canonical operator-facing security reference for VirtRigaud v0.3.8. It describes the current security posture honestly: what the code actually does, what the operator is expected to provide, and what remains out of scope for a regulated (e.g. banking) deployment.

Threat model¶

What VirtRigaud is trying to protect¶

• Hypervisor credentials at rest in K8s Secrets and in flight between the provider pod and the hypervisor API endpoint (vCenter SOAP, libvirt over SSH, Proxmox REST).
• Operator intent carried by VirtualMachine / Provider / VMMigration CRs — these are authoritative declarations of cluster state.
• Provider runtime integrity — the per-Provider Deployment that runs the gRPC server and holds the credentials Secret.

What VirtRigaud relies on Kubernetes to provide¶

• API-server authentication and authorization — every kubectl apply or controller action is authorised by the kube-apiserver against RBAC.
• Secret encryption at rest — VirtRigaud assumes the operator has enabled EncryptionConfiguration on the kube-apiserver; the credentials Secret is otherwise stored in etcd as base64.
• Namespace boundaries — VirtRigaud does not invent novel sandboxing. A cluster-admin can kubectl get secret from any namespace and read every provider credential. Treat manager- and provider-hosting namespaces as high-privilege.
• Pod-network policy enforcement — Kubernetes NetworkPolicies require a CNI that enforces them (Calico, Cilium, etc.). Without a CNI that enforces them, the Network Policies page is documentation, not control.
• PKI for admission webhooks — VirtRigaud's admission webhook (charts/virtrigaud/templates/webhooks.yaml) needs a TLS cert. The Helm chart can generate one (webhooks.secretName) or you can wire cert-manager.

What VirtRigaud is NOT trying to protect against¶

• A compromised cluster-admin. Cluster-admin can read all Secrets in all namespaces, including every provider credential. That is a Kubernetes RBAC concern.
• A compromised hypervisor. If vCenter / Proxmox / libvirt itself is owned, VirtRigaud is not a defender — the credentials it holds will be misused.
• Side-channel attacks against shared infrastructure. VirtRigaud has no model for noisy-neighbour or hardware-level isolation; that is a hypervisor concern.

STRIDE quick-reference¶

Provider credentials¶

How credentials flow¶

K8s Secret (operator-supplied)
        │
        │ referenced by Provider.spec.credentialSecretRef.name
        ▼
ProviderReconciler (internal/controller/provider_controller.go:697)
        │  mounts Secret read-only as a volume named "provider-credentials"
        │  at /etc/virtrigaud/credentials inside the provider pod
        ▼
Provider pod (vsphere / libvirt / proxmox / mock)
        │  reads individual keys as FILES, one file per Secret key
        ▼
Hypervisor API (vCenter SOAP / libvirt SSH / Proxmox REST)

Credentials are never placed in env vars by the controller. They are mounted as files. Each provider reads only the keys it needs.

Secret-key naming by provider¶

For Proxmox specifically, API tokens MUST be used in production. See Proxmox provider page for the rationale. Password auth is retained for development/CI parity only.

What is logged¶

• VirtRigaud logs length-only diagnostics (e.g. username_length=12 password_length=24) at INFO level to confirm credentials were mounted, never the values.
• vSphere provider explicitly does not pass username/password as command-line arguments; the SOAP client uses url.UserPassword so they are not visible in process listings.
• libvirt SSH password auth uses sshpass -e (env-var-bearing) rather than command-line; the SSH transport itself now verifies the host key by default (see Libvirt SSH host-key verification below).

Where credentials are NOT exposed¶

• They never appear in Provider.status.
• They never appear in Event records.
• They never appear in metric labels (label cardinality is bounded; secret values would be unbounded anyway).
• gRPC request/response logging (when enabled via the SDK Logging middleware) does not include user_data/meta_data payloads or credential fields.

gRPC transport between manager and providers¶

How it is wired¶

• CRD field with runtime effect. Provider.spec.runtime.service.tls (enabled, secretRef, insecureSkipVerify) now drives behaviour. The referenced Secret carries tls.crt / tls.key / ca.crt (a kubernetes.io/tls Secret or an Opaque Secret with those three keys; both accepted) and is mounted on the provider pod at /etc/virtrigaud/tls.
• Manager side (internal/runtime/remote/resolver.go): MinVersion=TLS1.3, RootCAs from ca.crt, client Certificates from tls.crt+tls.key, ServerName anchored to the provider Service FQDN.
• Provider side (SDK): MinVersion=TLS1.3, RequireAndVerifyClientCert, CA bundle in ClientCAs, SAN allow-list via validateTLSPeer.
• Status condition TLSConfigured (reasons Enabled / ExplicitlyDisabled / SecretRefMissing / TLSBlockMissing) makes posture auditable via kubectl get providers.
• Cert rotation hot-reloads the leaf cert/key without a pod restart; rotating the CA bundle still requires a provider restart. Documented limitation.

Provider-side gRPC server authentication¶

The provider SDK (sdk/provider/middleware/middleware.go) defines:

• AuthConfig.RequireTLS + AuthConfig.AllowedSANs — refuse RPCs without a verified client cert (mTLS), and gate accepted identities by SAN/CN allow-list.
• AuthConfig.BearerTokenAuth + AuthConfig.ValidateToken — accept a Bearer-token Authorization metadata header and validate it with an operator-supplied function.

Libvirt SSH host-key verification¶

Trust material. The host key lives in a known_hosts entry inside the existing libvirt credentials Secret (the one referenced by credentialSecretRef), mounted at /etc/virtrigaud/credentials/known_hosts. Seed it with:

ssh-keyscan -H <libvirt-host> >> known_hosts

then add the resulting known_hosts key to the credentials Secret. The full operational runbook (keyscan, Secret update, rollout) lives on the libvirt provider and host-prep pages; this page only covers the security framing.

Escape hatch (lab / migration only). Set the environment variable LIBVIRT_INSECURE_SKIP_HOST_KEY_VERIFICATION=true via spec.runtime.env to fall back to non-verifying behaviour. This is audit-flagged: a WARN is logged on every connection. Do not use it in regulated environments.

Defence-in-depth (still recommended): keep the libvirt provider pod and the libvirt host on the same private subnet behind a CNI that enforces traffic on that path, with a NetworkPolicy scoping egress. Host-key verification is now the primary control; network isolation is the backstop.

RBAC¶

Manager RBAC¶

charts/virtrigaud/templates/manager-rbac.yaml grants the manager's ServiceAccount these verbs:

• VirtRigaud CRDs (infra.virtrigaud.io): create, delete, get, list, patch, update, watch on virtualmachines, providers, vmsnapshots, vmclones, vmmigrations, vmsets, vmclasses, vmimages, vmnetworkattachments, vmplacementpolicies (and their /status and /finalizers subresources).
• secrets: get, list, watch only — read-only (tightened in v0.3.7, #152; unchanged in v0.3.8). The manager resolves Provider.spec.credentialSecretRef and the TLS secretRef to mount them into provider Deployments; it never creates, updates, or deletes Secrets.
• Core K8s: configmaps, services, events (scoped to the verbs each actually needs).
• persistentvolumeclaims (for migration storage).
• pods: get, list, watch (for provider-readiness checks).
• apps/deployments (for spawning provider pods).
• coordination.k8s.io/leases: leader election.
• metrics.k8s.io/pods,nodes: get, list.

No wildcards. No cluster-admin. No * resources. The chart supports rbac.scope=namespace for single-namespace deployments via the Role/RoleBinding branch.

Provider pod RBAC¶

Each Provider gets its own ServiceAccount (auto-created by the controller). Provider pods have no Kubernetes API access by default. They are not granted any Role, so a compromised provider pod cannot list other Secrets or escape its own credential mount.

This is enforced by the absence of a RoleBinding on the per-Provider ServiceAccount. If you add custom RBAC for a provider, scope it to the resources that provider actually needs (typically: none).

Container hardening¶

The provider-libvirt image is the only one that cannot use distroless because it shells out to virsh, ssh, and scp. It is still non-root and reads its own root filesystem read-only. References: cmd/provider-libvirt/Dockerfile, build/Dockerfile.provider-vsphere, build/Dockerfile.manager, cmd/provider-proxmox/Dockerfile, cmd/provider-mock/Dockerfile.

The securityContext applied to every provider pod by the controller (internal/controller/provider_controller.go:602-611):

securityContext:
  runAsNonRoot: true
  runAsUser: 65532
  readOnlyRootFilesystem: true
  allowPrivilegeEscalation: false
  capabilities:
    drop: [ALL]

You should apply equivalent settings to the manager Deployment via Helm values if your cluster's Pod Security Standards do not enforce them already.

Metrics endpoint security¶

By default (still the case in v0.3.8), the manager's /metrics endpoint is HTTP on :8080, unauthenticated. This is the controller-runtime default, ported into the canonical manager entrypoint by H1 PR-1 (#115) as part of the v0.3.6 build-path consolidation (#92). The HTTPS-default flip remains deferred (see note below).

Opting into RBAC-authenticated /metrics¶

Pass --metrics-secure=true to the manager. When this flag is set:

• /metrics is served over HTTPS.
• metrics/filters.WithAuthenticationAndAuthorization (cmd/manager/main.go:209) is installed as the metrics FilterProvider.
• Every scrape must present a Kubernetes-issued bearer token (typically a ServiceAccount token from the Prometheus pod). The token's TokenReview must succeed AND a SubjectAccessReview must show the token holder has get on nonResourceURLs: ["/metrics"].

You must therefore grant Prometheus's ServiceAccount the right to scrape:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: prometheus-metrics-scraper
rules:
  - nonResourceURLs: ["/metrics"]
    verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: prometheus-metrics-scraper
subjects:
  - kind: ServiceAccount
    name: prometheus-server
    namespace: monitoring
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: prometheus-metrics-scraper

Provider metrics¶

The per-provider metrics surface (e.g. RPC metrics emitted by the gRPC client interceptor) is exposed on the manager's /metrics endpoint — provider pods themselves do not expose a Prometheus endpoint. Their :8080 port is the healthz endpoint only. So securing manager /metrics is sufficient to secure all virtrigaud_* metric series.

See Observability Guide for the metric catalogue.

CircuitBreaker as a denial-of-service control¶

The per-Provider CircuitBreaker (G6 / #112, wired in v0.3.6) is also a security control: it caps how loudly a wedged, flapping, or compromised provider can fail. When the breaker is open, the manager fast-fails RPCs to that provider with codes.Unavailable for a cool-down period instead of hammering it.

Operationally, this means an attacker who manages to put a single provider into a degraded state cannot use that provider to consume controller worker slots indefinitely. See Resilience for the lifecycle, metrics, and tuning.

Enforcing provider capabilities¶

v0.3.8 adds an opt-in manager flag, --enforce-provider-capabilities (#176, default OFF). When enabled, the manager fail-closes snapshot and migration operations against any provider that does not advertise the corresponding capability, returning a clear error instead of attempting an RPC the provider cannot honour.

• Default OFF — this is not a breaking change. Existing deployments behave exactly as they did in v0.3.7 unless an operator opts in.
• What it hardens — it removes the ambiguity of calling snapshot/migration RPCs against a provider that never declared support, turning a best-effort call into a deterministic, audit-visible refusal. For a regulated deployment this makes "this provider is not allowed to snapshot" an enforceable posture rather than a convention.
• How to enable — pass --enforce-provider-capabilities to the manager (via the chart's manager args). Confirm each Provider advertises the capabilities you rely on before turning it on, since enabling it will reject operations on providers that under-report.

This is an operational hardening toggle, not a transport or credential control; it complements, but does not replace, mTLS and RBAC.

Supply chain¶

CVE management¶

• Container images are scanned with Trivy on every release (.github/workflows/release.yml:185-198). The release workflow fails if Trivy finds any HIGH or CRITICAL severity vulnerability. v0.3.6 itself was held back until 3 HIGH-severity OpenTelemetry CVEs (CVE-2026-29181, CVE-2026-24051, CVE-2026-39883) were addressed by PR #144.
• Code is scanned with Trivy in repo mode on every CI run (.github/workflows/ci.yml:160-171). Results are uploaded to the GitHub Security tab as SARIF.
• Release artifacts are signed and attested with cosign (.github/workflows/release.yml). Every published multi-arch image — and its per-arch children, via cosign sign --recursive — carries a keyless signature (Fulcio + Rekor), an SBOM attestation (spdxjson), and SLSA L3 provenance (slsa-github-generator, generator_container_slsa3.yml@v2.1.0).

Verifying release artifacts¶

From v0.3.9 onward, the signature, SBOM, and SLSA provenance are all stored in the legacy .sig/.att tag format — the release pins cosign to v2.6.3 (#172) so its sign/attest output matches the SLSA generator's tag. As a result, a single cosign version (any ≥ 2.2) verifies all three with default flags. Prefer an immutable @sha256:… digest over a tag:

IMAGE=ghcr.io/projectbeskar/virtrigaud/manager:v0.3.9
ISSUER=https://token.actions.githubusercontent.com
# Accepts both the release workflow (signature/SBOM) and the SLSA generator
# (provenance) identities; tighten per-artifact if you need a stricter policy.
ID_RE='https://github.com/(projectbeskar/virtrigaud|slsa-framework/slsa-github-generator)/.*'

# 1. Signature
cosign verify "$IMAGE" \
  --certificate-identity-regexp="$ID_RE" \
  --certificate-oidc-issuer="$ISSUER"

# 2. SBOM (SPDX)
cosign verify-attestation "$IMAGE" --type spdxjson \
  --certificate-identity-regexp="$ID_RE" \
  --certificate-oidc-issuer="$ISSUER"

# 3. SLSA provenance
cosign verify-attestation "$IMAGE" --type slsaprovenance \
  --certificate-identity-regexp="$ID_RE" \
  --certificate-oidc-issuer="$ISSUER"

GitHub Actions pinning¶

All third-party Actions are pinned to 40-character commit SHAs, not floating tags. Dependabot maintains the SHA-pin policy via .github/dependabot.yml (see #135 for the policy ratification).

Go module integrity¶

• go.sum is verified on every CI run via go mod download against the module proxy.
• make verify-tidy (the convention) fails on a dirty go mod tidy diff.
• govulncheck runs as a blocking CI gate on every run (added in v0.3.7, #151), failing the build on a known vulnerability in a reachable code path — complementing the Trivy image/repo scans.

CRD input validation¶

Every string field that flows to a hypervisor API call has Kubebuilder validation. Spot-check examples:

• Provider.spec.endpoint: regex-validated to accept only well-formed http(s)://, tcp://, grpc://, or qemu(+ssh|+tcp|+tls):// URIs (api/infra.virtrigaud.io/v1beta1/provider_types.go:218).
• Provider.spec.type: enum-validated to one of vsphere | libvirt | firecracker | qemu | proxmox.
• ProviderDefaults.{datastore,cluster,folder,resourcePool,network}: MaxLength=255.
• ProviderRuntimeSpec.image: regex-validated to enforce image[:tag][@digest] format only.
• Numeric ports, replicas, QPS, burst — all range-bounded.

Cloud-init userdata (carried in VirtualMachine.spec.userData.cloudInit) is treated as opaque bytes by the manager and never interpreted as shell. It is forwarded to the provider as a raw byte payload via the CreateRequest.UserData proto field.

Vulnerability reporting¶

Please do not report security vulnerabilities through public GitHub issues.

Email security@virtrigaud.io with:

• A description of the vulnerability
• Steps to reproduce
• Potential impact
• Any mitigations you have already identified

You should receive a response within 48 hours.

Severity classification¶

• Critical: patch within 24 hours; out-of-band release if needed.
• High: patch within 7 days.
• Medium: patch within 30 days.
• Low: patch in the next regular release.

We coordinate disclosure on a 90-day default timeline.

Supported versions¶

v0.3.6 security gap inventory¶

This section tracks the security gaps that were open in v0.3.6 and records what shipped to close them. The heading and anchor (#v036-security-gap-inventory) are retained so links from older pages still resolve. The two highest-severity transport gaps were resolved in v0.3.7 and remain closed in v0.3.8.

The following remain open and operators in regulated environments must factor them into their compensating-control posture: