API Reference

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

The apiban.org 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]/

Authentication

The apiban.org API uses simple API authentication via a replaceable API key. The API key can be replaced in the user control panel.

One API key can be active per account.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Errors

Apiban.org uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an API key failed, etc.). Codes in the 5xx range indicate an error with our servers.

Some 4xx errors can be handled on the client side. For example, when no new information is available, an error code is displayed.

Each APIBAN key is rate limited for 5 requests in 2 minutes. It is recommended that every resource utilize a unique key to avoid rate limits.

Banned

Banned is an object returning banned ipaddresses in batches of 250.

Arguments

ID (in the URL) optional

Examples

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

{
	"ipaddress": [
		"1.2.3.4",
		"1.2.3.5",
		...
		"1.2.3.250"
	],
	"ID": "987654321"
}

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

{
	"ipaddress": [
		"1.2.3.251",
		"1.2.3.252"
	],
	"ID": "987654322"
}

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

{"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.

Arguments

IPADDRESS (in the URL) required

Examples

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

{"ipaddress":"blocked", "ID":"987654321"}

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

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

Integrations

The IP addresses provided by apiban.org have attempted to access resources on various honeypots or systems throughout the globe. This data can be implemented into a wide variety of VoIP software.

Integration examples are provided for:

IPTABLES

An open source client exists for automatically blocking bad traffic via IPTABLES.

You can get the client at github — the GO client is the recommended client.

The executable can be automatically run via cron with instructions in the github README.

Kamailio Example

With Kamailio, there would be two main aspects: (1) keeping the blocklist updated and (2) using the blocklist to block traffic.

First, in order to process the max batch size of 250 ip addresses, we should make sure that Kamailio has a max_while_loops value of at least 250.

max_while_loops=250

You will need to load the following modules (if not already loaded):

loadmodule "http_client.so"
loadmodule "jansson.so"
loadmodule "rtimer.so"

The following htables should be created (you can increase the size of apiban as needed):

modparam("htable", "htable", "apiban=>size=11;")
modparam("htable", "htable", "apibanctl=>size=1;initval=0;")

In this example, let's set an rtimer to run every 5 minutes:

modparam("rtimer", "timer", "name=apiban;interval=300;mode=1;")
modparam("rtimer", "exec", "timer=apiban;route=APIBAN")

Let's create that [APIBAN] route to get the ipaddresses and add them to the apiban htable. The control ID is used to download an incremental list. On startup or restart, the full list is loaded.

route[APIBAN] {
	// check if we already have an APIBAN id... if so, get the updates and
	// if not, get the full list of banned ips.

	// replace MYAPIKEY with your apiban.org API key.
	$var(apikey) = "MYAPIKEY";

	if($sht(apibanctl=>ID) == 0) {
		$var(apiget) = "https://apiban.org/api/" + $var(apikey) + "/banned";
	} else {
		$var(apiget) = "https://apiban.org/api/" + $var(apikey) + "/banned/" + $sht(apibanctl=>ID);
	}

	xlog("L_INFO","APIBAN: Sending API request to $var(apiget)\n");
	http_client_query("$var(apiget)", "$var(banned)");

	// if we dont get a 200 OK from the webserver we will log and exit
	if($rc!=200) {
		xlog("L_INFO","APIBAN: No 200 Received. $var(banned)\n");
		exit;
	}

	// lets loop through the ipaddresses we received from our API request
	$var(count) = 0;
	jansson_array_size("ipaddress", $var(banned), "$var(size)");
	while($var(count) < $var(size)) {
		jansson_get("ipaddress[$var(count)]", $var(banned), "$var(blockaddr)");
		// add the blocked ipaddress to the apiban htable and log
		$sht(apiban=>$var(blockaddr)) = 1;
		xlog("L_INFO","API: ipaddress[$var(count)] == $var(blockaddr)\n");

		$var(count) = $var(count) + 1;
	}

	// lets get our control ID and use it for incremental downloads
	jansson_get("ID", $var(banned), "$var(apiid)");
	xlog("L_INFO","ID: $var(apiid)\n");
	$sht(apibanctl=>ID) = $var(apiid);
}

Lastly, we can use these IPs to block unwanted traffic. For example, if you were using ipban as demonstrated in the [REQINIT] route of the default config, you can just add this block:

		if($sht(apiban=>$si)!=$null) {
			// ip is blocked from apiban.org
			xdbg("request from apiban.org blocked IP - $rm from $fu (IP:$si:$sp)\n");
			exit;
		}

HOMER Example

HOMER is a robust, carrier-grade, scalable Packet and Event capture system and VoiP/RTC Monitoring Application based on the HEP/EEP protocol and ready to process & store insane amounts of signaling, rtc events, logs and statistics with instant search, end-to-end analysis and drill-down capabilities.

Homer implements APIBan interactions through a dedicated HEPSub agent interactively retrieving and caching APIBan API information in memory, and providing total flexibility, extensibility and customization for HEP users and integrators.

HOMER Documentation: https://github.com/sipcapture/hepsub-apiban

SIP3 Example

SIP3 is an end-to-end solution for real-time monitor, analysis and troubleshooting of network performance in large volumes of traffic.

Thanks to the SIP3 architecture design you can have a monitoring set in place that works in front of iptables. So even if the traffic has been blocked you will still be able detect fraud attempts and whitelist wrongly blocked IP addresses.

Example: https://sip3.io/docs/tutorials/HowToInroduceUserDefinedAttribute.html

Getting Help

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

APIBAN.ORG REST API

For more information, please visit LOD.com.