A previous release had provenance metadata, but this release does not. View details.
Lire en français · Technical documentation
🔒 ufw-audit
Smart UFW security audit — fast, readable, actionable.
Analyses your UFW configuration, exposed services and logs to detect real risks, with clear recommendations.
⚡ TL;DR
sudo apt install pipx && pipx ensurepath
# open a new terminal, then:
pipx install ufw-audit
sudo ~/.local/bin/ufw-audit --install-completion
sudo ufw-audit
🛠 Installation
Prerequisites
- Linux: Debian, Ubuntu, Mint or derivative
- UFW:
sudo apt install ufw - pipx:
sudo apt install pipx && pipx ensurepath
Open a new terminal after
pipx ensurepathto activate the PATH.
Install
pipx install ufw-audit
Enable sudo + bash completion
pipx installs the binary in ~/.local/bin/, which is not in sudo's restricted PATH.
--install-completion creates the symlink /usr/local/bin/ufw-audit and installs the bash completion script:
sudo ~/.local/bin/ufw-audit --install-completion
source /etc/bash_completion.d/ufw-audit
After this step, sudo ufw-audit works normally.
Update
pipx upgrade ufw-audit
Uninstall
pipx uninstall ufw-audit
🚀 Why ufw-audit?
- 🔍 Full audit — firewall, services, ports, logs, DDNS, Docker, virtualisation
- 🎯 Smart prioritisation — score + classification (OK / Warning / Action required)
- 🧠 Context-aware — network exposure + service criticality
- 🛠 Optional auto-fix — corrections proposed or applied automatically
- 📊 Clear output — human-readable + scriptable
- 🌍 Bilingual EN/FR
🔎 What the tool analyses
🔥 Firewall (UFW)
- Active/inactive status
- Dangerous rules (
allow from any) - IPv4 / IPv6 consistency
- Duplicates and errors
🌐 Exposed services (28+)
- SSH, Redis, PostgreSQL, Docker, etc.
- Detection via systemd / active ports
- Real exposure, risk level, UFW consistency
📡 Ports
- Open ports (
ss) - Interfaces (loopback / LAN / public)
- Unintended exposures
📜 UFW logs
- Suspicious attempts, brute-force detection
- IP analysis (optional GeoIP)
☁️ DDNS / Docker / Virtualisation
- Advanced network correlations
- Indirect exposure detection
📊 Example output
✔ Firewall active
⚠ SSH exposed to the Internet
✖ Redis open without restriction
Score: 6/10
→ Action required
▶️ Usage
sudo ufw-audit # standard audit
sudo ufw-audit -f # interactive fix mode
sudo ufw-audit -f -y # auto-fix without confirmation
sudo ufw-audit -v # verbose
sudo ufw-audit -q # silent — exit code 0/1/2/3
sudo ufw-audit --french # French interface
🔌 Custom services (plugin system)
Drop a .json file into ~/.config/ufw-audit/services.d/ to add services that are not in the built-in registry.
mkdir -p ~/.config/ufw-audit/services.d/
# create my-services.json — same format as ufw_audit/data/services.json
Note (pipx / sudo): ufw-audit requires
sudo. Undersudo,~resolves to/root.
Place your plugin files in/root/.config/ufw-audit/services.d/for them to be active at runtime.This will change in a future
.debrelease, where the system-wide directory/etc/ufw-audit/services.d/will be used instead.
🤖 Automation
- 🕒 Built-in cron (
--install-cron) - 📧 Email notifications (HTML + plain text)
- 📁 Report management (
--manage-logs) - 🔁 Multi-job scheduling (
--manage-cron)
Email notifications require a working Postfix setup. See AUTOMATION.md for step-by-step configuration instructions.
🧪 Quality & reliability
- ✅ 4134 unit tests
- 🧱 Modular architecture (snapshot / check separated)
- 🧪 Tested on Debian, Ubuntu, Kali, Mint
🆕 v1.25.0
- 🗂️ CIS compliance mapping inline — each finding in the summary box now shows its machine-readable CIS code
[CIS:X.Y.Z](dimmed); full CIS ref text shown dimmed in--verbosemode after each WARN/ALERT finding - 🏷️ Best-practice entries clarified — 34 entries without a formal CIS section number now use the
"Best practice — ..."prefix instead of a misleading"CIS..."label - 🔧
cis_refs.jsonrestructured —{"ref": "...", "code": "CIS:X.Y.Z"|null}per entry; 133 entries (99 formal CIS, 34 best-practice, 4 Docker); newget_cis_code()function - 🧹 Locale cleanup —
explain_cissection (170 strings) removed fromen.jsonandfr.json; CIS refs now served from JSON, language-independent - 🛡️ 5 new services — SMTP/Postfix (25/tcp), NFS (2049/tcp+udp), Jenkins (8080/tcp), OpenVPN (1194/udp), Squid (3128/tcp); registry now covers 32 services
- 🐛
_ipt_has_conntrackACCEPT fix — regex now requires-j ACCEPT;--ctstate ESTABLISHED -j DROPno longer treated as valid conntrack rule - 🔧 FORWARD DROP/REJECT → ✔ OK — symmetric with INPUT; was previously silent
- ✅ 4200/4200 unit tests (+60)
v1.24.1
- 🐛 Debian kernel parsing hotfix —
_KVER_REnow handles6.12.74+deb13+1-amd64format (+separator);_query_apt_kernel_updateaddslinux-image-$(uname -r)path for Debian (nolinux-image-genericmeta-package); ABI sort group made optional - ✨ CHECK 46 — iptables/nftables audit — when UFW is inactive, audits the underlying firewall layer (INPUT/FORWARD policies, conntrack, iptables vs nftables backend); INPUT ACCEPT → ALERT −3 pts
- ✨ 5 new critical services — Telnet (23/tcp), RDP/xRDP (3389/tcp), MongoDB (27017/tcp), Elasticsearch (9200/tcp), Memcached (11211/tcp+udp) — registry now covers 28 services
- ✨ Installed-but-inactive critical services — CRITICAL/HIGH packages installed but not running now show
⚠ [ATTENTION]+ risk context block (wasℹ [INFO]) - ✨ Kernel apt update check — ✔ [OK] when kernel is confirmed current; detects available updates; Ubuntu and Debian supported
- ✅ 4140/4140 unit tests
v1.23.0
- ✨
--format=FORMAT— unified output flag:json | json-full | csv | markdown | html; legacy flags (-j,-J,--output csv,--html) kept as aliases - ✨
--check=list— prints all 31 filterable section names (no sudo required) - ✨
--manage-logslog preview — Enter opens a scrollable viewer;stoggles full/summary mode (score + ALERT/WARN only);g/Gtop/bottom - ✨ Risk context scope qualifier —
[CRITIQUE • LAN]on all service labels when network context is local - 🔧 TUI help bar harmonization — consistent hints across
--explain,--manage-logs, preview viewer - ✅ 4042/4042 unit tests (+35)
v1.22.3
- 🐛 Snakeoil cert filter extended — now covers nginx/apache/postfix config paths (previously only
/etc/ssl/private) - 🐛 DDNS reflected in exposure view — internet-facing row shows
⚠ warnwhen DDNS is active - 🐛 High-numbered listen ports shown — removed incorrect
port < 32768ephemeral filter - 🐛 SSH notes display fixed — local-exposure and non-standard-port notes no longer concatenated on one line
- ✅ 4004/4004 unit tests (+3)
v1.22.1
- 🔧
recurrence.pyfloat policy unified —update_recurrencenow normalizes floats toint(consistent withload_recurrence);import osremoved - 🧪 Test suite hardening —
test_message_uses_translation_key;fw_policy=None → alertasserted;test_float_value_in_prev_is_normalized - ✅ 4001/4001 unit tests (+5)
v1.22.0
- 🔗 Signal correlation engine — 5 compound-risk rules combining individual findings (root login + no Fail2ban → ALERT; password auth + brute-force → ALERT; NOPASSWD sudo + unexpected SUID → WARN; etc.)
- 🔁 Recurring finding tracker — counts consecutive audit appearances per key; persisted at
~/.config/ufw-audit/recurrence.json - 📡 Port exposure analysis — groups exposed listening services by interface scope and risk level;
fw_policyallowlist fix - 📋 Comparative report — finding-key diff — new/resolved ALERT+WARN keys shown between audits; migration guard for pre-v1.22 baselines
- 🐛 IPv6 false-positive fix — WARN downgraded to INFO when only link-local/ULA addresses assigned (machine not internet-reachable via IPv6)
- 🐛 Kernel message fix — redundant "(running: X, latest: X)" suppressed when both values are identical
- 🐛 Snakeoil cert filter —
ssl-cert-snakeoil.pemno longer triggers TLS audit on Debian/Ubuntu - 🔍
--explain— 87→112 keys (+25 across 7 new groups: auth logs, umask, firewall logging, TLS/SSL certs, systemd timers, firmware, Docker) - ✅ 3996/3996 unit tests (+218)
🧠 Philosophy
Not just listing ports — understanding the real risk.
ufw-audit prioritises what matters: real exposure, attack surface, potential impact.
📁 Project structure
Automated-UFW-audit/
├── README.md / README_FR.md # project overview (EN/FR)
├── LICENSE
├── pyproject.toml # build config (pip/pipx install)
├── DOCUMENTS/
│ ├── README_TECH.md / _FR.md # complete technical reference
│ ├── README_DEV.md / _FR.md # developer documentation
│ ├── CHANGELOG_FULL.md / _FR.md # full version history
│ ├── TESTING.md / _FR.md # test plan & validated scenarios
│ └── AUTOMATION.md / _FR.md # cron & automation guide
├── ufw_audit/ # Python package
│ ├── checks/ # firewall, services, ports, logs, ddns, docker, virt, ssh, ssl_certs, systemd_timers, firmware
│ ├── data/
│ │ ├── services.json # 22 built-in service definitions
│ │ ├── profiles/ # built-in audit profiles (server, desktop, container)
│ │ └── ufw-audit.bash-completion
│ │ # ~/.config/ufw-audit/services.d/ ← user plugin directory (sudo: /root/...)
│ │ # ~/.config/ufw-audit/profiles/ ← user-defined audit profiles
│ └── locales/
│ ├── en.json
│ └── fr.json
└── tests/ # 3996 unit tests
📄 License
MIT — © 2026 Cédric Clauzel
🤝 Contributing
Bug reports, new detections, UX improvements — contributions welcome.
Metadata
Release files for ufw-audit 1.25.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Loss of provenance
These files do not have provenance metadata, despite files in a prior release including this data.
We recommend further investigation before installing these files. View details.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ufw_audit-1.25.1.tar.gz | 543.0 kB | Without provenance | Details for ufw_audit-1.25.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ufw_audit-1.25.1-py3-none-any.whl | Python 3 | none | any | Details for ufw_audit-1.25.1-py3-none-any.whl |
Total release size: 941.8 kB
Release files / ufw_audit-1.25.1.tar.gz
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | ufw_audit-1.25.1.tar.gz |
|---|---|
| Size | 543.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fad356a4f40ea0a927f62d7e6452416c8ed7006764395b381d3f8f3ac3b352d7
|
|
BLAKE2b-256 checksum How to use checksums |
6f682ad0d2ddac90cca50f56338f7a01da65efe59820045a96288c5fe067a168
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / ufw_audit-1.25.1-py3-none-any.whl
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | ufw_audit-1.25.1-py3-none-any.whl |
|---|---|
| Size | 398.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
03f63efa6a492f8ba0baab2afe9afe42b774ceef9fc1dcf69676bb7ed49fb08c
|
|
BLAKE2b-256 checksum How to use checksums |
8ce7a4229dee46edd18d6acbffe022ca9998156f4b5c9c142921d2293e32dcf5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for ufw-audit 1.25.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Loss of provenance
A previous release of these files had provenance metadata, but this release does not.
While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.
Release comparison
- Removed 1.25.0 2 files With provenance
- Added 1.25.1 2 files Without provenance
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.