AWS API Changes

2023/11/16 - Amazon Macie 2 - 3 updated api methods

Changes This release adds support for configuring Macie to assume an IAM role when retrieving sample occurrences of sensitive data reported by findings.

GetRevealConfiguration (updated)

Link ¶
Changes (response)

{'retrievalConfiguration': {'externalId': 'string',
                            'retrievalMode': 'CALLER_CREDENTIALS | ASSUME_ROLE',
                            'roleName': 'string'}}

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

See also: AWS API Documentation

Request Syntax

client.get_reveal_configuration()

rtype

dict

returns

Response Syntax

{
    'configuration': {
        'kmsKeyId': 'string',
        'status': 'ENABLED'|'DISABLED'
    },
    'retrievalConfiguration': {
        'externalId': 'string',
        'retrievalMode': 'CALLER_CREDENTIALS'|'ASSUME_ROLE',
        'roleName': 'string'
    }
}

Response Structure

(dict) --

The request succeeded.
- configuration (dict) --
  
  The KMS key that's used to encrypt the sensitive data, and the status of the configuration for the Amazon Macie account.
  - kmsKeyId (string) --
    
    The Amazon Resource Name (ARN), ID, or alias of the 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 Amazon Web Services Region as the Amazon Macie account.
    
    If this value specifies an alias, it must include the following prefix: alias/. If this value specifies a key that's owned by another Amazon Web Services account, it must specify the ARN of the key or the ARN of the key's alias.
  - status (string) --
    
    The status of the configuration for the Amazon Macie account. In a request, valid values are: ENABLED, enable the configuration for the account; and, DISABLED, disable the configuration for the account. In a response, possible values are: ENABLED, the configuration is currently enabled for the account; and, DISABLED, the configuration is currently disabled for the account.
- retrievalConfiguration (dict) --
  
  The access method and settings that are used to retrieve the sensitive data.
  - externalId (string) --
    
    The external ID to specify in the trust policy for the IAM role to assume when retrieving sensitive data from affected S3 objects (roleName). The trust policy must include an sts:ExternalId condition that requires this ID.
    
    This ID is a unique alphanumeric string that Amazon Macie generates automatically after you configure it to assume a role. This value is null if the value for retrievalMode is CALLER_CREDENTIALS.
  - retrievalMode (string) --
    
    The access method that's used when retrieving sensitive data from affected S3 objects. Valid values are: ASSUME_ROLE, assume an IAM role that is in the affected Amazon Web Services account and delegates access to Amazon Macie (roleName); and, CALLER_CREDENTIALS, use the credentials of the IAM user who requests the sensitive data.
  - roleName (string) --
    
    The name of the IAM role that is in the affected Amazon Web Services 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 is CALLER_CREDENTIALS.

GetSensitiveDataOccurrencesAvailability (updated)

Link ¶
Changes (response)

{'reasons': {'ACCOUNT_NOT_IN_ORGANIZATION',
             'INVALID_RESULT_SIGNATURE',
             'MEMBER_ROLE_TOO_PERMISSIVE',
             'MISSING_GET_MEMBER_PERMISSION',
             'RESULT_NOT_SIGNED',
             'ROLE_TOO_PERMISSIVE'}}

Checks whether occurrences of sensitive data can be retrieved for a finding.

See also: AWS API Documentation

Request Syntax

client.get_sensitive_data_occurrences_availability(
    findingId='string'
)

type findingId

string

param findingId

[REQUIRED]

The unique identifier for the finding.

rtype

dict

returns

Response Syntax

{
    'code': 'AVAILABLE'|'UNAVAILABLE',
    'reasons': [
        'OBJECT_EXCEEDS_SIZE_QUOTA'|'UNSUPPORTED_OBJECT_TYPE'|'UNSUPPORTED_FINDING_TYPE'|'INVALID_CLASSIFICATION_RESULT'|'OBJECT_UNAVAILABLE'|'ACCOUNT_NOT_IN_ORGANIZATION'|'MISSING_GET_MEMBER_PERMISSION'|'ROLE_TOO_PERMISSIVE'|'MEMBER_ROLE_TOO_PERMISSIVE'|'INVALID_RESULT_SIGNATURE'|'RESULT_NOT_SIGNED',
    ]
}

Response Structure

(dict) --

The request succeeded.
- code (string) --
  
  Specifies whether occurrences of sensitive data can be retrieved for the finding. Possible values are: AVAILABLE, the sensitive data can be retrieved; and, UNAVAILABLE, the sensitive data can't be retrieved. If this value is UNAVAILABLE, the reasons array indicates why the data can't be retrieved.
- reasons (list) --
  
  Specifies why occurrences of sensitive data can't be retrieved for 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, 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 affected member 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. Or the role's trust policy doesn't specify the correct external ID. 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, or deleted. Or the object was changed after Macie created the finding.
  - 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.
  This value is null if sensitive data can be retrieved for the finding.
  - (string) --
    
    Specifies why occurrences of sensitive data can't be retrieved for a finding. Possible values are:

UpdateRevealConfiguration (updated)

Link ¶
Changes (request, response)
Request

{'retrievalConfiguration': {'retrievalMode': 'CALLER_CREDENTIALS | ASSUME_ROLE',
                            'roleName': 'string'}}

Response

{'retrievalConfiguration': {'externalId': 'string',
                            'retrievalMode': 'CALLER_CREDENTIALS | ASSUME_ROLE',
                            'roleName': 'string'}}

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

See also: AWS API Documentation

Request Syntax

client.update_reveal_configuration(
    configuration={
        'kmsKeyId': 'string',
        'status': 'ENABLED'|'DISABLED'
    },
    retrievalConfiguration={
        'retrievalMode': 'CALLER_CREDENTIALS'|'ASSUME_ROLE',
        'roleName': 'string'
    }
)

type configuration

dict

param configuration

[REQUIRED]

The KMS key to use to encrypt the sensitive data, and the status of the configuration for the Amazon Macie account.

kmsKeyId (string) --

The Amazon Resource Name (ARN), ID, or alias of the 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 Amazon Web Services Region as the Amazon Macie account.

If this value specifies an alias, it must include the following prefix: alias/. If this value specifies a key that's owned by another Amazon Web Services account, it must specify the ARN of the key or the ARN of the key's alias.
status (string) -- [REQUIRED]

The status of the configuration for the Amazon Macie account. In a request, valid values are: ENABLED, enable the configuration for the account; and, DISABLED, disable the configuration for the account. In a response, possible values are: ENABLED, the configuration is currently enabled for the account; and, DISABLED, the configuration is currently disabled for the account.

type retrievalConfiguration

dict

param retrievalConfiguration

The access method and settings to use to retrieve the sensitive data.

retrievalMode (string) -- [REQUIRED]

The access method to use when retrieving sensitive data from affected S3 objects. Valid values are: ASSUME_ROLE, assume an IAM role that is in the affected Amazon Web Services account and delegates access to Amazon Macie; and, CALLER_CREDENTIALS, use the credentials of the IAM user who requests the sensitive data. If you specify ASSUME_ROLE, also specify the name of an existing IAM role for Macie to assume (roleName).

Warning

If you change this value from ASSUME_ROLE to CALLER_CREDENTIALS for an existing configuration, Macie permanently deletes the external ID and role name currently specified for the configuration. These settings can't be recovered after they're deleted.
roleName (string) --

The name of the IAM role that is in the affected Amazon Web Services 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.

rtype

dict

returns

Response Syntax

{
    'configuration': {
        'kmsKeyId': 'string',
        'status': 'ENABLED'|'DISABLED'
    },
    'retrievalConfiguration': {
        'externalId': 'string',
        'retrievalMode': 'CALLER_CREDENTIALS'|'ASSUME_ROLE',
        'roleName': 'string'
    }
}

Response Structure

(dict) --

The request succeeded.
- configuration (dict) --
  
  The KMS key to use to encrypt the sensitive data, and the status of the configuration for the Amazon Macie account.
  - kmsKeyId (string) --
    
    The Amazon Resource Name (ARN), ID, or alias of the 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 Amazon Web Services Region as the Amazon Macie account.
    
    If this value specifies an alias, it must include the following prefix: alias/. If this value specifies a key that's owned by another Amazon Web Services account, it must specify the ARN of the key or the ARN of the key's alias.
  - status (string) --
    
    The status of the configuration for the Amazon Macie account. In a request, valid values are: ENABLED, enable the configuration for the account; and, DISABLED, disable the configuration for the account. In a response, possible values are: ENABLED, the configuration is currently enabled for the account; and, DISABLED, the configuration is currently disabled for the account.
- retrievalConfiguration (dict) --
  
  The access method and settings to use to retrieve the sensitive data.
  - externalId (string) --
    
    The external ID to specify in the trust policy for the IAM role to assume when retrieving sensitive data from affected S3 objects (roleName). The trust policy must include an sts:ExternalId condition that requires this ID.
    
    This ID is a unique alphanumeric string that Amazon Macie generates automatically after you configure it to assume a role. This value is null if the value for retrievalMode is CALLER_CREDENTIALS.
  - retrievalMode (string) --
    
    The access method that's used when retrieving sensitive data from affected S3 objects. Valid values are: ASSUME_ROLE, assume an IAM role that is in the affected Amazon Web Services account and delegates access to Amazon Macie (roleName); and, CALLER_CREDENTIALS, use the credentials of the IAM user who requests the sensitive data.
  - roleName (string) --
    
    The name of the IAM role that is in the affected Amazon Web Services 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 is CALLER_CREDENTIALS.