Docker and UFW Firewall Security Strategy

[josecelano]

Overview

During implementation of issue #246 (Grafana slice), we re-encountered a known but forgotten issue: Docker bypasses UFW firewall rules. This behavior was previously addressed in the Torrust Tracker Live Demo by using Digital Ocean's cloud firewall, but that solution was deliberately avoided in the deployer to maintain provider portability.

The deployer chose UFW for firewall management to avoid cloud-provider-specific features. However, during development, we configured UFW expecting it to block Docker-exposed ports, forgetting that Docker manipulates iptables directly and bypasses UFW rules entirely.

This task involves creating a comprehensive, documented security strategy that correctly addresses Docker-UFW interaction while maintaining provider-agnostic deployment capabilities.

Specification

See detailed specification: docs/issues/248-docker-ufw-firewall-security-strategy.md

(This link will be updated after the file is renamed with the issue number)

🏗️ Architecture Requirements

DDD Layer: Multiple (Domain, Infrastructure, Application)
Module Path: templates/ansible/, templates/docker-compose/, Security validation in application layer (future)
Pattern: Infrastructure as Code (IaC) templates, Architectural Decision Record

Architectural Constraints

• Maintain provider-agnostic deployment approach
• Use layered security approach (instance-level + service-level)
• Follow Infrastructure as Software principles
• Error handling for security misconfigurations must be explicit and actionable

Implementation Plan

Phase 1: Research and Analysis (2-3 hours)

• Review prior work in Torrust Tracker Live Demo project
• Review Docker official documentation on UFW incompatibility
• Study Docker networking security model
• Document threat model and attack vectors
• Evaluate trade-offs: simplicity vs security vs portability

Phase 2: Design and Documentation (2-3 hours)

• Create comprehensive ADR for firewall security strategy
• Define explicit rules for which services should have port bindings
• Design validation/linting strategy for docker-compose security
• Create security testing strategy for E2E tests

Phase 3: Template Implementation (3-4 hours)

• Remove obsolete templates/ansible/configure-tracker-firewall.yml
• Remove tracker firewall step and registrations
• Update firewall playbook to clarify SSH-only management
• Review and update all docker-compose templates
• Add explicit comments documenting public vs internal services

Phase 4: Validation and Testing (2-3 hours)

• Design and implement E2E security tests
• Verify internal services are NOT accessible externally
• Verify public services ARE accessible with correct ports
• Document testing procedures

Phase 5: Documentation and Review (1-2 hours)

• Review and update docs/user-guide/security.md
• Document deployment security best practices
• Add warnings about Docker port binding risks
• Security audit of final implementation

Acceptance Criteria

Quality Checks:

• Pre-commit checks pass: ./scripts/pre-commit.sh

Research and Analysis:

• Docker networking security model documented
• UFW-Docker interaction thoroughly understood
• Threat model documented with attack vectors

Design and Documentation:

• ADR created in docs/decisions/ following ADR template
• Security strategy explicitly documented with examples
• Clear rules for public vs internal service configuration

Implementation:

• All docker-compose templates updated with security strategy
• Internal services have NO port bindings (or localhost-only)
• Public services have EXPLICIT port bindings with comments

Testing:

• E2E tests verify internal services are NOT externally accessible
• E2E tests verify public services ARE externally accessible
• All existing E2E tests pass

Documentation:

• User guide updated with security strategy
• Architecture documentation reflects security patterns
• Comments in templates explain security decisions

Related

• Discovered in: Grafana Slice - Add Grafana metrics visualization service #246 - Grafana slice implementation
• Related: torrust-demo#72 - Docker bypassing systemd-resolved
• Specification: docs/issues/docker-ufw-firewall-security-strategy.md (will be renamed with issue number)

Priority

CRITICAL because:

1. Security vulnerability - Internal services can be accidentally exposed
2. Silent failure - UFW shows correct configuration but doesn't protect
3. False sense of security - Developers may assume UFW is protecting them
4. Production impact - Affects all deployments using Docker