SQL Search API Documentation

Intro

Hunt SQL search can be queried via an API interface which is now available to customers. This allows users to query Hunt intelligence data programatically and integrate it directly into custom workflows and internal tooling.

How To Reach the API

The SQL Search API can be called at the following URL.

https://api.hunt.io/v1/sql

Requests will require an authorization token, you can find your token at the following URL.

https://app.hunt.io/token

How to Perform a Request

Requests to the SQL search API can be made via GET requests to https://api.hunt.io/v1/sql.

An example is provided below via the CURL utility. Noting the following requirement.

1. Requests must contain an authorization token inside the token header
2. Queries must be placed inside the query parameter in the URL. This can be added by appending ?query= followed by your query.
3. SQL queries should be URL encoded if special characters are used.

curl --request GET \
     --url https://api.hunt.io/v1/sql?query=<your query> \
     --header 'accept: application/json' \
     --header 'token: <your_token>'

Performing a Request With Curl

An example of a complete request using the CURL utility is shown below.

The example query is SELECT * FROM malware, which has been URL encoded and placed inside the query parameter.

curl --request GET \
     --url https://api.hunt.io/v1/sql?query=select%20%2A%20from%20malware \
     --header 'accept: application/json' \
     --header 'token: <your-token>'

Performing a Request With Powershell

Below is an example of SELECT * FROM malware performed via Powershell.

$headers = @{
    "accept" = "application/json"
    "token" = "<your-token>"
}
$response = Invoke-WebRequest -Uri "https://api.hunt.io/v1/sql?query=select%20%2A%20from%20malware" -Headers $headers

Performing a Request With Python

Below is an example of SELECT * FROM malware performed via Python.

import requests

url = "https://api.hunt.io/v1/sql?query=select%20%2A%20from%20malware"

headers = {
    "accept": "application/json",
    "token": "<your-token>"
}

response = requests.get(url, headers=headers)

print(response.text)

How to Specify Pagination and Size

Users may want to limit results and retrieve specific pages from returned data, this is especially useful for queries that return a lot of results, or where only the most recent results are desired.

SQL search caters for this with the page and size parameters. This allows users to retrieve specific pages from search results, or to limit how many results are displayed per page.

A default page will return 50 results - providing the size parameter allows up to 500.

Example Request With Pagination and Size

For example, this is a request for select url from urlx where url RLIKE '\/api$', showing the first 10 results.

#Set accept format and provide Auth token
$headers = @{
    "accept" = "application/json"
    "token" = "<your-token>"
}
#URL encode query string, specify page and size
$query = [URI]::EscapeUriString("select url from urlx where url RLIKE '\/api$'")
$page = 1
$size = 10

#Execute the query
$full_uri = "https://api.hunt.io/v1/sql?query={0}&page={1}&size={2}" -f $query,$page,$size

#Perform request
$response = Invoke-WebRequest -Uri $full_uri -Headers $headers

#print response data
$response.content

Regular Expressions

Most fields allow for re2 regular expressions via the RLIKE operator.

Regular expressions should be enclosed in single quotes, and do NOT require forward slashes /at the start or end of the expression.

Here are some examples to help get you started.

1. SELECT url FROM urlx WHERE url RLIKE '\/api$'
2. SELECT ip, header.raw FROM http WHERE header.raw RLIKE '.*X-Havoc.*'
3. SELECT ip, subject.common_name FROM certificates WHERE subject.common_name RLIKE 'AsyncRAT.*'

Returned Data

Data is returned in JSON format with the fields that were requested in the SQL query. Available fields vary considerably between tables, and we strongly recommend checking the main SQL page for the latest fields available.