Skip to main content

Add or Edit Compliance Policy Exceptions through the Lacework API

This method requires that you obtain the policy exception configuration before creating an exception. The exception configuration varies from policy to policy, so this must be known before creating an exception for a given policy.

tip

Generate your API Access Key and Token before attempting to create exceptions.

The access token is represented as $AccountAdminToken within the curl command examples shown in this article.

General Considerations & Limitations
  • Manual Policies cannot have exceptions applied to them.
  • Once an exception is added or edited, it will not take effect until the next compliance assessment run is complete.

Add Compliance Policy Exceptions​

1. Get the Policy Exception Configuration​

Use the Policies Details endpoint to get all the information on a given policy:

GET https://YourLacework.lacework.net/api/v2/Policies/{policyId}

Example for lacework-global-87
curl -X GET -H "Authorization: Bearer $AccountAdminToken" -H "Content-Type: application/json" "https://myAccount.lacework.net/api/v2/Policies/lacework-global-87"

From the output, you need the exceptionConfiguration section as that contains the required fieldKey values for creating the exception.

If you have jq installed, you can adjust the example above to only print the exceptionConfiguration section:

Example for lacework-global-87 with jq
curl -X GET -H "Authorization: Bearer $AccountAdminToken" -H "Content-Type: application/json" "https://myAccount.lacework.net/api/v2/Policies/lacework-global-87" | jq '.data.exceptionConfiguration'
tip

Alternatively, if you have the Lacework CLI installed, you can use the Raw Lacework API to get the exceptionConfig for a given policy:

lacework api get /api/v2/Policies/<policy-id> | jq '.data.exceptionConfiguration'

Exception Configuration Examples​

Example output for lacework-global-87
    "exceptionConfiguration": {
      "constraintFields": [
        {
          "dataType": "String",
          "fieldKey": "accountIds",
          "multiValue": true
        },
        {
          "dataType": "String",
          "fieldKey": "regionNames",
          "multiValue": true
        },
        {
          "dataType": "String",
          "fieldKey": "resourceNames",
          "multiValue": false
        },
        {
          "dataType": "KVTagPair",
          "fieldKey": "resourceTags",
          "multiValue": true
        }
      ]
    },

2. Create the JSON Payload for the Exception​

Once you have the exception configuration for the policy, create the JSON payload for the policy exception based on the fieldKey values.

AND vs OR​

The following operator logic applies in these circumstances:

  • Multiple exception criteria in a single exception = AND

    For example:

    1. A policy exception is created for an Amazon S3 bucket resource with criteria that includes a resourceNames and resourceTags field.
    2. The exception applies to a bucket that has a matching resource name and resource tag.

  • Multiple policy exceptions for a single policy = OR

    For example:

    1. A policy exception is created for an Amazon S3 bucket resource with criteria of a resourceNames.
    2. A second policy exception is created with criteria of resourceTags.
    3. The exception applies to any bucket found that has a matching resource name defined in the first exception or resource tags defined in the second exception.

Data Types and Wildcards​

Use the following sections to understand the expected format for each fieldKey value.

JSON fieldKeyUI EquivalentData TypeWildcards accepted?
accountIdsAccount IdsStringYes
regionNamesRegion NamesStringYes
resourceNamesUser Name, Policy Name, Bucket Name, Volume Id, RDS Database, Trail Name, Key Id/Alias, VPC Id, Network ACL ARN, Group Id/NameStringYes
resourceTagsResource TagsKey ValueNo

Wildcard Usage​

You can use wildcards to match and exclude singular or multiple resources for field values that accept wildcards.

For example, if you wanted to exclude the AWS resource mySecurityGroup_sg, you can exclude it using wildcards with one of the following examples:

AWS Example 1
      {
        "fieldKey": "resourceNames",
        "fieldValues": [
          "*_sg"
        ]
      },
AWS Example 2
      {
        "fieldKey": "resourceNames",
        "fieldValues": [
          "*SecurityGroup*"
        ]
      },
AWS Example 3
      {
        "fieldKey": "resourceNames",
        "fieldValues": [
          "mySecurityGroup*"
        ]
      },

For Google Cloud, if you wanted to exclude the resource //storage.googleapis.com/myBucketName, the following example will work:

Google Cloud Example
      {
        "fieldKey": "resourceName",
        "fieldValues": [
          "*myBucketName"
        ]
      },

JSON Payload Examples​

danger

Do not use the ARN format when providing the resourceNames value for policy exceptions.

For example, using arn:aws:s3:::mys3bucket is not accepted, as only mys3bucket should be provided.

Based on the policy type, the correct type of resource should be provided when entering the fieldValues for resourceNames (if you are not using a "*" wildcard).

For example, the lacework-global-87 policy requires one or more security groups in the fieldValues entry for resourceNames:

Example JSON Payload for lacework-global-87
{
    "description": "All traffic is allowed through this security group",
    "constraints": [
      {
        "fieldKey": "accountIds",
        "fieldValues": [
          "*"
        ]
      },
      {
        "fieldKey": "regionNames",
        "fieldValues": [
          "us-west-2"
        ]
      },
      {
        "fieldKey": "resourceNames",
        "fieldValues": [
          "mySecurityGroup_sg"
        ]
      },
      {
        "fieldKey": "resourceTags",
        "fieldValues": [
          {
          "key": "mykey",
          "value": "myvalue"
          }
        ]
      },
    ]
}
note

If accountIds or regionNames are not included in the JSON payload and are part of the exception criteria for a policy, the default fieldValues would be *.

This would mean all integrated accounts and/or regions would be included in the exception.

3. Add the Policy Exception​

Use the Create Policy Exceptions endpoint when adding new policy exceptions:

POST /api/v2/Exceptions?policyId={policyId}

In the example below, the JSON payload exists as a file named myexceptionpayload.json in the local directory:

Example for lacework-global-87
curl -X POST -H "Authorization: Bearer $AccountAdminToken" -H "Content-Type: application/json" --data @myexceptionpayload.json "https://myAccount.lacework.net/api/v2/Exceptions?policyId=lacework-global-87"

The command is successful if a 201 response is received.

Edit Compliance Policy Exceptions​

Editing an existing Compliance policy exception through the API is similar to adding a new policy exception. A different endpoint will be used, and the existing policy exception ID must also be obtained.

  1. Edit your existing JSON Payload file or create a new one with the updated details.

  2. Use the List All Policy Exceptions endpoint to find all exceptions applied to a policy:

    GET /api/v2/Exceptions?policyId={policyId}

    Example for lacework-global-87
    curl -X GET -H "Authorization: Bearer $AccountAdminToken" -H "Content-Type: application/json" "https://myAccount.lacework.net/api/v2/Exceptions?policyId=lacework-global-87"

    Find the exceptionId that you want to update as this will be used in the next step.

  3. Update policy exceptions by using the Update Policy Exceptions endpoint:

    PATCH /api/v2/Exceptions/{exceptionId}?policyId={policyId}

    In the example below, the JSON payload exists as a file named myupdatedexceptionpayload.json in the local directory and the existing policy exception ID is myExceptionId:

    Example for lacework-global-87
    curl -X PATCH -H "Authorization: Bearer $AccountAdminToken" -H "Content-Type: application/json" --data @myupdatedexceptionpayload.json "https://myAccount.lacework.net/api/v2/Exceptions/myExceptionId?policyId=lacework-global-87"

    The command is successful if a 200 response is received.

Last updated on