As we interact with our customers and partners, we’ve run into instances where users aren’t yet leveraging ThreatScape API 2, which was released early this year. When we talk to our users about it further, the reasoning we’re hearing is that they’re not sure what changes they have to make to their existing API 1 scripts to move to API 2. We also hear that they’re not sure if they’ll be able to continue using the same queries…

I’m happy to report that there’s good news to be had. With some minor changes to most scripts, you should be able to start using API 2 for all of your automated iSIGHT intelligence needs!

Before we get started…

…we need to make sure that we have the right keys for API 2. API 2 does use different keys from API 1. This was done for a number of reasons, including stronger authentication and simpler requests for specific formats. The good news is that separating the keys means that your API 1 integrations and scripts will continue to function successfully while you work on making the necessary changes to leverage API 2.

To get the correct keys all you need to do is reach out to your Client Engagement or Partner team representative. They should be able to provide you with keys in short order.

So what’s the big deal?

Actually, it’s not that big of a deal to convert to API 2. The most significant changes we need to implement are based on the new headers and authentication scheme introduced in API version 2.0. In the sections below, I’m going to walk through updating your API 1 authentication code so that your script works with API 2

Reference API 2 documentation on headers can be found here, and documentation on authentication here.

Note: All code references here will be for Python. Keep an eye out for more information on other languages as we continue to publish more API information.

API1

The first iteration of the API only required two headers:

• X-Auth – This was simply the user’s public API key.
• X-Auth-Hash – This was a SHA256 HMAC hash of the user’s private key.

To successfully authenticate, you had to provide your public key and hashed private key. Let’s take a look!

Here’s my old API 1 script. Here’s the part we’re interested in:

public_key = ‘YOUR_PUBLIC_KEY’
private_key = ‘YOUR_PRIVATE_KEY’

search_query = '/view/iocs?format=json'

hashed = hmac.new(private_key, '', hashlib.sha256)

headers = {
     'X-Auth' : public_key,
     'X-Auth-Hash' : hashed.hexdigest()
}

As you can see, we’re hashing the private key in the code above. This results in a simple header that contains only X-Auth and X-Auth-Hash:

{'X-Auth': ' YOUR_PUBLIC_KEY', 'X-Auth-Hash': 'BORINGHARDTOREADHASH'}

After that, we build the request itself by combining the API domain (api.isightpartners.com), query and the headers. Then you can use the library of your choice to manage your response. See the linked sample, referenced above, for an example of how to print the response to your terminal window.

API2

With the release of API 2, we definitely beefed up our authentication requirements for successful requests, simplified the process to request response formats, and added a timestamp field to make it easier for our global customers to grab our intel no matter where they or their security integrations reside. We now have a much more diverse header list:

• X-Auth – Still just the user’s public API key.
• X-Auth-Hash – While still a SHA256 HMAC hash, we’re including a lot more data in the calculation this time around. We’ll come back to this in a moment.
• Accept – This is populated with the output format desired for the query response.
• Accept-Version – This is populated with the API 2 version that the user would like to query. As we update schemas and formats, we will only do so as part of a version change. This allows users who have existing integrations to keep them running as they test new versions.
• Content-Type – This header is specific to POST requests only, and indicates the type of content being uploaded. We won’t be using this in our code example for this exercise.
• Date – This is exactly what it sounds like! The date format must conform to section 5 of RFC 822. It will look similar to “Thu, 15 Oct 2015 16:52:50 -0400”.

As I pointed out above, the hash calculation is a bit more involved than it was in API 1. To calculate the hash, you need to concatenate the following items (don’t worry, we’ll show a code sample for this too):

• The query string
• The Accept-Version header
• The Accept header
• The timestamp in the Date header

These values are then hashed using the same functionality used in API 1.

Let’s take a look at how we accomplish this in API 2:

public_key = ‘YOUR_PUBLIC_KEY’
private_key = ‘YOUR_PRIVATE_KEY’

search_query = '/view/iocs'

accept_version = '2.0'
accept_header = 'application/json'
time_stamp = email.Utils.formatdate(localtime=True)

hash_data = search_query + accept_version + accept_header + time_stamp
hashed = hmac.new(private_key, hash_data, hashlib.sha256)

headers = {
     'Accept' : accept_header,
     'Accept-Version' : accept_version,
     'X-Auth' : public_key,
     'X-Auth-Hash' : hashed.hexdigest(),
     'Date' : time_stamp,
}

Ok, don’t let all of the variables scare you. I’m using them here so I only have to change them in one place when I want to update my code. As you can see, I’m using the hash_data variable to concatenate everything that isn’t an API key for hashing. You could do this manually, but this helps me keep everything organized.

You’ll also notice that I’ve dropped the ?format=json argument from the search_query. This is because this argument has been moved to the Accept header (accept_header variable in the code sample). It’s important to note this change as you will receive an error if the ?format= argument doesn’t match the accept_header.

Using this code will result in the following header:

{'Date': 'Thu, 15 Oct 2015 16:52:50 -0400', 'X-Auth-Hash': 'BORINGHARDTOREADHASH', 'Accept-Version': '2.0', 'Accept': 'application/json', 'X-Auth': ‘YOUR_PUBLIC_KEY’}

Look at all the new fields! After this is accomplished, it’s business as usual… Seriously. It’s exactly the same as the code we used in our API 1 script. You shouldn’t have to make any further changes to your script to use API 2!

If you want to look at an example, check out the new fangled API 2 script.

Or if you want a quick visual representation, here’s a screen grab of both scripts side by side (click to expand).

That’s It!

I’ve used a very simple code example utilizing the Indicators of Compromise endpoint, but you should be able to take this guidance and update any of your API 1 code to leverage API 2. As always, you can refer to the ThreatScape API documentation on our website for reference while troubleshooting or working with the new query endpoints. Happy coding!

The post What do you mean you’re not on API 2 yet? appeared first on iSIGHT Partners.