# ADR-009: Manifest-Level Container Security Enforcement

## Status

Accepted

## Context

Archipelago runs third-party applications as containers. Without enforcement, containers could:

- Run as root and escalate privileges
- Access the host filesystem
- Modify their own binaries (persistence of malicious code)
- Acquire unnecessary Linux capabilities
- Use unverified or tampered container images

Other node OS projects (Umbrel, Start9) vary in their security enforcement. Archipelago targets a higher security bar suitable for handling Bitcoin private keys and personal data.

## Decision

Enforce security constraints at the **manifest level**, applied automatically during container creation. Every container MUST comply with these non-negotiable defaults:

### Mandatory Security Defaults

| Constraint | Value | Rationale |
|-----------|-------|-----------|
| `readonly_root` | `true` | Prevents runtime filesystem modification (anti-persistence) |
| `no_new_privileges` | `true` | Prevents privilege escalation via setuid/setgid |
| `user` | UID > 1000 | Never run as root |
| `capabilities` | Drop ALL, add only required | Principle of least privilege |
| `image_tag` | Pinned version | No `latest` tags — reproducible deploys |
| `seccomp_profile` | Default | Blocks dangerous syscalls |

### Manifest Enforcement

The `core/container/` module validates manifests before container creation:

1. **Parse** the YAML manifest
2. **Validate** all required security fields are present
3. **Reject** manifests that violate mandatory defaults (e.g., `readonly_root: false` without explicit override)
4. **Apply** security context during `podman create`

### Optional Overrides

Some apps legitimately need elevated privileges:

- `readonly_root: false` — Only for apps that must write to their root filesystem (documented reason required)
- Additional capabilities (e.g., `NET_ADMIN` for VPN apps) — must be explicitly listed and justified

## Consequences

### Positive

- Defense in depth — even if a container image is compromised, damage is limited
- Consistent security posture across all apps
- Transparent — users can inspect any app's security manifest
- Aligns with industry best practices (CIS Benchmarks, NIST)

### Negative

- Some apps may not work without modifications (e.g., apps expecting root)
- Read-only root requires explicit volume mounts for writable directories
- Developers must understand and comply with the security model
- Slightly more complex manifest format than competitors

### Mitigations

- Clear documentation in `docs/app-manifest-spec.md`
- Example manifests for common app patterns
- Build-time validation catches issues before deployment
- Override mechanism for legitimate exceptions (with audit trail)

## References

- `docs/app-manifest-spec.md` — Full manifest specification
- `core/container/src/` — Container security implementation
- `core/security/src/` — AppArmor profiles and secrets management