Run a groups query¶

POST/queries/detection-groups

Run a detection groups query.

Required permissiondetections.queries.detections:create

Parameters¶

Name	In	Type	Required	Description
`X-Tenant-ID`	header	string (uuid)	Yes	Tenant ID.

Request body¶

Content type: application/json

Request body fields

detectionRulestring

The Detection rule ID.
Must match the pattern ^[\p{L}0-9\s_-]*$. Must be 0–300 characters long.

deviceNamestring

The device name.
Must match the pattern ^[\p{L}0-9\s_-]*$. Must be 0–200 characters long.

severityarray of integer

Filter detection group by the severity level.
Items must be unique. Each item must be ≥ 0 and ≤ 10.

typearray of string

Filter detection group by the type.
Items must be unique. Each item must be one of: process, threat, vulnerability.

categoryarray of string

Filter detection group by the category.
Items must be unique. Each item must be one of: cloud, endpoint, email, firewall, iam, network, compound, backupAndRecovery.

sourcestring

The detection source.
Must match the pattern ^[\p{L}0-9\s]*$. Must be 0–200 characters long.

mitreAttackTacticsarray of string

Filter detection group by the MITRE ATT&CK tactic.
Items must be unique. Each item must be one of: collection, commandControl, credentialAccess, defenseEvasion, discovery, execution, exfiltration, impact, initialAccess, lateralMovement, persistence, privilegeEscalation, reconnaissance, resourceDevelopment, undefined.

mitreAttackstring

Case-insensitive text field that allows partial matching to filter detection group by MITRE ATT&CK technique ID, technique name, or tactic.

userNamearray of string

Filter detection group by the username (exact match).
Each item must match the pattern ^[\p{L}\s_-]*$. Each item must be 0–300 characters long.

entityTypestring

The entity type.
Must match the pattern ^[\p{L}\s]*$. Must be 0–200 characters long.

locationstring

The location.
Must match the pattern ^[\p{L}\s.-]*$. Must be 0–200 characters long.

idsarray of string

Filter detection group by the ID.
Must contain at most 10 items. Items must be unique. Each item must match the pattern ^[A-Fa-f0-9_-]+$. Each item must be at most 150 characters long.

operatingSystemarray of string

Filter by detection group by the operating system (exact match).
Each item must match the pattern ^[\p{L}\s]*$. Each item must be 0–100 characters long.

operatingSystemNamestring

The operating system name.
Must match the pattern ^[\p{L}0-9\s._-]*$. Must be 0–200 characters long.

showSuppressedboolean

Show suppressed detections, if true. False by default.

sortarray of object

Defines how to sort the data.

Show child attributesHide child attributes

fieldstring

Field that supports sorting.
Must be one of: category, detectionRule, sensorCount, count, device, firstSeenAt, lastSeenAt, mitreAttack, severity, ruleDescription, sensorGeneratedAt.

directionstring

Order of the results.
Must be one of: asc, desc.

fromstring (date-time)

Start of time range that is applied when retrieving the detection groups. The default value is one day before the current date and time.

tostring (date-time)

End of time range that is applied when retrieving the detection groups. The default value is the current date and time.

Request samples¶

cURLPythonPowerShellGoJavaScript

curl -X POST "https://api-<data-region>.central.sophos.com/detections/v1/queries/detection-groups" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"detectionRule\": \"MS-SEC-GRAPH-open\",
  \"severity\": [
    7,
    8,
    9,
    10
  ],
  \"sort\": [
    {
      \"field\": \"severity\",
      \"direction\": \"asc\"
    }
  ],
  \"from\": \"2021-11-10T12:23:54.780Z\",
  \"to\": \"2021-11-17T12:23:54.780Z\"
}"

import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/detections/v1/queries/detection-groups",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'detectionRule': 'MS-SEC-GRAPH-open',
    'severity': [7, 8, 9, 10],
    'sort': [{'field': 'severity', 'direction': 'asc'}],
    'from': '2021-11-10T12:23:54.780Z',
    'to': '2021-11-17T12:23:54.780Z'},
)
print(response.json())

$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "detectionRule": "MS-SEC-GRAPH-open",
  "severity": [
    7,
    8,
    9,
    10
  ],
  "sort": [
    {
      "field": "severity",
      "direction": "asc"
    }
  ],
  "from": "2021-11-10T12:23:54.780Z",
  "to": "2021-11-17T12:23:54.780Z"
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/detections/v1/queries/detection-groups" -Headers $headers -Body $body -ContentType "application/json"

package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/detections/v1/queries/detection-groups", strings.NewReader(`{
  "detectionRule": "MS-SEC-GRAPH-open",
  "severity": [
    7,
    8,
    9,
    10
  ],
  "sort": [
    {
      "field": "severity",
      "direction": "asc"
    }
  ],
  "from": "2021-11-10T12:23:54.780Z",
  "to": "2021-11-17T12:23:54.780Z"
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

const response = await fetch("https://api-<data-region>.central.sophos.com/detections/v1/queries/detection-groups", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "detectionRule": "MS-SEC-GRAPH-open",
  "severity": [
    7,
    8,
    9,
    10
  ],
  "sort": [
    {
      "field": "severity",
      "direction": "asc"
    }
  ],
  "from": "2021-11-10T12:23:54.780Z",
  "to": "2021-11-17T12:23:54.780Z"
}),
});
const data = await response.json();
console.log(data);

Responses¶

`201` — Successful creation of a group query.¶

Response fields

idstring (uuid)

ID of the run.

createdAtstring (date-time)

Timestamp when the run started.

expiresAtstring (date-time)

Timestamp when the run expired.

finishedAtstring (date-time)

Timestamp when the run finished.

resultCountinteger

The total number of items across all pages.

resultstring

Result of a query run on groups or detections.
Must be one of: succeeded, canceled, failed, notAvailable, timedOut.

statusstring

Status of a query run on groups or detections.
Must be one of: finished, pending, started.

Errors¶

Status	Meaning
`400`	Bad Request.
`401`	Unauthorized.
`403`	Forbidden.
`429`	Too Many Requests.
`500`	Unexpected error.

All error responses share the same shape — see the error response object.

Response examples¶

`201`¶

{
  "id": "4a9bb69a-c7f1-4a59-b912-7fe4ba70b751",
  "createdAt": "2023-11-22T18:55:33.811Z",
  "expiresAt": "2023-11-23T18:55:33.811Z",
  "finishedAt": "2023-11-22T18:55:35.716Z",
  "resultCount": 100,
  "result": "succeeded",
  "status": "finished"
}

See the guide for a narrative walkthrough of this API.