Get BIOCs

post /public_api/v1/bioc/get

Return a list of BIOCs. You can return all BIOCs or filter results. You can also return extended results with all details included.- The response is concatenated using AND condition (OR is not supported).

The maximum result set size is >100.
Offset is the zero-based number of incidents from the start of the result set.

You must have Rules Edit permissions to run this endpoint.

Request headers

Authorization String required

{api_key}

Example: authorization_example

x-xdr-auth-id String required

{api_key_id}

Example: xXdrAuthId_example

CLIENT REQUEST

          curl -X 'POST'

        -H
        'Accept: application/json'
      
        -H
        'Content-Type: application/json'
      
          -H
          'Authorization: authorization_example'
          -H
          'x-xdr-auth-id: xXdrAuthId_example'
      
      'https://api-yourfqdn/public_api/v1/bioc/get'
    
      -d
      ''

import http.client

conn = http.client.HTTPSConnection("api-yourfqdn")

payload = "{\"request_data\":{\"extended_view\":true,\"filters\":[{\"field\":\"name\",\"operator\":\"EQ\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0}}"

headers = {
    'Authorization': "SOME_STRING_VALUE",
    'x-xdr-auth-id': "SOME_STRING_VALUE",
    'content-type': "application/json"
    }

conn.request("POST", "/public_api/v1/bioc/get", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api-yourfqdn/public_api/v1/bioc/get")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'SOME_STRING_VALUE'
request["x-xdr-auth-id"] = 'SOME_STRING_VALUE'
request["content-type"] = 'application/json'
request.body = "{\"request_data\":{\"extended_view\":true,\"filters\":[{\"field\":\"name\",\"operator\":\"EQ\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0}}"

response = http.request(request)
puts response.read_body

const data = JSON.stringify({
  "request_data": {
    "extended_view": true,
    "filters": [
      {
        "field": "name",
        "operator": "EQ",
        "value": "string"
      }
    ],
    "search_from": 0,
    "search_to": 0
  }
});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-yourfqdn/public_api/v1/bioc/get");
xhr.setRequestHeader("Authorization", "SOME_STRING_VALUE");
xhr.setRequestHeader("x-xdr-auth-id", "SOME_STRING_VALUE");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

HttpResponse<String> response = Unirest.post("https://api-yourfqdn/public_api/v1/bioc/get")
  .header("Authorization", "SOME_STRING_VALUE")
  .header("x-xdr-auth-id", "SOME_STRING_VALUE")
  .header("content-type", "application/json")
  .body("{\"request_data\":{\"extended_view\":true,\"filters\":[{\"field\":\"name\",\"operator\":\"EQ\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0}}")
  .asString();

import Foundation

let headers = [
  "Authorization": "SOME_STRING_VALUE",
  "x-xdr-auth-id": "SOME_STRING_VALUE",
  "content-type": "application/json"
]
let parameters = ["request_data": [
    "extended_view": true,
    "filters": [
      [
        "field": "name",
        "operator": "EQ",
        "value": "string"
      ]
    ],
    "search_from": 0,
    "search_to": 0
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-yourfqdn/public_api/v1/bioc/get")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-yourfqdn/public_api/v1/bioc/get",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"request_data\":{\"extended_view\":true,\"filters\":[{\"field\":\"name\",\"operator\":\"EQ\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0}}",
  CURLOPT_HTTPHEADER => [
    "Authorization: SOME_STRING_VALUE",
    "content-type: application/json",
    "x-xdr-auth-id: SOME_STRING_VALUE"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api-yourfqdn/public_api/v1/bioc/get");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "x-xdr-auth-id: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "content-type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\"request_data\":{\"extended_view\":true,\"filters\":[{\"field\":\"name\",\"operator\":\"EQ\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0}}");

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://api-yourfqdn/public_api/v1/bioc/get");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "SOME_STRING_VALUE");
request.AddHeader("x-xdr-auth-id", "SOME_STRING_VALUE");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"request_data\":{\"extended_view\":true,\"filters\":[{\"field\":\"name\",\"operator\":\"EQ\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Body parameters

application/json

request_dataobjectrequired

extended_viewboolean

filtersarray

An array of filter fields.

[

fieldobject (Enum)

Identifies the BIOC field the filter is matching. Filters are based on the following keywords:

name: BIOC name.
severity: BIOC severity level.
type: BIOC type.
is_xql: Whether or not the BIOC is XQL.
comment: Comment.
status: BIOC status.
indicator: Indicator.
mitre_technique_id_and_name: MITRE technique ID and name.
mitre_tactic_id_and_name: MITRE tactic ID and name.

Allowed values:"name""severity""type""is_xql""comment""status""indicator""mitre_technique_id_and_name""mitre_tactic_id_and_name"

operatorobject (Enum)

Identifies the comparison operator you want to use for this filter. Valid keywords are: EQ / NEQ

name: String
severity: String
type: String
is_xql: Boolean
comment: String
status: String
indicator: String IN
mitre_technique_id_and_name: List of strings
mitre_tactic_id_and_name: List of strings

Allowed values:"EQ""NEQ""IN""GTE""LTE"

valueobject

Value that this filter must match. The contents of this field will differ depending on the IOC field that you specified for this filter:

name, comment: String.
severity: String, can be one of the following: SEV_010_INFO, SEV_020_LOW, SEV_030_MEDIUM, SEV_040_HIGH
type: String, can be one of the following: other, persistence, evasion, tampering, file_type_obfuscation, privilege_escalation, credential_access, lateral_movement, execution, collection, exfiltration, infiltration, dropper, file_privilege_manipulation, reconnaissance, discovery.
is_xql: Boolean: true or false.
status: String, can be one of the following: enabled, disabled.
indicator: String or dictionary in the format you wrote it.
mitre_technique_id_and_name: List of strings.
mitre_tactic_id_and_name: List of strings.

One of

string

Value that this filter must match. The contents of this field will differ depending on the IOC field that you specified for this filter:

name, comment: String.
severity: String, can be one of the following: SEV_010_INFO, SEV_020_LOW, SEV_030_MEDIUM, SEV_040_HIGH
type: String, can be one of the following: other, persistence, evasion, tampering, file_type_obfuscation, privilege_escalation, credential_access, lateral_movement, execution, collection, exfiltration, infiltration, dropper, file_privilege_manipulation, reconnaissance, discovery.
is_xql: Boolean: true or false.
status: String, can be one of the following: enabled, disabled.
indicator: String or dictionary in the format you wrote it.
mitre_technique_id_and_name: List of strings.
mitre_tactic_id_and_name: List of strings.

Array

boolean

Value that this filter must match. The contents of this field will differ depending on the IOC field that you specified for this filter:

name, comment: String.
severity: String, can be one of the following: SEV_010_INFO, SEV_020_LOW, SEV_030_MEDIUM, SEV_040_HIGH
type: String, can be one of the following: other, persistence, evasion, tampering, file_type_obfuscation, privilege_escalation, credential_access, lateral_movement, execution, collection, exfiltration, infiltration, dropper, file_privilege_manipulation, reconnaissance, discovery.
is_xql: Boolean: true or false.
status: String, can be one of the following: enabled, disabled.
indicator: String or dictionary in the format you wrote it.
mitre_technique_id_and_name: List of strings.
mitre_tactic_id_and_name: List of strings.

]

search_frominteger

Integer representing the starting offset within the query result set from which you want BIOCs returned. BIOCs are returned as a zero-based list. Any BIOC indexed less than this value is not returned in the final result set and defaults to zero.

search_tointeger

Integer representing the end offset within the result set after which you do not want BIOCs returned. BIOCs in the BIOC list that are indexed higher than this value are not returned in the final results set. Defaults to >100, which returns all BIOCs to the end of the list.

REQUESTExample 1
{
  "request_data": {
    "extended_view": false
  }
}

Responses

Body

application/json

objects_countinteger

objectsarray

[

rule_idinteger

namestring

typestring

severitystring

commentstring

statusstring

is_xqlboolean

indicatorobject

runOnCGOboolean

investigationTypestring

investigationobject

PROCESS_EXECUTION_EVENTobject

filterobject

ANDarray

[

SEARCH_FIELDstring

SEARCH_TYPEstring

SEARCH_VALUEstring

EXTRA_FIELDSarray

[

]

isExtendedboolean

]

mitre_tactic_id_and_namearray[string]

mitre_technique_id_and_namearray[string]

]

objects_typestring

RESPONSEExample 1
{
  "objects_count": 2,
  "objects": [
    {
      "rule_id": 376,
      "name": "TestDataSourceTags",
      "type": "OTHER",
      "severity": "SEV_030_MEDIUM",
      "comment": "",
      "status": "DISABLED",
      "is_xql": false,
      "indicator": {
        "runOnCGO": true,
        "investigationType": "PROCESS_EXECUTION_EVENT",
        "investigation": {
          "PROCESS_EXECUTION_EVENT": {
            "filter": {
              "AND": [
                {
                  "SEARCH_FIELD": "action_process_username",
                  "SEARCH_TYPE": "EQ",
                  "SEARCH_VALUE": "guyk",
                  "EXTRA_FIELDS": [],
                  "isExtended": false
                }
              ]
            }
          }
        }
      },
      "mitre_tactic_id_and_name": [],
      "mitre_technique_id_and_name": []
    },
    {
      "rule_id": 421,
      "name": "new_bioc_test",
      "type": "EXECUTION",
      "severity": "SEV_020_LOW",
      "comment": "",
      "status": "ENABLED",
      "is_xql": true,
      "indicator": "dataset = xdr_data | filter event_type = 1 and actor_process_image_name = \"SDFDSGFHFN\"",
      "mitre_tactic_id_and_name": [
        "12 - Tactic",
        "45 - Another Tactic"
      ],
      "mitre_technique_id_and_name": [
        "123 - Test",
        "12 - Another Test"
      ]
    }
  ],
  "objects_type": "bioc"
}

Bad Request. Got invalid JSON.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Unauthorized access. User does not have the required license type to run this API.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Internal server error. A unified status for API communication type errors.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}