Findings - Reveal Sensitive Data Occurrences - Amazon Macie

Findings - Reveal Sensitive Data Occurrences

The Reveal Sensitive Data Occurrences resource 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. You can also use them to tailor your investigation of the affected Amazon Simple Storage Service (Amazon S3) object or bucket. You can retrieve sensitive data samples 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 particular 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.

To retrieve sensitive data samples for a finding, the finding must meet all the following criteria:

  • Include one or more occurrences objects that indicate the location of specific occurrences of sensitive data in the affected S3 object.

  • Specify the location of a valid, corresponding sensitive data discovery result in the classificationDetails.detailedResultsLocation field.

  • Specify one of the following values in the mimeType field: application/avro, application/gzip, application/json, application/parquet, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/zip, text/csv, text/plain, or text/tab-separated-values.

For additional requirements, see Retrieving sensitive data samples with findings in the Amazon Macie User Guide.

By using the Reveal Sensitive Data Occurrences resource, you can 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 for findings. 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

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

  • ACCOUNT_NOT_IN_ORGANIZATION - The affected account isn't currently part of your organization. Or the account is part of your organization but Macie isn't currently enabled for the account. You're not allowed to access the affected S3 object by using Macie.

  • INVALID_CLASSIFICATION_RESULT - There isn't a corresponding sensitive data discovery result for the finding. Or the corresponding sensitive data discovery result isn't available in the current AWS Region, is malformed or corrupted, or uses an unsupported storage format. Macie can't verify the location of the sensitive data to retrieve.

  • INVALID_RESULT_SIGNATURE - The corresponding sensitive data discovery result is stored in an S3 object that wasn't signed by Macie. Macie can't verify the integrity and authenticity of the sensitive data discovery result. Therefore, Macie can't verify the location of the sensitive data to retrieve.

  • MEMBER_ROLE_TOO_PERMISSIVE - The trust or permissions policy for the IAM role in the affected member account doesn't meet Macie requirements for restricting access to the role. Or the role's trust policy doesn't specify the correct external ID for your organization. Macie can't assume the role to retrieve the sensitive data.

  • MISSING_GET_MEMBER_PERMISSION - You're not allowed to retrieve information about the association between your account and the affected account. Macie can't determine whether you’re allowed to access the affected S3 object as the delegated Macie administrator for the affected account.

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

  • OBJECT_UNAVAILABLE - The affected S3 object isn't available. The object was renamed, moved, deleted, or changed after Macie created the finding. Or the object is encrypted with an AWS KMS key that isn’t available. For example, the key is disabled, is scheduled for deletion, or was deleted.

  • RESULT_NOT_SIGNED - The corresponding sensitive data discovery result is stored in an S3 object that hasn't been signed. Macie can't verify the integrity and authenticity of the sensitive data discovery result. Therefore, Macie can't verify the location of the sensitive data to retrieve.

  • ROLE_TOO_PERMISSIVE - Your account is configured to retrieve occurrences of sensitive data by using an IAM role whose trust or permissions policy doesn't meet Macie requirements for restricting access to the role. Macie can’t assume the role to retrieve the sensitive data.

  • 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