Blue Hexagon Verdict API

Overview

The Blue Hexagon API provides RESTful programmatic access to Blue Hexagon’s deep learning powered threat detection capabilities. To use the API, contact your Blue Hexagon representative to get your API key.

All API endpoints referenced in this guide use this common URL prefix:
https://verdict.gobluehexagon.ai

Quota

Your API key is limited by your licensing agreement in terms of rate and volume. For example:

1 request per second (average and burst)
30 requests per day

Responses

A valid response is usually JSON formatted, with all response fields encapsulated in a top-level “bluehexagon” key:

{

"bluehexagon": {

...

}

Your API request may receive any of the following HTTP status codes:

Code	Description
200	Request was correctly handled by the server with no errors produced.
400	Bad request. The request likely contains missing or invalid arguments.
403	Forbidden. The request contains a missing or invalid API key, or your API key is not authorized to access the API endpoint.
429	Request rate limit exceeded. You have exceeded your quota (see above). Quota is reset every day at 0000 UTC.
5xx	Service errors.

GET /file/report

Params

sha256 : SHA256 of file for which to retrieve latest report

Returns

prediction : malicious / benign
score : confidence in verdict, range [0.5, 1.0]
category : threat category (one of sixteen categories)
family : threat family
cve : cve numbers for CVEs associated with threat
severity : threat severity (low, medium, high, or critical)
filetype : type of file
filesize : size of file
descendant_sha256 : for an archive file, SHA256 of files contained in archive
scan_time : timestamp in UTC of latest scan
iocs : detailed explanation report on behavior of sample

Description

Given the sha256 of a file, returns the latest existing Blue Hexagon verdict for that file (if any). If Blue Hexagon has never seen that sha256 before, prediction:NOTFOUND will be returned.

Example

Request

curl -H "x-api-key: YOUR-API-KEY" https://verdict.gobluehexagon.ai/file/report?sha256=00eccee470630aae9da556e2779ce2f6cc8bc93c98f0cc438920237cc014f07c

Response

{

"bluehexagon": {

"prediction": "malicious",

"score": 1.0,

"category": "trojan",

"family": "gepys",

"cve": [],

"severity": "medium",

"filetype": "exe",

"filesize": 147720,

"scan_time": "2020-08-12 00:22:40.603174"

}

POST /file/scan

Params

file : file to be analyzed

Returns

sha256 : SHA256 of file
prediction : malicious / benign
score : confidence in verdict, range [0.5, 1.0]
category : threat category (one of sixteen categories)
family : threat family
cve : cve numbers for CVEs associated with threat
severity : threat severity (low, medium, high, or critical)
filetype : type of file
filesize : size of file
descendant_sha256 : for an archive file, SHA256 of files contained in archive
scan_time : timestamp in UTC of latest scan

Description

Given a file (up to 5MB), scan and return the Blue Hexagon verdict for that file. Returns “no verdict” for unsupported filetypes.

Example

Request

curl -XPOST https://verdict.gobluehexagon.ai/file/scan -H "x-api-key: YOUR-API-KEY" -F "file=@/Users/ubuntu/test.xlsx"

Response

{

"bluehexagon": {

"prediction": "malicious",

"score": 1.0,

"category": "exploit",

"family": "cve-2017-11882",

"cve": [

"cve-2017-11882",

"cve-2017-1182"

],

"severity": "high",

"filesize": 214853,

"filetype": "ms-excel",

"sha256": "0bbd195e4ac0ab25a4c74fb96923f25ac4b22ffb962148ddc7e380580dc69f84",

"scan_time": "2020-08-12 05:35:29.923226"

}

POST /file/rescan

Params

sha256 : SHA256 of file for which to retrieve latest report

Returns

prediction : malicious / benign
score : confidence in verdict, range [0.5, 1.0]
category : threat category (one of sixteen categories)
family : threat family
cve : cve numbers for CVEs associated with threat
severity : threat severity (low, medium, high, or critical)
filetype : type of file
filesize : size of file
descendant_sha256 : for an archive file, SHA256 of files contained in archive
scan_time : timestamp in UTC of latest scan

Description

Given the sha256 of a file in JSON format, rescan and return the Blue Hexagon verdict for that file. If Blue Hexagon has never seen that sha256 before, prediction:NOTFOUND will be returned.

Example

Request

curl -XPOST https://verdict.gobluehexagon.ai/file/rescan -H "x-api-key: YOUR-API-KEY" -d '{"sha256":"00eccee470630aae9da556e2779ce2f6cc8bc93c98f0cc438920237cc014f07c"}'

Response

{

"bluehexagon": {

"prediction": "malicious",

"score": 1.0,

"category": "trojan",

"family": "gepys",

"cve": [],

"severity": "medium",

"filesize": 147720,

"filetype": "exe",

"sha256": "00eccee470630aae9da556e2779ce2f6cc8bc93c98f0cc438920237cc014f07c",

"scan_time": "2020-08-12 00:22:40.603174"

}

POST /ip/offender

Params:

from (optional. Default: 14 days ago)
to (optional. Default: now)
max_result (optional. Default: 200)
score_min (optional. Default: 0.0)
exclude (optional. Can be used to point to a file containing a list of IPs (one line per IP))

Returns
JSON formatted list of items where each item contains:

deployment : name of deployment / appliance
orig_h : ip address of impacted asset
attack : list of security findings
score: risk score associated with orig_h
hostname: list of hostnames associated with ip address
mac_list: list of MAC addresses associated with ip address
user_list: list of users known to be associated with ip address

Description:

Returns a list of ip addresses that have the highest risk score along with any associated user, host or mac address information. The attack types exhibited by the offender are also listed

Example
Request

curl https://verdict.gobluehexagon.ai/ip/offenders -H "x-api-key: YOUR-API-KEY" -F "from=14 days ago" -F "to=now" -F "max_result=20" -F "score_min=0"