AbuseIPDB Integration

Automatically report malicious IPs to AbuseIPDB when they get banned.

What is AbuseIPDB?

AbuseIPDB is a project dedicated to helping combat the spread of hackers, spammers, and abusive activity on the internet. By reporting IPs that attack your infrastructure, you help the entire community.

Setup

1. Get API Key

1. Create an account at abuseipdb.com
2. Go to Account → API
3. Create a new API key
4. Copy the key

2. Configure in Bloqd

1. Go to Settings → Integrations
2. Find AbuseIPDB section
3. Enable the integration
4. Paste your API key
5. Configure rate limit (default: 1000/day)
6. Click Save

Or via environment variables:

ABUSEIPDB_ENABLED=true
ABUSEIPDB_API_KEY=your_api_key_here
ABUSEIPDB_RATE_LIMIT=1000

How It Works

┌──────────────┐    Ban Event    ┌──────────────┐
│   fail2ban   │────────────────►│    Bloqd     │
└──────────────┘                 └──────┬───────┘
                                        │
                            ┌───────────┴───────────┐
                            ▼                       ▼
                    ┌───────────────┐       ┌───────────────┐
                    │  Dashboard    │       │  AbuseIPDB    │
                    │  (Ban List)   │       │  (Report)     │
                    └───────────────┘       └───────────────┘

1. fail2ban bans an IP
2. Agent reports ban to Bloqd
3. Bloqd maps jail to AbuseIPDB category
4. Bloqd checks if IP was reported recently (15-min window)
5. If not duplicate, submits report to AbuseIPDB
6. Stores record to prevent duplicate reports

Category Mapping

Bloqd automatically maps jails to AbuseIPDB categories:

Jail	AbuseIPDB Category
sshd	22 (SSH)
recidive	22 (SSH)
postfix, postfix-sasl	11 (Email Spam)
dovecot	11 (Email Spam)
mailcow-*	11 (Email Spam)
nginx-, apache-	21 (Web App Attack)
wordpress*	21 (Web App Attack)
phpmyadmin	21 (Web App Attack)
nextcloud	21 (Web App Attack)
grafana	21 (Web App Attack)
mysqld-auth	14 (Hacking)
mongodb-auth	14 (Hacking)
proxmox*	14 (Hacking)

AbuseIPDB Categories Reference

ID	Category
11	Email Spam
14	Port Scan / Hacking
18	Brute-Force
21	Web App Attack
22	SSH

Rate Limiting

AbuseIPDB has daily report limits:

Plan	Daily Reports
Free	1,000
Basic	3,000
Premium	10,000

Bloqd respects your configured limit and stops reporting when reached.

Configuration

# Set limit based on your plan
ABUSEIPDB_RATE_LIMIT=1000

Check usage in Settings → AbuseIPDB → Usage Stats.

Duplicate Prevention

Bloqd prevents duplicate reports:

• Stores reported IP + timestamp
• Won't report same IP within 15 minutes
• Reduces noise in AbuseIPDB
• Conserves your rate limit

Report Details

Each report includes:

{
  "ip": "192.168.1.100",
  "categories": "22",
  "comment": "Fail2ban: sshd - Multiple failed SSH login attempts"
}

Manual Reporting

You can manually report IPs from the dashboard:

1. Go to Bans page
2. Find the ban entry
3. Click Report to AbuseIPDB
4. Confirm

Checking IP Reputation

Before whitelisting an IP, check its reputation:

1. Click on any IP in the ban list
2. View AbuseIPDB Score in the details panel

Or check directly on AbuseIPDB:

https://www.abuseipdb.com/check/192.168.1.100

Troubleshooting

Reports Not Being Sent

1. Verify AbuseIPDB is enabled in settings
2. Check API key is valid
3. Check rate limit not exceeded
4. Review logs for errors

Invalid API Key

AbuseIPDB Error: Invalid API key

1. Verify key in settings
2. Regenerate key on AbuseIPDB
3. Ensure no extra spaces in key

Rate Limit Exceeded

AbuseIPDB Error: Daily report limit reached

• Wait until next day (UTC midnight reset)
• Upgrade AbuseIPDB plan for higher limits
• Reduce report categories

Best Practices

1. Enable for public-facing servers - Report attacks on SSH, web, mail
2. Don't report internal IPs - Only report attacks from internet
3. Use appropriate rate limit - Don't exceed your plan's limit
4. Monitor usage - Check stats regularly
5. Whitelist trusted IPs - Prevent false reports