{"id":13721808,"url":"https://github.com/awgh/madns","last_synced_at":"2026-01-12T06:38:02.678Z","repository":{"id":20580665,"uuid":"90332346","full_name":"awgh/madns","owner":"awgh","description":"DNS server for pentesters","archived":false,"fork":false,"pushed_at":"2021-12-14T22:38:43.000Z","size":56,"stargazers_count":48,"open_issues_count":0,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-31T09:02:37.541Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/awgh.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}},"created_at":"2017-05-05T03:14:10.000Z","updated_at":"2024-07-13T12:16:56.000Z","dependencies_parsed_at":"2022-09-06T05:20:19.265Z","dependency_job_id":null,"html_url":"https://github.com/awgh/madns","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awgh%2Fmadns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awgh%2Fmadns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awgh%2Fmadns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awgh%2Fmadns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/awgh","download_url":"https://codeload.github.com/awgh/madns/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252895490,"owners_count":21821169,"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-03T01:01:21.677Z","updated_at":"2026-01-12T06:38:02.672Z","avatar_url":"https://github.com/awgh.png","language":"Go","funding_links":[],"categories":["Web Application Testing","Go (531)","Go"],"sub_categories":[],"readme":"# madns: the DNS server for pentesters\n\n## Dependencies \u0026 Requirements\n - [go language](https://golang.org/)\n - [go dns package](https://github.com/miekg/dns)\n - A domain you own\n\n\n## Installation on Linux\n\n### Install go\n```\nwget https://go.dev/dl/go1.17.5.linux-amd64.tar.gz\nsudo tar -C /usr/local -xzf go1.17.5.linux-amd64.tar.gz\n```\n\n### Add go to your environment/PATH\n```\necho 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' \u003e\u003e ~/.profile\nsource ~/.profile\n```\n\n### Install madns (installs to ~/go/bin/madns)\n```\ngo install github.com/awgh/madns@latest\n```\n\n### Create madns-config based off template\n```\ncp ~/go/pkg/mod/github.com/awgh/madns@*/madns-config.json.example ./madns-config.json\n```\n\n## Setup madns config\n\nEdit the madns-config.json file, according to the following instructions.\n\n### Port\nStandard DNS port, only change if you know your setup differs.\n\n`\"Port\": 53`\n\n#### Dealing with systemd-resolved\nIf your system is running systemd-resolved (common for Ubuntu), you will have to follow these instructions to free up port 53: \nhttps://medium.com/@niktrix/getting-rid-of-systemd-resolved-consuming-port-53-605f0234f32f\n\n\n### Handlers\nThis is where you define the domain/subdomain to trigger your email notification.\n\nEach handler has a trigger portion, which describes the (sub)domains that it will handle, and **either** a Redirect command or a Respond command.  You must have a Redirect or a Respond command in each handler, but not both!\n\nAdditionally, handlers can have a NotifyEmail instruction, which notify you by email when the handler is invoked. They can also use the NotifySlack instruction, which sends the same notification to a Slack channel via webhooks.\n\n**.** is the default DNS handler, if a query doesn't match any other handler it will use this handler.\n\n#### Redirect handlers\nRedirect commands will redirect the request to an upstream DNS server.  Redirect commands require the IP address and the port, like \"8.8.8.8:53\".\n\n#### Respond handlers\nRespond commands will respond with a fixed response.  Respond commands only need the IP address or the domain name (for a CNAME).  IP addresses can be either IPv4 or IPv6, and will generate an A/AAAA record accordingly.\n\n\n### Examples\nThe following example is a catch-all handler that will redirect requests not handled by another handler to another DNS Server, in this case 8.8.8.8:\n\n```\n\".\": {\n        \"Redirect\": \"8.8.8.8:53\"\n        \"NotifyEmail\": \"youremail@domain.com\"\n     },\n```\n\nNow you’ll want to create a subdomain that will trigger when a DNS lookup is performed on it for testing double blind XXE/SQLi/etc. It can be useful to setup an email with a +filterkeyword to make it easier to tell which handler fired when you get a successful hit.\n\nIn the following example, the triggering domain will always respond with a fixed address and also notify you of the hit by email:\n\n```\n\"your.triggering.domain\": { \n        \"Respond\": \"192.168.1.1\", \n        \"NotifyEmail\": \"youremail+filterkeyword@domain.com\"\n        }\n```\n\n### SMTP Configuration (Optional)\n\nIf you want to use the NotifyEmail feature, you have to set the SMTP configuration values.\n\n```\n\"SmtpUser\":\"yourburneremail@gmail.com\",\n\"SmtpPassword\":\"\u003cpassword to yourburneremail\u003e\",\n\"SmtpServer\":\"smtp.gmail.com:587\",\n\"SmtpDelay\":30,\n```\nThe SmtpDelay parameter determines how many seconds madns will batch up alerts into a single email.  By default, this is set to 1 minute, so there will be a 1 minute delay before the first email is sent unless the SmtpDelay is set.\n\n#### Gmail SMTP enable less-secure apps\nSo gmail does that whole security thing and won't let madns log in and\nperform SMTP unless you enable less secure apps. https://www.google.com/settings/security/lesssecureapps\n\n### Start madns\nIf you're listening to the default port 53 (or anything lower than 1024):\n\n`sudo madns -c madns-config.json \u0026`\n\nFor ports above 1024:\n\n`madns -c madns-config.json \u0026`\n\n## Configure your domain\nAdd an subdomain record (an A record) in your DNS management section of your domain to point to the IP address that madns is running on. For example:\n\n```\nType\t\tName\t\t\tValue\t\t\t\tTTL\nA\t\t\u003cspecial\u003e\t\t\u003cip-to-madns-server\u003e\t\t7200\nNS\t\t\u003csubdomain\u003e\t\t\u003cspecial.domain\u003e\t\t7200\n```\nAlso ensure that incoming/outgoing traffic on port 53 is open and outgoing SMTP traffic is allowed on your box.\n\n## Test madns\nGet the nameserver registered for your domain\n\n`dig domain -t NS   `\n\nUse that nameserver to query your subdomain\n\n`dig @\u003cnameserver.from.previous.dig\u003e subdomain.domain -t NS`\n\nIf all is well you should see something like\n```\n;; QUESTION SECTION:\n;\u003csubdomain.domain.\u003e IN    NS\n\n;; AUTHORITY SECTION:\n.\u003csubdomain.domain\u003e. 259200 IN NS   \u003cspecial.domain.\u003e\n;; ADDITIONAL SECTION:\n\u003cspecial.domain.\u003e          3600    IN      A       \u003cip.of.host.running.madns\u003e\n```\n\n\nNow test with curl\n\n`curl subdomain.subdomain.domain`\n\nOn the madns server you see notifications to stdout that it hit the Handler and sent an email such as:\n\n`2017/09/21 11:24:37 sent email to xxe+dns@hotmail.com`\n\n   \n\n## systemd service file\n\nYou can set up madns to run as a systemd server which starts on boot.\n\nRun the following commands to install madns in /opt and create a systemd service file for it.\n\n```\nsudo mkdir -p /opt/madns/\nsudo cp ~/go/bin/madns /opt/madns/\nsudo cp madns-config.json /opt/madns/\nsudo nano /etc/systemd/system/madns.service\n```\n\nPut the following contents into the madns.service file and save it:\n```\n[Unit]\nDescription=madns DNS server\nAfter=network.target\n\n[Service]\nWorkingDirectory=/opt/madns\nExecStart=/opt/madns/madns -c madns-config.json\nExecStop=/bin/kill $MAINPID\nKillMode=process\nRestart=on-failure\nRestartSec=5s\nType=simple\n\n[Install]\nWantedBy=multi-user.target\nAlias=madns.service\n```\n\nFinally, reload the systemd config files and start/enable madns:\n```\nsudo systemctl daemon-reload\nsudo systemctl enable madns\nsudo systemctl start madns\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawgh%2Fmadns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fawgh%2Fmadns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawgh%2Fmadns/lists"}