{"id":34077383,"url":"https://github.com/itsamirhn/latterdns","last_synced_at":"2025-12-14T10:02:55.348Z","repository":{"id":326740737,"uuid":"1105528499","full_name":"itsamirhn/LatterDNS","owner":"itsamirhn","description":"DNS Proxy which choose latter packets to bypass GFW","archived":false,"fork":false,"pushed_at":"2025-12-06T20:29:16.000Z","size":62,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-09T04:39:52.335Z","etag":null,"topics":["anti-censorship","dns","gfw","network","proxy"],"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/itsamirhn.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-27T18:43:49.000Z","updated_at":"2025-12-06T20:29:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/itsamirhn/LatterDNS","commit_stats":null,"previous_names":["itsamirhn/latterdns"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/itsamirhn/LatterDNS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsamirhn%2FLatterDNS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsamirhn%2FLatterDNS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsamirhn%2FLatterDNS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsamirhn%2FLatterDNS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itsamirhn","download_url":"https://codeload.github.com/itsamirhn/LatterDNS/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsamirhn%2FLatterDNS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27725930,"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-12-14T02:00:11.348Z","response_time":56,"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":["anti-censorship","dns","gfw","network","proxy"],"created_at":"2025-12-14T10:02:49.746Z","updated_at":"2025-12-14T10:02:50.840Z","avatar_url":"https://github.com/itsamirhn.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LatterDNS\n\n**LatterDNS** is a lightweight, experimental DNS proxy designed to bypass DNS spoofing; a common censorship method used by the Great Firewall (GFW); by exploiting the timing difference between fake and legitimate packets.\n\n\u003e \"The truth arrives late.\"\n\nThis project is inspired by prior research on DNS censorship, especially the measurement work in [“How Great is the Great Firewall? Measuring China’s DNS Censorship” (2021)](https://arxiv.org/abs/2106.02167). That paper documents the race condition between forged and legitimate DNS packets, which this tool leverages in practice.\n\n## How It Works\n\nThis tool operates on a simple observation: **Censorship is a race.**\n\n1. **The Trigger:** When you query a blocked domain (e.g., `facebook.com`), the firewall detects the request.\n\n2. **The Race:** The firewall attempts to \"poison\" your DNS cache by racing to send you a fake response (usually a random or reset IP) before the legitimate DNS server can respond.\n\n3. **The Exploit:** Because the firewall is injecting packets locally/en route, the fake response almost always arrives **first**. The legitimate response from the real DNS server travels a longer path and arrives **second** (milliseconds later).\n\n**LatterDNS** simply discards the first response it sees for every query and accepts the second one.\n\n\n### Visualizing the Logic\n\n```mermaid\nsequenceDiagram\n    participant Client\n    participant LatterDNS\n    participant GFW\n    participant RealDNS\n\n    Client-\u003e\u003eLatterDNS: Query: facebook.com\n    LatterDNS-\u003e\u003eRealDNS: Forward Query\n    Note over GFW: GFW detects keyword!\n    GFW--\u003e\u003eLatterDNS: Fake IP (First Packet)\n    Note over LatterDNS: 🛑 BLOCKED (Too fast)\n    RealDNS--\u003e\u003eLatterDNS: Real IP (Second Packet)\n    Note over LatterDNS: ✅ ACCEPTED (The Latter)\n    LatterDNS-\u003e\u003eClient: Real IP\n```\n\n\n## Installation\n\n### Normal Usage\n\n```shell\npip install latterdns\n```\n\n### Development\n\n```shell\ngit clone https://github.com/itsamirhn/latterdns.git\ncd latterdns\nuv pip install -e .\n```\n\n\n## Usage\n\nOnce installed, you can run LatterDNS from anywhere using the `latterdns` command.\n\n```shell\n# Basic usage (defaults to listening on port 1053)\nlatterdns\n\n# Custom upstream (Google DNS) and custom timeouts\nlatterdns --upstream-host 8.8.8.8 --timeouts 150 --timeouts 600\n\n# Enable debug logging\nlatterdns --log-level DEBUG\n\n# Multiple timeout values for packet collection\nlatterdns --timeouts 50 --timeouts 200 --timeouts 500\n```\n\n**Available Options:**\n\nYou can view all options anytime by running `latterdns --help`:\n\n```\nUsage: latterdns [OPTIONS]\n\n  LatterDNS - Returns the latter DNS response packet from upstream.\n\nOptions:\n  --listen-port INTEGER           Port to listen on  [default: 1053]\n  --upstream-host TEXT            Upstream DNS host  [default: 1.1.1.1]\n  --upstream-port INTEGER         Upstream DNS port  [default: 53]\n  --timeouts INTEGER              Timeout values in milliseconds (can be\n                                  specified multiple times, e.g., --timeouts\n                                  100 --timeouts 500)  [default: 100, 500]\n  --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]\n                                  Logging level  [default: INFO]\n  --help                          Show this message and exit.\n```\n\n\n## 🧪 How to Test\n\nTo verify that LatterDNS is working, you need to query a domain known to be poisoned by the GFW.\n\n**1. Without LatterDNS (The Control Test)** Run a query against a standard upstream DNS. You should see a suspicious IP (often changed) or a connection reset.\n\n```shell\ndig @8.8.8.8 facebook.com +short\n# Result: 1.2.3.4 (Fake IP / Poisoned Result)\n```\n\n**2. With LatterDNS** Point your query to the local port where LatterDNS is running (e.g., 1053).\n\n```shell\ndig @127.0.0.1 -p 1053 facebook.com +short\n# Result: 157.240.x.x (Real Facebook IP)\n```\n\n\n## ⚠️ Limitations \u0026 Trade-offs\n\n- **Latency for Unblocked Domains:** For unblocked domains (where the GFW sends nothing), the proxy receives the legitimate packet first. It waits for the first timeout (default 100ms) to check for additional packets before returning the result. This adds latency to every query.\n\n- **Packet Loss:** If the legitimate packet (the latter one) is lost in transit, the proxy will timeout and return the last received packet (potentially the fake one), failing to bypass the block.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsamirhn%2Flatterdns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitsamirhn%2Flatterdns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsamirhn%2Flatterdns/lists"}