Skip to content

docs(security): document Docker UFW hardening via DOCKER-USER#27613

Merged
grp06 merged 4 commits intoopenclaw:mainfrom
dorukardahan:codex/docker-ufw-hardening-docs
Mar 3, 2026
Merged

docs(security): document Docker UFW hardening via DOCKER-USER#27613
grp06 merged 4 commits intoopenclaw:mainfrom
dorukardahan:codex/docker-ufw-hardening-docs

Conversation

@dorukardahan
Copy link
Copy Markdown
Contributor

Summary / What changed

  • Added a new security subsection in docs/gateway/security/index.md:
    • explains Docker port publishing vs host firewall assumptions
    • documents DOCKER-USER allowlist/drop policy guidance
    • includes IPv6 note (after6.rules) and validation commands
  • Added a cross-link in docs/install/docker.md so VPS users discover the hardening guidance earlier.

Why

Docker-published ports are handled through forwarding chains. Without explicit DOCKER-USER policy, users can think UFW is sufficient while exposure assumptions drift. This docs update gives concrete, actionable hardening guidance for common self-hosted setups.

Tests

  • pnpm check:docs

Real-world validation

  • Tested on a live Ubuntu 24.04 self-hosted VPS on February 26, 2026.
  • Applied equivalent DOCKER-USER policy (IPv4 + IPv6), reloaded UFW, and verified externally.
  • Full-port scans confirmed expected reachable ports only.
  • Service behavior remained healthy after firewall reload.

Issue

Fixes #27612

AI-assisted disclosure

  • AI-assisted: prepared with Codex, manually reviewed before submission.

@dorukardahan
Copy link
Copy Markdown
Contributor Author

Self-review: improvements from a second pass

  • I added an explicit IPv6 note (after6.rules) so users do not harden only IPv4 by mistake.
  • I kept the policy as an allowlist pattern in DOCKER-USER (trusted ranges + 80/443 + drop) because it is easier to audit than many per-port block rules.
  • I also added a short link from Docker install docs to this security section, so users can find it early.

@openclaw-barnacle openclaw-barnacle bot added docs Improvements or additions to documentation gateway Gateway runtime docker Docker and sandbox tooling size: XS labels Feb 26, 2026
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b9b8066d38

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +645 to +646
-A DOCKER-USER -i eth0 -j DROP
-A DOCKER-USER -j RETURN
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Replace hardcoded eth0 with actual public interface

The documented DOCKER-USER allowlist hardcodes -i eth0 and then falls through to -j RETURN, which means on common VPS setups where the external NIC is named ens3/enp*, none of the interface-gated rules match and the intended deny rule is skipped, leaving Docker-published ports reachable from the internet even when users follow this guide exactly. Use a placeholder (for example <public-iface>) or an interface-agnostic deny pattern so the policy remains effective across host network naming schemes.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good catch, thanks. i fixed this in b16c703.

i removed hardcoded interface rules and switched the example to interface-agnostic policy:

  • allow trusted source ranges
  • allow 80/443
  • drop remaining NEW forwarded traffic

i also added a note that hardcoding eth0 is unsafe because interface names vary across VPS images.

@greptile-apps
Copy link
Copy Markdown
Contributor

greptile-apps bot commented Feb 26, 2026

Greptile Summary

Added comprehensive Docker + UFW firewall hardening guidance to address a common security gap where users assume UFW alone protects Docker-published ports. The new documentation explains that Docker's forwarding chains bypass typical INPUT rules and provides a concrete DOCKER-USER iptables allowlist configuration with:

  • Clear explanation of why UFW alone is insufficient for Docker port publishing
  • Minimal working example of DOCKER-USER chain rules for IPv4
  • IPv6 consideration pointing to after6.rules
  • Validation commands using ufw, iptables, ip6tables, and nmap
  • Cross-reference added to Docker installation docs so VPS users discover this guidance early

The documentation follows repository conventions with proper Mintlify-compatible formatting, root-relative links, and generic placeholders. The iptables rules are technically sound as a minimal example and provide actionable hardening for self-hosted VPS deployments.

Confidence Score: 5/5

  • This PR is safe to merge with minimal risk as it only adds documentation with no code changes.
  • Documentation-only change that addresses a real security concern with accurate technical guidance. The iptables rules are valid, the formatting follows repository conventions (root-relative links, proper backtick usage, generic placeholders), and real-world testing was performed per the PR description. No code execution paths are modified.
  • No files require special attention.

Last reviewed commit: b9b8066

@bmendonca3
Copy link
Copy Markdown
Contributor

Security review note:

The Docker DOCKER-USER guidance is directionally solid and fills an important gap for VPS deployments.

Evidence I checked:

  • Docs-only changes in docs/gateway/security/index.md and docs/install/docker.md.
  • Current failing checks are not docs-specific:
    • protocol check drift (GatewayModels.swift diff)
    • shared Windows shard failures (src/plugins/loader.test.ts assertion)

Actionable suggestion:

  1. Rebase and rerun so CI reflects this docs-only change cleanly.
  2. Consider adding one sentence clarifying nftables environments (iptables-nft) so operators know the commands shown are expected to map to nft backends.

@dorukardahan
Copy link
Copy Markdown
Contributor Author

dorukardahan commented Feb 26, 2026

@bmendonca3 thanks, i applied both suggestions.

  • synced this branch with latest main and pushed (c0cdaf0)
  • added one sentence about iptables-nft frontend mapping in docs/gateway/security/index.md

local docs check is green (pnpm check:docs). if CI still shows red, it looks unrelated to this docs change.

@grp06 grp06 self-assigned this Mar 3, 2026
@grp06 grp06 force-pushed the codex/docker-ufw-hardening-docs branch from d6b14cb to 31ddd43 Compare March 3, 2026 20:21
@grp06 grp06 merged commit 2cd3be8 into openclaw:main Mar 3, 2026
8 of 9 checks passed
@grp06
Copy link
Copy Markdown
Member

grp06 commented Mar 3, 2026

Merged via squash.

Thanks @dorukardahan!

@dorukardahan
Copy link
Copy Markdown
Contributor Author

Thanks @grp06 for picking this up and merging it. I appreciate the changelog addition and the branch cleanup. I tested this guidance on my VPS and it matched what i observed in production.

ghostcoderraj pushed a commit to ghostcoderraj/openclaww that referenced this pull request Mar 3, 2026
…aw#27613)

Merged via squash.

Prepared head SHA: 31ddd43
Co-authored-by: dorukardahan <[email protected]>
Co-authored-by: grp06 <[email protected]>
Reviewed-by: @grp06