Findings - Reveal Sensitive Data Occurrences Configuration - Amazon Macie

Findings - Reveal Sensitive Data Occurrences Configuration

The Reveal Sensitive Data Occurrences Configuration resource provides access to settings for retrieving sample occurrences of sensitive data that Amazon Macie reports in findings. The samples can help you verify the nature of the sensitive data that Macie found. They can also help you tailor your investigation of an affected Amazon Simple Storage Service (Amazon S3) object or bucket. You can retrieve sensitive data samples for findings in all the AWS Regions where Macie is currently available except the Asia Pacific (Osaka) and Israel (Tel Aviv) Regions.

When you retrieve sensitive data samples, you specify the unique identifier for a sensitive data finding. Macie then uses location data in the corresponding sensitive data discovery result to locate and extract sample occurrences of sensitive data from the affected S3 object. Macie encrypts the extracted data with an AWS Key Management Service (AWS KMS) key that you specify, temporarily stores the encrypted data in a cache, and returns the data in your results. Soon after extraction and encryption, Macie permanently deletes the data from the cache unless additional retention is temporarily required to resolve an operational issue.

By using the Reveal Sensitive Data Occurrences Configuration resource, you can specify configuration settings for retrieving sensitive data samples from affected S3 objects. When you configure the settings for your Macie account, you specify how to access affected objects and which AWS KMS key to use to encrypt the samples.

To access affected S3 objects, you have two options. You can configure Macie to use AWS Identity and Access Management (IAM) user credentials or assume an IAM role:

  • Use IAM user credentials - With this option (CALLER_CREDENTIALS), each user of your account uses their individual IAM identity to locate, retrieve, encrypt, and reveal sensitive data samples for a finding.

  • Assume an IAM role - With this option (ASSUME_ROLE), you create an IAM role that delegates access to Macie. You also ensure that the trust and permissions policies for the role meet all requirements for Macie to assume the role. Macie then assumes the role when a user of your account chooses to locate, retrieve, encrypt, and reveal sensitive data samples for a finding.

To encrypt sensitive data samples, configure Macie to use an AWS KMS key that you specify. The KMS key must be a customer managed, symmetric encryption key. It must also be a single-Region key that's enabled in the same AWS Region as your Macie account.

For more information about configuration options and requirements, see Configuring Macie to retrieve sensitive data samples for findings in the Amazon Macie User Guide.

In addition to specifying configuration settings, you can use the Reveal Sensitive Data Occurrences Configuration resource to enable or disable the configuration for your Macie account. If you enable the configuration, use the Reveal Sensitive Data Occurrences resource to retrieve sensitive data samples for individual findings.

Before you enable the configuration, verify that you configured Macie to store your sensitive data discovery results in an S3 bucket. Otherwise, you won't be able to retrieve sensitive data samples for findings. To check your configuration, use the Export Configuration resource for data classification results.

URI

/reveal-configuration

HTTP methods

GET

Operation ID: GetRevealConfiguration

Retrieves the status and configuration settings for retrieving occurrences of sensitive data reported by findings.

Responses
Status codeResponse modelDescription
200GetRevealConfigurationResponse

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.

PUT

Operation ID: UpdateRevealConfiguration

Updates the status and configuration settings for retrieving occurrences of sensitive data reported by findings.

Responses
Status codeResponse modelDescription
200UpdateRevealConfigurationResponse

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.

Schemas

Request bodies

{ "configuration": { "kmsKeyId": "string", "status": enum }, "retrievalConfiguration": { "retrievalMode": enum, "roleName": "string" } }

Response bodies

{ "configuration": { "kmsKeyId": "string", "status": enum }, "retrievalConfiguration": { "externalId": "string", "retrievalMode": enum, "roleName": "string" } }
{ "configuration": { "kmsKeyId": "string", "status": enum }, "retrievalConfiguration": { "externalId": "string", "retrievalMode": enum, "roleName": "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.

GetRevealConfigurationResponse

Provides information about the configuration settings for retrieving occurrences of sensitive data reported by findings, and the status of the configuration for an Amazon Macie account.

PropertyTypeRequiredDescription
configuration

RevealConfiguration

True

The AWS KMS key that's used to encrypt the sensitive data, and the status of the configuration for the Amazon Macie account.

retrievalConfiguration

RetrievalConfiguration

False

The access method and settings that are used to retrieve the sensitive data.

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.

RetrievalConfiguration

Provides information about the access method and settings that are used to retrieve occurrences of sensitive data reported by findings.

PropertyTypeRequiredDescription
externalId

string

False

The external ID to specify in the trust policy for the IAM role to assume when retrieving sensitive data from affected S3 objects (roleName). This value is null if the value for retrievalMode is CALLER_CREDENTIALS.

This ID is a unique alphanumeric string that Amazon Macie generates automatically after you configure it to assume an IAM role. For a Macie administrator to retrieve sensitive data from an affected S3 object for a member account, the trust policy for the role in the member account must include an sts:ExternalId condition that requires this ID.

retrievalMode

RetrievalMode

True

The access method that's used to retrieve sensitive data from affected S3 objects. Valid values are: ASSUME_ROLE, assume an IAM role that is in the affected AWS account and delegates access to Amazon Macie (roleName); and, CALLER_CREDENTIALS, use the credentials of the IAM user who requests the sensitive data.

roleName

string

Pattern: ^[\w+=,.@-]*$

MinLength: 1

MaxLength: 64

False

The name of the IAM role that is in the affected AWS account and Amazon Macie is allowed to assume when retrieving sensitive data from affected S3 objects for the account. This value is null if the value for retrievalMode is CALLER_CREDENTIALS.

RetrievalMode

The access method to use when retrieving occurrences of sensitive data reported by findings. Valid values are:

  • CALLER_CREDENTIALS

  • ASSUME_ROLE

RevealConfiguration

Specifies the status of the Amazon Macie configuration for retrieving occurrences of sensitive data reported by findings, and the AWS Key Management Service (AWS KMS) key to use to encrypt sensitive data that's retrieved. When you enable the configuration for the first time, your request must specify an AWS KMS key. Otherwise, an error occurs.

PropertyTypeRequiredDescription
kmsKeyId

string

MinLength: 1

MaxLength: 2048

False

The Amazon Resource Name (ARN), ID, or alias of the AWS KMS key to use to encrypt sensitive data that's retrieved. The key must be an existing, customer managed, symmetric encryption key that's enabled in the same AWS Region as the Amazon Macie account.

If this value specifies an alias, it must include the following prefix: alias/. If this value specifies a key that's owned by another AWS account, it must specify the ARN of the key or the ARN of the key's alias.

status

RevealStatus

True

The status of the configuration for the Amazon Macie account. In a response, possible values are: ENABLED, the configuration is currently enabled for the account; and, DISABLED, the configuration is currently disabled for the account. In a request, valid values are: ENABLED, enable the configuration for the account; and, DISABLED, disable the configuration for the account.

Important

If you disable the configuration, you also permanently delete current settings that specify how to access affected S3 objects. If your current access method is ASSUME_ROLE, Macie also deletes the external ID and role name currently specified for the configuration. These settings can't be recovered after they're deleted.

RevealStatus

The status of the configuration for retrieving occurrences of sensitive data reported by findings. Valid values are:

  • ENABLED

  • DISABLED

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.

UpdateRetrievalConfiguration

Specifies the access method and settings to use when retrieving occurrences of sensitive data reported by findings. If your request specifies an AWS Identity and Access Management (IAM) role to assume, Amazon Macie verifies that the role exists and the attached policies are configured correctly. If there's an issue, Macie returns an error. For information about addressing the issue, see Configuration options for retrieving sensitive data samples in the Amazon Macie User Guide.

PropertyTypeRequiredDescription
retrievalMode

RetrievalMode

True

The access method to use when retrieving sensitive data from affected S3 objects. Valid values are: ASSUME_ROLE, assume an IAM role that is in the affected AWS account and delegates access to Amazon Macie; and, CALLER_CREDENTIALS, use the credentials of the IAM user who requests the sensitive data. If you specify ASSUME_ROLE, also specify the name of an existing IAM role for Macie to assume (roleName).

Important

If you change this value from ASSUME_ROLE to CALLER_CREDENTIALS for an existing configuration, Macie permanently deletes the external ID and role name currently specified for the configuration. These settings can't be recovered after they're deleted.

roleName

string

Pattern: ^[\w+=,.@-]*$

MinLength: 1

MaxLength: 64

False

The name of the IAM role that is in the affected AWS account and Amazon Macie is allowed to assume when retrieving sensitive data from affected S3 objects for the account. The trust and permissions policies for the role must meet all requirements for Macie to assume the role.

UpdateRevealConfigurationRequest

Specifies configuration settings for retrieving occurrences of sensitive data reported by findings, and the status of the configuration for an Amazon Macie account. If you don't specify retrievalConfiguration settings for an existing configuration, Macie sets the access method to CALLER_CREDENTIALS. If your current access method is ASSUME_ROLE, Macie also deletes the external ID and role name currently specified for the configuration. To keep these settings for an existing configuration, specify your current retrievalConfiguration settings in your request.

PropertyTypeRequiredDescription
configuration

RevealConfiguration

True

The AWS KMS key to use to encrypt the sensitive data, and the status of the configuration for the Amazon Macie account.

retrievalConfiguration

UpdateRetrievalConfiguration

False

The access method and settings to use when retrieving the sensitive data.

UpdateRevealConfigurationResponse

Provides information about updated configuration settings for retrieving occurrences of sensitive data reported by findings, and the status of the configuration for an Amazon Macie account.

PropertyTypeRequiredDescription
configuration

RevealConfiguration

True

The AWS KMS key to use to encrypt the sensitive data, and the status of the configuration for the Amazon Macie account.

retrievalConfiguration

RetrievalConfiguration

False

The access method and settings to use when retrieving the sensitive data.

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:

GetRevealConfiguration

UpdateRevealConfiguration