How to Import IOCs into the CrowdStrike Falcon Platform via API

Introduction

As part of the CrowdStrike Falcon Query API, the “IOC import” allows you to retrieve, upload, update, search, and delete custom indicators of compromise (IOCs) that you want CrowdStrike to watch.

Prerequisites

Before using any of the Query APIs, you must contact support@crowdstrike.com to enable access and to obtain a username and password. The credentials for the Query APIs are the same as the Falcon Threat Graph API but are different from the credentials used for the Falcon Streaming API and Falcon Intel APIs. Learn more about How to get access to CrowdStrike APIs.

The examples below will walk you through the first steps with the API. Two different tools are used to demonstrate the API calls:

  1. A Chrome Extension called Postman (recommended for API testing on Windows or Mac)
  2. The command line browser cURL (recommended for API testing on Mac or Linux). In addition to cURL, we are also using a JSON tool called jq to help with formatting and improve human readability on the command line (totally optional)

As example IOCs we will be using the domain “tme-lab.com” (no content is hosted on this domain, it is purely used for testing) and the file “this_does_nothing.exe” (this_does_nothing.exe (zipped), Source Code (zipped), sha256: 4e106c973f28acfc4461caec3179319e784afa9cd939e3eda41ee7426e60989f, )

Importing an IOC

Postman:

1: Every request to the CrowdStrike Falcon Query API requires a username and password. Due to the “query/response” nature of the API, no session or cookie is needed for requests.

In the Postman interface first select the HTTP method from the drop down and set it to “POST”
In the URL field enter the URL for the IOC Import:

https://falconapi.crowdstrike.com/indicators/entities/iocs/v1

Then select the first tab called “Authorization” and enter your username and password for the API. A click on “Update Request” will save the username and password in the correct format.

1-authorization

 

2: Switch to the second tab called “Headers” and click below the existing “Authorization” header to add a new header to the request.

In the first field (the header name) enter “Content-Type” (Postman will help with auto completion once you start typing).
In the second field (the header value) type “application/json” (again, Postman will help with auto completion)

02-content-type

 

3: Now it is time to actually add the IOCs that we want to import.

You can import individual IOCs or multiple in one request.

For our example, we will add an IOC for the domain “tme-lab.com” and the file hash “4e106c973f28acfc4461caec3179319e784afa9cd939e3eda41ee7426e60989f”.
To see a full list of IOC types and options available for import, please consult the “Falcon – Query API Reference” which is part of the Crowdstrike Documentation package in the UI.

In Postman, select the third tab called “Body” and then select “raw” as the data format. The actual body of our POST request will be JSON text.

[
    {
        "type":"sha256",
        "value":"4e106c973f28acfc4461caec3179319e784afa9cd939e3eda41ee7426e60989f",
        "description":"description",
        "share level":"red",
        "source":"source",
        "policy":"detect"
    },
    {
        "type":"domain",
        "value":"tme-lab.com",
        "description":"description",
        "share level":"red",
        "source":"source",
        "policy":"detect",
        "expiration_days": 1
    }
]

After entering the content of the JSON body, click “Send” to submit your request to add our two IOCs via the API.

JSON Body

 

4: If everything went well, you will receive a “HTTP 200 OK” response with no “errors” in the body of the response.

If you do receive errors on this test, double check your username and password (it needs to be the username and password for the Query API!). Further troubleshooting help can be found in the “Falcon – Query API Reference” which is part of the CrowdStrike Documentation package in the UI.

API Response

 

cURL:

The requirements for cURL are the same as for Postman:

  • username/password in every request
  • set the Content-Type header
  • send raw JSON as the body

The difference is that cURL does all three things in one step:

curl -X POST -s -H "Content-Type: application/json" -u "youruser:yourkey" "https://falconapi.crowdstrike.com/indicators/entities/iocs/v1" -d '[{"type":"sha256","value":"4e106c973f28acfc4461caec3179319e784afa9cd939e3eda41ee7426e60989f","description":"description","share level":"red","source":"source","policy":"detect"},{"type":"domain","value":"tme-lab.com","description":"description","share level":"red","source":"source","policy":"detect","expiration_days": 1}]' | jq '.'

Note: the “| jq ‘.’” at the end is purely for formatting the response from the API.

cURL add IOCs

 

If you do receive errors on this test, double check your username and password (it needs to be the username and password for the Query API!). Further troubleshooting help can be found in the “Falcon – Query API Reference” which is part of the CrowdStrike Documentation package in the UI.

Listing IOCs

Postman:

Change your HTTP Method in the drop down to “GET” and the URL to

https://falconapi.crowdstrike.com/indicators/queries/iocs/v1?types=sha256&types=domain

Note that multiple IOC types can be searched for in the same query by adding more “types” to the end of the URL.

Once you hit “Send” the response field will populate with JSON data, showing the two IOCs we uploaded in the previous step.

search IOCs

 

 

cURL:

Running the below cURL command will show the two IOC entries we made in the previous step:

curl -s -X GET -H "Content-Type: application/json" -u "youruser:yourkey" "https://falconapi.crowdstrike.com/indicators/queries/iocs/v1?types=domain&types=sha256" | jq '.'

cURL search IOCs

 

An example detection from an imported IOC

To demonstrate what a detection based on your custom IOC looks like, we will use a windows machine with CrowdStrike Falcon installed.
You can run our test tool “this_does_nothing.exe” (see beginning of article) and verify in the command window that opens, that the sha256 hash matches the hash in the IOC we uploaded.


run test file

 

Immediately after you execute the test tool, you will now see a detection in the Falcon UI (or via the Streaming API/SIEM Connector).

IOC Detection

 

Keep in mind that not all types of IOCs will produce a detection in the UI. Please see the “Falcon – Query API Reference” for more details.

Deleting an IOC

Postman:

To demonstrate the deletion of an existing IOC, we will be removing the sha256 hash of our test tool from the IOC list.

Please change your HTTP method from the drop down to “DELETE” and the URL to

https://falconapi.crowdstrike.com/indicators/entities/iocs/v1?ids=sha256:4e106c973f28acfc4461caec3179319e784afa9cd939e3eda41ee7426e60989f

Note that multiple IOCs can be deleted by adding additional “ids” to the end of the URL

After clicking “SEND” you should see a JSON response with no errors reported.

delete IOC


To verify that our file hash got deleted, we will execute the same search as in the “Listing IOCs” again.

Switch the HTTP method to “GET” and the URL to

https://falconapi.crowdstrike.com/indicators/queries/iocs/v1?types=sha256&types=domain

After clicking “SEND” you should now see the JSON response containing only our domain tme-lab.com but no longer the file hash 4e106c973f28acfc4461caec3179319e784afa9cd939e3eda41ee7426e60989f

verify deletion

 

cURL:

Run the following cURL command to delete the sha256 IOC:

curl -X DELETE -s -H "Content-Type: application/json" -u "youruser:yourkey" "https://falconapi.crowdstrike.com/indicators/entities/iocs/v1?ids=sha256:4e106c973f28acfc4461caec3179319e784afa9cd939e3eda41ee7426e60989f" | jq '.'

03-curl-delete

To verify that your deleted IOC has been removed from the list, you can run the same command as in “Listing IOCs:

curl -s -X GET -H "Content-Type: application/json" -u "youruser:yourkey" "https://falconapi.crowdstrike.com/indicators/queries/iocs/v1?types=domain&types=sha256" | jq '.'

cURL search IOCs

 

Conclusion

This guide is intended to get you started with the IOC import API on the CrowdStrike Falcon Platform. There are many more options and details described in the “Falcon – Query API Reference” which is part of the Documentation package in the Falcon UI.

More resources

 

Stop Breaches with CrowdStrike Falcon request a live demo