boma/docs/decisions/002-security.md

# ADR-002 — Security baseline and strategy

## Context

Security here is not a single control but the sum of several combined efforts —
host hardening, network segmentation, secrets handling, supply-chain hygiene, and
disciplined automation. This ADR is the frame that organizes them: it records the
**threat model** we design against, the **principles** every control serves, the
host-level **baseline** the `base` role enforces, and the **governance** that keeps
security sharp as the homelab grows.

The goal is a principled, maintainable posture for a homelab with some
public-facing services — effective against a realistic threat model, not a
compliance exercise.

Related decisions: network segmentation (ADR-007), secrets structure (ADR-003),
per-service roles (ADR-004), CI secret-scanning (ADR-010).

## Threat model

What we deliberately design against — and, just as importantly, what we do not:

| Threat | In scope? | What it drives |
|---|---|---|
| **Opportunistic external** — bots scanning, credential stuffing, mass-exploiting known CVEs in exposed services | Yes — primary | SSH key-only + fail2ban, deny-by-default firewall, security auto-patching, minimal attack surface, services behind a reverse proxy with auth |
| **Lateral movement / blast radius** — assume one service *is* compromised; limit how far it spreads | Yes | VLAN segmentation (ADR-007), least-privilege containers, no host network mode, per-service isolation, no shared credentials |
| **Operator / agent error** — accidental secret leak, misconfiguration, or an AI agent making an unsafe change | Yes | Vault + gitleaks, declarative firewall (no ad-hoc ports), review gates, agent guardrails (below), pre-commit hooks |
| **Supply chain** — compromised images, base images, dependencies, collections | Acknowledged, lower priority | Version pinning where practical (ADR-011), gitleaks; tracked as an accepted risk with a revisit trigger |
| **Targeted / physical** — a determined adversary specifically after this homelab, or physical device access | Out of scope | Not designed against at this scale; revisit if the threat model changes |

Supply chain is consciously deprioritized, not forgotten — see
`docs/security/accepted-risks.md`.

## Security principles

Every control below should trace back to one of these:

- **Defense in depth** — no single control is load-bearing; layers compensate.
- **Least privilege** — accounts, containers, and automation get the minimum they need.
- **Deny / secure by default** — closed unless explicitly opened; safe defaults.
- **Contain the blast radius** — segment and isolate so one compromise isn't total.
- **Automated & reproducible** — the baseline is reached by Ansible, never by hand.
- **Explicit & revisitable** — decisions and accepted risks are written down and
  re-challenged, not left implicit.

## Baseline controls

Applied by the `base` role, non-negotiable — it runs first, on every host, every
time. Each heading tags the threat(s) it primarily serves.

### Access & authentication — *opportunistic, agent error*

- SSH key authentication only — password auth disabled
- Root login disabled — `PermitRootLogin no`
- Dedicated `ansible` user with locked-down sudo (NOPASSWD for automation)
- No shared user accounts — per-person SSH keys in `group_vars/all/vars.yml`

### Firewall — *opportunistic, blast radius, agent error*

- `nftables` (native on Debian 13, replaces iptables)
- Default policy: deny inbound, allow established/related, allow loopback
- Rules managed entirely by Ansible — never edited manually on hosts
- Port definitions live in `group_vars/` so rules stay in sync with deployed services
- Docker's own iptables rules are disabled — nftables manages all filtering

> **Note on Docker + nftables**: Docker historically bypassed iptables-based firewalls.
> This is addressed by setting `"iptables": false` in Docker daemon config and managing
> all rules via nftables explicitly. See `docs/decisions/004-docker-model.md`.

### Intrusion deterrence — *opportunistic*

- `fail2ban` monitoring SSH (and optionally reverse proxy logs)
- Configured to ban after 5 failed attempts, 1-hour ban

### Updates — *opportunistic*

- `unattended-upgrades` enabled for **security patches only**
- Full system upgrades triggered deliberately via Ansible (`make deploy PLAYBOOK=upgrade`)
- No automatic reboots — reboots are a conscious operational decision

### Minimal attack surface — *opportunistic, blast radius*

- No unnecessary packages installed
- Docker daemon TCP socket disabled — Unix socket only
- No open ports beyond those explicitly defined in firewall rules

### Audit trail — *agent error, blast radius*

- `auditd` installed and running with a baseline ruleset
- Logs shipped to a central location if a log aggregation service is available

## Secrets management — *agent error, opportunistic*

- Ansible Vault for all secrets (API keys, passwords, certificates), structured as a
  nested `vault.<service>.<key>` map (ADR-003)
- The master vault password lives in **Vaultwarden** and is fetched on demand by
  `scripts/vault-pass-client.sh` (wired as `vault_password_file`) through the `rbw`
  agent — never written to a plaintext file on disk. Unlock once per session with
  `rbw unlock`; nothing decryptable sits at rest in the repo or working tree
- See `docs/runbooks/rotate-secrets.md` for `rbw` setup and rotation

## Governance

Security is maintained, not achieved once. This ADR **establishes** four
mechanisms; each lives where change is cheap and is linked from here.

- **Per-service security bar** — every exposed service must clear a defined
  checklist before deploy (secrets in vault, no default creds, least-privilege /
  non-root, declared firewall ports, reverse-proxy + auth if exposed). Lives in
  `docs/security/service-checklist.md`; referenced from `docs/runbooks/new-role.md`.
  Enforced manually in review today; the planned `/security-review` will automate it.
- **Periodic security review** — a recurring review that re-checks posture,
  surfaces drift, and re-challenges accepted risks. Planned as a `/security-review`
  skill (sibling to `/review-repo`); see `docs/TODO.md` (Scheduled work). Not built
  yet — see STATUS.md.
- **Accepted-risk register** — the conscious trade-offs we choose to live with, each
  with rationale and a revisit trigger. Lives in `docs/security/accepted-risks.md`
  (expected to change; kept out of this ADR so the ADR stays stable).
- **Agent / automation guardrails** — what AI agents and automation may do
  unsupervised vs. what needs a human gate, since operator/agent error is in the
  threat model. Encoded in `CLAUDE.md` ("What Claude must not do without explicit
  instruction") and enforced by PreToolUse hooks (generated-file guard, `rbw`
  pre-flight).

## Decision

This posture was chosen to be:

- **Effective** against the stated threat model (opportunistic external, lateral
  movement, operator/agent error)
- **Maintainable** by a small team without security-expertise overhead
- **Automated** — no manual steps to reach baseline state
- **Legible & revisitable** — the threat model, principles, and accepted risks are
  written down and reviewed over time, not implicit

Out-of-scope items and conscious trade-offs are recorded in
`docs/security/accepted-risks.md` rather than here, so this decision record stays
stable while the risk posture evolves.