Amazon AWS S3 REST API protocol configuration options

The Amazon AWS S3 REST API protocol for IBM® Security QRadar® is an outbound/active protocol that collects AWS CloudTrail logs from Amazon S3 buckets.

Note: It's important to ensure that no data is missing when you collect logs from Amazon S3 to use with a custom DSM or other unsupported integrations. Because of the way the S3 APIs return the data, all files must be in an alphabetically increasing order when the full path is listed. Make sure that the full path name includes a full date and time in ISO9660 format (leading zeros in all fields and a YYYY-MM-DD date format).

Consider the following file path:

<Name>test-bucket</Name><Prefix>MyLogs/</Prefix><Marker>MyLogs/2018-8-9/2018-08-09T23-5925.955097.log.g</Marker><MaxKeys>1000</MaxKeys><IsTruncated>false</IsTruncated></ListBucketResult>

The full name of the file in the marker is MyLogs/2018-8-9/2018-08-09T23-59-25.955097.log.gz and the folder name is written as 2018-8-9 instead of 2018-08-09. This date format causes an issue when data for the 10 September 2018 is presented. When sorted, the date displays as 2018-8-10 and the files are not sorted chronologically:

2018-10-1

2018-11-1

2018-12-31

2018-8-10

2018-8-9

2018-9-1

After data for 9 August 2018 comes in to QRadar, you won't see data again until 1 September 2018 because leading zeros were not used in the date format. After September, you won't see data again until 2019. Leading zeros are used in the date (ISO 9660) so this issue does not occur.

By using leading zeros, files and folders are sorted chronologically:

2018-08-09

2018-08-10

2018-09-01

2018-10-01

2018-11-01

2018-12-01

2018-12-31
Restriction:

A log source can retrieve data from only one region, so use a different log source for each region. Include the region folder name in the file path for the Directory Prefix value when using the Directory Prefix event collection method to configure the log source.

The following table describes the common parameter values to collect audit events by using the Directory Prefix collection method or the SQS event collection method. These collection methods use the Amazon AWS S3 REST API protocol.
Table 1. Amazon AWS S3 REST API protocol common log source parameters when using the Directory Prefix method or the SQS method
Parameter Description
Protocol Configuration Amazon AWS S3 REST API
Log Source Identifier

Type a unique name for the log source.

The Log Source Identifier can be any valid value and does not need to reference a specific server. The Log Source Identifier can be the same value as the Log Source Name. If you have more than one Amazon AWS CloudTrail log source that is configured, you might want to identify the first log source as awscloudtrail1, the second log source as awscloudtrail2, and the third log source as awscloudtrail3.

Authentication Method
Access Key ID / Secret Key
Standard authentication that can be used from anywhere.
For more information about configuring security credentials, see Configuring security credentials for your AWS user account.
Assume IAM Role
Authenticate with keys and then temporarily assume a role for access. This option is available only when you use the SQS Event Notifications collection method.
For more information about creating IAM users and assigning roles, see Creating an Identity and Access Management (IAM) user in the AWS Management Console when using the Amazon AWS S3 REST API.
EC2 Instance IAM Role
If your managed host is running on an AWS EC2 instance, choosing this option uses the IAM Role from the instance metadata that is assigned to the instance for authentication; no keys are required. This method works only for managed hosts that are running within an AWS EC2 container.
Event Format

AWS Cloud Trail JSON

AWS Network Firewall

AWS VPC Flow Logs

Cisco Umbrella CSB

LINEBYLINE

W3C

Region Name The region that the SQS Queue or the AWS S3 bucket is in.

Example: us-east-1, eu-west-1, ap-northeast-3

Use as a Gateway Log Source Select this option for the collected events to flow through the QRadar Traffic Analysis engine and for QRadar to automatically detect one or more log sources.
Show Advanced Options Select this option if you want to customize the event data.
File Pattern

This option is available when you set Show Advanced Options to Yes.

Type a regex for the file pattern that matches the files that you want to pull; for example, .*?\.json\.gz

Local Directory

This option is available when you set Show Advanced Options to Yes.

The local directory on the Target Event Collector. The directory must exist before the AWS S3 REST API protocol attempts to retrieve events.

S3 Endpoint URL

This option is available when you set Show Advanced Options to Yes.

The endpoint URL that is used to query the AWS S3 REST API.

If your endpoint URL is different from the default, type your endpoint URL. The default is https://s3.amazonaws.com.

Use S3 Path-Style Access

Forces S3 requests to use path-style access.

This method is deprecated by AWS. However, it might be required when you use other S3 compatible APIs. For example, the https://s3.region.amazonaws.com/bucket-name/key-name path-style is automatically used when a bucket name contains a period (.). Therefore, this option is not required, but can be used.

Use Proxy

If QRadar accesses the Amazon Web Service by using a proxy, enable Use Proxy.

If the proxy requires authentication, configure the Proxy Server, Proxy Port, Proxy Username, and Proxy Password fields.

If the proxy does not require authentication, configure the Proxy IP or Hostname field.

Recurrence

How often a poll is made to scan for new data.

If you are using the SQS event collection method, SQS Event Notifications can have a minimum value of 10 (seconds). Because SQS Queue polling can occur more often, a lower value can be used.

If you are using the Directory Prefix event collection method, Use a Specific Prefix has a minimum value of 60 (seconds) or 1M. Because every listBucket request to an AWS S3 bucket incurs a cost to the account that owns the bucket, a smaller recurrence value increases the cost.

Type a time interval to determine how frequently the poll is made for new data. The time interval can include values in hours (H), minutes (M), or days (D). For example, 2H = 2 hours, 15M = 15 minutes, 30 = seconds.

EPS Throttle The maximum number of events per second that are sent to the flow pipeline. The default is 5000.

Ensure that the EPS Throttle value is higher than the incoming rate or data processing might fall behind.

The following table describes the specific parameter values to collect audit events by using the Directory Prefix event collection method:

Table 2. Amazon AWS S3 REST API protocol log source-specific parameters when using the Directory Prefix method
Parameter Description
S3 Collection Method Select Use a Specific Prefix.
Bucket Name

The name of the AWS S3 bucket where the log files are stored.

Directory Prefix

The root directory location on the AWS S3 bucket from where the CloudTrail logs are retrieved; for example, AWSLogs/<AccountNumber>/CloudTrail/<RegionName>/

To pull files from the root directory of a bucket, you must use a forward slash (/) in the Directory Prefix file path.

Note:
  • Changing the Directory Prefix value clears the persisted file marker. All files that match the new prefix are downloaded in the next pull.
  • The Directory Prefix file path cannot begin with a forward slash (/) unless only the forward slash is used to collect data from the root of the bucket.
  • If the Directory Prefix file path is used to specify folders, you must not begin the file path with a forward slash (for example, use folder1/folder2 instead).

The following table describes the parameters that require specific values to collect audit events by using the SQS event collection method:

Table 3. Amazon AWS S3 REST API protocol log source-specific parameters when using the SQS method
Parameter Description
S3 Collection Method Select SQS Event Notifications.
SQS Queue URL The full URL that begins with https://, for the SQS Queue that is set up to receive notifications for ObjectCreated events from S3.