APIBAN API Reference

REST API for sharing IP addresses sending unwanted SIP traffic

APIBAN helps prevent unwanted SIP traffic by identifying addresses of known bad actors before they attack your system. Bad actors are collected through globally deployed honeypots and curated by LOD/APIBAN.

Introduction

To use the APIBAN API, you will need to first obtain an API KEY. The API KEY is used for all API requests.

NOTE API KEYs are limited to one per user/email. If your organization needs multiple keys, please contact LOD.

The API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes and verbs.

For integration examples for Kamailio, Homer, and more, please visit our Github repo.

Authentication

Authentication with the API is made through the API KEY. If having trouble receiving an API KEY or if an API KEY needs to be replaced, please contact our support team.

Requests to the API are limited to 11 requests in 2 minutes.

Errors

The API will return non-2xx http status codes and descriptive responses when able to do so. Examples include:

• 400 often used to indicate no matching results {"ipaddress":"no new bans", "ID":"none"}
• 403 unauthorized {"ipaddress":"none", "ID":"unauthorized"}
• 404 used within check for an ip address that is not blocked {"ipaddress":"ok", "ID":"0"}
• 429 rate limit exceeded {"ipaddress":"rate limit exceeded", "ID":"unauthorized"}
• 503 server error {"error":"gK10", "description":"an internal error occurred"}

Core Resources

Banned

Banned is an object returning banned ip addresses in batches of 250. An ID is provided to use when pulling the next batch. If no ID is passed, the first 250 addresses (oldest first) will be provided.

Check

Check is an object returning the status of a specific ip address. A 2xx indicates a ban and a 404 indicates the ipaddress is not banned.

IPset

IPsets (lists of IPs) can be used by many firewalls, iptables, and appliances (such as pfsense, opnsense, etc.) to block unwanted traffic to your network.

List

List returns a plain text ipset with control id, record count, and IPs (listed in age order from oldest to most recent).

License / Warranty

The APIBAN API is provided in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

apiban-iptables-client is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

apiban-iptables-client is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Getting Help

Help is provided by LOD and an APIBAN room is available on the LOD Matrix homeserver. The client software is provided under the GPLv2 license.

NOTE The best method to get assistance is in the APIBAN Matrix room: #apiban:matrix.lod.com.

Open Source

APIBAN (LOD, and Palner) greatly values and supports open source software.

There are many ways you can participate in open source software, including:

• financial support
• reviewing, writing, updating code
• reviewing, adding, editing documentation
• evangelism

Open Source Used by APIBAN

• Linux — powers our servers and honeypots
• Kamailio — powers our honeypots
• Golang — powers the API
• Redis — data storage
• MariaDB — data storage
• NGINX — http requests
• matrix — online support / communication

Open Source Made by APIBAN

• Bash Client
• Go Client