Blue Hexagon Verdict API
- Andrew Nelson (Unlicensed)
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"
Blue Hexagon Proprietary