{"id":16858138,"url":"https://github.com/ogham/madns","last_synced_at":"2026-01-04T15:02:34.528Z","repository":{"id":66117935,"uuid":"319455002","full_name":"ogham/madns","owner":"ogham","description":"A dummy DNS server with pre-programmed deliberately-incorrect responses.","archived":false,"fork":false,"pushed_at":"2021-10-16T23:26:22.000Z","size":127,"stargazers_count":8,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-24T18:12:36.405Z","etag":null,"topics":["dns","testing"],"latest_commit_sha":null,"homepage":"https://madns.binarystar.systems/","language":"HTML","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/ogham.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2020-12-07T21:58:18.000Z","updated_at":"2023-04-14T02:02:09.000Z","dependencies_parsed_at":"2023-02-20T18:15:37.547Z","dependency_job_id":null,"html_url":"https://github.com/ogham/madns","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogham%2Fmadns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogham%2Fmadns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogham%2Fmadns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogham%2Fmadns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ogham","download_url":"https://codeload.github.com/ogham/madns/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244217951,"owners_count":20417677,"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","testing"],"created_at":"2024-10-13T14:11:44.479Z","updated_at":"2026-01-04T15:02:29.509Z","avatar_url":"https://github.com/ogham.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"madns\n=====\n\nA dummy DNS server with pre-programmed deliberately-incorrect responses.\n\n**For more information, see [the madns website](https://madns.binarystar.systems/).**\n\n\nOptions\n-------\n\n```\n  -b, --bind=ADDR     Network address to bind to\n  -p, --port=PORT     Port to serve on\n      --tcp           Serve over TCP\n      --udp           Serve over UDP\n  -4                  Serve using IPv4 (with UDP)\n  -6                  Serve using IPv6 (with UDP)\n  -d, --dir=DIR       Path to the samples directory\n  -h, --help          Prints this help\n```\n\nThe `--port`, `--bind`, and `--dir` arguments, along with one of `--tcp` or `--udp`, are mandatory.\n\n\nTechnical details\n-----------------\n\nmadns is written in Ruby and Hexit.\n\nThe server is written in Ruby using the networking facilities in the standard library. It uses no third-party gems.\n\nThe DNS packet samples are written in [Hexit](https://github.com/ogham/hexit), a mini-language specifically constructed for writing network packets and other binary data while still being readable to those seeing it for the first time. The Ruby server invokes a `hexit` command, so you will need to have the binary somewhere in your `$PATH`.\n\nFor example, here’s the code to generate the response to a query for `a.example`, which exists in the `a.example.hexit` file in the `a` folder in the samples directory:\n\n```hexit\n# DNS header\n# (minus transaction ID)\nFlags: 81 80\nCounts: be16[1]  be16[1]  be16[0]  be16[0]\n\n# Question\nDomain: 01 \"a\" 07 \"example\" 00\nType: be16(DNS_A)\nClass: be16(DNS_IN)\n\n# Answer\nDomain: c0 0c\nType: be16(DNS_A)\nClass: be16(DNS_IN)\nTTL: be32[600]\nLength: be16[4]\nIP: [127.0.0.1]\n```\n\nIt starts with the DNS flags (standard query, response, no error) and contains 1 question and 1 answer. The domain and record type in the question needs to match up with the name of the file and the directory it’s in; the domain has been segment-encoded in the way DNS clients expect. The answer is the interesting part: it refers back to the original domain using DNS compression, and the type and class must match up too. This A record responds with the `127.0.0.1` IP address.\n\nNote that the transaction ID is _not_ present in the Hexit code. Because this is the only part of the response that varies between queries, it is instead handled by the Ruby server and gets tacked on at the front before the response is sent.\n\nResponses that _must_ vary between queries, such as the random data or transaction ID ones, are handled entirely by the Ruby server.\n\n\nDocker support\n--------------\n\nThere’s an included `Dockerfile` that you can use to run madns without Rust, Ruby, or Hexit installed on your host computer. (It is not on Docker Hub or anything.)\n\nBuild it with `docker build`:\n\n```\n$ docker build . -t madns\n```\n\nBy default, the container process will bind to the address 0.0.0.0, listening to port 5301 over UDP. You’ll need to specify `/udp` in the port mapping section to specify a UDP port:\n\n```\n$ docker run -it --rm -p 5301:5301/udp madns\nListening on UDP port 5301, binding to 0.0.0.0\n```\n\nTo use TCP mode, pass `--tcp` as an argument:\n\n```\n$ docker run -it --rm -p 5301:5301 madns --tcp\nListening on TCP port 5301, binding to 0.0.0.0\n```\n\n\nLicence\n-------\n\nmadns is dual-licenced under the [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/) and [MIT](https://opensource.org/licenses/MIT) licences.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fogham%2Fmadns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fogham%2Fmadns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fogham%2Fmadns/lists"}