Using the Resource Groups API

PREVIEW FEATURE

This topic describes functionality that is currently in preview.

The Resource Groups API lets you view, modify, and create resource groups with conditions that allow you to closely control the resources that will be associated with the group. For example, you can create resource groups with resources with a particular tag or region.

This page provides examples of resource groups you can create with the Lacework API, and lists the fields that you can test with the conditions used to create them. For general information about resource groups, including how to work with them in the Lacework Console, see Resource Groups.

The Query Object

When creating or modifying a resource group, you can specify conditions for the resources that belong to that group using the query object in the request body to the endpoint.

The query object has this format:

"query":{
  "filters":[
    {
      "^\\w+$":{
        "field":"string",
        "operation":"STARTS_WITH",
        "values":[
           "string"
        ],
        "key":"string"
      }
    }
  ],
  "expression":{
    "operator":"AND",
    "children":[
      {
        "operator":"AND",
        "filterName":"string",
        "children":[ ]
      }
    ]
  }
}

The query object is made up of one or more filters, which specify a data field to be tested by the condition, an operation, and the values against which the field is tested based on the operation. The key field is required for fields that support key-value pairs, as described in Filterable Fields.

Possible operations include STARTS_WITH, INCLUDES, ENDS_WITH, and EQUALS. The resource groups field and the AWS account field work with EQUALS only.

The expression combines filters with an operator, AND or OR, into a multi-level logical hierarchy. Notice that there can only be one type of operator for each expression level. That is, the operator applied to filters at say the top expression level, or its child, or its child, can either be OR or AND, but not both.

Examples

The following example creates a resource group for all AWS resources in any US region that ends with 1:

{
  "name": "US regions 1",
  "description": "Resource in US regions ending with 1",
  "resourceType": "AWS",
  "query": {
    "filters": {
      "filter2": {
        "field": "Region",
        "operation": "STARTS_WITH",
        "values": [
          "us"
        ]
      },
      "filter3": {
        "field": "Region",
        "operation": "ENDS_WITH",
        "values": [
          "1"
        ]
      },
    },
    "expression": {
      "operator": "AND",
      "children": [
        {
          "filterName": "filter2"
        },
        {
          "filterName": "filter3"
        }
      ]
    }
  }
  "enabled": 1
}

The following example defines a group made up of resources associated with a specific account in either an Asia Pacific or US West (N. California) region:

{
  "NAME": "Resource group with nested conditions",
  "DESCRIPTION": "",
  "GROUP_TYPE": "AWS",
  "QUERY": {
    "filters": {
      "filter0": {
        "field": "Account",
        "operation": "EQUALS",
        "values": [
          "123412341234"
        ]
      },
      "filter77": {
        "field": "Region",
        "operation": "EQUALS",
        "values": [
          "ap-east-1"
        ]
      },
      "filter78": {
        "field": "Region",
        "operation": "EQUALS",
        "values": [
          "us-west-1"
        ]
      }
    },
    "expression": {
      "operator": "AND",
      "children": [
        {
          "filterName": "filter0"
        },
        {
          "operator": "OR",
          "children": [
            {
              "filterName": "filter77"
            },
            {
              "filterName": "filter78"
            }
          ]
        }
      ]
    }
  }
}

The following example creates a resource group for AWS resources with a HOST tag from the Asia Pacific South or Asia Pacific Southeast region:

{
  "name": "All resources tags and regions",
  "description": "Custom resource group for resources with a resource tag named HOST with any value and from Asia Pacific South regions",
  "resourceType": "AWS",
  "query": {
    "filters": {
      "filter0": {
        "field": "Resource Tag",
        "operation": "INCLUDES",
        "values": [
          "*"
        ],
        "key": "HOST"
      },
      "filter1": {
        "field": "Region",
        "operation": "STARTS_WITH",
        "values": [
          "ap-south"
        ]
      }
    },
    "expression": {
      "operator": "AND",
      "children": [
        {
          "filterName": "filter0"
        },
        {
          "filterName": "filter1"
        }
      ]
    }
  },
  "enabled": 1
}

See the Resource Groups API for the complete specification of the request body and the response format.

Filterable Fields

The fields you can filter on in a query statement appear below, organized by resource type.

AWS

• Account
• Organization ID
• Resource Tag (requires a key field that specifies the resource tag name)
• Region
• Resource Group ID
• Resource Group Name

GCP

• Project ID
• Organization ID
• Organization Name
• Folder
• Resource Label (requires a key field that specifies the resource label name)
• Region
• Resource Group ID
• Resource Group Name

Azure

• Subscription ID
• Subscription Name
• Tenant ID
• Tenant Name
• Resource Tag (requires a key field that specifies the resource tag name)
• Region
• Resource Group ID
• Resource Group Name

Container

• Container Tag (requires a key field that specifies the container tag name)
• Container Label (requires a key field that specifies the container label name)
• Image Repo
• Image Registry
• Resource Group ID
• Resource Group Name

Machine

• Machine Tag (requires a key field that specifies the machine tag name)
• Resource Group ID
• Resource Group Name

Kubernetes

• AWS Account
• AWS Region
• Cluster Name
• Namespace
• Resource Group ID
• Resource Group Name

Oracle Cloud Infrastructure (OCI)

• Compartment ID
• Compartment Name
• Region
• Resource Group ID
• Resource Group Name
• Resource Tag