Onboard Oracle Cloud accounts with a Python script

The onboarding script creates an IAM user, group, and policy, then generates an API key pair 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 Oracle Cloud.
5. Click Script.
6. Optionally, toggle Power User on to enable remediation capabilities. The default is read-only.
7. Click Generate & Download Script.

To run the script:

1. Open a terminal with the OCI CLI (oci) configured.

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

3. Optionally review and adjust the policies as needed. Review Download policies only for more information.

4. 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

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

# Option 1: Basic interactive deployment (tenancy auto-detected in Cloud Shell)
python onboard.py
 
# Option 2: Deploy with custom parameters
python onboard.py \
  --user-name r7cs_harvester \
  --tenancy-id ocid1.tenancy.oc1..<unique-id>
 
# Option 3: Deploy with power user permissions
python onboard.py \
  --user-name r7cs_harvester \
  --tenancy-id ocid1.tenancy.oc1..<unique-id> \
  --power-user

What happens:

• Validates OCI permissions
• Checks identity domain type and displays relevant tier information
• Creates an IAM group (CloudSec) or uses an existing one
• Creates an IAM user or uses an existing one
• Adds the user to the group
• Downloads the appropriate policy (read-only or power user) from Rapid7
• Creates and attaches the IAM policy at the tenancy level
• Generates an RSA API key pair and saves the private key locally

When the script is finished, copy the deployment details displayed in the terminal to a secure location. You will need the User ID, Tenancy ID, fingerprint, and private key file to complete onboarding.

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 User ID generated by the script.
3. Enter your Tenancy ID.
4. Paste the contents of the private key file (oci_api_key.pem by default) into the Key Content field.
5. Enter the Fingerprint generated by the script.
6. Enter a Nickname for the account. This is a unique value that can be used to search and filter across Cloud Security (InsightCloudSec).
7. Enter the Home Region for your tenancy (for example, us-ashburn-1).
8. 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 OCI permissions before deployment.

python onboard.py --check-permissions --tenancy-id ocid1.tenancy.oc1..<unique-id>

--power-user:

Use power user permissions instead of read-only. Enables remediation capabilities.

python onboard.py --power-user

--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

--key-output:

Specify a custom filename for the generated API private key. Defaults to oci_api_key.pem.

python onboard.py --key-output my_key.pem

--compartment-id:

Specify a compartment OCID to scope policy creation. Defaults to the tenancy root compartment.

python onboard.py --compartment-id ocid1.compartment.oc1..<unique-id>

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
• Run the script from Oracle Cloud Shell when possible — the tenancy ID is auto-detected from the environment variable OCI_TENANCY
• Use descriptive IAM user names that include environment or purpose (for example, r7cs-prod)
• Store the private key file securely — never in code repositories or publicly accessible locations
• Use separate IAM users for different environments (dev, staging, prod)
• Document IAM users and groups for future reference and auditing
• Monitor IAM user activity through OCI Audit logs
• Start with read-only permissions and add power user only when remediation is required

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

• Grant only the minimum permissions required for monitoring; use read-only unless remediation is needed
• Store the private key file in a secure vault, never in code repositories or public locations
• Limit the number of active API keys per user and delete unused keys via the OCI console
• Scope policies at the tenancy level only when tenancy-wide visibility is required
• Monitor IAM user and API key activity through OCI Audit
• Restrict who can create and manage IAM users using OCI policies
• Run deployment from a trusted environment — Oracle Cloud Shell is recommended
• Periodically audit policy statements 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 OCI permissions:

# Check deploy permissions
python onboard.py --check-permissions --tenancy-id ocid1.tenancy.oc1..<unique-id>

The permission check also displays your OCI identity domain tier and its associated API rate limits. Free tier tenancies have significantly lower rate limits, which may affect harvesting performance. Review the output for guidance specific to your tier. For production use with large OCI environments, Rapid7 recommends a paid identity domain tier. See Oracle’s identity domain tier documentation  for details.

How it works:

1. Script validates access to tenancy information
2. Tests iam user list to confirm user management access
3. Tests iam group list to confirm group management access
4. Tests iam policy list to confirm policy management access
5. Checks your identity domain type and displays API rate limit information for your tier
6. 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: Insufficient permissions detected — exits with an error
      • ℹ️ Inconclusive: Unable to verify — proceeds with a warning

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

# Test complete deployment configuration
python onboard.py \
  --read-only \
  --user-name "r7cs_harvester" \
  --tenancy-id "ocid1.tenancy.oc1..<unique-id>"
 
# Preview a policy permissions upgrade
python onboard.py \
  --upgrade-policy-permissions \
  --tenancy-id "ocid1.tenancy.oc1..<unique-id>" \
  --read-only
 
# Preview undeploy operation
python onboard.py \
  --read-only \
  --undeploy \
  --user-name "r7cs_harvester" \
  --tenancy-id "ocid1.tenancy.oc1..<unique-id>"

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).

To deploy non-interactively:

# Full non-interactive deployment (read-only permissions)
python onboard.py \
  --user-name "r7cs_harvester" \
  --tenancy-id "ocid1.tenancy.oc1..<unique-id>"
 
# Non-interactive deployment with power user permissions
python onboard.py \
  --user-name "r7cs_harvester" \
  --tenancy-id "ocid1.tenancy.oc1..<unique-id>" \
  --power-user

What happens:

1. Automatic permission check validates credentials
2. Identity domain type is checked and displayed
3. Script uses all provided parameters without prompts
4. Creates IAM group, user, and policy with specified configuration
5. Generates RSA API key pair and uploads the public key to OCI
6. Saves the private key to the specified file (oci_api_key.pem by default)
7. Exits with appropriate status code

You may want to review or customize the OCI policy statements before deploying. The --download-policies-only option downloads both the read-only and power user policy files from Rapid7 without making any other changes.

To download the policy files:

# Download to a specific directory
python onboard.py --download-policies-only ./policies

What happens:

1. Script downloads both Oracle-Read-Only-Policy.txt and Oracle-Power-User-Policy.txt from Rapid7
2. Saves the files to the specified directory
3. Displays the file paths and next steps
4. Exits without creating any cloud resources

After reviewing or modifying the files, run the deployment as usual. If a local policies/ directory containing both policy files is present in the working directory, the script uses those files instead of downloading fresh copies from Rapid7.

Update one or both Rapid7 CloudSec policies to include the latest permissions from Rapid7. The upgrade process checks both Rapid7CloudSecReadOnlyPolicy and Rapid7CloudSecPowerUserPolicy and updates whichever ones exist. This is an additive operation — existing statements are never removed.

To upgrade policy permissions:

# Interactive upgrade (prompts for confirmation per policy)
python onboard.py \
  --upgrade-policy-permissions \
  --tenancy-id "ocid1.tenancy.oc1..<unique-id>"
 
# Upgrade without prompting
python onboard.py \
  --upgrade-policy-permissions \
  --tenancy-id "ocid1.tenancy.oc1..<unique-id>" \
  --auto-update-policies
 
# Upgrade policies associated with a specific user only
python onboard.py \
  --upgrade-policy-permissions \
  --tenancy-id "ocid1.tenancy.oc1..<unique-id>" \
  --user-name "r7cs_harvester"
 
# Preview what would change (read-only)
python onboard.py \
  --upgrade-policy-permissions \
  --tenancy-id "ocid1.tenancy.oc1..<unique-id>" \
  --read-only

What happens:

1. If --user-name is provided, the script verifies the user exists and is a member of the CloudSec group
2. Checks for both Rapid7CloudSecReadOnlyPolicy and Rapid7CloudSecPowerUserPolicy — skips any that do not exist
3. Downloads the latest policy statements from Rapid7
4. Compares current and latest statement sets
5. Merges new statements into existing policies (additive only)
6. If the policy has no version-date, it is deleted and recreated; otherwise it is updated in place

You may want to remove OCI resources when they are no longer needed. By default, the IAM group and policy are preserved in case they are used by other users or resources.

To undeploy resources:

# Preview undeploy with read-only mode
python onboard.py \
  --read-only \
  --undeploy \
  --user-name "r7cs_harvester" \
  --tenancy-id "ocid1.tenancy.oc1..<unique-id>"
 
# Perform actual undeploy (preserves group and policy)
python onboard.py \
  --undeploy \
  --user-name "r7cs_harvester" \
  --tenancy-id "ocid1.tenancy.oc1..<unique-id>"
 
# Force delete all resources including group and policy
python onboard.py \
  --undeploy \
  --user-name "r7cs_harvester" \
  --tenancy-id "ocid1.tenancy.oc1..<unique-id>" \
  --force-delete-all

What happens:

1. Script locates the IAM user, group, and policy
2. Removes the user from all group memberships
3. Deletes all API keys associated with the user
4. Deletes the IAM user
5. Preserves the IAM group and policy by default (use --force-delete-all to delete them)
6. Confirms deletion

The script has a verbose flag for detailed output.

To use the --verbose option:

python onboard.py --verbose

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

Solution:

Ensure your credentials have IAM admin permissions or the following equivalent capabilities:

• List and manage users (iam-users)
• List and manage groups (iam-groups)
• List and manage policies (iam-policies)
• Manage group memberships
• Upload and delete API keys

Run python onboard.py --check-permissions --tenancy-id <tenancy-id> to identify which checks are failing.

Some Oracle Identity Domains are configured to require a primary email address for all new users. This setting cannot be changed via the OCI CLI.

Solution:

Disable the email requirement through the OCI console:

1. Open the Oracle Cloud Console .
2. Go to Identity & Security > Domains.
3. Click on your identity domain (usually Default).
4. Go to Settings > Domain Settings.
5. Find Primary Email Address is required and toggle it off.
6. Save the changes.
7. Re-run the onboarding script.

Alternatively, you can create the user manually in the console with an email address, then re-run the script. The script detects the existing user and continues with the remaining setup steps.

This error occurs when the OCI CLI is not properly configured or the tenancy ID cannot be resolved.

Solution:

# Check current OCI CLI configuration
oci setup config
 
# Verify the active profile
oci iam tenancy get --tenancy-id <tenancy-id>
 
# If running in Oracle Cloud Shell, the tenancy ID is auto-detected
# Confirm the environment variable is set
echo $OCI_TENANCY
 
# Provide the tenancy ID explicitly if needed
python onboard.py --tenancy-id ocid1.tenancy.oc1..<unique-id>

This error occurs when an IAM user with the specified name already exists in the tenancy.

Solutions:

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

   python onboard.py --user-name "r7cs_harvester" --tenancy-id "ocid1.tenancy.oc1..<unique-id>"

2. Use a different user name:

   python onboard.py --user-name "r7cs_harvester_v2" --tenancy-id "ocid1.tenancy.oc1..<unique-id>"

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

   python onboard.py --undeploy --user-name "r7cs_harvester" --tenancy-id "ocid1.tenancy.oc1..<unique-id>"

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

Solutions:

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

   # Download both policy files
   python onboard.py --download-policies-only ./policies
    
   # Copy the policies directory to the deployment environment, then run
   python onboard.py \
     --user-name "r7cs_harvester" \
     --tenancy-id "ocid1.tenancy.oc1..<unique-id>"

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

OCI requires a version-date to update a policy in place. If a policy was created without one, the update command fails.

The script handles this automatically: when no version-date is detected, it deletes the existing policy and recreates it with the merged statements and today’s date as the version-date. No manual action is required, but ensure you have permissions to both delete and create policies.