git.stella-ops.org/docs/doctor/articles/environment/environment-secret-health.md

checkId, plugin, severity, tags

checkId	plugin	severity	tags
check.environment.secrets	stellaops.doctor.environment	warn	environment secrets security rotation expiry

Environment Secret Health

What It Checks

Queries the Release Orchestrator secrets status API (/api/v1/environments/secrets/status) for metadata about all configured secrets (no actual secret values are retrieved). Each secret is evaluated for:

• Expiry -- secrets already expired, expiring within 7 days (critical), or expiring within 30 days (warning)
• Rotation compliance -- if a rotation policy is defined, checks whether lastRotated exceeds the policy interval by more than 10% grace

Severity escalation:

• Fail if any production secret has expired
• Fail if any secret has expired or production secrets are expiring within 7 days
• Warn if secrets are expiring within 30 days or rotation is overdue
• Pass if all secrets are healthy

Why It Matters

Expired secrets cause immediate authentication and authorization failures. Services that depend on expired credentials will fail to connect to databases, registries, external APIs, and other integrations. In production, this means outages. Secrets expiring within 7 days require urgent rotation to prevent imminent failures. Overdue rotation violates security policies and increases the blast radius of a credential compromise.

Common Causes

• Secret expired without automated rotation being configured
• Rotation job failed silently (scheduler down, permissions changed)
• Secret provider (Vault, Key Vault) connection lost during rotation window
• Manual secret set with fixed expiry and no follow-up rotation
• Rotation policy interval shorter than actual rotation cadence

How to Fix

Docker Compose

# List secrets with expiry status
stella env secrets list --expiring

# Rotate an expired or expiring secret immediately
stella env secrets rotate <environment> <secret-name>

# Check secret provider connectivity
stella secrets provider status

# Update secret in .env file for compose deployments
# Edit devops/compose/.env with the new secret value
# Then restart affected services
docker compose -f docker-compose.stella-ops.yml restart <service>

Bare Metal / systemd

# List secrets with expiry details
stella env secrets list --expiring

# Rotate expired secret
stella env secrets rotate <environment> <secret-name>

# If using file-based secrets, update the file
sudo vi /etc/stellaops/secrets/<secret-name>
sudo chmod 600 /etc/stellaops/secrets/<secret-name>
sudo systemctl restart stellaops-<service>

# Schedule automated rotation
stella env secrets rotate-scheduled --days 7

Kubernetes / Helm

# List expiring secrets
stella env secrets list --expiring

# Rotate secret and update Kubernetes secret
stella env secrets rotate <environment> <secret-name>

# Or update manually
kubectl create secret generic <secret-name> \
  --from-literal=value=<new-value> \
  -n stellaops-<env> --dry-run=client -o yaml | kubectl apply -f -

# Restart pods to pick up new secret
kubectl rollout restart deployment/<service> -n stellaops-<env>

# For external-secrets-operator, trigger a refresh
kubectl annotate externalsecret <name> -n stellaops force-sync=$(date +%s)

Verification

stella doctor run --check check.environment.secrets

Related Checks

• check.environment.connectivity - expired agent credentials cause connectivity failures
• check.environment.deployments - services fail when their secrets expire
• check.integration.secrets.manager - verifies the secrets manager itself is healthy