REST API for identifying 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.

Visit https://www.apiban.org/ for more information.

APIBAN is made possible by the generosity of our sponsors.

• Introduction
• Using the API
• Integration with Kamailio
• Integration with HOMER
• Integration with SIP3
• Integration with IPTABLES
• Integration with OpenSIPS
• Integration with pfSense/opnSense
• Getting Help
• Warranty

APIBAn helps you block and identify unwanted traffic.

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

The data is provided in standard JSON responses and uses 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.

1. obtain an API KEY (the API KEY is used for all API requests)
2. Integrate

Once you have an API KEY, you can use the API to:

• pull the full banned list
• check specific IPs
• pull changes since last full list

To protect your PBX automatically, without programming, use our go api client to integrate with iptables. This is the easiest way to use APIBAN on a single box.

The full APIBAN API documentation is available at https://apiban.org/doc.html.

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

Kamailio is an open source implementation of a SIP Signaling Server. SIP is an open standard protocol specified by the IETF. The core specification document is RFC3261.

A loop is used to cycle through the banned IPs. On first download, this list can be quite large and max_while_loops will need to be large enough to handle the list.

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: Non 200 response. $var(banned)\n");
		xlog("L_INFO","APIBAN: $sht(apibanctl=>blocks) attacks blocked since $(Tb{s.ftime,%Y-%m-%d %H:%M:%S})\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","APIBAN: Adding block 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","APIBAN: New ID is $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");
			$sht(apibanctl=>blocks) = $sht(apibanctl=>blocks) + 1;
			exit;
		}

Bonus: Want to run APIBAN at start-up? Using the htable:mod-init event_route built into Kamailio, you can pre-load the APIBAN htable at start-up:

event_route[htable:mod-init] {
	# pre load apiban
	route(APIBAN);
}

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.

Read more: https://github.com/sipcapture/hepsub-apiban

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.

Read more: https://sip3.io/docs/tutorials/HowToInroduceUserDefinedAttribute.html

APIBAN provides two open source clients for integrated into IPTABLES.

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

loadmodule "json.so"
loadmodule "cachedb_local.so"
loadmodule "rest_client.so"

The following collections and URLs should be created (adjust the size of collection apiban as needed):

modparam("cachedb_local", "cache_collections", "apiban = 11;apibanctl = 1")
modparam("cachedb_local", "cachedb_url", "local:apiban:///apiban")
modparam("cachedb_local", "cachedb_url", "local:apibanctl:///apibanctl")

We'll adjust some rest client timeouts:

modparam("rest_client", "curl_timeout", 60)
modparam("rest_client", "connection_timeout", 10)

Let's create the [APIBAN] route at the end of your script. When invoked, it will get the batches of IP addresses and add them to the cache. Note that APIBAN sends batches of 250 entries per batch. The control ID is used to download an incremental list. On startup or restart, the full list is loaded.

route[APIBAN] {
  $var(apikey) = "<<<< ENTER YOU APIBAN KEY HERE >>>>";

  $var(loop) = true;

  while ($var(loop)) {
    if (!cache_fetch("local:apibanctl", "ID", $var(apiban_id)))
      $var(apiban_id) = 0;

    if($var(apiban_id) == "0") {
      # First run, we will get the full IP list
      $var(apiget) = "https://apiban.org/api/" + $var(apikey) + "/banned";
    } else {
      # ID exists, we pull incemental list
      $var(apiget) = "https://apiban.org/api/" + $var(apikey) + "/banned/" + $var(apiban_id);
    }

    xlog("L_INFO","APIBAN: Sending API request to APIBAN\n");
    rest_get("$var(apiget)",$var(resp_body),,$var(rcode));

    if ($var(rcode) == 200) {
      $json(apiban_resp) := $var(resp_body);
      $json(ip_array) := $(json(apiban_resp/ipaddress));
      cache_store("local:apibanctl", "ID", "$(json(apiban_resp/ID))");

      $var(index_count) = 0;
      for ($var(ip) in $(json(ip_array)[*])) {
        cache_store("local:apiban", "$var(ip)", "1");
        xlog("L_INFO","APIBAN: Adding IP address $var(ip)\n");
        $var(index_count) = $var(index_count) + 1;
      }
      if ($var(index_count) < 250) {
        # Last batch has less than 250 records, loop can stop
        break;
      } 
    } else {
      # There are no records to process in ths request
      break;
    }
  }
}

Let's create a timer-route in order to get updates from APIBAN. Change the interval of 180 seconds to whatever works best for you. Remember that APIBAN has a limit of 11 requests every 2 minutes, adjust accordingly if you are using the same key for several instances.

timer_route[apiban_update, 180] {
  route(APIBAN);
}

[Optional]: Let's create a startup-route (or modify your current one) in order to get the data from APIBAN when OpenSIPS is starting up.

startup_route {
  route(APIBAN);
}

Now you are able to pull the list of IP banned addresses from APIBAN, now let's make good use of it. Somewhere in the top of your main route, add:

if (cache_fetch("local:apiban", "$si", $var(ip_val))) {
  xlog("Request from IP $si blocked. IP is listed in APIBAN\n");
  exit;
}

APIBAN provides an ipset for easy integration in pfSense, opnsense, or any software using ipsets. The simple GET is:

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

More information is documented at https://apiban.org/doc.html#ipset.

Example tutorials for adding ipsets:

• Blocking malicious IPs with OPNsense and external lists
• Block Malicious IPs in pfSense

Help is provided by LOD (https://www.lod.com) and an APIBAN room (#apiban:matrix.lod.com) is available on the LOD Matrix homeserver. The software is provided under the GPLv2 license.

ABIBAN data 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. See the GNU General Public License for more details.