Findings - Reveal Sensitive Data Occurrences - Amazon Macie

Findings - Reveal Sensitive Data Occurrences

The Reveal Sensitive Data Occurrences resource for findings provides options for retrieving sample occurrences of sensitive data that Amazon Macie reported in a finding. The samples can help you verify the nature of the sensitive data that Macie found, and tailor your investigation of the 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) Region.

When you retrieve sensitive data samples, you specify the unique identifier for a particular sensitive data finding. Macie then uses location data in the corresponding sensitive data discovery result for the finding 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.

To retrieve sensitive data samples for a finding, the finding must include one or more occurrences objects that indicate the location of specific occurrences of sensitive data in the affected S3 object. In addition, the ClassificationDetails.detailedResultsLocation field of the finding must specify the location of a valid sensitive data discovery result for the finding. Also, the value for the mimeType field of the finding must be: application/avro, application/gzip, application/json, application/parquet, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/zip, text/csv, or text/plain. For additional requirements, see Investigating sensitive data with findings in the Amazon Macie User Guide.

You can use the Reveal Sensitive Data Occurrences resource to retrieve sample occurrences of sensitive data that Macie reported in a particular finding. When you use this resource, you have to specify the unique identifier for the finding that your request applies to. To find this identifier, you can use the Finding List resource.

Before you can use this resource, you have to configure and enable Macie to retrieve sensitive data samples. To do this, use the Reveal Sensitive Data Occurrences Configuration resource.

URI

/findings/findingId/reveal

HTTP methods

GET

Operation ID: GetSensitiveDataOccurrences

Retrieves occurrences of sensitive data reported by a finding.

Path parameters
NameTypeRequiredDescription
findingIdStringTrue

The unique identifier for the finding.

Responses
Status codeResponse modelDescription
200GetSensitiveDataOccurrencesResponse

The request succeeded.

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.

422UnprocessableEntityException

The request failed because it contains instructions that Amazon Macie can't process (Unprocessable Entity).

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

Response bodies

{ "sensitiveDataOccurrences": { }, "error": "string", "status": enum }
{ "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.

DetectedDataDetails

Specifies 1-10 occurrences of a specific type of sensitive data reported by a finding.

PropertyTypeRequiredDescription
value

string

Format: password

MinLength: 1

MaxLength: 128

True

An occurrence of the specified type of sensitive data. Each occurrence can contain 1-128 characters.

GetSensitiveDataOccurrencesResponse

Provides the results of a request to retrieve occurrences of sensitive data reported by a finding.

PropertyTypeRequiredDescription
error

string

False

If an error occurred when Amazon Macie attempted to retrieve occurrences of sensitive data reported by the finding, a description of the error that occurred. This value is null if the status (status) of the request is PROCESSING or SUCCESS.

sensitiveDataOccurrences

SensitiveDataOccurrences

False

A map that specifies 1-100 types of sensitive data reported by the finding and, for each type, 1-10 occurrences of sensitive data.

status

RevealRequestStatus

False

The status of the request to retrieve occurrences of sensitive data reported by the finding. Possible values are:

  • ERROR - An error occurred when Amazon Macie attempted to locate, retrieve, or encrypt the sensitive data. The error value indicates the nature of the error that occurred.

  • PROCESSING - Macie is processing the request.

  • SUCCESS - Macie successfully located, retrieved, and encrypted 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.

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.

RevealRequestStatus

The status of a request to retrieve occurrences of sensitive data reported by a finding. Possible values are:

  • SUCCESS

  • PROCESSING

  • ERROR

SensitiveDataOccurrences

Specifies a type of sensitive data reported by a finding and provides occurrences of the specified type of sensitive data.

PropertyTypeRequiredDescription

*

array

False

An array of DetectedDataDetails objects. Each object specifies 1-10 occurrences of a specified type of sensitive data.

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.

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.

UnprocessableEntityException

Provides information about an error that occurred due to an unprocessable entity.

PropertyTypeRequiredDescription
message

string

True

The type of error that occurred and prevented Amazon Macie from retrieving occurrences of sensitive data reported by the finding. Possible values are:

  • INVALID_CLASSIFICATION_RESULT - Amazon Macie can't verify the location of the sensitive data to retrieve. There isn't a corresponding sensitive data discovery result for the finding. Or the sensitive data discovery result specified by the ClassificationDetails.detailedResultsLocation field of the finding isn't available, is malformed or corrupted, or uses an unsupported storage format.

  • OBJECT_EXCEEDS_SIZE_QUOTA - The storage size of the affected S3 object exceeds the size quota for retrieving occurrences of sensitive data.

  • OBJECT_UNAVAILABLE - The affected S3 object isn't available. The object might have been renamed, moved, or deleted. Or the object was changed after Macie created the finding.

  • UNSUPPORTED_FINDING_TYPE - The specified finding isn't a sensitive data finding.

  • UNSUPPORTED_OBJECT_TYPE - The affected S3 object uses a file or storage format that Macie doesn't support for retrieving occurrences of sensitive data.

See also

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

GetSensitiveDataOccurrences