[IMP] Modify README

Author: josep-tecnativa

README.md

@@ -1,174 +1,198 @@
-# Docker Whitelist Gateway (Multi-Destination Edition)
+# Docker Whitelist Gateway
 
-A transparent outbound firewall + DNS gateway for Docker internal networks.
+Outbound network gateway + filtered DNS for Docker internal networks.
 
-This project allows containers attached to **internal (isolated) Docker networks** to
-reach selected external destinations while keeping all other outbound traffic blocked.
+This project allows containers attached to **internal Docker networks** to reach only a
+defined set of external destinations, while preserving internal Docker service
+resolution.
 
-Unlike classic single-target whitelist proxies, this implementation supports:
+It is designed for stacks where:
 
--   Multiple external destinations (multi-destination)
--   Dynamic DNS resolution
--   Automatic subnet detection (no fixed IP configuration)
--   Internal service resolution preservation
--   Transparent TCP forwarding using iptables + asyncio
+-   the main application runs on an internal network
+-   outbound internet access must be restricted
+-   only specific domains or IPs should be reachable
+-   internal Docker service names must continue to resolve normally
 
 ---
 
-## Architecture Overview
+## Architecture
 
-The gateway is designed for environments where:
+The setup usually uses two containers:
 
--   The main service runs in a Docker **internal network**
--   Outbound internet access must be restricted
--   Only specific domains/IPs should be reachable
--   Internal service discovery must keep working
+1. **gateway container**
 
-The architecture typically uses two containers:
+    - enables IPv4 forwarding
+    - applies `iptables` and `ipset` rules
+    - performs NAT/masquerading for outbound traffic
+    - periodically resolves allowed hosts and populates the whitelist
 
-1.  **gateway container**
-    -   Runs iptables rules
-    -   Runs async TCP forwarder
-    -   Runs controlled DNS (dnsmasq)
-    -   Whitelists allowed destinations
-2.  **net_setup sidecar (optional but recommended)**
-    -   Shares network namespace with the main service
-    -   Rewrites default route to gateway
-    -   Rewrites /etc/resolv.conf to use gateway DNS
+2. **net_setup sidecar**
+    - shares the network namespace of the main app container
+    - rewrites the default route so traffic exits through the gateway
+    - optionally starts a **local dnsmasq**
+    - generates internal DNS entries automatically from Docker metadata
 
 ---
 
-## How It Works
+## How it works
 
-### Traffic Redirection
+### Outbound traffic filtering
 
-The gateway:
+The gateway container maintains an `ipset` containing the IPs resolved from
+`ALLOWED_HOSTS`.
 
--   Installs NAT REDIRECT rules
--   Captures outbound TCP traffic
--   Recovers original destination using `SO_ORIGINAL_DST`
--   Forwards only if destination is allowed
+Traffic is allowed only when the destination IP matches that set.
 
-All other outbound traffic is dropped.
+The gateway also installs:
+
+-   a `FORWARD` rule allowing `RELATED,ESTABLISHED`
+-   a `FORWARD` rule allowing destinations present in the whitelist ipset
+-   a `POSTROUTING MASQUERADE` rule for outbound NAT
+
+This means the application can only reach external destinations whose IPs are currently
+present in the whitelist.
 
 ---
 
-### Controlled DNS
+### DNS behavior
 
-When the main container switches its resolver to the gateway:
+There are two DNS layers:
 
--   Internal Docker names must still resolve
--   External domains must be filtered
+#### 1. Local app DNS (inside the app namespace)
 
-The gateway:
+When `DNS_LOCAL=1` is enabled in `net_setup`:
 
--   Uses Docker DNS to resolve internal services
--   Runs dnsmasq for controlled external resolution
--   Returns `0.0.0.0` for non-allowed domains
+-   `dnsmasq` listens on `127.0.0.1`
+-   `/etc/resolv.conf` is rewritten to use `127.0.0.1`
+-   external resolution is restricted to domains derived from `ALLOWED_HOSTS`
+-   internal Docker service names are served from an autogenerated hosts file
 
-Allowed example:
+#### 2. Internal Docker service resolution
 
-    transfer.einsamobile.de → 194.26.180.120
+Internal names are not maintained manually.
 
-Blocked example:
+Instead, the sidecar can generate `/run/dnsmasq-internal.hosts` from Docker metadata
+using the Docker socket. This includes:
 
-    www.google.com → 0.0.0.0
+-   Compose service names (`db`, `smtp`, `odoo`, etc.)
+-   explicit network aliases (`wdb_internal`, etc.)
+-   container names when useful
+
+This preserves internal service discovery without relying on Docker DNS as an upstream
+resolver.
 
 ---
 
-## Required Capability
+## Required capability
 
 ```yaml
 cap_add:
     - NET_ADMIN
 ```
 
----
-
-## Environment Variables
-
-### ALLOWED_HOSTS (Required)
-
-Space-separated list of domains or IPs allowed for outbound access.
+For automatic internal DNS generation, the net setup sidecar also needs access to the
+Docker socket:
 
 ```yaml
-environment:
-    ALLOWED_HOSTS: "api.example.com smtp.example.com 1.2.3.4"
+volumes:
+    - /var/run/docker.sock:/var/run/docker.sock:ro
 ```
 
 ---
 
-### PORT
+## Environment variables
 
-Default: `*`
+### Common
 
-Defines allowed TCP ports.
+#### `ALLOWED_HOSTS` (required)
 
-Examples:
+Space-separated list of allowed external domains and/or IPs.
+
+Example:
 
 ```yaml
-PORT: "443"
-PORT: "80 443 8080"
-PORT: "21 50000-51000"
+ALLOWED_HOSTS: "graph.microsoft.com api.example.com 1.2.3.4"
 ```
 
+Domains are used for:
+
+-   whitelist IP resolution in the gateway
+-   filtered external DNS in local dnsmasq
+
+IP literals are added directly to the whitelist.
+
 ---
 
-### PRE_RESOLVE
+#### `DNS_UPSTREAMS`
 
-Default: `0`
+Default:
 
-When enabled (`1`):
+```yaml
+DNS_UPSTREAMS: "1.1.1.1 8.8.8.8"
+```
 
--   The gateway resolves allowed domains itself
--   Refreshes periodically
--   Avoids dependency on system DNS
+Upstream resolvers used by dnsmasq for allowed external domains.
 
 ---
 
-### RESOLVE_INTERVAL
+### Gateway mode
 
-Default: `60`
+#### `MODE_RUN=gateway`
 
-DNS refresh interval in seconds when `PRE_RESOLVE=1`.
+Runs the container as the outbound network gateway.
 
----
+Optional:
 
-### DNS_UPSTREAMS
-
-Default: `1.1.1.1 8.8.8.8`
+```yaml
+IPSET_NAME: "whitelist"
+REFRESH_INTERVAL: "300"
+```
 
-Upstream DNS servers used by dnsmasq.
+-   `IPSET_NAME`: name of the whitelist ipset
+-   `REFRESH_INTERVAL`: refresh interval in seconds for resolving allowed hosts
 
 ---
 
-### DNS_INTERNAL_NAMES
+### Net setup mode
 
-Optional.
+#### `MODE_RUN=net_setup`
 
-Defines internal Docker service names that must always resolve.
+Runs the container as the sidecar that configures routing and DNS for the main app.
 
-Example:
+Required:
+
+```yaml
+GATEWAY_NAME: "proxy_general"
+```
+
+This must resolve to the gateway container on the shared Docker network.
+
+Optional:
 
 ```yaml
-DNS_INTERNAL_NAMES: "db smtp redis backend gateway"
+DNS_LOCAL: "1"
+DNS_INTERNAL_FROM_DOCKER: "1"
+DOCKER_PROJECT: "my-project"
+DOCKER_PRIMARY_SERVICE: "odoo"
+DNS_DOCKER_REFRESH_INTERVAL: "5"
 ```
 
-Only required if the gateway replaces Docker's default resolver and you want
-deterministic internal resolution.
+-   `DNS_LOCAL=1`: enable local dnsmasq in the app namespace
+-   `DNS_INTERNAL_FROM_DOCKER=1`: generate internal DNS entries from Docker metadata
+-   `DOCKER_PROJECT`: Compose project name used to discover related containers
+-   `DOCKER_PRIMARY_SERVICE`: main service whose visible networks define the DNS scope
+-   `DNS_DOCKER_REFRESH_INTERVAL`: refresh interval for autogenerated internal hosts
 
 ---
 
-## Multi-Destination Example (Generic Service)
+## Example
 
 ```yaml
 services:
     app:
         image: my-app
         networks:
             - internal
-        cap_add:
-            - NET_ADMIN
         depends_on:
             - gateway
 
@@ -177,9 +201,16 @@ services:
         network_mode: "service:app"
         cap_add:
             - NET_ADMIN
+        volumes:
+            - /var/run/docker.sock:/var/run/docker.sock:ro
         environment:
-            MODE_RUN: net_setup
-            GATEWAY_NAME: gateway
+            MODE_RUN: "net_setup"
+            GATEWAY_NAME: "gateway"
+            DNS_LOCAL: "1"
+            DNS_INTERNAL_FROM_DOCKER: "1"
+            DOCKER_PROJECT: "my-project"
+            DOCKER_PRIMARY_SERVICE: "app"
+            ALLOWED_HOSTS: "graph.microsoft.com api.example.com"
 
     gateway:
         image: docker-whitelist-gateway:latest
@@ -189,8 +220,8 @@ services:
             - internal
             - public
         environment:
-            ALLOWED_HOSTS: "api.stripe.com smtp.mailgun.org ftp.partner.com"
-            PRE_RESOLVE: 1
+            MODE_RUN: "gateway"
+            ALLOWED_HOSTS: "graph.microsoft.com api.example.com"
 
 networks:
     internal:
@@ -200,15 +231,21 @@ networks:
 
 ---
 
-## Summary
+## Current behavior summary
 
-Docker Whitelist Gateway provides:
+This implementation now provides:
+
+-   outbound filtering based on destination IP whitelist
+-   automatic refresh of allowed destination IPs
+-   local filtered DNS for the application
+-   automatic internal Docker name resolution from Docker metadata
+-   no need to maintain `DNS_INTERNAL_NAMES` manually in normal setups
+
+---
 
--   Transparent outbound filtering
--   DNS-level control
--   Multi-destination support
--   Automatic dynamic routing
--   Clean separation between service and firewall logic
+## Notes
 
-It is designed for secure containerized environments where outbound access must be
-explicitly controlled.
+-   The gateway healthcheck validates the current `iptables`/`ipset`-based setup.
+-   Internal DNS generation depends on the Docker socket and Compose metadata.
+-   External DNS resolution is intentionally restricted to domains derived from
+    `ALLOWED_HOSTS`.