Route 3: observe what your TV talks to
Goal: replace guesses with observations. Record everything the TV resolves, then classify it.
- Set up AdGuard Home (route 2, option A) or Pi-hole (option B) and point only the TV at it.
- Use the TV normally for a day or two: home screen, YouTube, Netflix, settings.
-
Get the query log. AdGuard Home: export from the web UI, or use
scripts/fetch_query_log.py, which pulls it from the/control/querylogAPI of your own AdGuard Home. Pi-hole: copy/etc/pihole/pihole-FTL.dbto your working directory (copy, never move: Pi-hole keeps writing to the original) and classify the copy; the classifier opens it read-only.Credential and data hygiene:
- Never put the password on the command line (it lands in your shell
history), in a chat, or in any file you might commit. The script asks
for it without echo, or reads
ADGUARD_PASSWORDfrom the environment of that one command. - Run it only against your own AdGuard Home on your own network. The script refuses HTTP redirects so your credentials cannot be forwarded to a different address. Prefer HTTPS if your AdGuard Home has it.
- The exported
querylog.jsonis a record of what your TV looked up: treat it as private browsing data. Keep it local and never commit it (it is covered by.gitignorealong with.env). One page holds 500 entries by default; a day or two of TV traffic is often more.--pages Nkeeps fetching older pages until the log runs out (max 100 pages). If the export stops on a full page, the script warns that older entries may remain; raise N until the warning disappears.
- Never put the password on the command line (it lands in your shell
history), in a chat, or in any file you might commit. The script asks
for it without echo, or reads
- Run
scripts/classify_dns_log.pyon the export. It aggregates domains, marks which are already covered by the upstream blocklist, and prints candidate rules for the rest. - Add candidates one functional group at a time, test after each group, keep what breaks nothing. Log everything in TESTING.md.
Never add a domain you have not observed your own TV resolve.
Catching startup and input-switch ads
Owners also report full-screen ads at power-on or when switching inputs.
To find the domains behind them instead of guessing: note the exact time,
cold-boot the TV or switch inputs once, then export the query log and
search the raw entries in the seconds around that moment. --timeline 1
narrows the search to the one-minute bucket that spikes, but buckets only
carry counts - the domains come from the log itself. Cross-check each
candidate against the classified table: a domain that appears only in the
seconds around the ad is a candidate; one that also serves artwork or
search shows up in normal browsing too, which is how you avoid breaking
the home screen.
python3 scripts/fetch_query_log.py --host http://192.0.2.10:3000 \
--user admin --pages 10 -o querylog.json
python3 scripts/classify_dns_log.py querylog.json \
--client 192.0.2.50 \
--blocklist Blocked_Domains.txt \
--min-count 3 --rules
# Pi-hole: same command on a copy of the FTL database
python3 scripts/classify_dns_log.py pihole-FTL.db \
--client 192.0.2.50 \
--blocklist Blocked_Domains.txt \
--min-count 3 --rules
To see when the TV is most active, run a separate command with --timeline (bucket size in minutes,
default 60). It prints per-bucket counts split into filtered and unblocked:
python3 scripts/classify_dns_log.py querylog.json --client 192.0.2.50 --timeline
Timestamps exist in AdGuard Home JSON exports and in Pi-hole FTL databases; dnsmasq logs and plain domain lists cannot produce a timeline. A timeline shows request volume over time - for example whether queries spike right after you unblock a domain. Volume says nothing about what data was sent, so use it to decide when to look closer, not to draw conclusions about content.
Supported comparison lists
The offline classifier compares plain hostnames (exact name only) and
unconditional ||hostname^ rules (the name and its subdomains), following
AdGuard DNS rule scope.
It is not an AdGuard filtering engine:
options (such as client conditions), exceptions, wildcards, hosts-file lines
and regex filters are rejected with a line number instead of being silently
misreported as coverage. Use a separate supported-syntax list for comparison;
do not strip conditions or exceptions from a real filter to make it pass.
The standalone validator also rejects wildcard rules, including in an
--upstream file: it cannot certify wildcard redundancy or coverage. This is
an intentional restriction of these offline tools, not a claim that AdGuard
rejects wildcard syntax. Do not remove active wildcard rules from a real
filter just to make validation pass.
Find the client identifier first
Not sure which identifier to use with --client? List the clients present in
an export without making a network request:
python3 scripts/classify_dns_log.py querylog.json --clients
The table shows each identifier, query count and count marked filtered in the
log. Identifiers have a literal client: prefix and a JSON-quoted value so
unusual characters cannot break the table or become spreadsheet formulas;
for normal IP addresses, copy the address inside the quotes to --client
(not the quotes themselves). A label with escaped control characters is not
a normal IP address; inspect your export before using it as a filter.
<unknown> means the input had no client identifier; plain domain files cannot
identify a TV. Check the TV’s network settings or your router to choose the
right client. This command cannot prove which physical device owns an address.
Counts include only supported, valid query records, not malformed entries.
Keep the inventory private just like the log. --clients is a separate mode,
not combined with client filters, blocklist comparisons, rules or timelines.
Choose one output mode
| Output | Options you can combine |
|---|---|
| Domain table (default) | --client, --blocklist, --min-count N |
Candidate rules (--rules) |
--client, --blocklist, --min-count N |
Timeline (--timeline [MINUTES]) |
--client only |
Client inventory (--clients) |
No other filtering or output options |
--min-count is a domain-query threshold, not a timeline-bucket or client
threshold. It must be at least 1; its default is 1 for tables and rules.
Timeline minutes must also be at least 1. Conflicting options are rejected
before the log or comparison list is read, with an error on stderr and exit
code 2. No partial table or rules are printed. Run separate commands when you
need both rules and a timeline; options are never silently ignored.