Security Hub CSPM to OCSF Migration Tool

Migrate AWS Security Hub CSPM automation rules to OCSF format with automated field mapping and CloudFormation template generation.

Prerequisites

• AWS CLI: Latest version for CloudFormation deployment support

• AWS Credentials: Configure AWS CLI with credentials for the Security Hub delegated admin account

• Permissions:

  Migration Scripts - Required to discover and transform existing CSPM rules:

  "securityhub:DescribeHub",
  "securityhub:ListAutomationRules",
  "securityhub:BatchGetAutomationRules",
  "securityhub:GetFindingAggregator",
  "securityhub:ListAutomationRulesV2"

  CloudFormation Deployment - Required to deploy the generated template:

  "cloudformation:CreateStack",
  "cloudformation:UpdateStack",
  "cloudformation:DescribeStacks",
  "cloudformation:CreateChangeSet",
  "cloudformation:DescribeChangeSet",
  "cloudformation:ExecuteChangeSet",
  "cloudformation:GetTemplateSummary",
  "securityhub:CreateAutomationRuleV2",
  "securityhub:UpdateAutomationRuleV2",
  "securityhub:DeleteAutomationRuleV2",
  "securityhub:GetAutomationRuleV2",
  "securityhub:TagResource",
  "securityhub:ListTagsForResource"

• Python: Python 3.12+ with latest boto3 and pyyaml packages

# Update AWS CLI
pip install --upgrade awscli

# Install Python dependencies
pip install --upgrade boto3 pyyaml

Quick Start

# Basic migration (rules created in DISABLED state for safety)
# Replace region placeholders with actual regions such as us-east-1, us-east-2, etc.
python migrate_automation_rules.py --regions region-1,region-2,... --output-dir ./migration-output

# Create rules in ENABLED state (skip manual validation step)
# Recommended approach is to create in disabled state, review migrated rules, and then update to enabled, but this option allows you create all new rules in enabled state
# Replace region placeholders with actual regions such as us-east-1, us-east-2, etc. where you like to discover existing Securit Hub CSPM automation rules
python migrate_automation_rules.py --regions region-1,region-2,... --output-dir ./migration-output --create-enabled

What It Does

The migration orchestrator calls three scripts in sequence:

1. fetch_cspm_automation_rules.py - Discovers existing CSPM rules across specified regions
2. convert_cspm_rules_to_OSCF.py - Transforms ASFF rules to OCSF format with field mapping
3. generate_template.py - Creates CloudFormation templates for deployment

Deployment Strategies

• Home Region (Recommended): Deploy all rules to OCSF home region with region filters
• Region-by-Region: Deploy separate templates to each region (fails if home region configured)

Output Files

All files are created in your specified output directory:

• original-rules.json - Discovered CSPM rules
• transformed-rules-config.json - OCSF-compatible configuration
• security-hub-migrated-rules-cfn-template.yaml - CloudFormation template
• migration-report.md - Detailed analysis and warnings
• MIGRATION_SUMMARY.md - Final summary with deployment instructions
• discovery.log - Detailed logs from rule discovery
• transformation.log - Detailed logs from rule transformation
• migration-orchestrator.log - Orchestrator execution logs

Deploy Rules

The migration scripts will provide a CloudFormation template titled "security-hub-migrated-rules-cfn-template.yaml" by default. If you run the migration in "Region-by-Region" mode, there will be one CloudFromation template per region you specified. You can deploy the template(s) via the CloudFormation console or using the commands below.

Important: Navigate to your output directory before running deployment commands.

Deploy Command

Update file names and region if needed

# Navigate to the output directory (default: ./migration-output)
cd ./migration-output

# Deploy the CloudFormation template, update region and stack name if needed
# Repeat for each region if using Region-by-Region deployment, each template will have region added to name
aws cloudformation deploy \
  --template-file security-hub-migrated-rules-cfn-template.yaml \
  --stack-name security-hub-migrated-rules \
  --region us-east-1

Rule Status Options

By default, rules are created in DISABLED state for safety:

• Allows validation in Security Hub console before activation
• Prevents unintended finding updates during testing
• Recommended for production environments

To create rules in ENABLED state, use the --create-enabled flag:

python migrate_automation_rules.py --regions us-east-1 --output-dir ./output --create-enabled

Enable Rules After Validation

If rules were created in DISABLED state, you have two options to enable them:

Option 1: Enable via Security Hub Console This is the suggested method if you want to review any matching findings for each new automation rule before enabling it. To do this:

1. Navigate to AWS Security Hub console
2. Go to the Automations page
3. Select each rule you want to enable by clicking on its name
4. Click "Edit"
5. Review the criteria and actions, then click "Preview matching findings"
6. Once validated, select "Enabled" under "Rule Status"
7. Click save changes

You can also enable your automation rules in bulk via the console. To do this:

1. Navigate to AWS Security Hub console
2. Go to the Automations page
3. Select each rule you want to enable using the checkbox next to the rule order. Or, if you'd like to select all rules click the box at the very top left of the automation rule table.
4. Click "Actions" select "Enable"

Option 2: Re-run Migration with --create-enabled Flag This will regenerate a new template with all rules created in an enabled status. This can be used to update the existing stack. However, any direct changes made to automation rules via the console will be lost. If automation rules were modified manually during validation, use option 1.

Step 1: Re-run the migration with --create-enabled flag

# Update region as needed
python migrate_automation_rules.py --regions us-east-1 --output-dir ./migration-output --create-enabled

Step 2: Navigate to the output directory

cd ./migration-output

Step 3: Update the CloudFormation stack

# Update stack-name and region as needed
aws cloudformation update-stack \
  --stack-name security-hub-migrated-rules \
  --template-body file://security-hub-migrated-rules-cfn-template.yaml \
  --region us-east-1