IAM Issues

Guardian Pro connects to your AWS accounts through cross-account IAM roles. This page helps you diagnose and resolve issues related to role deployment, permission errors, and cross-account access failures.

Role Deployment Failures

CloudFormation Stack Failed to Create

Symptoms: The CloudFormation stack deployment fails during onboarding or when adding a new account.

Troubleshooting Steps:

1. Check CloudFormation Events

1. Sign in to the AWS Console for the target account.
2. Navigate to CloudFormation > Stacks.
3. Find the Guardian Pro stack (it will show a CREATE_FAILED or ROLLBACK_COMPLETE status).
4. Click the stack name, then select the Events tab.
5. Look for the first event with a CREATE_FAILED status -- this is the root cause.

2. Common Failure Reasons

Error	Cause	Solution
IAM role already exists	A previous Guardian Pro deployment left behind a role with the same name	Delete the existing role from IAM, then retry the stack deployment
Insufficient permissions	The IAM user or role you are using does not have permission to create IAM roles or CloudFormation stacks	Use an account with administrator access, or ask your administrator to grant the required permissions
Service limit exceeded	Your account has reached the maximum number of IAM roles	Request a limit increase from AWS Support, or delete unused roles
Access denied on iam:CreateRole	Your IAM user/role lacks the iam:CreateRole permission	Ensure you have the permissions listed in Onboarding Prerequisites

tip

If the stack failed and rolled back, you can safely delete the failed stack and retry. CloudFormation cleans up any partially created resources during rollback.

StackSet Deployment Failures

Symptoms: The StackSet deployed during onboarding failed to deploy to one or more member accounts.

Troubleshooting Steps:

1. Navigate to CloudFormation > StackSets in the AWS Console (management account).
2. Select the Guardian Pro StackSet.
3. Click Stack instances to see per-account deployment status.
4. For any failed instances, check the Status reason column.

Common StackSet failure reasons:

• Account is suspended: The member account is suspended or closed. No action needed unless you want to reactivate the account.
• Region not enabled: The StackSet tried to deploy to a region that is not enabled in the member account. Enable the region or exclude it from the StackSet.
• Concurrent modification: Another StackSet operation was running at the same time. Wait and retry.
• Permissions boundary: The member account has an IAM permissions boundary that prevents role creation. Update the boundary to allow the Guardian Pro role.

note

StackSet failures in individual accounts do not affect other accounts. Guardian Pro will monitor all accounts where the role was successfully deployed.

Permission Errors

"Access Denied" During Scanning

Symptoms: Scan results show errors for specific services or resources, with "Access Denied" messages.

Troubleshooting Steps:

1. Verify the IAM role exists -- Navigate to IAM > Roles in the target AWS account and search for the Guardian Pro role.
2. Check attached policies -- Click the role and review its attached policies. Ensure the read-only scanning policy is present.
3. Check for SCPs -- If your organization uses Service Control Policies (SCPs), verify that the SCP does not deny the permissions required by the Guardian Pro role. SCPs take precedence over IAM role permissions.
4. Check for permissions boundaries -- If the role has a permissions boundary attached, ensure it allows the required read permissions.

info

Occasional "Access Denied" errors for specific services may indicate that the service is not available in a particular region, or that a regional service requires explicit opt-in. These are typically safe to ignore.

"Access Denied" During Remediation

Symptoms: Remediation actions fail with "Access Denied" errors.

Troubleshooting Steps:

1. Verify write permissions -- The Guardian Pro role requires specific write permissions for remediation. If you deployed the read-only version of the role, write operations will be denied by design.
2. Check the specific permission needed -- The remediation error message typically indicates which permission was denied. Verify this permission is granted in the role's policy.
3. SCP restrictions -- Service Control Policies may block write operations even if the IAM role allows them. Check your organization's SCPs.
4. Resource-level restrictions -- Some remediation actions may be blocked by resource-level policies (e.g., S3 bucket policies, KMS key policies).

To add missing write permissions:

1. Navigate to CloudFormation in the target account.
2. Find the Guardian Pro stack.
3. Update the stack with the latest template from Guardian Pro (available in Settings > Organization > select account > Update Role).

Role Cannot Be Assumed

Symptoms: Guardian Pro shows an "Error" status for an account, indicating it cannot assume the monitoring role.

Troubleshooting Steps:

1. Verify the Role Exists

1. Navigate to IAM > Roles in the target AWS account.
2. Search for the Guardian Pro role name.
3. If the role does not exist, it may have been manually deleted. Redeploy it by adding the account again.

2. Check the Trust Policy

The role's trust policy must allow the Guardian Pro service to assume it. To verify:

1. Click the Guardian Pro role in the IAM Console.
2. Select the Trust relationships tab.
3. Verify that the trust policy allows the Guardian Pro service to assume the role.
4. Verify that the External ID condition matches your Guardian Pro organization.

3. Verify the External ID

The external ID is a critical security control that prevents unauthorized access. If the external ID in the trust policy does not match your Guardian Pro organization's ID:

• The role assumption will fail silently.
• Redeploy the role using the CloudFormation template from Guardian Pro, which includes the correct external ID.

caution

Never manually edit the external ID in the trust policy unless you are certain of the correct value. An incorrect external ID will lock Guardian Pro out of the account.

4. Check for Role Name Changes

If the role was renamed or recreated with a different name, Guardian Pro will not be able to find it. The role name must match the expected naming convention used during deployment.

Cross-Account Access Issues

Scans Work but Remediation Fails

This typically indicates the role has read permissions but is missing write permissions:

1. Check whether you deployed the read-only version of the role (intended for scan-only mode).
2. If you need remediation capabilities, update the role by redeploying the CloudFormation stack with the full-access template.
3. The latest template is available from Guardian Pro at Settings > Organization > select the account > Update Role.

Some Regions Not Scanning

Symptoms: Resources in certain AWS regions are not being discovered.

Solutions:

• Region opt-in required: Some AWS regions require explicit opt-in (e.g., me-south-1, ap-east-1). Enable the region in your AWS account settings.
• SCP region restrictions: Your organization may have SCPs that restrict which regions can be accessed. Check your SCP policies.
• New regions: If you recently enabled a new region, run a new scan to discover resources in that region.

Multiple Accounts Showing Errors

If several accounts simultaneously show connection errors:

1. Check SCP changes -- A recent SCP change in your AWS Organization may be blocking the Guardian Pro role across multiple accounts.
2. Check StackSet updates -- If the StackSet was recently modified or deleted, roles in member accounts may have been affected.
3. Verify the management role -- Issues with the management account role can cascade to affect the connection status of member accounts.

Resolving Persistent Issues

If IAM issues persist after trying the solutions above:

1. Test the role manually -- In the target account, use the IAM Console's Policy Simulator to test whether the Guardian Pro role has the expected permissions.
2. Review CloudTrail -- Check CloudTrail logs in the target account for denied API calls from the Guardian Pro role. This reveals exactly which permissions are missing.
3. Redeploy the role -- Delete the existing CloudFormation stack and redeploy from scratch using the latest template from Guardian Pro.
4. Contact support -- If the issue remains unresolved, contact Guardian Pro support with the account ID and error messages.

Next Steps

• IAM Permissions -- Review the full permissions model.
• Adding Accounts -- Redeploy roles to affected accounts.
• Onboarding Overview -- Revisit the initial role deployment process.
• Contact Support -- Get help from the Guardian Pro team.