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 code | Response model | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
200 | GetRevealConfigurationResponse | The request succeeded. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 | ValidationException | The request failed because the input doesn't satisfy the constraints specified by the service. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 | AccessDeniedException | The request was denied because you don't have sufficient access to the specified resource. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
429 | ThrottlingException | The request failed because you sent too many requests during a certain amount of time. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 | InternalServerException | 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 code | Response model | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
200 | UpdateRevealConfigurationResponse | The request succeeded. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 | ValidationException | The request failed because the input doesn't satisfy the constraints specified by the service. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 | AccessDeniedException | The request was denied because you don't have sufficient access to the specified resource. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
429 | ThrottlingException | The request failed because you sent too many requests during a certain amount of time. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 | InternalServerException | 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.
Property | Type | Required | Description |
---|---|---|---|
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.
Property | Type | Required | Description |
---|---|---|---|
configuration | 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 | 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.
Property | Type | Required | Description |
---|---|---|---|
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.
Property | Type | Required | Description |
---|---|---|---|
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 ( 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 |
retrievalMode | True | The access method that's used to retrieve sensitive data from affected S3 objects. Valid values are: | |
roleName | string Pattern: 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
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.
Property | Type | Required | Description |
---|---|---|---|
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:
|
status | True | The status of the configuration for the Amazon Macie account. In a
response, possible values are: ImportantIf you disable the configuration, you also permanently delete current settings that specify how to access affected S3
objects. If your current access method is |
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.
Property | Type | Required | Description |
---|---|---|---|
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.
Property | Type | Required | Description |
---|---|---|---|
retrievalMode | True | The access method to use when retrieving sensitive data from affected S3 objects. Valid values are: ImportantIf you change this value from | |
roleName | string Pattern: 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.
Property | Type | Required | Description |
---|---|---|---|
configuration | True | The AWS KMS key to use to encrypt the sensitive data, and the status of the configuration for the Amazon Macie account. | |
retrievalConfiguration | 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.
Property | Type | Required | Description |
---|---|---|---|
configuration | True | The AWS KMS key to use to encrypt the sensitive data, and the status of the configuration for the Amazon Macie account. | |
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.
Property | Type | Required | Description |
---|---|---|---|
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: