Enabling AWS integrations

Enable AWS HostID and optional Security Hub and CloudWatch integrations.

Vectra AWS Integrations

In addition to all the standard integrations available in the hardware appliance version of the Vectra Brain, the AWS Brain allows native integrations with various AWS services with the goal of either gathering context or publishing alerts. Vectra AWS integrations require adding AWS IAM users, roles, and policies.

Security Hub publishing (Quadrant UX deployments only) will only publish Host scores involving AWS workloads. CloudWatch health and audit logs (Quadrant UX deployments only) are typically only desired in AWS for customers whose Brain is deployed in AWS.

Vectra has 3 AWS integrations:

• HostID

  • This is the most common AWS integration and configuring it is considered a best practice.

  • Instructions are provide below.

  • Adding relevant context (Host ID, OS, instance ID, tags, etc) about Amazon EC2 hosts when observed by Vectra.

  • While technically optional, it is a best practice is to enable this integration when you have Hosts deployed in AWS that are monitored by Vectra. Detections in Vectra are tied to a Host or Account entity. To be more easily actionable and for some algorithms to support learning, Detections must be attributable to a Host (including statically defined hosts), rather than a generic Host IP address or other similar network artifact – especially as many of these network artifacts are transient in the cloud. To this end, the Vectra Brain can directly query the describe instance APIs in AWS to extract the instance identifier, tags, Amazon VPC and other metadata for Amazon EC2 VMs.

  • The AWS account used for this integration may be set up as a standalone account or as a federated organization with a parent account and multiple child accounts.

• AWS Security Hub (Quadrant UX deployments only)

  • Please see AWS Security Hub integration for configuration details.

    • Please note that it is required to configure AWS HostID integration before configuring Security Hub integration.

  • The Vectra Brain can natively publish Host scores involving AWS workloads in AWS Security Findings Format (ASFF) to the AWS Security Hub service. This is optional.

• CloudWatch (Quadrant UX deployments only)

  • Instructions are provided below.

  • Publishing health and audit logs to Amazon CoudWatch. This is optional.

AWS HostID Integration

AWS HostID Integration Introduction

• The HostID integration for AWS VPCs enables adding relevant context (Host ID, OS, instance ID, tags, etc) about Amazon EC2 hosts when observed by Vectra.

• Detections in Vectra are tied to a Host or Account entity.

  • To be more easily actionable and for some algorithms to support learning, Vectra detections must be attributable to a Host (including statically defined hosts), rather than a generic Host IP address or other similar network artifact – especially as many of these network artifacts are transient in the cloud.

  • To this end, the Vectra Brain can directly query the describe instance APIs in AWS to extract the instance identifier, tags, Amazon VPC and other metadata for Amazon EC2 VMs.

• While technically optional, it is a best practice is to enable this integration when you have Hosts deployed in AWS that are monitored by Vectra.

  • This may be because you have vSensors deployed in AWS, or if you have connectivity to AWS that allows any of your other Vectra Sensors to observe communications with hosts deployed in AWS.

• The integration will provide additional artifacts that help with HostID's automated naming of hosts in your environment.

  • For more details on HostID, please see Understanding Vectra Detect Host Naming.

• The AWS account used for this integration may be set up as a standalone account or as a federated organization with a parent account and multiple child accounts.

Supporting Materials

Vectra makes CloudFormation templates available to enable easy creation of the users, roles and policies required.

HostIdTemplate.yml- Used for integration with the AWS Resource Manager to collect artifacts that provide details to Vectra's automated HostID capability.

883B

HostIdTemplate.yml

Open

HostIdFederatedParentTemplate.yml - Used for HostID in Federated AWS setups

2KB

HostIdFederatedParentTemplate.yml

Open

HostIdFederatedChildTemplate.yml - Used for HostID in Federated AWS setups

2KB

HostIdFederatedChildTemplate.yml

Open

The files can also be downloaded from your Brain after deployment from the following locations:

• https://<brain_hostname_or_IP>/resources/HostIdTemplate.yaml/serve_file

• https://<brain_hostname_or_IP>/resources/HostIdFederatedParentTemplate.yaml/serve_file

• https://<brain_hostname_or_IP>/resources/HostIdFederatedChildTemplate.yaml/serve_file

Configuration

The AWS account may be set up as a standalone account or as a federated organization with a parent account and multiple child accounts.

Standalone Accounts

If the deployment involves just a single AWS account, use CloudFormation to create the VectraCognitoHostIDv1 IAM user using the HostIdTemplate.yml. The template is also shown in an expandable code block below. Users can also be created manually if desired using the template as guide for the permissions required.

AWSTemplateFormatVersion: '2010-09-09'
Description: Vectra HostID User version 1
Resources:
  user:
    Properties:
      Policies:
        - PolicyDocument:
            Statement:
              - Action:
                  - iam:ListAccountAliases
                  - iam:SimulatePrincipalPolicy
                  - ec2:DescribeInstances
                  - ec2:DescribeRegions
                  - ec2:DescribeSubnets
                  - ec2:DescribeTrafficMirrorTargets
                  - ec2:DescribeTrafficMirrorSessions
                  - ec2:DescribeVpcPeeringConnections
                  - ec2:DescribeVpcs
                  - sts:GetCallerIdentity
                Effect: Allow
                Resource:
                  - '*'
            Version: '2012-10-17'
          PolicyName: vectra_hostid_permissions
      UserName: VectraCognitoHostIDv1
    Type: AWS::IAM::User

You may add as many credential sets as required if you have multiple AWS accounts that you wish to treat as standalone accounts. Once you have created the IAM user you must create a new Access key in AWS for the user. AWS has some documentation available here.

• Navigate to the user VectraCognitoHostIDv1 in the Identity and Access Management service.

• Click on the Security credentials tab and the Create Access key button.

  • This will generate a credential pair similar to the below screenshot.

  • Please take note of these credentials for later use in the Vectra UI.

• In the Vectra UI, navigate to Configuration > SETUP > External Connectors > AWS and click Edit.

• Turn On the Enable integration with AWS.

• Click Add Credential and fill out the form using the values you just noted and the appropriate Cloud Type.

  • The Alias can be any identifier you wish to use for this set of credentials in Vectra’s UI.

  • Enter access key ID and secret access key corresponding to the VectraCognitoHostIDv1 IAM user.

• Click Add.

• Click Save on the Enable integration with AWS Resource Manager configuration area.

• Look for the green check mark and a status of Connected.

Federated AWS Organizations with Parent and Child Accounts

For these types of organizations, Vectra supports role assumption at the child account level using an IAM user that is created at the parent account level.

• Use CloudFormation to create the VectraCognitoHostIDFederated IAM user in the parent account using the HostIdFederatedParentTemplate.yml file.

  • The user can also be created manually if desired using the template as guide for the permissions required.

  • The template is also shown in an expandable code block below.

AWSTemplateFormatVersion: '2010-09-09'
Description: Vectra HostID Federated User version 1
Outputs:
  ChildAccountRole:
    Description: The role name that will be assumed in all child AWS accounts
    Value: !Ref 'ChildAccountRole'
  ParentAccountUser:
    Description: The user name in the parent AWS account
    Value: !Ref 'ParentAccountUser'
Parameters:
  ChildAccountRole:
    Default: VectraCognitoHostID
    Description: The role name that will be assumed in all child AWS accounts
    MaxLength: '64'
    MinLength: '6'
    Type: String
  ParentAccountUser:
    Default: VectraCognitoHostIDFederated
    Description: The user name in the parent AWS account
    MaxLength: '64'
    MinLength: '6'
    Type: String
Resources:
  user:
    Properties:
      Policies:
        - PolicyDocument:
            Statement:
              - Action:
                  - sts:AssumeRole
                Effect: Allow
                Resource:
                  - !Join
                    - ''
                    - - arn:aws:iam::*:role/
                      - !Ref 'ChildAccountRole'
            Version: '2012-10-17'
          PolicyName: VectraCognitoHostID
      UserName: !Ref 'ParentAccountUser'
    Type: AWS::IAM::User

• Navigate to the user VectraCognitoHostIDFederated in the Identity and Access Management service.

• Click on the Security credentials tab and the Create Access key button.

  • This will generate a credential pair similar to the below screenshot.

  • Please take note of these credentials for later use in the Vectra UI.

• Use CloudFormation to create the VectraCognitoHostID role in each child account where Vectra vSensors will be deployed.

  • Use the HostIdFederatedChildTemplate.yml attached at the bottom of this page.

  • The user can also be created manually if desired using the template as guide for the permissions required.

  • The template is also shown in an expandable code block below.

AWSTemplateFormatVersion: '2010-09-09'
Description: Vectra HostID Federated Assume Role version 1
Outputs:
  ChildAccountRole:
    Description: The role name that will be assumed in all child AWS accounts
    Value: !Ref 'ChildAccountRole'
  ParentAccount:
    Description: The AWS account ID of the parent account
    Value: !Ref 'ParentAccount'
  ParentAccountUser:
    Description: The user name in the parent AWS account
    Value: !Ref 'ParentAccountUser'
Parameters:
  ChildAccountRole:
    Default: VectraCognitoHostID
    Description: The role name that will be assumed in all child AWS accounts
    MaxLength: '64'
    MinLength: '6'
    Type: String
  ParentAccount:
    AllowedPattern: '[0-9]{12}'
    Description: The AWS account ID of the parent account
    Type: String
  ParentAccountUser:
    Default: VectraCognitoHostIDFederated
    Description: The user name in the parent AWS account
    MaxLength: '64'
    MinLength: '6'
    Type: String
Resources:
  role:
    Properties:
      AssumeRolePolicyDocument:
        Statement:
          - Action:
              - sts:AssumeRole
            Effect: Allow
            Principal:
              AWS:
                - !Join
                  - ''
                  - - 'arn:aws:iam::'
                    - !Ref 'ParentAccount'
                    - :user/
                    - !Ref 'ParentAccountUser'
      MaxSessionDuration: 7200
      Path: /
      Policies:
        - PolicyDocument:
            Statement:
              - Action:
                  - iam:ListAccountAliases
                  - iam:SimulatePrincipalPolicy
                  - ec2:DescribeInstances
                  - ec2:DescribeRegions
                  - ec2:DescribeSubnets
                  - ec2:DescribeTrafficMirrorTargets
                  - ec2:DescribeTrafficMirrorSessions
                  - ec2:DescribeVpcPeeringConnections
                  - ec2:DescribeVpcs
                  - sts:GetCallerIdentity
                Effect: Allow
                Resource:
                  - '*'
            Version: '2012-10-17'
          PolicyName: VectraCognitoHostIDPolicy
      RoleName: !Ref 'ChildAccountRole'
    Type: AWS::IAM::Role

• In the Vectra UI, navigate to Configuration > Setup > External Connectors > AWS and click Edit.

• Turn On the Enable integration with AWS setting.

• Click Add Credential and fill out the form using the values you just noted and the appropriate Cloud Type.

  • Enter the access key ID and secret access key corresponding to the VectraCognitoHostIDFederated user you created earlier in the parent account.

  • The Alias can be any identifier you wish to use for this set of credentials in Vectra’s UI.

• Click the Multi-Account Credential checkbox to enable multi-account credential entry.

• Role to Assume should default to VectraCognitoHostID and can be left as is unless any of the templates have been modified.

• List all the AWS Account Numbers (account IDs) to be covered.

  • You can hit enter after each account or paste in multiple account numbers separated by a comma.

• You may test access using the Test Account link.

• Click Add.

• Save your connector configuration

• Look for the green check mark and a status of Connected.

Viewing and Modifying Virtual Networks Considered by the Connector

The connector will only look at virtual machines that belong to some VPCs, not necessarily all VPCs that the credentials have access to. Specifically, by default, the connector will only look for virtual machines with network interfaces in the VPCs where a Vectra AWS Sensor traffic interface is deployed into, and all the VPCs peered to it. If a virtual machine has multiple network interfaces, the connector will provide host identification only for the IP addresses belonging to interfaces on monitored VPCs.

Vectra limits the scope of the connector to only virtual networks that can reach an AWS Sensor for the following reasons:

• Vectra wants to avoid an excessive number of connections to the AWS resource manager.

• To improve performance, Vectra wants to avoid storing unnecessary information in the platform for resources that we are not monitoring.

• In the cloud it is possible that you may have some isolated virtual networks that are not monitored by Vectra Sensors but have overlapping IP space with some other networks that are monitored. Duplicate IPs are not supported by Vectra. To avoid Host ID issues, we only consider virtual machines on the networks that appear reachable by our Sensors.

If you want to add or remove some virtual networks from the set of virtual networks that Vectra monitors, you can do so through the CLI (ssh to the Brain as the vectra user). This functionality is not available in the Vectra UI. The use case for adding or removing virtual networks could be any of the following:

• If you have some tunneling or forwarding enabled and Vectra AWS Sensors see traffic from VPCs that are NOT directly connected to our Sensor:

  • You will want to add the networks to the monitored networks list to extend Host ID coverage to the tunneled/forwarded traffic’s associated Hosts.

• If you do NOT have any AWS Sensors deployed, but mirror AWS traffic into your data center where you have Vectra physical or virtual Sensor coverage:

  • You will want to add the networks to the monitored networks list to extend Host ID coverage to the mirrored traffic.

• If you do have some overlapping IP space on a network that appears reachable by our Sensor, but it is not monitored by our Sensor:

  • You will want to remove the overlapping networks from the monitored networks to avoid any Host ID issues.

• If you have a lot of peered VPCs but only some are monitored by the Sensor:

  • You will want to remove the non-monitored networks from the monitored networks list to increase performance and reduce load on the AWS resource manager.

The command to include or exclude specific virtual networks from the Vectra CLI is set aws hostid config. Without turning on the aws hostid config at the CLI, the connector will operate in a default manner. Think of this command as customization beyond the default behavior described above, not a full replacement for it. You must turn on the aws hostid config at the CLI to enable any include/exclude customizations that you configure.

The command has a help message illustrating its use:

vscli > set aws hostid config --help
Usage: set aws hostid config [ --clear-exclude ] [ --clear-include ] [ --on-off ( on | off ) ] [ -i include ] [ -e exclude ]

Options:
  --clear-exclude     set if you want to wipe the list of vpcs to exclude
  --clear-include     set if you want to wipe the list of vpcs to include
  --on-off [on|off]
  -i, --include TEXT  comma separated list of vpc id's to add to the include
                      list
  -e, --exclude TEXT  comma separated list of vpc id's to add to the exclude
                      list
  -h, --help          Show this message and exit.

The command show aws hostid config will show if customization is enabled for the default HostID configuration, and any included or excluded VPCs that you want to be considered or not considered by the connector.

Example of usage:

vscli > set aws hostid config -i vpc-0830d0eef7c5d27fc
vscli > set aws hostid config --on-off on
successfully set aws hostid configuration

vscli > show aws hostid config
enabled: True
exclude:
include:
    vpc-0abc356d,
    vpc-0830d0eef7c5d27fc

CloudWatch Integration

The Vectra Brain can publish system health and audit logs to the CloudWatch service (Quadrant UX deployment only). This is optional.

Supporting Materials

CloudwatchLogsTemplate - (QUX deployments only) - Used for integration with AWS CloudWatch

1KB

CloudwatchLogsTemplate.yml

Open

This file can also be downloaded from your Brain after deployment from the following location:

• https://<brain_hostname_or_IP>/resources/CloudwatchLogsTemplate.yaml/serve_file

Configuration

To configure this integration:

• Use CloudFormation to create the VectraCognitoCloudwatchLogsv1 IAM user using the CloudwatchLogsTemplate.yml .

• The template is also shown in an expandable code block below.

AWSTemplateFormatVersion: '2010-09-09'
Description: Vectra Cloudwatch Logs User version 1.2
Resources:
  user:
    Properties:
      Policies:
        - PolicyDocument:
            Statement:
              - Action:
                  - logs:CreateLogStream
                  - logs:DeleteLogStream
                  - logs:DescribeLogStreams
                  - logs:GetLogEvents
                  - logs:PutLogEvents
                  - logs:DeleteLogGroup
                  - logs:GetLogEvents
                  - logs:PutRetentionPolicy
                Effect: Allow
                Resource:
                  - !Join
                    - ''
                    - - 'arn:'
                      - !Ref 'AWS::Partition'
                      - :logs:*:*:log-group:/vectra/cognito/*
                Sid: CreateDeleteAndRetrieveVectraCloudwatchGroupLogEvents
              - Action:
                  - iam:SimulatePrincipalPolicy
                  - logs:DeleteLogGroup
                  - logs:CreateLogGroup
                  - sts:GetCallerIdentity
                Effect: Allow
                Resource:
                  - '*'
                Sid: CreateVectraLogs
            Version: '2012-10-17'
          PolicyName: vectra_cloudwatch_log_permissions
      UserName: VectraCognitoCloudwatchLogsv1
    Type: AWS::IAM::User

• Browse to the Identity and Access Management service.

• Navigate to the user VectraCognitoCloudwatchLogsv1 in the Identity and Access Management service.

• Click on the Security credentials tab and the Create Access key button.

  • This will generate a credential pair similar to the below (make note of these for use in the Vectra UI):

• Navigate on the Vectra UI to Configuration → RESPONSE > Notifications > AWS CloudWatch.

• Click Edit.

• Enter the credentials and the fields related to the AWS account, including Amazon CloudWatch fields like Group Name and Stream name, and the format.

• Select the log types you wish to forward from Vectra.

• Click Save.