Onboard Alibaba Cloud accounts with a Python script

The onboarding script creates a RAM user with an AccessKey and attaches the required read-only policy to enable Rapid7 data collection.

To generate the onboarding script:

1. Log in to the Command Platform .
2. Go to Data Connectors > Cloud Accounts.
3. Click + Add Cloud.
4. Select Alibaba Cloud.
5. Click Script.
6. Click Download Script.

To run the script:

1. Open a terminal with the Alibaba Cloud CLI (aliyun) configured.

2. Navigate to the directory where the script was downloaded.

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

   python onboard.py --read-only

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

# Option 1: Basic interactive deployment
python onboard.py
 
# Option 2: Deploy with custom parameters
python onboard.py \
  --user-name r7cs_harvester \
  --account-id <account-id>

What happens:

• Validates Alibaba Cloud permissions
• Creates a RAM user (or uses an existing one)
• Downloads the latest read-only policy from Rapid7
• Creates and attaches the Rapid7CloudSecPolicy to the RAM user
• Generates an AccessKey for authentication

When the script is finished, copy the AccessKey ID and AccessKey Secret to a secure location. The AccessKey Secret cannot be retrieved after this point.

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 Access Key ID and Access Key Secret generated by the script.
3. Enter a Nickname for the account. This is a unique value that can be used to search and filter across Cloud Security (InsightCloudSec).
4. Click Connect Account.

--help:

Display all available options.

python onboard.py --help

--read-only:

Run in read-only mode to validate configuration without making changes.

python onboard.py --read-only

--check-permissions:

Validate required Alibaba Cloud permissions before deployment.

python onboard.py --check-permissions

--verbose:

Enable detailed logging for troubleshooting.

python onboard.py --verbose

--skip-permissions-check:

Skip the automatic permission check that runs before deployment. Not recommended.

python onboard.py --skip-permissions-check

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

• Check permissions first before attempting deployments using --check-permissions
• Test with --read-only mode when working with new configurations
• Use descriptive RAM user names that include environment or purpose (for example, r7cs-prod)
• Store AccessKey credentials securely — never in code repositories or publicly accessible locations
• Rotate AccessKeys regularly (recommended: every 90 days)
• Use separate RAM users for different environments (dev, staging, prod)
• Document RAM users for future reference and auditing
• Monitor RAM user activity through Alibaba Cloud ActionTrail

When connecting Rapid7 (or any product) to your Alibaba Cloud environment, consider the following before deploying anything:

• Grant only the minimum permissions required for monitoring
• Store AccessKey credentials in a secure vault, never in code repositories or public locations
• Rotate AccessKeys periodically (recommended: every 90 days)
• Monitor RAM user activity in Alibaba Cloud ActionTrail and RAM access logs
• Restrict who can create and manage RAM users using RAM policies
• Minimize the number of active AccessKeys per user (delete unused keys)
• Run deployment from a trusted, secured environment
• Periodically audit custom policy permissions and remove unnecessary access

You may want to explicitly validate that your credentials have the required permissions before attempting deployment or cleanup. Note that permission checks run automatically before every deployment unless --skip-permissions-check is provided.

To check your Alibaba Cloud permissions:

# Check deploy permissions
python onboard.py --check-permissions
 
# Check deploy permissions for a specific account
python onboard.py --check-permissions --account-id 1234567890123456
 
# Check undeploy permissions
python onboard.py --check-permissions --undeploy

How it works:

1. Script validates your aliyun CLI credentials are configured
2. Tests STS GetCallerIdentity to confirm the credentials resolve
3. Tests RAM ListUsers to confirm user management access
4. Tests RAM ListPolicies to confirm policy management access
5. Provides clear feedback on missing permissions with guidance
   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: Suggest running with --check-permissions for detailed analysis if issues are detected

You may want to validate your configuration without making any changes to Alibaba Cloud.

# Test complete deployment configuration
python onboard.py \
  --read-only \
  --user-name "r7cs_harvester" \
  --account-id "1234567890123456"
 
# Preview a policy permissions upgrade
python onboard.py --upgrade-policy-permissions --read-only
 
# Preview undeploy operation
python onboard.py --read-only --undeploy --user-name "r7cs_harvester"

What happens:

1. Script simulates all operations without executing writes
2. Shows what would be created, modified, or deleted
3. Validates all parameters and configurations
4. Reports any issues that would occur
5. Exits without making any changes

You may want to deploy in an automated environment (for example, in a CI/CD pipeline or script).

To deploy non-interactively:

# Full non-interactive deployment
python onboard.py \
  --user-name "r7cs_harvester" \
  --account-id "1234567890123456"

What happens:

1. Automatic permission check validates credentials
2. Script uses all provided parameters without prompts
3. Creates RAM user with specified configuration
4. Downloads latest policy from Rapid7
5. Creates and attaches the Rapid7CloudSecPolicy to the RAM user
6. Generates an AccessKey for authentication
7. Exits with appropriate status code

You may want to review or customize the RAM policy before deploying. The --download-policy-only option downloads the latest policy file from Rapid7 without making any other changes.

To download the policy file:

# Download to the default 'policies' directory
python onboard.py --download-policy-only
 
# Download to a specific directory
python onboard.py --download-policy-only /path/to/policies/

What happens:

1. Script downloads AliCloud-Read-Only-Policy.json from Rapid7
2. Saves the file to the specified directory (defaults to policies/)
3. Displays the file path and next steps
4. Exits without creating any cloud resources

After reviewing or modifying the file, run the deployment as usual. If a local policies/ directory is present when deploying, the script uses that policy instead of downloading a fresh copy from Rapid7.

Update the Rapid7CloudSecPolicy to include the latest permissions from Rapid7.

To upgrade policy permissions:

# Interactive upgrade (prompts for confirmation)
python onboard.py --upgrade-policy-permissions
 
# Upgrade without prompting
python onboard.py --upgrade-policy-permissions --auto-update-policies
 
# Upgrade policies attached to a specific user only
python onboard.py --upgrade-policy-permissions --user-name "r7cs_harvester"
 
# Preview what would change (read-only)
python onboard.py --upgrade-policy-permissions --read-only

What happens:

1. Script checks that Rapid7CloudSecPolicy exists
2. If --user-name is provided, verifies the policy is attached to that user
3. Retrieves the current policy permissions
4. Downloads the latest permissions from Rapid7
5. Compares current and latest permission sets
6. Merges new permissions into the existing policy (additive only)
7. Creates a new policy version set as default

You may want to remove the RAM user and policy assignments when they are no longer needed. By default, the Rapid7CloudSecPolicy custom policy is preserved in case it is used by other users.

To undeploy a RAM user:

# Check undeploy permissions first
python onboard.py --check-permissions --undeploy
 
# Preview undeploy with read-only mode
python onboard.py --read-only --undeploy --user-name "r7cs_harvester"
 
# Perform actual undeploy (preserves a custom policy)
python onboard.py --undeploy --user-name "r7cs_harvester"
 
# Force delete all resources including the custom policy
python onboard.py --undeploy --user-name "r7cs_harvester" --force-delete-all

What happens:

1. Automatic permission check validates you can delete resources
2. Script verifies the RAM user exists
3. Detaches all attached policies from the user
4. Deletes all AccessKeys associated with the user
5. Deletes the RAM user
6. Preserves Rapid7CloudSecPolicy by default (use --force-delete-all to delete it)
7. Confirms deletion

The script has a verbose flag for detailed output.

To use the --verbose option:

python onboard.py --verbose

This error occurs when the aliyun CLI is not properly authenticated or the account ID cannot be resolved.

Solution:

# Check current authentication status
aliyun configure list
 
# Re-configure the CLI if needed
aliyun configure
 
# Provide the account ID explicitly
python onboard.py --account-id YOUR_ACCOUNT_ID

This error occurs when your credentials do not have the required RAM permissions for the requested operation.

Solution:

Ensure your credentials have RAM admin permissions or the following equivalent permissions:

ram:CreateUser
ram:GetUser
ram:ListUsers
ram:DeleteUser
ram:CreateAccessKey
ram:ListAccessKeys
ram:DeleteAccessKey
ram:CreatePolicy
ram:GetPolicy
ram:GetPolicyVersion
ram:ListPolicies
ram:ListPolicyVersions
ram:CreatePolicyVersion
ram:DeletePolicyVersion
ram:DeletePolicy
ram:AttachPolicyToUser
ram:DetachPolicyFromUser
ram:ListPoliciesForUser
sts:GetCallerIdentity

Run python onboard.py --check-permissions to identify exactly which permissions are missing.

This error occurs when a RAM user with the specified name already exists in the account.

Solutions:

1. Re-run the script with the same user name — the script handles pre-existing users gracefully and will update the policy without creating a duplicate user:

   python onboard.py --user-name "r7cs_harvester" --account-id "1234567890123456"

2. Use a different user name:

   python onboard.py --user-name "r7cs_harvester_v2"

3. Remove the old user first (if no longer needed):

   python onboard.py --undeploy --user-name "r7cs_harvester"

Alibaba Cloud enforces a limit on the number of versions per custom policy. This can occur when --upgrade-policy-permissions has been run many times.

Solution:

The script automatically deletes non-default policy versions when cleaning up. To manually remove old versions:

# List policy versions
aliyun ram ListPolicyVersions --PolicyName Rapid7CloudSecPolicy --PolicyType Custom
 
# Delete a specific non-default version
aliyun ram DeletePolicyVersion --PolicyName Rapid7CloudSecPolicy --VersionId <version-id>

This error occurs when the script cannot reach Rapid7’s policy CDN (s3.amazonaws.com/get.divvycloud.com) to download the latest policy file.

Solutions:

1. Check your internet connectivity from the environment where you’re running the script.
2. Pre-download the policy file from a machine with connectivity, then use the local file:

   # Download the policy file
   python onboard.py --download-policy-only /path/to/policies/
    
   # Copy the policies directory to the deployment environment, then run
   python onboard.py --user-name "r7cs_harvester" --account-id "1234567890123456"

   When a local policies/ directory is present in the working directory, the script uses it instead of downloading from CDN.