Building an integration for (not only) SecOps

Building an integration is generally not very complex. If someone tries to tell you that this is complicated and expensive, it is not very true. There might be very complex integrations, but it always depends on the use case. When we look at typical integrations for Security Incident Response, they are mostly for enriching our incidents, and they usually involve a single REST API call with a single response that needs to be processed in some way.

While at ServiceNow, I was on booth duty during the Knowledge conference. I was approached by a customer who asked me if we had an integration that could enrich an IP's geolocation. We did not, so I quickly found a service that could provide such information and told the customer that it would be easy to integrate. I immediately saw that he did not trusted me. I asked him if he had a few minutes that I could show it to him.

So, let's look together now at how we can quickly build it. It was a bit dirty PoC but I was able to do it in less than 30min.

User story: As a security analyst, I need to know the geolocation of IP IoC that is associated with a security incident.

We will use https://ipstack.com as a provider.

Test the API in REST API client, e.g. Postman

It helps you avoid any errors caused by misunderstanding the API call format. The usage is straightforward:

https://api.ipstack.com/<IP Address>?access_key=<API KEY>

For instance

https://api.ipstack.com/134.201.250.155?access_key=ae5315e8a59c323d68caa19ed5be9398

We will get a response:

{
    "ip": "134.201.250.155",
    "type": "ipv4",
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code": "US",
    "country_name": "United States",
    "region_code": "CA",
    "region_name": "California",
    "city": "Los Angeles",
    "zip": "90012",
    "latitude": 34.0655517578125,
    "longitude": -118.24053955078125,
    "location": {
        "geoname_id": 5368361,
        "capital": "Washington D.C.",
        "languages": [
            {
                "code": "en",
                "name": "English",
                "native": "English"
            }
        ],
        "country_flag": "https://assets.ipstack.com/flags/us.svg",
        "country_flag_emoji": "????",
        "country_flag_emoji_unicode": "U+1F1FA U+1F1F8",
        "calling_code": "1",
        "is_eu": false
    }
}        

Move to ServiceNow

There are multiple ways to perform a REST call from the ServiceNow platform. You can use Outbound REST messages, Flow Designer, or write a script. ServiceNow highly recommends a no-code approach. There is a reason for that. The clickable configuration creates an abstract layer. If there is any change underneath, you do not even realize it. However, even the script is not a native JavaScript but built libraries by ServiceNow. Any changes are rare. In our case, I will use scripting only. When I develop my script, I usually use "Fix scripts." It is a great playground, but let's start by creating a new app in the Application Studio.

Creating an app

Create a new application in Application Studio directly in System Applications-> Studio. If you use App Engine Studio, you will need to switch by "Open app in Dev Studio" in Settings.

Creating a new JavaScript class - Script Include

var IPStack = Class.create();
IPStack.prototype = {
	// The constructor set the api key as a object property
    initialize: function(api) {
        this.API = api;
    },
	// The getGeoLocation method requires ip as a paramater and return a country code
    getGeoLocation: function(ip) {
		//IP address validation (IPv4 only)
        if (ip.match(/^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$/gm)) {
			//Creating the REST message - setting endpoint, method, headers and query params
            var sm = new sn_ws.RESTMessageV2();
            sm.setEndpoint("https://api.ipstack.com/" + ip);
            sm.setHttpMethod("get");
            sm.setRequestHeader("Accept", "Application/json");
            sm.setQueryParameter("access_key", this.API);
            var response = sm.execute();	
			//validating HTTP status code
            if (response.getStatusCode() == 200) {
                var body = JSON.parse(response.getBody());
				//validating existanceof country_code property
                if (body.hasOwnProperty('country_code')) {
                    return body.country_code;
                }
            }
        }
		//method failed
		return -1;
    },
    type: 'IPStack'
};        

Create a Fix script to play around

var ips = new IPStack("ae5315e8a59c323d68caa19ed5be9398");
var response = ips.getGeoLocation('134.201.250.155');
gs.info(response);        

when you finish remove the Fix script record or just comment the whole code. The Fix script is intended to be used after the app is installed or upgraded. We do not want any runs in such occasion.

Create a Flow Designer Action

Conclusion

The whole integration returns Country Code only, but we can get more, like flag, city, or state. All this information is available in the REST API response. How exactly the response will be used or where it will be stored is not part of the integration. We can write it into an incident feed or update a custom file in IoC.

There are still places in the script requiring more attention to make it bulletproof for errors. I assume that you can spot them instantly ;-)