[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80834":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":14,"stars30d":14,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":16,"rankGlobal":10,"rankLanguage":10,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":10,"pushedAt":10,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":15,"starSnapshotCount":15,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},80834,"az-firewall-watch","cloudchristoph\u002Faz-firewall-watch","cloudchristoph","Terminal UI for live log monitoring of Azure Firewall","",null,"Python",37,7,1,0,2.71,"MIT License",false,"main",true,[22,23,24],"azure-firewall","azure-firewall-rules","azure-networking","2026-06-12 02:04:07","# 🔥 Azure Firewall Watch\n\nAzure 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.\n\nBuilt by [CloudChristoph](https:\u002F\u002Fgithub.com\u002Fcloudchristoph).\n\n> This project is based on the excellent work by [Nicola Delfino](https:\u002F\u002Fgithub.com\u002Fnicolgit) and his\n> [azure-firewall-mon](https:\u002F\u002Fgithub.com\u002Fnicolgit\u002Fazure-firewall-mon) project.\n\n![Azure Firewall Watch screenshot](https:\u002F\u002Fraw.githubusercontent.com\u002Fcloudchristoph\u002Faz-firewall-watch\u002Fmain\u002Fdocs\u002Fscreenshot.png)\n\n## 🏗️ How it works\n\nAzure Firewall Watch reads logs from an **Azure Event Hub** that receives firewall events via **Diagnostic Settings**:\n\n```text\nAzure Firewall\n    └─▶ Diagnostic Settings\n            └─▶ Event Hub  ◀─── az-firewall-watch (streams in real time)\n```\n\n1. **Diagnostic Settings** on your Azure Firewall forward structured log categories (NetworkRule, AppRule, IDPS, …) to an Event Hub namespace.  \n   → [Configure Azure Firewall diagnostics](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fazure\u002Ffirewall\u002Fmonitor-firewall#enable-structured-logs)\n\n2. **Event Hub** buffers the events (default retention: 1 day) so az-firewall-watch can consume them live.  \n   → [Azure Event Hubs overview](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fazure\u002Fevent-hubs\u002Fevent-hubs-about)\n\n## 🚀 Getting started\n\n### Option 1 - Download the binary *(recommended)*\n\nDownload the binary for your platform from the [latest release](..\u002F..\u002Freleases\u002Flatest):\n\n\u003C!-- markdownlint-disable MD060 -->\n| Platform            | File                                                                                              |\n| ------------------- | ------------------------------------------------------------------------------------------------- |\n| Windows             | [`az-firewall-watch.exe`](..\u002F..\u002Freleases\u002Flatest\u002Fdownload\u002Faz-firewall-watch.exe)                   |\n| macOS Apple Silicon | [`az-firewall-watch-macos.tar.gz`](..\u002F..\u002Freleases\u002Flatest\u002Fdownload\u002Faz-firewall-watch-macos.tar.gz) |\n| Linux x86_64        | [`az-firewall-watch-linux.tar.gz`](..\u002F..\u002Freleases\u002Flatest\u002Fdownload\u002Faz-firewall-watch-linux.tar.gz) |\n\u003C!-- markdownlint-enable MD060 -->\n\n**Windows:**\n\nDouble-click `az-firewall-watch.exe` or run from PowerShell:\n\n```powershell\n.\\az-firewall-watch.exe\n```\n\n> [!NOTE]\n> **Windows SmartScreen** may warn on first launch - click **More info → Run anyway**.  \n> This is expected for unsigned binaries.\n\n**macOS:**\n\n```bash\n# 1. Extract (preserves execute permission)\ntar -xzf az-firewall-watch-macos.tar.gz\n\n# 2. Remove the Gatekeeper quarantine flag (required for unsigned binaries)\nxattr -d com.apple.quarantine az-firewall-watch\n\n# 3. Run — the setup wizard launches automatically on first start\n.\u002Faz-firewall-watch\n```\n\n**Linux:**\n\n```bash\n# 1. Extract (preserves execute permission)\ntar -xzf az-firewall-watch-linux.tar.gz\n\n# 2. Run — the setup wizard launches automatically on first start\n.\u002Faz-firewall-watch\n```\n\n### Option 2 — Run from source *(Python 3.10+)*\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fcloudchristoph\u002Faz-firewall-watch.git\ncd az-firewall-watch\n\n# Linux \u002F macOS\n.\u002Fstart.sh\n\n# Windows\nstart.bat\n```\n\nThe scripts create a virtual environment, install dependencies, and launch the app — the setup wizard runs automatically if `.env` is not yet configured.\n\n### 🧙 First-run setup wizard\n\nThe 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.\n\nYou have two main options for connecting your firewall logs Event Hub:\n\n#### Existing Event Hub\n\n\u003C!-- markdownlint-disable MD060 -->\n| Option                               | What it does                                                                                          | Azure CLI required |\n| ------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------------ |\n| **Discover Event Hub automatically** | Lists your subscriptions, namespaces and hubs so you can pick one from a menu                         | ✅                  |\n| **Enter existing Event Hub data**    | Type namespace + hub name manually (handy when your identity can read the hub but not list resources) | —                  |\n| **Paste SAS connection string**      | Paste a full `Endpoint=sb:\u002F\u002F…;EntityPath=…` string — written verbatim to `.env`                       | —                  |\n\u003C!-- markdownlint-enable MD060 -->\n\n#### New Event Hub\n\n> [!NOTE]\n> If your environment uses Azure Policy to enforce specific naming conventions, settings, or resource tags (as it should 😉), the automatic deployment may fail since it creates a new Event Hub with default settings within the same subscription as the firewall.\n>\n> In that case, you should create the Event Hub manually or via IaC according to your policies and then use the \"Discover\" or \"Enter existing\" options to connect it to the app.\n\n\u003C!-- markdownlint-disable MD060 -->\n| Option                                            | What it does                                                                                                                                                             | Azure CLI required |\n| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ |\n| **Deploy new Event Hub and Diagnostics settings** | Discovers your Azure Firewall, creates a Basic-tier Event Hub namespace + `firewall-logs` hub, and wires up Diagnostic Settings to forward the structured log categories | ✅                  |\n\n> [!NOTE]\n> The deployment will require permissions to create an Event Hub namespace and hub, and to update Diagnostic Settings on the firewall. Also keep in mind that it can take *up to 10-15 minutes at the first launch* for the Event Hub to be fully provisioned and start receiving logs from the firewall.\n\n### 🔑 Authentication methods\n\nAfter picking a hub (Discover, Enter existing, or Deploy new), a follow-up screen asks **how** to authenticate:\n\n- **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.\n- **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`.\n\n> The *Paste connection string* path skips the auth-method screen since SAS is already implied.\n\n> [!CAUTION]\n> SAS keys are powerful secrets that grant access to your Event Hub. If you choose the SAS auth method, make sure to protect the generated connection string and `.env` file, and rotate keys regularly.\n>\n> Never commit your `.env` file to source control or share it with unauthorized parties.\n\nRun with `--reconfigure` to redo setup at any time:\n\n```bash\n.\u002Faz-firewall-watch --reconfigure\n```\n\n## ⚙️ Configuration\n\n### Manual setup (skip the wizard)\n\nIf you already have an Event Hub connection string, create `.env` next to the binary (or in the repo root):\n\n```ini\nEVENT_HUB_CONNECTION_STRING=Endpoint=sb:\u002F\u002Fyour-ns.servicebus.windows.net\u002F;SharedAccessKeyName=...;EntityPath=your-hub-name\nEVENT_HUB_CONSUMER_GROUP=$Default\nEVENT_HUB_START_POSITION=latest   # or: earliest\n```\n\nAlternatively, for **Entra ID (passwordless) authentication** — required when SAS keys are disabled on the namespace:\n\n```ini\nEVENT_HUB_NAMESPACE=your-ns.servicebus.windows.net\nEVENT_HUB_NAME=your-hub-name\nEVENT_HUB_CONSUMER_GROUP=$Default\nEVENT_HUB_START_POSITION=latest\n```\n\n> **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.\n\n### Environment variables\n\n\u003C!-- markdownlint-disable MD060 -->\n| Variable                      | Description                                                                               | Default    |\n| ----------------------------- | ----------------------------------------------------------------------------------------- | ---------- |\n| `EVENT_HUB_CONNECTION_STRING` | Primary connection string incl. `EntityPath=\u003Cyour-hub-name>`                              | —          |\n| `EVENT_HUB_NAMESPACE`         | Fully qualified namespace (e.g. `mynamespace.servicebus.windows.net`) — for Entra ID auth | —          |\n| `EVENT_HUB_NAME`              | Event Hub name — for Entra ID auth                                                        | —          |\n| `EVENT_HUB_CONSUMER_GROUP`    | Consumer group                                                                            | `$Default` |\n| `EVENT_HUB_START_POSITION`    | `latest` (live only) or `earliest` (read full retention)                                  | `latest`   |\n\u003C!-- markdownlint-enable MD060 -->\n\n> When both `EVENT_HUB_NAMESPACE`\u002F`EVENT_HUB_NAME` and `EVENT_HUB_CONNECTION_STRING` are set, Entra ID is preferred.\n> **Tip:** If you deploy the Event Hub manually, configure [Diagnostic Settings](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fazure\u002Fazure-monitor\u002Fplatform\u002Fdiagnostic-settings) on your Azure Firewall to forward logs to the `firewall-logs` Event Hub.\n\n## ⌨️ Key bindings\n\n| Key          | Action                                |\n| ------------ | ------------------------------------- |\n| `Ctrl` + `q` | Quit                                  |\n| `Ctrl` + `p` | Pause \u002F resume streaming              |\n| `Ctrl` + `s` | Save a screenshot of the current view |\n| `Escape`     | Clear all filter inputs               |\n| `f`          | Jump focus to the filters             |\n| `Tab`        | Move between filter inputs            |\n| `Enter`      | Open detail view for the selected row |\n| `c`          | Clear all rows from the table         |\n\nThe status bar at the bottom shows the connection state, total events received,\nthe currently visible count when a filter is active, and how many records were\nskipped (e.g. unknown categories).\n\n## 🔍 Filters\n\nAll filters are **case-insensitive substring matches** applied instantly as you type.\n\n\u003C!-- markdownlint-disable MD060 -->\n| Filter      | Matches against                                                                        |\n| ----------- | -------------------------------------------------------------------------------------- |\n| Source IP   | `sourceip` field                                                                       |\n| Dest \u002F FQDN | `targetip` \u002F FQDN field                                                                |\n| Action      | `allow`, `deny`, `dnat`, `alert`, `resolvefail`, DNS RCODEs (`noerror`, `nxdomain`, …) |\n| Category    | `NetworkRule`, `AppRule`, `DnsQuery`, `NATRule`, `IDPS`, `ThreatIntel`                 |\n| Protocol    | `TCP`, `UDP`, `HTTPS`, `HTTP`, DNS query types (`A`, `AAAA`, `MX`, …)                  |\n| Port        | Destination port (e.g. `443`, `80`, `53`)                                              |\n\u003C!-- markdownlint-enable MD060 -->\n\n### Hide DNS toggle\n\nDNS proxy traffic can dominate the log volume on busy firewalls. A **Hide DNS**\nswitch sits at the end of the filter bar and is **on by default**, so `DnsQuery`\nrows are filtered out until you explicitly want to see them.\n\nThe toggle is smart:\n\n- Flipping it **off** instantly shows all DNS rows.\n- Picking **DnsQuery** in the Category dropdown automatically flips it off — so\n  you never end up with an empty table after asking to see DNS entries.\n- Pressing `Escape` to clear all filters resets the toggle back to **on**.\n\nPress `Escape` to clear all filters at once, or `f` to jump directly into the filter bar.\n\n---\n\n## 📋 Supported log categories\n\nBoth the **legacy** (single-message) and the **structured** (typed JSON) log\nformats produced by Azure Firewall are parsed. Legacy `AzureFirewallDnsProxy`\nentries are normalised into the `DnsQuery` category so you only deal with one\ndisplay name regardless of which diagnostic mode is enabled.\n\n| Category shown | Azure category (structured \u002F legacy)                                                                                   |\n| -------------- | ---------------------------------------------------------------------------------------------------------------------- |\n| NetworkRule    | `AZFWNetworkRule` \u002F `AzureFirewallNetworkRule`                                                                         |\n| AppRule        | `AZFWApplicationRule` \u002F `AzureFirewallApplicationRule` \u002F `AZFWFqdnResolveFailure` (rendered with action `ResolveFail`) |\n| NATRule        | `AZFWNatRule` \u002F `AzureFirewallNatRuleLog`                                                                              |\n| DnsQuery       | `AZFWDnsQuery` \u002F `AzureFirewallDnsProxy`                                                                               |\n| IDPS           | `AZFWIdpsSignature`                                                                                                    |\n| ThreatIntel    | `AZFWThreatIntel`                                                                                                      |\n\nUnknown or non-firewall categories are counted in the status bar as *skipped*\nrather than displayed.\n\n## 🔨 Building locally\n\n```bash\npip install -r requirements.txt -r requirements-build.txt\n\npyinstaller \\\n  --onefile \\\n  --name az-firewall-watch \\\n  --collect-all textual \\\n  --hidden-import azure.eventhub \\\n  --hidden-import azure.eventhub.aio \\\n  --hidden-import azure.eventhub._transport._pyamqp_transport \\\n  --add-data \"fw_parser.py:.\" \\\n  main.py\n\n# Binary is at dist\u002Faz-firewall-watch  (or dist\u002Faz-firewall-watch.exe on Windows)\n```\n\n### 💰 Cost considerations\n\nAn Event Hub for firewall logs is typically inexpensive:\n\n| Tier                | ~Rough monthly cost                                                       |\n| ------------------- | ------------------------------------------------------------------------- |\n| **Basic** (1 TU)    | ~$10 + ~$0.028 per million events                                         |\n| **Standard** (1 TU) | ~$22 + ~$0.028 per million events — required for multiple consumer groups |\n\nFirewall log volume depends on traffic intensity — most environments stay comfortably within a single Throughput Unit.  \n→ [Event Hubs pricing](https:\u002F\u002Fazure.microsoft.com\u002Fpricing\u002Fdetails\u002Fevent-hubs\u002F)\n\n> **Tip:** The built-in setup wizard can deploy a new Event Hub and configure diagnostic settings automatically in ~2–3 minutes.\n\n## 📄 License\n\nMIT\n","Azure Firewall Watch 是一个用于实时监控 Azure 防火墙日志的终端 UI 工具。它通过 Event Hub 实时流式传输防火墙日志，并允许用户在终端中直接过滤和检查这些日志。该工具基于 Python 开发，具有直观的日志展示界面和强大的实时处理能力，适用于需要对 Azure 防火墙活动进行即时监控和分析的场景，如安全审计、故障排查等。此外，Azure Firewall Watch 支持跨平台使用，无论是 Windows、macOS 还是 Linux 用户都能轻松部署并运行。",2,"2026-06-11 04:02:29","CREATED_QUERY"]