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.

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

horrible graphical representation of a honeypot in action

Block/Identify Traffic

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 APIBAN client to automatically block traffic.

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.

Base URL

https://apiban.org/api/[KEY]/

Where [KEY] is replaced with your API KEY.

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.

Authentication Errors

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

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

Example authentication errors received from the API.

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.

Banned

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

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

Example responses

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

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

Where [KEY] is replaced with your API KEY and optional [ID] represents last known ID received.

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.

Check

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

Example responses

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

HTTP 404 {"ipaddress":"ok", "ID":"0"}

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

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.