AbuseBox is a self-hosted Python and Docker monitoring tool that watches your own IPs and domains across 28 DNS blacklists, certificate expiry, and SPF/DKIM/DMARC health for authorized mail operators.
| Tool | bekkaze/abusebox — self-hosted blacklist and mail-server health monitoring with risk scoring and alerting |
| Category | Defensive monitoring / email infrastructure hygiene |
| Primary Use | Continuous authorized monitoring of mail-server assets you own: DNSBL listings, AbuseIPDB reputation, SSL and domain expiry, SPF/DKIM/DMARC grades, and uptime, with alerts via email, Slack, Discord or webhook |
| Safe Use | Deploying on infrastructure you own or administer during authorized operations, internal SOC hygiene, and mail-ops troubleshooting; it queries only your own assets and public reputation sources |
| Telemetry Note | The README states there is no telemetry; it generates outbound DNSBL queries, AbuseIPDB API calls, WHOIS and TLS probes from the hosting IP, and an activity log of every change visible to administrators |
bekkaze/abusebox attacks a problem every mail operator knows intimately: you find out your IP is on a DNSBL when users complain about bounced mail. The tool, written in Python with a Node.js/Vite frontend and shipped as prebuilt Docker images for amd64 and arm64, turns that reactive discovery into continuous, self-hosted monitoring. It watches IPs and domains you register as assets, checks 28 DNS blacklists, tracks certificate and domain expiry, grades SPF/DKIM/DMARC, probes uptime, and pushes alerts when something changes. For a blue-team or mail-ops audience it sits in the same niche as uptime monitors, but specialized in mail-server reputation.
What separates it from a naive dig-based checker is the trust model around blacklist answers. Before trusting any list, abusebox validates it against its own test addresses per RFC 5782 — the standard that defines how DNS blacklists should publish known-listed and known-clean test points. A resolver that a blacklist refuses to answer shows No answer rather than a false "clean", which the README calls out with a concrete example: through Google DNS, Spamhaus reports "not listed" for everything. That single design decision prevents the most dangerous failure mode of blacklist monitoring — silently believing you are clean because the query never got answered.
The second distinguishing decision is semantic decoding of listings. A Spamhaus SBL hit (a spam source) and a PBL hit (a policy block on end-user ranges) indicate entirely different problems and remediation paths, so abusebox attaches a meaning and a severity to every listing rather than a binary listed/not-listed flag. Those severities feed a per-asset risk score out of 100, weighted so one critical listing outranks several cosmetic ones. Crucially, the score is explainable: the dashboard shows every factor, what it contributed, and out of what, which makes triage defensible when you are arguing priorities with a change-adverse network team.
Coverage spans 24 IPv4 lists, 5 lists answering IPv6 (one IPv6-only), plus Spamhaus DBL, SURBL and URIBL for domain reputation. Beyond blacklists, the check engine integrates AbuseIPDB abuse confidence scores, reports, ISP and country data via a free API key; SSL inspection covering validity, issuer, covered names, and whether the TLS version and cipher are still acceptable; WHOIS over IPv6 or IPv4; and full DNS record enumeration (A, AAAA, MX, TXT, CNAME, NS, SOA, PTR). The email-authentication checks are graded A to F with custom DKIM selector support and DMARC aggregate report parsing — and it handles the subtlety of a mail server's hostname whose SPF is published elsewhere, resolving the DMARC policy and DKIM key on the owning domain.
Asset management is built for realistic fleet sizes: add targets one at a time, in bulk lists of up to 300, or as an entire /24. Scheduling supports a global or per-asset re-check interval plus a manual "check due assets now" button, and the activity log records every state transition with a diff between checks — so you can see not just that an asset is bad, but when it became bad and whether you were delisted overnight. Delist tracking includes links to each blacklist's removal page, which is exactly what you need at 2 a.m. when marketing rented a "clean" list. Server-side search, filtering, sorting and paging mean the ordering stays correct as asset counts grow, and there is a CSV export, an owner field per asset, and bulk actions.
The operational surface is deliberately hardened for something that will live on a homelab or SOC box. First sign-in is admin with a randomly generated password written to /app/data/initial_admin_password, readable via docker compose exec backend cat /app/data/initial_admin_password; the backend log names the file but no longer prints the secret, so a shared log does not leak the account, and the stored copy is deleted once you change it. The backend runs as an unprivileged user, a bundled Unbound resolver handles blacklist lookups since v1.3.2, and migrations moved to Alembic with automatic database upgrades on start. The README explicitly warns that the UI answers on any hostname, so anything beyond localhost belongs behind your own HTTPS reverse proxy.
Deployment paths are unusually broad for a project this size. The canonical route is git clone https://github.com/bekkaze/abusebox.git followed by docker compose up -d, which pulls prebuilt images and serves the UI on port 3000. Manual installs need Python 3.11+ and Node.js 20.19+, running uvicorn app.main:app on port 8100 with yarn dev for the frontend, where VITE_BASE_URL and VITE_ALLOWED_HOSTS control the dev proxy. There are first-class templates for Unraid (two containers, backend and frontend), Portainer (app template or repository stack using templates/portainer/docker-compose.yml), and CasaOS (import templates/casaos/docker-compose.yml), each with honest notes — such as Unraid lacking a bundled resolver, which is why **Blacklist resolvers** starts empty there.
Alerting covers the full lifecycle operators care about: new listings, delistings, outages, recoveries and expiry warnings, delivered by email, Slack, Discord or generic webhook. There is a public, rate-limited quick-check page requiring no account, while everything else sits behind authentication with multiple users and admin roles. A REST API with Swagger documentation at /api/swagger/ makes it scriptable from an existing SOC pipeline, which is where most professional deployments will want it — feeding reputation state into a wider posture dashboard rather than being yet another tab to check.
The security posture notes in the changelog suggest an actively maintained project that responds to its own mistakes: v1.1.x-era setups used a published JWT secret, so upgrading signs everyone out once; older default passwords keep working but carry a change-me banner; ISPs and commercial users need SPAMHAUS_DQS_KEY since Spamhaus restricts free-zone queries from resolver ranges. The repo carries CI badges, an MIT license, roughly 85 stars at time of writing, and explicit commitments to no telemetry and no paid tier. For defenders and authorized mail administrators, abusebox is a solid example of monitoring built for the realities of DNSBL behavior — and its trust-verification approach is worth studying even if you build your own.
bekkaze/abusebox.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.