Cloud App Analyzer AWS Onboarding Script

This topic explains how to use an AWS CloudFormation Template script to automate the onboarding of accounts into the Cloud App Analyzerapplication. Each step of the script is outlined to help users understand its purpose and functionality.

The AWS CloudFormation template is structured according to AWS CloudFormation best practices and includes the following main sections:

  • AWSTemplateFormatVersion: Specifies the template format version (2010-09-09)

  • Description: Provides a brief description of the template’s purpose

  • Mappings: Contains constant values used throughout the template

  • Resources: Defines all AWS resources created by the template

  • Outputs: Specifies values that are returned upon stack creation

  • Metadata: Contains additional information about the stack configuration

Detailed Section Analysis

Mappings Section

The Mappings section contains constant values related to Secret Manager configuration:

Copy 
"Mappings": {
    "Constants": {
        "SecretManager": {
            "SecretRole": "",
            "SecretId": "",
            "SecretRegion": "us-east-1",
            "AuthToken": ""
        }
    }
}    

These constants facilitate secure cross-account access to the Prevasio service by defining:

  • The IAM role used to access secrets

  • The specific secret ID containing API connection details

  • The AWS region where the secret is stored

  • An authentication token for the Prevasio API

Resources Section

The Resources section defines all AWS resources created by the template. Key resources include:

  1. ApiConnectionSecret
    Creates a Secrets Manager secret to store the Prevasio API connection properties:

    Copy 
    "ApiConnectionSecret": {
        "Type": "AWS::SecretsManager::Secret",
        "Properties": {
            "Description": "This secret contains Prevasio API connection properties"
        }
    }                    

    This secret will store authentication and connection details needed for communicating with the Prevasio API.

  2. LambdaExecutionRole
    Defines an IAM role for Lambda functions with permissions to:

    • Execute basic Lambda operations

    • Assume the Prevasio secret role

    • Access and update the API connection secret

    • Interact with ECR repositories

    Copy 
    "LambdaExecutionRole": {
        "Type": "AWS::IAM::Role",
        "Properties": {
            "ManagedPolicyArns": ["arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"],
            "AssumeRolePolicyDocument": { /* Trust policy */ },
            "Policies": [{ /* Inline policy permissions */ }]
        }
    }                

    The inline policy grants specific permissions for cross-account secret access and ECR repository management, which are crucial for the onboarding process.

  3. GetUUIDFunction and GetUUID
    A Lambda function and custom resource that generates a UUID for secure cross-account role assumption:

    Copy 
    "GetUUIDFunction": {
        "Type": "AWS::Lambda::Function",
        "Properties": {
            "Runtime": "python3.9",
            "Handler": "index.handler",
            "Role": { "Fn::GetAtt": ["LambdaExecutionRole", "Arn"] },
            "Timeout": 30,
            "Code": { "ZipFile": "/* Python code to generate UUID */" }
        }
    }                    

    The generated UUID serves as an external ID in the trust relationship, providing an additional security layer for cross-account access.

  4. PrevasioCSPMRole
    Creates the primary IAM role that Prevasio will assume to perform security scanning:

    Copy 
    "PrevasioCSPMRole": {
        "Type": "AWS::IAM::Role",
        "Properties": {
            "AssumeRolePolicyDocument": { /* Trust policy allowing Prevasio to assume this role */ },
            "Policies": [{ /* Additional permissions for CSPM scanning */ }],
            "ManagedPolicyArns": ["arn:aws:iam::aws:policy/SecurityAudit"]
        }
    }                        

    Key aspects of this role:

    • Uses the generated UUID as an external ID condition for role assumption

    • Attaches the AWS SecurityAudit managed policy for read-only security assessment

    • Includes additional permissions needed for comprehensive security scanning

  5. OnboardAccountFunction and OnboardAccount
    A Lambda function and custom resource that handles the account onboarding process:

    Copy 
    "OnboardAccountFunction": {
        "Type": "AWS::Lambda::Function",
        "Properties": {
            "Runtime": "python3.9",
            "Handler": "index.handler",
            "Role": { "Fn::GetAtt": ["LambdaExecutionRole", "Arn"] },
            "Timeout": 60,
            "Code": { "ZipFile": "/* Python code for onboarding */" }
        }
    }                

    This function performs several key operations:

    • Retrieves API connection details from Prevasio’s secret

    • Updates the local API connection secret

    • Modifies ECR repository policies if needed

    • Calls the Prevasio API to register the account

    • Reports onboarding success or failure

  6. ImagePushHandlerFunction
    A Lambda function that processes ECR image push events:

    Copy 
    "ImagePushHandlerFunction": {
        "Type": "AWS::Lambda::Function",
        "Properties": {
            "Runtime": "python3.9",
            "Handler": "index.handler",
            "Role": { "Fn::GetAtt": ["LambdaExecutionRole", "Arn"] },
            "Timeout": 10,
            "Code": { "ZipFile": "/* Python code for handling image push events */" },
            "Environment": { /* Environment variables */ }
        }
    }            

    This function sends container image push events to Prevasio for potential container security scanning.

  7. ImagePushedEventBridgeRule and InvokeImagePushHandlerFunctionPermission
    Sets up EventBridge to trigger the image push handler when images are pushed to ECR:

    Copy 
    "ImagePushedEventBridgeRule": {
        "Type": "AWS::Events::Rule",
        "Properties": {
            "EventPattern": { /* ECR image push event pattern */ },
            "Targets": [{ /* Target configuration */ }]
        }
    }                    

    This enables automated notifications to Prevasio when new container images are available, facilitating continuous security scanning.

Outputs Section

The template provides three output values:

Copy 
"Outputs": {
    "PrevasioRoleARN": {
        "Description": "The ARN of the cross-account role for Prevasio CSPM security scanner.",
        "Value": { "Fn::GetAtt": ["PrevasioCSPMRole", "Arn"] }
    },
    "StackVersion": {
        "Description": "Prevasio CSPM stack version.",
        "Value": "3.0"
    },
    "OnboardingResult": {
        "Description": "The result of onboarding the AWS account with Prevasio CSPM.",
        "Value": { "Fn::GetAtt": ["OnboardAccount", "Data"] }
    }
}        

These outputs provide:

  • The ARN of the created cross-account role

  • The stack version for tracking purposes

  • The result of the onboarding process

Metadata Section

Copy 
"Metadata": {
    "kspm": "disabled",
    "vm_scan": "disabled"
}            

Indicates that Kubernetes Security Posture Management (KSPM) and VM scanning features are disabled in this configuration.

Security Considerations

This template implements several security best practices:

  • External ID: Uses UUID-based external IDs for secure cross-account role assumption

  • Least Privilege: Applies specific IAM permissions tailored to required functions

  • Secure Communication: Encrypts API credentials using AWS Secrets Manager

  • Read-Only Access: Primarily uses read-only permissions for security scanning

Workflow Overview

  1. The stack creates a cross-account IAM role (PrevasioCSPMRole).

  2. A unique UUID is generated as an external ID for secure role assumption.

  3. The onboarding function registers the account with Prevasio’s API.

  4. ECR repository policies are configured to allow secure scanning.

  5. An EventBridge rule is set up to notify Prevasio of new container images.

This CloudFormation template automates the entire onboarding process, simplifying customer setup while maintaining security best practices.