{"id":13688734,"url":"https://github.com/kaysond/trafficjam","last_synced_at":"2025-05-01T20:30:34.700Z","repository":{"id":37611470,"uuid":"249029243","full_name":"kaysond/trafficjam","owner":"kaysond","description":"A Docker firewall for your reverse proxy network","archived":false,"fork":false,"pushed_at":"2025-04-20T17:42:51.000Z","size":156,"stargazers_count":144,"open_issues_count":3,"forks_count":12,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-23T01:05:25.347Z","etag":null,"topics":["docker","docker-swarm","swarm","traefik"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kaysond.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-21T17:44:23.000Z","updated_at":"2025-04-22T20:35:10.000Z","dependencies_parsed_at":"2024-01-14T16:05:55.026Z","dependency_job_id":"dd451962-e969-498e-b61b-e2bb91672103","html_url":"https://github.com/kaysond/trafficjam","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaysond%2Ftrafficjam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaysond%2Ftrafficjam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaysond%2Ftrafficjam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaysond%2Ftrafficjam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kaysond","download_url":"https://codeload.github.com/kaysond/trafficjam/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251940395,"owners_count":21668530,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-swarm","swarm","traefik"],"created_at":"2024-08-02T15:01:21.418Z","updated_at":"2025-05-01T20:30:34.694Z","avatar_url":"https://github.com/kaysond.png","language":"Shell","funding_links":[],"categories":["Shell","docker"],"sub_categories":[],"readme":"# TrafficJam (Beta)\nA Docker firewall for your reverse proxy network\n\n[![Build - Latest](https://github.com/kaysond/trafficjam/actions/workflows/build-latest.yml/badge.svg)](https://github.com/kaysond/trafficjam/actions/workflows/build-latest.yml) [![Build - Nightly](https://github.com/kaysond/trafficjam/actions/workflows/build-nightly.yml/badge.svg)](https://github.com/kaysond/trafficjam/actions/workflows/build-nightly.yml) [![CI](https://github.com/kaysond/trafficjam/actions/workflows/ci.yml/badge.svg)](https://github.com/kaysond/trafficjam/actions/workflows/ci.yml)\n## Threat Model\n**Why do you need something like TrafficJam?** Reverse proxies are often used to authenticate external access to internal services, providing benefits such as centralized user management, access control, 2FA and SSO. In a typical Docker setup, multiple services are connected to the reverse proxy via a single network. If a user authenticates to one service and is able to compromise that service (such as by using [this Pi-Hole vulnerability](https://natedotred.wordpress.com/2020/03/28/cve-2020-8816-pi-hole-remote-code-execution/ \"this Pi-Hole vulnerability\")), that user will gain access to the entire network *behind* the reverse proxy, and can access every service on the network whether they would normally have permission or not.\n\nPotential solutions include:\n* Use each service's own authentication\n  * Not all services provide 2FA :(\n  * Many services do not support centralized user management (LDAP)  :(\n  * Many services do not support SSO  :(\n* Have each service on a unique network\n  * Reverse proxy network connections must be updated every time a service is added or removed :(\n  * Manually configuring every service and reverse proxy entry is painful and error-prone even with tools like Ansible :(\n* Use a reverse proxy with auto-discovery and a firewall to isolate services\n  * Enables 2FA, LDAP, ACL, SSO, etc. regardless of service support :)\n  * Routes are automatically discovered by the proxy without manual configuration :)\n  * Every service only needs a connection to one network :)\n\n## What TrafficJam Does\nTrafficJam allows you to safely and easily connect all of your backend containers to your reverse proxy using a single docker network by preventing the backend containers from communicating with each other.\n\n![TrafficJam](./trafficjam-diagram.png)\n\n## How TrafficJam Works\nTrafficJam works by adding some firewall (`iptables`) rules to the docker network you specify. First, it blocks all traffic on the network. Then it adds a rule that only allows traffic to/from the container(s) you specify in the whitelist. It continually monitors the docker network to make sure the rules stay up to date as you add or remove containers.\n\n## Setup Examples\n\n### Vanilla Docker\n`docker-cli`:\n```\ndocker run \\\n  --name trafficjam \\\n  --cap-add NET_ADMIN \\\n  --network host \\\n  --volume \"/var/run/docker.sock:/var/run/docker.sock\" \\\n  --env NETWORK=traefik_public \\\n  --env WHITELIST_FILTER=\"ancestor=traefik:latest\" \\\n  --env TZ=\"America/Los_Angeles\" \\\n  --detach \\\n  kaysond/trafficjam\n```\n\n`docker-compose.yml`:\n```\nservices:\n  trafficjam:\n    container_name: trafficjam\n    image: kaysond/trafficjam\n    cap_add:\n      - NET_ADMIN\n    network_mode: host\n    volumes:\n     - /var/run/docker.sock:/var/run/docker.sock\n    environment:\n      NETWORK: traefik_public\n      WHITELIST_FILTER: ancestor=traefik:latest\n      TZ: America/Los_Angeles\n\n  traefik:\n    container_name: traefik\n    image: traefik:latest\n    networks:\n      traefik_public:\n\n  whoami:\n    container_name: whoami\n    image: traefik/whoami\n    networks:\n      traefik_public:\n\nnetworks:\n  traefik_public:\n```\n\n### Docker Swarm\n`docker-cli`:\n```\ndocker service create \\\n  --name trafficjam \\\n  --mount type=bind,source=/var/run/docker.sock,destination=/var/run/docker.sock \\\n  --env NETWORK=traefik_public \\\n  --env WHITELIST_FILTER=ancestor=traefik:v3.3.3@sha256:19884a9d0b922b321c9cff54cbfe43f3169893041b8dd4ea6100677afaddce46 \\\n  --env SWARM_DAEMON=true \\\n  --env TZ=America/Los_Angeles \\\n  --replicas 1 \\\n  --constraint node.role==manager \\\n  kaysond/trafficjam\n```\n\n`docker-compose.yml`:\n```\nservices:\n  trafficjam:\n    image: trafficjam\n    volumes:\n     - /var/run/docker.sock:/var/run/docker.sock\n    environment:\n      NETWORK: traefik_network\n      WHITELIST_FILTER: ancestor=traefik:v3.3.3@sha256:19884a9d0b922b321c9cff54cbfe43f3169893041b8dd4ea6100677afaddce46\n      SWARM_DAEMON: \"true\"\n      TZ: America/Los_Angeles\n    deploy:\n      replicas: 1\n      placement:\n        constraints: ['node.role==manager']\n```\n\n### Docker Socket Proxying\nThe attack surface of trafficjam is very low because it is not exposed to any networks; it's nearly the same as running the bash scripts outside of docker. For this reason, bind mounting the docker socket does not pose a significant security concern. It is possible to use a docker socket proxy nonetheless with some special setup. First, the proxy image must have a static IP address. Second, the environment variable `DOCKER_HOST` must be set on **trafficjam** to `tcp://\u003cproxy ip address\u003e:2375`. For more details, see #15.\n\n**Notes:** \nDocker Swarm services tag images with a sha256 hash to guarantee that every node runs the exact same container (since tags are mutable). When using the `ancestor` tag, ensure that the appropriate hash is included as shown in the examples.\n\n`trafficjam` requires the `NET_ADMIN` Linux capability in order to manipulate `iptables` rules. For Docker Swarm setups, `SYS_ADMIN` is also required in order to enter namespaces, though the setting of container capabilities is automatically handled by the `trafficjam` swarm daemon.\n\n## Configuration\nTrafficJam is configured via several environment variables:\n* **NETWORK** - The name of the Docker network this instance of TrafficJam should manage (multiple instances can be run for different networks)\n* **WHITELIST_FILTER** - A Docker `--filter` parameter that designates which containers should be permitted to openly access the network. See [Docker Docs - filtering](https://docs.docker.com/engine/reference/commandline/ps/#filtering)\n* **TZ** - Timezone (for logging)\n* **INSTANCE_ID** - A unique alphanumeric instance ID that is required to run multiple instances of trafficjam\n* **SWARM_DAEMON** - Setting this variable is required for swarm and activates a daemon that determines network load balancer IP addresses and properly configures the trafficjam service\n* **SWARM_IMAGE** - The image the trafficjam swarm daemon should deploy (defaults to `kaysond/trafficjam`). The best practice is to pin this to a particular image hash (e.g. `kaysond/trafficjam:v1.0.0@sha256:8d41599fa564e058f7eb396016e229402730841fa43994124a8fb3a14f1a9122`)\n* **POLL_INTERVAL** - How often TrafficJam checks Docker for changes\n* **ALLOW_HOST_TRAFFIC** - Allow containers to initiate communication with the docker host, and thus any port-mapped containers. Most users do not need this setting enabled. (See [ARCHITECTURE.md](ARCHITECTURE.md)). Note that if this setting is enabled while old rules exist, some will not be cleared automatically and must be done so manually (See [Clearing Rules](#clearing-rules)).\n* **DEBUG** - Setting this variable turns on debug logging\n\n## Dependencies\n* Linux with iptables whose version is compatible with the iptables in TrafficJam (currently `1.8.10`)\n  * **NOTE:** support for legacy iptables (non-nftables) is deprecated, not actively tested, and will be removed from a future release.\n* Modern version of Docker (trafficjam image and CI use 28.0.4)\n\n## Known Limitations\n* ipv6 is currently unsupported\n* networks with multiple IPAM configurations (e.g. ipv4 and ipv6 subnets) are not supported\n\n## Clearing Rules\n`trafficjam` can be run with the `--clear` argument to remove all rules that have been set. Note that the host docker socket must be mounted within the container. The rules can also be cleared by sending the `SIGUSR1` signal to the container. This will cause `trafficjam` to exit.\n\nExamples:\n* `docker run --volume \"/var/run/docker.sock:/var/run/docker.sock\" --cap-add NET_ADMIN --network host kaysond/trafficjam --clear`\n* `docker kill --signal SIGUSR1 trafficjam`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaysond%2Ftrafficjam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaysond%2Ftrafficjam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaysond%2Ftrafficjam/lists"}