Allow Lists - Amazon Macie

Allow Lists

In Amazon 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, 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:

  • Predefined text - For this type of list (s3WordsList), you create a line-delimited plaintext file that lists specific text to ignore. You store the file in an Amazon Simple Storage Service (Amazon S3) bucket and then configure settings for Macie to access the list in the bucket.

    This type of list typically contains specific words, phrases, and other kinds of character sequences that aren’t sensitive, aren't likely to change, and don’t necessarily adhere to a common pattern. If you use this type of list, Macie doesn't report occurrences of text that exactly match a complete entry in the list. Macie treats each entry in the list as a string literal value. Matches aren't case sensitive.

  • Regular expression - For this type of list (regex), you specify a regular expression that defines a text pattern to ignore. Unlike an allow list with predefined text, you create and store the regex and all other list settings in Macie.

    This type of list is helpful if you want to specify text that isn’t sensitive but varies or is likely to change while also adhering to a common pattern. If you use this type of list, Macie doesn't report occurrences of text that completely match the pattern defined by the list.

For more information, see Defining sensitive data exceptions with allow lists in the Amazon Macie User Guide.

You can use the Allow Lists resource to create an allow list or to retrieve a subset of information about all the existing allow lists for your account. To retrieve detailed information about the settings and status of an individual allow list, use the Allow List resource.

URI

/allow-lists

HTTP methods

GET

Operation ID: ListAllowLists

Retrieves a subset of information about all the allow lists for an account.

Query parameters
NameTypeRequiredDescription
nextTokenStringFalse

The nextToken string that specifies which page of results to return in a paginated response.

maxResultsStringFalse

The maximum number of items to include in each page of a paginated response.

Responses
Status codeResponse modelDescription
200ListAllowListsResponse

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.

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.

POST

Operation ID: CreateAllowList

Creates and defines the settings for an allow list.

Responses
Status codeResponse modelDescription
200CreateAllowListResponse

The request succeeded. The specified allow list was created.

400ValidationException

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

402ServiceQuotaExceededException

The request failed because fulfilling the request would exceed one or more service quotas for your account.

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.

409ConflictException

The request failed because it conflicts with the current state of the specified resource.

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

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

Response bodies

{ "allowLists": [ { "arn": "string", "createdAt": "string", "description": "string", "id": "string", "name": "string", "updatedAt": "string" } ], "nextToken": "string" }
{ "arn": "string", "id": "string" }
{ "message": "string" }
{ "message": "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.

AllowListSummary

Provides a subset of information about 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

False

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

createdAt

string

Format: date-time

False

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

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

False

The unique identifier for the allow list.

name

string

Pattern: ^.+$

MinLength: 1

MaxLength: 128

False

The custom name of the allow list.

updatedAt

string

Format: date-time

False

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

ConflictException

Provides information about an error that occurred due to a versioning conflict for a specified resource.

PropertyTypeRequiredDescription
message

string

False

The explanation of the error that occurred.

CreateAllowListRequest

Specifies the settings for an allow list. When Amazon Macie processes the request, Macie tests the list's criteria. 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
clientToken

string

True

A unique, case-sensitive token that you provide to ensure the idempotency of the request.

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 (regex) that defines a text pattern to ignore.

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.

tags

TagMap

False

A map of key-value pairs that specifies the tags to associate with the allow list.

An allow list can have a maximum of 50 tags. Each tag consists of a tag key and an associated tag value. The maximum length of a tag key is 128 characters. The maximum length of a tag value is 256 characters.

CreateAllowListResponse

Provides information about an allow list that was created 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.

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.

ListAllowListsResponse

Provides the results of a request for information about allow lists.

PropertyTypeRequiredDescription
allowLists

Array of type AllowListSummary

False

An array of objects, one for each allow list.

nextToken

string

False

The string to use in a subsequent request to get the next page of results in a paginated response. This value is null if there are no additional pages.

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.

ServiceQuotaExceededException

Provides information about an error that occurred due to one or more service quotas for an account.

PropertyTypeRequiredDescription
message

string

False

The explanation of the error that occurred.

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.

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:

ListAllowLists

CreateAllowList