{"id":30222787,"url":"https://github.com/asivery/badns","last_synced_at":"2025-08-14T11:09:57.854Z","repository":{"id":299907805,"uuid":"792076659","full_name":"asivery/badns","owner":"asivery","description":"An unusual DNS server written in Rust, that sends DNS requests to a config file written in JS.","archived":false,"fork":false,"pushed_at":"2025-06-18T22:21:11.000Z","size":30,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-18T23:26:04.596Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asivery.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,"zenodo":null}},"created_at":"2024-04-25T23:43:50.000Z","updated_at":"2025-06-18T22:21:15.000Z","dependencies_parsed_at":"2025-06-18T23:36:39.834Z","dependency_job_id":null,"html_url":"https://github.com/asivery/badns","commit_stats":null,"previous_names":["asivery/badns"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/asivery/badns","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asivery%2Fbadns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asivery%2Fbadns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asivery%2Fbadns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asivery%2Fbadns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asivery","download_url":"https://codeload.github.com/asivery/badns/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asivery%2Fbadns/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270407963,"owners_count":24578345,"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","status":"online","status_checked_at":"2025-08-14T02:00:10.309Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-08-14T11:09:55.637Z","updated_at":"2025-08-14T11:09:57.815Z","avatar_url":"https://github.com/asivery.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# baDNS\n\nbaDNS is a DNS server written in Rust, leveraging the `rustdns` library for core functionality. It uses QuickJS to evaluate configuration files, allowing for dynamic and programmable DNS handling. When a DNS request is received, baDNS first routes the request to the JavaScript context defined by the configuration. If a response is generated within the JS context, it is returned. Otherwise, baDNS queries the configured upstream servers sequentially and caches the response for the specified TTL.\n\n## Features\n\n- **Programmable DNS Handling**: Define custom DNS logic using JavaScript.\n- **Flexible Configuration**: Use JavaScript to define how DNS requests are processed.\n- **Upstream Server Support**: Automatically query upstream servers if the JS context does not provide a response.\n- **Response Caching**: Cache upstream responses based on their TTL.\n- **HTTP Reverse Proxy**: Set up HTTP reverse proxy for domains.\n\n## Installation\n\nTo install baDNS, follow these steps:\n\n1. Ensure you have Rust installed. If not, download it from [rust-lang.org](https://www.rust-lang.org/).\n2. Clone the baDNS repository:\n   ```sh\n   git clone https://github.com/asivery/badns.git\n   cd badns\n   ```\n3. Build the project using Cargo:\n   ```sh\n   cargo build --release\n   ```\n4. The binary will be located in `target/release/badns`.\n\n## Usage\n\nTo run baDNS, execute the following command:\n```sh\n./badns \u003cconfig-file\u003e\n```\nReplace `\u003cconfig-file\u003e` with the path to your JavaScript configuration file.\n\n## Configuration\n\nThe configuration file is a JavaScript file evaluated by QuickJS. Below is a summary of the available functions and their purposes:\n\n### Main Initialization\n\nThe main baDNS initialization file is executed before the configuration file. It prepares the environment and exposes user-friendly methods for DNS handling.\n\n### Functions\n\n#### Network Setup\n- **`bindAddress(address: string, port = 53)`**: Binds the UDP address and starts listening. Multiple interfaces can be open simultaneously.\n- **`upstream(address: string, port = 53)`**: Adds an upstream server. Queries upstream servers sequentially if no JS context response is found.\n\n#### HTTP Reverse Proxy\n- **`setupHTTPRedirectServer(address: string, port: number, recordTarget: string)`**: Sets up the HTTP reverse proxy server - it needs to know its own IP address, so that it redirects correctly.\n- **`addHTTPRedirect(target: string, name: string)`**: Adds a reverse proxy entry to bind the domain `name` to the HTTP address `target`.\n\n#### DNS Bindings\n- **`addBinding(rrtype: RRConstant, name: string, handler: Handler)`**: Adds a binding for a specific rrtype and name.\n- **`addABinding(name: string, handler: Handler)`**: Adds an RR_A binding.\n- **`addAAAABinding(name: string, handler: Handler)`**: Adds an RR_AAAA binding.\n- **`addCNAMEBinding(name: string, handler: Handler)`**: Adds an RR_CNAME binding.\n- **`addUniversalBinding(handler: Handler)`**: Adds a universal binding triggered on every query unless overridden by specific bindings.\n\n#### Helper Functions\n- **`STUB()`**: Returns an RR_A response with an infinite TTL pointing to 0.0.0.0.\n- **`permanentBinding(ip: string, domain: string)`**: Adds a permanent RR_A binding.\n- **`ban(domain: string)`**: Bans a domain using a STUB() handler.\n- **`exec(filename: string)`**: Evaluates the contents of the provided file.\n\n### baDNS Extensions\n\n- **`sha256(data: string)`**: Generates a SHA256 digest of the provided data.\n- **`readFile(filename: string)`**: Reads and returns the contents of the specified file as UTF-8.\n\n## Example Configuration\n\nBelow is an example configuration file demonstrating basic usage:\n\n```javascript\n// Bind to port 53 on all interfaces\nbindAddress('0.0.0.0');\n\n// Set up an upstream DNS server\nupstream('8.8.8.8');\n\n// Add a permanent A record binding\npermanentBinding('192.168.1.1', 'example.com');\n\n// Ban a specific domain\nban('malicious.com');\n\n// Set up the HTTP reverse proxy server on port 80, with the server returning its own address as 192.168.1.2\nsetupHTTPRedirectServer('0.0.0.0', 80, '192.168.1.2');\n\n// Add a reverse proxy entry to bind the domain 'web.example.com' to HTTP address 'http://localhost:3000'\naddHTTPRedirect('192.168.1.123:3000', 'internal.site');\n\n// Universal binding for all queries\naddUniversalBinding((name, rrtype, rrclass, peerAddress, ownAddress) =\u003e {\n    console.log(`Query received: ${name}, type: ${rrtype}`);\n    return { special: true, specialType: 'queryUpstream' };\n});\n```\n\n---\n\nFeel free to reach out with any questions or feedback regarding baDNS. Happy DNS serving!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasivery%2Fbadns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasivery%2Fbadns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasivery%2Fbadns/lists"}