URI HTTP methods Schemas Properties See also

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
Name	Type	Required	Description
`findingId`	String	True	The unique identifier for the finding.

Responses
Status code	Response model	Description
`200`	`GetSensitiveDataOccurrencesResponse`	The request succeeded.
`402`	`ServiceQuotaExceededException`	The request failed because fulfilling the request would exceed one or more service quotas for your account.
`403`	`AccessDeniedException`	The request was denied because you don't have sufficient access to the specified resource.
`404`	`ResourceNotFoundException`	The request failed because the specified resource wasn't found.
`422`	`UnprocessableEntityException`	The request failed because it contains instructions that Amazon Macie can't process (Unprocessable Entity).
`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

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.

Property	Type	Required	Description
`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.

Property Type Required Description

Property	Type	Required	Description
`value`	string Format: password MinLength: 1 MaxLength: 128	True	An occurrence of the specified type of sensitive data. Each occurrence contains 1-128 characters.

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.

Property	Type	Required	Description
`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.

Property	Type	Required	Description
`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.

Property	Type	Required	Description
`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.

Property	Type	Required	Description
`*`	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.

Property	Type	Required	Description
`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.

Property	Type	Required	Description
`message`	string	False	The explanation of the error that occurred.

UnprocessableEntityException

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

Property	Type	Required	Description
`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's currently disabled. `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.