{"id":13564012,"url":"https://github.com/markdingo/trustydns","last_synced_at":"2026-01-16T15:11:36.889Z","repository":{"id":57484842,"uuid":"194191641","full_name":"markdingo/trustydns","owner":"markdingo","description":"DNS Over HTTPS proxy, server and query programs","archived":false,"fork":false,"pushed_at":"2025-11-20T12:10:16.000Z","size":228,"stargazers_count":24,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-20T14:17:03.178Z","etag":null,"topics":["dns","dns-over-https","doh-server","go","golang","golang-application","rfc-8484","split-dns","unix-daemon","windows-server"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markdingo.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","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":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-06-28T02:19:07.000Z","updated_at":"2025-11-20T12:10:19.000Z","dependencies_parsed_at":"2022-08-26T11:10:52.166Z","dependency_job_id":"fa170ece-097b-4f8f-8cb2-3ebb7dadca61","html_url":"https://github.com/markdingo/trustydns","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/markdingo/trustydns","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markdingo%2Ftrustydns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markdingo%2Ftrustydns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markdingo%2Ftrustydns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markdingo%2Ftrustydns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markdingo","download_url":"https://codeload.github.com/markdingo/trustydns/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markdingo%2Ftrustydns/sbom","scorecard":{"id":619849,"data":{"date":"2025-08-11","repo":{"name":"github.com/markdingo/trustydns","commit":"766fc0e6b83bb8aaa9cf4035e3f26fc1d5141c59"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":0,"reason":"Found 0/20 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: BSD 2-Clause \"Simplified\" License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 10 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-21T04:56:38.009Z","repository_id":57484842,"created_at":"2025-08-21T04:56:38.009Z","updated_at":"2025-08-21T04:56:38.009Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["dns","dns-over-https","doh-server","go","golang","golang-application","rfc-8484","split-dns","unix-daemon","windows-server"],"created_at":"2024-08-01T13:01:25.538Z","updated_at":"2026-01-16T15:11:36.880Z","avatar_url":"https://github.com/markdingo.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"## DNS Over HTTPS proxy, server and query programs\n\nTrustydns is a DNS Over HTTPS (DoH) package written in Go. The proxy and server programs can be\ncombined to create a completely independent DoH eco-system or they can be mixed and matched\nwith other DoH components. Trustydns is intended to comply with RFC8484 but has additional\nnon-standard features which can be optionally enabled.\n\n\n[![Build Status](https://travis-ci.org/markdingo/trustydns.svg?branch=master)](https://travis-ci.org/markdingo/trustydns)\n[![Go Report Card](https://goreportcard.com/badge/github.com/markdingo/trustydns)](https://goreportcard.com/report/github.com/markdingo/trustydns)\n[![codecov](https://codecov.io/gh/markdingo/trustydns/branch/master/graph/badge.svg)](https://codecov.io/gh/markdingo/trustydns)\n\n### Programs\n\nThe `trustydns-proxy` daemon accepts regular DNS queries and forwards them to a DoH server over\nHTTPS. Typically `trustydns-proxy` is installed on your home or office gateway and replaces your\nlocal resolver. It could also be installed on your portable devices if you roam on to untrusted\nnetworks. The `trustydns-server` daemon accepts DoH queries and forwards them to a local\nresolver. It is normally installed on a remote, trusted system which has access to a trusted\nresolver. Finally, the `trustydns-dig` command-line utility issues DoH queries and can be used to\ntest DoH servers.\n\n### Anticipated deployment\n\nWhile these programs can be mixed and matched with existing DoH infrastructure such as those\nprovided by Quad9 and Mozilla, the intent is to let you create your own DoH eco-system independent\nof all external parties. In particular, the programs have been written in Go expressly so they can\nbe easily cross-compiled for targets such as home routers which do not normally provide a\ndevelopment environment. Sample cross-compile targets can be found in the [Makefile](./Makefile).\n\nTrustydns supports both server-side and client-side TLS certificates so you can set up a completely\nclosed system whereby only appropriately credentialed proxies and servers can exchange DoH queries\nwith each other.\n\nAdditional deployment features which may be of interest include:\n\n * Split-horizon DNS settings to ensure local domain queries stay local\n * EDNS Client Subnet (RFC7871) controls for masking, substitution and synthesis\n * Support for alternate root CAs to enable private certificates\n * Proxy support for a pool of DoH servers so no single point of failure\n\n### Caveats\n\nTrustydns is new and has some rough edges to it and the compilation and installation process is\nsimplistic at best, so bug reports, suggestions and feedback are more than welcome.\n\nThis package is targeted at DNS administrators with a modicum of Unix sysadmin experience. You need\nnot be an expert to deploy trustydns but there are many different ways a DoH installation can be\nconstructed such that this document can at best offer general guidance and hints.\n\nSome features have been deferred prior to gaining more real-world deployment experience to assess\nhow desirable they truly are. These are discussed in the [TODO](docs/TODO.md) document.\n\nThe alternate root CA support is definitely \"primordial\". Let's see how useful it is before making\ntoo much of a meal out of it. It may turn out that this feature is more hassle than it's worth in\nwhich case it may be removed in a future release.\n\n### Installation\n\nThis package should compile and run on most Unix-like systems which support go1.23 or higher. All\nprograms have been tested on various CPU architectures with FreeBSD, Linux and macOS. The\n[Makefile](./Makefile) in the root directory is a very simple affair which builds and installs the programs into\n`/usr/local/{sbin|bin}`. Feel free to modify it to suit your environment.\n\nTo fetch, compile and install trustydns, run the following commands:\n\n```sh\ngo get -d -u github.com/markdingo/trustydns     # Ignore the warning about no go programs\n\ncd $GOPATH/src/github.com/markdingo/trustydns\n\nmake clean all             # Compile everything\nsudo make install          # Install programs into /usr/local\n```\n\n### Getting Started\n\nThe proxy and server daemons are designed to be run by a process supervision manager such as\n[daemontools](http://cr.yp.to/daemontools.html), launchd, runit or systemd; how you do this is up to\nyou. Prior to deployment though you can test all the trustydns programs from the command line and\neven do so without needing to obtain a TLS certifcate!  First start the server with:\n\n`/usr/local/sbin/trustydns-server -A 127.0.0.1:8080 --log-all -v`\n\nThe server should start accepting DoH queries over HTTP on port 8080 and resolve those queries via\nthe resolvers in `/etc/resolv.conf`.\n\nUse `trustydns-dig` to send a DoH query to your freshly running server:\n\n`/usr/local/bin/trustydns-dig http://127.0.0.1:8080/dns-query yahoo.com mx`\n\nIf all goes well `trustydns-dig` returns the MX RRs for Yahoo! and you should see some\nlog chatter from the server as it processes the query. The log chatter is mostly of use to\ndevelopers but it's helpful here to demonstrate server activity.\n\nThe final step is to incorporate the proxy into the query flow. Start it with:\n\n`/usr/local/sbin/trustydns-proxy -A 127.0.0.1:6653 -v --log-all http://127.0.0.1:8080/dns-query`\n\nThe proxy should start accepting DNS queries on port 6653 and forward them to your\n`trustydns-server` instance on port 8080. To test the proxy, use your preferred DNS query tool to\nissue a regular query to port 6653, e.g:\n\n`dig -p 6653 @127.0.0.1 yahoo.com mx`\n\nIf all goes *really* well, the DNS query returns the MX RRs for Yahoo! which closely matches your\nprevious `trustydns-dig` query. Both the proxy and the server should chatter away with their logging\noutput showing \"proof of life\".\n\nIf you've got this far, congratulations! You've successfully run all the programs and are now ready\nto deploy.\n\n\n### Server Certificate\n\nAs you no doubt observed in \"Getting Started\", all the programs can use HTTP which expedites the\nlearning exercise and greatly simplifies traffic debugging. However if you plan to run\n`trustydns-server` in production you'll need to acquire a TLS server certificate and invoke\n`trustydns-server` with `--tls-cert` and `--tls-key`.\n\nYou should be able to use any of: an official paid-for certificate generated by a commercial CA,\n\"free\" certificates from https://letsencrypt.org or a self-signed certificate generated by a tool\nsuch as `openssl`. For reference, the author runs `trustydns-server` with a \"Let's Encrypt\"\ncertificated generated with [certbot](https://certbot.eff.org). For those that want to take the self-signed\nroute there are a few scripts in the [openssl](./openssl) directory which might help.\n\nIf you plan to run a \"proxy only\" deployment which relies on existing DoH Servers you will of course\nnot need a Server Certificate.\n\n### Deployments Scenarios\n\n#### A Proxy-only Deployment\n\nOne possible deployment scenario is to use `trustydns-proxy` on your local network and direct its\nDoH queries to public DoH servers such as those run by Mozilla, Quad9 and Google. To do this invoke\nthe proxy as follows:\n\n```sh\n/usr/local/sbin/trustydns-proxy -v https://mozilla.cloudflare-dns.com/dns-query \\\n                                   https://dns.quad9.net/dns-query \\\n                                   https://dns.google/dns-query\n```\n\nThe proxy accepts DNS queries on port 53 and forward them to one of the servers on the command line\ndepending on which is offering reliable responses with the lowest latency. `trustydns-proxy`\nopportunistically forwards queries to different servers to accumulate latency and reliability data.\n\nThere are many other public DoH servers besides those used in the example above. A fairly\ncomprehensive list along with their attributes can be found on the [Curl\nGitHub](https://github.com/curl/curl/wiki/DNS-over-HTTPS) site.\n\n#### A Proxy deployment with split-DNS\n\nIt's not un-common for a network to have a \"split-DNS\" whereby lookups of your local domain produce\ndifferent results from those seen by the \"outside\" world. This is usually achieved with a special\nlocal resolver configuration.\n\n`trustydns-proxy` supports split-DNS environments with the `-c` and `-e` options. Here is an example\ninvocation:\n\n```sh\n/usr/local/sbin/trustydns-proxy -v -c /etc/resolv.conf \\\n                                   -e example.net -e 168.192.in-addr.arpa \\\n                                   https://mozilla.cloudflare-dns.com/dns-query \\\n                                   https://dns.quad9.net/dns-query \\\n                                   https://dns.google/dns-query\n```\n\nThis invocation causes `trustydns-proxy` to redirect all queries for the search/domains in\n`/etc/resolv.conf` as well as the domains \"example.net\" and \"168.192.in-addr.arpa\" to the resolvers\nspecified in /etc/resolv.conf. All other queries are forwarded to the DoH servers on the command\nline. Redirection to local resolvers also includes all sub-domains of the specified domains.\n\n**WARNING:** Make very sure that the proxy listen address is not included in the nominated\nresolv.conf file otherwise redirected queries will cause an unpleasant query loop.\n\n\n#### Private Proxy and Server Deployment\n\nA private proxy/server deployment is one in which both the proxy and server use privately generated\ncertificates to authorize access to each other. If we assume that you have previously generated a\nrootCA and server and proxy certificates - perhaps with the help of the supplied [openssl\nscripts](./openssl/README.md) - then proxy invocation looks something like:\n\n```sh\n/usr/local/sbin/trustydns-proxy -v --tls-key proxy.key --tls-cert proxy.cert \\\n                                   --tls-other-roots rootCA.cert --tls-use-system-roots=false \\\n                                   --log-tls-errors \\\n                                   https://$yourDoHServer/dns-query\n```\n\nWhile not essential the `--log-tls-errors` option is useful for identifying certificate verification\nfailures.\n\nand server invocation is something like:\n\n```sh\n/usr/local/sbin/trustydns-server -v --tls-key $yourDoHServer.key --tls-cert $yourDoHServer.cert \\\n                                    --tls-other-roots rootCA.cert --tls-use-system-roots=false \\\n                                    --log-tls-errors\n```\n\nSetting `--tls-use-system-roots=false` retricts access solely to certificates generated with your\nroot CA.\n\n\n### Reporting Tools\n\nIn verbose mode (-v) both the server and the proxy produce periodic statistical output which is\nnormally written to log files. There are a number of scripts in the [tools](./tools) directory which\nproduce summary reports from the log file entries. For details see [tools/README](tools/README.md).\n\n\n### Other Documents\n\nThere are various ancilliary documents in the [docs](docs/.) directory which cover less common\naspects of running trustydns. They include: running on Windows, implications of edns-client-subnet\nwith DoH and how to build and configure [unbound](https://nlnetlabs.nl/projects/unbound) to support ECS\nqueries and how to enable ECS synthesis to improve GSLB responses.\n\n### Community\n\nIf you have any problems using trustydns or suggestions on how it can do a better job, don't\nhesitate to create an [issue](https://github.com/markdingo/trustydns/issues) or email the\n[authors](https://github.com/markdingo/trustydns/blob/master/AUTHORS) directly. This package can\nonly improve with your feedback.\n\n### Copyright and License\n\nTrustydns is Copyright :copyright: 2019, 2020 Mark Delany. This software  is licensed under the BSD 2-Clause \"Simplified\" License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkdingo%2Ftrustydns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkdingo%2Ftrustydns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkdingo%2Ftrustydns/lists"}