DNSnitch

Disclaimer I use that for myself, it's here if someone needs it though. Feel free to open an issue if you find bugs!

The Interactive Terminal DNS Firewall

DNSnitch is a local, privacy-first DNS server that puts you in complete control of your network traffic. Unlike passive blocklists, DNSnitch operates on a "Default Deny" philosophy: every unknown domain is blocked by default until you authorize it via a real-time terminal dashboard.

Key Features

• Real-Time Interception: Runs locally (port 5353, configurable) to catch every DNS request leaving your machine.
• Default Deny Policy: Unknown domains return NXDOMAIN instantly and appear in a "Pending Queue".
• 4-Tier Permission System:
  • PERMANENT: Whitelist forever.
  • TEMPORARY: Allow for 5 minutes (auto-expires, configurable).
  • ONCE: Allow for exactly one DNS request (great for captive portals or one-off logins).
  • BLOCK: Explicitly blacklist a domain so it never asks again.
• Staged Workflow: Changes are "staged" in a workspace and only active when you Apply.
• Traffic Recording: Switch modes to allow traffic while recording unique domains to a history list.
• DNS Redirection: Map domains to specific IPs (local dev) or other domains (CNAME) instantly.
• Live TUI Dashboard: A multi-tab, mouse-free interface built with Ncurses.
  • Console: Command history and colored feedback.
  • Monitor: 4-column live view of active rules.
  • Queue: Interactive list of blocked requests.
  • Logs: Live scrolling of raw DNS queries.
  • Redirections: Preview currently enforced redirections.
  • Records: Display recorded domain name requests.

---

The Interface

Navigate the dashboard using F-Keys:

• [F1] CONSOLE: The main command center. Type commands here. Scroll history with PgUp/PgDn.
• [F2] MONITOR: A live overview of your rules.
  • Controls: Use Left/Right arrows to highlight a column (Temp, Once, Perm, Blocked), and Up/Down to scroll that specific column.
• [F3] QUEUE: The "In-Box" for blocked domains.
  • Visuals: > indicates selection, * indicates staged changes.
• [F4] LOGS: A raw stream of every request handled by the engine.
• [F5] REDIRECTS: Manage custom A/CNAME records.
• [F6] RECORDS: View domains captured while in "Record Mode".

---

Command Reference

DNSnitch is keyboard-driven. Below is the complete list of commands available in the Console [F1].

Selection & Queue Management

Before applying an action, you must select targets. You can select pending requests by ID or manual domains by name.

Command	Usage Example	Description
s	s	Clear the current selection.
s <id>	s 1 3 5	Select pending domains by their Queue ID (visible in F3).
s <domain>	s google.com	Select a specific domain by name (even if not in queue). Useful for editing existing rules. Multi-selection is supported
q, ls	q	Switch to the Queue Tab [F3].
clear	clear	Flush the pending queue (removes all pending requests from view).

Actions (Staging)

Once domains are selected, use these shortcuts to set their status.

Command	Usage	Description
p	p	Mark selected as Permanent Allow.
t	t	Mark selected as Temporary (5 Minutes).
o	o	Mark selected as Allow Once (Next request only).
b	b	Mark selected as Blocked (Blacklist).
rm, del	rm	Remove the rule for the selected domain (Forget it, start fresh).

Workflow (Applying Changes)

Changes are not live until applied.

Command	Usage	Description
cc	cc	Check Config: Print a text summary of staged changes.
d, ditch	d	Discard: Reset the workspace and undo all staged changes.
a	a	Apply: Commit the workspace to the live firewall database.

Modes & Recording

Change how the firewall behaves globally.

Command	Usage	Description
m dft	m dft	Default Mode: Block everything unknown (Standard security).
m rec	m rec	Record Mode: Allow everything + Log unique domains to [F6].
m rbl	m rbl	Record + Blocklist: Allow everything except known blocks + Log unique domains.
crec	crec	Clear Records: Wipe the list of recorded domains in [F6].

Redirection

Map domains to custom targets (Local DNS spoofing).

Command	Usage Example	Description
r	r dev.loc 127.0.0.1	Redirect dev.loc to local IP (A Record).
r	r my.net google.com	Redirect my.net to google.com (CNAME).
ur	ur dev.loc	Unredirect: Remove the custom rule for dev.loc.

System

Command	Usage	Description
logs	logs	Switch to Logs Tab [F4].
help	help	List all available commands.
exit	exit	Shut down the DNS server.

---

Usage Scenarios

1. The Standard Workflow (Unblocking a site)

1. Try to visit example.com. It fails.
2. Press F3 (Queue). You see 1. example.com.
3. Type s 1. (Row highlights).
4. Type p. (Row shows [PERM]).
5. Type a. (Apply).
6. Refresh browser. It works.

2. Modifying a Rule (Unblocking a mistake)

1. You accidentally blocked google.com.
2. Type s google.com.
3. Type rm (Remove) or p (Perm) to overwrite the block.
4. Type a.

3. Local Development

1. You are building a site and want to access it via mysite.local.
2. Press F5.
3. Type r mysite.local 127.0.0.1.
4. Your system now resolves that domain to localhost.

4. Auditing an App (Record Mode)

1. You installed a new app and want to see what it connects to without breaking it.
2. Type m rec (Mode: Record).
3. Use the app for 5 minutes.
4. Press F6.
5. Review the list.
6. Type m dft to go back to secure mode.