{"id":43567938,"url":"https://github.com/hapara-fail/nx53","last_synced_at":"2026-02-08T17:18:54.151Z","repository":{"id":334637226,"uuid":"1133116559","full_name":"hapara-fail/nx53","owner":"hapara-fail","description":"A firewall designed for owners of open DNS resolvers written in Rust.","archived":false,"fork":false,"pushed_at":"2026-01-26T14:45:51.000Z","size":296,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-26T17:43:03.488Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","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/hapara-fail.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"hapara.fail","thanks_dev":null,"custom":null}},"created_at":"2026-01-12T22:50:58.000Z","updated_at":"2026-01-26T14:45:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hapara-fail/nx53","commit_stats":null,"previous_names":["hapara-fail/nx53"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hapara-fail/nx53","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapara-fail%2Fnx53","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapara-fail%2Fnx53/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapara-fail%2Fnx53/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapara-fail%2Fnx53/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hapara-fail","download_url":"https://codeload.github.com/hapara-fail/nx53/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapara-fail%2Fnx53/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29058972,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T20:13:53.544Z","status":"ssl_error","status_checked_at":"2026-02-03T20:13:40.507Z","response_time":96,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":"2026-02-03T22:00:20.533Z","updated_at":"2026-02-03T22:00:38.625Z","avatar_url":"https://github.com/hapara-fail.png","language":"Rust","funding_links":["https://buymeacoffee.com/hapara.fail"],"categories":[],"sub_categories":[],"readme":"# nx53\n\n[![Rust CI](https://github.com/hapara-fail/nx53/actions/workflows/ci.yml/badge.svg)](https://github.com/hapara-fail/nx53/actions/workflows/ci.yml)\n\n**High-Performance DNS Firewall \u0026 Amplification Mitigation Engine**\n\n**nx53** is a lightweight, mission-critical firewall daemon written in **Rust**, optimized for Debian-based Linux environments. It operates as a protective layer for Public DNS Resolvers, specifically targeting the detection and mitigation of **DNS Amplification Attacks** (DDoS).\n\n---\n\n## 🛡️ Objective\n\nThe primary objective of nx53 is to protect open DNS resolvers from being exploited as amplifiers in DDoS attacks. It achieves this by:\n\n- **Protocol Awareness:** Inspecting DNS traffic (Port 53 UDP/TCP) at wire speed.\n- **Behavioral Analysis:** Identifying and blocking abusive traffic patterns without relying solely on static blacklists.\n- **Kernel Integration:** Enforcing drop rules directly in the Linux kernel via Netfilter for minimal overhead.\n\n---\n\n## 🎯 Protection Philosophy\n\nIt is important to understand the specific security role `nx53` plays in your infrastructure:\n\n- **✅ The Problem It Solves (Reflector Abuse):**\n  By stopping your server from replying to spoofed requests, `nx53` prevents your infrastructure from being weaponized to attack innocent victims. This protects your **Reputation** (keeping you off blacklists), saves your **Outbound Bandwidth**, and prevents **ISP/VPS Abuse Complaints** that typically lead to account suspension.\n\n- **❌ The Limitation (Inbound Saturation):**\n  `nx53` runs _on_ your server. If an attacker targets **you** directly with a volumetric attack larger than your internet connection (e.g., 10Gbps of traffic on a 1Gbps port), your pipe will be saturated _before_ the software can filter the packets.\n\n`nx53` is the ideal \"Host-Based\" defense. It is the most effective way to secure a custom UDP service without paying thousands of dollars for enterprise \"upstream\" mitigation (like Cloudflare Spectrum).\n\n---\n\n## 🚀 Installation \u0026 Management\n\n### Quick Install (Debian/Ubuntu)\n\nThe easiest way to install nx53 is to run the automated installer. **By default, it downloads pre-built binaries from GitHub releases**, which is significantly faster than building from source (especially on low-resource VMs). If no pre-built binary is available for your architecture or the download fails, it automatically falls back to building from source.\n\n```bash\ncurl -s -S -L https://raw.githubusercontent.com/hapara-fail/nx53/main/install.sh | sh -s -- -v\n```\n\nAlternatively using `wget`:\n\n```bash\nwget --no-verbose -O - https://raw.githubusercontent.com/hapara-fail/nx53/main/install.sh | sh -s -- -v\n```\n\nDuring installation, you will be prompted to select a traffic profile (Home, School, Enterprise, Datacenter).\n\n**Supported Architectures (Pre-built Binaries):**\n\n- Linux x86_64 (AMD64)\n- Linux aarch64 (ARM64)\n\n**Build from Source Option:**\n\nIf you prefer to build from source even when pre-built binaries are available:\n\n```bash\ncurl -s -S -L https://raw.githubusercontent.com/hapara-fail/nx53/main/install.sh | sh -s -- --build-from-source\n```\n\n### Uninstallation\n\nWe provide a dedicated cleanup script to remove nx53 and all associated components (service, configs, man pages, completions).\n\n```bash\ncurl -s -S -L https://raw.githubusercontent.com/hapara-fail/nx53/main/uninstall.sh | sudo sh\n```\n\n### Manual Build\n\nIf you prefer to build manually:\n\n```bash\ngit clone https://github.com/hapara-fail/nx53.git\ncd nx53\ncargo build --release\nsudo cp target/release/nx53 /usr/local/bin/\n```\n\n---\n\n## ✨ Core Features\n\n- **Heuristic Mitigation:** Uses a \"First-Packet\" rule and \"Escape Hatch\" logic to differentiate between legitimate users and attack scripts.\n- **Zero-Cost Abstractions:** Built with Rust for memory safety and high throughput on minimal hardware.\n- **Hybrid Operation:** Supports both automated intelligent filtering and manual static blocklists/whitelists.\n- **Real-Time Telemetry:** Provides instant visibility into attack metrics and dropped IPs.\n\n---\n\n## 🔥 Advanced Protection Features\n\n### Rate Limiting Per IP\n\nGraduated response system to prevent abuse without blanket blocking:\n\n| Offense | Action                       |\n| :------ | :--------------------------- |\n| First   | Temporary ban (default: 60s) |\n| Repeat  | Longer ban (default: 300s)   |\n\nConfigure in `config.toml`:\n\n```toml\n[rate_limit]\nenabled = true\nrequests_per_sec = 10\nfirst_offense_duration_secs = 60\nsecond_offense_duration_secs = 300\n```\n\n### DNS Query Type Filtering\n\nBlocks query types commonly used in amplification attacks:\n\n- **ANY queries:** Blocked by default (major amplification vector)\n- **Large TXT queries:** Blocked when exceeding size threshold\n- **Zone transfers (AXFR/IXFR):** Blocked by default (massive amplification)\n- **Custom blocking:** Configure any query type to block\n\n```toml\n[filters]\nblock_any_queries = true\nblock_large_txt = true\ntxt_max_size = 1024\nblocked_query_types = [\"AXFR\", \"IXFR\"]  # Configurable list\n```\n\n\u003e **Note:** DNSSEC query types (RRSIG, DNSKEY) are allowed by default for proper DNSSEC validation.\n\n### Response Rate Limiting (RRL)\n\nLimits identical responses per second to prevent reflection attacks:\n\n```toml\n[filters]\nenable_rrl = true\nrrl_responses_per_sec = 5      # Max identical responses/sec\nrrl_slip_ratio = 2             # Respond to 1/N requests when rate limited (0 = drop all)\n```\n\n### TCP Source Validation\n\nIPs that complete a TCP handshake are proven non-spoofed and receive trusted status:\n\n```toml\n[filters]\ntcp_validation_enabled = true\ntcp_validation_ttl_hours = 24  # Trust duration after TCP validation\nforce_tcp_for_large = true     # Force TCP for responses \u003e 512 bytes\nmax_udp_response_size = 512    # UDP response size limit (RFC 1035)\n```\n\n### Reflection Pattern Detection\n\nDetects attack signatures: new IP + single domain + high rate = blocked immediately:\n\n```toml\n[filters]\ndetect_reflection_patterns = true\n```\n\n### Subdomain Entropy Detection\n\nDetects random subdomain attacks (e.g., `abc123.example.com`, `xyz789.example.com`):\n\n```toml\n[filters]\nsubdomain_entropy_threshold = 3.5  # Shannon entropy threshold (0 = disabled)\n```\n\n### Amplification Ratio Limiting\n\nBlocks IPs when response/query byte ratio exceeds threshold:\n\n```toml\n[filters]\namplification_ratio_limit = 10  # Block if response \u003e 10x query size\n```\n\n\u003e **Note:** This feature tracks query sizes from captured packets. For full amplification ratio enforcement, integrate with your DNS server to report response sizes via the `record_response_size` API.\n\n### Automatic Whitelist Learning\n\nIPs with clean traffic patterns are automatically whitelisted after a configurable period:\n\n```toml\nauto_whitelist_days = 7\n```\n\n### IPv6 Support\n\nFull dual-stack monitoring with IPv6-specific attack pattern detection (enabled by default).\n\n---\n\n## 🧠 The Logic Engine\n\nnx53 employs a **Dynamic Behavioral Inspection** engine to stop attacks without false positives.\n\n### The Problem\n\nDNS Amplification attacks involve spoofed IPs flooding a resolver with queries for a single, specific domain to generate large response packets.\n\n### The Solution\n\nnx53 uses a multi-stage **Defense Pipeline** to filter traffic:\n\n1.  **Static Filtering:** Immediately drops specific query types (e.g., `ANY`, large `TXT`, `AXFR`) known for amplification.\n2.  **Response Rate Limiting (RRL):** Caps identical responses per second with configurable slip ratio.\n3.  **Reflection Pattern Detection:** Identifies attack signatures (new IP, single domain, high rate) in real-time.\n4.  **Volumetric Analysis:** Continuously monitors domain confirmation levels to detect active attacks.\n5.  **Rate Limiting:** Enforces strict queries-per-second limits on new or suspicious IPs, applying graduated temporary bans for offenders.\n6.  **TCP Source Validation:** IPs proven via TCP handshake bypass reflection checks (can't spoof TCP).\n7.  **Amplification Ratio Monitoring:** Blocks IPs when response/query ratio exceeds threshold.\n8.  **Subdomain Entropy Detection:** Detects random subdomain attacks using Shannon entropy analysis.\n9.  **The \"First-Packet\" Rule:** If a **new** IP's very first query is for a flagged \"High-Volume\" domain, it is immediately marked as hostile and blocked.\n10. **The \"Escape Hatch\" (Legitimacy Validation):** If an IP queries a _different_ domain (one not under attack), it is re-classified as a legitimate user and whitelisted.\n11. **Auto-Whitelisting:** IPs that maintain a clean reputation for N days (default: 7) are automatically trusted.\n\n### Defense Pipeline Flowchart\n\n```mermaid\nflowchart TD\n    START([DNS Query Received]) --\u003e A{Query Type Check}\n    A --\u003e|ANY/AXFR/IXFR| BLOCK[🚫 BLOCK]\n    A --\u003e|Large TXT| BLOCK\n    A --\u003e|Allowed Type| B{Response Rate Limit}\n\n    B --\u003e|Exceeded + No Slip| BLOCK\n    B --\u003e|OK or Slip| C{Reflection Pattern?}\n\n    C --\u003e|New IP + 1 Domain + High Rate| BLOCK\n    C --\u003e|No Pattern| D{IP Banned?}\n\n    D --\u003e|Yes, Not Expired| BLOCK\n    D --\u003e|No or Expired| E{Subdomain Entropy}\n\n    E --\u003e|High Entropy + Many Subdomains| BLOCK\n    E --\u003e|Normal| F{TCP Validated?}\n\n    F --\u003e|Yes| TRUST[✅ ALLOW - Trusted]\n    F --\u003e|No| G{Rate Limit Check}\n\n    G --\u003e|Exceeded| BAN[🚫 TEMP BAN]\n    G --\u003e|OK| H{Already Whitelisted?}\n\n    H --\u003e|Yes| ALLOW[✅ ALLOW]\n    H --\u003e|No| I{High-Volume Domain?}\n\n    I --\u003e|Yes + First Packet| BLOCK\n    I --\u003e|No| J{Escape Hatch?}\n\n    J --\u003e|Different Safe Domain| WHITELIST[✅ WHITELIST]\n    J --\u003e|Same Domain| K{Auto-Whitelist Age?}\n\n    K --\u003e|Clean for N Days| WHITELIST\n    K --\u003e|Too New| ALLOW\n\n    style BLOCK fill:#ff6b6b,color:#fff\n    style BAN fill:#ff6b6b,color:#fff\n    style ALLOW fill:#51cf66,color:#fff\n    style TRUST fill:#51cf66,color:#fff\n    style WHITELIST fill:#51cf66,color:#fff\n    style START fill:#339af0,color:#fff\n```\n\n---\n\n## ⚙️ CLI Specification\n\nThe software is controlled via a standard Command Line Interface.\n\n| Command        | Arguments                 | Description                                                                         |\n| :------------- | :------------------------ | :---------------------------------------------------------------------------------- |\n| `nx53 block`   | `\u003cip/domain\u003e`             | Adds a static rule to drop all packets from an IP or specific domain queries.       |\n| `nx53 allow`   | `\u003cip/domain\u003e`             | Adds a static rule to whitelist an IP or domain (bypasses all checks).              |\n| `nx53 toggle`  | `intelligent` \\| `manual` | Toggles the active status of the heuristic engine or manual rulesets independently. |\n| `nx53 stats`   | `[--json]`                | Displays real-time telemetry: attack counts, dropped IPs, and resource usage.       |\n| `nx53 flush`   | `all` \\| `banned`         | Clears nftables rules managed by nx53.                                              |\n| `nx53 update`  | N/A                       | Updates nx53 to the latest version from GitHub.                                     |\n| `nx53 version` | N/A                       | Displays the current version.                                                       |\n\n---\n\n## 💻 Tech Stack\n\n- **Language:** [Rust](https://www.rust-lang.org/)\n- **Packet Capture:** `pcap` / `af_packet`\n- **Concurrency:** `Tokio` / `DashMap` for efficient state management.\n- **Firewall:** `nftables` / Linux Netfilter\n\n---\n\n## ⚠️ Disclaimer\n\n- **Root Privileges:** nx53 requires root access to manage network interfaces and firewall rules.\n- **Compatibility:** Designed primarily for **Debian-based Linux** systems.\n- **Use Responsibly:** This tool modifies kernel networking rules. Ensure you have out-of-band access to your server (e.g., VNC/Console) before deploying in production.\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! To ensure changes are processed quickly and correctly, please review our **[Contributing Guidelines](https://github.com/hapara-fail/nx53/blob/main/CONTRIBUTING.md)** before submitting.\n\nIf you have ideas for improvements, new tools, bug fixes, or blog post topics, please feel free to:\n\n- **Open an Issue** on GitHub using our standardized templates.\n- **Submit a Pull Request** with your proposed changes.\n- Join our [Discord server](https://www.hapara.fail/discord) to discuss.\n\nYou can also find donation options [here](https://hapara.fail/contribute).\n\n---\n\n## 📄 License\n\nThis project is licensed under the terms specified at [www.hapara.fail/license](https://www.hapara.fail/license).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhapara-fail%2Fnx53","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhapara-fail%2Fnx53","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhapara-fail%2Fnx53/lists"}