Metadata-Version: 2.4
Name: rabdomancia
Version: 26.2.0
Summary: Discover with your senses what your devices are up to! A pretty and fun way to visualise DNS requests in your network
Project-URL: Changelog, https://farga.exo.cat/evilham/rabdomancia/commits/branch/main
Project-URL: Documentation, https://farga.exo.cat/evilham/rabdomancia/
Project-URL: Homepage, https://farga.exo.cat/evilham/rabdomancia/
Project-URL: Issues, https://farga.exo.cat/evilham/rabdomancia/issues
Project-URL: Source, https://farga.exo.cat/evilham/rabdomancia/
Author-email: Evilham <cvs@evilham.com>
License: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11.0
Requires-Dist: attrs>=25.4.0
Requires-Dist: fstrm>=0.6.0
Requires-Dist: incremental>=22.10.0
Requires-Dist: protobuf>=6.0.0
Description-Content-Type: text/markdown

# Rabdomància

> **Descobreix amb els sentits el que fan els teus dispositius!**
>
> **Una manera bonica i divertida de visualitzar peticions DNS a la teva xarxa**

> *Discover with your senses what your devices are up to!*
>
> *A pretty and fun way to visualise DNS requests in your network*

## About the sound concept

> Bells indicate regular web and string plucks indicate big tech.
> Pitch changes according to the frequency of the visits;
> the more frequent visit, the deeper the note.
>
> You may see announcements for new users as they join, punctuated by a string
> swell.

If this sounds awfully familiar, it is because we use the exact same algorithm
and sounds as [Hatnote's Listen to Wikipedia](http://listen.hatnote.com/).

## Setting things up

> This documentation can be improved, relies on a lot of invisible knowledge,
> and can certainly be more friendly to people who are learning networking.
>
> If that is you, and you are willing to help improve the documentation,
> please reach out, you may learn a lot (you don't have to be alone!), have a
> blast, and while at it, the next person who tries to use this will have a
> much easier time.

You'll need a device which has one upstream WAN interface (where the internet
will come from), and at least another local interface.

> Ideally one of the local interfaces is wireless in nature, or if it is wired,
> you set up an access point that **does not perform DHCP or masquerading**.

The device will act as the Access Point, gateway and DNS resolver, and will
have a private subnet that is masqueraded to the WAN port.

All of this is done with standard OS tooling (Debian is used as an example),
it's not too difficult if you are familiar with the terms and tools, but might
be a bit daunting otherwise:

- We may need to
  [bridge LAN and Wireless interfaces](https://wiki.debian.org/%20BridgeNetworkConnections%20#Configuring_bridging_in_.2Fetc.2Fnetwork.2Finterfaces):
  - we use interface `br0`
- Configure a [DHCP server](https://wiki.debian.org/DHCP_Server):
  - we use the subnet `10.42.42.1/24` on `br0`
- Configure masquerading on WAN port:
  - we call the WAN port `eth0`
- Configure the DNS resolver:
  - we may use unbound
  - any [dnstap](https://dnstap.info/)-enabled resolver will do

If your routing device has graphics and sound cards, you can plug in a screen
and speakers, and run `rabdomancia` on it.

Otherwise, you'll have to run `rabdomancia` on a different machine which does
support graphics and sound, and transport in real-time the data from the DNS
resolver.

## Running `rabdomancia`

### Getting data from the DNS resolver

The easiest way to do this is to use a network socket(!) on unbound this is
done with:

```yaml
server:
  interface: lo
  interface: br0
  interface-action: br0 allow
  interface-action: lo allow

dnstap:
  dnstap-enable: yes
  # Where 10.42.42.2 is your graphics+sound device
  # If the machines are the same, use 10.42.42.1
  dnstap-ip: 10.42.42.2@5342
  dnstap-tls: no
  dnstap-sample-rate: 1
  dnstap-log-client-query-messages: yes
```

### Start `rabdomancia`

See `rabdomancia --help` for all possible inputs.

By default `rabdomancia` will listen on port `5342` for DNSTAP connections.
Make sure you limit where this connections come from by using your firewall.


## Orígen del projecte

### Idea original

> [Dowse](https://dyne.org/dowse/) de [Dyne.org](https://dyne.org)

Sembla que el projecte original era molt més, però a nosaltres només ens
interessava la part de la visualització.

La idea de reutilitzar l'arbre de fitxers que necessita
[gource](https://gource.io/) és super bona, i la hem volgut portar una mica
més enllà.

### Anàlisi de viabilitat per nosaltres

D'entrada intentem fer servir Dowse, amb els repositoris i codi originals.

Després d'invertir-hi cert temps sense que funcioni, ens posem en contacte
amb [la comunitat de Dowse](https://dyne.org/dowse/community/).

Finalment abans no ens contestin aconseguim fer anar Dowse i comencem a
iterar, trobant-nos-hi limitacions, punts de millora, i afegint-hi les
nostres pròpies idees:

- [X] Documentar tot el procés
- [X] Afegir so
- [X] Actualitzar llistes de dominis d'entitats, sense que hagi de ser un esforç específic d'aquest projecte
- [X] Treballar les llistes, de forma que afegim "pseudo" jerarquies (`BigTech` i `MidTech`)
- [X] Usar DNSTAP en comptes d'un resolver amb pedaços

Tot plegat ho documentem en un
[anàlisi/report](https://pad.exo.cat/code/#/2/code/view/LG69jQlUrEis5LGydPgagoIFoI6wIAfR6n46+espz0I/embed/)
que enviem a la comunitat per si ho volen reutilitzar; i mencionant que hi
podríem contribuir.

Lis desenvolupadiris ens diuen:

> rather than fixing the software for all generic cases, the best route is to try the specific installation and hack a bit on it to smooth the edges
>
> embrace the way of the patch

Així que entenem que si volem mantenir els pedaços, ho fem nosaltres mateixis.
Cap problema!

En trobar-nos amb algunes limitacions, i havent reimplementat algunes coses,
decidim deixar estar totalment el codi original de Dowse.

### El nom: rabdomància

La versió curta és que és una manera d'anomenar "dowse" (anglès) en català.

<details><summary>Per què rabdomància?</summary>

> **[rabdomància](https://dlc.iec.cat/Results?DecEntradaText=rabdom%C3%A0ncia)**
>
> f. [LC] Radioestèsia 2 .

> **[radioestèsia](https://dlc.iec.cat/Results?DecEntradaText=radioest%C3%A8sia)**
>
> 1 f. [LC] Pretesa sensibilitat de certes persones a les radiacions emeses o absorbides pels cossos que tenen a prop.
>
> 2 f. [LC] Pràctica no científica de detecció de corrents d’aigua, de minerals, d’objectes amagats, etc., basada en la radioestèsia.


> **[dowsed; dowsing](https://www.merriam-webster.com/dictionary/dowse)**
>
> intransitive verb
> : to use a divining rod
>
> transitive verb
> : to find (something, such as water) by dowsing

</details>
