Egress Filter

Status

Version: 1.0.0 | Tests: Passing

Usage

devcontainer.json

{
    "features": {
        "ghcr.io/infrashift/trusted-devcontainer-features/egress-filter:latest": {
            "allowed_domains": "example.com",
            "squid_port": "3128",
            "allow_localhost": "true"
        }
    }
}

Options

Option	Type	Default	Description
allowed_domains	string	example.com	Comma-separated list of allowed domains. Prefix with '.' for subdomain matching.
squid_port	string	3128	Localhost port for the Squid proxy.
allow_localhost	boolean	true	Allow connections to localhost without proxy.

Dependencies

None — this feature is independent and has no dependencies.

How It Works

This feature installs and configures Squid proxy and iptables rules to enforce domain-based egress filtering within your devcontainer. It provides a network security boundary that restricts which external domains the container can reach, which is especially valuable when running AI coding agents that may make arbitrary network requests.

The Ansible playbook installs Squid via dnf, generates a squid.conf with the allowed domains whitelist derived from the allowed_domains option, and creates iptables rules that redirect all outbound HTTP and HTTPS traffic through the local Squid proxy. Domains can be prefixed with . for subdomain matching (e.g., .github.com allows api.github.com, raw.github.com, etc.). The proxy port defaults to 3128 and can be customized.

A startup script (egress-filter-start.sh) is registered as the postStartCommand to reapply the iptables rules and restart Squid each time the container starts, since iptables rules do not persist across container restarts. This ensures consistent enforcement throughout the container lifecycle.

This feature requires NET_ADMIN and NET_RAW Linux capabilities to be granted to the container in your devcontainer.json via the capAdd property. Without these capabilities, the iptables rules cannot be applied. Pair the egress filter with Claude Code or OpenAI Codex to control AI agent network access and enforce a least-privilege networking model.