How To Introduce a User-Defined Attribute or Integration with APIBAN Example

Overview

With SIP3 you can search for calls and build metric dashboards based on a set of defined criteria.

For instance, you can find all calls sent though particular SIP trunk, filter them by state and check which of those had problems with setup time, like it’s shown on the picture below:

We call each of the criteria above Service Attributes. They are assigned automatically by SIP3 to each call. You can also use those attributes for building metric dashboards:

Service Attributes can help you troubleshoot and address various problems. That, however, is not enough to cover different traffic profile use cases.

In this tutorial we will define a specific use case, introducing a User-Defined Attribute, and learn how to use it later.

Use Case

Everyone in the VoIP community knows Fred Posner as a great VoIP engeener and very talented baker.

Awhile back Fred introduced a new community-driven service called APIBAN. A platform for sharing and retrieving a list of fraud IP addresses.

APIBAN is integrated with Kamailio and iptables which makes it possible to automatically update firewall rules and block any fraud attempts.

Unfortunately, as with any other open source platform, APIBAN’s data may be compromised. Thus, the need of a verification via another service. 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. You will also:

see statistics of fraud attempts and determine the size of a fraud attack
analyze SIP messages retrieved from blacklisted IPs
be able to find a similar fraud attempts pattern in your own traffic from addresses that are not yet added to your blacklist.

Let’s see how this works in action!

Before you start, make sure you get yourself familiar with the concept of User-Defined Functions.

For this use case we will introduce two User-Defined Attributes: blocked as a Boolean and blocked_addr as a String. The first one will let us search for all calls originated from blacklisted IPs while the second one will show us more detailed information per IP.

User-Defined Function

The SIP3 team recommends you to use InteliJ IDEA. Just clone the SIP3 Salto project, open it in your IDEA, create .groovy file within the project and take an advantage of syntax highlight and autocomplete.

The use case, we are going to implement, is a bit more complex. However, it’s enough to just go though the Vert.x Documentation to understand the logic behind the code snippet below:

class ApiBanUdfExample extends AbstractVerticle {                           (1)

    private final APIBAN_URL = 'https://apiban.org/api/%API_KEY%/banned'

    private Set blocked = []

    @Override
    void start() throws Exception {
        vertx.eventBus().localConsumer("sip_message_udf") { event ->        (2)
            def packet = event.body()

            if (blocked.contains(packet['src_addr'])) {
                packet['attributes']['blocked'] = true
                packet['attributes']['blocked_addr'] = packet['src_addr']
            }

            event.reply(true)
        }

        asyncUpdateBlocked()                                                (3)
    }
}

1	Don’t be confused by the fact that our code doesn’t look like a Groovy script from User-Defined Functions document. This is because every SIP3 User-Defined Function is a verticle which can be written in multiple ways. We’ve chosen to extend the `AbstractVerticle` class because it gives more control on the IDEA level.
2	This part is a very simple and looks exactly like any Groovy script from User-Defined Functions document. In our case, we will analyze packet’s `src_addr` attribute. If this attribute is found in the `blocked` set we will assign the User-Defined Attributes stated above.
3	To update the `blocked` list we need to call APIBAN API. The `asyncUpdateBlocked` method is pretty big. That’s why you can find it in a separate code snippet below:

private void asyncUpdateBlocked(String controlId) {
    def url = controlId ? "$APIBAN_URL/$controlId" : APIBAN_URL             (1)

    WebClient.create(vertx).getAbs(url).send { asr ->
        if (asr.failed()) {
            vertx.setTimer(5 * 60000) {
                asyncUpdateBlocked()
            }
            return
        }

        def response = asr.result().bodyAsJsonObject()
        def id = response.get('ID') as String
        def addresses = response.get('ipaddress') as ArrayList

        blocked.addAll(addresses)                                           (2)

        if (addresses.size() == 250) {
            asyncUpdateBlocked(id)                                          (3)
        } else {
            vertx.setTimer(5 * 60000) {                                     (4)
                asyncUpdateBlocked(id)
            }
        }
    }
}

1	When SIP3 is just started we don’t have an APIBAN control ID. That’s why we will use a generic API method to get the first bulk of the blacklisted IPs. Otherwise, we will use control ID to get the next bulk. You can find more information about this in the official APIBAN Documentation.
2	Once the HTTP request retuns a list of blacklisted IPs we will add them to the `blocked` set.
3	If the amount of returned IPs equals 250 (which is a bulk size) we will do the following API call using the control ID immediately.
4	Otherwise, we will be checking every 5 minutes for new portion of the blacklisted IPs.

That’s it! Our User-Defined Function is ready. Check out the Installation Guide for more instructions on how to deploy it.

Real Life Example

In order to make this use case more interesting and show you real data, we agreed to deploy the User-Defined Function from above to one of our customers who wasn’t sure if they are experiencing fraud attacks.

As soon as it was deployed we built a metric dashboard using the blocked attribute. Here is what we’ve got:

Dashboard For Call Attempts Blocked By APIBAN

As you can see there is a good amount of fraud attempts blocked by the list of IPs retrieved from APIBAN API. Let’s see what are those:

Search For Call Attempts Blocked By APIBAN

Now let’s see how many blacklisted IPs are attacking the customer’s VoIP servers:

After seeing this data, our customer decided to leave the SIP3 integration with APIBAN working, hoping that the APIBAN database will keep expanding in future and help more businesses like his.

Minimizing VoIP fraud attempts with SIP3

As the VoIP fraud attempts have begun to rise in the last few years, it is important to understand how you can minimize the impact they have on your business.

While it might be difficult to prevent VoIP fraud from happening, the right tools in place could help you reduce your chances of becoming a victim. Why to wait for fraud attacks to effect your business when SIP3 can give you 360-degree service visibility?