https://github.com/pilosus/dnseen
simple DNS queries analyzer that works on top of the tcpdump logs
https://github.com/pilosus/dnseen
dns hosts privacy stats
Last synced: over 1 year ago
JSON representation
simple DNS queries analyzer that works on top of the tcpdump logs
- Host: GitHub
- URL: https://github.com/pilosus/dnseen
- Owner: pilosus
- License: other
- Created: 2023-12-28T16:22:28.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-01-10T13:50:56.000Z (over 2 years ago)
- Last Synced: 2025-02-01T16:48:28.863Z (over 1 year ago)
- Topics: dns, hosts, privacy, stats
- Language: Clojure
- Homepage: https://blog.pilosus.org/posts/2023/12/29/dnseen-simple-dns-queries-analyzer/
- Size: 64.5 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# dnseen - DNS queries analyzer
`dnseen` is a simple DNS queries analyzer that works on top of the `tcpdump` logs.
- Simple: no GUI/TUI, no modes, easy command-line interface
- Stands on the shoulders of giants: used `tcpdump` and `systemd` at
its core
- Separation of concerns: logs and a stats report produced by
different components and can be used independently
- Filtering: select a datetime range, filter out domains with regex,
filter by domain hits, etc.
```
$ dnseen
| :domain | :hits | :blocked |
|-------------------------------------+-------+----------|
| profile.accounts.firefox.com | 831 | false |
| github.com | 531 | false |
| www.google.com | 351 | false |
| alive.github.com | 332 | false |
| api.github.com | 331 | false |
| www.youtube.com | 326 | false |
| slack.com | 260 | false |
| app.slack.com | 246 | false |
| slackb.com | 232 | false |
| clojurians.slack.com | 230 | false |
...
```
## Install
### Dependencies
`dnseen` requires the following dependencies:
- Linux OS
- `tcpdump`
- [babashka](https://github.com/babashka/babashka#installation)
- (optionally) `logrotate`
### Installer script
Install `dnseen` with the installer script on Linux:
```shell
curl -sLO https://raw.githubusercontent.com/pilosus/dnseen/master/install
chmod +x install
./install
```
By default, the command will be installed in `/usr/local/bin` (you may
need to use `sudo` to run the installer script in this case!). You can
change installation directory with the option `--install-dir`:
```shell
./install --install-dir
```
To install a specific version instead of the latest one use
`--version` option:
```shell
./install --version 0.2.0
```
Installer script downloads a package archive file to a temporary
directory under `/tmp`, you can change it with the option
`--download-dir`:
```shell
./install --download-dir
```
You can uninstall `dnseen` and all its corresponding services with the
`--uninstall` option (can be used along with `--install-dir`):
```shell
./install --uninstall
```
For more options see installer script's help:
```shell
./install --help
```
### Manual install
1. Clone the repo and `cd` to it:
```shell
git clone https://github.com/pilosus/dnseen.git
cd dnseen
```
2. Copy content of the `dnseen.service` file and paste to a new
`systemd` service:
```shell
sudo -E systemctl edit dnseen --full --force
```
Alternatively, simply copy the service file:
```shell
sudo cp dnseen.service /etc/systemd/system/
```
3. Reload `systemd`, start the service, enable it to start
automatically on system boot, and make sure it works:
```shell
sudo systemctl daemon-reload
sudo systemctl start dnseen.service
sudo systemctl enable dnseen.service
sudo systemctl status dnseen.service
```
4. (Optionally) Add `logrotate` config file to make logs rotated:
```shell
sudo cp dnseen.logrotate /etc/logrotate.d/dnseen
```
Make sure config is valid:
```shell
sudo logrotate --debug /etc/logrotate.d/dnseen
```
If needed, force rotation and restart the service:
```shell
sudo logrotate --force /etc/logrotate.d/dnseen
sudo systemctl restart dnseen.service
```
## Use
Basic usage takes the whole log and prints the report without any
filters applied, domains ordered by number of hits in descending
order:
```shell
dnseen
```
when invoking command that is not under your `$PATH` (e.g. if you
followed the manual installation guide), use:
```shell
./dnseen
```
Apply some filters if needed:
```shell
dnseen \
--from "2023-12-01T00:00:00" \
--to "2024-01-01T00:00:00" \
--match '\.(goog|google)$' \
--exclude '(?i).*domains\.' \
--hosts '/etc/hosts' \
--hits 10 \
--head 20 \
--no-pretty \
-vvv
```
A path to a file or a directory containing [hosts
file](https://man7.org/linux/man-pages/man5/hosts.5.html) can be
provided to get statistics about blocked domains, i.e. domains that
resolve to either [localhost](https://en.wikipedia.org/wiki/Localhost)
or [0.0.0.0](https://en.wikipedia.org/wiki/0.0.0.0). Use `--totals`
flag to get aggregation statistics of the report itself:
```shell
dnseen \
--hosts '/etc/hosts.d/' \
--hosts '/etc/hosts.old' \
--totals
```
Configuration parameters can also be defined in a
[EDN](https://github.com/edn-format/edn) config file. A default path
to the config file is either `$XDG_CONFIG_HOME/dnseen/config.edn` or
`$HOME/.config/dnseen/config.edn`. It can be overriden with the
`--config` option:
```shell
dnseen --config ~/.dnseen
```
Get more help with:
```shell
dnseen --help
```
Filters are applied to the raw logs in the order the corresponding CLI
options are shown in the help message (e.g. `--match` is applied
before `--exclude`).