Azure Firewall Watch is a terminal UI for live log monitoring of Azure Firewall. It streams logs from an Event Hub in real time and lets you filter and inspect them directly in your terminal.

Built by CloudChristoph.

This project is based on the excellent work by Nicola Delfino and his azure-firewall-mon project.

Azure Firewall Watch reads logs from an Azure Event Hub that receives firewall events via Diagnostic Settings:

Azure Firewall
    └─▶ Diagnostic Settings
            └─▶ Event Hub  ◀─── az-firewall-watch (streams in real time)

1. Diagnostic Settings on your Azure Firewall forward structured log categories (NetworkRule, AppRule, IDPS, …) to an Event Hub namespace.
   → Configure Azure Firewall diagnostics

2. Event Hub buffers the events (default retention: 1 day) so az-firewall-watch can consume them live.
   → Azure Event Hubs overview

Download the binary for your platform from the latest release:

Windows:

Double-click az-firewall-watch.exe or run from PowerShell:

.\az-firewall-watch.exe

macOS:

# 1. Extract (preserves execute permission)
tar -xzf az-firewall-watch-macos.tar.gz

# 2. Remove the Gatekeeper quarantine flag (required for unsigned binaries)
xattr -d com.apple.quarantine az-firewall-watch

# 3. Run — the setup wizard launches automatically on first start
./az-firewall-watch

Linux:

# 1. Extract (preserves execute permission)
tar -xzf az-firewall-watch-linux.tar.gz

# 2. Run — the setup wizard launches automatically on first start
./az-firewall-watch

git clone https://github.com/cloudchristoph/az-firewall-watch.git
cd az-firewall-watch

# Linux / macOS
./start.sh

# Windows
start.bat

The scripts create a virtual environment, install dependencies, and launch the app — the setup wizard runs automatically if .env is not yet configured.

The setup wizard runs automatically the first time you launch the app (or whenever .env is missing). It's a full TUI — navigate with arrow keys, Enter to confirm, Escape or Q to go back.

You have two main options for connecting your firewall logs Event Hub:

After picking a hub (Discover, Enter existing, or Deploy new), a follow-up screen asks how to authenticate:

• Entra ID (recommended) — uses passwordless auth via logged in Azure CLI login, managed identity, environment credentials, etc. Nothing secret is written to .env. Requires the Azure Event Hubs Data Receiver role on the namespace or hub; the wizard verifies your assignment up-front.
• SAS auth rule — looks for a reusable Listen-only authorization rule on the hub; if none exists you'll be asked to confirm the creation of a new one before the connection string is written to .env.

The Paste connection string path skips the auth-method screen since SAS is already implied.

Run with --reconfigure to redo setup at any time:

./az-firewall-watch --reconfigure

If you already have an Event Hub connection string, create .env next to the binary (or in the repo root):

EVENT_HUB_CONNECTION_STRING=Endpoint=sb://your-ns.servicebus.windows.net/;SharedAccessKeyName=...;EntityPath=your-hub-name
EVENT_HUB_CONSUMER_GROUP=$Default
EVENT_HUB_START_POSITION=latest   # or: earliest

Alternatively, for Entra ID (passwordless) authentication — required when SAS keys are disabled on the namespace:

EVENT_HUB_NAMESPACE=your-ns.servicebus.windows.net
EVENT_HUB_NAME=your-hub-name
EVENT_HUB_CONSUMER_GROUP=$Default
EVENT_HUB_START_POSITION=latest

Note: Entra ID auth uses DefaultAzureCredential which picks up Azure CLI login, managed identity, environment variables, etc. Your identity must have the Azure Event Hubs Data Receiver role on the namespace or hub.

When both EVENT_HUB_NAMESPACE/EVENT_HUB_NAME and EVENT_HUB_CONNECTION_STRING are set, Entra ID is preferred. Tip: If you deploy the Event Hub manually, configure Diagnostic Settings on your Azure Firewall to forward logs to the firewall-logs Event Hub.

The status bar at the bottom shows the connection state, total events received, the currently visible count when a filter is active, and how many records were skipped (e.g. unknown categories).

All filters are case-insensitive substring matches applied instantly as you type.

DNS proxy traffic can dominate the log volume on busy firewalls. A Hide DNS switch sits at the end of the filter bar and is on by default, so DnsQuery rows are filtered out until you explicitly want to see them.

The toggle is smart:

• Flipping it off instantly shows all DNS rows.
• Picking DnsQuery in the Category dropdown automatically flips it off — so you never end up with an empty table after asking to see DNS entries.
• Pressing Escape to clear all filters resets the toggle back to on.

Press Escape to clear all filters at once, or f to jump directly into the filter bar.

Both the legacy (single-message) and the structured (typed JSON) log formats produced by Azure Firewall are parsed. Legacy AzureFirewallDnsProxy entries are normalised into the DnsQuery category so you only deal with one display name regardless of which diagnostic mode is enabled.

Unknown or non-firewall categories are counted in the status bar as skipped rather than displayed.

pip install -r requirements.txt -r requirements-build.txt

pyinstaller \
  --onefile \
  --name az-firewall-watch \
  --collect-all textual \
  --hidden-import azure.eventhub \
  --hidden-import azure.eventhub.aio \
  --hidden-import azure.eventhub._transport._pyamqp_transport \
  --add-data "fw_parser.py:." \
  main.py

# Binary is at dist/az-firewall-watch  (or dist/az-firewall-watch.exe on Windows)

An Event Hub for firewall logs is typically inexpensive:

Firewall log volume depends on traffic intensity — most environments stay comfortably within a single Throughput Unit.
→ Event Hubs pricing

Tip: The built-in setup wizard can deploy a new Event Hub and configure diagnostic settings automatically in ~2–3 minutes.

MIT