Allow List - Amazon Macie

Allow List

The Allow List resource provides access to existing allow lists for your Amazon Macie account. In Macie, an allow list defines specific text or a text pattern that you want Macie to ignore when it inspects a data source for sensitive data. If data matches text or a text pattern in an allow list, Macie doesn’t report the data. This is the case even if the data matches the criteria of a managed data identifier or a custom data identifier. You can create and use allow lists in all the AWS Regions where Macie is currently available except the Asia Pacific (Osaka) Region.

Macie supports two types of allow lists. An allow list can be a line-delimited plaintext file that lists specific text to ignore. For this type of list (s3WordsList), you create the list by using a text editor, store the list in an Amazon Simple Storage Service (Amazon S3) general purpose bucket, and then configure settings for Macie to access the list in the bucket. Alternatively, an allow list can specify a regular expression (regex) that defines a text pattern to ignore. For this type of list (regex), you create and store the regex and all other list settings in Macie. For more information, see Defining sensitive data exceptions with allow lists in the Amazon Macie User Guide.

You can use the Allow List resource to retrieve detailed information about an allow list, including the current status of the list. If a list is stored in an S3 bucket, the list's status indicates whether Macie can retrieve and parse the list. You can also use the Allow List resource to update the settings for an allow list or to delete an allow list from Macie.

To use this resource, you have to specify the unique identifier for the allow list that your request applies to. To find this identifier, use the Allow Lists resource.

URI

/allow-lists/id

HTTP methods

DELETE

Operation ID: DeleteAllowList

Deletes an allow list.

Path parameters
NameTypeRequiredDescription
idStringTrue

The unique identifier for the Amazon Macie resource that the request applies to.

Query parameters
NameTypeRequiredDescription
ignoreJobChecksStringFalse

Specifies whether to force deletion of the allow list, even if active classification jobs are configured to use the list.

When you try to delete an allow list, Amazon Macie checks for classification jobs that use the list and have a status other than COMPLETE or CANCELLED. By default, Macie rejects your request if any jobs meet these criteria. To skip these checks and delete the list, set this value to true. To delete the list only if no active jobs are configured to use it, set this value to false.

Responses
Status codeResponse modelDescription
200Empty Schema

The request succeeded. The allow list was deleted and there isn't any content to include in the body of the response (No Content).

400ValidationException

The request failed because the input doesn't satisfy the constraints specified by the service.

403AccessDeniedException

The request was denied because you don't have sufficient access to the specified resource.

404ResourceNotFoundException

The request failed because the specified resource wasn't found.

429ThrottlingException

The request failed because you sent too many requests during a certain amount of time.

500InternalServerException

The request failed due to an unknown internal server error, exception, or failure.

GET

Operation ID: GetAllowList

Retrieves the settings and status of an allow list.

Path parameters
NameTypeRequiredDescription
idStringTrue

The unique identifier for the Amazon Macie resource that the request applies to.

Responses
Status codeResponse modelDescription
200GetAllowListResponse

The request succeeded.

400ValidationException

The request failed because the input doesn't satisfy the constraints specified by the service.

403AccessDeniedException

The request was denied because you don't have sufficient access to the specified resource.

404ResourceNotFoundException

The request failed because the specified resource wasn't found.

429ThrottlingException

The request failed because you sent too many requests during a certain amount of time.

500InternalServerException

The request failed due to an unknown internal server error, exception, or failure.

PUT

Operation ID: UpdateAllowList

Updates the settings for an allow list.

Path parameters
NameTypeRequiredDescription
idStringTrue

The unique identifier for the Amazon Macie resource that the request applies to.

Responses
Status codeResponse modelDescription
200UpdateAllowListResponse

The request succeeded. The settings for the allow list were updated.

400ValidationException

The request failed because the input doesn't satisfy the constraints specified by the service.

403AccessDeniedException

The request was denied because you don't have sufficient access to the specified resource.

404ResourceNotFoundException

The request failed because the specified resource wasn't found.

429ThrottlingException

The request failed because you sent too many requests during a certain amount of time.

500InternalServerException

The request failed due to an unknown internal server error, exception, or failure.

Schemas

Request bodies

{ "criteria": { "regex": "string", "s3WordsList": { "bucketName": "string", "objectKey": "string" } }, "description": "string", "name": "string" }

Response bodies

{ }
{ "arn": "string", "createdAt": "string", "criteria": { "regex": "string", "s3WordsList": { "bucketName": "string", "objectKey": "string" } }, "description": "string", "id": "string", "name": "string", "status": { "code": enum, "description": "string" }, "tags": { }, "updatedAt": "string" }
{ "arn": "string", "id": "string" }
{ "message": "string" }
{ "message": "string" }
{ "message": "string" }
{ "message": "string" }
{ "message": "string" }

Properties

AccessDeniedException

Provides information about an error that occurred due to insufficient access to a specified resource.

PropertyTypeRequiredDescription
message

string

False

The explanation of the error that occurred.

AllowListCriteria

Specifies the criteria for an allow list. The criteria must specify a regular expression (regex) or an S3 object (s3WordsList). It can't specify both.

PropertyTypeRequiredDescription
regex

string

Pattern: ^[\s\S]+$

MinLength: 1

MaxLength: 512

False

The regular expression (regex) that defines the text pattern to ignore. The expression can contain as many as 512 characters.

s3WordsList

S3WordsList

False

The location and name of the S3 object that lists specific text to ignore.

AllowListStatus

Provides information about the current status of an allow list, which indicates whether Amazon Macie can access and use the list's criteria.

PropertyTypeRequiredDescription
code

AllowListStatusCode

True

The current status of the allow list. If the list's criteria specify a regular expression (regex), this value is typically OK. Amazon Macie can compile the expression.

If the list's criteria specify an S3 object, possible values are:

  • OK - Macie can retrieve and parse the contents of the object.

  • S3_OBJECT_ACCESS_DENIED - Macie isn't allowed to access the object or the object is encrypted with a customer managed AWS KMS key that Macie isn't allowed to use. Check the bucket policy and other permissions settings for the bucket and the object. If the object is encrypted, also ensure that it's encrypted with a key that Macie is allowed to use.

  • S3_OBJECT_EMPTY - Macie can retrieve the object but the object doesn't contain any content. Ensure that the object contains the correct entries. Also ensure that the list's criteria specify the correct bucket and object names.

  • S3_OBJECT_NOT_FOUND - The object doesn't exist in Amazon S3. Ensure that the list's criteria specify the correct bucket and object names.

  • S3_OBJECT_OVERSIZE - Macie can retrieve the object. However, the object contains too many entries or its storage size exceeds the quota for an allow list. Try breaking the list into multiple files and ensure that each file doesn't exceed any quotas. Then configure list settings in Macie for each file.

  • S3_THROTTLED - Amazon S3 throttled the request to retrieve the object. Wait a few minutes and then try again.

  • S3_USER_ACCESS_DENIED - Amazon S3 denied the request to retrieve the object. If the specified object exists, you're not allowed to access it or it's encrypted with an AWS KMS key that you're not allowed to use. Work with your AWS administrator to ensure that the list's criteria specify the correct bucket and object names, and you have read access to the bucket and the object. If the object is encrypted, also ensure that it's encrypted with a key that you're allowed to use.

  • UNKNOWN_ERROR - A transient or internal error occurred when Macie attempted to retrieve or parse the object. Wait a few minutes and then try again. A list can also have this status if it's encrypted with a key that Amazon S3 and Macie can't access or use.

description

string

Pattern: ^[\s\S]+$

MinLength: 1

MaxLength: 1024

False

A brief description of the status of the allow list. Amazon Macie uses this value to provide additional information about an error that occurred when Macie tried to access and use the list's criteria.

AllowListStatusCode

Indicates the current status of an allow list. Depending on the type of criteria that the list specifies, possible values are:

  • OK

  • S3_OBJECT_NOT_FOUND

  • S3_USER_ACCESS_DENIED

  • S3_OBJECT_ACCESS_DENIED

  • S3_THROTTLED

  • S3_OBJECT_OVERSIZE

  • S3_OBJECT_EMPTY

  • UNKNOWN_ERROR

Empty

The request succeeded and there isn't any content to include in the body of the response (No Content).

GetAllowListResponse

Provides information about the settings and status of an allow list.

PropertyTypeRequiredDescription
arn

string

Pattern: ^arn:(aws|aws-cn|aws-us-gov):macie2:[a-z1-9-]{9,20}:\d{12}:allow-list\/[a-z0-9]{22}$

MinLength: 71

MaxLength: 89

True

The Amazon Resource Name (ARN) of the allow list.

createdAt

string

Format: date-time

True

The date and time, in UTC and extended ISO 8601 format, when the allow list was created in Amazon Macie.

criteria

AllowListCriteria

False

The criteria that specify the text or text pattern to ignore. The criteria can be the location and name of an S3 object that lists specific text to ignore (s3WordsList), or a regular expression (regex) that defines a text pattern to ignore.

description

string

Pattern: ^[\s\S]+$

MinLength: 1

MaxLength: 512

False

The custom description of the allow list.

id

string

Pattern: ^[a-z0-9]{22}$

MinLength: 22

MaxLength: 22

True

The unique identifier for the allow list.

name

string

Pattern: ^.+$

MinLength: 1

MaxLength: 128

True

The custom name of the allow list.

status

AllowListStatus

False

The current status of the allow list, which indicates whether Amazon Macie can access and use the list's criteria.

tags

TagMap

False

A map of key-value pairs that specifies which tags (keys and values) are associated with the allow list.

updatedAt

string

Format: date-time

True

The date and time, in UTC and extended ISO 8601 format, when the allow list's settings were most recently changed in Amazon Macie.

InternalServerException

Provides information about an error that occurred due to an unknown internal server error, exception, or failure.

PropertyTypeRequiredDescription
message

string

False

The explanation of the error that occurred.

ResourceNotFoundException

Provides information about an error that occurred because a specified resource wasn't found.

PropertyTypeRequiredDescription
message

string

False

The explanation of the error that occurred.

S3WordsList

Provides information about an S3 object that lists specific text to ignore.

PropertyTypeRequiredDescription
bucketName

string

Pattern: ^[A-Za-z0-9.\-_]{3,255}$

MinLength: 3

MaxLength: 255

True

The full name of the S3 bucket that contains the object.

objectKey

string

Pattern: ^[\s\S]+$

MinLength: 1

MaxLength: 1024

True

The full name (key) of the object.

TagMap

A string-to-string map of key-value pairs that specifies the tags (keys and values) for an Amazon Macie resource.

PropertyTypeRequiredDescription

*

string

False

ThrottlingException

Provides information about an error that occurred because too many requests were sent during a certain amount of time.

PropertyTypeRequiredDescription
message

string

False

The explanation of the error that occurred.

UpdateAllowListRequest

Changes the settings for an allow list. If you change the list's criteria, Amazon Macie tests the new criteria when it processes your request. If the criteria specify a regular expression that Macie can't compile or an S3 object that Macie can't retrieve or parse, an error occurs.

PropertyTypeRequiredDescription
criteria

AllowListCriteria

True

The criteria that specify the text or text pattern to ignore. The criteria can be the location and name of an S3 object that lists specific text to ignore (s3WordsList), or a regular expression that defines a text pattern to ignore (regex).

You can change a list's underlying criteria, such as the name of the S3 object or the regular expression to use. However, you can't change the type from s3WordsList to regex or the other way around.

description

string

Pattern: ^[\s\S]+$

MinLength: 1

MaxLength: 512

False

A custom description of the allow list. The description can contain as many as 512 characters.

name

string

Pattern: ^.+$

MinLength: 1

MaxLength: 128

True

A custom name for the allow list. The name can contain as many as 128 characters.

UpdateAllowListResponse

Provides information about an allow list whose settings were changed in response to a request.

PropertyTypeRequiredDescription
arn

string

Pattern: ^arn:(aws|aws-cn|aws-us-gov):macie2:[a-z1-9-]{9,20}:\d{12}:allow-list\/[a-z0-9]{22}$

MinLength: 71

MaxLength: 89

True

The Amazon Resource Name (ARN) of the allow list.

id

string

Pattern: ^[a-z0-9]{22}$

MinLength: 22

MaxLength: 22

True

The unique identifier for the allow list.

ValidationException

Provides information about an error that occurred due to a syntax error in a request.

PropertyTypeRequiredDescription
message

string

False

The explanation of the error that occurred.

See also

For more information about using this API in one of the language-specific AWS SDKs and references, see the following:

DeleteAllowList

GetAllowList

UpdateAllowList