DOCSEARCHbyAlgolia
Submit Docs

PolarDNS

repository·main·Indexed 42 days ago

https://github.com/oryxlabs/polardns

A specialized authoritative DNS server written in Python 3.x for penetration testing and vulnerability research. PolarDNS allows operators to generate highly custom, non-standard, and malformed DNS responses to test the robustness of recursive resolvers, clients, libraries, and parsers. It features over 70 response generators and 19 modifiers to simulate complex scenarios such as alias chains, cache poisoning, and DNS header malformations. Version 1.6.6.

Tokens
17.5K
Snippets
41
Records
82
Agent score
54%

What's inside PolarDNS

  1. Overview of PolarDNS

    main

    PolarDNS is a specialized authoritative DNS server written in Python 3.x. It is designed primarily for security testing of DNS recursive resolvers from the server-side.

    Key capabilities include:

    • Custom DNS Responses: Allows operators to produce custom, non-standard, or non-compliant DNS responses.
    • Protocol Testing: Can generate responses that violate RFC specifications, including highly abnormal or malformed DNS responses.
    • Protocol Support: Supports both UDP and TCP protocols.

    Use Cases:

    • Testing DNS resolvers (server-side), clients, libraries, parsers, and dissectors.
    • Functional testing and RFC compliance verification.
    • Vulnerability research.

  2. How Alias Chains work in PolarDNS

    main

    Alias Chain modules are designed to generate incremental alias records for various resource types (such as CNAME, DNAME, NS, MX, HTTPS, SVCB, SRV, and SPF-TXT).

    These modules produce records in a specific format: chain###.yourdomain.com, where ### is an incrementing index. The purpose of this mechanism is to create an infinite resolution chain: when a client or resolver attempts to resolve an alias, the module provides a new, incremented alias, potentially keeping the resolver occupied indefinitely.

  3. How PolarDNS response customization works

    main

    PolarDNS allows clients to dictate the specific characteristics of a DNS response by embedding instructions directly into the query domain name. Instead of just requesting a record, you can use specific keywords and modifiers within the hostname to control the response type, TTL (Time To Live), and latency (delay).

    To customize a response, you construct a query using a pattern of [feature].[modifier].[modifier].yourdomain.com.

    Common modifiers include:

    • always: A basic feature that ensures the server always returns a response.
    • ttl<value>: Adjusts the TTL value of the returned record (e.g., ttl2000000000).
    • slp<value>: Introduces a delay (latency) before the response is sent (e.g., slp1500 for 1.5 seconds).

    This mechanism is useful for testing how clients and recursive resolvers handle specific DNS behaviors like long-lived cache entries or network latency.

    dig always.ttl2000000000.slp1500.yourdomain.com @127.0.0.1

  4. Fuzzing capabilities of PolarDNS via subdomain prefixes

    main

    PolarDNS includes built-in support for DNS fuzzing and security testing. By prefixing queries with specific subdomain strings, you can trigger specialized responses designed to test DNS resolver robustness, including malformed compression pointers, loops, and large records.

    Supported Fuzzing Prefixes

    PrefixBehavior
    always or somethingResolves to a fixed IP (2.3.4.5 for A, 1111:2222:3333:4444:5555:6666:7777:8888 for AAAA) with a configurable number of answers.
    afuzz1Returns an A record with a distorted domain name (replacing a character with a specific byte).
    afuzz2Returns multiple A records with distorted names, followed by a legitimate record.
    aliasReturns multiple random aliases (CNAME, DNAME, HTTPS, SVCB, SRV, MX, NS, or SPF/TXT) to test alias handling.
    badcompress1Sends a CNAME with an arbitrary compression pointer in the Answer name.
    badcompress2Sends a CNAME with an arbitrary compression pointer inside the CNAME value.
    badcompressfwptr1 / badcompressfwptr2Sends CNAMEs with forward compression pointers that point to other pointers (pointer chains).
    badcompressloop1 to badcompressloop5Sends various CNAME compression loops (in the Answer name, in the CNAME value, or involving forward/backward pointers).
    badcompressmid1Sends a CNAME with a compression pointer in the middle of the name, concatenated with additional strings.
    bigbintxtReturns a large TXT record composed of multiple binary chunks.
    bigtxtReturns a large TXT record composed of multiple long alphanumeric labels.
    chainReturns an incremented alias record (CNAME, DNAME, etc.) to test chain resolution.

  5. Understanding Alias Loops in PolarDNS

    main

    PolarDNS includes modules designed to implement alias loops for various DNS resource types. An alias loop occurs when an alias record (such as CNAME, NS, or MX) points back to the original domain name or cycles through a sequence of elements that eventually returns to the starting domain.

    If a client or recursive resolver attempts to follow these aliases, it will enter an infinite resolution loop. This behavior is implemented for the following resource types:

    • CNAME
    • DNAME
    • PTR
    • NAPTR
    • NS
    • MX
    • HTTPS
    • SVCB
    • SRV
    • SPF-TXT

  6. How header manipulation modules work in PolarDNS

    main

    Header manipulation modules are a category of response modifiers in PolarDNS. They are used to modify various fields and flags within the DNS header during the response phase.

    Common use cases include:

    • Altering the number of records in a response.
    • Generating a new Transaction ID in the response.
    • Modifying other header flags and fields.

    Because these are response modifiers, they can be combined with any other PolarDNS feature or modifier to create highly customized DNS responses.

  7. Experiment with DNS compression malformations

    main

    PolarDNS provides specialized modules for testing how DNS resolvers and clients handle malformed or non-standard compression schemes. You can use these modules to inject specific errors into DNS messages to assess the robustness of your infrastructure against various compression-based attacks or implementation bugs.

    Supported malformations include:

    • Pointer loops: Creating circular references in DNS compression pointers.
    • Forward pointers: Using pointers that point to locations ahead of the current position.
    • Double compression: Applying compression multiple times to the same data.
    • Offset manipulation: Manipulating offsets across different fields of DNS messages.

  8. Use response modifiers for packet manipulation

    main

    PolarDNS provides a category of modules known as response modifiers that allow you to manipulate DNS packets. These modules enable you to modify various aspects of DNS responses, such as:

    • Adjusting TTL (Time To Live) values
    • Introducing artificial delays
    • Forcing TCP mode
    • Adding or removing bytes from the packet

    Response modifiers are highly composable; they can be combined with any other feature or modifier to create complex, customized DNS response behaviors.

  9. Use Fuzzing modules for domain name experimentation

    main

    PolarDNS provides a category of Fuzzing modules designed to experiment with domain name malformations across multiple resource types. These modules are used to test how DNS resolvers handle edge cases, including:

    • Oversized domain names and subdomains: Testing limits of length constraints.
    • Permitted characters: Validating how different character sets are handled in domain names.
    • Encoding and transmission: Testing how domain names are encoded and transmitted over the network using DNS name notation.

  10. How PolarDNS response generation works

    main

    PolarDNS uses a unique mechanism where the client (the person making the DNS query) dictates the server's response through the structure of the requested subdomain.

    By combining Features and Response Modifiers in the query string, you can control exactly what the server returns.

    • Features: Produce specific DNS responses (e.g., always always resolves to something).
    • Response Modifiers: Modify the response produced by a feature (e.g., ttl to change the Time-To-Live, or slp to introduce latency).

    Example: To request a response with a specific TTL and a simulated delay, you would structure a query like this: always.ttl<TTL_VALUE>.slp<DELAY_SECONDS>.yourdomain.com

    In the example always.ttl2000000000.slp1500.yourdomain.com, the server returns an A record with a TTL of 2,000,000,000 after a 1.5-second delay.

    dig always.ttl2000000000.slp1500.yourdomain.com @127.0.0.1

  11. Structure of a DNS response feature in PolarDNS

    main

    When implementing a new feature that crafts custom DNS responses in PolarDNS, you should follow a consistent four-part structure to ensure clarity and maintainability. Most features follow this pattern:

    1. DNS Header Construction: Logic to build the DNS header section.
    2. QUESTION Section Construction: Logic to build the question section of the DNS packet.
    3. ANSWER Section Construction: Logic to build the answer section. This is the primary area for innovation and where most custom logic resides.
    4. Packet Transmission: Logic to send the constructed packet out and print a status message to the console.

  12. Use Alias modules to generate randomized DNS records

    main

    Alias modules in PolarDNS are used to generate randomized alias records for various resource types. These modules are designed to create an infinite chain of resolutions: if a client or resolver attempts to resolve an alias, it triggers the generation of a new, subsequent alias.

    Supported resource types for alias generation include:

    • CNAME
    • DNAME
    • NS
    • MX
    • HTTPS
    • SVCB
    • SRV
    • SPF-TXT

    Generated aliases typically follow the format: alias######.yourdomain.com, where ###### represents a randomly generated number.