Connecting Your AWS Account

Guardian Pro connects to your AWS environment through IAM roles -- there are no agents to install, no credentials to store, and no long-lived access keys. This page explains the two connection paths, what gets deployed, and how least-privilege access works.

Connection Paths

Guardian Pro supports two setup paths depending on your AWS environment:

Path 1: Multi-Account (AWS Organizations)

Best for: Teams managing multiple AWS accounts through AWS Organizations.

This is the recommended approach. Guardian Pro discovers your entire Organization structure and deploys lightweight IAM roles to each member account using CloudFormation StackSets.

What gets deployed:

Component	Where	Purpose
Management Role	Management account	Read-only access to AWS Organizations APIs for account discovery
Member Roles	Each member account (via StackSet)	Read access for resource discovery and scanning; limited write access for optional remediation

tip

When you add new accounts to your AWS Organization, Guardian Pro automatically detects them and deploys the member role via the existing StackSet. No manual intervention is needed.

Path 2: Single Account

Best for: Individual AWS accounts not part of an Organization, or teams wanting to evaluate Guardian Pro on a single account before expanding.

What gets deployed:

Component	Where	Purpose
Guardian Pro Role	Your AWS account	Combined read access for discovery and scanning, with limited write for optional remediation

info

You can start with a single account and migrate to the multi-account path later. Your existing scan history, findings, and configuration are preserved.

How IAM Roles Work

Guardian Pro uses the AWS cross-account role assumption pattern -- the same mechanism AWS recommends for third-party integrations.

The Trust Relationship

Each IAM role includes a trust policy that allows Guardian Pro's service account to assume the role. The trust policy includes:

• Principal: Guardian Pro's dedicated AWS account ID
• External ID: A unique, organization-specific identifier that prevents confused deputy attacks
• Condition: The External ID must match exactly, ensuring that only your Guardian Pro tenant can assume the role

Your AWS Account                    Guardian Pro
┌──────────────────┐               ┌──────────────────┐
│                  │  AssumeRole   │                  │
│   IAM Role       │◄──────────────│   Service        │
│   (Trust Policy) │  + ExternalID │   Account        │
│                  │               │                  │
└──────────────────┘               └──────────────────┘

note

Guardian Pro never stores or uses AWS access keys. All access flows through temporary credentials obtained via role assumption, which automatically expire after a short session.

What Guardian Pro Can Access

Guardian Pro's IAM roles follow the principle of least privilege. Permissions are divided into two categories:

Read Permissions (Always Active)

Read permissions enable resource discovery and security scanning. These include:

• Describe and List calls across AWS services (EC2, RDS, S3, IAM, Lambda, ECS, and more)
• GetBucketPolicy, GetEncryptionConfiguration, and similar configuration reads
• CloudFormation stack inspection for IaC governance features
• Cost and Usage Report access (if CUR is configured)

Read permissions are sufficient for all scanning, compliance, and architecture features to function. No resources in your account are modified.

Write Permissions (Optional, Scoped)

Write permissions are only used when you explicitly trigger a remediation action. They are:

• Scoped to specific API actions -- only the exact API calls needed for supported remediation strategies
• Triggered only by user action -- Guardian Pro never modifies resources without explicit user approval
• Fully auditable -- every remediation action is logged with a complete audit trail
• Reversible -- many remediation actions support one-click rollback

warning

If your security policy prohibits any write access from third-party tools, you can deploy Guardian Pro with read-only roles. All scanning, compliance, and advisory features will work normally. Only the automated remediation feature requires write permissions.

Deployment Process

Multi-Account Deployment

The onboarding wizard guides you through each step. Here is what happens behind the scenes:

Step 1: Deploy the Management Role

Guardian Pro provides a CloudFormation template that creates a read-only IAM role in your management account. This role can:

• List accounts in your AWS Organization
• Describe organizational units (OUs) and account structure
• Read Organization metadata

How to deploy:

1. During onboarding, Guardian Pro presents a CloudFormation quick-create link.
2. Click the link -- it opens the CloudFormation console in your management account.
3. Review the template (it contains only the IAM role and its trust policy).
4. Acknowledge IAM resource creation and click Create Stack.
5. Wait for stack creation to complete (typically under 60 seconds).
6. Return to the Guardian Pro console and click Verify to confirm the connection.

Step 2: Organization Discovery

Once the management role is verified, Guardian Pro automatically:

• Discovers all accounts in your Organization
• Maps the OU structure
• Identifies the management account and member accounts

You will see your full account tree displayed in the Guardian Pro console.

Step 3: Deploy Member Roles via StackSet

Guardian Pro uses CloudFormation StackSets to deploy a member role to every account in your Organization:

1. Guardian Pro presents a StackSet quick-create link.
2. Click the link to open the CloudFormation StackSets console.
3. Review the template -- it contains the member IAM role for each account.
4. Choose deployment targets (all accounts, or specific OUs).
5. Deploy the StackSet.

info

StackSets use service-managed deployment, which means new accounts added to your Organization in the future will automatically receive the member role. No manual updates are needed.

Step 4: Verification

After the StackSet deployment completes, Guardian Pro verifies connectivity to each member account by performing a test role assumption. Accounts that pass verification appear as "Connected" in the console.

Single Account Deployment

For single account setups, the process is simpler:

1. During onboarding, Guardian Pro provides a CloudFormation quick-create link.
2. Click the link to open the CloudFormation console in your account.
3. Review and deploy the template.
4. Return to Guardian Pro and verify the connection.

Security Considerations

Least Privilege

Every IAM role deployed by Guardian Pro follows the principle of least privilege:

• Permissions are limited to the specific API actions required for each feature
• No wildcard (*) resource permissions are used where resource-level permissions are supported
• Write permissions are narrowly scoped to supported remediation actions

External ID Protection

The External ID mechanism prevents confused deputy attacks. Each Guardian Pro tenant receives a unique External ID that is:

• Generated during onboarding
• Included in every role trust policy
• Validated on every role assumption
• Not shared across tenants

No Persistent Credentials

Guardian Pro never stores long-lived AWS credentials:

• All access uses temporary session credentials via sts:AssumeRole
• Session credentials expire automatically
• No access keys, secret keys, or long-term credentials are involved

Audit Trail

All API calls made by Guardian Pro appear in your AWS CloudTrail logs. You can:

• Filter CloudTrail events by the Guardian Pro role ARN
• Monitor which API calls Guardian Pro makes in each account
• Set up CloudTrail alerts for specific actions if desired

tip

Search your CloudTrail logs for the Guardian Pro role name to review exactly what API calls have been made in your accounts at any time.

Removing Access

If you need to disconnect Guardian Pro from your AWS environment:

1. Delete the StackSet (multi-account) -- This removes member roles from all accounts.
2. Delete the management role stack -- This removes the management account role.
3. Single account -- Delete the CloudFormation stack containing the Guardian Pro role.

Removing the IAM roles immediately and permanently revokes Guardian Pro's access to your accounts. No residual access remains.

Troubleshooting Connection Issues

Issue	Likely Cause	Resolution
Role verification fails	CloudFormation stack not yet complete	Wait for stack status to show CREATE_COMPLETE, then retry verification
StackSet deployment partial	SCP blocking IAM role creation in some accounts	Review SCPs in affected OUs; exempt the Guardian Pro StackSet or adjust policies
"Access Denied" after setup	Role trust policy mismatch	Verify the External ID in the role's trust policy matches your Guardian Pro tenant
Account not appearing	Account added after StackSet deployment	For service-managed StackSets, the role deploys automatically. Allow a few minutes for propagation

For additional help, see the Troubleshooting guide or contact Support.

Next Steps

Once your accounts are connected, continue with the onboarding wizard to:

• Set up users and permissions
• Run your first scan
• Take a tour of the dashboard