---
checkId: check.environment.secrets
plugin: stellaops.doctor.environment
severity: warn
tags: [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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
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