Onboard accounts and organizations with a Python script

The onboarding script can deploy an IAM role and policies to a single AWS account to connect it to Cloud Security (InsightCloudSec). First, you’ll need to generate the script using your custom configuration details:

To generate the onboarding script:

1. Log in to the Command Platform .
2. Go to Data Connectors > Cloud Accounts.
3. Click + Add Cloud.
4. Click Amazon Web Services.
5. Click Script.
6. Select an AWS partition.
7. Indicate whether Cloud Security (InsightCloudSec) is deployed in the same AWS partition as the account you want to connect.
   • If No:
     1. Enter an Authenticating Principal.
8. Select Individual.
9. Optionally, expand Advanced Options:
   1. To enable AWS Event-Driven Harvesting (EDH) , set Allow Eventbridge To Assume Egress Role and Enable Eventbridge Auto Provisioning to ON.
   2. To enable automation and remediation features (for example, BotFactory , resource management ), set Enable Automation Full Access Policy to ON.
      1. To specify an existing automation-friendly IAM policy, enter an IAM Automation Policy Name. This policy must exist in the account you want to connect or the onboarding process will fail.
   3. To enable Container Vulnerability Assessments , set Enable Container Vulnerability Management to ON.
   4. To enable Host Vulnerability Assessments , set Enable Container Vulnerability Management to ON.
   5. To enable AWS Least-Privileged Access (LPA) , set Enable LPA Auto Provisioning to ON.
      1. To specify an existing S3 bucket to hold LPA findings, enter an LPA Working Bucket. Otherwise, you will need to create one later .
10. Click Generate & Download Script.
11. Copy and save Your Authenticating Principal to a secure location.

Your configured script is downloaded. Next, you’ll need to run the script to deploy the CFT, which creates the IAM resources needed to connect the account.

To run the script:

1. Open a new tab and log in to the AWS console .

2. Click the CloudShell icon.

3. Once the environment is finished loading, click Actions > Upload File.

4. Select the onboarding script from its downloaded location. The file is uploaded to /home/cloudshell-user by default.

5. Recommended: run the script with the --read-only option to testing your configuration, validate your permissions, and audit existing resources.

   python onboard.py --role-name <account-role> --read-only

6. Run the script and follow the prompts. The script will not run with Python 2.

   # Option 1: Basic deployment
   python onboard.py --role-name <account-role>
    
   # Option 2: Deploy with custom parameters
   python onboard.py \
     --role-name <role-name> \
     --iam-path <iam-path> \
     --allow-set-source-identity \
     --tags key=value key1=value1 \
     --on-high-complexity proceed

7. The script reports on the status of the onboarding process. What happens:

   1. Script generates CloudFormation template
   2. Determines deployment scope (organization vs account level) based on configuration
   3. Creates CloudFormation stack in current account
   4. Deploys IAM role and policies
   5. Displays deployment status and next steps

8. Copy the deployment details to a secure location.

Lastly, you’ll need to update Cloud Security (InsightCloudSec) with the deployment details.

To finish the onboarding process:

1. Return to the Command Platform browser tab.
2. Enter the Role ARN for the new IAM role inside the AWS account.
3. Enter a Nickname for the AWS account. This is a unique value that can be used to search and filter across Cloud Security (InsightCloudSec).
4. Optionally, adjust the Role Session Name or the Duration.
5. Click Connect Account.

The onboarding script can deploy an IAM role and policies to an AWS organization and its member accounts to connect them to Cloud Security (InsightCloudSec). First, you’ll need to generate the script using your custom configuration details:

To generate the onboarding script:

1. Log in to the Command Platform .
2. Go to Data Connectors > Cloud Accounts.
3. Click + Add Cloud.
4. Click Amazon Web Services.
5. Click Script.
6. Select an AWS partition.
7. Indicate whether Cloud Security (InsightCloudSec) is deployed in the same AWS partition as the account you want to connect.
   • If No:
     1. Enter an Authenticating Principal.
8. Select Organization.
9. Optionally, expand Advanced Options:
   1. To enable AWS Event-Driven Harvesting (EDH) , set Allow Eventbridge To Assume Egress Role and Enable Eventbridge Auto Provisioning to ON.
   2. To enable automation and remediation features (for example, BotFactory , resource management ), set Enable Automation Full Access Policy to ON.
      1. To specify an existing automation-friendly IAM policy, enter an IAM Automation Policy Name. This policy must exist in the account you want to connect or the onboarding process will fail.
   3. To enable Container Vulnerability Assessments , set Enable Container Vulnerability Management to ON.
   4. To enable Host Vulnerability Assessments , set Enable Container Vulnerability Management to ON.
   5. To enable AWS Least-Privileged Access (LPA) , set Enable LPA Auto Provisioning to ON.
      1. To specify an existing S3 bucket to hold LPA findings, enter an LPA Working Bucket. Otherwise, you will need to create one later .
10. Click Generate & Download Script.
11. Copy and save Your Authenticating Principal to a secure location.

Your configured script is downloaded. Next, you’ll need to run the script to deploy the CFT, which creates the IAM resources needed to connect the account.

To run the script:

1. Open a new tab, and using your organization root account, log in to the AWS console  .

2. Click the CloudShell icon.

3. Once the environment is finished loading, click Actions > Upload File.

4. Select the onboarding script from its downloaded location. The file is uploaded to /home/cloudshell-user by default.

5. Recommended: run the script with the --read-only option to testing your configuration, validate your permissions, and audit existing resources.

   python onboard.py --role-name <org-role-name> --read-only

6. Run the script and follow the prompts. The script will not run with Python 2.

   # Option 1: Basic deployment
   python onboard.py --role-name <org-role-name>
    
   # Option 2: Deploy with custom parameters
   python onboard.py \
     --role-name <org-role-name> \
     --iam-path <iam-path> \
     --allow-set-source-identity \
     --tags key=value key1=value1 \
     --on-high-complexity proceed

7. The script reports on the status of the onboarding process. What happens:

   1. Script detects organization context
   2. Determines deployment scope based on pre-configured settings
   3. Deploys both Stack (root account) and StackSet (member accounts) for organization-wide connection

8. Copy the deployment details to a secure location.

Lastly, you’ll need to update Cloud Security (InsightCloudSec) with the deployment details.

To finish the onboarding process:

1. Return to the Command Platform browser tab.
2. Enter the Role ARN for the new IAM role inside the AWS account.
3. Enter a Nickname for the AWS account. This is a unique value that can be used to search and filter across Cloud Security (InsightCloudSec).
4. Optionally, adjust the Role Session Name or the Duration.
5. Click Connect Account.

--help:

Display comprehensive help information about all available options.

python onboard.py --help

--debug:

Enable debug logging for troubleshooting and verbose output.

python onboard.py --debug

--read-only:

Enable read-only mode to prevent all write operations (for example, CloudFormation deployments and stack modifications) while allowing read-only AWS API calls for analysis. Read-only mode is useful for testing commands and validating configurations without making any changes.

python onboard.py --read-only

--check-permissions:

Explicitly validate that your AWS credentials have the required permissions before attempting deployment or cleanup. This performs a read-only check using the AWS IAM Policy Simulator to verify you have all necessary permissions.

python onboard.py --check-permissions

When running the script, use these best practices to ensure minimal friction:

• Check permissions first before attempting deployments using --check-permissions.
• Test new configurations using --read-only mode.
• Use unique suffixes for multiple deployments in the same account.
• Tag your resources appropriately for cost tracking and management.
• Review policy files before deployment when security is critical.
• Monitor CloudFormation events in the AWS Console during deployment.
• Keep templates under size limits by using AWS managed policies when possible.
• Document your deployment parameters for future reference and updates.

When connecting Rapid7 (or any product) to your AWS environment, you should always consider the following before deploying anything:

• Principle of Least Privilege: Review all policies to ensure they grant only necessary permissions.
• Trust Policy Review: Carefully review which principals can assume your roles.
• Regular Updates: Keep policies updated with the latest versions from Rapid7.
• Audit Logging: Ensure CloudTrail is enabled to monitor role usage.
• Multi-Account Strategy: Consider using separate roles for different environments or purposes.

You may want to explicitly validate that your AWS credentials have the required permissions before attempting deployment or cleanup. This performs a read-only check using AWS IAM Policy Simulator to verify you have all necessary permissions. Note that permission checks run automatically before every deployment unless --skip-deploy is provided.

To check your AWS permissions:

# Check general AWS permissions
python onboard.py --check-permissions

# Check if you can undeploy the specified role and onboarding infrastructure
python onboard.py --check-permissions --undeploy --role-name my-cs-role

How it works:

1. Retrieves your current AWS identity (User or Role ARN)
2. Uses IAM Policy Simulator to test each required permission:
   • Account-level permissions: Required for all deployments (CloudFormation, IAM operations)
   • Organization-level permissions: Required only if deploying to AWS Organizations
3. Reports results with detailed feedback on any missing permissions
   1. If this was an explicit permissions check, the script exits after showing results (does not proceed with deployment)
   2. If this was an automatic permissions check:
      • ✅ Passes: All permissions verified - proceeds with deployment
      • ⚠️ Fails: Missing permissions detected - warns but continues anyway
      • ℹ️ Skips: IAM Policy Simulator unavailable - continues with deployment

You may want to enable read-only mode to prevent all write operations (for example, CloudFormation deployments and stack modifications) while allowing read-only AWS API calls for analysis. Read-only mode is useful for testing commands and validating configurations without making any changes.

python onboard.py --read-only --role-name test-role

You may want to download the policies to review them before deployment.

To download all policies created by Rapid7:

# Download all policies to a local directory
python onboard.py --download-policies-only <directory>

All policy files are downloaded as YAML from the Rapid7 content delivery network (CDN) and saved to the specified directory.

You may want to customize policies before generating CFTs.

To modify policies and generate an updated CFT:

1. Download the policy files:

   python onboard.py --download-policies-only <directory>

2. Review and edit the policies using a text editor as needed.

3. Generate the deployment CFT using the new, local policies:

   python onboard.py --policy-source <directory> --skip-deploy --role-name custom-role

You may want to generate a CFT for review without deploying.

To generate a CFT (no options):

python onboard.py --skip-deploy --role-name my-security-role

To generate a CFT using advanced options:

python onboard.py \
  --skip-deploy \
  --role-name <role-name> \
  --iam-path <iam-path>> \
  --explicit-readonly-policy \
  --allow-tag-session \
  --tags key=value key1=value1 \
  --outfile <file-name>.yaml

If a new resource is supported by Cloud Security (InsightCloudSec) or new permissions are required, you may want to update an existing role deployment with new policies or configuration.

To update an existing role:

# Update with change analysis
python onboard.py --role-name <existing-role>
 
# Update without prompts (CI/CD friendly)
python onboard.py \
  --role-name <existing-role> \
  --skip-update-analysis \
  --on-high-complexity proceed

When you provide an existing role name to the onboarding script, it can automatically detect the existing role and CFT Stack, analyze the changes necessary to update, and apply the changes.

If you want to remove a cloud account connection or a role entirely, you can un-deploy the resources.

To un-deploy onboarding artifacts:

# Undeploy specific role resources
python onboard.py --undeploy --role-name role-to-remove
 
# Test undeploy with read-only mode
python onboard.py --undeploy --read-only --role-name test-role

The script then identifies the CloudFormation Stacks and StackSets associated with the role name, then deletes all instances from your AWS.

You may want to deploy multiple versions of the same role configuration for testing, rollback, or gradual migration purposes. Using the --unique-suffix option, you can deploy multiple versions of the same base role configuration.

To deploy multiple role versions (example):

# Deploy initial production role `cs-production-role-v1`
python onboard.py --role-name cs-production-role --unique-suffix v1
 
# Deploy updated role for testing `cs-production-role-v2`
python onboard.py --role-name cs-production-role --unique-suffix v2
 
# Deploy new role (`cs-production-role-v3`) with additional features
python onboard.py \
  --role-name cs-production-role \
  --unique-suffix v3 \
  --allow-set-source-identity \
  --allow-tag-session
 
# Keep previous version (`cs-production-role-v1-backup`) as fallback
python onboard.py --role-name cs-production-role --unique-suffix v1-backup

All managed policies get the suffix appended and CloudFormation Stacks and StackSets are named uniquely for each version.

To test role configurations (example):

# Current production role
aws sts assume-role --role-arn arn:aws:iam::123456789012:role/cs-production-role-v2 --role-session-name test
 
# Test new version
aws sts assume-role --role-arn arn:aws:iam::123456789012:role/cs-production-role-v3 --role-session-name test
 
# Clean up old version when confident
python onboard.py --undeploy --role-name cs-production-role --unique-suffix v1

You may want to deploy different configurations for development, staging, and production environments.

To onboard multiple environments (example):

# Development environment
python onboard.py \
  --role-name dev-cs-role \
  --unique-suffix dev \
  --tags environment=development cost-center=engineering
 
# Staging environment
python onboard.py \
  --role-name staging-cs-role \
  --unique-suffix staging \
  --iam-path /staging/security/ \
  --tags environment=staging cost-center=qa
 
# Production environment
python onboard.py \
  --role-name prod-cs-role \
  --unique-suffix prod \
  --iam-path /production/security/ \
  --explicit-readonly-policy \
  --allow-set-source-identity \
  --allow-tag-session \
  --tags environment=production cost-center=security \
  --on-high-complexity stop

You may need to integrate the onboarding script into automated deployment pipeline.

To integrate the onboarding script into a CI/CD pipeline:

# CI/CD friendly deployment
python onboard.py \
  --role-name automated-role \
  --skip-update-analysis \
  --on-high-complexity proceed \
  --tags deployment-method=cicd pipeline-id="${CI_PIPELINE_ID}" \
  --debug

If you need to grant multiple AWS accounts or roles access to assume the Cloud Security (InsightCloudSec) role, you can use the --principals flag.

To onboard with multiple principals (example):

python onboard.py \
  --role-name shared-role \
  --principals \
    arn:aws:iam::111111111111:root=external-id-1 \
    arn:aws:iam::222222222222:role/SecurityRole=external-id-2 \
    arn:aws:iam::333333333333:role/AuditRole=external-id-3

You can onboard a cloud account using policy files in a local directory or from a custom CDN.

To use custom policies (example):

# Use policies from local directory
python onboard.py --policy-source /path/to/custom/policies/ --role-name custom-role
 
# Use policies from custom CDN endpoint
python onboard.py --policy-source https://custom-cdn.example.com/policies --role-name custom-role

By default, the onboarding script uses the AWS-managed SecurityAudit policy. You can use the --explicit-readonly-policy option to create explicit policies with only read only permissions.

python onboard.py --explicit-readonly-policy

Benefits of AWS-managed SecurityAudit policy (default):

• Automatic updates: Managed policy grows as AWS services expand, providing coverage for new services without script updates
• Smaller template size: Reduces CloudFormation template size, helping stay within the character limit
• AWS best practices: Maintained by AWS with security best practices

Benefits of explicit readonly policies:

• Direct visibility: All permissions are explicitly listed in the template for audit purposes
• Version control: Exact permissions are locked to specific versions
• Compliance requirements: Some organizations require explicit permission documentation
• Air-gapped environments: Useful when SecurityAudit managed policy updates are restricted

When to use each approach:

• Use managed SecurityAudit (default): For most deployments, especially when you want automatic coverage of new AWS services
• Use explicit policies: When you need complete audit visibility, have strict compliance requirements, or operate in environments where managed policy updates are controlled

This error is caused by the user not properly configuring AWS credentials or the AWS credentials expiring.

Solution:

# Check current credentials
aws sts get-caller-identity
 
# Reconfigure if needed
aws configure
# or for SSO
aws sso login
 
# For AWS CloudShell users: credentials should be automatic
# If issues persist in CloudShell, try refreshing the session

This error is caused by insufficient AWS permissions for the required operations.

Solution: Ensure your AWS user or role has permissions for:

• iam:* (for role and policy management)
• cloudformation:* (for stack operations)
• organizations:* (for organization-level deployment only)
• sts:GetCallerIdentity (for identity verification)

This error is caused by not running the script from the AWS Organizations root account or insufficient permissions.

Solution:

• Ensure you’re running from the root account of your AWS Organization
• Verify you have AWS Organizations permissions
• Script will automatically fall back to account-level deployment

This error is caused by your CloudFormation template exceeding the maximum size limit (51,200 bytes) for direct deployment. The script automatically checks template size and warns when approaching or exceeding limits. You can implement one of the following strategies for larger deployments:

Use AWS-managed SecurityAudit policies (default onboarding script behavior, recommended):

# Uses SecurityAudit managed policy (smaller template size)
python onboard.py --role-name optimized-role

The SecurityAudit managed policy helps keep templates smaller, while explicit policies may exceed this limit in complex deployments.

Manually deploy in the AWS CloudFormation console using an S3 bucket:

1. Upload your generated template to an S3 bucket in the account.
2. Use the AWS CloudFormation console with the --template-url option pointing to the S3 bucket.
   1. For more specific details, see Onboard an account with CloudFormation Templates or Onboard an organization with CloudFormation Templates.

Use multiple roles:

For very large environments, consider creating different roles for different accounts. Currently, Cloud Security (InsightCloudSec) only supports connecting one role per account, so you’ll need to onboard each role separately.

# Core monitoring role
python onboard.py --role-name core-monitoring --unique-suffix core
 
# Compliance role
python onboard.py --role-name compliance-monitoring --unique-suffix compliance

This error is caused by a role name containing characters that create invalid CloudFormation resource names.

Solution: Use only alphanumeric characters and hyphens:

python onboard.py --role-name valid-role-name

This error is caused by AWS CloudFormation detecting potentially disruptive changes.

Solutions:

1. Review changes carefully and proceed if safe.
2. Use --on-high-complexity proceed to skip prompts.
3. Use --skip-update-analysis to bypass analysis.

This error is caused by CloudFormation StackSet operations taking longer than expected.

Solution: Check AWS Console for detailed status or increase timeout environment variables:

export AWS_STACK_SET_TIMEOUT_MINUTES=30
export AWS_STACK_SET_MAX_ATTEMPTS=360
python onboard.py --role-name slow-role

As a non-admin user, you need to copy and send a message to an AWS admin user in your organization asking them to complete specific tasks and provide you with the information needed to complete onboarding.

1. Log in to the Command Platform .
2. Go to Data Connectors > Cloud Accounts.
3. Click + Add Cloud.
4. Click Amazon Web Services.
5. Click Don’t have admin access?.
6. Click Copy in the Amazon Web Services Admin Instructions text box and share them with the admin user.

When the admin has completed their steps and provided the information to you, you can now connect the account.

1. Log in to the Command Platform .
2. Go to Data Connectors > Cloud Accounts.
3. Click + Add Cloud.
4. Click Amazon Web Services.
5. Enter the following information (provided by your admin):
   1. Select an AWS partition.
   2. Indicate whether Cloud Security (InsightCloudSec) is deployed in the same AWS partition as the account you want to connect.
      • If No:
        1. Enter an Authenticating Principal.
   3. Select Organization.
   4. Optionally, expand Advanced Options:
      1. To enable AWS Event-Driven Harvesting (EDH) , set Allow Eventbridge To Assume Egress Role and Enable Eventbridge Auto Provisioning to ON.
      2. To enable automation and remediation features (for example, BotFactory , resource management ), set Enable Automation Full Access Policy to ON.
         1. To specify an existing automation-friendly IAM policy, enter an IAM Automation Policy Name. This policy must exist in the account you want to connect or the onboarding process will fail.
      3. To enable Container Vulnerability Assessments , set Enable Container Vulnerability Management to ON.
      4. To enable Host Vulnerability Assessments , set Enable Container Vulnerability Management to ON.
      5. To enable AWS Least-Privileged Access (LPA) , set Enable LPA Auto Provisioning to ON.
         1. To specify an existing S3 bucket to hold LPA findings, enter an LPA Working Bucket. Otherwise, Rapid7 will create a bucket automatically.
      6. If your admin chose not to use the default Session Name, enter the new value.
      7. If your admin chose not to use the default Duration, enter the new value.
      8. Enter the Role ARN.
      9. Enter the Nickname.
6. Click Connect Account.

The script has a debugging flag.

To use the --debug option:

python onboard.py --debug --role-name debug-role

You can use the --skip-deploy option to get a detailed preview of your operation.

To use the --skip-deploy option:

# Generate template and preview changes without deploying
python onboard.py --skip-deploy --role-name existing-role

You can use the AWS CloudFormation CLI option validate-template:

# Validate template syntax without deploying
aws cloudformation validate-template --template-body file://rapid7-aws-iam-roles-cloudformation-template.yaml
 
# Estimate costs (if applicable)
aws cloudformation estimate-template-cost --template-body file://rapid7-aws-iam-roles-cloudformation-template.yaml