If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/felixonmars/dnsmasq-china-list shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Solo project — review before adopting

• Last commit today
• Other licensed
• CI configured
• Tests present
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live felixonmars/dnsmasq-china-list repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/felixonmars/dnsmasq-china-list.

What it runs against: a local clone of felixonmars/dnsmasq-china-list — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in felixonmars/dnsmasq-china-list | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of felixonmars/dnsmasq-china-list. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/felixonmars/dnsmasq-china-list.git
#   cd dnsmasq-china-list
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of felixonmars/dnsmasq-china-list and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "felixonmars/dnsmasq-china-list(\\.git)?\\b" \\
  && ok "origin remote is felixonmars/dnsmasq-china-list" \\
  || miss "origin remote is not felixonmars/dnsmasq-china-list (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "accelerated-domains.china.conf" \\
  && ok "accelerated-domains.china.conf" \\
  || miss "missing critical file: accelerated-domains.china.conf"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f "updater.rb" \\
  && ok "updater.rb" \\
  || miss "missing critical file: updater.rb"
test -f "verify.rb" \\
  && ok "verify.rb" \\
  || miss "missing critical file: verify.rb"
test -f "dnsmasq-update-china-list" \\
  && ok "dnsmasq-update-china-list" \\
  || miss "missing critical file: dnsmasq-update-china-list"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/felixonmars/dnsmasq-china-list"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

This repository generates dnsmasq configuration files that optimize DNS resolution for Chinese domains by routing them to Chinese nameservers and CDN nodes. It maintains curated lists in accelerated-domains.china.conf, google.china.conf, apple.china.conf, and bogus-nxdomain.china.conf that tell dnsmasq which domains to resolve via Chinese DNS servers (like 202.96.128.86) to improve speed and ensure users hit the nearest CDN node. Single-module architecture: domain lists are stored as .conf files in the root (accelerated-domains.china.conf, google.china.conf, etc.), build logic lives in Makefile and Ruby scripts (autoupdater.rb, updater.rb, verify.rb, find_redundant.rb), and installation is handled by shell (install.sh, dnsmasq-update-china-list). Test suite validates redundancy and correctness in test/redundant.rb.

Chinese internet users and network administrators who run dnsmasq on their routers, NAS devices, or Linux servers and want faster DNS resolution for Chinese domains without compromising foreign CDN performance. Contributors are maintainers curating domain lists and improving the build/deployment infrastructure.

This is a production-ready, actively maintained project with 5.6K+ GitHub stars. It uses CI/CD (GitHub Actions in .github/workflows/test.yaml), has automated testing via Ruby scripts (test/redundant.rb, verify.rb), and maintains regular updates to domain lists. The codebase is stable but continuously evolving as Chinese internet infrastructure changes.

Low risk for end-users (it's configuration data, not executable code), but high maintenance burden: the domain lists must be kept current as ISPs and CDNs change, making it vulnerable to becoming stale if the single maintainer (felixonmars) becomes unavailable. Dependencies are minimal (Ruby for build tooling only), but the correctness of domain lists directly impacts user experience — incorrect entries cause routing failures.

The repository is actively maintained with regular updates to domain lists driven by community contributions and ISP changes. GitHub Actions CI runs tests on updates. The tooling supports generating configurations for multiple DNS server types (dnsmasq, unbound, bind) via Makefile targets, indicating ongoing support for diverse deployment scenarios.

git clone https://github.com/felixonmars/dnsmasq-china-list.git
cd dnsmasq-china-list
wget https://raw.githubusercontent.com/felixonmars/dnsmasq-china-list/master/install.sh
sudo ./install.sh

For development, install Ruby dependencies: bundle install (uses gems.rb).

Daily commands: For end-users: sudo ./install.sh installs and configures dnsmasq. For development/maintenance: make test runs validation, make dnsmasq SERVER=202.96.128.86 generates dnsmasq config, make unbound or make bind generate configs for other DNS servers (see Makefile). Ruby scripts in root validate and deduplicate domain lists.

• accelerated-domains.china.conf — Core dataset of Chinese domains eligible for acceleration; the primary output that users consume to configure dnsmasq.
• Makefile — Build orchestration that generates all .conf files from source data; entry point for the entire pipeline.
• updater.rb — Fetches and processes domain lists from authoritative sources; critical for data freshness and accuracy.
• verify.rb — Validation script ensuring domain eligibility criteria are met and output quality; prevents bad data from reaching users.
• dnsmasq-update-china-list — Installation and update script for end-users; the primary integration point into dnsmasq configurations.
• .github/workflows/test.yaml — CI/CD pipeline that validates all changes before merge; ensures data integrity across releases.

• updater.rb (Ruby, HTTP clients, text parsing) — Fetch domain lists from external sources (registry APIs, public datasets) and apply initial filtering
  • Failure mode: External source unavailable → build fails; data becomes stale if not re-run; corrupted lists propagate
• verify.rb (Ruby, DNS queries (optional), regex matching) — Validate that each domain meets China-specific acceleration criteria (NS location or China-only resolution)
  • Failure mode: Incorrect validation logic → false positives (non-Chinese domains added) or false negatives (valid domains excluded)
• Makefile (Make, shell commands) — Orchestrate the entire generation pipeline and coordinate between updater, verify, and output generation
  • Failure mode: Missing dependencies in Makefile → incomplete or outdated configs; race conditions if parallel execution misconfigured
• dnsmasq-update-china-list (Shell script, wget/curl, file system operations) — Download latest configs and update user's local dnsmasq installation with new domain lists
  • Failure mode: Network failure → update not downloaded; filesystem error → dnsmasq left in broken state; permission issues → silent failure
• Generated .conf files — Provide dnsmasq-compatible configuration directives routing Chinese domains to appropriate nameservers

Add a new domain to the accelerated list

1. Verify the domain meets criteria: NS server in China mainland OR resolves to China IP via Chinese DNS only (README.md)
2. Add domain to the appropriate source list or modify updater.rb if automating from external sources (updater.rb)
3. Run 'make' to regenerate accelerated-domains.china.conf with the new entry (Makefile)
4. Run verify.rb to validate the domain entry meets all criteria (verify.rb)
5. Check for and remove any redundant subdomains using find_redundant.rb (find_redundant.rb)

Add a new specialized domain configuration

1. Create a new .china.conf file (e.g., facebook.china.conf) following the naming pattern (google.china.conf)
2. Populate with domains specific to that service, using the same dnsmasq format (apple.china.conf)
3. Update updater.rb if the list should be auto-generated from an external source (updater.rb)
4. Add corresponding test rules in .github/workflows/test.yaml to validate the new config (.github/workflows/test.yaml)

Update domain lists from external sources

1. Identify the authoritative source for the domain list (e.g., registry API, public dataset) (updater.rb)
2. Add or modify the fetch logic in updater.rb to pull the latest data (updater.rb)
3. Implement filtering logic in verify.rb to validate domains against China-specific criteria (verify.rb)
4. Run 'make' to regenerate configurations and commit the changes with changelog (Makefile)
5. Validate changes pass all checks in .github/workflows/test.yaml before pushing (.github/workflows/test.yaml)

• Ruby scripts (updater.rb, verify.rb) — Dynamic domain list processing, text parsing, and network requests for fetching external sources; Ruby's flexibility suits one-off data transformation tasks
• dnsmasq .conf format — Industry-standard configuration for the dnsmasq DNS server; directly consumable by the target application without additional compilation
• Makefile for orchestration — Declarative build pipeline ensuring reproducible generation of outputs; simple dependency tracking between source data and generated configs
• GitHub Actions (CI/CD) — Automated validation on every commit; ensures data quality before release without manual overhead

• Manual curation + automated updates from external sources

  • Why: Balances coverage (automated feeds) with accuracy (manual vetting of China-specific criteria)
  • Consequence: Requires ongoing human review; may lag behind new domains but avoids false positives that degrade user experience

• Single source of truth in .conf files (generated, not hand-edited)

  • Why: Prevents merge conflicts and inconsistencies when regenerating from updated source data
  • Consequence: Users must re-run updater to get new domains; no direct manual patching of .conf files

• Ruby for data processing rather than bash/Python

  • Why: Developer familiarity and conciseness for complex filtering logic
  • Consequence: Requires Ruby runtime; slightly heavier than pure bash but more maintainable for evolving requirements

• Does not handle DNS resolution itself — only generates configuration for dnsmasq
• Does not manage VPN routing; pairs with chnroutes as separate tool
• Does not provide real-time domain discovery — batch-updated lists only
• Does not support non-dnsmasq DNS servers (no configs for BIND, unbound, etc.)
• Does not perform CDN performance testing; relies on static criteria (NS location, geographic DNS behavior)

No hidden traps — this is a data-driven project with minimal complexity. Gotchas: (1) Domain lists are manually curated; no automated source of truth exists, so contributors must verify eligibility per the README criteria. (2) install.sh assumes /etc/dnsmasq.d/ exists and dnsmasq is running; it will fail silently if dnsmasq is not installed. (3) The Makefile uses SERVER= variable to customize target DNS — if unset, defaults may not match user's intended resolver. (4) CI tests assume Ruby + Bundler; local development requires bundle install.

• DNS server IP geolocation & CDN node selection — The core premise of dnsmasq-china-list is that querying Chinese DNS servers returns IPs for Chinese CDN nodes; understanding how CDNs distribute geographically and how DNS can influence routing is critical to evaluating whether a domain belongs in the list
• DNS NXDOMAIN hijacking & ISP ad injection — The bogus-nxdomain.china.conf file blocks ISP servers that hijack NXDOMAIN (non-existent domain) responses to inject ads; understanding NXDOMAIN and ISP DNS behavior is necessary to use this feature effectively
• Nameserver (NS) records & DNS delegation — One criterion for including a domain is 'NS server located in China mainland'; understanding NS records and how they control which authoritative server is queried is essential to verifying domain eligibility
• Dnsmasq configuration syntax & address records — All output is in dnsmasq .conf format with address= directives; contributors must understand dnsmasq's address-rewriting syntax to modify or generate configs correctly
• DNS resolver caching & TTL — The lists work because dnsmasq caches DNS responses; understanding TTL (time-to-live) and resolver caching is important to know why stale domain lists can cause issues and why frequent updates matter
• Domain list deduplication & redundancy detection — Scripts like find_redundant.rb and verify.rb detect when one domain is a subdomain of another already in the list; understanding domain hierarchy and wildcard matching is necessary to maintain list quality
• Great Firewall (GFW) & Chinese internet infrastructure — The project's entire motivation stems from how GFW and ISP routing affect DNS and CDN performance in mainland China; understanding China's internet censorship and infrastructure is context for why these lists exist

• yangchuansheng/love-gfw — Similar DNS configuration lists for GFW circumvention and Chinese domain optimization; complementary approach to dnsmasq-china-list
• 18612392945/chnroutes — Referenced in README as 'best partner'; generates routing rules for Chinese IPs to use domestic connections, works alongside dnsmasq-china-list for complete optimization
• felixonmars/archlabs — Same maintainer's broader toolkit; may share domain data sources and validation patterns with dnsmasq-china-list
• dnsmasq/dnsmasq — The upstream DNS server software; understanding dnsmasq's conf syntax and features is essential to using this project correctly
• ilanyu/ReverseProxy — Alternative approach using reverse proxy instead of DNS for Chinese domain acceleration; represents competing strategy in same problem space

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for domain list validation in test/redundant.rb

The repo has test/redundant.rb for finding redundant entries, but lacks comprehensive test coverage for the core validation logic. Currently, there's no automated test suite that validates the generated .conf files (accelerated-domains.china.conf, apple.china.conf, google.china.conf, bogus-nxdomain.china.conf) against dnsmasq syntax requirements or checks for duplicate entries, invalid domains, or malformed DNS server addresses. This would catch regressions early and ensure domain list quality.

• [ ] Extend test/redundant.rb to include tests for dnsmasq config syntax validation
• [ ] Add test cases for detecting duplicate domains across all .conf files
• [ ] Add test cases for validating DNS server IPs in each config file
• [ ] Integrate these tests into .github/workflows/test.yaml to run on each commit

Implement CI workflow for automated domain list freshness checks

The repo has autoupdater.rb and updater.rb scripts but no automated GitHub Actions workflow to verify that domain lists haven't gone stale. The repository should have a scheduled workflow (e.g., weekly) that runs these update scripts and alerts maintainers if upstream sources have changed significantly, ensuring the lists stay current. The .github/workflows/test.yaml exists but only runs on push/PR—a separate scheduled workflow for freshness validation is missing.

• [ ] Create .github/workflows/update-check.yaml with a schedule trigger (e.g., weekly)
• [ ] Add logic to run updater.rb and autoupdater.rb and compare diffs against current tracked files
• [ ] Configure the workflow to create a GitHub issue if significant changes are detected
• [ ] Document the freshness check process in README.md under a new 'Maintenance' section

Add documentation for maintenance scripts (updater.rb, autoupdater.rb, find_redundant.rb, verify.rb)

The repo contains multiple Ruby scripts (updater.rb, autoupdater.rb, find_redundant.rb, verify.rb, and gems.rb for dependencies) but README.md lacks any guidance on how to run, configure, or understand these scripts. New contributors cannot easily understand the update workflow, how to verify list integrity, or how to identify redundant entries. This documentation gap makes contributing harder and causes duplicated work.

• [ ] Add 'Development & Maintenance' section to README.md documenting each .rb script's purpose
• [ ] Document how to run updater.rb and autoupdater.rb with example commands and expected outputs
• [ ] Explain find_redundant.rb usage and how to interpret its results
• [ ] Document the gems.rb dependencies and how to set up the Ruby environment (bundle install)
• [ ] Add instructions for running verify.rb to validate generated config files locally

• Add test coverage for autoupdater.rb: Currently test/redundant.rb only validates redundancy; autoupdater.rb which fetches lists from external sources has no tests. Write specs to verify it correctly parses and deduplicates input.
• Document domain eligibility criteria with examples: The README explains the rules for including domains (NS in China OR CDN node in China) but lacks concrete examples. Add 5-10 specific domain case studies (e.g., 'baidu.com is included because...') to README.md.
• Create a validation script for user-submitted domains: Users contributing new domains should be able to run ruby validate_domain.rb example.com locally to check eligibility before opening a PR. Currently only verify.rb exists and runs globally.

This DNS configuration repository has moderate security posture. Primary concerns involve secure handling of remote script execution, unvetted Ruby dependencies, and validation of dynamically fetched configuration data. The project lacks visible security scanning in CI/CD pipeline and dependency lock files. No critical vulnerabilities detected based on file structure analysis, but implementation details in shell and Ruby scripts require closer review. Recommendations focus on signature verification, dependency pinning, and input validation.

• Medium · Insecure Script Execution in Shell Script — install.sh, dnsmasq-update-china-list. The file 'install.sh' and 'dnsmasq-update-china-list' are shell scripts that download and execute code. If these scripts use curl/wget without HTTPS verification or signature validation, they could be vulnerable to MITM attacks. Fix: Ensure all remote downloads use HTTPS with certificate verification. Implement GPG signature verification for downloaded files. Use checksums to verify file integrity.
• Medium · Unvetted Ruby Dependencies — gems.rb, autoupdater.rb, updater.rb, find_redundant.rb, verify.rb. The project uses 'gems.rb' for Ruby dependencies (used in autoupdater.rb, find_redundant.rb, verify.rb, updater.rb). Without seeing the contents, there's risk of vulnerable gem dependencies. Ruby projects often lack pinned versions. Fix: Use Gemfile.lock to pin exact versions of all dependencies. Regularly run 'bundle audit' to scan for known vulnerabilities. Specify minimum Ruby version compatibility.
• Medium · Dynamic Configuration from External Sources — updater.rb, autoupdater.rb. The updater scripts (updater.rb, autoupdater.rb) appear to fetch and process DNS configuration files from external sources. Without proper validation and sanitization, malicious configuration could be injected. Fix: Implement strict validation of downloaded configuration files. Use schema validation (YAML/JSON schema). Verify signatures of configuration sources. Implement rate limiting and timeout controls.
• Low · Missing Input Validation in Test Scripts — test/redundant.rb, find_redundant.rb, verify.rb. Test and utility scripts (test/redundant.rb, find_redundant.rb, verify.rb) may process untrusted input without proper validation, potentially leading to code injection or unexpected behavior. Fix: Add strict input validation and sanitization. Use safe Ruby methods (avoid eval, system calls with user input). Implement proper error handling.
• Low · Lack of Access Controls Documentation — install.sh, dnsmasq-update-china-list. No evidence of RBAC, authentication, or authorization controls documented. Installation and update scripts may execute with elevated privileges without proper safeguards. Fix: Document required privileges clearly. Implement principle of least privilege. Add user/permission checks in installation scripts. Use capability-based security where applicable.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.