Skip to content
Pure Python Dnstap!
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
agents Merge branch 'fwm' Jun 16, 2019
app Merge branch 'fwm' Jun 16, 2019
examples
install
shodohflo BUG: Missing socket file causes abort. Jun 6, 2019
.gitignore Initial commit Jun 1, 2019
CONTRIBUTING.md
LICENSE
README.md Update README.md Jun 14, 2019

README.md

Prologue

There's a perfectly good dnstap dissector here. You'll find it in shodohflo/, with an example: examples/tap_example.py.

shodohflo

Ultimately this is going to be a DNS and netflow (IP address) correlator. It also includes pure Python implementations of Frame Streams and Protobuf, useful in their own right.

Dnstap is a technology for DNS traffic capture within a DNS server, therefore capturing both UDP and TCP queries and responses with fidelity. http://dnstap.info/

Prerequisites

Aside from standard libraries the only dependencies for the core shodohflo package components are:

  • Python 3
  • dnspython

Dependencies for the agents are:

  • dnspython (mandatory for the dns agent, optional for pcap)
  • dpkt (mandatory for pcap)
  • a local caching resolver compiled with dnstap support (mandatory for dns)
  • redis

Dependencies for the app/ at the present time (may change in the future) are:

  • redis
  • dnspython (optional)
  • flask

It is developed and tested on Linux. In particular the agents will likely not run except on Linux.

Installation

shodohflo package (Dnstap listener)

This is a pure python dnstap protocol implementation for Linux, with potentially reusable frame streams and protocol buffer implementations.

  1. Download or clone the repo.
  2. Make sure the dnspython package is installed (see PyPI.org)
  3. Make sure your DNS server is compiled with dnstap and configured to write to a unix domain socket.
  4. Make sure that SOCKET_ADDRESS in tap_example.py references the socket location.
  5. You should be able to run the tap_example.py program.
  6. You can symlink / move / copy the shodohflo package wherever you wish.

You can find additional pointers in the install/ directory.

Agents

There are two agents, one for packet capture and one for DNS traffic (using dnstap). Both of them write to Redis.

  1. Follow the instructions in the install/ directory.
  2. Review the README in the agents/ directory and copy configuration_sample.py to configuration.py.
  3. Look in install/systemd/ for service scripts and review the README there.

The ShoDoHFlo app

This is a browser-based DNS and netflow correlator.

  1. Follow the instructions in the install/ directory
  2. Review the README in the app/ directory and copy configuration_sample.py to configuration.py.
  3. To run the app run app.py with Python 3.

Examples

tap_example.py is a working example of listening to a Unix domain socket receiving dnstap data and has no dependencies beyond those for core components.

There are other examples as well, look in the examples/ directory.

Collaborators welcomed!

Send me an email, or file an issue or PR.

You can’t perform that action at this time.