Onboarding AWS Environments to Intelligence

This topic describes how to onboard an AWSClosed Amazon® Web Services. Public cloud platform that offers global compute, storage, database, application and other cloud services. environment to Intelligence with an automated onboarding experience. For a legacy procedure with manual onboarding, see Custom Onboarding of AWS Environments to Intelligence.

Your AWS environment has to be onboarded to CloudGuard before you can onboard it to Intelligence. If your account is not yet onboarded, follow the instructions in Unified Onboarding of AWS Environments.

How It Works

Intelligence uses VPC Flow Logs and CloudTrail logs from your AWS account. These logs have to be stored in an Amazon S3 bucket. Intelligence analyzes only the new logs that CloudGuard starts to receive after you onboarded the account to Intelligence. The S3 bucket sends PutObject event notifications to an SNS topic, and the topic is connected through an SNS Subscription to the Intelligence SQSClosed Reliable and scalable hosted queues for storing messages as they travel between computers.-queue endpoint. When CloudGuard receives this event notification, it runs the S3 GetObject on the path specified in the notification to retrieve the log.

During the onboarding process, CloudGuard establishes the connection to receive notifications regarding new log files and obtains permissions to run the S3 GetObject on one or more log buckets. For easier handling of the required configuration, CloudGuard can create a CloudFormation Template (CFT) to run in your AWS environment.

S3 bucket for each account

The architecture diagram below illustrates how to onboard an S3 bucket for each account.

Centralized S3 bucket

A centralized S3 bucket is an Amazon S3 bucket that stores logs for multiple AWS accounts. Use the onboarded centralized S3 bucket to easily monitor and run log analysis of all your AWS accounts that send logs to this S3 bucket.

The onboarding initiates from the AWS account that has the centralized S3 bucket already configured in its environment. CloudGuard then retrieves a list of AWS accounts that send Flow Logs or CloudTrail logs to the centralized S3 bucket. You can select the applicable AWS account(s) to onboard from this list. To onboard all AWS accounts to Intelligence, use Automatic Onboarding.

The onboarding of an organizational unit is supported only when a centralized S3 bucket is configured in your AWS organization structure.

The architecture diagram below illustrates how to onboard several AWS accounts to a centralized S3 bucket.

Known Limitations

  • AWS allows you to set only one event notification on a specific prefix with a specific event type. You cannot onboard an S3 bucket if the bucket has the event notifications set, and one of the notifications meets two conditions below:

    • The notification has an empty prefix filter set (that is, all of the bucket) or an explicit AWS log-prefix set.

    • The event type is PutObject or all object-created events.

  • For Intelligence, you can onboard an S3 bucket through one SNS topic only.

  • Intelligence cannot analyze the involved IAMClosed Identity and Access Management (IAM) - A web service that customers can use to manage users and user permissions within their organizations. policies: S3 bucket policy, existing SNS topic policy, and policies of the CloudGuard IAM trust role. Therefore, permission-related issues can occur when you create the onboarding stack.

  • You cannot onboard an account to Intelligence if you use an encrypted SNS topic.

For these and other CloudGuard limitations, see Known Limitations.

Onboarding to Account Activity or Traffic Activity

Note - You must onboard Flow Logs and CloudTrail separately for each account.

Follow these steps in CloudGuard to enable Account Activity with CloudTrail:

  1. In CloudGuard, open the Environments page from the Assets menu.

  2. Select the AWS environment to be onboarded to Intelligence.

  3. In the account row and the Account Activity column, click Enable to start the Intelligence onboarding wizard.

    As an alternative, you can click and open the environment page. From the top right, select Add Intelligence > CloudTrail.

  4. Follow the on-screen instructions to complete the wizard.

Follow these steps in CloudGuard to enable Traffic Activity with Flow Logs:

  1. In CloudGuard, open the Environments page from the Assets menu.

  2. Select the AWS environment to be onboarded to Intelligence.

  3. In the account row and the Traffic Activity column, click Enable to start the Intelligence onboarding wizard.

    Or, you can click and open the environment page. From the top right, select Add Intelligence > Flow Logs.

  4. Follow the on-screen instructions to complete the wizard.

Wizard Stages

  1. Welcome - Read carefully the onboarding prerequisites and make sure that the AWS environments to be onboarded meet all the required conditions.

  2. S3 Buckets

    1. Select one or more S3 bucketsClosed A bucket is a container for objects stored in Amazon S3 (Amazon Simple Storage Service). to be onboarded.

    2. Set Auto Onboard to ON to let CloudGuard:

      • detect all onboarded AWS accounts that send logs of a certain type to this centralized S3 bucket

      • automatically onboard these accounts to Intelligence

      The toggle button is enabled only for new buckets that you select to onboard. To update the onboarded bucket(s) mode, go to the Intelligence tab on the environment page. For more information, see Automatic Onboarding.

    You can see the status details for each S3 bucket on the right pane. The details help you troubleshoot issues that prevent onboarding of the S3 bucket. For more information on possible issues, see Errors, Warnings, and Troubleshooting.

  3. CloudFormation Template - Create a stack from the provided CFT. For more information, see CFT Resources and Permissions.

    During the process, CloudGuard shows the onboarding status on the bottom part of the page. Click Check Now to see the current status of the configuration. For more information, see Status Check.

    CloudGuard skips this step if your AWS account already has all the required resources.

  4. Accounts - For centralized S3 buckets, select the AWS accounts that you want to onboard and see their logs.

    CloudGuard skips this step if only one AWS account sends logs to this S3 bucket.

  5. Done - Make sure the onboarding is successful.

AWS Onboarding Permissions

When you launch a CloudFormation stack, the stack gets its permissions through two primary processes.

  1. It inherits the permissions of the user who creates the stack. The user has one of these credentials:

  2. It receives an IAM Role assigned directly to the stack.

    To assign a dedicated role to the onboarding stack, the role must allow for the AWS CloudFormation service to assume it.

For successful onboarding, it is necessary to give the stack all the necessary permissions.

Some of the permissions include a Delete step. It is applicable when it is necessary to create a dedicated IAM role for the stack, rather than use the user's permissions. As a result, this role is used for the deletion of the stack.

CFT Resources and Permissions

Common Permissions

CloudGuard generates a customized CloudFormation Template based on your bucket selection. Based on the setup in your account, the template can include these resources:

  • IAM inline policy added to the CloudGuard trust role.

    The policy grants these permissions:

  • SNS Topic – If the log bucket is not pre-connected to SNS topics

  • SNS Topic Policy - The policy allows all of the buckets in the AWS account to publish event notifications to the topic. The policy allows subscription to the Intelligence SQS queue endpoint.

  • SNS Subscription to the Intelligence SQS queue endpoint.

  • Lambda function - It is used to create a correct event notification on the S3 bucket if there is no such notification.

  • CloudWatch Log Group – To store logs from Lambda.

  • Lambda Execution IAM Role and Lambda Execution IAM Policy - To grant the lambda the following permissions:

    • logs:CreateLogStream, logs:PutLogEvents – Allow logging in CloudWatch, standard lambda permissions.

    • s3:GetBucketNotification, s3:PutBucketNotification – Allow reading the existing notifications on the bucket and appending the correct one. This permission applies only to the bucket onboarded in the process.

Resources for Multiple Buckets

If you select multiple buckets from different regions as part of one onboarding process, then is necessary for CloudGuard to have more resources. These resources are necessary because CloudFormation does not allow interaction with multiple regions from one stack.

  • Stack Sets – A stack set for each selected region.

  • Stack – A stack for each region.

  • Two IAM roles that CloudGuard role does not have permission to assume.

    • IAM Role (Admin Custom Role) - The role that can be assumed by CloudFormation and can assume the execution role below.

    • IAM Role (Execution Custom Role) – The role with the exact permissions that the CFT needs to complete.

IAM Custom Role

If necessary, configure a custom IAM role to reduce the scope of your administrative role and allow CloudFormation to use this role to create, change, or delete resources in the stack.

This custom role can be assigned through:

  • A regular IAM user

  • A federated user

  • An IAM role

You can select this role in the Permissions section when you configure stack options.

Important - To make sure that the stack creation is successful:

  • Make sure that the IAM user (or the federated user, or the IAM role) that creates the stack has all the permissions for the involved resources listed above.

  • After you have generated a template, do not change the account configuration until the template reaches a steady (not in progress) state.

Status Check

You can see in real time the status of part of the configurations added as part of the CFT.

This process verifies that:

  • All required S3 bucket event notifications were added to the correct SNS topics, with the correct prefix filter and event type.

  • All connected SNS topics are at this time subscribed to the correct Intelligence SQS endpoint based on the onboarding log type.

This process does not make sure that the permissions are added successfully to the CloudGuard trust role. And it does not make sure that the stack reached a Create_Complete state.

Possible results:

  • Complete - The checked configurations appended successfully. You can continue with the onboarding process.

  • Not Complete - Some parts of the configuration are missing. Possibly, the stack creation did not complete. Wait until the stack reaches a stable state and retry the call.

Automatic Onboarding

CloudGuard can detect all onboarded AWS accounts that send logs of a certain type to the centralized S3 bucket and automatically onboard them to Intelligence.

  • For accounts that send CloudTrail logs to the centralized S3 bucket, CloudGuard can automatically onboard them to Account Activity.

  • For accounts that send Flow Logs to the centralized S3 bucket, CloudGuard can automatically onboard them to Traffic Activity.

If you do not select this option, you have to onboard each account to Intelligence manually.

To update the Auto Onboard status:

  1. On the Assets > Environments page, click to open an environment onboarded to Intelligence.

  2. Go to the Intelligence tab.

  3. In the Auto Onboard column, click the toggle button to change the status of automatic onboarding.

Note - Automatic Onboarding is applicable to a certain log type on the entire bucket. On the environment page, Intelligence tab, you can sometimes see more than one row of a bucket for different log scopes (VPCs). However, when you enable Automatic Onboarding on one row, it is enabled on all other rows of the same bucket and the same log type.

Errors, Warnings, and Troubleshooting

When you select from available S3 buckets for onboarding, you can see the bucket status on the right pane. The bucket status can be:

  • Available - You can continue to the next step and onboard the S3 bucket.

  • Onboarded - This S3 bucket is already onboarded. For centralized S3 buckets, you can continue and onboard more accounts with the bucket.

  • Cannot onboard - You cannot onboard this S3 bucket. Resolve the related issue or select a different S3 bucket.

    Note - Some AWS account configurations do not allow S3 bucket onboarding, for example, when the S3 bucket is already connected to a non-SNS endpoint.

Errors prevent your S3 bucket from onboarding; with warnings, you can continue the process.

Best Practice - Attempt to resolve issues from a status warning before you continue to onboard the S3 bucket. Although CloudGuard allows you to move on to the next step, this can cause Intelligence not to do a full analysis of your account.

If you cannot successfully finish the onboarding process:

Onboarding Verification

When the onboarding is complete, make sure that the new logs of the onboarded AWS account start to appear in the CloudGuard portal in Events > Cloud Logs > Account Activity or Network Traffic. This can take less than 30 minutes.

Troubleshooting

Problem: During onboarding to Intelligence, an S3 bucket of logs does not appear in the list.

The issue of not seeing an S3 bucket of logs in the onboarding wizard can occur in both CloudTrail and Flow Logs, though it is more common with Flow Logs. This is because CloudTrail is often enabled across the entire organization, whereas Flow Logs can be missing due to a lack of network setup in the environment.

In a typical AWS environment, especially in organizations, there is often a dedicated logging environment with a centralized S3 bucket storing logs for the entire organization. Sometimes, this logging environment does not have Flow Logs enabled because there might not be any network setup or logs to record.

To resolve the issue:

  1. Verify that Flow Logs/CloudTrail are configured in the AWS environment where the S3 bucket is located.

  2. If Flow Logs/CloudTrail are not configured in the account of the bucket, consider these options:

More Links