{"id":16776378,"url":"https://github.com/ameshkov/sniproxy","last_synced_at":"2025-07-14T05:36:08.882Z","repository":{"id":151007790,"uuid":"612989521","full_name":"ameshkov/sniproxy","owner":"ameshkov","description":"SNI proxy with embedded DNS server that supports blocking and forwarding rules.","archived":false,"fork":false,"pushed_at":"2023-10-02T13:37:03.000Z","size":101,"stargazers_count":78,"open_issues_count":4,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-04T02:01:29.564Z","etag":null,"topics":["dns-server","golang","proxy","sniproxy"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ameshkov.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}},"created_at":"2023-03-12T15:23:59.000Z","updated_at":"2025-03-28T02:33:34.000Z","dependencies_parsed_at":"2024-10-28T11:46:44.043Z","dependency_job_id":"fc4831ae-f791-4618-95fe-f088ce4e5f02","html_url":"https://github.com/ameshkov/sniproxy","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/ameshkov/sniproxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameshkov%2Fsniproxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameshkov%2Fsniproxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameshkov%2Fsniproxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameshkov%2Fsniproxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ameshkov","download_url":"https://codeload.github.com/ameshkov/sniproxy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameshkov%2Fsniproxy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265246068,"owners_count":23734109,"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":["dns-server","golang","proxy","sniproxy"],"created_at":"2024-10-13T07:09:46.914Z","updated_at":"2025-07-14T05:36:08.859Z","avatar_url":"https://github.com/ameshkov.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sniproxy\n\nProxies incoming HTTP and TLS connections based on the hostname that is parsed\nfrom either HTTP Host header (for plain HTTP connections) or TLS ClientHello.\n\nThis allows transparent proxying of the network traffic by simply rerouting\nconnections to the `sniproxy`. There are many ways to re-route traffic, but most\noften it is done either on the DNS level or by using `iptables`.\n\n## Features\n\n* Embedded DNS server that can be used to redirect traffic to the proxy.\n* Supports both TLS and plain HTTP.\n* Supports forwarding connections to an upstream SOCKS proxy.\n* Flexible rules for redirecting, forwarding, blocking or throttling\n  connections.\n* Cross-platform and simple.\n\n## How to install\n\n* Using homebrew:\n    ```\n    brew install ameshkov/tap/sniproxy\n    ```\n* From source:\n    ```\n    go install github.com/ameshkov/sniproxy\n    ```\n* You can get a binary for your platform from\n  the [releases page](https://github.com/ameshkov/sniproxy/releases).\n\n## Using `sniproxy`\n\n### Redirect all traffic to a SNI proxy\n\n* Run `sniproxy` and rewrite DNS responses to point to `1.2.3.4`:\n  ```shell\n  sudo sniproxy --dns-redirect-ipv4-to=1.2.3.4\n  ```\n* You can test locally it with the following commands:\n  ```shell\n  curl \"https://example.org/\" --dns-servers 127.0.0.1\n  curl \"http://example.org/\" --dns-servers 127.0.0.1\n  ```\n\n  Not every curl version supports `--dns-servers`. Alternatively, use these\n  commands:\n  ```shell\n  curl \"https://example.org/\" --connect-to example.org:443:127.0.0.1:443\n  curl \"http://example.org/\" --connect-to example.org:80:127.0.0.1:80\n  ```\n\n* Now you should just point your device to the DNS server that is running on\n  your computer.\n\n### Forward all traffic to a proxy\n\nRun `sniproxy`, rewrite DNS responses to point to `1.2.3.4`, :\n\n```shell\nsudo sniproxy \\\n    --dns-redirect-ipv4-to=1.2.3.4 \\\n    --forward-proxy=\"socks5://127.0.0.1:1080\"\n```\n\nNow every connection will be re-routed to the SOCKS5 proxy on `127.0.0.1:1080`.\n\nYou can choose which domains are re-routed. For instance, here only `example.\norg` and `example.com` will be re-routed through the SOCKS5 proxy:\n\n```shell\nsudo sniproxy \\\n    --dns-redirect-ipv4-to=1.2.3.4 \\\n    --forward-proxy=\"socks5://127.0.0.1:1080\" \\\n    --forward-rule=example.org \\\n    --forward-rule=example.com\n```\n\nIt also supports HTTP and HTTPS proxies. Here's an example:\n```shell\nsudo sniproxy \\\n    --dns-redirect-ipv4-to=1.2.3.4 \\\n    --forward-proxy=\"http://127.0.0.1:8080\" \\\n    --forward-rule=example.org \\\n    --forward-rule=example.com\n```\n\n### Block domains\n\nYou may want to block access to some domains.  There are two options of how it\ncan be done: `--block-rule` or `--drop-rule`.  If the connection matches a\n`--block-rule`, the connection will be closed immediately.  If the connection\nmatches a `--drop-rule`, the connection will \"hang\" for a hard-coded limit of\n3 minutes before it will be closed.\n\nHere's how block or drop connections to domains:\n\n```shell\nsudo sniproxy \\\n    --dns-redirect-ipv4-to=1.2.3.4 \\\n    --block-rule=example.org \\\n    --block-rule=example.com \\\n    --drop-rule=example.net\n```\n\n### Drop DNS queries\n\nYou may want to emulate the situation when DNS queries to specific domains are\ndropped.  Use `--dns-drop-rule` option to do this:\n\n```shell\nsudo sniproxy \\\n    --dns-redirect-ipv4-to=1.2.3.4 \\\n    --dns-drop-rule=example.net \\\n    --dns-drop-rule=example.com\n```\n\n### Throttle connections\n\nIf you need to emulate slow network, use `bandwidth-rate` to set the desired\nbytes-per-sec rate.\n\n```shell\nsudo sniproxy \\\n    --dns-redirect-ipv4-to=1.2.3.4 \\\n    --bandwidth-rate=1000\n```\n\nYou can also throttle connections to individual domains using `bandwidth-rule`.\n\n```shell\nsudo sniproxy \\\n    --dns-redirect-ipv4-to=1.2.3.4 \\\n    --bandwidth-rule=\"example.*:5000\"\n```\n\n### Command-line arguments\n\n```shell\nUsage:\n  sniproxy [OPTIONS]\n\nApplication Options:\n      --dns-address=          IP address that the DNS proxy server will be listening to. (default: 0.0.0.0)\n      --dns-port=             Port the DNS proxy server will be listening to. (default: 53)\n      --dns-upstream=         The address of the DNS server the proxy will forward queries that are not\n                              rewritten by sniproxy. (default: 8.8.8.8)\n      --dns-redirect-ipv4-to= IPv4 address that will be used for redirecting type A DNS queries.\n      --dns-redirect-ipv6-to= IPv6 address that will be used for redirecting type AAAA DNS queries.\n      --dns-redirect-rule=    Wildcard that defines which domains should be redirected to the SNI proxy. Can\n                              be specified multiple times. (default: *)\n      --dns-drop-rule=        Wildcard that defines DNS queries to which domains should be dropped. Can be\n                              specified multiple times.\n      --http-address=         IP address the SNI proxy server will be listening for plain HTTP connections.\n                              (default: 0.0.0.0)\n      --http-port=            Port the SNI proxy server will be listening for plain HTTP connections.\n                              (default: 80)\n      --tls-address=          IP address the SNI proxy server will be listening for TLS connections.\n                              (default: 0.0.0.0)\n      --tls-port=             Port the SNI proxy server will be listening for TLS connections. (default: 443)\n      --bandwidth-rate=       Bytes per second the connections speed will be limited to. If not set, there\n                              is no limit. (default: 0)\n      --bandwidth-rule=       Allows to define connection speed in bytes/sec for domains that match the\n                              wildcard. Example: example.*:1024. Can be specified multiple times.\n      --forward-proxy=        Address of a SOCKS/HTTP/HTTPS proxy that the connections will be forwarded to\n                              according to forward-rule.\n      --forward-rule=         Wildcard that defines what connections will be forwarded to forward-proxy. Can\n                              be specified multiple times. If no rules are specified, all connections will\n                              be forwarded to the proxy.\n      --block-rule=           Wildcard that defines connections to which domains should be blocked. Can be\n                              specified multiple times.\n      --drop-rule=            Wildcard that defines connections to which domains should be dropped (i.e.\n                              delayed for a hard-coded period of 3 minutes. Can be specified multiple times.\n      --verbose               Verbose output (optional)\n      --output=               Path to the log file. If not set, write to stdout.\n\nHelp Options:\n  -h, --help                  Show this help message\n```\n\n## Debugging locally\n\nIf you want to contribute to `sniproxy`, here are some tips on how to debug it\nlocally.\n\nFirst, you rarely want to run with `sudo` and instead you'd prefer to use high\nports. `sniproxy` provides command-line arguments for that.\n\n```shell\n./sniproxy \\\n    --dns-address=127.0.0.1 \\\n    --dns-port=5354 \\\n    --dns-upstream=8.8.8.8 \\\n    --dns-redirect-ipv4-to=127.0.0.1 \\\n    --dns-redirect-rule=example.org \\\n    --dns-redirect-rule=example.com \\\n    --tls-address=127.0.0.1 \\\n    --tls-port=8443 \\\n    --http-address=127.0.0.1 \\\n    --http-port=8080 \\\n    --forward-proxy=\"socks5://127.0.0.1:1080\" \\\n    --verbose\n```\n\nIt is easy to use curl to debug `sniproxy`:\n\n```shell\n# HTTPS request\ncurl \"https://example.org/\" --connect-to example.org:443:127.0.0.1:8443\n\n# Plain HTTP request\ncurl \"http://example.org/\" --connect-to example.org:80:127.0.0.1:8080\n\n```\n\nUse `mitmproxy` to debug `sniproxy` with forwarding rules:\n\n```shell\n# Run mitmproxy in SOCKS mode\nmitmweb --mode=socks5\n\n# Forward connections to mitmproxy\n./sniproxy \\\n    --dns-address=127.0.0.1 \\\n    --dns-port=5354 \\\n    --dns-upstream=8.8.8.8 \\\n    --dns-redirect-ipv4-to=127.0.0.1 \\\n    --dns-redirect-rule=example.org \\\n    --dns-redirect-rule=example.com \\\n    --tls-address=127.0.0.1 \\\n    --tls-port=8443 \\\n    --http-address=127.0.0.1 \\\n    --http-port=8080 \\\n    --forward-proxy=\"socks5://127.0.0.1:1080\" \\\n    --verbose\n\n# Check that the connections were properly forwarded\ncurl \"https://example.org/\" --connect-to example.org:443:127.0.0.1:8443 --insecure\ncurl \"http://example.org/\" --connect-to example.org:80:127.0.0.1:8080\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fameshkov%2Fsniproxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fameshkov%2Fsniproxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fameshkov%2Fsniproxy/lists"}