The AWS CloudWatch Logs integration enables Border0 to write session and/or audit logs to the AWS CloudWatch service in an AWS account.

Having Border0 session and audit logs in AWS CloudWatch means you can use Logs Insights and other CloudWatch native features to search, filter, and manipulate Border0 logs how you would any other logs in CloudWatch.

The integration uses a cross-account AWS IAM role and thus requires no credentials to be provided.

Integration Pre-Requisites

Certain resources must exist in your AWS account in order for Border0 to write logs there. In this section we will go over what those resources are and what they will be used for.

📘

Note

Advanced AWS users may choose to skip to the "AWS CloudFormation Stack" section below where a CFN stack template is provided for you to inspect and deploy at will

In short, your AWS account needs the following three resources:

• An AWS CloudWatch Logs "log group" to be used as the target location for logs written by Border0
• An AWS IAM "policy" to grant an IAM entity permissions to write logs to the log group
• An AWS IAM "role" with the above policy attached - for Border0 to assume (and receive its permissions)

The AWS IAM Policy

The IAM policy should have the following policy document:

Note: replace ${LOG_GROUP_AWS_REGION}, ${AWS_ACCOUNT_ID}, and ${LOG_GROUP_NAME} with real values

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "logs:CreateLogStream",
                "logs:DescribeLogStreams",
                "logs:PutLogEvents"
            ],
            "Resource": [
                "arn:aws:logs:${LOG_GROUP_AWS_REGION}:${AWS_ACCOUNT_ID}:log-group:${LOG_GROUP_NAME}",
                "arn:aws:logs:${LOG_GROUP_AWS_REGION}:${AWS_ACCOUNT_ID}:log-group:${LOG_GROUP_NAME}:log-stream:*"
            ],
            "Effect": "Allow",
            "Sid": "AllowManagingAllLogStreamsInLogGroup"
        }
    ]
}

The AWS IAM Role

The IAM role should have the IAM policy attached, and the following Assume-Role-Policy (trusted entities):

Note: replace ${SOME_SUPER_SECRET_PASSWORD}

Note: The "Condition" section with an ExternalId is optional, but recommended by Amazon Web Services. For more information see the official AWS documentation regarding External ID

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "arn:aws:iam::774169227652:root",
                    "arn:aws:iam::235487987553:root"
                ]
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "${SOME_SUPER_SECRET_PASSWORD}"
                }
            }
        }
    ]
}

AWS CloudFormation Stack Template

Advanced AWS users may choose to inspect and deploy a CloudFormation stack template. It will create the above three resources following the recommended approach. You may click here to download it.

AWS CloudWatch Logs Integration Configuration

(1) Name (required)

The integration's "name" is a unique identifier for the integration within your Border0 organization. In other words, no two integrations for the same Border0 organization can have the same name.

Name must start with an alphanumeric character [a-zA-Z0-9] and can only consist of alphanumeric characters and dashes ('-') - it must not include spaces.1

🚧

Note

Name is the only parameter which can not be changed after creation-time.

(2) Description

The integration's "description" is a short phrase describing what the integration does or what its purpose is.

(3) AWS CloudWatch Log Group ARN (required)

The integration's "log group arn" is the Amazon Resource Number (ARN) of the AWS CloudWatch log group to use as the target/sink for logs.

(4) AWS IAM Role ARN (required)

The integration's "role arn" is the Amazon Resource Number (ARN) of the AWS IAM Role in your AWS account for Border0 to assume.

By assuming this role within your AWS account, Border0 is able to write logs to CloudWatch in your account.

(5) External ID (strongly recommended)

The integration's "external id" is an optional parameter that can be configured when creating the AWS IAM Role in your account. It acts as an additional parameter for third-parties to provide when assuming the role.

For more information regarding the "external id" concept and how it makes cross-account roles more secure, see the official AWS documentation.

AWS CloudWatch Logs Notification Usage

AWS CloudWatch Logs integrations can be referenced in Border0 notification rules in order for Border0 to write logs regarding session or audit events into the log stream defined in your integration's configuration.

Once you have at least one AWS CloudWatch Logs integration in your organization, the notifications page will expose the option to add an AWS CloudWatch Logs based notification.

AWS CloudWatch Logs Notification Configuration

(1) name (required)

The notification's "name" is a unique identifier for the notification within your Border0 organization. In other words, no two notifications for the same Border0 organization can have the same name.

Name must start with an lowercase alphanumeric character [a-z0-9] and can only consist of lowercase alphanumeric characters and dashes ('-') - it must not include spaces.

🚧

Note

Name is the only parameter which can not be changed after creation-time.

(2) enabled (required)

The notification's "enabled" setting is a boolean which toggles the notification on/off. When false, the notification is not active and acts as if the notification did not exist.

(3) AWS CloudWatch Logs Integration Name (required)

The notification's "AWS CloudWatch Logs Integration Name" is the name of the AWS CloudWatch Logs integration to use for notifications.

(4) Notify on the following Events (required)

The notification's "Events" are a list of event types that will trigger the notification. These include "login-success", "login-failure", and "audit-event".

For more information see the general documentation on setting up notifications.

Example

Assume you have configured the following AWS CloudWatch Logs integration in your Border0 organization.

Then we can proceed to add a notification referencing our AWS CloudWatch Logs integration:

AWS CloudWatch Logs Processing

Once you have Border0 logs in your AWS account you are able to parse and filter them using Logs Insights.

Note that for each log group, Border0 will create a log stream per day with the log stream name as "${YEAR}-${MONTH}-${DAY}". e.g. "2023-May-08"

The following queries may come in handy as a starting point for querying your Border0 logs.

Session Logs

Successful Sessions

filter @logStream like /*-*-*/
 | fields @timestamp, @message
 | filter @message like /New session/
 | parse @message '🔔 New session for *\nUser: *\nSource IP: * *\nPolicy evaluation result:\n*' as @service, @user_email, @source_ip, @flag, @policy_evaluation_result
 | display @timestamp, @service, @user_email, @source_ip, @flag, @policy_evaluation_result

Failed Sessions

filter @logStream like /*-*-*/
 | fields @timestamp, @message
 | filter @message like /Failed login/
 | parse @message '🔔 Failed login attempt for *\nUser: *\nSource IP: * *\nAccess denied reason:\n*' as @service, @user_email, @source_ip, @flag, @policy_evaluation_result
 | display @timestamp, @service, @user_email, @source_ip, @flag, @policy_evaluation_result

Audit Events

filter @logStream like /*-*-*/
 | fields @timestamp, @message
 | parse @message '🔔 New audit event in Border0 organization *\nResource: * *\nAction: *\nActor: *\nDate: *' as @organization, @resource_type, @resource, @action, @actor, @date
 | display @timestamp, @organization, @resource_type, @resource, @action, @actor, @date