Get a list of security signals

POST https://api.ap1.datadoghq.com/api/v2/security_monitoring/signals/searchhttps://api.ap2.datadoghq.com/api/v2/security_monitoring/signals/searchhttps://api.datadoghq.eu/api/v2/security_monitoring/signals/searchhttps://api.ddog-gov.com/api/v2/security_monitoring/signals/searchhttps://api.us2.ddog-gov.com/api/v2/security_monitoring/signals/searchhttps://api.datadoghq.com/api/v2/security_monitoring/signals/searchhttps://api.us3.datadoghq.com/api/v2/security_monitoring/signals/searchhttps://api.us5.datadoghq.com/api/v2/security_monitoring/signals/search

Overview

Returns security signals that match a search query. Both this endpoint and the GET endpoint can be used interchangeably for listing security signals. This endpoint requires the security_monitoring_signals_read permission.

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

Request

Body Data

Expand All

Field

Type

Description

filter

object

Search filters for listing security signals.

from

date-time

The minimum timestamp for requested security signals.

query

string

Search query for listing security signals.

to

date-time

The maximum timestamp for requested security signals.

page

object

The paging attributes for listing security signals.

cursor

string

A list of results using the cursor provided in the previous query.

limit

int32

The maximum number of security signals in the response.

default: 10

sort

enum

The sort parameters used for querying security signals. Allowed enum values: timestamp,-timestamp

{
  "filter": {
    "from": "2021-11-11T10:56:11+00:00",
    "query": "security:attack status:high",
    "to": "2021-11-11T11:11:11+00:00"
  },
  "page": {
    "limit": 2
  },
  "sort": "timestamp"
}

Response

OK

The response object with all security signals matching the request and pagination information.

Expand All

Field

Type

Description

data

[object]

An array of security signals matching the request.

attributes

object

The object containing all signal attributes and their associated values.

custom

object

A JSON object of attributes in the security signal.

message

string

The message in the security signal defined by the rule that generated the signal.

tags

[string]

An array of tags associated with the security signal.

timestamp

date-time

The timestamp of the security signal.

id

string

The unique ID of the security signal.

type

enum

The type of event. Allowed enum values: signal

default: signal

links

object

Links attributes.

next

string

The link for the next set of results. Note: The request can also be made using the POST endpoint.

meta

object

Meta attributes.

page

object

Paging attributes.

after

string

The cursor used to get the next results, if any. To make the next request, use the same parameters with the addition of the page[cursor].

{
  "data": [
    {
      "attributes": {
        "custom": {
          "workflow": {
            "first_seen": "2020-06-23T14:46:01.000Z",
            "last_seen": "2020-06-23T14:46:49.000Z",
            "rule": {
              "id": "0f5-e0c-805",
              "name": "Brute Force Attack Grouped By User",
              "version": 12
            }
          }
        },
        "message": "Detect Account Take Over (ATO) through brute force attempts",
        "tags": [
          "security:attack",
          "technique:T1110-brute-force"
        ],
        "timestamp": "2019-01-02T09:42:36.320Z"
      },
      "id": "AAAAAWgN8Xwgr1vKDQAAAABBV2dOOFh3ZzZobm1mWXJFYTR0OA",
      "type": "signal"
    }
  ],
  "links": {
    "next": "https://app.datadoghq.com/api/v2/security_monitoring/signals?filter[query]=foo\u0026page[cursor]=eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ=="
  },
  "meta": {
    "page": {
      "after": "eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ=="
    }
  }
}

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

                          ## default
# 

# Curl command
curl -X POST "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_monitoring/signals/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "filter": { "from": "2019-01-02T09:42:36.320Z", "query": "security:attack status:high", "to": "2019-01-03T09:42:36.320Z" }, "page": { "cursor": "eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ==", "limit": 25 }, "sort": "timestamp" } EOF
// Get a list of security signals returns "OK" response with pagination

package main

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

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

func main() {
	body := datadogV2.SecurityMonitoringSignalListRequest{
		Filter: &datadogV2.SecurityMonitoringSignalListRequestFilter{
			From:  datadog.PtrTime(time.Now().Add(time.Minute * -15)),
			Query: datadog.PtrString("security:attack status:high"),
			To:    datadog.PtrTime(time.Now()),
		},
		Page: &datadogV2.SecurityMonitoringSignalListRequestPage{
			Limit: datadog.PtrInt32(2),
		},
		Sort: datadogV2.SECURITYMONITORINGSIGNALSSORT_TIMESTAMP_ASCENDING.Ptr(),
	}
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewSecurityMonitoringApi(apiClient)
	resp, _ := api.SearchSecurityMonitoringSignalsWithPagination(ctx, *datadogV2.NewSearchSecurityMonitoringSignalsOptionalParameters().WithBody(body))

	for paginationResult := range resp {
		if paginationResult.Error != nil {
			fmt.Fprintf(os.Stderr, "Error when calling `SecurityMonitoringApi.SearchSecurityMonitoringSignals`: %v\n", paginationResult.Error)
		}
		responseContent, _ := json.MarshalIndent(paginationResult.Item, "", "  ")
		fmt.Fprintf(os.Stdout, "%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"
// Get a list of security signals returns "OK" response with pagination
import com.datadog.api.client.ApiClient;
import com.datadog.api.client.PaginationIterable;
import com.datadog.api.client.v2.api.SecurityMonitoringApi;
import com.datadog.api.client.v2.api.SecurityMonitoringApi.SearchSecurityMonitoringSignalsOptionalParameters;
import com.datadog.api.client.v2.model.SecurityMonitoringSignal;
import com.datadog.api.client.v2.model.SecurityMonitoringSignalListRequest;
import com.datadog.api.client.v2.model.SecurityMonitoringSignalListRequestFilter;
import com.datadog.api.client.v2.model.SecurityMonitoringSignalListRequestPage;
import com.datadog.api.client.v2.model.SecurityMonitoringSignalsSort;
import java.time.OffsetDateTime;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    SecurityMonitoringApi apiInstance = new SecurityMonitoringApi(defaultClient);

    SecurityMonitoringSignalListRequest body =
        new SecurityMonitoringSignalListRequest()
            .filter(
                new SecurityMonitoringSignalListRequestFilter()
                    .from(OffsetDateTime.now().plusMinutes(-15))
                    .query("security:attack status:high")
                    .to(OffsetDateTime.now()))
            .page(new SecurityMonitoringSignalListRequestPage().limit(2))
            .sort(SecurityMonitoringSignalsSort.TIMESTAMP_ASCENDING);

    try {
      PaginationIterable<SecurityMonitoringSignal> iterable =
          apiInstance.searchSecurityMonitoringSignalsWithPagination(
              new SearchSecurityMonitoringSignalsOptionalParameters().body(body));

      for (SecurityMonitoringSignal item : iterable) {
        System.out.println(item);
      }
    } catch (RuntimeException e) {
      System.err.println(
          "Exception when calling"
              + " SecurityMonitoringApi#searchSecurityMonitoringSignalsWithPagination");
      System.err.println("Reason: " + e.getMessage());
      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"
"""
Get a list of security signals returns "OK" response with pagination
"""

from datetime import datetime
from dateutil.relativedelta import relativedelta
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.security_monitoring_api import SecurityMonitoringApi
from datadog_api_client.v2.model.security_monitoring_signal_list_request import SecurityMonitoringSignalListRequest
from datadog_api_client.v2.model.security_monitoring_signal_list_request_filter import (
    SecurityMonitoringSignalListRequestFilter,
)
from datadog_api_client.v2.model.security_monitoring_signal_list_request_page import (
    SecurityMonitoringSignalListRequestPage,
)
from datadog_api_client.v2.model.security_monitoring_signals_sort import SecurityMonitoringSignalsSort

body = SecurityMonitoringSignalListRequest(
    filter=SecurityMonitoringSignalListRequestFilter(
        _from=(datetime.now() + relativedelta(minutes=-15)),
        query="security:attack status:high",
        to=datetime.now(),
    ),
    page=SecurityMonitoringSignalListRequestPage(
        limit=2,
    ),
    sort=SecurityMonitoringSignalsSort.TIMESTAMP_ASCENDING,
)

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = SecurityMonitoringApi(api_client)
    items = api_instance.search_security_monitoring_signals_with_pagination(body=body)
    for item in items:
        print(item)

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"
# Get a list of security signals returns "OK" response with pagination

require "datadog_api_client"
api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new

body = DatadogAPIClient::V2::SecurityMonitoringSignalListRequest.new({
  filter: DatadogAPIClient::V2::SecurityMonitoringSignalListRequestFilter.new({
    from: (Time.now + -15 * 60),
    query: "security:attack status:high",
    to: Time.now,
  }),
  page: DatadogAPIClient::V2::SecurityMonitoringSignalListRequestPage.new({
    limit: 2,
  }),
  sort: DatadogAPIClient::V2::SecurityMonitoringSignalsSort::TIMESTAMP_ASCENDING,
})
opts = {
  body: body,
}
api_instance.search_security_monitoring_signals_with_pagination(opts) { |item| puts item }

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"
// Get a list of security signals returns "OK" response with pagination
use chrono::{DateTime, Utc};
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_security_monitoring::SearchSecurityMonitoringSignalsOptionalParams;
use datadog_api_client::datadogV2::api_security_monitoring::SecurityMonitoringAPI;
use datadog_api_client::datadogV2::model::SecurityMonitoringSignalListRequest;
use datadog_api_client::datadogV2::model::SecurityMonitoringSignalListRequestFilter;
use datadog_api_client::datadogV2::model::SecurityMonitoringSignalListRequestPage;
use datadog_api_client::datadogV2::model::SecurityMonitoringSignalsSort;
use futures_util::pin_mut;
use futures_util::stream::StreamExt;

#[tokio::main]
async fn main() {
    let body = SecurityMonitoringSignalListRequest::new()
        .filter(
            SecurityMonitoringSignalListRequestFilter::new()
                .from(
                    DateTime::parse_from_rfc3339("2021-11-11T10:56:11+00:00")
                        .expect("Failed to parse datetime")
                        .with_timezone(&Utc),
                )
                .query("security:attack status:high".to_string())
                .to(DateTime::parse_from_rfc3339("2021-11-11T11:11:11+00:00")
                    .expect("Failed to parse datetime")
                    .with_timezone(&Utc)),
        )
        .page(SecurityMonitoringSignalListRequestPage::new().limit(2))
        .sort(SecurityMonitoringSignalsSort::TIMESTAMP_ASCENDING);
    let configuration = datadog::Configuration::new();
    let api = SecurityMonitoringAPI::with_config(configuration);
    let response = api.search_security_monitoring_signals_with_pagination(
        SearchSecurityMonitoringSignalsOptionalParams::default().body(body),
    );
    pin_mut!(response);
    while let Some(resp) = response.next().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
/**
 * Get a list of security signals returns "OK" response with pagination
 */

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

const configuration = client.createConfiguration();
const apiInstance = new v2.SecurityMonitoringApi(configuration);

const params: v2.SecurityMonitoringApiSearchSecurityMonitoringSignalsRequest = {
  body: {
    filter: {
      from: new Date(new Date().getTime() + -15 * 60 * 1000),
      query: "security:attack status:high",
      to: new Date(),
    },
    page: {
      limit: 2,
    },
    sort: "timestamp",
  },
};

(async () => {
  try {
    for await (const item of apiInstance.searchSecurityMonitoringSignalsWithPagination(
      params
    )) {
      console.log(item);
    }
  } catch (error) {
    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"