Skip to main content

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​

StatusMeaningDescriptionSchema
200OKOK-
400Bad RequestBad RequesterrorMessage
401UnauthorizedBad RequesterrorMessage
403ForbiddenForbiddenerrorMessage
429Too Many RequestsToo Many RequestserrorMessage

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​

StatusMeaningDescriptionSchema
200OKOKaccountStatus

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."
    }
  ]
}

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​

NameInTypeRequiredDescription
followquerystringfalsePage bookmark as provided by one of the previous responses. Only new alerts since the bookmark will be returned.

Responses​

StatusMeaningDescriptionSchema
200OKOKalerts

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
    }
  }
}

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​

NameInTypeRequiredDescription
Content-EncodingheaderstringfalseSets compression
bodybodydnsEventfalsenone

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​

StatusMeaningDescriptionSchema
200OKOKeventsResponseBody

Example 200 response​

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

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​

NameInTypeRequiredDescription
Content-EncodingheaderstringfalseSets compression
bodybodyipEventfalsenone

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​

StatusMeaningDescriptionSchema
200OKOKeventsResponseBody

Example 200 response​

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

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​

NameInTypeRequiredDescription
Content-EncodingheaderstringfalseSets compression
bodybodytlsEventfalsenone

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​

StatusMeaningDescriptionSchema
200OKOKeventsResponseBody

Example 200 response​

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

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​

NameInTypeRequiredDescription
Content-EncodingheaderstringfalseSets compression
bodybodyhttpEventfalsenone

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​

StatusMeaningDescriptionSchema
200OKOKeventsResponseBody

Example 200 response​

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

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​

NameInTypeRequiredDescription
Content-EncodingheaderstringfalseSets compression
bodybodyleaseEventfalsenone

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​

StatusMeaningDescriptionSchema
200OKOKeventsResponseBody

Example 200 response​

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

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​

StatusMeaningDescriptionSchema
200OKOKaeThreats

Example 200 response​

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

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​

StatusMeaningDescriptionSchema
200OKOKaeFlags

Example 200 response​

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

Code samples​

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

Schemas​

accountStatus​

Properties​

NameTypeRequiredDescription
todaystring(date-time)falseToday's date
registeredbooleanfalseRegistration status
expiredbooleanfalseKey expiration status
expirationDatestring(date-time)falseKey expiration date
endpointsSeenTodayintegerfalseKey usage status
messages[message]falseHuman 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​

NameTypeRequiredDescription
levelintegerfalseMessage level
bodystringfalseMessage text

Enumerated Values​

PropertyValueDescription
level11 - INFO
level22 - WARN
level33 - ERROR

Example​

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

alerts​

Properties​

NameTypeRequiredDescription
followstringfalsePage bookmark. Can be passed to consecutive request to retrieve only new alerts since the last query.
morebooleanfalseIndicates if there are more alerts to retrieve.
alerts[alert]falseArray of alerts.
threatsthreatsfalseDictionary 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​

NameTypeRequiredDescription
eventTypestringfalseEventType describes type of event object ("dns", "ip", "http", "tls").
threats[string]falseThreats associated with alert.
wisdomwisdomfalseWisdom context of alert.
eventanyfalseOne of the *Event schema described in the table below.

oneOf

NameTypeRequiredDescription
-dnsEventfalseDNS query event
-ipEventfalseIP traffic event
-httpEventfalseHTTP request event
-tlsEventfalseTLS 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​

NameTypeRequiredDescription
flags[string]falsenone
labels[string]falsenone
domainstringfalsenone

Example​

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

eventHeader​

Common properties for each type of event

Properties​

NameTypeRequiredDescription
tsstring(date-time)falseEvent timestamp
srcIPstring(ip)falseSource IP
srcPortintegerfalseSource port
srcHoststringfalseSource host
srcMacstringfalseSource mac address
srcUserstringfalseSource user
srcIDstringfalseSource 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

NameTypeRequiredDescription
-eventHeaderfalseCommon properties for each type of event

and

NameTypeRequiredDescription
-objectfalsenone
querystringfalseDNS query
qtypestringfalseQuery 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

NameTypeRequiredDescription
-eventHeaderfalseCommon properties for each type of event

and

NameTypeRequiredDescription
-objectfalsenone
destIPstring(ip)falseDestination IP
destPortintegerfalseDestination port
protostringfalseTransport layer protocol
bytesIninteger(int64)falseNumber of incoming bytes
bytesOutinteger(int64)falseNumber of outgoing bytes
appstringfalseApplication layer protocol
actionstringfalseDefines if event was allowed or denied
durationnumber(double)falseDuration 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

NameTypeRequiredDescription
-eventHeaderfalseCommon properties for each type of event

and

NameTypeRequiredDescription
-objectfalsenone
urlstringfalseHTTP request URL
methodstringfalseHTTP method
statusinteger(int64)falseHTTP response status code
appstringfalseApplication layer protocol
actionstringfalseDefines if event was allowed or denied
bytesIninteger(int64)falseNumber of incoming bytes
bytesOutinteger(int64)falseNumber of outgoing bytes
contentTypestringfalseContent type of HTTP event
referrerstringfalsenone
userAgentstringfalseUser 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

NameTypeRequiredDescription
-eventHeaderfalseCommon properties for each type of event

and

NameTypeRequiredDescription
-objectfalsenone
certHashstringfalseCertificate hash
issuerstringfalseCertificate issuer
subjectstringfalseCertificate subject
validFromstring(date-time)falseFrom when certificate is valid
validTostring(date-time)falseCertificate expiration date
destIPstring(ip)falseDestination IP
destPortintegerfalseDestination port
ja3stringfalseJA3 fingerprint
ja3sstringfalseJA3S 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

NameTypeRequiredDescription
-eventHeaderfalseCommon properties for each type of event

and

NameTypeRequiredDescription
-objectfalsenone
typestringfalsenone
terminationbooleanfalsenone
durationinteger(int64)falseDuration 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​

NameTypeRequiredDescription
threatsthreatsfalseDictionary 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​

NameTypeRequiredDescription
threatIDthreatfalsenone

Example​

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

threat​

Properties​

NameTypeRequiredDescription
titlestringtrueHuman readable description of the threat
severityintegertrueSeverity of the threat
policybooleanfalsenone

Example​

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

aeFlags​

Properties​

NameTypeRequiredDescription
flagsflagsfalseDictionary 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​

NameTypeRequiredDescription
flagIDflagfalsenone

Example​

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

flag​

Properties​

NameTypeRequiredDescription
titlestringfalseFlag description
typestringfalseFlag type

Example​

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

eventsResponseBody​

Properties​

NameTypeRequiredDescription
receivedintegerfalseNumber of received events
acceptedintegerfalseNumber of accepted events

Example​

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

errorMessage​

Properties​

NameTypeRequiredDescription
messagestringfalseError message

Example​

{
  "message": "string"
}