{"id":51298843,"url":"https://github.com/naseridev/cortado","last_synced_at":"2026-06-30T17:02:34.275Z","repository":{"id":366118705,"uuid":"1274463160","full_name":"naseridev/cortado","owner":"naseridev","description":"TUN-to-SOCKS5 tunnel for Linux, macOS, and Windows.","archived":false,"fork":false,"pushed_at":"2026-06-20T09:47:07.000Z","size":95,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T11:22:20.304Z","etag":null,"topics":["proxy","rust","tun","tun2socks"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/naseridev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-19T14:38:25.000Z","updated_at":"2026-06-20T10:27:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/naseridev/cortado","commit_stats":null,"previous_names":["naseridev/cortado"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/naseridev/cortado","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naseridev%2Fcortado","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naseridev%2Fcortado/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naseridev%2Fcortado/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naseridev%2Fcortado/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/naseridev","download_url":"https://codeload.github.com/naseridev/cortado/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naseridev%2Fcortado/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34975672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["proxy","rust","tun","tun2socks"],"created_at":"2026-06-30T17:02:33.816Z","updated_at":"2026-06-30T17:02:34.268Z","avatar_url":"https://github.com/naseridev.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cortado\nA TUN-to-SOCKS5 tunnel for Linux, macOS, and Windows. Routes all system traffic through a userspace network stack and relays it to an upstream SOCKS5 proxy, with no manual tuning required.\n\n## Installation\n\n```sh\ncargo build --release\nsudo install -m 0755 target/release/cortado /usr/local/bin/cortado\n```\n\n## Usage\n\nCortado mutates global system state (routes and DNS) and `run` must be invoked as root.\n\n### Init\n\nInitialize or reset the default configuration:\n\n```sh\ncortado init\n```\n\nWrites the configuration file to `/etc/cortado/cortado.conf` when run as root, or `~/.config/cortado/cortado.conf` otherwise. Always writes a complete default, so it doubles as a reset.\n\n### Run\n\nStart the tunnel:\n\n```sh\nsudo cortado run\n```\n\nThe tunnel runs in the foreground. `Ctrl-C` or `SIGTERM` triggers a graceful teardown that restores the routing table and `/etc/resolv.conf`. Sending `SIGHUP` reloads proxy and bypass-route settings without restarting.\n\n## Technical Implementation\n\n### Architecture\n\nCortado creates a TUN interface and rewrites the system routing table to funnel all IPv4 (and optionally IPv6) traffic through it. A userspace TCP/UDP stack terminates the captured flows and relays each connection through the upstream SOCKS5 proxy:\n\n- TCP relayed via SOCKS5 CONNECT\n- UDP relayed via RFC 1928 UDP ASSOCIATE\n- DNS relayed over TCP framing, so name resolution works even against proxies that do not support UDP\n\nPer-connection memory is bounded by decoupling the relay copy buffer from the socket window. Concurrency is gated by caps derived from what the host can actually sustain.\n\n### Automatic Tuning\n\nAt startup, Cortado probes live system state and derives all values governing throughput and stability:\n\n- MTU is read from the egress interface of the default route\n- Socket windows, stack queue depth, and per-connection copy buffer are derived from the detected MTU and total system memory\n- Connection and UDP-session caps are derived from `RLIMIT_NOFILE` (raised to its hard limit) and available memory\n- IPv6 capture activates only when a default IPv6 gateway is present\n\nThe computed values are logged once at startup (`auto-tuned: mtu=… relay_buf=… max_tcp=… capture_ipv6=…`).\n\n### Configuration Reload\n\nSending `SIGHUP` applies proxy and bypass-route changes without dropping the tunnel. Fields that require a full restart are reported and left unchanged. Configuration files containing legacy tuning keys (`mtu`, `relay_buf_size`, `max_tcp_connections`, …) remain valid: those keys are now ignored in favour of automatic tuning.\n\n### Recovery\n\nA hard kill (`SIGKILL`) skips teardown and can leave the system with split routes and a modified `/etc/resolv.conf`. To recover:\n\n```sh\nsudo cp /etc/resolv.conf.cortado.bak /etc/resolv.conf\nsudo ip route del 0.0.0.0/1\nsudo ip route del 128.0.0.0/1\n```\n\n## Configuration\n\nCortado reads `cortado.conf` (TOML) from the first location that exists:\n\n1. `/etc/cortado/cortado.conf` (system-wide)\n2. `$XDG_CONFIG_HOME/cortado/cortado.conf`, falling back to `~/.config/cortado/cortado.conf` (per-user)\n\n| Key                   | Default          | Description                                        |\n| --------------------- | ---------------- | -------------------------------------------------- |\n| `proxy_addr`          | `127.0.0.1:1080` | Upstream SOCKS5 proxy (`ip:port`)                  |\n| `username`/`password` | unset            | SOCKS5 credentials; set both or neither            |\n| `tun_name`            | `cortado0`       | TUN interface name                                 |\n| `tun_ip`              | `10.0.0.1`       | TUN interface address                              |\n| `dns_server`          | `1.1.1.1`        | DNS server written to `/etc/resolv.conf`           |\n| `override_dns`        | `true`           | Whether to rewrite `/etc/resolv.conf`              |\n| `dns_over_tcp`        | `true`           | Relay DNS over TCP framing                         |\n| `bypass_cidrs`        | `[]`             | CIDRs routed directly, bypassing the proxy         |\n| `metrics_addr`        | unset            | Address to serve Prometheus metrics on             |\n\n## Limitations\n\n### Platform Support\n\n- Linux: Fully supported and tested: TUN device (`tokio-tun`), routing and MTU detection (netlink), and DNS handling (`/etc/resolv.conf`) are all implemented\n- macOS (utun) and Windows (Wintun): Platform seams exist and compile, but backends are not yet complete or runtime-tested; treat as in-progress\n\n### Security Considerations\n\n- SOCKS5 credentials are stored in plaintext in the configuration file\n- No traffic encryption beyond what the upstream proxy provides\n- LSB steganography is detectable through statistical analysis\n- Password-based SOCKS5 authentication is vulnerable to weak passwords\n\n## Comparison with tun2socks\n\nCortado is a tun2socks-class forwarding engine. The packet forwarding problem is solved by existing tools: `badvpn-tun2socks` and the Go [`tun2socks`](https://github.com/xjasonlyu/tun2socks) among them. What Cortado changes is everything around the forwarding loop.\n\n### Approach\n\n- tun2socks: Forwards packets; routing, DNS, and teardown are the user's responsibility to script\n- Cortado: Owns the system state it touches: installs routes and DNS override itself, restores both on exit, reloads on `SIGHUP`\n\n### Medium\n\n- tun2socks: Statically configured via flags or compile-time constants; values are fixed for the life of the process\n- Cortado: All throughput parameters auto-derived from live system state at startup; no tuning flags\n\n### Advantages over tun2socks\n\n- No tuning knobs: MTU, buffer sizes, and connection caps are computed automatically: no trial-and-error for different link conditions\n- System state management: Routes and DNS are installed and restored automatically; a crash is recoverable with two commands\n- UDP and DNS out of the box: Full RFC 1928 UDP ASSOCIATE plus DNS-over-TCP framing; no `badvpn-udpgw` side helper needed\n- Observability: Prometheus metrics endpoint and structured leveled logs; throughput, active connections, and error counts are visible\n- Memory bounded under load: Per-connection memory is capped; concurrency is gated to what the host can actually sustain\n\n### Trade-offs\n\n- Maturity: tun2socks has a longer track record on production systems\n- Platform coverage: macOS and Windows support is in-progress vs tun2socks being cross-platform today\n- Simplicity: Cortado's automatic system management is an implicit contract: it touches routes and DNS that users may want to control manually\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaseridev%2Fcortado","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnaseridev%2Fcortado","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaseridev%2Fcortado/lists"}