Access Analyzer

2021/04/07 - Access Analyzer - 4 new api methods

Changes  IAM Access Analyzer now analyzes your CloudTrail events to identify actions and services that have been used by an IAM entity (user or role) and generates an IAM policy that is based on that activity.

StartPolicyGeneration (new) Link ¶

Starts the policy generation request.

See also: AWS API Documentation

Request Syntax

client.start_policy_generation(
    clientToken='string',
    cloudTrailDetails={
        'accessRole': 'string',
        'endTime': datetime(2015, 1, 1),
        'startTime': datetime(2015, 1, 1),
        'trails': [
            {
                'allRegions': True|False,
                'cloudTrailArn': 'string',
                'regions': [
                    'string',
                ]
            },
        ]
    },
    policyGenerationDetails={
        'principalArn': 'string'
    }
)
type clientToken

string

param clientToken

A unique, case-sensitive identifier that you provide to ensure the idempotency of the request. Idempotency ensures that an API request completes only once. With an idempotent request, if the original request completes successfully, the subsequent retries with the same client token return the result from the original successful request and they have no additional effect.

If you do not specify a client token, one is automatically generated by the AWS SDK.

This field is autopopulated if not provided.

type cloudTrailDetails

dict

param cloudTrailDetails

A CloudTrailDetails object that contains details about a Trail that you want to analyze to generate policies.

  • accessRole (string) -- [REQUIRED]

    The ARN of the service role that Access Analyzer uses to access your CloudTrail trail and service last accessed information.

  • endTime (datetime) --

    The end of the time range for which Access Analyzer reviews your CloudTrail events. Events with a timestamp after this time are not considered to generate a policy. If this is not included in the request, the default value is the current time.

  • startTime (datetime) -- [REQUIRED]

    The start of the time range for which Access Analyzer reviews your CloudTrail events. Events with a timestamp before this time are not considered to generate a policy.

  • trails (list) -- [REQUIRED]

    A Trail object that contains settings for a trail.

    • (dict) --

      Contains details about the CloudTrail trail being analyzed to generate a policy.

      • allRegions (boolean) --

        Possible values are true or false . If set to true , Access Analyzer retrieves CloudTrail data from all regions to analyze and generate a policy.

      • cloudTrailArn (string) -- [REQUIRED]

        Specifies the ARN of the trail. The format of a trail ARN is arn:aws:cloudtrail:us-east-2:123456789012:trail/MyTrail .

      • regions (list) --

        A list of regions to get CloudTrail data from and analyze to generate a policy.

        • (string) --

type policyGenerationDetails

dict

param policyGenerationDetails

[REQUIRED]

Contains the ARN of the IAM entity (user or role) for which you are generating a policy.

  • principalArn (string) -- [REQUIRED]

    The ARN of the IAM entity (user or role) for which you are generating a policy.

rtype

dict

returns

Response Syntax

{
    'jobId': 'string'
}

Response Structure

  • (dict) --

    • jobId (string) --

      The JobId that is returned by the StartPolicyGeneration operation. The JobId can be used with GetGeneratedPolicy to retrieve the generated policies or used with CancelPolicyGeneration to cancel the policy generation request.

ListPolicyGenerations (new) Link ¶

Lists all of the policy generations requested in the last seven days.

See also: AWS API Documentation

Request Syntax

client.list_policy_generations(
    maxResults=123,
    nextToken='string',
    principalArn='string'
)
type maxResults

integer

param maxResults

The maximum number of results to return in the response.

type nextToken

string

param nextToken

A token used for pagination of results returned.

type principalArn

string

param principalArn

The ARN of the IAM entity (user or role) for which you are generating a policy. Use this with ListGeneratedPolicies to filter the results to only include results for a specific principal.

rtype

dict

returns

Response Syntax

{
    'nextToken': 'string',
    'policyGenerations': [
        {
            'completedOn': datetime(2015, 1, 1),
            'jobId': 'string',
            'principalArn': 'string',
            'startedOn': datetime(2015, 1, 1),
            'status': 'IN_PROGRESS'|'SUCCEEDED'|'FAILED'|'CANCELED'
        },
    ]
}

Response Structure

  • (dict) --

    • nextToken (string) --

      A token used for pagination of results returned.

    • policyGenerations (list) --

      A PolicyGeneration object that contains details about the generated policy.

      • (dict) --

        Contains details about the policy generation status and properties.

        • completedOn (datetime) --

          A timestamp of when the policy generation was completed.

        • jobId (string) --

          The JobId that is returned by the StartPolicyGeneration operation. The JobId can be used with GetGeneratedPolicy to retrieve the generated policies or used with CancelPolicyGeneration to cancel the policy generation request.

        • principalArn (string) --

          The ARN of the IAM entity (user or role) for which you are generating a policy.

        • startedOn (datetime) --

          A timestamp of when the policy generation started.

        • status (string) --

          The status of the policy generation request.

GetGeneratedPolicy (new) Link ¶

Retrieves the policy that was generated using StartPolicyGeneration .

See also: AWS API Documentation

Request Syntax

client.get_generated_policy(
    includeResourcePlaceholders=True|False,
    includeServiceLevelTemplate=True|False,
    jobId='string'
)
type includeResourcePlaceholders

boolean

param includeResourcePlaceholders

The level of detail that you want to generate. You can specify whether to generate policies with placeholders for resource ARNs for actions that support resource level granularity in policies.

For example, in the resource section of a policy, you can receive a placeholder such as "Resource":"arn:aws:s3:::${BucketName}" instead of "*" .

type includeServiceLevelTemplate

boolean

param includeServiceLevelTemplate

The level of detail that you want to generate. You can specify whether to generate service-level policies.

Access Analyzer uses iam:servicelastaccessed to identify services that have been used recently to create this service-level template.

type jobId

string

param jobId

[REQUIRED]

The JobId that is returned by the StartPolicyGeneration operation. The JobId can be used with GetGeneratedPolicy to retrieve the generated policies or used with CancelPolicyGeneration to cancel the policy generation request.

rtype

dict

returns

Response Syntax

{
    'generatedPolicyResult': {
        'generatedPolicies': [
            {
                'policy': 'string'
            },
        ],
        'properties': {
            'cloudTrailProperties': {
                'endTime': datetime(2015, 1, 1),
                'startTime': datetime(2015, 1, 1),
                'trailProperties': [
                    {
                        'allRegions': True|False,
                        'cloudTrailArn': 'string',
                        'regions': [
                            'string',
                        ]
                    },
                ]
            },
            'isComplete': True|False,
            'principalArn': 'string'
        }
    },
    'jobDetails': {
        'completedOn': datetime(2015, 1, 1),
        'jobError': {
            'code': 'AUTHORIZATION_ERROR'|'RESOURCE_NOT_FOUND_ERROR'|'SERVICE_QUOTA_EXCEEDED_ERROR'|'SERVICE_ERROR',
            'message': 'string'
        },
        'jobId': 'string',
        'startedOn': datetime(2015, 1, 1),
        'status': 'IN_PROGRESS'|'SUCCEEDED'|'FAILED'|'CANCELED'
    }
}

Response Structure

  • (dict) --

    • generatedPolicyResult (dict) --

      A GeneratedPolicyResult object that contains the generated policies and associated details.

      • generatedPolicies (list) --

        The text to use as the content for the new policy. The policy is created using the CreatePolicy action.

        • (dict) --

          Contains the text for the generated policy.

          • policy (string) --

            The text to use as the content for the new policy. The policy is created using the CreatePolicy action.

      • properties (dict) --

        A GeneratedPolicyProperties object that contains properties of the generated policy.

        • cloudTrailProperties (dict) --

          Lists details about the Trail used to generated policy.

          • endTime (datetime) --

            The end of the time range for which Access Analyzer reviews your CloudTrail events. Events with a timestamp after this time are not considered to generate a policy. If this is not included in the request, the default value is the current time.

          • startTime (datetime) --

            The start of the time range for which Access Analyzer reviews your CloudTrail events. Events with a timestamp before this time are not considered to generate a policy.

          • trailProperties (list) --

            A TrailProperties object that contains settings for trail properties.

            • (dict) --

              Contains details about the CloudTrail trail being analyzed to generate a policy.

              • allRegions (boolean) --

                Possible values are true or false . If set to true , Access Analyzer retrieves CloudTrail data from all regions to analyze and generate a policy.

              • cloudTrailArn (string) --

                Specifies the ARN of the trail. The format of a trail ARN is arn:aws:cloudtrail:us-east-2:123456789012:trail/MyTrail .

              • regions (list) --

                A list of regions to get CloudTrail data from and analyze to generate a policy.

                • (string) --

        • isComplete (boolean) --

          This value is set to true if the generated policy contains all possible actions for a service that Access Analyzer identified from the CloudTrail trail that you specified, and false otherwise.

        • principalArn (string) --

          The ARN of the IAM entity (user or role) for which you are generating a policy.

    • jobDetails (dict) --

      A GeneratedPolicyDetails object that contains details about the generated policy.

      • completedOn (datetime) --

        A timestamp of when the job was completed.

      • jobError (dict) --

        Contains the details about the policy generation error.

        • code (string) --

          The job error code.

        • message (string) --

          Specific information about the error. For example, which service quota was exceeded or which resource was not found.

      • jobId (string) --

        The JobId that is returned by the StartPolicyGeneration operation. The JobId can be used with GetGeneratedPolicy to retrieve the generated policies or used with CancelPolicyGeneration to cancel the policy generation request.

      • startedOn (datetime) --

        A timestamp of when the job was started.

      • status (string) --

        The status of the job request.

CancelPolicyGeneration (new) Link ¶

Cancels the requested policy generation.

See also: AWS API Documentation

Request Syntax

client.cancel_policy_generation(
    jobId='string'
)
type jobId

string

param jobId

[REQUIRED]

The JobId that is returned by the StartPolicyGeneration operation. The JobId can be used with GetGeneratedPolicy to retrieve the generated policies or used with CancelPolicyGeneration to cancel the policy generation request.

rtype

dict

returns

Response Syntax

{}

Response Structure

  • (dict) --