2021/03/10 - Access Analyzer - 4 new api methods
Changes This release adds support to preview IAM Access Analyzer findings for a resource before deploying resource permission changes.
Retrieves a list of access preview findings generated by the specified access preview.
See also: AWS API Documentation
Request Syntax
client.list_access_preview_findings(
accessPreviewId='string',
analyzerArn='string',
filter={
'string': {
'contains': [
'string',
],
'eq': [
'string',
],
'exists': True|False,
'neq': [
'string',
]
}
},
maxResults=123,
nextToken='string'
)
string
[REQUIRED]
The unique ID for the access preview.
string
[REQUIRED]
The ARN of the analyzer used to generate the access.
dict
Criteria to filter the returned findings.
(string) --
(dict) --
The criteria to use in the filter that defines the archive rule.
contains (list) --
A "contains" operator to match for the filter used to create the rule.
(string) --
eq (list) --
An "equals" operator to match for the filter used to create the rule.
(string) --
exists (boolean) --
An "exists" operator to match for the filter used to create the rule.
neq (list) --
A "not equals" operator to match for the filter used to create the rule.
(string) --
integer
The maximum number of results to return in the response.
string
A token used for pagination of results returned.
dict
Response Syntax
{
'findings': [
{
'action': [
'string',
],
'changeType': 'CHANGED'|'NEW'|'UNCHANGED',
'condition': {
'string': 'string'
},
'createdAt': datetime(2015, 1, 1),
'error': 'string',
'existingFindingId': 'string',
'existingFindingStatus': 'ACTIVE'|'ARCHIVED'|'RESOLVED',
'id': 'string',
'isPublic': True|False,
'principal': {
'string': 'string'
},
'resource': 'string',
'resourceOwnerAccount': 'string',
'resourceType': 'AWS::S3::Bucket'|'AWS::IAM::Role'|'AWS::SQS::Queue'|'AWS::Lambda::Function'|'AWS::Lambda::LayerVersion'|'AWS::KMS::Key'|'AWS::SecretsManager::Secret',
'sources': [
{
'detail': {
'accessPointArn': 'string'
},
'type': 'POLICY'|'BUCKET_ACL'|'S3_ACCESS_POINT'
},
],
'status': 'ACTIVE'|'ARCHIVED'|'RESOLVED'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
findings (list) --
A list of access preview findings that match the specified filter criteria.
(dict) --
An access preview finding generated by the access preview.
action (list) --
The action in the analyzed policy statement that an external principal has permission to perform.
(string) --
changeType (string) --
Provides context on how the access preview finding compares to existing access identified in Access Analyzer.
New - The finding is for newly-introduced access.
Unchanged - The preview finding is an existing finding that would remain unchanged.
Changed - The preview finding is an existing finding with a change in status.
For example, a Changed finding with preview status Resolved and existing status Active indicates the existing Active finding would become Resolved as a result of the proposed permissions change.
condition (dict) --
The condition in the analyzed policy statement that resulted in a finding.
(string) --
(string) --
createdAt (datetime) --
The time at which the access preview finding was created.
error (string) --
An error.
existingFindingId (string) --
The existing ID of the finding in Access Analyzer, provided only for existing findings.
existingFindingStatus (string) --
The existing status of the finding, provided only for existing findings.
id (string) --
The ID of the access preview finding. This ID uniquely identifies the element in the list of access preview findings and is not related to the finding ID in Access Analyzer.
isPublic (boolean) --
Indicates whether the policy that generated the finding allows public access to the resource.
principal (dict) --
The external principal that has access to a resource within the zone of trust.
(string) --
(string) --
resource (string) --
The resource that an external principal has access to. This is the resource associated with the access preview.
resourceOwnerAccount (string) --
The AWS account ID that owns the resource. For most AWS resources, the owning account is the account in which the resource was created.
resourceType (string) --
The type of the resource that can be accessed in the finding.
sources (list) --
The sources of the finding. This indicates how the access that generated the finding is granted. It is populated for Amazon S3 bucket findings.
(dict) --
The source of the finding. This indicates how the access that generated the finding is granted. It is populated for Amazon S3 bucket findings.
detail (dict) --
Includes details about how the access that generated the finding is granted. This is populated for Amazon S3 bucket findings.
accessPointArn (string) --
The ARN of the access point that generated the finding.
type (string) --
Indicates the type of access that generated the finding.
status (string) --
The preview status of the finding. This is what the status of the finding would be after permissions deployment. For example, a Changed finding with preview status Resolved and existing status Active indicates the existing Active finding would become Resolved as a result of the proposed permissions change.
nextToken (string) --
A token used for pagination of results returned.
Creates an access preview that allows you to preview Access Analyzer findings for your resource before deploying resource permissions.
See also: AWS API Documentation
Request Syntax
client.create_access_preview(
analyzerArn='string',
clientToken='string',
configurations={
'string': {
'iamRole': {
'trustPolicy': 'string'
},
'kmsKey': {
'grants': [
{
'constraints': {
'encryptionContextEquals': {
'string': 'string'
},
'encryptionContextSubset': {
'string': 'string'
}
},
'granteePrincipal': 'string',
'issuingAccount': 'string',
'operations': [
'CreateGrant'|'Decrypt'|'DescribeKey'|'Encrypt'|'GenerateDataKey'|'GenerateDataKeyPair'|'GenerateDataKeyPairWithoutPlaintext'|'GenerateDataKeyWithoutPlaintext'|'GetPublicKey'|'ReEncryptFrom'|'ReEncryptTo'|'RetireGrant'|'Sign'|'Verify',
],
'retiringPrincipal': 'string'
},
],
'keyPolicies': {
'string': 'string'
}
},
's3Bucket': {
'accessPoints': {
'string': {
'accessPointPolicy': 'string',
'networkOrigin': {
'internetConfiguration': {}
,
'vpcConfiguration': {
'vpcId': 'string'
}
},
'publicAccessBlock': {
'ignorePublicAcls': True|False,
'restrictPublicBuckets': True|False
}
}
},
'bucketAclGrants': [
{
'grantee': {
'id': 'string',
'uri': 'string'
},
'permission': 'READ'|'WRITE'|'READ_ACP'|'WRITE_ACP'|'FULL_CONTROL'
},
],
'bucketPolicy': 'string',
'bucketPublicAccessBlock': {
'ignorePublicAcls': True|False,
'restrictPublicBuckets': True|False
}
},
'secretsManagerSecret': {
'kmsKeyId': 'string',
'secretPolicy': 'string'
},
'sqsQueue': {
'queuePolicy': 'string'
}
}
}
)
string
[REQUIRED]
The ARN of the account analyzer used to generate the access preview. You can only create an access preview for analyzers with an Account type and Active status.
string
A client token.
This field is autopopulated if not provided.
dict
[REQUIRED]
Access control configuration for your resource that is used to generate the access preview. The access preview includes findings for external access allowed to the resource with the proposed access control configuration. The configuration must contain exactly one element.
(string) --
(dict) --
Access control configuration structures for your resource. You specify the configuration as a type-value pair. You can specify only one type of access control configuration.
Note
This is a Tagged Union structure. Only one of the following top level keys can be set: iamRole, kmsKey, s3Bucket, secretsManagerSecret, sqsQueue.
iamRole (dict) --
The access control configuration is for an IAM role.
trustPolicy (string) --
The proposed trust policy for the IAM role.
kmsKey (dict) --
The access control configuration is for a KMS key.
grants (list) --
A list of proposed grant configurations for the KMS key. If the proposed grant configuration is for an existing key, the access preview uses the proposed list of grant configurations in place of the existing grants. Otherwise, the access preview uses the existing grants for the key.
(dict) --
A proposed grant configuration for a KMS key. For more information, see CreateGrant.
constraints (dict) --
Use this structure to propose allowing cryptographic operations in the grant only when the operation request includes the specified encryption context.
encryptionContextEquals (dict) --
A list of key-value pairs that must match the encryption context in the cryptographic operation request. The grant allows the operation only when the encryption context in the request is the same as the encryption context specified in this constraint.
(string) --
(string) --
encryptionContextSubset (dict) --
A list of key-value pairs that must be included in the encryption context of the cryptographic operation request. The grant allows the cryptographic operation only when the encryption context in the request includes the key-value pairs specified in this constraint, although it can include additional key-value pairs.
(string) --
(string) --
granteePrincipal (string) -- [REQUIRED]
The principal that is given permission to perform the operations that the grant permits.
issuingAccount (string) -- [REQUIRED]
The AWS account under which the grant was issued. The account is used to propose KMS grants issued by accounts other than the owner of the key.
operations (list) -- [REQUIRED]
A list of operations that the grant permits.
(string) --
retiringPrincipal (string) --
The principal that is given permission to retire the grant by using RetireGrant operation.
keyPolicies (dict) --
Resource policy configuration for the KMS key. The only valid value for the name of the key policy is default . For more information, see Default key policy.
(string) --
(string) --
s3Bucket (dict) --
The access control configuration is for an Amazon S3 Bucket.
accessPoints (dict) --
The configuration of Amazon S3 access points for the bucket.
(string) --
(dict) --
The configuration for an Amazon S3 access point for the bucket. You can propose up to 10 access points per bucket. If the proposed Amazon S3 access point configuration is for an existing bucket, the access preview uses the proposed access point configuration in place of the existing access points. To propose an access point without a policy, you can provide an empty string as the access point policy. For more information, see Creating access points. For more information about access point policy limits, see Access points restrictions and limitations.
accessPointPolicy (string) --
The access point policy.
networkOrigin (dict) --
The proposed Internet and VpcConfiguration to apply to this Amazon S3 access point. If the access preview is for a new resource and neither is specified, the access preview uses Internet for the network origin. If the access preview is for an existing resource and neither is specified, the access preview uses the exiting network origin.
Note
This is a Tagged Union structure. Only one of the following top level keys can be set: internetConfiguration, vpcConfiguration.
internetConfiguration (dict) --
The configuration for the Amazon S3 access point with an Internet origin.
vpcConfiguration (dict) --
The proposed virtual private cloud (VPC) configuration for the Amazon S3 access point. For more information, see VpcConfiguration.
vpcId (string) -- [REQUIRED]
If this field is specified, this access point will only allow connections from the specified VPC ID.
publicAccessBlock (dict) --
The proposed S3PublicAccessBlock configuration to apply to this Amazon S3 Access Point.
ignorePublicAcls (boolean) -- [REQUIRED]
Specifies whether Amazon S3 should ignore public ACLs for this bucket and objects in this bucket.
restrictPublicBuckets (boolean) -- [REQUIRED]
Specifies whether Amazon S3 should restrict public bucket policies for this bucket.
bucketAclGrants (list) --
The proposed list of ACL grants for the Amazon S3 bucket. You can propose up to 100 ACL grants per bucket. If the proposed grant configuration is for an existing bucket, the access preview uses the proposed list of grant configurations in place of the existing grants. Otherwise, the access preview uses the existing grants for the bucket.
(dict) --
A proposed access control list grant configuration for an Amazon S3 bucket. For more information, see How to Specify an ACL.
grantee (dict) -- [REQUIRED]
The grantee to whom you’re assigning access rights.
Note
This is a Tagged Union structure. Only one of the following top level keys can be set: id, uri.
id (string) --
The value specified is the canonical user ID of an AWS account.
uri (string) --
Used for granting permissions to a predefined group.
permission (string) -- [REQUIRED]
The permissions being granted.
bucketPolicy (string) --
The proposed bucket policy for the Amazon S3 bucket.
bucketPublicAccessBlock (dict) --
The proposed block public access configuration for the Amazon S3 bucket.
ignorePublicAcls (boolean) -- [REQUIRED]
Specifies whether Amazon S3 should ignore public ACLs for this bucket and objects in this bucket.
restrictPublicBuckets (boolean) -- [REQUIRED]
Specifies whether Amazon S3 should restrict public bucket policies for this bucket.
secretsManagerSecret (dict) --
The access control configuration is for a Secrets Manager secret.
kmsKeyId (string) --
The proposed ARN, key ID, or alias of the AWS KMS customer master key (CMK).
secretPolicy (string) --
The proposed resource policy defining who can access or manage the secret.
sqsQueue (dict) --
The access control configuration is for an SQS queue.
queuePolicy (string) --
The proposed resource policy for the SQS queue.
dict
Response Syntax
{
'id': 'string'
}
Response Structure
(dict) --
id (string) --
The unique ID for the access preview.
Retrieves information about an access preview for the specified analyzer.
See also: AWS API Documentation
Request Syntax
client.get_access_preview(
accessPreviewId='string',
analyzerArn='string'
)
string
[REQUIRED]
The unique ID for the access preview.
string
[REQUIRED]
The ARN of the analyzer used to generate the access preview.
dict
Response Syntax
{
'accessPreview': {
'analyzerArn': 'string',
'configurations': {
'string': {
'iamRole': {
'trustPolicy': 'string'
},
'kmsKey': {
'grants': [
{
'constraints': {
'encryptionContextEquals': {
'string': 'string'
},
'encryptionContextSubset': {
'string': 'string'
}
},
'granteePrincipal': 'string',
'issuingAccount': 'string',
'operations': [
'CreateGrant'|'Decrypt'|'DescribeKey'|'Encrypt'|'GenerateDataKey'|'GenerateDataKeyPair'|'GenerateDataKeyPairWithoutPlaintext'|'GenerateDataKeyWithoutPlaintext'|'GetPublicKey'|'ReEncryptFrom'|'ReEncryptTo'|'RetireGrant'|'Sign'|'Verify',
],
'retiringPrincipal': 'string'
},
],
'keyPolicies': {
'string': 'string'
}
},
's3Bucket': {
'accessPoints': {
'string': {
'accessPointPolicy': 'string',
'networkOrigin': {
'internetConfiguration': {},
'vpcConfiguration': {
'vpcId': 'string'
}
},
'publicAccessBlock': {
'ignorePublicAcls': True|False,
'restrictPublicBuckets': True|False
}
}
},
'bucketAclGrants': [
{
'grantee': {
'id': 'string',
'uri': 'string'
},
'permission': 'READ'|'WRITE'|'READ_ACP'|'WRITE_ACP'|'FULL_CONTROL'
},
],
'bucketPolicy': 'string',
'bucketPublicAccessBlock': {
'ignorePublicAcls': True|False,
'restrictPublicBuckets': True|False
}
},
'secretsManagerSecret': {
'kmsKeyId': 'string',
'secretPolicy': 'string'
},
'sqsQueue': {
'queuePolicy': 'string'
}
}
},
'createdAt': datetime(2015, 1, 1),
'id': 'string',
'status': 'COMPLETED'|'CREATING'|'FAILED',
'statusReason': {
'code': 'INTERNAL_ERROR'|'INVALID_CONFIGURATION'
}
}
}
Response Structure
(dict) --
accessPreview (dict) --
An object that contains information about the access preview.
analyzerArn (string) --
The ARN of the analyzer used to generate the access preview.
configurations (dict) --
A map of resource ARNs for the proposed resource configuration.
(string) --
(dict) --
Access control configuration structures for your resource. You specify the configuration as a type-value pair. You can specify only one type of access control configuration.
Note
This is a Tagged Union structure. Only one of the following top level keys will be set: iamRole, kmsKey, s3Bucket, secretsManagerSecret, sqsQueue. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
iamRole (dict) --
The access control configuration is for an IAM role.
trustPolicy (string) --
The proposed trust policy for the IAM role.
kmsKey (dict) --
The access control configuration is for a KMS key.
grants (list) --
A list of proposed grant configurations for the KMS key. If the proposed grant configuration is for an existing key, the access preview uses the proposed list of grant configurations in place of the existing grants. Otherwise, the access preview uses the existing grants for the key.
(dict) --
A proposed grant configuration for a KMS key. For more information, see CreateGrant.
constraints (dict) --
Use this structure to propose allowing cryptographic operations in the grant only when the operation request includes the specified encryption context.
encryptionContextEquals (dict) --
A list of key-value pairs that must match the encryption context in the cryptographic operation request. The grant allows the operation only when the encryption context in the request is the same as the encryption context specified in this constraint.
(string) --
(string) --
encryptionContextSubset (dict) --
A list of key-value pairs that must be included in the encryption context of the cryptographic operation request. The grant allows the cryptographic operation only when the encryption context in the request includes the key-value pairs specified in this constraint, although it can include additional key-value pairs.
(string) --
(string) --
granteePrincipal (string) --
The principal that is given permission to perform the operations that the grant permits.
issuingAccount (string) --
The AWS account under which the grant was issued. The account is used to propose KMS grants issued by accounts other than the owner of the key.
operations (list) --
A list of operations that the grant permits.
(string) --
retiringPrincipal (string) --
The principal that is given permission to retire the grant by using RetireGrant operation.
keyPolicies (dict) --
Resource policy configuration for the KMS key. The only valid value for the name of the key policy is default . For more information, see Default key policy.
(string) --
(string) --
s3Bucket (dict) --
The access control configuration is for an Amazon S3 Bucket.
accessPoints (dict) --
The configuration of Amazon S3 access points for the bucket.
(string) --
(dict) --
The configuration for an Amazon S3 access point for the bucket. You can propose up to 10 access points per bucket. If the proposed Amazon S3 access point configuration is for an existing bucket, the access preview uses the proposed access point configuration in place of the existing access points. To propose an access point without a policy, you can provide an empty string as the access point policy. For more information, see Creating access points. For more information about access point policy limits, see Access points restrictions and limitations.
accessPointPolicy (string) --
The access point policy.
networkOrigin (dict) --
The proposed Internet and VpcConfiguration to apply to this Amazon S3 access point. If the access preview is for a new resource and neither is specified, the access preview uses Internet for the network origin. If the access preview is for an existing resource and neither is specified, the access preview uses the exiting network origin.
Note
This is a Tagged Union structure. Only one of the following top level keys will be set: internetConfiguration, vpcConfiguration. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
internetConfiguration (dict) --
The configuration for the Amazon S3 access point with an Internet origin.
vpcConfiguration (dict) --
The proposed virtual private cloud (VPC) configuration for the Amazon S3 access point. For more information, see VpcConfiguration.
vpcId (string) --
If this field is specified, this access point will only allow connections from the specified VPC ID.
publicAccessBlock (dict) --
The proposed S3PublicAccessBlock configuration to apply to this Amazon S3 Access Point.
ignorePublicAcls (boolean) --
Specifies whether Amazon S3 should ignore public ACLs for this bucket and objects in this bucket.
restrictPublicBuckets (boolean) --
Specifies whether Amazon S3 should restrict public bucket policies for this bucket.
bucketAclGrants (list) --
The proposed list of ACL grants for the Amazon S3 bucket. You can propose up to 100 ACL grants per bucket. If the proposed grant configuration is for an existing bucket, the access preview uses the proposed list of grant configurations in place of the existing grants. Otherwise, the access preview uses the existing grants for the bucket.
(dict) --
A proposed access control list grant configuration for an Amazon S3 bucket. For more information, see How to Specify an ACL.
grantee (dict) --
The grantee to whom you’re assigning access rights.
Note
This is a Tagged Union structure. Only one of the following top level keys will be set: id, uri. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
id (string) --
The value specified is the canonical user ID of an AWS account.
uri (string) --
Used for granting permissions to a predefined group.
permission (string) --
The permissions being granted.
bucketPolicy (string) --
The proposed bucket policy for the Amazon S3 bucket.
bucketPublicAccessBlock (dict) --
The proposed block public access configuration for the Amazon S3 bucket.
ignorePublicAcls (boolean) --
Specifies whether Amazon S3 should ignore public ACLs for this bucket and objects in this bucket.
restrictPublicBuckets (boolean) --
Specifies whether Amazon S3 should restrict public bucket policies for this bucket.
secretsManagerSecret (dict) --
The access control configuration is for a Secrets Manager secret.
kmsKeyId (string) --
The proposed ARN, key ID, or alias of the AWS KMS customer master key (CMK).
secretPolicy (string) --
The proposed resource policy defining who can access or manage the secret.
sqsQueue (dict) --
The access control configuration is for an SQS queue.
queuePolicy (string) --
The proposed resource policy for the SQS queue.
createdAt (datetime) --
The time at which the access preview was created.
id (string) --
The unique ID for the access preview.
status (string) --
The status of the access preview.
Creating - The access preview creation is in progress.
Completed - The access preview is complete. You can preview findings for external access to the resource.
Failed - The access preview creation has failed.
statusReason (dict) --
Provides more details about the current status of the access preview.
For example, if the creation of the access preview fails, a Failed status is returned. This failure can be due to an internal issue with the analysis or due to an invalid resource configuration.
code (string) --
The reason code for the current status of the access preview.
Retrieves a list of access previews for the specified analyzer.
See also: AWS API Documentation
Request Syntax
client.list_access_previews(
analyzerArn='string',
maxResults=123,
nextToken='string'
)
string
[REQUIRED]
The ARN of the analyzer used to generate the access preview.
integer
The maximum number of results to return in the response.
string
A token used for pagination of results returned.
dict
Response Syntax
{
'accessPreviews': [
{
'analyzerArn': 'string',
'createdAt': datetime(2015, 1, 1),
'id': 'string',
'status': 'COMPLETED'|'CREATING'|'FAILED',
'statusReason': {
'code': 'INTERNAL_ERROR'|'INVALID_CONFIGURATION'
}
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
accessPreviews (list) --
A list of access previews retrieved for the analyzer.
(dict) --
Contains a summary of information about an access preview.
analyzerArn (string) --
The ARN of the analyzer used to generate the access preview.
createdAt (datetime) --
The time at which the access preview was created.
id (string) --
The unique ID for the access preview.
status (string) --
The status of the access preview.
Creating - The access preview creation is in progress.
Completed - The access preview is complete and previews the findings for external access to the resource.
Failed - The access preview creation has failed.
statusReason (dict) --
Provides more details about the current status of the access preview. For example, if the creation of the access preview fails, a Failed status is returned. This failure can be due to an internal issue with the analysis or due to an invalid proposed resource configuration.
code (string) --
The reason code for the current status of the access preview.
nextToken (string) --
A token used for pagination of results returned.