docs/operations/security-maintenance.md

# Security Maintenance

This runbook defines dependency/version policy and monthly maintenance tasks for CI/action supply-chain hygiene.

## 1) Third-Party Workflow Provenance

| Component | Source | Pin/verification strategy |
|---|---|---|
| `actions/checkout` | GitHub (`actions/checkout`) | Full commit SHA pin in workflows |
| `actions/setup-python` | GitHub (`actions/setup-python`) | Full commit SHA pin in workflows |
| `actions/upload-artifact` | GitHub (`actions/upload-artifact`) | Full commit SHA pin in workflows |
| `astral-sh/setup-uv` | Astral (`astral-sh/setup-uv`) | Full commit SHA pin in workflows |
| `github/codeql-action/*` | GitHub (`github/codeql-action`) | Full commit SHA pin in workflows |
| `actionlint` binary | GitHub release (`rhysd/actionlint`) | Version pin + SHA256 checksum verification in workflow |
| `gitleaks` binary | GitHub release (`gitleaks/gitleaks`) | Version pin + SHA256 checksum verification in workflow |
| `shellcheck` | Ubuntu apt repository | Installed from `ubuntu-latest` apt; review version during monthly maintenance |

## 2) Minimum Version Policy (Critical Dependencies)

Keep explicit lower bounds in `pyproject.toml` for core runtime/security-critical dependencies. Raise floors when upstream advisories require it.

| Dependency | Minimum floor policy | Rationale |
|---|---|---|
| `aiohttp` | `>=3.10.0` | Network boundary + HTTP client security fixes |
| `python-dotenv` | `>=1.0.0` | Stable env loading semantics |
| `torch` | `>=2.0.0` | Model runtime compatibility/security updates |
| `ultralytics` | `>=8.3.0` | Vision pipeline compatibility + fixes |
| `faster-whisper` | `>=1.1.0` | STT runtime compatibility |
| `claude-agent-sdk` | `>=0.1.0` | Agent/runtime protocol compatibility |

When adding new critical dependencies:
1. Add an explicit lower bound.
2. Document rationale in this table.
3. Add/update tests for config/runtime fallback behavior when feasible.

## 3) Monthly Maintenance Checklist

Run this once per month:

1. Update action pins:
   - Re-resolve latest trusted SHAs for pinned actions.
   - Update pins in `.github/workflows/*.yml`.
2. Refresh workflow binary pins:
   - `actionlint` version + checksum.
   - `gitleaks` version + checksum.
3. Review dependency updates:
   - Triage open Dependabot PRs.
   - Prioritize security updates and networking/auth libraries.
4. Run security workflows manually:
   - `security.yml` (CodeQL + pip-audit)
   - `secrets-scan.yml` (gitleaks)
   - `deploy-security-gate.yml` (release/deploy hardening checks)
5. Validate baseline exceptions:
   - Review `.gitleaksignore` entries.
   - Remove stale/obsolete fingerprints.
6. Confirm docs are current:
   - This runbook
   - `docs/operations/release-checklist.md`

## 4) Runtime Credential and Retention Guards

- Startup now emits warnings for potentially unsafe credential posture:
  - unusually short API tokens (`HASS_TOKEN`, `TODOIST_API_TOKEN`, `PUSHOVER_API_TOKEN`)
  - insecure webhook URLs for Slack/Discord (`http://` instead of `https://`)
  - `WEBHOOK_AUTH_TOKEN` configured without a `WEBHOOK_ALLOWLIST`
- Retention windows are configurable:
  - `MEMORY_RETENTION_DAYS`
  - `AUDIT_RETENTION_DAYS`
- Memory-write PII guardrails:
  - `MEMORY_PII_GUARDRAILS_ENABLED=true|false`
  - default behavior blocks memory writes that look like SSNs, card-like numbers, phone numbers, or email addresses unless explicitly overridden.
- A value of `0` disables pruning; positive values apply automatic startup pruning.