Security Monitoring

Search remediation groups

Changed on

Search the remediation groups of your organization. A remediation group gathers the open security findings that one change fixes, such as updating a package in a repository or upgrading an image.

Each group comes from a grouping definition, which sets the finding type it covers and the kind object the group returns:

Grouping definitionFinding typeKind object
sca.package_updatelibrary_vulnerabilitypackage_update
cloudvm.image_updatehost_and_container_vulnerabilityimage_update

Groups are computed from the attributes of security findings, described in the security findings schema. The description of each kind object lists the findings its grouping definition reads and the attribute each field comes from.

The search includes all open findings, regardless of when they were first detected.

This endpoint requires the cases_read permission and either the security_monitoring_findings_read or appsec_vm_read permission.

get/api/v2/security/remediation_groups

Request

  • Base URL
    https://api.datadoghq.com
  • Auth
    • API key in header DD-API-KEY and API key in header DD-APPLICATION-KEY
    • or OAuth 2
      Authorization code/oauth2/v1/authorize
      Token URL/oauth2/v1/token
      Scopessecurity_monitoring_findings_read, cases_read
    • or OAuth 2
      Authorization code/oauth2/v1/authorize
      Token URL/oauth2/v1/token
      Scopesappsec_vm_read, cases_read

Query parameters

filter[finding_type]RemediationGroupFindingType[]

Returns only groups whose grouping definition covers this @finding_type value. To match more than one finding type, repeat the parameter.

[
  "library_vulnerability"
]
filter[query]string

Returns only groups with at least one open finding that matches the query. Use the security findings search syntax with attributes from the security findings schema, prefixed by @. For example, @severity:(critical OR high) returns groups with at least one critical or high finding. The group's counts still include every finding in the group. The query can be at most 2048 bytes after JSON encoding, and the parameter can appear only once.

sortstring

Comma-separated list of sort fields. Prefix a field with - to sort in descending order. findings.by_severity sorts by the critical count, then high, medium, low, info, none, and unknown. findings.total sorts by the total finding count. By default, groups are sorted by critical count, then high count, then total finding count, all in descending order.

page[size]integer

Number of groups in a page.

page[number]integer

Page to return, starting at 1.

include'case'

Related resource to add to included.

Example:case

Adds each group's case to included. case is the only supported value.

Response

OK

Example response

{
  "data": [
    {
      "attributes": {
        "findings": {
          "by_severity": {
            "critical": 2,
            "high": 5,
            "low": 1,
            "medium": 4
          },
          "total": 12
        },
        "grouping_definition_id": "sca.package_update",
        "image_update": {
          "action": "alpine",
          "advisory_count": 25,
          "exploitable_cve_count": 2,
          "file_count": 1,
          "grouping_location": "Dockerfile",
          "location_is_filename": true,
          "remediation_kind": "image_update",
          "target_version": "3.20.3"
        },
        "package_update": {
          "advisory_count": 3,
          "ecosystem": "npm",
          "exploitable_cve_count": 1,
          "file_count": 2,
          "package_name": "lodash",
          "repository_id": "github.com/acme/api",
          "target_version": "4.17.21"
        },
        "title": "Update lodash to 4.17.21 in github.com/acme/api"
      },
      "id": "sca.package_update:eyJlY29zeXN0ZW0iOiJucG0iLCJyZWNvbW1lbmRlZF9uYW1lIjoibG9kYXNoIiwicmVwb3NpdG9yeV9pZCI6ImdpdGh1Yi5jb20vYWNtZS9hcGkifQ",
      "relationships": {
        "case": {
          "data": {
            "id": "c1234567-89ab-cdef-0123-456789abcdef",
            "type": "cases"
          }
        }
      },
      "type": "remediation_groups"
    }
  ],
  "included": [
    {
      "attributes": {
        "archived_at": "2025-01-01T00:00:00.000Z",
        "assigned_to": {
          "data": {
            "id": "00000000-0000-0000-2345-000000000000",
            "type": "users"
          }
        },
        "closed_at": "2025-01-01T00:00:00.000Z",
        "created_at": "2025-01-01T00:00:00.000Z",
        "creation_source": "CS_SECURITY_FINDING",
        "description": "A description of the case.",
        "due_date": "2025-01-01",
        "insights": [
          {
            "ref": "/security/appsec/vm/library/vulnerability/dfa027f7c037b2f77159adc027fecb56?detection=static",
            "resource_id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==",
            "type": "SECURITY_FINDING"
          }
        ],
        "jira_issue": {
          "error_message": "{\"errorMessages\":[\"An error occured.\"],\"errors\":{}}",
          "result": {
            "account_id": "463a8631-680e-455c-bfd3-3ed04d326eb7",
            "issue_id": "2871276",
            "issue_key": "PROJ-123",
            "issue_url": "https://domain.atlassian.net/browse/PROJ-123"
          },
          "status": "COMPLETED"
        },
        "key": "PROJ-123",
        "linear_issue": {
          "error_message": "Linear issue creation failed.",
          "result": {
            "account_id": "463a8631-680e-455c-bfd3-3ed04d326eb7",
            "issue_id": "9c1e5f8a-2b3d-4c7e-8f6a-1d2e3f4a5b6c",
            "issue_key": "ENG-123",
            "team_id": "b5d3c8a1-7e6f-4d2c-9a8b-3c4d5e6f7a8b",
            "url": "https://linear.app/your-workspace/issue/ENG-123"
          },
          "status": "COMPLETED"
        },
        "modified_at": "2025-01-01T00:00:00.000Z",
        "priority": "P4",
        "servicenow_ticket": {
          "result": {
            "instance_name": "example",
            "sys_id": "abcdef0123456789abcdef0123456789",
            "sys_target_link": "https://example.service-now.com/incident.do?sys_id=abcdef0123456789abcdef0123456789",
            "sys_target_sys_id": "abcdef0123456789abcdef0123456789",
            "table_name": "incident",
            "url": "https://example.service-now.com/now/nav/ui/classic/params/target/incident.do?sys_id=abcdef0123456789abcdef0123456789"
          },
          "status": "COMPLETED"
        },
        "status": "OPEN",
        "status_group": "SG_OPEN",
        "status_name": "Open",
        "title": "A title for the case.",
        "type": "SECURITY"
      },
      "id": "c1234567-89ab-cdef-0123-456789abcdef",
      "relationships": {
        "created_by": {
          "data": {
            "id": "00000000-0000-0000-2345-000000000000",
            "type": "users"
          }
        },
        "modified_by": {
          "data": {
            "id": "00000000-0000-0000-2345-000000000000",
            "type": "users"
          }
        },
        "project": {
          "data": {
            "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
            "type": "projects"
          }
        }
      },
      "type": "cases"
    }
  ],
  "meta": {
    "page": {
      "number": 1,
      "size": 50,
      "total_filtered_count": 134
    }
  }
}

Changes

    • info

      the security scope security_monitoring_findings_read was added to the endpoint's security scheme AuthZ

    • info

      the security scope appsec_vm_read was removed from the endpoint's security scheme AuthZ

    • info

      the security scope security_monitoring_findings_read was added to the endpoint's security scheme AuthZ

    1 more change in this revision