AbuseBox
Open-source threat monitoring toolkit for IPs, domains, and servers.
- Language
- Python
- Stars
- 0
- Last updated
- License
- MIT
From the README
Check blacklists, query AbuseIPDB, inspect DNS/SSL/DMARC records, scan subnets and verify uptime, then get told when something changes. One self-hosted dashboard.
Screenshots
Dashboard: everything that needs attention across your assets, scheduler status, recent activity and listing history
Assets: health at a glance, filters, sorting, card or table view, and bulk actions
Asset detail: results for every check, plus the asset's activity and a check-by-check history
Landing page: anyone can run a quick blacklist check, no account needed
Activity log: every change, with severity filters![]() |
Alerts: email, Slack, Discord or any webhook, with a test button![]() |
Dark mode![]() |
Command palette (Ctrl/Cmd + K): jump to any asset or page![]() |
Why AbuseBox?
Most blacklist tools check one thing at a time. AbuseBox gives you a single pane of glass to:
- See what needs attention in one list: blacklist listings, expiring certificates and domains, servers down, weak email security
- Scan 60 DNSBL providers in seconds
- Get AbuseIPDB reputation scores alongside blacklist results
- Run bulk checks on up to 300 IPs/domains at once (paste or upload TXT/CSV/XLSX)
- Scan entire subnets (CIDR /24) for blacklisted IPs
- Pull WHOIS, DNS records, and SSL certificate details with one click
- Validate SPF / DKIM / DMARC email authentication
- Check if a server is up or down with DNS, port, and HTTP checks
- Register assets and run all checks with configurable toggles
- Schedule periodic checks with email, Slack, Discord or webhook alerts for listings, recoveries, outages and expiry
- Keep an activity log of every change and compare any two checks
- Export results to CSV and track history with charts
- Switch between light and dark mode
No vendor lock-in. No paid tiers. Self-host it and own your data.
Features
| Feature | Description | Auth required |
|---|---|---|
| Needs-attention dashboard | Listings, invalid/expiring SSL, expiring domains, servers down, weak email security, overdue checks, scheduler status | Yes |
| Activity log | Every detected change (listed, delisted, down, recovered, expiring) with severity filters | Yes |
| Alerts | Email and webhook (Slack/Discord formatted) for new listings, removals, outages and expiry warnings, with a test button | Yes |
| Blacklist Quick Check | Scan hostname/IP against 60 DNSBL providers (rate limited for anonymous use) | No |
| Bulk Check | Check up to 300 IPs/domains at once, from a list or a TXT/CSV/XLSX file | Yes |
| Subnet / CIDR Check | Scan an entire IP range (max /24) against key DNSBL providers | Yes |
| AbuseIPDB | IP reputation score, abuse reports, ISP & geolocation | Yes |
| WHOIS Lookup | Domain registrar, dates, name servers, registrant info | Yes |
| DNS Record Viewer | A, AAAA, MX, TXT, CNAME, NS, SOA, PTR records | Yes |
| SSL Certificate Checker | Validity, expiry, issuer, cipher, SAN list | Yes |
| SPF / DKIM / DMARC | Email authentication validation with A-F grading, custom DKIM selectors | Yes |
| Is Server Up? | DNS resolution, port scan (80/443), HTTP status & response time | Yes |
| CSV Export | Download blacklist and subnet results as CSV | - |
| Bulk Asset Import | Add up to 300 assets at once from a pasted list or TXT/CSV/XLSX file | Yes |
| CIDR Import | Import an IP range (max /24) as monitored assets from the UI | Yes |
| Assets | Register domains/IPs, run all checks with per-asset toggles, edit them later | Yes |
| Bulk Actions | Select many assets to re-check (in the background), toggle monitoring/alerts or delete; table view, sorting, CSV export | Yes |
| Check History | Browse past checks and see which blacklists were added or removed | Yes |
| Asset Detail View | Tabbed results for every check type with summary cards | Yes |
| Scheduled Monitoring | Automatic re-checks on a global or per-asset interval, with a "check due assets now" button | Yes |
| Historical Charts | Visual blacklist history per monitored asset | Yes |
| Re-check Asset | Re-run all enabled checks on any asset with one click | Yes |
| Delist Tracking | Links to each provider's removal page and tracks requested removals | Yes |
| Search & Filter | Search assets by hostname, type or description; filter by needs attention, listed or clean | Yes |
| Auto-refresh | Configurable auto-refresh (30s/1m/5m) on Dashboard and Assets | Yes |
| Copy to Clipboard | One-click copy on IPs, DNS records, WHOIS data, SSL details | - |
| Relative Timestamps | "2 hours ago" with full datetime tooltip on hover | - |
| Dark Mode | Toggle between light and dark themes, persisted to localStorage | - |
| Responsive Layout | Collapsible sidebar with hamburger menu on mobile | - |
| Favicon Alert | Red badge on favicon when any asset is blacklisted | - |
| Users | Admins add users, grant admin, deactivate and reset passwords; everyone can change their own password | Yes |
| Data Retention | Optionally delete history older than 30–365 days | Yes |
| Command Palette | Ctrl/Cmd + K to jump to any asset, page or setting, or check a domain/IP | Yes |
| API Documentation | Swagger UI & ReDoc for all endpoints | No |
| Composite Risk Score | Runs every scanner in parallel and reduces the results to one weighted 0-100 posture score with a prioritised fix list | Yes |
| HTTP Security Headers | Grades CSP, HSTS, frame options, referrer and cross-origin policies A+ to F, plus cookie flags and version disclosure | Yes |
| TLS / Cipher Audit | Separate handshake per TLS version to find deprecated protocols (TLS 1.0/1.1), weak ciphers and missing forward secrecy | Yes |
| Port Scanner | 50 commonly exposed ports with service identification, banner grab and risk tiering (exposed database, RDP, Redis) | Yes |
| Exposed Files & Paths | Finds readable .env, .git/config, SQL dumps, backups, Spring Actuator and unprotected admin panels, with soft-404 filtering |
Yes |
| DNS Security Audit | DNSSEC chain validation, zone transfer (AXFR) test against every nameserver, CAA records and wildcard detection | Yes |
| Subdomain Enumeration | Certificate Transparency logs plus a DNS wordlist, with wildcard filtering and subdomain-takeover detection | Yes |
| Technology Fingerprint | Detects web server, framework, CMS, WAF/CDN and analytics from headers, cookies and page markers, with evidence | Yes |
| Typosquat Detector | Generates lookalike domains across seven techniques and reports which are registered, live and able to send email | Yes |
| Snort3 Alert Ingestion | Receives alerts from Snort3 sensors in alert_json, alert_fast or alert_csv format, deduplicates floods and correlates them to monitored assets | Yes |
| Snort3 Rule Generator | Turns blacklisted assets, repeat attackers and lookalike domains into deployable Snort3 rules, with a syntax validator | Yes |
| Sensor Health | Lists every reporting sensor and flags one that has gone quiet for over an hour | Yes |
| Role-Based Access Control | Three roles (viewer, analyst, admin) enforced server-side on every request | Yes |
| API Keys | Scoped machine credentials for sensors and automation; only a SHA-256 digest is stored | Yes |
| Audit Trail | Append-only record of logins, failed logins, user and role changes, key issuance and alert triage, with source IP | Yes |
| Prometheus Metrics | /metrics endpoint with request counters and latency histograms, labelled by route template | No |
| Nmap | Five scan profiles with service and version detection, run inside the container | Yes |
| Ncat | Service banner grabbing, including over TLS with SNI, with protocol probes | Yes |
| OpenVAS / Greenbone | Live over GMP: start a scan, poll it, pull the report. XML import also supported | Yes |
| Rapid7 Nexpose / InsightVM | Live over REST API v3 against your licensed console | Yes |
| MBSA, LanGuard, Nipper, Core Impact | Live via the Windows connector, which runs them locally and pushes results back | Yes |
| Contextual risk prioritisation | Dempster-Shafer evidence fusion across all eight scanners, weighted by learned per-tool reliability, multiplied by live exploitation evidence from Snort3, suppressed by a false-positive model trained on your own triage, and measured against a CVSS-only baseline | Yes |
| Cross-tool correlation | Groups findings by CVE fingerprint to show where independent scanners agree, and where they disagree on severity | Yes |
Quick Start
Docker (recommended)
git clone https://github.com/bekkaze/abusebox cd abusebox cp backend/.env.example .env # configure your settings docker compose up --build
Open http://localhost:3000 and you're ready to go.
Default login:
admin/password123. Change it in Settings right after the first sign-in.To open AbuseBox from another machine, add that hostname or IP to
VITE_ALLOWED_HOSTSandAPP_CORS_ALLOWED_ORIGINSin.env.
Manual Setup
Click to expand
Prerequisites: Python 3.11+, Node.js 20.19+, Yarn
Backend:
cd backend
cp .env.example .env
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8100 --reloadFrontend (new terminal):
cd frontend
cp .env.example .env
yarn install
yarn devOpen http://localhost:3000.
Upgrading from v1.1.x
Back up your data first, then pull the new version. The database is migrated automatically on start.
# The volume is named <folder>_abusebox-data; `docker volume ls` shows it. docker run --rm -v abusebox_abusebox-data:/data -v "$PWD":/backup alpine tar czf /backup/abusebox-data.tgz -C /data . git pull docker compose up -d --build
Things that changed:
- Everyone is signed out once. Older Docker setups used a published JWT secret; v1.2.0 generates a private one (or uses your
APP_SECRET_KEY). - Change the admin password. Older Docker setups ignored
DEFAULT_ADMIN_PASSWORDfrom.env, so the admin account probably still usespassword123. A banner reminds you until you change it in Settings → Security. - The
/tools/*API needs a token. Only/blacklist/quick-check/stays public. See API Endpoints. - No public sign-up. Admins add users in Settings → Users.
- The scheduler is on by default unless you turned it off in Settings before.
Snort3 integration
AbuseBox works in both directions with Snort3: alerts flow in for correlation, and detection rules flow back out.
Snort3 sensor AbuseBox Snort3 sensor
| | |
| alert_json --> agent --> | correlate to assets |
| | deduplicate floods |
| | triage queue |
| | |
| | generate rules ---------> |
| | from blacklists, |
| | repeat attackers, |
| | lookalike domains |
Sending alerts from a sensor
-
Configure Snort3 to write JSON alerts. A working
snort.luaand a starterlocal.rulesare indeploy/snort/:alert_json = { file = true, limit = 100, fields = 'timestamp pkt_num proto pkt_gen pkt_len dir src_addr src_port dst_addr dst_port service rule action msg priority class' }
-
Create an API key in Administration → API keys with the
snort:ingestscope. The plaintext is shown once; only a SHA-256 digest is stored. -
Run the agent on the sensor host. It needs nothing beyond Python 3:
export ABUSEBOX_URL=https://abusebox.example.com export ABUSEBOX_API_KEY=abx_... ./deploy/snort3-agent.py --log /var/log/snort/alert_json.txt --sensor dmz-01
The agent checkpoints its byte offset and the log's inode, so it resumes after a restart, follows log rotation, and retries with backoff when the server is unreachable rather than dropping alerts.
No sensor to hand? Use Import log on the Intrusion Alerts page to replay an
existing alert file, or POST raw text to /snort/ingest/raw/.
What happens to an alert
- Deduplicated on
sensor|gid:sid|src|dstinside a time window. A port scan produces thousands of identical alerts; the first is stored and the rest incrementhit_count. Ports are excluded from the key on purpose, since a scan varies the port on every packet. - Correlated to a monitored asset when either endpoint matches. Domain assets are resolved, and that IP-to-asset index is cached for five minutes so ingest stays fast.
- Graded from Snort's priority: 1 to critical, 2 to high, 3 to medium, 4 and above to low.
Generating rules
The Rule Generator builds a deployable ruleset from what AbuseBox has already found:
| Source | Rule produced |
|---|---|
| Blacklisted assets | Alert on traffic involving the asset |
| Repeat attackers | Alert on source IPs that keep triggering critical/high alerts |
| Lookalike domains | Alert on DNS queries and HTTP Host headers for the lookalike |
Generated SIDs start at 9000000 - clear of the vendor range (up to 1000000) and the conventional local range (1000000-1999999) - so a rule update never collides. Private and reserved addresses are never turned into rules, because such a rule would alert on ordinary internal traffic.
Domain rules match the longest label rather than the dotted name: DNS puts
length-prefixed labels on the wire, so the bytes for paypa1.com are
\x06paypa1\x03com\x00 and the dotted string never appears in the packet.
# Deploy an exported ruleset cp abusebox.rules /etc/snort/rules/ # add to snort.lua: include $RULE_PATH/abusebox.rules snort -c /etc/snort/snort.lua -R abusebox.rules -T # validate before reload
The built-in validator catches the structural mistakes Snort rejects, but it is
not a substitute for snort -T: only Snort can confirm a rule loads against
your configuration.
Running Snort3 with Docker Compose
docker compose --profile snort up -d
Snort has to see the traffic it inspects, which a bridge network hides, so that
profile uses the host network namespace with NET_ADMIN/NET_RAW and reads
SNORT_IFACE. On Docker Desktop (macOS/Windows) there is no host interface to
tap: run Snort3 on the monitored host itself and point only the agent at
AbuseBox.
Enterprise deployment
Roles
Authorisation is enforced on the server. The interface also hides what a role cannot do, but that is a convenience, not the control: a viewer who crafts the request by hand still gets a 403.
| Role | Can |
|---|---|
viewer |
Read dashboards, scan results and alerts. Change nothing. |
analyst |
Run scans, manage assets, acknowledge alerts, generate rules. |
admin |
Everything, plus users, API keys, settings and retention. |
New accounts default to viewer. Accounts created before roles existed are
assigned one at startup from their previous admin flags, so an upgrade never
locks out an administrator. An admin cannot demote or deactivate their own
account, and the last active admin cannot be removed.
API keys
Sensors and CI jobs cannot complete an interactive login, so they authenticate
with a scoped key in the X-API-Key header. Keys carry snort:ingest,
scan:read or scan:run; usage (count, last IP, last time) is tracked so an
unused or compromised key is visible. Revoked keys are kept rather than deleted,
so the audit trail still resolves which credential performed a past action.
Audit trail
Append-only, admin-only, and separate from the asset activity log. It records logins and failed logins (by attempted username, so credential stuffing is visible), user and role changes, key issuance and revocation, alert triage and rule exports - each with actor, source IP, user agent and outcome.
Retention is deliberately manual (Administration → Data retention) rather than automatic, so deleting audit history is an attributable act. That operation is itself audited.
Self-hardening
AbuseBox ships a scanner that grades other people's security headers, so it
sets the same ones on its own responses: a strict Content-Security-Policy,
X-Frame-Options, nosniff, Referrer-Policy, Permissions-Policy and the
cross-origin isolation headers. The Server banner is suppressed.
HSTS is sent only when the request arrived over TLS. Sending it over plain
HTTP would tell a browser to refuse http://localhost for a year, which breaks
local access in a way that persists long after the header is removed.
PostgreSQL
SQLite is fine for a single operator but serialises writers, and the background scheduler writes alongside the API. For anything multi-user:
docker compose --profile postgres up -d # then in .env: DATABASE_URL=postgresql+psycopg2://abusebox:<password>@postgres:5432/abusebox
Metrics
GET /metrics exposes Prometheus counters and latency histograms. It is
unauthenticated on purpose: a scraper is usually a sidecar that cannot hold a
credential, and the output is counters only, with no scan results, hostnames or
alert contents. Restrict it at the network layer if your deployment needs that.
Series are labelled by matched route template, not raw path, so
/snort/alerts/{alert_id} is one series rather than one per alert id.
Not included
Stated plainly, because a half-built version of any of these would be worse than none: SSO/SAML/OIDC, multi-tenancy (one organisation per deployment) and HA/clustering (a single API container; Postgres can be made highly available independently). Rate limiting currently covers login and the public blacklist check, not every endpoint.
External scanners
Eight industry tools feed one normalised finding model. How each is driven depends on what the tool actually permits - stated plainly, because the difference matters when planning a deployment.
| Tool | How it runs | What you need |
|---|---|---|
| Nmap | In this container | Nothing. Installed in the image. |
| Ncat | In this container | Nothing. Installed in the image. |
| OpenVAS / Greenbone | Live over GMP | Your own Greenbone server, or the bundled compose profile |
| Rapid7 Nexpose / InsightVM | Live over REST API v3 | Your licensed console |
| Microsoft MBSA | Live via the Windows connector | A Windows host with MBSA installed |
| GFI LanGuard | Live via the Windows connector | A Windows host with LanGuard installed |
| Titania Nipper | Live via the Windows connector | A licensed host with Nipper installed |
| Core Impact | Live via the Windows connector | A licensed host with Core Impact installed |
Every one of them is driven by the platform. Nothing is import-only, though a manual XML upload still works for all eight and goes through the same parser, so both routes produce identical findings.
Nmap and Ncat
Both run inside the backend container and need no configuration.
Nmap offers five profiles - Quick, Standard, Service detail, Vulnerability scripts and Host discovery - each with its own timeout. Callers pick a profile; they never supply nmap arguments. That removes a whole class of attacks based on nmap's own options, and keeps scans predictable.
Ncat grabs service banners, including over TLS with SNI, and can send a protocol probe to services that stay silent until spoken to.
Safety, since this is where user input reaches a subprocess:
- An argument list, never a shell string, so there is nothing to inject into
- Named profiles only; no raw flags are ever accepted
- Targets pass the same public-address guard as the rest of the platform, so loopback, link-local and cloud-metadata addresses are refused
- Output goes to stdout (
-oX -), so no user-controlled path is written - Every profile is bounded by a timeout
OpenVAS / Greenbone (live over GMP)
Speaks the Greenbone Management Protocol directly: XML over a TLS socket on
port 9390, the same protocol gvm-tools uses. Implemented against the
standard library rather than python-gvm, because the surface used here is
six commands and a security tool benefits from one less dependency.
# Stand up Greenbone Community Edition docker compose --profile openvas up -d # The first start downloads a multi-GB feed. Allow 30-60 minutes.
Then in .env:
OPENVAS_HOST=greenbone OPENVAS_USERNAME=admin OPENVAS_PASSWORD=your-password
From Network Scanning -> OpenVAS you can start a scan, poll its progress and pull the report. A scan runs for minutes to hours, so the API starts the work and returns a task id rather than holding an HTTP request open.
The live pull and a manual XML upload go through the same parser, so both produce identical findings.
Rapid7 Nexpose / InsightVM (live over REST)
Drives the console you already licence, via API v3.
NEXPOSE_URL=https://console.example.com:3780 NEXPOSE_USERNAME=admin NEXPOSE_PASSWORD=your-password
Scans run against a site, not a free-form address: the console owns what is in scope, which is the right place for that decision. It also means this integration cannot point a licensed scanner at something the console was never configured to assess.
MBSA, LanGuard, Nipper and Core Impact (live via the connector)
These four are licensed desktop products and cannot run in a Linux
container. What they do have is a scriptable interface, so
deploy/windows-connector.py runs on the
Windows host where they are installed, invokes them, and posts the results
back. Standard library only, so there is nothing to install on the scanning
host.
setx ABUSEBOX_URL https://abusebox.example.com setx ABUSEBOX_API_KEY abx_... python windows-connector.py --tool all --target localhost python windows-connector.py --tool nipper --config-file C:\configs\router.conf
Create the key in Administration -> API keys with the snort:ingest
scope. Run it from Task Scheduler and the findings stay current without
anyone exporting a report by hand.
Core Impact is the awkward one, because its automation surface varies by version and licence, so the connector offers two modes:
rem Drive the console's Python automation to run an RPT python windows-connector.py --tool core-impact --target 192.0.2.10 rem Or watch the console's report folder and ship anything new python windows-connector.py --tool core-impact --report-dir "C:\Core Impact\reports" eports"
Harvest mode is checkpointed by modification time, so a scheduled run does not re-upload the same assessment every time it fires. Use it if you are unsure: it works on every licence, including ones with scripting disabled, and still means nobody exports a report by hand.
Importing a report
Any supported tool's XML export can be dropped into Network Scanning -> Import. The format is auto-detected from the document, so you do not have to say which tool produced it.
Two detection notes worth knowing: Nipper and OpenVAS both use <report> as
their root element, so Nipper is identified by its <part><section>
structure and OpenVAS is required to show an actual <result>. Nexpose must
be exported with the XML Export 2.0 template, which is the one that
includes the <VulnerabilityDefinitions> block the parser joins against.
HTML and PDF reports cannot be parsed. Maximum 8 MB.
One severity scale
Eight tools means eight severity vocabularies: Nexpose grades 0-10, OpenVAS says "High" and also gives CVSS, MBSA says "Check failed", Nipper says "Critical", and nmap has no severity concept at all.
Two rules keep the mapping honest:
- CVSS wins when present. A numeric score is objective; a vendor's word for it is partly a marketing decision. The original label is still stored on the finding, so nothing is lost.
- Unknown maps to info, never to critical. A parser meeting a severity string it does not recognise must not manufacture an emergency.
Cross-tool correlation
This is what the normalisation is for. Findings are grouped on a fingerprint keyed on the CVE where there is one - the only identifier different vendors reliably agree on - and on a normalised title where there is not.
Findings -> Confirmed by more than one tool then answers the question that actually matters: where do independent scanners agree? Two tools reporting the same CVE on the same host and port is a far stronger signal than either alone, and a finding only one tool saw is the first thing to verify by hand.
Where tools disagree about how bad something is, that disagreement is shown rather than silently resolved in favour of one of them.
Contextual risk prioritisation
Eight scanners produce findings that repeat and contradict each other, and the usual answer - sort by CVSS - cannot express the three things that decide what actually gets fixed first: whether the finding is real, whether anyone is attacking it, and whether your own analysts would dismiss it.
Dashboard -> Risk Prioritisation answers those separately and shows its working:
- Is it real? Dempster-Shafer evidence fusion across every scanner that looked, each discounted by a reliability figure learned from your triage. The output is a belief interval, not a point score, so "one tool said so and nothing corroborated it" is visibly different from "four tools agree".
- Is anyone exploiting it? Snort3 alerts are joined to findings on host and port. A host appearing as the source of attack traffic is treated as a suspected compromise and listed above everything else.
- Would an analyst dismiss it? A logistic-regression model trained on your own confirmed/false-positive decisions, which refuses to train on fewer than 20 labels rather than guessing.
- Does it beat sorting by CVSS? An evaluation harness reports precision@k, NDCG and average precision against a CVSS-only baseline, plus ablations for each component, scored on analyst triage as ground truth.
A medium under live attack can outrank a critical nobody is touching. That inversion is the point, and the rationale for every position is shown on the finding.
Full method, justification and limitations ->
# generate a demonstration estate (fabricated data, throwaway database)
DATABASE_URL=sqlite:////tmp/demo.db python scripts/seed_demo.py --hosts 40Automated response
Everything else in AbuseBox answers questions. This acts on the answers.
Dashboard -> Automated Response blocks the addresses attacking you, contains hosts that have started attacking other people, writes the remediation steps for the findings it ranked, re-scans to confirm a fix worked, and notifies when something needs a human now.
Two decisions make that safe enough to ship.
Autonomy is gated on evidence. A SOAR playbook fires on a boolean: one bad detection and a thoroughly corroborated one authorise the same action. Here the belief interval from the fusion engine decides how much autonomy an action gets
- proportional to confidence, inversely proportional to how much damage it could do. Sending a webhook needs 25% belief; cutting a host off the network needs 85%, almost no unresolved evidence, and tools that agree. The gate reports which criterion failed, so "belief 0.61, needs 0.85" replaces "not confident enough". Evidence of active exploitation raises an item's priority and never lowers the bar to act on it.
The platform holds no firewall credentials. Enforcement is pull-based: it publishes what is in force and your perimeter fetches it on a timer. Giving AbuseBox a firewall token would make this service the most valuable target on your network, since anything that can write arbitrary rules is worth more than the findings it stores. Pulling inverts that, and revoking the whole capability is deleting one cron line.
# nftables - replaces the set atomically, so re-pulling is safe */5 * * * * curl -sf -H "X-API-Key: abx_..." https://abusebox.example.com/response/feed/nftables | nft -f -
Nothing is ever sent to an attacking address. Every artefact is a rule for your own perimeter: no scan-back, no probe, no retaliation. You cannot block your own assets or a public resolver. Everything applied automatically expires, automatic actions are capped per hour, and every decision keeps a snapshot of the evidence that produced it.
The default mode is observe: it records what it would do and applies nothing.
Run it that way for a fortnight, read the plan each morning, then decide.
Method, guardrails and limitations ->
Configuration
Create a .env file in the project root (Docker Compose reads it automatically, and values in it override the compose defaults):
# Leave empty to auto-generate a secret (stored next to the database) APP_SECRET_KEY= APP_DEBUG=false APP_CORS_ALLOWED_ORIGINS=http://localhost:3000 VITE_ALLOWED_HOSTS=localhost,127.0.0.1 DATABASE_URL=sqlite:///./app.db # ignored by Docker Compose (always uses the data volume) # Default admin, created on first start only DEFAULT_ADMIN_USERNAME=admin DEFAULT_ADMIN_PASSWORD=password123 DEFAULT_ADMIN_EMAIL=admin@abusebox.local DEFAULT_ADMIN_PHONE=11111111 # Optional: AbuseIPDB (free key at https://www.abuseipdb.com/account/api) ABUSEIPDB_API_KEY= # Scheduled monitoring SCHEDULER_ENABLED=true SCHEDULER_INTERVAL_MINUTES=360 # Automated response. The default changes nothing: it records what it would do # and applies nothing. Read docs/automated-response.md before changing it. RESPONSE_MODE=observe # observe | propose | auto RESPONSE_NEVER_BLOCK= # comma-separated; your upstreams, VPN egress RESPONSE_AUTO_EXPIRY_HOURS=24 # everything automatic lifts itself RESPONSE_MAX_AUTO_PER_HOUR=10 # ceiling, so a forged-source flood cannot # have the platform write rules for an attacker RESPONSE_ALLOW_UNENROLLED_ISOLATION=false # isolating a private address you have not enrolled RESPONSE_DEMO_ALLOW_TESTNET=false # demonstration only; must stay false in production # Email alerts (optional) SMTP_HOST= SMTP_PORT=587 SMTP_USERNAME= SMTP_PASSWORD= SMTP_FROM_EMAIL= SMTP_USE_TLS=true # Webhook alerts (optional) WEBHOOK_URL=
| Variable | Description | Required |
|---|---|---|
APP_SECRET_KEY |
JWT signing secret. If unset, a random one is generated and saved as .secret_key next to the database |
No |
APP_DEBUG |
Show error tracebacks (development only) | No |
APP_CORS_ALLOWED_ORIGINS |
Comma-separated browser origins allowed to call the API | No |
DATABASE_URL |
Database connection string (SQLite default) | No |
ABUSEIPDB_API_KEY |
Enables AbuseIPDB reputation checks | No |
SCHEDULER_ENABLED |
Run periodic background checks (default: true; can also be changed in Settings) |
No |
SCHEDULER_INTERVAL_MINUTES |
Check interval in minutes (default: 360) | No |
SMTP_HOST |
SMTP server for email alerts | No |
WEBHOOK_URL |
Webhook URL for alerts (Slack and Discord URLs get chat messages). A URL set in Settings → Notifications takes precedence | No |
DNSBL_NAMESERVERS |
Comma-separated DNS resolvers for blacklist lookups. Spamhaus and some others refuse public resolvers; point this at your own recursive resolver for complete results | No |
DNS_TOOLS_NAMESERVERS |
Resolvers for the DNS audit, subdomain and typosquat scanners. Defaults to public resolvers, because Docker's embedded DNS does not answer DS/DNSKEY/CAA queries | No |
DNS Records, SSL Checker, WHOIS, SPF/DKIM/DMARC, and Server Status work out of the box with no API keys.
Frontend config (frontend/.env):
| Variable | Description |
|---|---|
VITE_BASE_URL |
Backend URL for Vite proxy (default: http://localhost:8100) |
VITE_ALLOWED_HOSTS |
Hostnames the dev server answers to (default: localhost,127.0.0.1) |
API Endpoints
Only the blacklist quick check is public (rate limited to 10 requests per minute per IP). Every other endpoint needs a bearer token from POST /user/login/:
GET /blacklist/quick-check/?hostname=example.com # public
GET /tools/abuseipdb/?hostname=8.8.8.8
GET /tools/whois/?hostname=example.com
GET /tools/dns/?hostname=example.com
GET /tools/ssl/?hostname=example.com
GET /tools/email-security/?hostname=example.com&dkim_selectors=s1,s2
GET /tools/server-status/?hostname=example.com
GET /tools/subnet/?cidr=203.0.113.0/24
GET /tools/risk-score/?hostname=example.com # all scanners, one score
GET /tools/security-headers/?hostname=example.com
GET /tools/tls-audit/?hostname=example.com
GET /tools/port-scan/?hostname=example.com&ports=22,80,443
GET /tools/exposure-scan/?hostname=example.com
GET /tools/dns-audit/?domain=example.com
GET /tools/subdomains/?domain=example.com&wordlist=true
GET /tools/fingerprint/?hostname=example.com
GET /tools/typosquat/?domain=example.com
POST /snort/ingest/ # sensor, via X-API-Key
POST /snort/ingest/raw/ # raw alert_json or alert_fast text
POST /snort/upload/ # upload an alert log
GET /snort/alerts/?severity=critical&acknowledged=false
GET /snort/alerts/stats/?hours=24
POST /snort/alerts/acknowledge/
GET /snort/sensors/
POST /snort/rules/generate/
GET /snort/rules/export/ # downloads abusebox.rules
POST /snort/rules/validate/
GET /admin/overview/ # admin only
GET /admin/api-keys/ POST /admin/api-keys/ DELETE /admin/api-keys/{id}
GET /admin/audit-log/?action=auth&outcome=failure
POST /admin/retention/run/
GET /metrics # Prometheus, unauthenticated
GET /scanners/catalog/ # which tools, and how each is driven
POST /scanners/nmap/ # live scan
POST /scanners/ncat/ # live banner grab
POST /scanners/import/ # any supported report, auto-detected
GET /scanners/findings/?severity=critical&open_only=true
GET /scanners/correlation/?min_sources=2 # confirmed by 2+ tools
GET /scanners/openvas/status/ POST /scanners/openvas/scan/
GET /scanners/openvas/task/{id} POST /scanners/openvas/report/{id}/import/
GET /scanners/nexpose/status/ GET /scanners/nexpose/sites/
POST /scanners/nexpose/scan/ POST /scanners/nexpose/scan/{id}/import/
POST /tools/bulk-check/ # {"hostnames": ["example.com", "8.8.8.8"]}
POST /tools/bulk-check-upload/ # multipart file: .txt, .csv or .xlsx
GET /tools/export/blacklist/?hostname=example.com
GET /tools/export/subnet/?cidr=203.0.113.0/24
POST /hostname/bulk/ # up to 300 assets
POST /hostname/cidr-import/
POST /hostname/{id}/recheck/
POST /hostname/bulk-action/ # {"ids": [1, 2], "action": "recheck"}
GET /hostname/list/?include_result=false
GET /hostname/{id}/checks/{check_id}
GET /hostname/{id}/events/
GET /events/?severity=critical
GET /settings/scheduler/status/
POST /settings/scheduler/run/ # admin only: check due assets now
PUT /settings/notifications/ # admin only
POST /settings/notifications/test/ # admin only
POST /user/change-password/
POST /user/create/ # admin only
GET /user/list/ # admin only
PATCH /user/{id}/ # admin only
TOKEN=$(curl -s -X POST localhost:8100/user/login/ -H 'Content-Type: application/json' \ -d '{"username":"admin","password":"your-password"}' | jq -r .access) curl -s -H "Authorization: Bearer $TOKEN" "localhost:8100/tools/dns/?hostname=example.com"
Full interactive docs available after startup:
- Swagger UI:
http://localhost:8100/swagger/ - ReDoc:
http://localhost:8100/redoc/
Tech Stack
| Layer | Technology |
|---|---|
| Backend | Python 3.11, FastAPI, SQLAlchemy 2, PyJWT, dnspython |
| Frontend | React 18, React Router 7, Vite 6, Tailwind CSS 3, Headless UI, Recharts |
| Database | SQLite (swappable via DATABASE_URL) |
| Deployment | Docker + Docker Compose; images published to GHCR |
| CI | GitHub Actions: backend tests, frontend lint and build |
Project Structure
abusebox/
├── backend/
│ ├── app/
│ │ ├── api/routers/ # auth, blacklist, dmarc, events, hostname, settings, tools
│ │ ├── core/ # config, JWT security, SSRF guards, client IP, UTC helpers
│ │ ├── db/ # SQLAlchemy session, seed data
│ │ ├── models/ # users, assets, check history, events, DMARC, settings
│ │ ├── schemas/ # Pydantic schemas
│ │ └── services/ # checks: dnsbl, abuseipdb, dns, ssl, whois, email security,
│ │ # server status, subnet, DMARC parser, export
│ │ # monitoring: monitoring (save + events + alerts), health,
│ │ # events, scheduler, notifications
│ └── tests/ # pytest (offline suite + live DNSBL cross-checks)
├── frontend/
│ └── src/
│ ├── pages/ # Landing, Login, Dashboard, Assets, Asset detail, Activity,
│ │ # Settings, Check & Lookup tools
│ ├── components/ # shared UI (forms, alerts, activity feed, command palette),
│ │ # dashboard, blacklist tables, dialogs
│ ├── services/ # API clients, auth, theme, current user
│ └── routes/ # React Router config
├── files/ # logo and README screenshots
├── docker-compose.yml
└── .env # your configuration (not committed)
Releases
| Version | Date | Highlights |
|---|---|---|
| v1.2.0 | October 7, 2026 | Needs-attention dashboard, activity log, recovery/outage/expiry alerts (Slack, Discord, webhooks), bulk actions and table view, check history, user management, command palette; scheduler fix (#20), security hardening, dependency updates, accessibility and dark mode overhaul |
| v1.1.2 | March 26, 2026 | Bulk asset import, CIDR import, auto-refresh auth, persistent DB, DNSBL false positive fix, community bug fixes |
| v1.1.1 | March 25, 2026 | UX polish, responsive mobile layout, asset re-check, code splitting, security fixes |
| v1.1.0 | March 23, 2026 | Asset management, DNS/SSL/DMARC tools, bulk & subnet check, scheduled monitoring, dark mode, 60+ DNSBL providers |
| v1.0.1 | March 19, 2026 | AbuseIPDB, WHOIS lookup, server status checker, security hardening |
| v1.0.0 | March 2, 2026 | Initial release — DNSBL monitoring, dashboard, delist workflow |
See CHANGELOG.md for full details.
Contributing
Contributions are welcome! Please read CONTRIBUTING.md before submitting a PR.
License
MIT — see LICENSE for details.







