Dgaard

A suite of Rust tools for high-performance, privacy-first DNS filtering and network security. Designed for resource-constrained environments (OpenWrt, embedded routers) and SME networks alike.

---

Packages

dgaard — DNS Security Proxy (main project)

A heuristic DNS filtering proxy that goes beyond static blocklists. Instead of waiting for a threat to appear on a list, Dgaard analyses the mathematical and lexical structure of every domain in real time to detect and block malicious traffic proactively.

Key capabilities:

• DGA detection — Shannon Entropy and N-Gram models identify algorithmically generated domains (malware C2) before they appear on any blocklist.
• Stratified filtering pipeline — queries flow through a short-circuit funnel: whitelist → hot LRU cache → Bloom filter + rkyv zero-copy blocklists → heuristic engine. Each stage is orders of magnitude cheaper than the next.
• Smart-IDN / Homograph protection — decodes Punycode and blocks look-alike phishing domains.
• DNS exfiltration & rebinding protection — monitors TXT record entropy, CNAME chains, and subdomain volume; drops public queries that resolve to private IPs.
• Behavioral analytics — detects NXDOMAIN-hunting clients (botnet indicators) and DNS tunneling patterns.
• GeoIP suspicion scoring — checks each resolved IP against a local MaxMind-format MMDB database; responses from high-risk jurisdictions add weighted points to the domain's cumulative threat score, catching new malware infrastructure regardless of whether it has appeared on any blocklist.
• Custom threat-intelligence flags (requires custom_flags feature) — map up to 16 organisation-specific domain lists (AI-generated feeds, sector threat intel, proprietary sources) to named bitflags, each with its own suspicion weight; flags propagate through the telemetry stream for dashboard and SIEM correlation.
• Live telemetry — streams length-prefixed binary events over a Unix Domain Socket for real-time dashboards.
• OpenWrt-optimised — binary under 5 MB, SO_REUSEPORT multi-threading, async Tokio runtime, zero-copy parsing with rkyv.

cargo install dgaard
dgaard --config /etc/dgaard/dgaard.toml

See the dgaard README and example configuration for the full setup guide.

---

dgaard-engine — Embeddable Filtering Engine (library)

The pure-Rust filtering engine extracted from dgaard as a standalone [lib] crate. It contains the complete analysis and decision pipeline — blocklists, DGA detection, entropy/N-Gram scoring, lexical heuristics, and policy checks — with no async runtime and no networking dependencies. Any Rust application can embed it directly.

Designed for:

• MTA spam filtering — call resolve_with_score from your mail pipeline to score domains in envelope/header/body.
• HTTP proxy / web service — expose the engine as a REST endpoint without pulling in Tokio or Hyper.
• Custom tooling — integrate DNS-level threat intelligence into any Rust binary.

Key properties:

• No tokio, hyper, or rustls — sync-friendly, zero async overhead.
• All state is explicit: FilterEngine and Config are plain structs passed by reference; no global statics.
• FilterEngine carries its own seed: u64 so multiple independent instances can coexist safely.

Quick start:

# Cargo.toml
[dependencies]
dgaard-engine = { path = "../dgaard-engine" } # or version from crates.io

use dgaard_engine::{Config, FilterEngine, resolve_with_score};
use dgaard_engine::model::Action;

let config = Config::default();
let filter = FilterEngine::new(/* blocklists loaded here */);

let result = resolve_with_score("suspicious-domain.xyz", &filter, &config);
match result.action {
    Action::Block(reason) => eprintln!("Blocked: {reason:?}"),
    Action::ProxyToUpstream => println!("Clean — forward to upstream"),
    Action::LocalResolve    => println!("Answered from cache/blocklist"),
}

See the dgaard-engine README for the full API reference.

---

dgaard-monitor — Real-Time TUI Dashboard

A terminal UI that connects to dgaard's Unix Domain Socket and visualises DNS activity without adding any overhead to the proxy process. It resolves domain hashes back to human-readable names via a static mapping file, then renders live feeds, per-client traffic (Talkers), timeline charts, and top-N block statistics.

Key capabilities:

• Parses the length-prefixed binary protocol emitted by dgaard ([u16: length][u8: type][payload]).
• Watches the host-index file with inotify and hot-reloads domain mappings without restarting.
• Aggregates events into bucketed timelines with zoom cycling and gap-filling.
• Resolves client IPs to hostnames via reverse-DNS (PTR lookups) in the background.
• Linux only (relies on inotify).

cargo install dgaard-monitor

# attach to a running dgaard instance
dgaard-monitor --socket /tmp/dgaard_stats.sock --index /var/lib/dgaard/hosts.bin

See the dgaard-monitor README for the full protocol and configuration reference.

---

adblockptimize — Adblock List Optimizer

A CLI tool that ingests standard adblock lists (files or URLs) and splits them into two deduplicated, sorted outputs: one for network-level blocking (DNS, dnsmasq, Unbound, Pi-hole, AdGuard Home) and one for browser-level blocking (CSS/JS/HTML cosmetic rules). Feeding the network output directly into dgaard gives you cleaner, smaller blocklists with no browser-specific noise.

cargo install adblockptimize

# split a list into network and browser files
adblockptimize https://example.com/list.txt local-list.txt

# dnsmasq format, network rules only
adblockptimize --no-browser --format=dnsmasq https://example.com/list.txt

# custom output file names
adblockptimize --network-file=dns.txt --browser-file=ublock.txt https://example.com/list.txt

See the adblockptimize README for the full format and target compatibility table.

---

Architecture

adblockptimize          dgaard-monitor
      |                       |
      | (optimised lists)     | (Unix socket telemetry)
      v                       |
   dgaard  <-----------------/        your-app (MTA, HTTP proxy…)
(DNS proxy, port 5353)                      |
      |                                     | (library embed)
      +--------- dgaard-engine  <----------/
      |          (filtering core)
   dnsmasq / router DNS
      |
   LAN clients

adblockptimize pre-processes upstream adblock lists into compact, DNS-ready formats that dgaard can ingest. dgaard-monitor connects to dgaard's telemetry socket and provides a live view of what is happening on the network. dgaard-engine is the shared filtering library used by dgaard internally and available for embedding in any Rust application — all tools are designed to work together but can be used independently.

---

Installation

All packages are published to crates.io and can be installed with Cargo:

cargo install dgaard
cargo install dgaard-monitor   # Linux only
cargo install adblockptimize

To use dgaard-engine as a library in your own project:

[dependencies]
dgaard-engine = "0.2"

Pre-built binaries for Linux (musl), macOS, and Windows are available on the Releases page. Each package is released independently and tagged <package>-v<version>.

---

Building from source

git clone https://codeberg.org/slundi/dgaard
cd dgaard

# build all packages
cargo build --release

# build a specific package
cargo build --release -p dgaard
cargo build --release -p dgaard-engine
cargo build --release -p dgaard-monitor
cargo build --release -p adblockptimize

Cross-compilation via cross:

cargo install cross --git https://github.com/cross-rs/cross

cross build --release --target aarch64-unknown-linux-musl -p dgaard
cross build --release --target armv7-unknown-linux-musleabihf -p dgaard