{"id":13440398,"url":"https://github.com/rustybird/corridor","last_synced_at":"2025-03-20T09:33:00.279Z","repository":{"id":14132076,"uuid":"16837470","full_name":"rustybird/corridor","owner":"rustybird","description":"Tor traffic whitelisting gateway","archived":false,"fork":false,"pushed_at":"2024-11-27T15:52:50.000Z","size":185,"stargazers_count":68,"open_issues_count":9,"forks_count":6,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-11-27T16:43:14.421Z","etag":null,"topics":["firewall","tor"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rustybird.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-ISC","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":"2014-02-14T13:07:53.000Z","updated_at":"2024-11-27T15:52:54.000Z","dependencies_parsed_at":"2024-10-27T23:46:33.858Z","dependency_job_id":null,"html_url":"https://github.com/rustybird/corridor","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rustybird%2Fcorridor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rustybird%2Fcorridor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rustybird%2Fcorridor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rustybird%2Fcorridor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rustybird","download_url":"https://codeload.github.com/rustybird/corridor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244586018,"owners_count":20476860,"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":["firewall","tor"],"created_at":"2024-07-31T03:01:22.417Z","updated_at":"2025-03-20T09:33:00.268Z","avatar_url":"https://github.com/rustybird.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# corridor, a Tor traffic whitelisting gateway\n\n**Not affiliated with the Tor Project.**\n\n\nThere are several transparently torifying gateways. They suffer from the same problems:\n\n- It's tricky to isolate circuits and issue NEWNYM signals, especially if multiple client computers are involved.\n- Any garbage software can pump identifiers into \"anonymous\" circuits, and get itself exploited by malicious exit nodes.\n- Trust is centralized to the gateway, which is bad enough when used by one person, and just inappropriate when shared with strangers.\n\n**corridor takes a different approach. It allows only connections to Tor relays to pass through (no clearnet leaks!), but client computers are themselves responsible for torifying their own traffic.** In other words, it is a filtering gateway, not a proxying gateway.\n\nYou can think of it as a fail-safe for your vanilla Tor Browser or Tails, for your beautiful scary experimental Qubes proxying schemes, etc. Or invite the hood to use your WiFi without getting into trouble.\n\n\n## Principle of operation\n\n1. The corridor-data script opens a Tor control connection and subscribes to NEWCONSENSUS events (announcements listing all public relays), unless you inform it of any bridges to use instead.\n2. That data is used to atomically update a Linux ipset (a list of IP-address:TCP-port entries accessible in constant time) named corridor_relays containing either all your bridges or all *acceptable* relays along with their ORPort. Acceptable means the relays have a Valid flag and a Guard or Authority flag.\n3. iptables rules refuse to forward packets unless they are going to / coming from one of the relays inside the ipset.\n\n\n## Pitfalls\n\n- **To be safe, corridor needs two separate network interfaces**, like two Ethernet NICs, or one WiFi radio and one DSL modem. One is to receive incoming traffic from client computers, the other one is to pass the filtered traffic towards the global internet, **and they need to be on different network address spaces**: Clients must not be able to take a shortcut via DHCP, DNS, ICMP Redirect requests, and who knows what else.\n\n- corridor cannot prevent **malware** on a client computer from **finding out your clearnet IP address**, e.g. by sending the `GETINFO address` command to any Tor control port on the network (incl. the one on the client computer itself). **corridor is not a replacement for using a well-designed operating system on your client computers**, like Qubes with TorVM/Whonix.\n\n- The optional **logging of prevented leaks has several limitations**:\n\t- Consider the role of DNS:\n\t\t- If leaky client software tries connecting to a server by its IP address, you see that in the log.\n\t\t- If it tries resolving a hostname through a hardcoded DNS server, you see a *failed connection to that DNS server* in the log.\n\t\t- If it tries resolving a hostname but the client system does not know any DNS server, *there is no connection* that could be logged.\n\t- Clients can spoof their source IP address.\n\t- The kernel shows MAC addresses in the log lines, maybe you don't want that.\n\n- You **probably should not use corridor in combination with other iptables-based firewalls** (like ufw): They can easily clobber some or all of corridor's rules. At the very least, start corridor-init-forwarding and corridor-init-snat *after* your other firewall, e.g. using systemd orderings.\n\n## Installation\n\n*You may also be interested in Patrick Schleizer's [corridor Debian package](https://github.com/adrelanos/corridor), or the [corridor page in the Whonix wiki](https://www.whonix.org/wiki/Corridor)*\n\n```\n# Install corridor and its systemd units to the default location in /usr/local.\nmake install install-systemd\n\n# Edit the configuration.\n$EDITOR /etc/corridor.d/*\n```\n\n\n## Manual usage\n\n```\n# Set up IP traffic forwarding.\ncorridor-init-forwarding\n\n# Set up Source NAT with iptables.\ncorridor-init-snat\n\n# Keep track of acceptable Tor relays.\ncorridor-data \u0026\n\n# Log attempted leaks from selected clients.\n# This command will block until corridor_relays gets populated!\ncorridor-init-logged\n```\n\n\n## systemd\n\n```\n# If you use something other than systemd-networkd to bring up your\n# network interfaces (make sure that whatever it is correctly orders\n# itself after network-pre.target!), you must add a dependency:\nmkdir /etc/systemd/system/some.service.d\ncat  \u003e/etc/systemd/system/some.service.d/corridor.conf \u003c\u003cEND\n[Unit]\nRequires=corridor-init-forwarding.service\nEND\n\n# Start corridor\nsystemctl start corridor.target\n\n# Start corridor when booting\nsystemctl enable corridor.target\n```\n\n\n## Qubes\n\n**This has barely even been tested, be careful!**\n\n```\n# In your template:\ndnf install tor ipset socat perl make  # or apt-get ...\nmake PREFIX=/usr install install-systemd install-qubes\nsystemctl enable corridor.target\n\n# In dom0:\nqvm-create --prop provides_network=True --template your-template --label blue corridor-gateway\nqvm-service --enable corridor-gateway corridor\n```\n\n\n## How does corridor-data open a Tor control connection?\n\nIf $TOR_CONTROL_SOCKET is nonempty, use it.\nOtherwise, connect to $TOR_CONTROL_HOST (localhost if unset) on $TOR_CONTROL_PORT (9051 if unset).\n\nIf $TOR_CONTROL_COOKIE_AUTH_FILE is nonempty, use it.\nOtherwise, pass $TOR_CONTROL_PASSWD.\n\nThe default configuration file sets $TOR_CONTROL_SOCKET to /var/run/tor/control, and $TOR_CONTROL_COOKIE_AUTH_FILE to /var/run/tor/control.authcookie. These values work on Debian and Fedora.\n\n\n## Dependencies so far\n\n- ipset, iptables, sysctl\n- socat (to open control connections)\n- sh, make, grep, sed, sleep, sort, test, echo\n- perl (to convert control cookies to hex, easily replaceable)\n- Linux kernel:\n\t- CONFIG_IP_SET_HASH_IPPORT\n\t- CONFIG_IP_SET_HASH_NET\n\t- CONFIG_IP_NF_TARGET_MASQUERADE\n\t- CONFIG_IP_NF_TARGET_REJECT\n\t- CONFIG_NETFILTER_XT_TARGET_LOG\n\t- CONFIG_NF_CONNTRACK_IPV4\n\n\n## Todo\n\n- Configure dnsmasq as a logging (but non-forwarding) DNS server\n- Build a WiFi/Ethernet portal that allows people to download Tor Browser:\n\t- Configure hostapd as an open AP\n\t- Configure dnsmasq\n\t\t- as a DHCP server\n\t\t- as a DNS proxy restricted to\n\t\t\t- torproject.org\n\t\t\t- maybe also guardianproject.info\n\t\t\t- maybe also tails.boum.org if they start to offer https for their ISOs\n\t- Transparently torify connections to only those domains' IP addresses on port 443\n\t- Configure publicfile to serve an info page linking to https://www.torproject.org\n\t- MITM all requests to port 80 into a HTTP 302 redirect to that info page\n- OpenWRT support\n\n\n## Version numbers\n\n[Semantic Versioning](http://semver.org/) is used in the form of signed git tags.\n\n\n## Redistribution\n\ncorridor is permissively licensed, see the LICENSE-ISC file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frustybird%2Fcorridor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frustybird%2Fcorridor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frustybird%2Fcorridor/lists"}