Download the PHP package monovm/abuseai without Composer

Abuse AI

AI-powered abuse management platform for hosting companies and ISPs.

Receives, triages, scores, and actions abuse reports with AI at every key step. Built with Laravel, Livewire, and Claude/OpenAI.

Deploy in one click

Each button builds the same Dockerfile that Docker Compose uses and provisions the app, a queue worker, and PostgreSQL. Render and Heroku add Redis too; on DigitalOcean you supply it (details in Deploy to the cloud). Prefer your own host? docker compose up -d — see Installation.

Built by MonoVM — main sponsor of this project.

License: Apache License 2.0 — open source. You may freely use, copy, modify, and redistribute this software for any purpose, including commercial and managed-service use, subject to the conditions of the license. See LICENSE for the full terms.

Reporting a security issue? See SECURITY.md. Want to contribute? See CONTRIBUTING.md.

Table of Contents

• Overview
• Architecture
• Pipeline Flow
• Features
• Installation
• Configuration
• Usage Guide
• IP Inventory & Reputation
• Email System
• API Reference
• Artisan Commands
• Scheduler & Automation
• Tech Stack
• Contributing
• License

Overview

Abuse AI is a centralized abuse desk that:

1. Ingests reports from email, API, webhooks, web form, and feeds
2. Classifies them with AI (type, severity, noise filtering, translation)
3. Matches target IPs against your IP inventory
4. Creates cases with severity scoring and SLA tracking
5. Enriches with threat intelligence (AbuseIPDB, VirusTotal, Shodan, DNSBL, Microsoft SNDS)
6. Automates actions (suspend, block, escalate, notify)
7. Communicates via branded email (Mandrill) with AI-drafted replies
8. Monitors IP reputation across 6 data sources continuously

Architecture

Pipeline Flow

When an email arrives:

When a web form / API report arrives:

Reputation scan (every 6 hours):

Features

Case Management

• Case queue with filter/sort by status, type, severity, search
• Case detail: reports, timeline, threat intel, AI panel, sent emails
• Manual case creation with IP inventory lookup
• Status workflow: Open → Investigating → Actioned → Resolved → Closed
• SLA deadlines per severity level

12 Abuse Types

Severity Scoring Formula

Action thresholds:

• Score ≥ 20 → Flag for review
• Score ≥ 50 → Warn customer
• Score ≥ 80 → Auto-suspend

AI Integration (Claude / OpenAI)

• Triage: Classify abuse type, extract IOCs, filter noise, translate non-English
• Intelligence: Re-score severity, detect patterns, analyze evidence, profile customers
• Communications: Draft reporter replies, customer notices, handle appeals, summarize cases
• Switch between Claude and OpenAI from admin settings
• All AI calls logged in audit trail

IP Inventory

• Add IPs individually, by CIDR range, or dash range
• Bulk import (CSV, one per line)
• Tags: server name, datacenter, rack, customer link
• Status: active, reserved, decommissioned
• Only IPs in active inventory create cases from reports

IP Reputation System (6 Collectors)

Score thresholds:

• 80-100: Good (green)
• 50-79: Fair (yellow)
• 30-49: Poor (orange)
• <30: Critical (red) → auto-create case

Multi-Brand Email

• Multiple brands (each with its own identity, e.g., "Acme Hosting", "Brand B")
• Each brand: from name, from email, signature, footer, logo
• Per-brand Mandrill API key
• Multiple POP3/IMAP connections, each linked to a brand
• Reply from case detail with brand selector
• Email threading (In-Reply-To headers)

Email Loop Prevention

• Skip emails from our own addresses
• Detect replies to our ACK emails → add as follow-up (no new case)
• Detect ISP auto-forward quoting our content → link to existing case
• Skip auto-replies, OOO, delivery failures, mailer-daemon
• RFC 3834 Auto-Submitted header detection
• Content dedup (strips our template, checks if meaningful content remains)

Automation Rules

• Configurable trigger events: report_received, score_changed, time_elapsed
• Conditions: field operators (=, !=, >, >=, <, <=, in)
• Actions: suspend, block_ip, escalate, notify (email/slack/pagerduty)
• Priority ordering, abuse type filtering, minimum score threshold

Audit Trail

• Every state change logged (old/new values)
• Every AI call logged (prompt + response, provider + model)
• Entity-based filtering (AbuseCase, AbuseReport, Customer, AI)
• Actor tracking (who did what)

Installation

Run with Docker (recommended)

The fastest way to get the full stack — web UI, queue workers, scheduler, PostgreSQL, and Redis — running:

Open http://localhost:8000. To start with an admin login already seeded:

Prebuilt multi-arch images are on Docker Hub (monovmcom/abuseai.io) and GHCR (ghcr.io/monovm/abuseai). See docs/docker.md for the full guide.

Deploy to the cloud

The one-click buttons are at the top of this README. What each target gives you:

• Render — fully one-click: app, worker, PostgreSQL, and Redis all come from render.yaml. Paste an APP_KEY when prompted.
• Heroku — fully one-click via app.json + heroku.yml: provisions Heroku Postgres and Heroku Key-Value Store, migrates in the release phase, seeds an admin account after deploy. Both dynos are paid — Heroku has no free tier.
• DigitalOcean — .do/deploy.template.yaml provisions the app, worker, and a dev PostgreSQL. One manual prerequisite: App Platform's dev databases are PostgreSQL-only, so create a managed Valkey database first and paste its connection string as REDIS_URL when the button prompts. Horizon and report de-duplication both require Redis.
• Railway — Dockerfile deploy via railway.json; add PostgreSQL and Redis from the dashboard.
• Coolify / Dokku / any Docker host — runs the bundled docker-compose.yml as-is.

Step-by-step instructions for each: docs/docker.md.

Requirements (manual install)

• PHP 8.4+
• MySQL 8.0+ or PostgreSQL 16+
• Composer 2.x
• Node.js 18+
• Redis (optional, for queue workers)

Manual installation steps

Admin Accounts (seeder)

php artisan db:seed runs the AdminSeeder, which creates two admin accounts ([email protected], [email protected]). Each gets a strong random password that is printed once to the console — copy it from the seed output, it is not stored anywhere else:

To pin a known password instead (CI, throwaway demo), set SEED_ADMIN_PASSWORD before seeding. Re-running the seeder never resets an existing account's password.

Hardening checklist (do this before going live)

1. Webserver docroot must point at public/, not the project root. .env, app/, config/, storage/, etc. live above the docroot in the safe layout — they cannot be served at all. See deploy/nginx.conf.example for an nginx vhost. The bundled root .htaccess is for shared-hosting layouts where you can't change the docroot; it has explicit deny rules for .env, composer.*, dotfiles, and the source directories.
2. Set APP_DEBUG=false and APP_ENV=production in your real .env.
3. Set SESSION_ENCRYPT=true and SESSION_SECURE_COOKIE=true.
4. Skip the demo seeder in production (or, if you ran it, change the seeded admin password after first login — see Admin Accounts above).
5. Enforce HTTPS at the edge (nginx/Cloudflare). Add HSTS once you've confirmed every subdomain has a valid cert.
6. Make sure your reverse proxy is in config/cloudflare.php (or set TRUSTED_PROXIES) so request()->ip() returns the real client.

Configuration

.env Variables

Note on data sources: Spamhaus, CBL, PSBL, Barracuda, and SpamCop data is collected via DNS lookups (DNSBL) — no API keys needed. Microsoft JMRP (Junk Mail Reporting Program) sends ARF-formatted emails to your abuse inbox — no webhook needed. SpamCop also sends reports via email. Google Postmaster data must be checked manually at postmaster.google.com.

Roles & Permissions

Usage Guide

1. Set Up Your IP Inventory

Go to /admin/ips and import your IP ranges:

2. Create Brands

Go to /admin/brands:

1. Create a brand (e.g., "Acme Hosting") with from email, signature, footer
2. Add a POP3/IMAP connection linked to that brand
3. Enable auto-import on the connection
4. Test the connection

3. Configure AI Provider

Go to /admin/ai-settings:

1. Select Claude or OpenAI
2. Choose model
3. Test connection

4. Start Processing

Cases are created automatically when:

• Emails arrive in configured POP3 inboxes (polled every 2 min)
• Reports submitted via web form at /report
• Reports received via API
• IP reputation drops below threshold

5. Work Cases

At /admin/cases:

1. Review incoming cases
2. View threat intelligence data
3. Use AI to draft replies
4. Reply directly via email (branded, threaded)
5. Change status, add notes
6. Close or escalate

Data Collection Sources

How Each Source Delivers Data

What Creates Cases vs What Updates Reputation

Cases are created from human-initiated reports: email inbox, web form, API, webhooks, manual creation. These represent someone actively reporting an issue.

Automated scans only update reputation: AbuseIPDB, DNSBL, VirusTotal, Shodan, SNDS. These are background checks that monitor your IP health. A case is auto-created only when reputation drops critically low (<30/100), ensuring you're not flooded with automated cases.

IP Inventory & Reputation

How IPs are Checked

Only IPs in your active inventory generate cases. This prevents creating cases for IPs you don't manage.

When a report mentions an IP:

1. System scans all IPs in the email/report body
2. Checks each against the ip_addresses table
3. First match with status = active becomes the case target
4. Customer auto-linked if IP has a customer_id

Reputation Dashboard (/admin/reputation)

Shows all IPs with:

• Reputation score bar (0-100, color-coded)
• AbuseIPDB score
• DNSBL listing count
• Microsoft SNDS status (Green/Yellow/Red)
• Open case count
• Per-IP "Scan" button

Reputation vs Direct Reports

Email System

Inbound (Receiving Reports)

Outbound (Sending Replies)

SMTP Fallback (when Mandrill is down)

If Mandrill rejects a message, errors, or has no API key, the email is automatically re-sent through the brand's own mailbox over SMTP — so outbound mail keeps flowing per-brand during an ESP outage:

• By default the SMTP credentials are derived from the brand's active inbox connection (same server + login the poller uses; port 465/SSL for SSL inboxes, otherwise 587/STARTTLS). Most brands need zero setup.
• Override anything that differs at /admin/brands → edit brand → SMTP Fallback (host, port, username, password, encryption) — e.g. when sending goes through smtp.example.com instead of mail.example.com.
• Fallback sends are recorded in the sent-email log with a via brand SMTP badge and keep full threading (Message-ID, In-Reply-To/References), so replies still land on the right case.

Loop Prevention

The system prevents email loops by:

1. Detecting our case number [ABU-XXXX-XXXXX] in subject or body → follow-up
2. Matching In-Reply-To header against sent emails → follow-up
3. Detecting quoted ACK template text → follow-up
4. Skipping emails from our own addresses
5. Skipping auto-replies, OOO, delivery failures
6. Content analysis: strips ISP wrapper + our template, checks if meaningful content remains

API Reference

Authentication

Two methods:

Endpoints

Submit Report

Submit ARF Report (RFC 5965)

Bulk Report

Check Case Status

Webhook / Inbound Endpoints

Note: Most abuse data comes via email (POP3) and API polling, not webhooks. SpamCop, Microsoft JMRP, and other ISPs send reports as emails to your abuse address. Spamhaus, CBL, PSBL, Barracuda are checked via DNSBL DNS lookups. The webhook endpoints exist for custom integrations where you want to push data into Abuse AI.

Artisan Commands

Email & Feed Polling

IP Reputation Scanning

Legacy Commands (still available)

Scheduler & Automation

Cron Setup

Scheduled Tasks

Supervisor (Optional)

Tech Stack

Admin Pages

Contributing

Contributions are welcome. The full guide — dev setup, conventions, PR process, code-style and test requirements — lives in CONTRIBUTING.md. Quick links:

• Bugs / features: open an issue using the templates under .github/ISSUE_TEMPLATE.
• Security issues: do not open a public issue — see SECURITY.md.
• Code changes: branch off main, run composer test and vendor/bin/pint --test clean, open a PR using the template.

By contributing, you agree your contributions will be licensed under the Apache License 2.0.

License

This project is licensed under the Apache License 2.0.

You may freely use, modify, and redistribute the source — including for commercial and managed-service use — subject to the conditions of the license (retain copyright/license notices, mark modified files, etc.). The license also includes an explicit grant of patent rights from contributors.

Sponsors

Abuse AI is built and maintained by MonoVM — the project's main sponsor. MonoVM is a global hosting provider running shared, VPS, dedicated, and colocation services, and uses Abuse AI in production to keep its abuse desk under control.

Want to sponsor the project? See GitHub Sponsors.