2026/04/06 - Access Analyzer - 7 new 1 updated api methods
Changes Brookie helps customers preview the impact of SCPs before deployment using historical access activity. It evaluates attached policies and proposed policy updates using collected access activity through CloudTrail authorization events and reports where currently allowed access will be denied.
Retrieves the metadata, parameters, and status for a policy preview job. Use this operation to monitor job progress and retrieve the Amazon S3 location of the completed analysis report.
See also: AWS API Documentation
Request Syntax
client.get_policy_preview_job(
jobId='string'
)
string
[REQUIRED]
The unique identifier of the policy preview job to retrieve. This is the job ID returned by StartPolicyPreviewJob.
dict
Response Syntax
{
'jobId': 'string',
'jobParameters': {
'startTime': datetime(2015, 1, 1),
'endTime': datetime(2015, 1, 1),
'policyConfigurations': [
{
'jobType': 'SCP',
'targetId': 'string',
'policyDocumentsList': [
'string',
]
},
]
},
'jobDetails': {
'jobStatus': 'SUBMITTED'|'IN_PROGRESS'|'COMPLETED'|'FAILED'|'CANCELED',
'submittedAt': datetime(2015, 1, 1),
'startedAt': datetime(2015, 1, 1),
'completedAt': datetime(2015, 1, 1),
'jobError': {
'code': 'AUTHORIZATION_ERROR'|'RESOURCE_NOT_FOUND_ERROR'|'SERVICE_QUOTA_EXCEEDED_ERROR'|'SERVICE_ERROR'|'CANCELED_JOB_ERROR'|'INVALID_SERVICE_LINKED_ROLE'|'INSUFFICIENT_PERMISSIONS_ERROR'|'ORGANIZATION_ACCESS_DENIED_ERROR'|'INVALID_TARGET_ERROR'|'INVALID_POLICY_PREVIEW_CONFIGURATION'|'INVALID_ORGANIZATION_CONFIGURATION'|'S3_BUCKET_NOT_FOUND_ERROR'|'S3_BUCKET_PERMISSION_ERROR',
'message': 'string'
}
},
'outputS3Uri': 'string'
}
Response Structure
(dict) --
jobId (string) --
The unique identifier of the policy preview job.
jobParameters (dict) --
The original parameters used to create the policy preview job, including the analysis time window and policy configurations.
startTime (datetime) --
The start of the CloudTrail event analysis window.
endTime (datetime) --
The end of the CloudTrail event analysis window.
policyConfigurations (list) --
The list of policy configurations that were analyzed.
(dict) --
Specifies the configuration for a policy preview analysis, including the type of analysis, the target resource, and the policy documents to evaluate.
jobType (string) --
The type of impact analysis job. Currently only SCP (Service Control Policy) is supported.
targetId (string) --
The identifier of the target resource for the policy analysis. This can be an Amazon Web Services account ID (12-digit number), an organization root ID (format: r-[0-9a-z]{4,32}), or an organizational unit ID (format: ou-[0-9a-z]{4,32}-[a-z0-9]{8,32}).
policyDocumentsList (list) --
A list of SCP policy documents to test. Each policy document is a JSON string with a maximum length of 5,120 characters. The analysis evaluates how these policies would affect access to resources.
(string) --
jobDetails (dict) --
Details about the job execution, including current status, submission time, start time, completion time, and any errors that occurred.
jobStatus (string) --
The current status of the job. Possible values are:
SUBMITTED - The job has been submitted but not yet started.
IN_PROGRESS - The job is currently executing.
COMPLETED - The job completed successfully.
FAILED - The job failed with an error.
CANCELED - The job was canceled by the user.
submittedAt (datetime) --
The time at which the job was submitted.
startedAt (datetime) --
The time at which the job execution started. This field is not populated until the job begins processing.
completedAt (datetime) --
The time at which the job completed. This field is populated only when the job reaches a terminal state (COMPLETED, FAILED, or CANCELED).
jobError (dict) --
Detailed information about the error that caused the job to fail. This field is populated only when the job status is FAILED.
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.
outputS3Uri (string) --
The Amazon S3 URI where the analysis report is stored. The report contains metadata for CloudTrail events that would be denied by the proposed policy.
Deletes the policy preview configuration for your account. After deletion, IAM Access Analyzer will stop collecting CloudTrail authorization events for policy preview analysis.
See also: AWS API Documentation
Request Syntax
client.delete_policy_preview_configuration(
clientToken='string'
)
string
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, subsequent retries with the same client token return the result from the original successful request and have no additional effect.
This field is autopopulated if not provided.
dict
Response Syntax
{}
Response Structure
(dict) --
Creates a policy preview configuration for your account. The configuration enables IAM Access Analyzer to collect and store CloudTrail authorization events needed for policy preview analysis.
See also: AWS API Documentation
Request Syntax
client.create_policy_preview_configuration(
clientToken='string',
scope='GLOBAL'
)
string
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, subsequent retries with the same client token return the result from the original successful request and have no additional effect.
This field is autopopulated if not provided.
string
The scope of the policy preview configuration. Currently only GLOBAL is supported.
dict
Response Syntax
{
'status': 'ACTIVE'|'PENDING_CREATION'|'FAILED'
}
Response Structure
(dict) --
status (string) --
The status of the policy preview configuration after creation. The status is PENDING_CREATION until the configuration is fully provisioned and becomes ACTIVE. If provisioning fails, the status is FAILED.
Lists all policy preview jobs with optional filtering by job status or target ID. Results are paginated for efficient retrieval of large result sets.
See also: AWS API Documentation
Request Syntax
client.list_policy_preview_jobs(
filters={
'string': 'string'
},
maxResults=123,
nextToken='string'
)
dict
Optional filter criteria to narrow the list of returned jobs. You can filter by job status or target ID. Maximum of one filter can be specified.
(string) --
The name of the filter to apply when listing policy preview jobs. Valid values are jobStatus to filter by job status, or targetId to filter by the target resource ID.
(string) --
integer
The maximum number of results to return in a single page. Minimum value is 1.
string
A token used for pagination of results. Use the token returned in the previous response to retrieve the next page of results.
dict
Response Syntax
{
'analysisReports': [
{
'jobId': 'string',
'status': 'SUBMITTED'|'IN_PROGRESS'|'COMPLETED'|'FAILED'|'CANCELED',
'submittedAt': datetime(2015, 1, 1),
'startedAt': datetime(2015, 1, 1),
'completedAt': datetime(2015, 1, 1),
'outputS3Uri': 'string'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
analysisReports (list) --
A list of policy preview job summaries that match the specified filter criteria.
(dict) --
Contains summary information about a policy preview job.
jobId (string) --
The unique identifier of the policy preview job.
status (string) --
The current status of the job.
submittedAt (datetime) --
The time at which the job was submitted.
startedAt (datetime) --
The time at which the job execution started.
completedAt (datetime) --
The time at which the job completed.
outputS3Uri (string) --
The Amazon S3 URI where the analysis report is stored.
nextToken (string) --
A token used for pagination. If present, indicates there are more results available. Pass this token to the next request to retrieve the next page.
Creates a policy preview analysis job to evaluate the impact of Service Control Policies (SCPs) before deployment. The analysis uses historical CloudTrail authorization events to identify potential access denials, helping you prevent service disruptions.
The job analyzes CloudTrail events within a specified time window and generates a report identifying which events would be denied by the proposed policy. The report is stored in the specified Amazon S3 location.
See also: AWS API Documentation
Request Syntax
client.start_policy_preview_job(
policyConfigurations=[
{
'jobType': 'SCP',
'targetId': 'string',
'policyDocumentsList': [
'string',
]
},
],
startTime=datetime(2015, 1, 1),
endTime=datetime(2015, 1, 1),
outputS3Uri='string',
clientToken='string'
)
list
[REQUIRED]
A list of policy configurations to analyze. Currently limited to one configuration per request. Each configuration specifies the job type, target ID, and policy documents to test.
(dict) --
Specifies the configuration for a policy preview analysis, including the type of analysis, the target resource, and the policy documents to evaluate.
jobType (string) -- [REQUIRED]
The type of impact analysis job. Currently only SCP (Service Control Policy) is supported.
targetId (string) -- [REQUIRED]
The identifier of the target resource for the policy analysis. This can be an Amazon Web Services account ID (12-digit number), an organization root ID (format: r-[0-9a-z]{4,32}), or an organizational unit ID (format: ou-[0-9a-z]{4,32}-[a-z0-9]{8,32}).
policyDocumentsList (list) -- [REQUIRED]
A list of SCP policy documents to test. Each policy document is a JSON string with a maximum length of 5,120 characters. The analysis evaluates how these policies would affect access to resources.
(string) --
datetime
[REQUIRED]
The start of the CloudTrail event analysis window. The analysis will evaluate events from this time forward.
datetime
The end of the analysis window. If not specified, defaults to the time of the request. The analysis will evaluate CloudTrail events up to this time.
string
[REQUIRED]
The Amazon S3 URI where the completed analysis report will be stored. The Amazon S3 bucket must grant access to the IAM Access Analyzer service principal in its resource policy. The report will be stored at the path: outputS3Uri/jobId/timestamp/.
string
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, subsequent retries with the same client token return the result from the original successful request and have no additional effect.
This field is autopopulated if not provided.
dict
Response Syntax
{
'jobId': 'string'
}
Response Structure
(dict) --
jobId (string) --
The unique identifier for the created policy preview job. Use this ID with GetPolicyPreviewJob to retrieve job status and details, or with CancelPolicyPreviewJob to cancel the job.
Retrieves the policy preview configuration for your account.
See also: AWS API Documentation
Request Syntax
client.get_policy_preview_configuration()
dict
Response Syntax
{
'policyPreviewConfigurations': [
{
'scope': 'GLOBAL',
'status': 'ACTIVE'|'PENDING_CREATION'|'FAILED',
'createdAt': datetime(2015, 1, 1),
'updatedAt': datetime(2015, 1, 1)
},
]
}
Response Structure
(dict) --
policyPreviewConfigurations (list) --
A list of policy preview configurations for the account.
(dict) --
Contains the configuration details for policy preview, including the scope, status, and timestamps.
scope (string) --
The scope of the policy preview configuration. Currently only GLOBAL is supported.
status (string) --
The status of the policy preview configuration. A value of ACTIVE indicates the configuration is enabled and CloudTrail authorization events are being collected.
createdAt (datetime) --
The time at which the policy preview configuration was created.
updatedAt (datetime) --
The time at which the policy preview configuration was last updated.
Cancels an in-progress policy preview job. Jobs that are already completed, failed, or canceled cannot be canceled.
See also: AWS API Documentation
Request Syntax
client.cancel_policy_preview_job(
jobId='string'
)
string
[REQUIRED]
The unique identifier of the policy preview job to cancel.
dict
Response Syntax
{}
Response Structure
(dict) --
{'jobDetails': {'jobError': {'code': {'CANCELED_JOB_ERROR',
'INSUFFICIENT_PERMISSIONS_ERROR',
'INVALID_ORGANIZATION_CONFIGURATION',
'INVALID_POLICY_PREVIEW_CONFIGURATION',
'INVALID_SERVICE_LINKED_ROLE',
'INVALID_TARGET_ERROR',
'ORGANIZATION_ACCESS_DENIED_ERROR',
'S3_BUCKET_NOT_FOUND_ERROR',
'S3_BUCKET_PERMISSION_ERROR'}}}}
Retrieves the policy that was generated using StartPolicyGeneration.
See also: AWS API Documentation
Request Syntax
client.get_generated_policy(
jobId='string',
includeResourcePlaceholders=True|False,
includeServiceLevelTemplate=True|False
)
string
[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.
boolean
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 "*".
boolean
The level of detail that you want to generate. You can specify whether to generate service-level policies.
IAM Access Analyzer uses iam:servicelastaccessed to identify services that have been used recently to create this service-level template.
dict
Response Syntax
{
'jobDetails': {
'jobId': 'string',
'status': 'IN_PROGRESS'|'SUCCEEDED'|'FAILED'|'CANCELED',
'startedOn': datetime(2015, 1, 1),
'completedOn': datetime(2015, 1, 1),
'jobError': {
'code': 'AUTHORIZATION_ERROR'|'RESOURCE_NOT_FOUND_ERROR'|'SERVICE_QUOTA_EXCEEDED_ERROR'|'SERVICE_ERROR'|'CANCELED_JOB_ERROR'|'INVALID_SERVICE_LINKED_ROLE'|'INSUFFICIENT_PERMISSIONS_ERROR'|'ORGANIZATION_ACCESS_DENIED_ERROR'|'INVALID_TARGET_ERROR'|'INVALID_POLICY_PREVIEW_CONFIGURATION'|'INVALID_ORGANIZATION_CONFIGURATION'|'S3_BUCKET_NOT_FOUND_ERROR'|'S3_BUCKET_PERMISSION_ERROR',
'message': 'string'
}
},
'generatedPolicyResult': {
'properties': {
'isComplete': True|False,
'principalArn': 'string',
'cloudTrailProperties': {
'trailProperties': [
{
'cloudTrailArn': 'string',
'regions': [
'string',
],
'allRegions': True|False
},
],
'startTime': datetime(2015, 1, 1),
'endTime': datetime(2015, 1, 1)
}
},
'generatedPolicies': [
{
'policy': 'string'
},
]
}
}
Response Structure
(dict) --
jobDetails (dict) --
A GeneratedPolicyDetails object that contains details about the generated policy.
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.
status (string) --
The status of the job request.
startedOn (datetime) --
A timestamp of when the job was started.
completedOn (datetime) --
A timestamp of when the job was completed.
jobError (dict) --
The job error for the policy generation request.
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.
generatedPolicyResult (dict) --
A GeneratedPolicyResult object that contains the generated policies and associated details.
properties (dict) --
A GeneratedPolicyProperties object that contains properties of the generated policy.
isComplete (boolean) --
This value is set to true if the generated policy contains all possible actions for a service that IAM 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.
cloudTrailProperties (dict) --
Lists details about the Trail used to generated 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.
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) --
allRegions (boolean) --
Possible values are true or false. If set to true, IAM Access Analyzer retrieves CloudTrail data from all regions to analyze and generate a policy.
startTime (datetime) --
The start of the time range for which IAM Access Analyzer reviews your CloudTrail events. Events with a timestamp before this time are not considered to generate a policy.
endTime (datetime) --
The end of the time range for which IAM 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.
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.