List indicators of compromise

Note: This endpoint is in beta and may be subject to changes. Please check the documentation regularly for updates.

GET https://api.ap1.datadoghq.com/api/v2/security/siem/ioc-explorerhttps://api.ap2.datadoghq.com/api/v2/security/siem/ioc-explorerhttps://api.datadoghq.eu/api/v2/security/siem/ioc-explorerhttps://api.ddog-gov.com/api/v2/security/siem/ioc-explorerhttps://api.us2.ddog-gov.com/api/v2/security/siem/ioc-explorerhttps://api.datadoghq.com/api/v2/security/siem/ioc-explorerhttps://api.us3.datadoghq.com/api/v2/security/siem/ioc-explorerhttps://api.us5.datadoghq.com/api/v2/security/siem/ioc-explorer

Overview

Get a list of indicators of compromise (IoCs) matching the specified filters.

OAuth apps require the security_monitoring_signals_read authorization scope to access this endpoint.

Arguments

Query Strings

Name

Type

Description

limit

integer

Number of results per page.

offset

integer

Pagination offset.

query

string

Search/filter query (supports field:value syntax).

sort[column]

string

Sort column: score, first_seen_ts_epoch, last_seen_ts_epoch, indicator, indicator_type, signal_count, log_count, category, as_type.

sort[order]

string

Sort order: asc or desc.

Response

OK

Response for the list indicators of compromise endpoint.

Expand All

Field

Type

Description

data

object

IoC Explorer list response data object.

attributes

object

Attributes of the IoC Explorer list response.

data

[object]

List of indicators of compromise.

as_geo

object

Geographic location information for an IP indicator.

city

string

City name.

country_code

string

ISO country code.

country_name

string

Full country name.

as_type

string

Autonomous system type.

benign_sources

[object]

Threat intelligence sources that flagged this indicator as benign.

name

string

Name of the threat intelligence source.

categories

[string]

Threat categories associated with the indicator.

first_seen

date-time

Timestamp when the indicator was first seen.

id

string

Unique identifier for the indicator.

indicator

string

The indicator value (for example, an IP address or domain).

indicator_type

string

Type of indicator (for example, IP address or domain).

last_seen

date-time

Timestamp when the indicator was last seen.

log_matches

int64

Number of logs that matched this indicator.

m_as_type

enum

Effect of a scoring factor on the indicator's threat score. Allowed enum values: RAISE_SCORE,LOWER_SCORE,NO_EFFECT

m_persistence

enum

Effect of a scoring factor on the indicator's threat score. Allowed enum values: RAISE_SCORE,LOWER_SCORE,NO_EFFECT

m_signal

enum

Effect of a scoring factor on the indicator's threat score. Allowed enum values: RAISE_SCORE,LOWER_SCORE,NO_EFFECT

m_sources

enum

Effect of a scoring factor on the indicator's threat score. Allowed enum values: RAISE_SCORE,LOWER_SCORE,NO_EFFECT

malicious_sources

[object]

Threat intelligence sources that flagged this indicator as malicious.

name

string

Name of the threat intelligence source.

max_trust_score

enum

Effect of a scoring factor on the indicator's threat score. Allowed enum values: RAISE_SCORE,LOWER_SCORE,NO_EFFECT

score

double

Threat score for the indicator (0-100).

signal_matches

int64

Number of security signals that matched this indicator.

signal_tier

int64

Signal tier level.

suspicious_sources

[object]

Threat intelligence sources that flagged this indicator as suspicious.

name

string

Name of the threat intelligence source.

tags

[string]

Tags associated with the indicator.

metadata

object

Response metadata.

count

int64

Total number of indicators matching the query.

paging

object

Pagination information.

offset

int64

Current pagination offset.

id

string

Unique identifier for the response.

type

string

Response type identifier.

{
  "data": {
    "attributes": {
      "data": [
        {
          "as_geo": {
            "city": "string",
            "country_code": "string",
            "country_name": "string"
          },
          "as_type": "string",
          "benign_sources": [
            {
              "name": "string"
            }
          ],
          "categories": [],
          "first_seen": "2019-09-19T10:00:00.000Z",
          "id": "string",
          "indicator": "string",
          "indicator_type": "string",
          "last_seen": "2019-09-19T10:00:00.000Z",
          "log_matches": "integer",
          "m_as_type": "string",
          "m_persistence": "string",
          "m_signal": "string",
          "m_sources": "string",
          "malicious_sources": [
            {
              "name": "string"
            }
          ],
          "max_trust_score": "string",
          "score": "number",
          "signal_matches": "integer",
          "signal_tier": "integer",
          "suspicious_sources": [
            {
              "name": "string"
            }
          ],
          "tags": []
        }
      ],
      "metadata": {
        "count": "integer"
      },
      "paging": {
        "offset": "integer"
      }
    },
    "id": "string",
    "type": "string"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Authorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/security/siem/ioc-explorer" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
"""
List indicators of compromise returns "OK" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.security_monitoring_api import SecurityMonitoringApi

configuration = Configuration()
configuration.unstable_operations["list_indicators_of_compromise"] = True
with ApiClient(configuration) as api_client:
    api_instance = SecurityMonitoringApi(api_client)
    response = api_instance.list_indicators_of_compromise(
        limit=1,
    )

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
# List indicators of compromise returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.unstable_operations["v2.list_indicators_of_compromise".to_sym] = true
end
api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
opts = {
  limit: 1,
}
p api_instance.list_indicators_of_compromise(opts)

Instructions

First install the library and its dependencies and then save the example to example.rb and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
// List indicators of compromise returns "OK" response

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
)

func main() {
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	configuration.SetUnstableOperationEnabled("v2.ListIndicatorsOfCompromise", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewSecurityMonitoringApi(apiClient)
	resp, r, err := api.ListIndicatorsOfCompromise(ctx, *datadogV2.NewListIndicatorsOfCompromiseOptionalParameters().WithLimit(1))

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `SecurityMonitoringApi.ListIndicatorsOfCompromise`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `SecurityMonitoringApi.ListIndicatorsOfCompromise`:\n%s\n", responseContent)
}

Instructions

First install the library and its dependencies and then save the example to main.go and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
// List indicators of compromise returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.SecurityMonitoringApi;
import com.datadog.api.client.v2.api.SecurityMonitoringApi.ListIndicatorsOfCompromiseOptionalParameters;
import com.datadog.api.client.v2.model.IoCExplorerListResponse;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    defaultClient.setUnstableOperationEnabled("v2.listIndicatorsOfCompromise", true);
    SecurityMonitoringApi apiInstance = new SecurityMonitoringApi(defaultClient);

    try {
      IoCExplorerListResponse result =
          apiInstance.listIndicatorsOfCompromise(
              new ListIndicatorsOfCompromiseOptionalParameters().limit(1));
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling SecurityMonitoringApi#listIndicatorsOfCompromise");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Instructions

First install the library and its dependencies and then save the example to Example.java and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
// List indicators of compromise returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_security_monitoring::ListIndicatorsOfCompromiseOptionalParams;
use datadog_api_client::datadogV2::api_security_monitoring::SecurityMonitoringAPI;

#[tokio::main]
async fn main() {
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.ListIndicatorsOfCompromise", true);
    let api = SecurityMonitoringAPI::with_config(configuration);
    let resp = api
        .list_indicators_of_compromise(ListIndicatorsOfCompromiseOptionalParams::default().limit(1))
        .await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

Instructions

First install the library and its dependencies and then save the example to src/main.rs and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
/**
 * List indicators of compromise returns "OK" response
 */

import { client, v2 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
configuration.unstableOperations["v2.listIndicatorsOfCompromise"] = true;
const apiInstance = new v2.SecurityMonitoringApi(configuration);

const params: v2.SecurityMonitoringApiListIndicatorsOfCompromiseRequest = {
  limit: 1,
};

apiInstance
  .listIndicatorsOfCompromise(params)
  .then((data: v2.IoCExplorerListResponse) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));

Instructions

First install the library and its dependencies and then save the example to example.ts and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"