Blue Hexagon Insights API

Owned by Andrew Nelson (Unlicensed)
Last updated: Feb 23, 2022
3 min read

Overview

The Blue Hexagon Insights API provides RESTful programmatic access to Blue Hexagon’s deep learning powered insights into the enriched cloud and network metadata gathered by Blue Hexagon sensors deployed in your environment. 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://api.gobluehexagon.ai/data

Quota

Your API key is limited by your licensing agreement in terms of total volume, average and burst rates to the following:

  • 1000 requests per day

  • 1 request per minute (average and burst)

Responses

A valid response is usually JSON formatted. Your API request may receive any of the following HTTP status codes:



GET /insights

Params

  • None

Returns

  • dictionary { index_name: [list of supported insights] }



Description

Enumerate datastore indexes that have insights and enumerate all supported insights for each index. Specify index_name and insight in other APIs.

Example

Request

curl -H "x-api-key: YOUR-API-KEY" https://api.gobluehexagon.ai/data/insights



Response

{  "dns_logs": ["least_queried_domains", "rare_dns_servers", "top_clients_with_dns_errors", "top_dns_data_uploaders", "top_dns_servers", "top_querying_clients"],   "conn_logs": ["longest_connections_by_orig_h", "longest_connections_by_resp_h", "max_connections_by_orig_h", "max_connections_by_resp_h", "top_downloaders_by_orig_h", "top_downloaders_by_resp_h", "top_external_downloaders_by_orig_h", "top_external_uploaders_by_orig_h", "top_uploaders_by_orig_h", "top_uploaders_by_resp_h"],  "ssl_logs": ["rare_certificates", "rare_ja3_hash"],  "cloudtrail_logs": ["cloudtrail_changes", "console_login_failures", "erroneous_activity", "iam_policy_changes", "network_acl_changes", "s3_bucket_activity", "security_group_changes", "unauthorized_activity", "vpc_changes"]}

 

 

POST /insight

Params

  • index : datastore index against which to run insight (e.g. "dns_logs", see GET /insights)

  • insight : name of desired insight (e.g. "top_dns_servers", see GET /insights)

  • time_from: time from which to get results in almost any format (e.g. "now-1d")

  • time_to: time until which to get results in almost any format (e.g. "now")

Returns

  • aggregations

  • hits



Description

Return all data corresponding to desired insight. Data returned may be either aggregations or hits. Some insights are aggregations, with data bucketed into keys and values; while other insights are filters and are returned as hits. The client can iterate through the returned aggregations or hits as needed.

Example

Request

curl -H "x-api-key: YOUR-API-KEY" -H "Content-Type: application/json" https://api.gobluehexagon.ai/data/insight -d '{"index": "dns_logs", "insight": "top_dns_servers", "time_from": "now-1d", "time_to": "now"}' | jq -r '.top_dns_servers.buckets[] | [ .key, .sum_count.value ] | @csv'



Response



"169.254.169.254",42990

"10.203.0.2",31307

"10.201.0.2",31145

"10.192.0.2",12315

"172.16.0.2",56

 

 

 

POST /query

Params

  • index : datastore index against which to run insight (e.g. "dns_logs", see GET /insights)

  • q : query in Elasticsearch Query DSL (e.g. {"query": {"match": {"resp_h": "80.92.206.168"}}})

  • time_from: time from which to get results in almost any format (e.g. "now-1d")

  • time_to: time until which to get results in almost any format (e.g. "now")

  • (optional pagination support) from: number of hits to skip (default 0)

  • (optional pagination support) size: maximum number of hits to return

Returns

  • hits: dictionary containing total number of hits and array of hits documents 



Description

Run query in Elasticsearch Query DSL to access enriched data in specified index.

Example

Request

import json

import requests

import sys



data = {

 "index": "object_logs",

 "q": {"query": {"match": {"resp_h": "52.11.127.211"}}},

 "time_from": "now-30d",

 "time_to": "now"

}



headers = {

  'x-api-key': sys.argv[1] # YOUR-API-KEY

}



r = requests.post("https://api.gobluehexagon.ai/data/query",

                data=json.dumps(data),

                headers=headers)

print(json.dumps(r.json()))

 

Response

{"hits": {"total": 89, "hits": [{"_source": {"filesize": 14336, "http_uri": "http://s3.amazonaws.com/[SNIPPED]/mal2.exe", "http_host": "s3.amazonaws.com", "hash": "3b87b6e1c722fcf5fa1b5f8841b923eff40c4fee67c096c1901be4207a13e0d4", "prediction": "malicious", "filename": "mal2.exe", "cve": [], "ts": "2021-07-15 17:20:18.181152", "source_location": "45.8696,-119.688", "source_location_accuracy": 1000, "overflow_bytes": 0, "total_bytes": 0, "resp_p": 443, "category": "trojan", "mime_type": "application/x-dosexec", "resp_h": "52.11.127.211", "source_host": "52.11.127.211", "score": 1.0, "bhid": "3aece9eb-0f57-4211-817a-439d13d6356b", [SNIPPED]]}}

Blue Hexagon Proprietary