Merge #249: feat: [#248] implement Docker/UFW firewall security strategy

78bbf21 fix: [#248] remove duplicate heading in security.md (Jose Celano)
11165fb docs: [#248] update security guide with Docker/UFW layered approach (Jose Celano)
317c47f docs: [#248] document manual E2E test results for network segmentation (Jose Celano)
46cd008 refactor: [#248] implement three-network Docker segmentation for defense in depth (Jose Celano)
d6cddb3 refactor: [#248] remove obsolete UFW tracker firewall configuration (Jose Celano)
f039664 docs: [#248] add comprehensive security documentation and analysis (Jose Celano)

Pull request description:

  ## Overview

  This PR implements a comprehensive Docker/UFW firewall security strategy to address the critical security issue where Docker bypasses UFW firewall rules.

  ## Problem

  Docker manipulates iptables directly, bypassing UFW rules for published container ports. This means services like MySQL and Prometheus can be accidentally exposed publicly even when UFW rules deny access.

  ## Solution

  Implemented a **layered security approach** combining:

  1. **Instance-Level Security (UFW)** - Protects SSH access only
  2. **Service-Level Security (Docker)** - Controls service exposure via port bindings
  3. **Network Segmentation** - Three isolated Docker networks for defense-in-depth

  ## Key Changes

  ### Phase 3.1: UFW Cleanup ✅
  - Removed obsolete UFW tracker firewall configuration
  - Updated base firewall to only manage SSH access
  - Added comments explaining Docker bypasses UFW

  ### Phase 3.2: Network Segmentation ✅
  - Implemented three-network architecture:
    - `database_network`: Tracker ↔ MySQL only
    - `metrics_network`: Tracker ↔ Prometheus only
    - `visualization_network`: Prometheus ↔ Grafana only
  - Updated docker-compose template with network segmentation
  - Added comprehensive security comments

  ### Phase 3.2: Manual E2E Testing ✅
  - All positive tests passed: Tracker→MySQL, Prometheus→Tracker, Grafana→Prometheus
  - All negative tests passed: Grafana/Prometheus blocked from MySQL
  - Test results documented in `docs/issues/manual-tests/248-network-segmentation-test-results.md`

  ### Phase 5: Documentation ✅
  - Updated `docs/user-guide/security.md` with correct Docker/UFW architecture
  - Documented service exposure strategy (Public/Localhost/Internal)
  - Added security best practices and warnings

  ## Security Impact

  ✅ **66% reduction in MySQL attack surface** (3 services → 1 service)
  ✅ Network isolation prevents lateral movement
  ✅ Production-ready implementation validated
  ✅ All manual E2E tests passed

  ## Testing

  - ✅ All unit tests pass
  - ✅ All E2E tests pass (infrastructure lifecycle + deployment workflow)
  - ✅ Manual E2E testing completed with 100% success rate
  - ✅ Pre-commit checks pass

  ## Documentation

  - ✅ Issue specification: `docs/issues/248-docker-ufw-firewall-security-strategy.md`
  - ✅ Manual test results: `docs/issues/manual-tests/248-network-segmentation-test-results.md`
  - ✅ User security guide updated: `docs/user-guide/security.md`
  - ✅ ADR created: `docs/decisions/docker-ufw-firewall-security-strategy.md`
  - ✅ Network analysis: `docs/analysis/security/docker-network-segmentation-analysis.md`

  ## Related

  - Fixes #248
  - Related to #246 (where this issue was discovered)

  ---

  **Ready for review and merge** - All implementation and testing complete, production-ready.

ACKs for top commit:
  josecelano:
    ACK 78bbf21

Tree-SHA512: b21b3c40cda816af427ae2498a65e37d688a85e2a9195c33667cda67bce5110abd0e2a286855711949bad2118367f83a13771c290d9b8fe1dc6c69ad9ef5ffeb

Author: josecelano

docs/analysis/security/docker-network-segmentation-analysis.md

@@ -218,6 +218,25 @@ mv docs/issues/scaffolding-for-main-app-epic.md \
 - Keep descriptive but concise
 - Match branch naming convention
 
+**Manual Test Documentation** (Optional):
+
+If your issue requires extensive manual E2E testing, you can document test results in:
+
+```bash
+docs/issues/manual-tests/{issue-number}-{description}.md
+```
+
+Example:
+
+- `docs/issues/manual-tests/248-network-segmentation-test-results.md`
+
+This extra documentation:
+
+- Provides detailed test results for complex implementations
+- Can include test commands, expected outputs, screenshots, and verification steps
+- Should be linked from the main issue specification file
+- Will be deleted when the issue is cleaned up (see [Cleanup Process](#cleanup-process))
+
 ### Step 6: Update GitHub Task Issue
 
 Update the task issue with the correct file link:
@@ -504,29 +523,49 @@ Over time, as issues are completed and closed on GitHub, the `docs/issues/` fold
    - `CLOSED` - Issue has been completed (remove the file)
    - `NOT_FOUND` - Issue doesn't exist (remove the file)
 
-3. **Remove Closed Issue Files**:
+3. **Check for Manual Test Documentation**:
+
+   Some issues may have additional manual testing documentation in `docs/issues/manual-tests/`:
 
    ```bash
-   # Remove specific closed issue files
+   # Check if manual test documentation exists for closed issues
+   ls docs/issues/manual-tests/
+
+   # Manual test files follow format: {issue-number}-{description}.md
+   # Example: 248-network-segmentation-test-results.md
+   ```
+
+4. **Remove Closed Issue Files and Manual Tests**:
+
+   ```bash
+   # Remove specific closed issue specification files
    cd docs/issues/
    rm -f 21-fix-e2e-infrastructure-preservation.md \
          22-rename-app-commands-to-command-handlers.md \
          23-add-clap-subcommand-configuration.md \
          24-add-user-documentation.md
+
+   # Remove associated manual test documentation (if exists)
+   cd manual-tests/
+   rm -f 21-*.md 22-*.md 23-*.md 24-*.md
+
+   # Or remove specific files if you know the names
+   rm -f 248-network-segmentation-test-results.md
    ```
 
-4. **Verify Remaining Files**:
+5. **Verify Remaining Files**:
 
    ```bash
    ls docs/issues/
+   ls docs/issues/manual-tests/
    ```
 
-   Only open issues and template files should remain.
+   Only open issues, their associated manual tests, and template files should remain.
 
-5. **Commit the Changes**:
+6. **Commit the Changes**:
 
    ```bash
-   # Stage the deletions
+   # Stage the deletions (both issue specs and manual tests)
    git add docs/issues/
 
    # Commit with descriptive message
@@ -538,6 +577,8 @@ Over time, as issues are completed and closed on GitHub, the `docs/issues/` fold
    - #23: add-clap-subcommand-configuration
    - #24: add-user-documentation
 
+   Also removed associated manual test documentation from docs/issues/manual-tests/.
+
    All these issues have been closed on GitHub and no longer need
    local documentation files.
 
@@ -550,6 +591,7 @@ Over time, as issues are completed and closed on GitHub, the `docs/issues/` fold
 ### Important Notes
 
 - **Keep Template Files**: Never delete `EPIC-TEMPLATE.md`, `GITHUB-ISSUE-TEMPLATE.md`, or `SPECIFICATION-TEMPLATE.md`
+- **Manual Test Documentation**: Check `docs/issues/manual-tests/` for issue-specific test results (format: `{issue-number}-*.md`) and remove them along with the issue specification
 - **Verify Before Deleting**: Always double-check issue status before removing files
 - **Document Removals**: Use descriptive commit messages listing which issues were removed
 - **Team Communication**: Consider notifying the team before large cleanup operations