Skip to main content

REST API 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'

Detection management​

POST /v1/detections​

Handles the upload of Sigma detection rules via a zip archive. The import_mode query parameter controls how rules are processed: merge adds new rules and updates existing ones, while replace removes all existing customer-provided Sigma rules before adding the new ones. The zip archive must contain Sigma rule files with .yaml or .yml extensions. The following limits apply:

  • Maximum number of files in archive: 1000
  • Maximum size of a single rule file: 100KB
  • Maximum total decompressed size of all rules: 10MB

Parameters

NameInTypeRequiredDescription
import_modequerystringfalseSpecifies the import mode. merge adds new rules and updates existing ones. replace replaces all existing customer-provided Sigma rules.
dry_runquerybooleanfalseSpecifies if the request will be run in dry run mode. If true, the request will be validated, but no changes will be persisted.
bodybodybinarytrueA zip archive containing Sigma rule files (.yaml or .yml).

Enumerated Values​

ParameterValue
import_modemerge (default)
import_modereplace
dry_runfalse (default)
dry_runtrue

Responses

StatusMeaningDescriptionSchema
200OKSigma rules processed successfully.detectionsUpload
400Bad RequestThe request was malformed or contained invalid detection files. The response body will contain details about the errors.detectionsBadRequest
401UnauthorizedUnauthorizederrorMessage
403ForbiddenForbiddenerrorMessage
415Unsupported Media TypeUnsupported Media TypeerrorMessage
429Too Many RequestsToo Many RequestserrorMessage

Example 200 response​

{
  "accepted": 10
}

Example 400 response​

{
  "message": "One or more detection files failed.",
  "validationResult": {
    "valid": 5,
    "invalid": 2,
    "errors": [
      {
        "fileName": "malformed_rule.yml",
        "error": "invalid Sigma rule: missing required field 'detection'"
      }
    ]
  }
}

Code samples

curl -X POST -u "<your-api-key>:"  https://api.alphasoc.net/v1/detections \
  -H 'Content-Type: application/zip' \
  -H 'Accept: application/json' \
  --data-binary @./path/to/rules.zip

Retrieving Findings​

GET /v1/findings​

This endpoint allows for fetching findings generated from logs submitted to the AlphaSOC Analytics Engine (via API or other sources). Each finding includes detections along with the associated resources and context. It might also include sampled log entries that triggered the detection.

Threat details can be accessed via additional threats dictionary, 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 findings already retrieved. The full and most recent threat dictionary is also available using (inventory endpoints)[#inventory].

The API uses stream pagination to limit the size of individual responses and allow reading stream of data in continuous manner. Each response includes a follow bookmark, which should be passed as a parameter in subsequent requests to retrieve only new results. When the last page is reached, the more property in the response is set to false.

Usually the flow for retrieving findings looks like this:

  1. Fetch new findings via /v1/findings?schema=ocsf&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].

It is also possible to use ndjson format for findings. In such case, the stream pagination values are returned in x-stream-more and x-stream-follow headers.

Parameters

NameInTypeRequiredDescription
followquerystringfalseBookmark provided by one of the previous responses. Only new findings since the bookmark will be returned.
schemaquerystringfalseReturned schema of the findings. Currently only ocsf value is supported.
maxAgequerystringfalseSpecifies maximum age of alerts to return.
AcceptheaderstringfalseSpecifies the format of the response. Defaults to application/json.

Detailed descriptions​

schema: Returned schema of the findings. Currently only ocsf value is supported.

maxAge: Specifies maximum age of alerts to return. Value can be represented in seconds (s), minutes (m), hours (h) or days (d) up to 30d. Defaults to 3 days.

Accept: Specifies the format of the response. Defaults to application/json.

Enumerated Values​

ParameterValue
schemaocsf
Acceptapplication/json
Acceptapplication/x-ndjson

Responses

StatusMeaningDescriptionSchema
200OKOKfindings

Example 200 response​

{
  "follow": "string",
  "more": true,
  "records": [
    {
      "category_name": "Findings",
      "category_uid": 2,
      "class_name": "DetectionFinding",
      "class_uid": 2004,
      "type_name": "DetectionFinding: Create",
      "type_uid": 200401,
      "count": 4,
      "time": 1725679437,
      "time_dt": "2024-09-07T03:23:57Z",
      "enrichments": [
        {
          "data": {
            "aggregation": {
              "key": {
                "workspaceID": "9269f7ee-115c-46da-8445-62ebff28217e",
                "srcIP": "192.168.40.17",
                "detections": [
                  {
                    "id": "c2",
                    "key": "LokiBot",
                    "severity": 5,
                    "observations": [],
                    "mitreAttack": [],
                    "threat": "c2_communication"
                  }
...

Response Headers​

StatusHeaderTypeFormatDescription
200X-Stream-FollowstringFollow bookmark to be used in subsequent requests
200X-Stream-MorebooleanIndicator whether there are more findings to retrieve

Code samples

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

Retrieving Alerts​

GET /v1/alerts​

Deprecated: it is recomended to use /v1/findings instead.

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

The API uses pagination to limit the size of individual responses. Each response includes a follow bookmark, which should be passed as a parameter in subsequent requests to retrieve only new results. When the last page is reached, the 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.
maxAgequerystringfalseSpecifies maximum age of alerts to return.

Detailed descriptions​

maxAge: Specifies maximum age of alerts to return. Value can be represented in seconds (s), minutes (m) or hours (h) up to 720h (30 days).

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

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,
  "packetsIn": 11,
  "packetsOut": 7,
  "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,"packetsIn":11,"packetsOut":7,"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,"packetsIn":11,"packetsOut":7,"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"
      }
...

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

findings​

Properties​

NameTypeRequiredDescription
followstringfalsePage bookmark. Can be passed to consecutive request to retrieve only new findings since the last query.
morebooleanfalseIndicates if there are more findings to retrieve.
records[finding]false[OCSF v1.2.0 Detection Finding. For more information about the schema see OCSF specification.]

Example​

{
  "follow": "string",
  "more": true,
  "records": [
    {
      "category_name": "Findings",
      "category_uid": 2,
      "class_name": "DetectionFinding",
      "class_uid": 2004,
      "type_name": "DetectionFinding: Create",
      "type_uid": 200401,
      "count": 4,
      "time": 1725679437,
      "time_dt": "2024-09-07T03:23:57Z",
      "enrichments": [
        {
          "data": {
            "aggregation": {
              "key": {
                "workspaceID": "9269f7ee-115c-46da-8445-62ebff28217e",
                "srcIP": "192.168.40.17",
                "detections": [
                  {
                    "id": "c2",
                    "key": "LokiBot",
                    "severity": 5,
                    "observations": [],
                    "mitreAttack": [],
                    "threat": "c2_communication"
                  }
...

finding​

OCSF v1.2.0 Detection Finding. For more information about the schema see OCSF specification.

Example​

{
  "category_name": "Findings",
  "category_uid": 2,
  "class_name": "DetectionFinding",
  "class_uid": 2004,
  "type_name": "DetectionFinding: Create",
  "type_uid": 200401,
  "count": 4,
  "time": 1725679437,
  "time_dt": "2024-09-07T03:23:57Z",
  "enrichments": [
    {
      "data": {
        "aggregation": {
          "key": {
            "workspaceID": "9269f7ee-115c-46da-8445-62ebff28217e",
            "srcIP": "192.168.40.17",
            "detections": [
              {
                "id": "c2",
                "key": "LokiBot",
                "severity": 5,
                "observations": [
                  "bad"
                ],
                "mitreAttack": [
                  "TA0011:T1071"
                ],
                "threat": "c2_communication"
              }
...

detectionsUpload​

Properties​

NameTypeRequiredDescription
acceptedintegerfalseNumber of Sigma rules that were successfully processed and accepted.

Example​

{
  "accepted": 10
}

detectionsBadRequest​

Properties​

NameTypeRequiredDescription
messagestringfalseMessage text
validationResultobjectfalseDetailed validation results when validation errors occur
validintegerfalseNumber of detections that passed validation and were stored
invalidintegerfalseNumber of detections that failed validation or storage
errors[object]falseDetailed validation errors for each invalid rule
»fileNamestringfalseName of the Sigma rule file that caused the error
»errorstringfalseError message describing the issue

Example​

{
  "message": "One or more detection files failed.",
  "validationResult": {
    "valid": 5,
    "invalid": 2,
    "errors": [
      {
        "fileName": "malformed_rule.yml",
        "error": "invalid Sigma rule: missing required field 'detection'"
      }
    ]
  }
}

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

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

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
packetsIninteger(int64)falseNumber of incoming packets
packetsOutinteger(int64)falseNumber of outgoing packets
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,
  "packetsIn": 11,
  "packetsOut": 7,
  "app": "ssl",
  "action": "allowed",
  "duration": 7.2
}

httpEvent​

HTTP request event

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

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

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