APIBAN

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.

In the videos section, you can learn about APIBAN by watching a presentation (or two).

APIBAN is made possible by the generosity of our sponsors.

This API allows you to integrate and interact with APIBAN data.

The data is provided in standard JSON responses and use HTTP Status Codes to help determine results

NOTE If you are looking to protect your PBX or SIP server without programming, you should use the free APIBAN client to automatically block traffic.

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 data is provided in standard JSON responses and use HTTP Status Codes to help determine results

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.

Base URL

Where [KEY] is replaced with your API KEY.

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.

Example authentication errors received from the API:

HTTP 403
{"ipaddress":"none", "ID":"unauthorized"}

HTTP 429
{"ipaddress":"rate limit exceeded", "ID":"unauthorized"}

Errors

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

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.

• Method: GET
• Required parameter: APIKEY
• Optional parameter: ID

Examples

GET https://apiban.org/api/[APIKEY]/banned

GET https://apiban.org/api/[APIKEY]/banned/[ID]

Where [KEY] is replaced with your API KEY and optional [ID] represents last known ID received, such as: https://apiban.org/api/abcdefg12345678/banned/9876543210

Example responses

200 {"ipaddress":["1.2.3.4","1.2.3.5"], "ID":"9876543210"}

400 {"ipaddress":["no new bans"], "ID":"none"}

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.

• Method: GET
• Required parameter: APIKEY
• Required parameter: IPADDRESS

Example

GET https://apiban.org/api/[APIKEY]/check/[IPADDRESS]

Where [KEY] is replaced with your API KEY and [IPADDRESS] is the address to check.

Example responses

200 {"ipaddress":"blocked", "ID":"9876543210"}

400 {"ipaddress":"ok", "ID":"0"}

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).

• Method: GET
• Required parameter: APIKEY

NOTE This uses the ipset resource vs api.

Example

GET https://apiban.org/ipset/[APIKEY]/list

Where [KEY] is replaced with your API KEY. Please note that this call uses the ipset resource vs api.

Example responses

200 plain text document

403 {"ipaddress":"none", "ID":"unauthorized"}

429 {"ipaddress":"rate limit exceeded", "ID":"unauthorized"}

503 {"error":"gK10", "description":"an internal error occurred"}

Cisco

Cisco returns a plain text Cisco formatted list with a deny statement for each IP address (listed in age order from oldest to most recent).

• Method: GET
• Required parameter: APIKEY

NOTE This uses the ipset resource vs api.

Example

GET https://apiban.org/ipset/[APIKEY]/cisco

Where [KEY] is replaced with your API KEY. Please note that this call uses the ipset resource vs api.

Example responses

200 plain text document

403 {"ipaddress":"none", "ID":"unauthorized"}

429 {"ipaddress":"rate limit exceeded", "ID":"unauthorized"}

503 {"error":"gK10", "description":"an internal error occurred"}

Juniper

Juniper returns a plain text Juniper formatted list with a set statement for each IP address (listed in age order from oldest to most recent).

• Method: GET
• Required parameter: APIKEY

NOTE This uses the ipset resource vs api.

Example

GET https://apiban.org/ipset/[APIKEY]/juniper

Where [KEY] is replaced with your API KEY. Please note that this call uses the ipset resource vs api.

Example responses

200 plain text document

403 {"ipaddress":"none", "ID":"unauthorized"}

429 {"ipaddress":"rate limit exceeded", "ID":"unauthorized"}

503 {"error":"gK10", "description":"an internal error occurred"}

APIBAN is made possible by the generosity of our sponsors.

We would also like to give thanks to Ivan Nyarko and our github sponsors.

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.

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.

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

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

APIBAN - Fred Posner (CommCon 2021)

Using APIBAN to protect your phone system (in under 5 minutes)

APIBAN: Protecting you from unwanted SIP traffic (tadsummit 2021)