Obtaining Findings Generated for an Access Preview

Function

This API is used to obtain the findings generated for an access preview.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the following required identity policy-based permissions. For details about the required permissions, see Permissions Policies and Supported Actions.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
AccessAnalyzer:analyzer:listPreviewFindings	List	analyzer *	g:ResourceTag/<tag-key>	-	-

URI

POST /v5/analyzers/{analyzer_id}/access-previews/{access_preview_id}/findings

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
analyzer_id	Yes	String	Unique identifier of an analyzer Minimum: 1 Maximum: 36
access_preview_id	Yes	String	Unique identifier of an access preview. Minimum: 1 Maximum: 36

Request Parameters

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
filters	No	Array of FindingFilter objects	A filter to match the returned findings. Array Length: 1 - 20
limit	No	Integer	Maximum number of results on a page
marker	No	String	Page marker

**Table 3** FindingFilter
Parameter	Mandatory	Type	Description
criterion	Yes	Criterion object	Criteria in the filter. Only one operator is allowed.
key	Yes	String	Filter key. resource: resource URN resource_type: resource type resource_owner_account: resource owner account is_public: public access permission id: finding ID status: finding type principal_type principal_identifier change_type: finding status change existing_finding_id: ID of an existing finding existing_finding_status: status of an existing finding condition.g:PrincipalUrn: principal URN condition.g:PrincipalId: principal ID condition.g:PrincipalAccount: principal account condition.g:PrincipalOrgId: principal organization ID condition.g:PrincipalOrgPath: principal organization path condition.g:PrincipalOrgManagementAccountId: principal organization management account ID condition.g:SourceIp: source IP address condition.g:SourceVpc: source VPC condition.g: SourceVpce: source VPC endpoint finding_type: finding type

**Table 4** Criterion
Parameter	Mandatory	Type	Description
contains	No	Array of strings	Matching the "contains" operator in the filter Array Length: 1 - 20
eq	No	Array of strings	Matching the "eq" operator in the filter Array Length: 1 - 20
exists	No	Boolean	Matching the "exists" operator in the filter
neq	No	Array of strings	Matching the "neq" operator in the filter Array Length: 1 - 20

Response Parameters

Status code: 200

**Table 5** Response body parameters
Parameter	Type	Description
findings	Array of PreviewFinding objects	List of findings generated by an access preview.
page_info	PageInfo object	Information on the page

**Table 6** PreviewFinding
Parameter	Type	Description
action	Array of strings	Action that can be used by external principals.
change_type	String	Finding change. unchanged: no change new: new content changed: content updated
condition	Array of FindingCondition objects	Condition that generates findings for an access preview in the policy statement.
created_at	String	Time when the findings were generated for an access preview.
existing_finding_id	String	Unique identifier of a finding.
existing_finding_status	String	Finding status. active archived resolved
id	String	Unique identifier of a finding.
is_public	Boolean	Whether the policy that generates findings allows public access to resources.
principal	FindingPrincipal object	An external principal that accesses resources in a zone of trust.
resource	String	Unique identifier of a resource.
resource_owner_account	String	ID of the account that owns resources.
resource_type	String	Resource type. iam:agency: IAM agency iam:user: IAM user kms:cmk: DEW shared key obs:bucket: OBS bucket swr:repo: SWR image repository cbr:backup: CBR backup ims:image: IMS image
sources	Array of strings	Source of findings, indicating how to grant access that generates the findings.
status	String	Status after the change. active archived resolved

**Table 7** FindingCondition
Parameter	Type	Description
key	String	Identifier or name of a condition key.
value	String	Value of the condition key.

**Table 8** FindingPrincipal
Parameter	Type	Description
identifier	String	Identifier of a principal.
type	String	Type of a principal. all_principal: all principals account all_user_in_account: all users in an account all_agency_in_account: all agencies in an account all_identity_provider_in_account: all identity providers in an account specific_user: specific user specific_agency: specific agency specific_group: specific user group specific_identity_provider: specific identity provider

**Table 9** PageInfo
Parameter	Type	Description
current_count	Integer	Number of items on the current page
next_marker	String	If present, it indicates that the available output is more than the output contained in the current response. Use this value in the marker request parameter in a subsequent call to the operation to get the next part of the output. You should repeat this operation until the next_marker response returns null.

Example Requests

Obtaining findings generated for an access preview

POST https://{hostname}/v5/analyzers/{analyzer_id}/access-previews/{access_preview_id}/findings

{
  "filters" : [ {
    "criterion" : {
      "eq" : [ "iam:agency" ]
    },
    "key" : "resource_type"
  } ]
}

Example Responses

Status code: 200

{
  "findings" : [ {
    "action" : [ "sts::setSourceIdentity", "sts::tagSession", "sts:agencies:assume" ],
    "change_type" : "new",
    "condition" : [ {
      "key" : "g:PrincipalOrgId",
      "value" : "org_id"
    } ],
    "created_at" : "2023-09-07T07:26:23.440Z",
    "existing_finding_status" : null,
    "existing_finding_id" : null,
    "is_public" : false,
    "id" : "{finding_id}",
    "principal" : {
      "identifier" : "{domain_id}",
      "type" : "account"
    },
    "resource" : "iam::{domain_id}:agency:{agency_name}",
    "resource_owner_account" : "{domain_id}",
    "resource_type" : "iam:agency",
    "status" : "active"
  } ],
  "page_info" : {
    "current_count" : 1,
    "next_marker" : null
  }
}