sikkerapi@prod ~$
Why SikkerAPI|
Sikker-CLISikkerGuard
Honeypot DatabaseEmail LookupUsername LookupDetection CatalogSubnet CalculatorEncoder / Decoder
Prices
|
Fail2BanCSF FirewallNginxiptables / ipset
|
Blog
OverviewIP CheckBlacklistReportBulk ReportTAXII FeedSikker-CLIConfidence Score Algorithm
Top CountriesTop ASNsTop ProtocolsTop IPsSMTP Database
CIDR Range AlertsIP AlertsUsername AlertsEmail AlertsBlacklist Web-UIInstall SikkerGuard
|login|signup
Loading
SikkerAPI

Open source threat intelligence from a global honeypot sensor network. Real attacker behavior, not purchased feeds.

Product
PricingDocumentationReport an IPThreat MapSystem Status
Resources
BlogFAQAboutContactComparisons
Tools
Sikker-CLISikkerGuardDetection CatalogSession DatabaseTAXII Feed
Browse
Top CountriesTop ASNsTop ProtocolsTop IPsSMTP Wall of Fame
© 2026 SikkerAPI
TermsPrivacyRemove Me

Fail2Ban Integration

Reports To
POST /v1/key/report
Authentication
Bearer sk_...
Requirements
Fail2Ban ≥ 0.9.0, curl
Data Sent
IP + category + protocol + optional comment

← Back to Overview

Overview

Integrate Fail2Ban with SikkerAPI to automatically report banned IPs to the community threat intelligence database. When Fail2Ban bans an IP on your server, the integration calls the Report API with the IP address, attack category, protocol, and an optional comment. No log snippets or sensitive information is ever transmitted.

Data flow
Fail2Ban detects intrusion→Bans IP via firewall→sikkerapi-report script→POST /v1/key/report→Threat database
What gets sent to the API
ipstringrequired — The banned IPv4 or IPv6 address.
categorystringrequired — Attack category (e.g. brute_force). Set per jail.
protocolstringProtocol involved (e.g. ssh, http). Set per jail.
commentstringOptional context (max 1000 chars). Set per jail.

Installation

Two files to download: the action configuration for Fail2Ban and the report script that calls the API. Takes under a minute.

1Download the action file
$ sudo curl -o /etc/fail2ban/action.d/sikkerapi.conf \ "https://sikkerapi.com/fail2ban/sikkerapi.conf"
2Download the report script
$ sudo curl -o /usr/local/bin/sikkerapi-report \ "https://sikkerapi.com/fail2ban/sikkerapi-report.sh"
3Make executable
$ sudo chmod +x /usr/local/bin/sikkerapi-report
4Test connection
$ sikkerapi-report 192.0.2.1 sk_free_... brute_force ssh "manual test" # Output: Reported 192.0.2.1 (brute_force) to SikkerAPI

Configuration

Add the SikkerAPI action to your jails in /etc/fail2ban/jail.local. Each jail can specify its own category and protocol. The action runs alongside your existing ban action — banning still works normally even if reporting fails.

Action parameters (set in jail.local)
keystringrequired — Your SikkerAPI key (sk_...). Get one free
categorystringrequired — Attack category. See categories below.
protocolstringProtocol involved: ssh, http, ftp, smtp, etc.
commentstringOptional context, max 1000 chars (e.g. "Fail2Ban Report - Brute force attempt")
jail.local — SSH jail example
[sshd] enabled = true port = ssh logpath = %(sshd_log)s backend = %(sshd_backend)s action = %(action_)s sikkerapi[key=sk_free_..., category=brute_force, protocol=ssh, comment="Fail2Ban Report - Brute force attempt"]
jail.local — Apache auth example
[apache-auth] enabled = true port = http,https logpath = %(apache_error_log)s action = %(action_)s sikkerapi[key=sk_free_..., category=brute_force, protocol=http]
jail.local — Multiple jails
# Each jail gets its own category and protocol [nginx-botsearch] enabled = true action = %(action_)s sikkerapi[key=sk_free_..., category=bad_bot, protocol=http] [postfix] enabled = true action = %(action_)s sikkerapi[key=sk_free_..., category=spam, protocol=smtp, comment="Fail2Ban Report - Spam attempt"]

Jail Mappings

Recommended category and protocol for common Fail2Ban jails. Use these as a starting point and adjust based on your specific configuration.

Common jail → category → protocol
sshdbrute_forcessh
apache-authbrute_forcehttp
nginx-http-authbrute_forcehttp
apache-badbotsbad_bothttp
nginx-botsearchbad_bothttp
postfixspamsmtp
postfix-saslbrute_forcesmtp
dovecotbrute_forceimap
vsftpdbrute_forceftp
proftpdbrute_forceftp
mysqld-authbrute_forcemysql
recidiveother—

Categories

Choose the category that best describes the attack your jail detects. Use the string name (not numeric ID). See the Report API for the full list of all 16 categories with numeric IDs.

Common categories for Fail2Ban
brute_forceSSH, FTP, HTTP auth, database auth brute force attempts
port_scanPort scanning and reconnaissance
ddosDDoS and flood attacks
web_exploitWeb application exploitation (path traversal, RCE, etc.)
sql_injectionSQL injection attempts
bad_botSuspicious bots, scrapers, and crawlers
spamEmail spam and SMTP abuse
phishingPhishing and social engineering attempts
malwareMalware distribution
otherOther suspicious activity (e.g. recidive jail)

Rate Limits

Report submissions are rate-limited per API key. Rate limit errors do not affect the ban action — the IP is still blocked on your server, just not reported. If you run multiple servers, consider using separate API keys or upgrading your tier.

Daily report quotas by tier
Free1,000 reports/day. Create free key
Paid tiersHigher limits. See pricing for details.

Verification

After configuration, reload Fail2Ban and verify reports are being submitted. Reported IPs appear in the IP Check response under the contributor section.

1Reload Fail2Ban
$ sudo fail2ban-client reload
2Check Fail2Ban logs
$ sudo tail -f /var/log/fail2ban.log # Look for [sshd] Ban entries, then check the script output: $ journalctl -u fail2ban --since "5 minutes ago" | grep -i sikker # Look for: "Reported x.x.x.x (brute_force) to SikkerAPI"
3Verify a reported IP via API
$ curl -H "Authorization: Bearer sk_..." \ "https://api.sikkerapi.com/v1/key/check/203.0.113.42" \ | jq .contributor # Should show your report in the contributor section

Troubleshooting

Common issues and how to resolve them. You can always test the script manually to isolate whether the issue is with Fail2Ban configuration or API connectivity.

Common issues
Reports not appearing in dashboardcheck script is executable: ls -la /usr/local/bin/sikkerapi-report
401 — Invalid API keyensure full key in jail.local, check key is enabled
429 — Rate limit exceededupgrade tier or use separate keys per server
Connection timeoutcheck outbound HTTPS to api.sikkerapi.com is allowed
Script not found by Fail2Banverify path: /usr/local/bin/sikkerapi-report
Manual test — run the script directly
$ /usr/local/bin/sikkerapi-report \ "192.0.2.1" \ "sk_free_..." \ "brute_force" \ "ssh" \ "manual test"
Verbose API test — bypass the script
$ curl -v -X POST "https://api.sikkerapi.com/v1/key/report" \ -H "Authorization: Bearer sk_..." \ -H "Content-Type: application/json" \ -d '{"ip":"192.0.2.1","category":"brute_force","protocol":"ssh"}' # Expected: {"success":true}

Action File Reference

The action configuration at /etc/fail2ban/action.d/sikkerapi.conf defines when the report script is called. Only actionban is used — no action is taken on unban, start, or stop events.

/etc/fail2ban/action.d/sikkerapi.conf
# SikkerAPI Fail2Ban Action # https://sikkerapi.com/docs/fail2ban [Definition] # Called when Fail2Ban bans an IP actionban = /usr/local/bin/sikkerapi-report <ip> "<key>" "<category>" "<protocol>" "<comment>" # No action on unban, start, or stop actionunban = actionstart = actionstop = [Init] # Defaults (override in jail.local) key = category = other protocol = comment =
Get started — Start reporting banned IPs to the community threat database in under a minute. Reports contribute to confidence level calculations and appear in IP Check responses. Want automated blocking too? Try SikkerGuard for zero-config firewall protection or CSF for pre-emptive blocking. Create free API key →