archy/docs/adr/009-manifest-container-security.md

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