AWS IAM Access Analyzer ExecModule

Overview

The AWS IAM Access Analyzer ExecModule turns access-analysis evidence into bounded, governed workflow input. Security and cloud-platform teams can inventory analyzers, build reviewed queues of external-access and unused-access findings, inspect which resources have been analyzed, validate IAM policies before deployment, and compare a proposed policy with its current baseline.

The connector complements the general AWS IAM ExecModule. IAM manages identities and policies; Access Analyzer evaluates how policies and resource configurations translate into reachable access. This release keeps that distinction explicit: it reads analyzer state and performs AWS-hosted policy checks, but it does not create analyzers, archive findings, change IAM, or remediate resources.

Every supported operation is read-only and repeatable. Lists are bounded, provider pagination is explicit, transient reads use controlled retries, and credentials come only from a verified IntegrationAccount. Raw credentials, session tokens, endpoint overrides, unknown fields, malformed ARNs, oversized policies, and unsupported enum values are rejected before any AWS request.

Finding output is intentionally minimized. Workflows receive stable finding identity, type, status, resource identity, owner account, and timestamps. Exact finding detail exposes only the detail categories and count—not raw principals, condition maps, unused-permission payloads, or provider documents. Policy documents are sent to Access Analyzer for the selected check but are never copied into module output.

Usage

Enable an account or organization analyzer in each AWS region the workflow must inspect.
Create a least-privilege AWS identity containing only the Access Analyzer read and check actions used by the workflow.
Store its access-key pair in a ValkyrAI IntegrationAccount, verify it, and keep it in READY status.
Add AwsIamAccessAnalyzerModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
Set the exact AWS region and choose one supported operation.
For finding or resource operations, supply the exact analyzer ARN returned by list_analyzers.
Use limit for a deliberate total bound. Enable returnAll only when the downstream workflow can safely process every page up to that bound.
Preserve analyzer ARN, finding ID, finding type, resource ARN, status, and update time when deduplicating security work.

Access Analyzer is regional. An analyzer or clean finding queue in one region does not establish coverage in another. Organization analyzers also depend on the current delegated-administrator and AWS Organizations configuration.

Inputs

Input	Type	Required	Default	Description
`operation`	string	Yes	—	One supported Access Analyzer operation.
`region`	string	Yes	—	Exact AWS region such as `us-west-2`.
`analyzerType`	string	No	—	`ACCOUNT`, `ORGANIZATION`, `ACCOUNT_UNUSED_ACCESS`, or `ORGANIZATION_UNUSED_ACCESS`.
`analyzerName`	string	Analyzer detail	—	Exact analyzer name.
`analyzerArn`	string	Finding/resource operations	—	Exact Access Analyzer ARN.
`findingId`	string	Finding detail	—	Exact finding identifier.
`nextToken`	string	No	—	Opaque continuation token returned by AWS.
`limit`	integer	No	`100`	Total list bound from 1 to 1,000.
`returnAll`	boolean	No	`false`	Follow provider pages until `limit` or exhaustion.
`findingStatus`	string	No	—	`ACTIVE`, `ARCHIVED`, or `RESOLVED`.
`findingType`	string	No	—	External access, unused role, unused access key, unused password, or unused permission.
`resourceType`	string	Operation-specific	—	One supported Access Analyzer resource type.
`resourceContains`	string	No	—	Bounded substring match against the resource ARN.
`sortField`	string	No	—	`createdAt`, `updatedAt`, `resource`, `resourceType`, `status`, or `findingType`.
`sortOrder`	string	No	`DESC` with a sort field	`ASC` or `DESC`; requires `sortField`.
`resourceArn`	string	Resource detail	—	Exact analyzed resource ARN.
`policyDocument`	string	Policy checks	—	IAM JSON object, bounded to 131,072 characters.
`existingPolicyDocument`	string	No-new-access check	—	Current IAM JSON policy used as the comparison baseline.
`policyType`	string	Validation/comparison	—	Supported policy family for the selected check.
`validatePolicyResourceType`	string	No	—	Optional resource context for resource-policy validation.

Unknown or operation-inappropriate fields are rejected. The module accepts policy documents only as JSON-object strings and never returns them in output.

Outputs

Every operation returns a stable envelope:

Output	Description
`status`	`success` or `error`.
`operation`	Normalized operation name.
`attempts`	Provider calls, including pages and safe read retries.
`resultType`	Result family such as `analyzers`, `findings`, `analyzed_resources`, or `policy_findings`.
`items` / `count`	Bounded normalized list results and returned count.
`pages` / `hasMore` / `nextToken`	Pagination evidence for list operations.
`data`	One analyzer, finding, resource, or access-check result.
`requestId`	AWS request identifier when safely available.
`error`	Stable code, redacted message, HTTP status, and retryability.

Analyzer output includes ARN, name, scope, status, creation time, and last analyzed resource/time. Finding output includes stable identity, finding type, status, resource ARN/type, owner account, analysis timestamps, and whether AWS recorded an analysis error. Exact finding detail adds only the number and categories of detail records plus whether AWS has more detail pages.

Analyzed-resource detail includes public-access state, status, bounded actions and sharing paths, owner account, and timestamps. Policy-validation findings include severity family, issue code, bounded guidance, AWS documentation link, and location count. Access checks return the AWS result, bounded message, and bounded statement-level reasons.

IntegrationAccount Requirements

Use an AWS IntegrationAccount with:

status: READY
verified: true
access key ID in the account API-key field
secret access key in the protected password field

The connector never reads credentials from workflow input. It creates a regional AWS SDK client only after account verification and disables SDK-level retries so ValkyrAI can report exact attempt counts.

A deployment may need only the actions its reviewed workflows call:

access-analyzer:ListAnalyzers
access-analyzer:GetAnalyzer
access-analyzer:ListFindings
access-analyzer:GetFinding
access-analyzer:ListAnalyzedResources
access-analyzer:GetAnalyzedResource
access-analyzer:ValidatePolicy
access-analyzer:CheckNoPublicAccess
access-analyzer:CheckNoNewAccess

Do not grant analyzer lifecycle, archive-rule changes, finding updates, policy generation, resource scans, tagging, or wildcard Access Analyzer access merely to satisfy this connector.

Configuration

ExecModuleConfig supplies the IntegrationAccount and optional retry policy. All operations are reads or policy checks. They retry transient throttling, server, and network failures up to the configured maximum, bounded from one to five attempts. The default is three.

The AWS SDK retry policy is disabled inside the connector. This keeps ValkyrAI's attempts field authoritative and avoids hidden replay behavior.

Operations

Analyzer and coverage inventory

list_analyzers — list bounded analyzers in one region, optionally filtered by account/organization and external/unused-access scope.
get_analyzer — retrieve one exact analyzer's scope, health, creation time, and last-analyzed-resource evidence.
list_analyzed_resources — list bounded resource identities evaluated by one analyzer, optionally filtered by resource type.
get_analyzed_resource — retrieve one exact resource's public state, actions, sharing paths, analysis status, and timestamps.

These operations can establish which analyzers exist and which resources they have evaluated. They do not prove that every account, region, resource type, or recent configuration change is covered.

Finding queues and review

list_findings — list bounded V2 findings with optional status, finding-type, resource-type, ARN-substring, and sorting controls.
get_finding — retrieve one exact finding's normalized identity and the categories/count of AWS detail records.

External-access findings can reveal resources reachable from outside the analyzer's zone of trust. Unused-access analyzers can identify roles, access keys, passwords, and permissions that meet AWS's configured inactivity criteria. Those findings are evidence for review—not automatic proof that access is malicious, unnecessary, or safe to remove.

Policy checks before change

validate_policy — validate an identity, resource, service-control, or resource-control policy against IAM grammar and AWS best-practice checks.
check_no_public_access — check that a supported resource policy does not grant public access.
check_no_new_access — compare a proposed identity or resource policy with an existing policy and check that it adds no access.

These checks make strong pre-deployment gates, but they do not apply the policy, simulate every runtime context, replace application authorization testing, or prove least privilege by themselves. Keep change approval, deployment, and post-change verification as separate workflow steps.

Errors and Failure Modes

Code	Meaning	Retry guidance
`VALIDATION_ERROR`	A required field, region, ARN, enum, policy, or bound is invalid.	Correct input; no provider call was made.
`INTEGRATION_ACCOUNT_ERROR`	The account is missing, unverified, not `READY`, or incomplete.	Repair and verify the account.
`UNSUPPORTED_OPERATION`	The operation is outside this release.	Select one documented operation.
`AWS_ACCESS_ANALYZER_HTTP_400` / `422`	AWS rejected an input or policy check.	Correct the target or policy; inspect the request ID.
`AWS_ACCESS_ANALYZER_HTTP_403`	IAM denied the operation.	Add only the missing least-privilege action.
`AWS_ACCESS_ANALYZER_HTTP_404`	The analyzer, finding, or resource was not found.	Confirm region and exact identifier.
`AWS_ACCESS_ANALYZER_HTTP_429` / `500` / `502` / `503` / `504`	Throttling or transient provider pressure.	Bounded read retries are automatic.
`NETWORK_ERROR`	ValkyrAI could not reach Access Analyzer.	Verify connectivity and retry the read.
`EXECUTION_ERROR`	An unexpected local failure was safely contained.	Inspect server logs; secrets and policies remain redacted.

Provider exception text is never returned to workflow output. AWS request IDs are preserved when safely available for CloudTrail and support correlation.

Example

Build a bounded queue of active external-access findings:

{
  "operation": "list_findings",
  "region": "us-west-2",
  "analyzerArn": "arn:aws:access-analyzer:us-west-2:111122223333:analyzer/account-access",
  "findingStatus": "ACTIVE",
  "findingType": "EXTERNAL_ACCESS",
  "sortField": "updatedAt",
  "sortOrder": "DESC",
  "returnAll": true,
  "limit": 100
}

Expected result shape:

{
  "status": "success",
  "operation": "list_findings",
  "attempts": 1,
  "resultType": "findings",
  "items": [
    {
      "findingId": "597f3bc2-3adc-4c18-9879-5c4b23485e46",
      "findingType": "EXTERNAL_ACCESS",
      "status": "ACTIVE",
      "resourceArn": "arn:aws:s3:::customer-artifacts",
      "resourceType": "AWS::S3::Bucket",
      "resourceOwnerAccount": "111122223333"
    }
  ],
  "count": 1,
  "pages": 1,
  "hasMore": false,
  "requestId": "example-request-id"
}

Route each reviewed finding by resource owner and finding version. Use get_finding only for the selected set, and keep raw principal/condition evidence inside the authorized AWS investigation path.

Notes

Pagination: Provider tokens are opaque and can expire. returnAll follows no more than 100 pages and never returns more than 1,000 items.
Rate limits: All operations are reads/checks and retry transient failures with bounded backoff and at most five configured attempts.
API limits: Provider pages request at most 100 items. Policy documents are capped at 131,072 characters before any AWS call.
Idempotency: Every supported operation is read-only and repeatable; no analyzer, finding, IAM policy, archive rule, or resource is changed.
Regional scope: Analyzer, finding, and resource operations use one exact regional endpoint. Endpoint overrides are not accepted.
Data minimization: Raw finding principals, conditions, detail payloads, policy documents, provider payloads, and provider exception text are excluded from output.
Credential boundary: Live AWS behavior remains unverified until an authorized least-privilege non-production account and reviewed analyzer are supplied.
Deferred capabilities: Analyzer lifecycle, finding status changes, archive rules, access previews, policy generation, recommendation generation, resource scans, tags, and arbitrary access assertions are intentionally deferred.
Destructive behavior: None. This release cannot change IAM access or Access Analyzer state.
Runtime boundary: Merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsIamAccessAnalyzerModule through /v1/modules/metadata.

Overview​

Usage​

Inputs​

Outputs​

IntegrationAccount Requirements​

Configuration​

Operations​

Analyzer and coverage inventory​

Finding queues and review​

Policy checks before change​

Errors and Failure Modes​

Example​

Notes​

Related resources​