dns-is-reverse 1.0.0__tar.gz

dns_is_reverse-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene Yaacobi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dns_is_reverse-1.0.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: dns-is-reverse
+Version: 1.0.0
+Summary: Python reimplementation of all-knowing-dns: authoritative DNS server for IPv6 reverse DNS synthesis
+Author: DNS Reverse Team
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dnslib>=0.9.23
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+# DNS-is-reverse
+
+A Python reimplementation of [all-knowing-dns](https://github.com/raumzeitlabor/all-knowing-dns): a tiny authoritative DNS server that synthesizes IPv6 reverse DNS (PTR) and matching forward AAAA records on the fly for SLAAC-style networks, avoiding gigantic zone files.
+
+## What it does
+
+DNS-is-reverse answers DNS queries for IPv6 networks by synthesizing responses based on templates:
+
+- **PTR queries**: For reverse DNS lookups (ip6.arpa), it extracts the host portion of the IPv6 address and generates a hostname using a configurable template
+- **AAAA queries**: For forward DNS lookups, it parses hostnames matching the template and returns the corresponding IPv6 address within the configured network
+- **Upstream fallback**: For PTR queries, it can optionally query an upstream DNS server first before synthesizing locally
+
+## Configuration Format
+
+The configuration file uses a simple line-based format:
+
+```
+listen <address>
+network <CIDR>
+    resolves to <template>
+    with upstream <address>  # optional
+```
+
+### Example Configuration
+
+```
+# Listen on IPv6 and IPv4
+listen ::1
+listen 127.0.0.1
+
+# Configure a /64 network
+network 2001:4d88:100e:ccc0::/64
+    resolves to ipv6-%DIGITS%.nutzer.raumzeitlabor.de
+    with upstream 2001:4860:4860::8888
+
+# Configure a /56 network without upstream
+network 2001:db8:100::/56
+    resolves to host-%DIGITS%.example.com
+```
+
+## How %DIGITS% Works
+
+The `%DIGITS%` placeholder in templates represents the host portion of IPv6 addresses as hexadecimal digits:
+
+- For a `/64` network: 64 host bits = 16 hex digits
+- For a `/56` network: 72 host bits = 18 hex digits  
+- For a `/80` network: 48 host bits = 12 hex digits
+
+### Example for /64 network `2001:4d88:100e:ccc0::/64`:
+
+- IPv6 address: `2001:4d88:100e:ccc0:216:eaff:fecb:826`
+- Host portion: `0216eafffecb0826` (16 hex digits, zero-padded)
+- Template: `ipv6-%DIGITS%.example.com`
+- Generated hostname: `ipv6-0216eafffecb0826.example.com`
+
+## Upstream Fallback
+
+When a network has `with upstream <address>` configured:
+
+1. For PTR queries, DNS-is-reverse first queries the upstream server for `<original_ptr_qname>.upstream`
+2. If the upstream returns a PTR answer, that answer is relayed to the client
+3. If the upstream returns NXDOMAIN/timeout/no-answer, DNS-is-reverse synthesizes the response locally
+4. AAAA queries are always synthesized locally (no upstream fallback)
+
+## Installation
+
+### Native Installation
+
+```bash
+pip install -e .
+```
+
+### Docker Installation
+
+```bash
+# Using docker-compose (recommended)
+docker-compose up --build
+
+# Or build and run manually
+docker build -t dns-is-reverse .
+docker run -p 53:53/udp -v ./test.conf:/etc/dns-is-reverse.conf:ro dns-is-reverse
+```
+
+## Usage
+
+### Command Line Options
+
+```bash
+dns-is-reverse [options]
+
+Options:
+  --configfile PATH     Configuration file path (default: /etc/all-knowing-dns.conf)
+  --listen ADDRESS      Additional listen address (can be used multiple times)
+  --port PORT          Listen port (default: 53)
+  --querylog           Enable query logging to stdout
+```
+
+### Running on High Port (Non-root)
+
+For development or non-root usage:
+
+```bash
+dns-is-reverse --configfile ./test.conf --port 5353 --querylog
+```
+
+### Running with Docker
+
+The Docker container runs on port 53 by default:
+
+```bash
+# Start with docker-compose
+docker-compose up
+
+# Or run directly with custom config
+docker run -p 53:53/udp -v /path/to/config.conf:/etc/dns-is-reverse.conf:ro dns-is-reverse
+```
+
+### Example Configuration File
+
+Create `test.conf`:
+
+```
+listen ::1
+listen 127.0.0.1
+
+network 2001:db8::/64
+    resolves to test-%DIGITS%.local
+
+network 2001:db8:100::/56
+    resolves to server-%DIGITS%.example.com
+    with upstream 8.8.8.8
+```
+
+### Testing with dig
+
+```bash
+# Test AAAA query
+dig @::1 -p 5353 test-1234567890abcdef.local AAAA
+
+# Test PTR query  
+dig @::1 -p 5353 -x 2001:db8::1234:5678:9abc:def0
+```
+
+## Supported Network Sizes
+
+DNS-is-reverse works with any IPv6 network size where the host portion is a multiple of 4 bits:
+
+- `/64` networks: 16 hex digits (most common for SLAAC)
+- `/56` networks: 18 hex digits  
+- `/48` networks: 20 hex digits
+- `/80` networks: 12 hex digits
+- etc.
+
+## DNS Behavior
+
+- **Authoritative**: All synthesized responses have the AA (Authoritative Answer) flag set
+- **TTL**: All responses use a 60-second TTL
+- **Error handling**: Returns NXDOMAIN for out-of-network queries or template mismatches
+- **Malformed queries**: Returns FORMERR for unparseable DNS requests
+- **Query types**: Only PTR and AAAA queries are supported; all others return NXDOMAIN
+
+## Development
+
+### Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+### Type Checking
+
+```bash
+mypy dns_is_reverse/
+```
+
+## License
+
+MIT License

dns_is_reverse-1.0.0/README.md

@@ -0,0 +1,179 @@
+# DNS-is-reverse
+
+A Python reimplementation of [all-knowing-dns](https://github.com/raumzeitlabor/all-knowing-dns): a tiny authoritative DNS server that synthesizes IPv6 reverse DNS (PTR) and matching forward AAAA records on the fly for SLAAC-style networks, avoiding gigantic zone files.
+
+## What it does
+
+DNS-is-reverse answers DNS queries for IPv6 networks by synthesizing responses based on templates:
+
+- **PTR queries**: For reverse DNS lookups (ip6.arpa), it extracts the host portion of the IPv6 address and generates a hostname using a configurable template
+- **AAAA queries**: For forward DNS lookups, it parses hostnames matching the template and returns the corresponding IPv6 address within the configured network
+- **Upstream fallback**: For PTR queries, it can optionally query an upstream DNS server first before synthesizing locally
+
+## Configuration Format
+
+The configuration file uses a simple line-based format:
+
+```
+listen <address>
+network <CIDR>
+    resolves to <template>
+    with upstream <address>  # optional
+```
+
+### Example Configuration
+
+```
+# Listen on IPv6 and IPv4
+listen ::1
+listen 127.0.0.1
+
+# Configure a /64 network
+network 2001:4d88:100e:ccc0::/64
+    resolves to ipv6-%DIGITS%.nutzer.raumzeitlabor.de
+    with upstream 2001:4860:4860::8888
+
+# Configure a /56 network without upstream
+network 2001:db8:100::/56
+    resolves to host-%DIGITS%.example.com
+```
+
+## How %DIGITS% Works
+
+The `%DIGITS%` placeholder in templates represents the host portion of IPv6 addresses as hexadecimal digits:
+
+- For a `/64` network: 64 host bits = 16 hex digits
+- For a `/56` network: 72 host bits = 18 hex digits  
+- For a `/80` network: 48 host bits = 12 hex digits
+
+### Example for /64 network `2001:4d88:100e:ccc0::/64`:
+
+- IPv6 address: `2001:4d88:100e:ccc0:216:eaff:fecb:826`
+- Host portion: `0216eafffecb0826` (16 hex digits, zero-padded)
+- Template: `ipv6-%DIGITS%.example.com`
+- Generated hostname: `ipv6-0216eafffecb0826.example.com`
+
+## Upstream Fallback
+
+When a network has `with upstream <address>` configured:
+
+1. For PTR queries, DNS-is-reverse first queries the upstream server for `<original_ptr_qname>.upstream`
+2. If the upstream returns a PTR answer, that answer is relayed to the client
+3. If the upstream returns NXDOMAIN/timeout/no-answer, DNS-is-reverse synthesizes the response locally
+4. AAAA queries are always synthesized locally (no upstream fallback)
+
+## Installation
+
+### Native Installation
+
+```bash
+pip install -e .
+```
+
+### Docker Installation
+
+```bash
+# Using docker-compose (recommended)
+docker-compose up --build
+
+# Or build and run manually
+docker build -t dns-is-reverse .
+docker run -p 53:53/udp -v ./test.conf:/etc/dns-is-reverse.conf:ro dns-is-reverse
+```
+
+## Usage
+
+### Command Line Options
+
+```bash
+dns-is-reverse [options]
+
+Options:
+  --configfile PATH     Configuration file path (default: /etc/all-knowing-dns.conf)
+  --listen ADDRESS      Additional listen address (can be used multiple times)
+  --port PORT          Listen port (default: 53)
+  --querylog           Enable query logging to stdout
+```
+
+### Running on High Port (Non-root)
+
+For development or non-root usage:
+
+```bash
+dns-is-reverse --configfile ./test.conf --port 5353 --querylog
+```
+
+### Running with Docker
+
+The Docker container runs on port 53 by default:
+
+```bash
+# Start with docker-compose
+docker-compose up
+
+# Or run directly with custom config
+docker run -p 53:53/udp -v /path/to/config.conf:/etc/dns-is-reverse.conf:ro dns-is-reverse
+```
+
+### Example Configuration File
+
+Create `test.conf`:
+
+```
+listen ::1
+listen 127.0.0.1
+
+network 2001:db8::/64
+    resolves to test-%DIGITS%.local
+
+network 2001:db8:100::/56
+    resolves to server-%DIGITS%.example.com
+    with upstream 8.8.8.8
+```
+
+### Testing with dig
+
+```bash
+# Test AAAA query
+dig @::1 -p 5353 test-1234567890abcdef.local AAAA
+
+# Test PTR query  
+dig @::1 -p 5353 -x 2001:db8::1234:5678:9abc:def0
+```
+
+## Supported Network Sizes
+
+DNS-is-reverse works with any IPv6 network size where the host portion is a multiple of 4 bits:
+
+- `/64` networks: 16 hex digits (most common for SLAAC)
+- `/56` networks: 18 hex digits  
+- `/48` networks: 20 hex digits
+- `/80` networks: 12 hex digits
+- etc.
+
+## DNS Behavior
+
+- **Authoritative**: All synthesized responses have the AA (Authoritative Answer) flag set
+- **TTL**: All responses use a 60-second TTL
+- **Error handling**: Returns NXDOMAIN for out-of-network queries or template mismatches
+- **Malformed queries**: Returns FORMERR for unparseable DNS requests
+- **Query types**: Only PTR and AAAA queries are supported; all others return NXDOMAIN
+
+## Development
+
+### Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+### Type Checking
+
+```bash
+mypy dns_is_reverse/
+```
+
+## License
+
+MIT License

dns_is_reverse-1.0.0/dns_is_reverse/__init__.py

@@ -0,0 +1,3 @@
+"""dns-is-reverse - Python reimplementation of all-knowing-dns."""
+
+__version__ = "1.0.0"

dns_is_reverse-1.0.0/dns_is_reverse/cli.py

@@ -0,0 +1,66 @@
+"""Command-line interface for DNS-is-reverse."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from .dns_server import DNSServer
+from .parser import parse_config
+
+
+def main() -> None:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(description="DNS-is-reverse - IPv6 reverse DNS synthesizer")
+    parser.add_argument(
+        "--configfile",
+        default="/etc/dns-is-reverse.conf",
+        help="Configuration file path (default: /etc/dns-is-reverse.conf)"
+    )
+    parser.add_argument(
+        "--listen",
+        action="append",
+        help="Additional listen address (can be used multiple times)"
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=53,
+        help="Listen port (default: 53)"
+    )
+    parser.add_argument(
+        "--querylog",
+        action="store_true",
+        help="Enable query logging to stdout"
+    )
+    
+    args = parser.parse_args()
+    
+    # Read config file
+    config_path = Path(args.configfile)
+    if not config_path.exists():
+        print(f"Error: Config file not found: {config_path}", file=sys.stderr)
+        sys.exit(1)
+    
+    try:
+        config_text = config_path.read_text()
+        config = parse_config(config_text)
+    except Exception as e:
+        print(f"Error parsing config: {e}", file=sys.stderr)
+        sys.exit(1)
+    
+    # Override config with CLI args
+    if args.listen:
+        config.listen_addresses.extend(args.listen)
+    config.port = args.port
+    config.query_log = args.querylog
+    
+    # Start server
+    server = DNSServer(config)
+    try:
+        server.start()
+    except KeyboardInterrupt:
+        print("\nShutting down...")
+
+
+if __name__ == "__main__":
+    main()

dns_is_reverse-1.0.0/dns_is_reverse/config.py

@@ -0,0 +1,27 @@
+"""Configuration data structures for dns-is-reverse."""
+
+from dataclasses import dataclass
+from ipaddress import IPv6Network
+from typing import Optional
+
+
+@dataclass
+class NetworkConfig:
+    """Configuration for a single network."""
+    network: IPv6Network
+    template: str
+    upstream: Optional[str] = None
+    
+    def __post_init__(self) -> None:
+        """Validate template contains exactly one %DIGITS%."""
+        if self.template.count('%DIGITS%') != 1:
+            raise ValueError(f"Template must contain exactly one %DIGITS%, got: {self.template}")
+
+
+@dataclass
+class Config:
+    """Main configuration."""
+    listen_addresses: list[str]
+    networks: list[NetworkConfig]
+    port: int = 53
+    query_log: bool = False

dns_is_reverse-1.0.0/dns_is_reverse/dns_server.py

@@ -0,0 +1,155 @@
+"""DNS server implementation."""
+
+import socket
+import threading
+from typing import Optional
+
+import dnslib  # type: ignore
+
+from .config import Config
+from .reverse import ptr_qname_to_ipv6
+from .synth import find_matching_network, find_matching_template, synthesize_ptr_hostname, synthesize_aaaa_address
+from .upstream import query_upstream
+
+
+class DNSServer:
+    """UDP DNS server."""
+    
+    def __init__(self, config: Config):
+        self.config = config
+        self.running = False
+        
+    def handle_request(self, data: bytes, addr: tuple[str, int]) -> bytes:
+        """Handle a single DNS request."""
+        try:
+            request = dnslib.DNSRecord.parse(data)
+        except Exception:
+            # Malformed request
+            response = dnslib.DNSRecord()
+            response.header.rcode = dnslib.RCODE.FORMERR
+            return response.pack()  # type: ignore
+        
+        if self.config.query_log:
+            print(f"Query from {addr[0]}: {request.q.qname} {dnslib.QTYPE[request.q.qtype]}")
+        
+        response = dnslib.DNSRecord()
+        response.header.id = request.header.id
+        response.header.qr = 1  # Response
+        response.header.aa = 1  # Authoritative
+        response.header.rcode = dnslib.RCODE.NOERROR  # Default to success
+        response.add_question(request.q)
+        
+        qname = str(request.q.qname).rstrip('.')
+        qtype = request.q.qtype
+        
+        if qtype == dnslib.QTYPE.PTR:
+            self._handle_ptr(qname, response)
+        elif qtype == dnslib.QTYPE.AAAA:
+            self._handle_aaaa(qname, response)
+        else:
+            response.header.rcode = dnslib.RCODE.NXDOMAIN
+            
+        return response.pack()  # type: ignore
+    
+    def _handle_ptr(self, qname: str, response: dnslib.DNSRecord) -> None:
+        """Handle PTR query."""
+        # Convert PTR qname to IPv6
+        addr = ptr_qname_to_ipv6(qname)
+        if addr is None:
+            response.header.rcode = dnslib.RCODE.NXDOMAIN
+            return
+        
+        # Find matching network
+        network_config = find_matching_network(addr, self.config.networks)
+        if network_config is None:
+            response.header.rcode = dnslib.RCODE.NXDOMAIN
+            return
+        
+        # Try upstream first if configured
+        if network_config.upstream:
+            upstream_qname = f"{qname}.upstream"
+            ptr_values = query_upstream(network_config.upstream, upstream_qname)
+            if ptr_values:
+                for ptr_value in ptr_values:
+                    # Strip trailing dot from upstream response
+                    ptr_value = ptr_value.rstrip('.')
+                    rr = dnslib.RR(
+                        rname=qname,
+                        rtype=dnslib.QTYPE.PTR,
+                        rdata=dnslib.PTR(ptr_value),
+                        ttl=60
+                    )
+                    response.add_answer(rr)
+                return
+        
+        # Synthesize locally
+        hostname = synthesize_ptr_hostname(addr, network_config)
+        rr = dnslib.RR(
+            rname=qname,
+            rtype=dnslib.QTYPE.PTR,
+            rdata=dnslib.PTR(hostname),
+            ttl=60
+        )
+        response.add_answer(rr)
+    
+    def _handle_aaaa(self, qname: str, response: dnslib.DNSRecord) -> None:
+        """Handle AAAA query."""
+        # Find matching template
+        network_config = find_matching_template(qname, self.config.networks)
+        if network_config is None:
+            response.header.rcode = dnslib.RCODE.NXDOMAIN
+            return
+        
+        # Synthesize address
+        addr = synthesize_aaaa_address(qname, network_config)
+        if addr is None:
+            response.header.rcode = dnslib.RCODE.NXDOMAIN
+            return
+        
+        rr = dnslib.RR(
+            rname=qname,
+            rtype=dnslib.QTYPE.AAAA,
+            rdata=dnslib.AAAA(str(addr)),
+            ttl=60
+        )
+        response.add_answer(rr)
+    
+    def start(self) -> None:
+        """Start the DNS server."""
+        self.running = True
+        threads = []
+        
+        for listen_addr in self.config.listen_addresses:
+            thread = threading.Thread(target=self._serve_address, args=(listen_addr,))
+            thread.daemon = True
+            thread.start()
+            threads.append(thread)
+        
+        try:
+            for thread in threads:
+                thread.join()
+        except KeyboardInterrupt:
+            self.running = False
+    
+    def _serve_address(self, listen_addr: str) -> None:
+        """Serve DNS requests on a single address."""
+        family = socket.AF_INET6 if ':' in listen_addr else socket.AF_INET
+        sock = socket.socket(family, socket.SOCK_DGRAM)
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        
+        try:
+            sock.bind((listen_addr, self.config.port))
+            print(f"Listening on {listen_addr}:{self.config.port}")
+            
+            while self.running:
+                try:
+                    data, addr = sock.recvfrom(4096)
+                    response_data = self.handle_request(data, addr)
+                    sock.sendto(response_data, addr)
+                except socket.timeout:
+                    continue
+                except Exception as e:
+                    if self.running:
+                        print(f"Error handling request: {e}")
+        finally:
+            sock.close()

dns_is_reverse-1.0.0/dns_is_reverse/parser.py

@@ -0,0 +1,60 @@
+"""Configuration file parser."""
+
+import re
+from ipaddress import IPv6Network
+from typing import Iterator
+
+from .config import Config, NetworkConfig
+
+
+def parse_config(text: str) -> Config:
+    """Parse configuration from text."""
+    lines = [line.rstrip() for line in text.splitlines()]
+    listen_addresses: list[str] = []
+    networks: list[NetworkConfig] = []
+    
+    i = 0
+    while i < len(lines):
+        line = lines[i].strip()
+        if not line or line.startswith('#'):
+            i += 1
+            continue
+            
+        if line.startswith('listen '):
+            address = line[7:].strip()
+            listen_addresses.append(address)
+            i += 1
+        elif line.startswith('network '):
+            network_str = line[8:].strip()
+            network = IPv6Network(network_str)
+            i += 1
+            
+            # Parse indented block
+            template = None
+            upstream = None
+            
+            while i < len(lines):
+                if not lines[i] or lines[i].startswith('#'):
+                    i += 1
+                    continue
+                if not lines[i].startswith((' ', '\t')):
+                    break
+                    
+                subline = lines[i].strip()
+                if subline.startswith('resolves to '):
+                    template = subline[12:].strip()
+                elif subline.startswith('with upstream '):
+                    upstream = subline[14:].strip()
+                i += 1
+            
+            if template is None:
+                raise ValueError(f"Network {network_str} missing 'resolves to' directive")
+            
+            networks.append(NetworkConfig(network, template, upstream))
+        else:
+            raise ValueError(f"Unknown directive: {line}")
+    
+    if not listen_addresses:
+        listen_addresses = ["::", "0.0.0.0"]
+    
+    return Config(listen_addresses, networks)