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:

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 Amazon Macie to retrieve and reveal sensitive data samples with 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.

PUT

Operation ID: UpdateRevealConfiguration

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

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.

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.

InternalServerException

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

RetrievalConfiguration

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

RetrievalMode

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

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.

RevealStatus

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

ThrottlingException

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

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 and requirements for retrieving sensitive data samples in the Amazon Macie User Guide.

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.

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.

ValidationException

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

See also

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

GetRevealConfiguration

UpdateRevealConfiguration