Metadata-Version: 2.4
Name: dnstrace
Version: 0.2.2
Summary: DnsTrace is a tool that identifies DNS queries made by processes on the host.
Author-email: Furkan Onder <furkanonder@protonmail.com>
Maintainer-email: Furkan Onder <furkanonder@protonmail.com>
License: MIT
Project-URL: Homepage, https://github.com/furkanonder/dnstrace
Project-URL: Documentation, https://github.com/furkanonder/dnstrace#readme
Project-URL: Repository, https://github.com/furkanonder/dnstrace.git
Project-URL: Bug Tracker, https://github.com/furkanonder/dnstrace/issues
Project-URL: Changelog, https://github.com/furkanonder/dnstrace/blob/main/CHANGELOG.md
Keywords: dns,ebpf,bpf,trace,monitoring,networking
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Internet :: Name Service (DNS)
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dnslib>=0.9.26
Provides-Extra: dev
Requires-Dist: pytest>=8.4.2; extra == "dev"
Requires-Dist: ruff>=0.13.2; extra == "dev"
Requires-Dist: mypy>=1.18.2; extra == "dev"
Requires-Dist: pre-commit>=4.3.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8.4.2; extra == "test"
Provides-Extra: all
Requires-Dist: pytest>=8.4.2; extra == "all"
Requires-Dist: ruff>=0.13.2; extra == "all"
Requires-Dist: mypy>=1.18.2; extra == "all"
Requires-Dist: pre-commit>=4.3.0; extra == "all"
Dynamic: license-file

<div align="center">
  <h2>DnsTrace</h2>
  <h3> Monitor DNS queries by host processes using eBPF!</h3>
  <a href="https://github.com/furkanonder/dnstrace/issues"><img alt="GitHub issues" src="https://img.shields.io/github/issues/furkanonder/dnstrace"></a>
  <a href="https://github.com/furkanonder/dnstrace/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/furkanonder/dnstrace"></a>
  <a href="https://github.com/furkanonder/dnstrace/blob/main/LICENSE"><img alt="GitHub license" src="https://img.shields.io/github/license/furkanonder/dnstrace"></a>
  <a href="https://pepy.tech/project/dnstrace"><img alt="Downloads" src="https://pepy.tech/badge/dnstrace"></a>
</div>

![Demo](assets/demo.gif)

## Quick Start

### Prerequisites

DnsTrace requires BCC (BPF Compiler Collection) to be installed on your system. Follow the [BCC installation guide](https://github.com/iovisor/bcc/blob/master/INSTALL.md) for your Linux distribution.

### Installation

Install DnsTrace using pipx:

```bash
pipx install dnstrace
```

### Usage

Run DnsTrace with root privileges:

```bash
sudo dnstrace
```

#### Command Line Options

```bash
sudo dnstrace [OPTIONS]

Options:
  -t, --tail     Stream live DNS queries (tail mode)
  -d, --domain   Show DNS query domains
  -h, --help     Show help message
```

#### Examples

**Basic monitoring:**
```bash
sudo dnstrace
```

**Stream live queries:**
```bash
sudo dnstrace --tail
```

**Show domains with live-streaming:**
```bash
sudo dnstrace --tail --domain
```

## 📊 Display Modes

### Table Mode (Default)
- Real-time statistics dashboard
- Query type distribution charts
- Process attribution and interface details
- Responsive column layout

### Tail Mode (`--tail`)
- Live-streaming of DNS queries
- Optional domain display with `--domain` flag
