If you're having trouble at any stage please contact us at support@skyformation.com. 

Notes

Multi region is only available from release 2.4.185 and later.

Preface

The goal of this guide is to add a new Amazon Web Service (AWS) connector to your SkyFormation Platform.

Prerequisites

1. Open Outbound communication to *.amazonaws.com:443

Procedure outline

During this procedure you will go through the following steps:

1. Review the supported AWS services and perform any AWS configuration steps that are required.
2. Choose your preferred authentication method.
3. Create IAM policy and other IAM entities based on your chosen authentication method.
4. On board the cloud connector via the Skyformation UI.

Before you start

AWS organizations

AWS SCP (Service Contol Policies) that are defined in the AWS Organizations infrastructure could potentially override the IAM policies that we will configure during this procedure. If your AWS infrastructure uses SCP, verify that it does not have overriding policies that will later block the IAM policies which could result in access denied errors.

AWS China

AWS in China is a completely different partition than the global AWS partition. Not all of the services that are offered in the global partition are also available in China and some services differ significantly. At this point, our support for AWS China accounts is only available through the Skyformation AWS multi tenant connector even for single tenant accounts. 

Step 1: Review the supported AWS Data sources, permissions and required Configuration

Step 2: Choose your preferred Authentication method

AWS Cloud Connector Authentication Options

Skyformation offers 3 methods for cloud connectors module authentication with AWS:

1. InstanceProfile:

   This is the recommended authentication method if the instance where SkyFormation runs is in AWS EC2, and the AWS account we want to collect data from is the same as the one where the machine is hosted.

   To use this method, you will need to create and IAM policy and assign it to a role, then assign the role with the required permissions to the EC2 instance running the SkyFormation app.
   For further reading, https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html.

2. STSAssumeRole: 

   This is the recommended method for authentication by AWS. It also allows for cross-account access.

   The credentials for the IAM user (i.e. "Basic") are used to authenticate with the user that will then assume the role. That user does not need any other permission other than the ability to assume the role specified.

   For further reading: https://docs.aws.amazon.com/cli/latest/reference/sts/assume-role.html.
   

3. Basic : via the access key and secret of an IAM User.

For any of the above methods, an IAM Policy is needed. 

Step 3: Create an IAM Policy

1. In your AWS console, navigate to Services --> IAM --> Policies --> Create policy.
2. Click on the "JSON" tab, to get an online editor.
3. Replace the default, empty Json with the JSON in (4) below. The JSON contains several statements:
   1. The first statement is a read-only statement without any reference to actual resources. It contains all of the required permissions, and it is highly recommended to use it as is. This way all supported services will get auto discovered, even if will be used only in the future. However you may remove some of the permissions based on the table of supported services above.
   2. The rest of the statements contain references to actual resources.
      The second statement contains references for S3 buckets and that are used for CloudWatch logs and Redshift audit logging. 
      The third statement contains the deleteObject permission which is required only for cloudwatch logs retrieval , related to the special bucket created specifically for this purpose.
      The last statement contains references for SQS queues , used for SQS events and macie events.
       This means you will have to input the actual names of your S3 buckets and/or queues (See the relevant config links in the table above for how to create/find these buckets/queues ). If you don't know them or you don't currently use these services, you can remove the 2nd to 4th statement entries altogether.
      Please note that AWS may after you save the policy merge the 2nd and 4th statements, this is OK.

4. {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudtrail:DescribeTrails",
                "cloudtrail:LookupEvents",
                "iam:ListGroups",
                "iam:ListRoles",
                "iam:ListPolicies",
                "iam:ListUsers",
                "iam:ListAccountAliases",
                "iam:GetUser",
                "cloudwatch:DescribeAlarms",
                "cloudwatch:DescribeAlarmHistory",
                "guardduty:GetFindings",
                "guardduty:ListDetectors",
                "guardduty:ListFindings",
                "events:ListRules",
                "events:ListTargetsByRule",
                "redshift:DescribeEvents",
                "redshift:DescribeClusters",
                "redshift:DescribeLoggingStatus",
                "redshift:DescribeClusterParameters",
                "shield:ListAttacks",
                "shield:GetSubscriptionState",
                "inspector:ListFindings",
                "inspector:DescribeFindings",
                "inspector:ListAssessmentTemplates",
                "logs:DescribeLogGroups",
                "logs:CreateExportTask",
                "logs:DescribeExportTasks",
                "logs:CancelExportTask",
                "ec2:DescribeInstances",
                "ec2:DescribeRegions"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:GetBucketAcl",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::my-cloudwatch-logs-bucket-for-region1",
                "arn:aws:s3:::my-cloudwatch-logs-bucket-for-region2",
                "arn:aws:s3:::my-redshift-cluster1-db-audit-log-bucket",
                "arn:aws:s3:::my-redshift-cluster2-db-audit-log-bucket",
                "arn:aws:s3:::my-cloudwatch-logs-bucket-for-region1/*",
                "arn:aws:s3:::my-cloudwatch-logs-bucket-for-region2/*",
                "arn:aws:s3:::my-redshift-cluster1-db-audit-log-bucket/*",
                "arn:aws:s3:::my-redshift-cluster2-db-audit-log-bucket/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:DeleteObject"
            ],
            "Resource": [
               "arn:aws:s3:::my-cloudwatch-logs-bucket-for-region1",
               "arn:aws:s3:::my-cloudwatch-logs-bucket-for-region2",
               "arn:aws:s3:::my-cloudwatch-logs-bucket-for-region1/*",
               "arn:aws:s3:::my-cloudwatch-logs-bucket-for-region2/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "sqs:DeleteMessage",
                "sqs:DeleteMessageBatch",
                "sqs:ReceiveMessage"
            ],
            "Resource": [
                "arn:aws:sqs:my-region:my-account-id:my-macie-sqs", 
                "arn:aws:sqs:my-region:my-account-id:my-cloudtraildata-sqs" 
            ]
        }
     ]
   }
   

 Note: if your S3 buckets are encrypted , you will need to add more permissions to the policy. Please review the following guide for more details: https://aws.amazon.com/premiumsupport/knowledge-center/decrypt-kms-encrypted-objects-s3/

Step 4 : Create an IAM User - Required for Basic and AssumeRole Authentication

1. In your AWS console, navigate to Services --> IAM --> Users --> Add user.
2. Give your user a name and check the programmatic access checkbox:
   
3. When you click next, you will be transferred to the set permissions page.
4. For Basic Authentication only, Choose "Attach Existing Policies Directly", and search for the policy you created in the previous step. (For STSAssumeRole authentication skip this step).
5. Continue the user creation process (tags are optional) and finish the user creation. You will see a screen like the following :
   

        You need the following attributes in the next step:

        - Secret Access Key (e.g. see in the diagram an example)

        - Access Key ID (e.g. see in the diagram an example)

       Note: The Access Key ID and Secret Access Key in the diagram are not valid keys. 

Step 5: Create an IAM Role - Required for AssumeRole and InstanceProfile authentication

1. Navigate to IAM -> Roles. Click "Create Role"
2. Select AWS Service box, and EC2 service and Click "Next: Permissions"
   1. This will create a "Trust relationship" that'll allow Allows EC2 instances to call AWS services on your behalf. We will modify the Trust relationship document later, per authentication method you'll choose
3. Search the policy created earlier and check its checkbox. Click "Next: Tags"
4. Optionally add tags. Click "Next: Review"
5. Give it a meaningful name, e.g. ExabeamCCAWSConnectorRole, and description. Click "Create Role".
6. Search for the created role and click on it. Copy aside the role's ARN.
   
   

 Step 6: Finalize AssumeRole and InstanceProfile authentication configuration

AssumeRole:

1. Navigate to IAM -> Roles and search for the role created earlier
2. Allow a specific user to use (assume) the role
   1. Go to "Trust relationships" tab, click "Edit trust relationship"
   2. Make sure the "Statements" array contains the following entry (modify accordingly):

      {
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::123456789012:user/ccuser"
        },
        "Action": "sts:AssumeRole"
       }

   3. Click "Update Trust Policy"

InstanceProfile:

1. Navigate to IAM -> Roles and search for the role created earlier
2. Allow EC2 instances to use (assume) the role
   1. Go to "Trust relationships" tab, click "Edit trust relationship"
   2. Make sure the "Statements" array contains the following statement entry:

      {
        "Effect": "Allow",
        "Principal": {
          "Service": "ec2.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
       }

   3. Click "Update Trust Policy"
3. Navigate to AWS EC2 service
4. Right-click on the instance where Cloud Connectors in installed, Click Instance Settings -> Attach/Replace IAM Role
5. Choose the role from the drop-down list, and Apply

Step 7: On-Board the Cloud Connector

1. Logon to your SkyFormation Platform:
2. Navigate via left navigation panel to "Settings" section
3. Navigate via New Settings left navigation panel to "Accounts" section
4. Click the "Add Account" bottom
   
   
5. Fill in the following information:
   1. Tenant - mandatory
   2. Account Name - mandatory . Give the account a meaningful name for you. This will become your cloud app  connector name displayed in the SkyFormation platform and added to entire events sent to your SIEM system from this connector as identifier.
   3. Description - Optional
6. Choose the authentication method.
   
   1. If you chose the basic authentication, fill in the access key and secret of the designated user which you created in the previous steps.
      
   2. if you chose the STSAssumeRole Authentication, the following additional information will be needed:
      
      1. Role ARN - the ARN of the role, which has the permissions above assigned to it
      2. Role session name - a unique name to identify the use of this role, e.g. "SkyFormation"
      3. External ID - Optional. A unique identifier that might be required when you assume a role in another account
      4. Account ID - the AWS account ID to which we're using these credentials to connect to; a 12 digit number
   3. If you chose ProfileInstance authentication, it requires only the Account ID - the AWS account ID to which we're using these credentials to connect to; a 12 digit number.
      
      
7. Click "SAVE" bottom, click on "test connection" to verify basic connectivity between the cloud connector and AWS, and click on "Start".

 Make sure the "STATUS" of the new AWS connector in the table is OK and green.

After a few minutes, you can click on the status of the account and see the endpoints status. You may inactivate/activate endpoints per your specific needs. 

When you reach this point you are done. The rest if the steps are optional. 

Step 8: Specific configuration for CloudWatch Logs and AWS Inspector

if you have AWS CloudWatch Logs , or AWS Inspector, after a few minutes services will automatically be discovered by the cloud connector. For these 2 services, extra information is required. When you navigate to Settings --> Accounts --> choose your relevant AWS account --> Edit, you will see the option to enter the additional information.

CloudWatch Logs - Mandatory

In order to pull the data, you must fill in the relevant S3 buckets for each region you want to pull the data from. Fill in the bucket names (these buckets should also be part of the permissions Json and these buckets should also have the correct ACL, see  Configure CloudWatch Logs) and click on "Done".

Inspector Pull Mode - Optional (default is "Full").

The options are:

1. Full : choosing this option, you will receive the current inspector finding each time skyformation            pulls for inspector information, regardless if a finding was previously reported by skyformation or not.
2. Unique: choosing this option, you will only receive events for inspector findings which are new, i.e. were not reported by skyformation in the previous syncs.

For example, in time t0 skyformation pulled inspector and got findings a,b,c. Finding b was then            corrected. Then, in time t1 skyformation pulled again and got findings a,b,d.

• Choosing full mode, in t0 you will get events for findings a,b,c and in t1 you will get a,b,d.
• Choosing unique mode, in t0 you will get events for findings a,b,c and in t1 you will get only d.