Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/st3v3nmw/beacon-dns
A DNS resolver with customizable & schedulable filtering for malware, trackers, ads, and other unwanted content
https://github.com/st3v3nmw/beacon-dns
ad-blocker adblock beacon-dns dns dns-cache dns-resolver dns-server golang parental-control self-hosted
Last synced: 14 days ago
JSON representation
A DNS resolver with customizable & schedulable filtering for malware, trackers, ads, and other unwanted content
- Host: GitHub
- URL: https://github.com/st3v3nmw/beacon-dns
- Owner: st3v3nmw
- License: mit
- Created: 2024-08-18T11:30:11.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2024-12-22T19:52:48.000Z (17 days ago)
- Last Synced: 2024-12-22T20:31:41.696Z (17 days ago)
- Topics: ad-blocker, adblock, beacon-dns, dns, dns-cache, dns-resolver, dns-server, golang, parental-control, self-hosted
- Language: Go
- Homepage: https://www.beacondns.org
- Size: 184 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Beacon DNS
Runs on a single vCPU, a small hill of RAM, and pure determination.
A DNS resolver with customizable & schedulable filtering for malware, trackers, ads, and other unwanted content.
## Features
### Blocking
Supports blocking of ads, malware, adult content, dating & social media sites, video streaming platforms, and [other content](https://github.com/st3v3nmw/beacon-dns/blob/main/internal/config/sources.go).
Blocking can be done network-wide or per device group:
```yaml
groups:
# not specifying devices blocks on the entire network
all:
block:
- ads
- malware
- adult
screens:
devices:
- phone
- laptop
- tv
```
Blocking can also be scheduled so that certain content is only blocked at certain times:
```yaml
schedules:
bedtime:
apply_to:
- screens
when:
- days: ["sun", "mon", "tue", "wed", "thur", "fri", "sat"]
periods:
- start: "22:00"
end: "06:00"
block:
- social-media
- video-streaming
- gaming
- dating
```
For now, rDNS queries for private IP ranges that reach the resolver are always blocked.
### Caching
Supports caching of DNS records for up to the record's TTL. This can then be served to other devices in the network thus speeding up DNS lookups.
But, DNS records on the internet use [ridicuously low TTLs](https://blog.apnic.net/2019/11/12/stop-using-ridiculously-low-dns-ttls/). The resolver can be configured to serve stale DNS records while it refreshes/prefetches the record in the background.
Beacon DNS also "learns" your query patterns to prefetch subsequent queries before the device makes them. For instance, when `github.com` is queried, `avatars.githubusercontent.com` & `github.githubassets.com` usually follow. So when the resolver sees `github.com`, it can prefetch the next two before the device queries for them.
```yaml
cache:
capacity: 1000
serve_stale:
for: 5m
with_ttl: 15s
query_patterns:
follow: true
look_back: 14d
```
### Client Lookup
Supports looking up of the client's hostname either using tailscale's MagicDNS:
```yaml
client_lookup:
upstream: 100.100.100.100
method: tailscale
```
Or hardcoded based on the static IPs configured on your router:
```yaml
client_lookup:
clients:
192.168.0.102: laptop
192.168.0.103: phone
```
### Statistics
Beacon DNS stores your queries for a configured retention period:
```yaml
querylog:
enabled: true
log_clients: true
retention: 90d
```
You can watch the querylog live:
```console
$ websocat ws:///api/watch\?clients=phone
{"hostname":"phone","ip":"","domain":"spclient.wg.spotify.com","query_type":"A","cached":false,"blocked":false,"block_reason":null,"upstream":"1.1.1.1","response_code":"NOERROR","response_time":1,"prefetched":false,"timestamp":"2024-12-09T21:06:05.067810278Z"}
{"hostname":"phone","ip":"","domain":"spclient.wg.spotify.com","query_type":"A","cached":true,"blocked":false,"block_reason":null,"upstream":null,"response_code":"NOERROR","response_time":0,"prefetched":false,"timestamp":"2024-12-09T21:06:05.08479734Z"}
```
The querylog allows us to generate statistics and compute the query patterns:
```console
$ curl -s http:///api/stats/devices?last=24h | jq
[
{
"client": "phone",
"total_queries": ,
"unique_domains": ,
"cached_queries": ,
"cache_hit_ratio": <%>,
"blocked_queries": ,
"block_ratio": <%>,
"prefetched_queries": ,
"prefetched_ratio": <%>,
"typical_response_time": ,
"typical_forwarded_response_time": ,
"min_response_time": ,
"max_response_time": ,
"query_types": {
"A": ,
"AAAA": ,
"HTTPS":
},
"block_reasons": {
"ads": ,
"gaming": ,
"social-media": ,
"video-streaming":
},
"upstreams": {
"1.1.1.1":
},
"resolved_domains": {
"apresolve.spotify.com": ,
"spclient.wg.spotify.com": ,
...
},
"blocked_domains": {
"app-measurement.com": ,
"incoming.telemetry.mozilla.org": ,
...
},
"response_codes": {
"NOERROR": ,
"NXDOMAIN": ,
"REFUSED":
},
"ips": {
"":
}
}
]
```
### TODO
- [ ] [CLI Interface](https://github.com/st3v3nmw/beaconctl)
- [ ] [Documentation website](https://www.beacondns.org/)
- [ ] Split DNS
- [ ] DHCP Support
- [ ] Call upstream resolvers over:
- [ ] DNS over TLS (DoT)
- [ ] DNS over HTTPS (DoH)
- [ ] Safe Search
- [ ] DNSSEC Validation
## Credits
### Logo
Logo created by Freepik - Flaticon
## Support
