{"id":13549695,"url":"https://github.com/facebookarchive/doh-proxy","last_synced_at":"2025-04-02T23:30:51.925Z","repository":{"id":53571894,"uuid":"116992110","full_name":"facebookarchive/doh-proxy","owner":"facebookarchive","description":"A proof of concept DNS-Over-HTTPS proxy implementing https://datatracker.ietf.org/doc/draft-ietf-doh-dns-over-https/","archived":true,"fork":false,"pushed_at":"2021-05-25T01:26:15.000Z","size":196,"stargazers_count":463,"open_issues_count":0,"forks_count":77,"subscribers_count":32,"default_branch":"master","last_synced_at":"2024-11-03T19:36:54.072Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://facebookexperimental.github.io/doh-proxy/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/facebookarchive.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-10T17:58:01.000Z","updated_at":"2024-08-15T05:04:34.000Z","dependencies_parsed_at":"2022-09-07T04:51:51.542Z","dependency_job_id":null,"html_url":"https://github.com/facebookarchive/doh-proxy","commit_stats":null,"previous_names":["facebookexperimental/doh-proxy"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookarchive%2Fdoh-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookarchive%2Fdoh-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookarchive%2Fdoh-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookarchive%2Fdoh-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/facebookarchive","download_url":"https://codeload.github.com/facebookarchive/doh-proxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246910850,"owners_count":20853651,"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":[],"created_at":"2024-08-01T12:01:24.528Z","updated_at":"2025-04-02T23:30:51.003Z","avatar_url":"https://github.com/facebookarchive.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# DNS Over HTTPS Proxy\n\n![Test Code Base](https://github.com/facebookexperimental/doh-proxy/workflows/Test%20Code%20Base/badge.svg)\n[![GitHub Super-Linter](https://github.com/facebookexperimental/doh-proxy/workflows/Lint%20Code%20Base/badge.svg)](https://github.com/marketplace/actions/super-linter)\n[![PyPI version](https://badge.fury.io/py/doh-proxy.svg)](https://badge.fury.io/py/doh-proxy)\n\nA set of python 3 scripts that supports proxying DNS over HTTPS as specified\nin the [IETF Draft draft-ietf-doh-dns-over-https](https://tools.ietf.org/html/draft-ietf-doh-dns-over-https-13).\n\nDOH provides a way to run encrypted DNS over HTTPS, a protocol which can freely\ntraverse firewalls when other encrypted mechanism may be blocked.\n\nThe project comes with a set of 4 tools:\n\n* [doh-proxy](#doh-proxy): A service that receives DOH queries over HTTP2 and forwards them\nto a recursive resolver.\n* [doh-httpproxy](#doh-httpproxy): Like `doh-proxy` but uses HTTP instead of HTTP2.\nThe main intent is to run this behind a reverse proxy.\n* [doh-stub](#doh-stub): A service that listens for DNS queries and forwards them to a DOH server.\n* [doh-client](#doh-client): A tool to perform a test DNS query against DOH server.\n\nSee the `CONTRIBUTING` file for how to help out.\n\nDOH Proxy was created during [IETF Hackathon 100](https://www.ietf.org/how/runningcode/hackathons/100-hackathon/) as a proof-of-concept and is not used at Facebook.\n\nYou are welcome to use it, but be aware that support is limited and best-effort.\n\n## Installing\n\nTo install an already packaged version directly from PyPi:\n\n```shell\n$ pip3 install doh-proxy\n```\n\n## Usage\n\n### doh-proxy\n\n`doh-proxy` is a stand alone server answering DOH request. The proxy does not do\nDNS recursion itself and rather forward the query to a full-featured DNS\nrecursive server or DNS caching server.\n\nBy running `doh-proxy`, you can get and end-to-end DOH solution with minimal\nsetup.\n\n```shell\n$ sudo doh-proxy \\\n    --upstream-resolver=::1 \\\n    --certfile=./fullchain.pem \\\n    --keyfile=./privkey.pem\n```\n\n### doh-httpproxy\n\n`doh-httpproxy` is designed to be running behind a reverse proxy. In this setup\na reverse proxy such as [NGINX](https://nginx.org/) would be handling the\nHTTPS/HTTP2 requests from the DOH clients and will forward them to\n`doh-httpproxy` backends.\n\nWhile this setup requires more upfront setup, it allows running DOH proxy\nunprivileged and on multiple cores.\n\n\n```shell\n$ doh-httpproxy \\\n    --upstream-resolver=::1 \\\n    --port 8080 \\\n    --listen-address ::1\n```\n\n`doh-httpproxy` now also supports TLS, that you can enable passing the \nargs `--certfile` and `--keyfile` (just like `doh-proxy`)\n\n### doh-stub\n\n`doh-stub` is the piece of software that you would run on the clients. By\nproviding a local DNS server, `doh-stub` will forward the DNS requests it\nreceives to a DOH server using an encrypted link.\n\nYou can start a stub resolver with:\n\n```shell\n$ doh-stub \\\n    --listen-port 5553 \\\n    --listen-address ::1 \\\n    --domain foo.bar \\\n    --remote-address ::1\n```\n\nand query it.\n\n```shell\n$ dig @::1 -p 5553 example.com\n```\n\n### doh-client\n\n`doh-client` is just a test cli that can be used to quickly send a request to\na DOH server and dump the returned answer.\n\n```shell\n$ doh-client  \\\n    --domain dns.dnsoverhttps.net \\\n    --qname sigfail.verteiltesysteme.net \\\n    --dnssec\nid 37762\nopcode QUERY\nrcode SERVFAIL\nflags QR RD RA\nedns 0\neflags DO\npayload 4096\n;QUESTION\nsigfail.verteiltesysteme.net. IN AAAA\n;ANSWER\n;AUTHORITY\n;ADDITIONAL\n\n$ doh-client  \\\n    --domain dns.dnsoverhttps.net \\\n    --qname sigok.verteiltesysteme.net \\\n    --dnssec\nid 49772\nopcode QUERY\nrcode NOERROR\nflags QR RD RA AD\nedns 0\neflags DO\npayload 4096\n;QUESTION\nsigok.verteiltesysteme.net. IN AAAA\n;ANSWER\nsigok.verteiltesysteme.net. 60 IN AAAA 2001:638:501:8efc::139\nsigok.verteiltesysteme.net. 60 IN RRSIG AAAA 5 3 60 20180130030002 20171031030002 30665 verteiltesysteme.net. O7QgNZFBu3fULvBXwM39apv5nMehh51f mLOVEsC8qZUyxIbxo4eDLQt0JvPoPpFH 5TbWdlm/jxq5x2/Kjw7yUdpohhiNmdoD Op7Y+RyHbf676FoC5Zko9uOAB7Pp8ERz qiT0QPt1ec12bM0XKQigfp+2Hy9wUuSN QmAzXS2s75k=\n;AUTHORITY\n;ADDITIONAL\n```\n\n## Development\n\n\n### Requirements\n\n* python \u003e= 3.5\n* aiohttp\n* aioh2\n* dnspython\n\n### Building\n\nDOH Proxy uses Python'setuptools to manage dependencies and build.\n\nTo install its dependencies:\n\n```shell\n$ python3 setup.py develop\n# Due to GH #63\n$ pip install git+https://github.com/URenko/aioh2#egg=aioh2\n```\n\nTo build:\n```shell\n$ python3 setup.py build\n```\n\nTo run unittests:\n```shell\n$ python3 setup.py test\n```\n\nTo run the linter:\n\nDOH Proxy uses GitHub Action [Super-Linter](https://github.com/marketplace/actions/super-linter) to lint the code. In order to validate your code locally, it is possible to run Super-Linter locally using the following comand line from within the repository:\n\n```shell\ndocker run -e RUN_LOCAL=true  -e VALIDATE_PYTHON_PYLINT=false \\\n    -e FILTER_REGX_INCLUDE='(dohproxy|test)/.*.py' \\\n    -v $(pwd):/tmp/lint \\\n     --rm github/super-linter:v3\n```\n\nFrom within the root of the repository, you can test the proxy, stub and client respectively\nby using the following commands:\n\n```shell\n$ sudo PYTHONPATH=. ./dohproxy/proxy.py ...\n```\n\n```shell\n$ PYTHONPATH=. ./dohproxy/httpproxy.py ...\n```\n\n\n```shell\n$ PYTHONPATH=. ./dohproxy/stub.py ...\n```\n\n```shell\n$ PYTHONPATH=. ./dohproxy/client.py ...\n```\n\n## License\nDOH Proxy is BSD-licensed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebookarchive%2Fdoh-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffacebookarchive%2Fdoh-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebookarchive%2Fdoh-proxy/lists"}