REST Reference

This document describes the official AlphaSOC REST API. The primary purpose of the API is to allow a wide variety of clients for sending network telemetry and receiving alerts. API endpoints are complementary to other data sources and alert escalations in a way that alerts generated for network telemetry submitted outside of the API are available to download via API and vice versa.

Schema

The API can be accessed at https://api.alphasoc.net over HTTPS. All requests and responses are encoded in JSON.

Compression

As the amount of data transmitted via API can be high, it's advisable to use the compression both ways. Usually HTTP clients transparently support compression when fetching data (by providing Accept-Encoding header), but the upload needs to be handled manually. AlphaSOC API supports gzip and deflate compression algorithms and it's recommended to compress large chunks of data (telemetry) before sending, along with attaching corresponding Content-Encoding header.

Rate limiting

API counts and limits number of requests from a single API key. The limits are not strictly defined and designed to protect from flooding and accidental errors in client's implementation. In the unlikely case of hitting the limit API returns 429 Too Many Requests response and expects the client to retry after some time.

Authentication

All the API requests should be authenticated using Basic Authentication where API key is provided as a username and leaving the password empty.

You can generate API keys in the console.

Responses

Status	Meaning	Description	Schema
200	OK	OK	-
400	Bad Request	Bad Request	errorMessage
401	Unauthorized	Bad Request	errorMessage
403	Forbidden	Forbidden	errorMessage
429	Too Many Requests	Too Many Requests	errorMessage

Account management

GET /v1/account/status

This call can be used to fetch general information about the account, e.g. registration status, key expiration time, and current license usage. Human-readable messages from the system are also included in the response, so they can be presented in the UI.

Responses

Status	Meaning	Description	Schema
200	OK	OK	accountStatus

Example 200 response

{
  "today": "2018-08-28T10:33:37.137110423Z",
  "registered": false,
  "expired": false,
  "expirationDate": "2018-09-27T10:31:32.196658Z",
  "endpointsSeenToday": 2338,
  "messages": [
    {
      "level": 2,
      "body": "Your API key is not activated. Alerts are suppressed until you have activated your account."
    }
  ]
}

To perform this operation, you must be authenticated by means of one of the following methods: basicAuth

Code samples

curl -X GET -u "<your-api-key>:"  https://api.alphasoc.net/v1/account/status \
  -H 'Accept: application/json' 

Retrieving Alerts

GET /v1/alerts

This endpoint allows for fetching alerts generated by network telemetry submitted to the AlphaSOC Analytics Engine (via API or other sources). Each alert includes the original (although normalized) event along with the associated threats and context.

Threat details can be accessed via additional threats dictionary included in the response, but note that for a given threat ID the description and severity can be amended at any time – in such the case the changes are valid for all the historical alerts already retrieved. The full and most recent threat dictionary is also available using (inventory endpoints)[#inventory].

As the number of alerts can be high, API uses pagination in order to limit individual responses. In every response there is a follow bookmark attached, which should be passed to consecutive requests as a parameter, so only new alerts are being returned. Once the last page is returned more property in the response is set to false.

Usually the flow for retrieving alerts looks like this:

1. Fetch new alerts via /v1/alerts?follow={lastFollowBookmark}.
2. If response.More == true then go back to [1] immediately.
3. If response.More == false then sleep for some time and go back to [1].

Parameters

Name	In	Type	Required	Description
follow	query	string	false	Page bookmark as provided by one of the previous responses. Only new alerts since the bookmark will be returned.

Responses

Status	Meaning	Description	Schema
200	OK	OK	alerts

Example 200 response

{
  "follow": "string",
  "more": true,
  "alerts": [
    {
      "eventType": "string",
      "threats": [
        "c2_communication"
      ],
      "wisdom": {
        "flags": [
          "c2",
          "young_domain"
        ],
        "labels": [
          "c2:TrickBot"
        ],
        "domain": "example.com"
      },
      "event": {
        "ts": "2018-03-01T10:31:59Z",
        "srcIP": "192.168.20.5",
        "srcPort": 32876,
        "srcHost": "john-pc",
        "srcMac": "16:c8:60:26:09:a6",
        "srcUser": "john",
        "srcID": "string",
        "query": "www.example.com",
        "qtype": "A"
      }
    }
  ],
  "threats": {
    "c2_communication": {
      "title": "C2 communication attempt indicating infection",
      "severity": 5
    },
    "cryptomining": {
      "title": "Cryptomining indicating infection or resource abuse",
      "severity": 4
    }
  }
}

To perform this operation, you must be authenticated by means of one of the following methods: basicAuth

Code samples

curl -X GET -u "<your-api-key>:" --compressed https://api.alphasoc.net/v1/alerts \
  -H 'Accept: application/json' 

Sending Telemetry

Network telemetry can be submitted for scoring using multiple endpoints – each one for specific type of events (DNS, IP, etc.). Events are submitted in batches containing a stream of JSON objects with every object representing an individual network event. For example:

{dnsEvent1}{dnsEvent2}{dnsEvent3}...

There is no limit for number of events one can send, but there is a limit of uncompressed body size (currently 10MB). It is advisable to compress the data before uploading, see Compression for details.

POST /v1/events/dns

Parameters

Name	In	Type	Required	Description
Content-Encoding	header	string	false	Sets compression
body	body	dnsEvent	false	none

Body parameter

{
  "ts": "2018-03-01T10:31:59Z",
  "srcIP": "192.168.20.5",
  "srcPort": 32876,
  "srcHost": "john-pc",
  "srcMac": "16:c8:60:26:09:a6",
  "srcUser": "john",
  "srcID": "string",
  "query": "www.example.com",
  "qtype": "A"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	eventsResponseBody

Example 200 response

{
  "received": 100,
  "accepted": 100
}

To perform this operation, you must be authenticated by means of one of the following methods: basicAuth

Code samples

# Without compression
curl -X POST -u "<your-api-key>:"  https://api.alphasoc.net/v1/events/dns \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"ts":"2018-03-01T10:31:59Z","srcIP":"192.168.20.5","srcPort":32876,"srcHost":"john-pc","srcMac":"16:c8:60:26:09:a6","srcUser":"john","srcID":"string","query":"www.example.com","qtype":"A"}'

# With compression
curl -u "<your-api-key>:" https://api.alphasoc.net/v1/events/dns \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Content-Encoding: gzip' \
  --data-binary @<(echo '{"ts":"2018-03-01T10:31:59Z","srcIP":"192.168.20.5","srcPort":32876,"srcHost":"john-pc","srcMac":"16:c8:60:26:09:a6","srcUser":"john","srcID":"string","query":"www.example.com","qtype":"A"}' | gzip)

POST /v1/events/ip

Parameters

Name	In	Type	Required	Description
Content-Encoding	header	string	false	Sets compression
body	body	ipEvent	false	none

Body parameter

{
  "ts": "2018-03-01T10:31:59Z",
  "srcIP": "192.168.20.5",
  "srcPort": 32876,
  "srcHost": "john-pc",
  "srcMac": "16:c8:60:26:09:a6",
  "srcUser": "john",
  "srcID": "string",
  "destIP": "8.8.8.8",
  "destPort": 23,
  "proto": "udp",
  "bytesIn": 3911,
  "bytesOut": 2512,
  "app": "ssl",
  "action": "allowed",
  "duration": 7.2
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	eventsResponseBody

Example 200 response

{
  "received": 100,
  "accepted": 100
}

To perform this operation, you must be authenticated by means of one of the following methods: basicAuth

Code samples

# Without compression
curl -X POST -u "<your-api-key>:"  https://api.alphasoc.net/v1/events/ip \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"ts":"2018-03-01T10:31:59Z","srcIP":"192.168.20.5","srcPort":32876,"srcHost":"john-pc","srcMac":"16:c8:60:26:09:a6","srcUser":"john","srcID":"string","destIP":"8.8.8.8","destPort":23,"proto":"udp","bytesIn":3911,"bytesOut":2512,"app":"ssl","action":"allowed","duration":7.2}'

# With compression
curl -u "<your-api-key>:" https://api.alphasoc.net/v1/events/ip \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Content-Encoding: gzip' \
  --data-binary @<(echo '{"ts":"2018-03-01T10:31:59Z","srcIP":"192.168.20.5","srcPort":32876,"srcHost":"john-pc","srcMac":"16:c8:60:26:09:a6","srcUser":"john","srcID":"string","destIP":"8.8.8.8","destPort":23,"proto":"udp","bytesIn":3911,"bytesOut":2512,"app":"ssl","action":"allowed","duration":7.2}' | gzip)

POST /v1/events/tls

Parameters

Name	In	Type	Required	Description
Content-Encoding	header	string	false	Sets compression
body	body	tlsEvent	false	none

Body parameter

{
  "ts": "2018-03-01T10:31:59Z",
  "srcIP": "192.168.20.5",
  "srcPort": 32876,
  "srcHost": "john-pc",
  "srcMac": "16:c8:60:26:09:a6",
  "srcUser": "john",
  "srcID": "string",
  "certHash": "9fcc5c1e8ec32f56e975ba43c923dbfa16a8f946",
  "issuer": "C=US; O=DigiCert Inc; OU=www.digicert.com; CN=GeoTrust RSA CA 2018",
  "subject": "C=US,ST=TX,L=Texas,O=lol,OU=,CN=example.com",
  "validFrom": "2021-03-30T00:34:02Z",
  "validTo": "2021-05-29T00:34:02Z",
  "destIP": "188.68.55.50",
  "destPort": 9001,
  "ja3": "724dedf93fb5a3636a0f1ee8fcec8801",
  "ja3s": "015535be754766257f9bfdf3470cd428e0f1cfd4"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	eventsResponseBody

Example 200 response

{
  "received": 100,
  "accepted": 100
}

To perform this operation, you must be authenticated by means of one of the following methods: basicAuth

Code samples

# Without compression
curl -X POST -u "<your-api-key>:"  https://api.alphasoc.net/v1/events/tls \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"ts":"2018-03-01T10:31:59Z","srcIP":"192.168.20.5","srcPort":32876,"srcHost":"john-pc","srcMac":"16:c8:60:26:09:a6","srcUser":"john","srcID":"string","certHash":"9fcc5c1e8ec32f56e975ba43c923dbfa16a8f946","issuer":"C=US; O=DigiCert Inc; OU=www.digicert.com; CN=GeoTrust RSA CA 2018","subject":"C=US,ST=TX,L=Texas,O=lol,OU=,CN=example.com","validFrom":"2021-03-30T00:34:02Z","validTo":"2021-05-29T00:34:02Z","destIP":"188.68.55.50","destPort":9001,"ja3":"724dedf93fb5a3636a0f1ee8fcec8801","ja3s":"015535be754766257f9bfdf3470cd428e0f1cfd4"}'

# With compression
curl -u "<your-api-key>:" https://api.alphasoc.net/v1/events/tls \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Content-Encoding: gzip' \
  --data-binary @<(echo '{"ts":"2018-03-01T10:31:59Z","srcIP":"192.168.20.5","srcPort":32876,"srcHost":"john-pc","srcMac":"16:c8:60:26:09:a6","srcUser":"john","srcID":"string","certHash":"9fcc5c1e8ec32f56e975ba43c923dbfa16a8f946","issuer":"C=US; O=DigiCert Inc; OU=www.digicert.com; CN=GeoTrust RSA CA 2018","subject":"C=US,ST=TX,L=Texas,O=lol,OU=,CN=example.com","validFrom":"2021-03-30T00:34:02Z","validTo":"2021-05-29T00:34:02Z","destIP":"188.68.55.50","destPort":9001,"ja3":"724dedf93fb5a3636a0f1ee8fcec8801","ja3s":"015535be754766257f9bfdf3470cd428e0f1cfd4"}' | gzip)

POST /v1/events/http

Parameters

Name	In	Type	Required	Description
Content-Encoding	header	string	false	Sets compression
body	body	httpEvent	false	none

Body parameter

{
  "ts": "2018-03-01T10:31:59Z",
  "srcIP": "192.168.20.5",
  "srcPort": 32876,
  "srcHost": "john-pc",
  "srcMac": "16:c8:60:26:09:a6",
  "srcUser": "john",
  "srcID": "string",
  "url": "http://microsoft775.com/wpad.dat",
  "method": "GET",
  "status": 200,
  "app": "http",
  "action": "allowed",
  "bytesIn": 4321,
  "bytesOut": 1234,
  "contentType": "text/html; charset=utf-8",
  "referrer": "someone.com",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	eventsResponseBody

Example 200 response

{
  "received": 100,
  "accepted": 100
}

To perform this operation, you must be authenticated by means of one of the following methods: basicAuth

Code samples

# Without compression
curl -X POST -u "<your-api-key>:"  https://api.alphasoc.net/v1/events/http \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"ts":"2018-03-01T10:31:59Z","srcIP":"192.168.20.5","srcPort":32876,"srcHost":"john-pc","srcMac":"16:c8:60:26:09:a6","srcUser":"john","srcID":"string","url":"http://microsoft775.com/wpad.dat","method":"GET","status":200,"app":"http","action":"allowed","bytesIn":4321,"bytesOut":1234,"contentType":"text/html; charset=utf-8","referrer":"someone.com","userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36"}'

# With compression
curl -u "<your-api-key>:" https://api.alphasoc.net/v1/events/http \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Content-Encoding: gzip' \
  --data-binary @<(echo '{"ts":"2018-03-01T10:31:59Z","srcIP":"192.168.20.5","srcPort":32876,"srcHost":"john-pc","srcMac":"16:c8:60:26:09:a6","srcUser":"john","srcID":"string","url":"http://microsoft775.com/wpad.dat","method":"GET","status":200,"app":"http","action":"allowed","bytesIn":4321,"bytesOut":1234,"contentType":"text/html; charset=utf-8","referrer":"someone.com","userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36"}' | gzip)

POST /v1/events/lease

Parameters

Name	In	Type	Required	Description
Content-Encoding	header	string	false	Sets compression
body	body	leaseEvent	false	none

Body parameter

{
  "ts": "2018-03-01T10:31:59Z",
  "srcIP": "192.168.20.5",
  "srcPort": 32876,
  "srcHost": "john-pc",
  "srcMac": "16:c8:60:26:09:a6",
  "srcUser": "john",
  "srcID": "string",
  "type": "string",
  "termination": true,
  "duration": 5.4
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	eventsResponseBody

Example 200 response

{
  "received": 100,
  "accepted": 100
}

To perform this operation, you must be authenticated by means of one of the following methods: basicAuth

Code samples

# Without compression
curl -X POST -u "<your-api-key>:"  https://api.alphasoc.net/v1/events/lease \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"ts":"2018-03-01T10:31:59Z","srcIP":"192.168.20.5","srcPort":32876,"srcHost":"john-pc","srcMac":"16:c8:60:26:09:a6","srcUser":"john","srcID":"string","type":"string","termination":true,"duration":5.4}'

# With compression
curl -u "<your-api-key>:" https://api.alphasoc.net/v1/events/lease \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Content-Encoding: gzip' \
  --data-binary @<(echo '{"ts":"2018-03-01T10:31:59Z","srcIP":"192.168.20.5","srcPort":32876,"srcHost":"john-pc","srcMac":"16:c8:60:26:09:a6","srcUser":"john","srcID":"string","type":"string","termination":true,"duration":5.4}' | gzip)

Inventory

GET /v1/ae/inventory/threats

Responses

Status	Meaning	Description	Schema
200	OK	OK	aeThreats

Example 200 response

{
  "threats": {
    "c2_communication": {
      "title": "C2 communication attempt indicating infection",
      "severity": 5
    },
    "cryptomining": {
      "title": "Cryptomining indicating infection or resource abuse",
      "severity": 4
    }
  }
}

To perform this operation, you must be authenticated by means of one of the following methods: basicAuth

Code samples

curl -X GET -u "<your-api-key>:"  https://api.alphasoc.net/v1/ae/inventory/threats \
  -H 'Accept: application/json' 

GET /v1/ae/inventory/flags

Responses

Status	Meaning	Description	Schema
200	OK	OK	aeFlags

Example 200 response

{
  "flags": {
    "c2": {
      "title": "Known C2 callback destination",
      "type": "category"
    },
    "freedns": {
      "title": "Parent domain is a dynamic DNS provider",
      "type": "feature"
    }
  }
}

To perform this operation, you must be authenticated by means of one of the following methods: basicAuth

Code samples

curl -X GET -u "<your-api-key>:"  https://api.alphasoc.net/v1/ae/inventory/flags \
  -H 'Accept: application/json' 

Schemas

accountStatus

Properties

|Name|Type|Required|Description| |---|---|---|---|---| |today|string(date-time)|false|Today's date| |registered|boolean|false|Registration status| |expired|boolean|false|Key expiration status| |expirationDate|string(date-time)|false|Key expiration date| |endpointsSeenToday|integer|false|Key usage status| |messages|[message]|false|Human readable messages from the system|

Example

{
  "today": "2018-08-28T10:33:37.137110423Z",
  "registered": false,
  "expired": false,
  "expirationDate": "2018-09-27T10:31:32.196658Z",
  "endpointsSeenToday": 2338,
  "messages": [
    {
      "level": 2,
      "body": "Your API key is not activated. Alerts are suppressed until you have activated your account."
    }
  ]
}

message

Properties

|Name|Type|Required|Description| |---|---|---|---|---| |level|integer|false|Message level| |body|string|false|Message text|

Enumerated Values

Property	Value	Description
level	1	1 - INFO
level	2	2 - WARN
level	3	3 - ERROR

Example

{
  "level": 2,
  "body": "Your API key is not activated. Alerts are suppressed until you have activated your account."
}

alerts

Properties

|Name|Type|Required|Description| |---|---|---|---|---| |follow|string|false|Page bookmark. Can be passed to consecutive request to retrieve only new alerts since the last query.| |more|boolean|false|Indicates if there are more alerts to retrieve.| |alerts|[alert]|false|Array of alerts.| |threats|threats|false|Dictionary containing definition of threats.|

Example

{
  "follow": "string",
  "more": true,
  "alerts": [
    {
      "eventType": "string",
      "threats": [
        "c2_communication"
      ],
      "wisdom": {
        "flags": [
          "c2",
          "young_domain"
        ],
        "labels": [
          "c2:TrickBot"
        ],
        "domain": "example.com"
      },
      "event": {
        "ts": "2018-03-01T10:31:59Z",
        "srcIP": "192.168.20.5",
        "srcPort": 32876,
        "srcHost": "john-pc",
        "srcMac": "16:c8:60:26:09:a6",
        "srcUser": "john",
        "srcID": "string",
        "query": "www.example.com",
        "qtype": "A"
      }
    }
  ],
  "threats": {
    "c2_communication": {
      "title": "C2 communication attempt indicating infection",
      "severity": 5
    },
    "cryptomining": {
      "title": "Cryptomining indicating infection or resource abuse",
      "severity": 4
    }
  }
}

alert

Properties

|Name|Type|Required|Description| |---|---|---|---|---| |eventType|string|false|EventType describes type of event object ("dns", "ip", "http", "tls").| |threats|[string]|false|Threats associated with alert.| |wisdom|wisdom|false|Wisdom context of alert.| |event|any|false|One of the *Event schema described in the table below.|

oneOf

|Name|Type|Required|Description| |---|---|---|---|---| |-|dnsEvent|false|DNS query event| |-|ipEvent|false|IP traffic event| |-|httpEvent|false|HTTP request event| |-|tlsEvent|false|TLS event|

Example

{
  "eventType": "string",
  "threats": [
    "c2_communication"
  ],
  "wisdom": {
    "flags": [
      "c2",
      "young_domain"
    ],
    "labels": [
      "c2:TrickBot"
    ],
    "domain": "example.com"
  },
  "event": {
    "ts": "2018-03-01T10:31:59Z",
    "srcIP": "192.168.20.5",
    "srcPort": 32876,
    "srcHost": "john-pc",
    "srcMac": "16:c8:60:26:09:a6",
    "srcUser": "john",
    "srcID": "string",
    "query": "www.example.com",
    "qtype": "A"
  }
}

wisdom

Properties

|Name|Type|Required|Description| |---|---|---|---|---| |flags|[string]|false|none| |labels|[string]|false|none| |domain|string|false|none|

Example

{
  "flags": [
    "c2",
    "young_domain"
  ],
  "labels": [
    "c2:TrickBot"
  ],
  "domain": "example.com"
}

eventHeader

Common properties for each type of event

Properties

|Name|Type|Required|Description| |---|---|---|---|---| |ts|string(date-time)|false|Event timestamp| |srcIP|string(ip)|false|Source IP| |srcPort|integer|false|Source port| |srcHost|string|false|Source host| |srcMac|string|false|Source mac address| |srcUser|string|false|Source user| |srcID|string|false|Source ID|

Example

{
  "ts": "2018-03-01T10:31:59Z",
  "srcIP": "192.168.20.5",
  "srcPort": 32876,
  "srcHost": "john-pc",
  "srcMac": "16:c8:60:26:09:a6",
  "srcUser": "john",
  "srcID": "string"
}

dnsEvent

DNS query event

Properties

allOf

|Name|Type|Required|Description| |---|---|---|---|---| |-|eventHeader|false|Common properties for each type of event|

and

|Name|Type|Required|Description| |---|---|---|---|---| |-|object|false|none| |query|string|false|DNS query| |qtype|string|false|Query type|

Example

{
  "ts": "2018-03-01T10:31:59Z",
  "srcIP": "192.168.20.5",
  "srcPort": 32876,
  "srcHost": "john-pc",
  "srcMac": "16:c8:60:26:09:a6",
  "srcUser": "john",
  "srcID": "string",
  "query": "www.example.com",
  "qtype": "A"
}

ipEvent

IP traffic event

Properties

allOf

|Name|Type|Required|Description| |---|---|---|---|---| |-|eventHeader|false|Common properties for each type of event|

and

|Name|Type|Required|Description| |---|---|---|---|---| |-|object|false|none| |destIP|string(ip)|false|Destination IP| |destPort|integer|false|Destination port| |proto|string|false|Transport layer protocol| |bytesIn|integer(int64)|false|Number of incoming bytes| |bytesOut|integer(int64)|false|Number of outgoing bytes| |app|string|false|Application layer protocol| |action|string|false|Defines if event was allowed or denied| |duration|number(double)|false|Duration of connection|

Example

{
  "ts": "2018-03-01T10:31:59Z",
  "srcIP": "192.168.20.5",
  "srcPort": 32876,
  "srcHost": "john-pc",
  "srcMac": "16:c8:60:26:09:a6",
  "srcUser": "john",
  "srcID": "string",
  "destIP": "8.8.8.8",
  "destPort": 23,
  "proto": "udp",
  "bytesIn": 3911,
  "bytesOut": 2512,
  "app": "ssl",
  "action": "allowed",
  "duration": 7.2
}

httpEvent

HTTP request event

Properties

allOf

|Name|Type|Required|Description| |---|---|---|---|---| |-|eventHeader|false|Common properties for each type of event|

and

|Name|Type|Required|Description| |---|---|---|---|---| |-|object|false|none| |url|string|false|HTTP request URL| |method|string|false|HTTP method| |status|integer(int64)|false|HTTP response status code| |app|string|false|Application layer protocol| |action|string|false|Defines if event was allowed or denied| |bytesIn|integer(int64)|false|Number of incoming bytes| |bytesOut|integer(int64)|false|Number of outgoing bytes| |contentType|string|false|Content type of HTTP event| |referrer|string|false|none| |userAgent|string|false|User Agent used in HTTP event|

Example

{
  "ts": "2018-03-01T10:31:59Z",
  "srcIP": "192.168.20.5",
  "srcPort": 32876,
  "srcHost": "john-pc",
  "srcMac": "16:c8:60:26:09:a6",
  "srcUser": "john",
  "srcID": "string",
  "url": "http://microsoft775.com/wpad.dat",
  "method": "GET",
  "status": 200,
  "app": "http",
  "action": "allowed",
  "bytesIn": 4321,
  "bytesOut": 1234,
  "contentType": "text/html; charset=utf-8",
  "referrer": "someone.com",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36"
}

tlsEvent

TLS event

Properties

allOf

|Name|Type|Required|Description| |---|---|---|---|---| |-|eventHeader|false|Common properties for each type of event|

and

|Name|Type|Required|Description| |---|---|---|---|---| |-|object|false|none| |certHash|string|false|Certificate hash| |issuer|string|false|Certificate issuer| |subject|string|false|Certificate subject| |validFrom|string(date-time)|false|From when certificate is valid| |validTo|string(date-time)|false|Certificate expiration date| |destIP|string(ip)|false|Destination IP| |destPort|integer|false|Destination port| |ja3|string|false|JA3 fingerprint| |ja3s|string|false|JA3S fingerprint|

Example

{
  "ts": "2018-03-01T10:31:59Z",
  "srcIP": "192.168.20.5",
  "srcPort": 32876,
  "srcHost": "john-pc",
  "srcMac": "16:c8:60:26:09:a6",
  "srcUser": "john",
  "srcID": "string",
  "certHash": "9fcc5c1e8ec32f56e975ba43c923dbfa16a8f946",
  "issuer": "C=US; O=DigiCert Inc; OU=www.digicert.com; CN=GeoTrust RSA CA 2018",
  "subject": "C=US,ST=TX,L=Texas,O=lol,OU=,CN=example.com",
  "validFrom": "2021-03-30T00:34:02Z",
  "validTo": "2021-05-29T00:34:02Z",
  "destIP": "188.68.55.50",
  "destPort": 9001,
  "ja3": "724dedf93fb5a3636a0f1ee8fcec8801",
  "ja3s": "015535be754766257f9bfdf3470cd428e0f1cfd4"
}

leaseEvent

DHCP query event

Properties

allOf

|Name|Type|Required|Description| |---|---|---|---|---| |-|eventHeader|false|Common properties for each type of event|

and

|Name|Type|Required|Description| |---|---|---|---|---| |-|object|false|none| |type|string|false|none| |termination|boolean|false|none| |duration|integer(int64)|false|Duration of the event|

Example

{
  "ts": "2018-03-01T10:31:59Z",
  "srcIP": "192.168.20.5",
  "srcPort": 32876,
  "srcHost": "john-pc",
  "srcMac": "16:c8:60:26:09:a6",
  "srcUser": "john",
  "srcID": "string",
  "type": "string",
  "termination": true,
  "duration": 5.4
}

aeThreats

Properties

|Name|Type|Required|Description| |---|---|---|---|---| |threats|threats|false|Dictionary containing definition of threats.|

Example

{
  "threats": {
    "c2_communication": {
      "title": "C2 communication attempt indicating infection",
      "severity": 5
    },
    "cryptomining": {
      "title": "Cryptomining indicating infection or resource abuse",
      "severity": 4
    }
  }
}

threats

Dictionary containing definition of threats.

Properties

|Name|Type|Required|Description| |---|---|---|---|---| |threatID|threat|false|none|

Example

{
  "c2_communication": {
    "title": "C2 communication attempt indicating infection",
    "severity": 5
  },
  "cryptomining": {
    "title": "Cryptomining indicating infection or resource abuse",
    "severity": 4
  }
}

threat

Properties

|Name|Type|Required|Description| |---|---|---|---|---| |title|string|true|Human readable description of the threat| |severity|integer|true|Severity of the threat| |policy|boolean|false|none|

Example

{
  "title": "human readable description",
  "severity": 5,
  "policy": true
}

aeFlags

Properties

|Name|Type|Required|Description| |---|---|---|---|---| |flags|flags|false|Dictionary that contains flags descriptions|

Example

{
  "flags": {
    "c2": {
      "title": "Known C2 callback destination",
      "type": "category"
    },
    "freedns": {
      "title": "Parent domain is a dynamic DNS provider",
      "type": "feature"
    }
  }
}

flags

Dictionary that contains flags descriptions

Properties

|Name|Type|Required|Description| |---|---|---|---|---| |flagID|flag|false|none|

Example

{
  "c2": {
    "title": "Known C2 callback destination",
    "type": "category"
  },
  "freedns": {
    "title": "Parent domain is a dynamic DNS provider",
    "type": "feature"
  }
}

flag

Properties

|Name|Type|Required|Description| |---|---|---|---|---| |title|string|false|Flag description| |type|string|false|Flag type|

Example

{
  "title": "Known blockchain API destination",
  "type": "feature"
}

eventsResponseBody

Properties

|Name|Type|Required|Description| |---|---|---|---|---| |received|integer|false|Number of received events| |accepted|integer|false|Number of accepted events|

Example

{
  "received": 100,
  "accepted": 100
}

errorMessage

Properties

|Name|Type|Required|Description| |---|---|---|---|---| |message|string|false|Error message|

Example

{
  "message": "string"
}