InfoSec: Querying the Recorded Future API using PowerShell

Recorded Future has a great Connect API with many options to retrieve, search or download every type of IOCs they offer as part of their subscription. Unfortunately, as most API providers out there, they only publish the instructions for accessing the API using common tools/languages (e.g. cURL, Python).

If you have a need to query their API using PowerShell because, for example, you are looking to add reputation checks to your O365 PowerShell Online script (or if you just prefer PowerShell), this post will hopefully save you a few minutes figuring out how to pass the API key to their API in the Invoke-WebRequest cmdlet.

Unlike most SaaS providers that make their API available for consumption nowadays, Recorded Future is different in that it does not require a username to be provided for API authentication. All you need is the key. Then, add the following property to your Invoke-WebRequest cmdlet:

-Headers @{"X-RFToken" = "api_key_here" }

So, for example, if your API key was "827ccb0eea8a706c4c34a16891f84e7b" (not an actual API key), a command to download the Recorded Future hash risk list would be:

Invoke-WebRequest -Headers @{"X-RFToken" = "827ccb0eea8a706c4c34a16891f84e7b" } -Method GET -ContentType "application/json" -Uri "https://api.recordedfuture.com/v2/hash/risklist?format=csv%2Fsplunk&gzip=false&list=positiveMalwareVerdict" -OutFile "out.csv"

Where to Find the Recorded Future API Key

Once you have your subscription and access to Recorded Future, you can get (or, rather, create) your API key under Menu - User Settings:

Click on "API Access" and use the "Generate New API Token" link to create a key, which will then be displayed in the list below (again, this isn't an actual API key):

Recorded Future API Documentation

Better than documentation, Recorded Future has a fantastic Connect API explorer page where you can, after plugging your API key in the top-right corner of the page, test all available API commands:

This page can be accessed at https://api.recordedfuture.com/v2/

A Note on Licensing

As expected, every API query uses up one usage "credit", but it should be noted that some of the queries (like the hash risk list used in the above examples) use up 5 credits per use. This can add up quickly when you're developing/testing something.

However, the Recorded Future's handy browser extension does not eat up your API credits.

Troubleshooting

If you get the following error, you need to add this to your code, to force the Invoke-WebRequest cmdlet to use TLS1.2:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Error:

Invoke-WebRequest : The underlying connection was closed: An unexpected error occurred on a send.
At line:1 char:1
+ Invoke-WebRequest -Headers @{"X-RFToken" = "827ccb0eea8a706c4c34a16891f84e7b...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-WebRequest], WebExc
   eption
    + FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeWebRequestCommand

Enjoy!