Enable Logging to Your Own S3 Bucket

You can set up Umbrella to log events to an Amazon S3 bucket which you manage. To enable logging in Umbrella to a self-managed Amazon S3 bucket, follow the prerequisite steps to set up an AWS account and create an AWS S3 bucket. Then, configure Umbrella to use the self-managed S3 bucket to record log events.

Table of Contents

• Prerequisites
  • JSON Bucket Policy
• Procedure
• Enable Logging HTTPS Query Parameters
• S3 Bucket Data Path
• Download Files From the S3 Bucket Locally

Prerequisites

• Full admin access to the Umbrella dashboard. See Manage User Roles.
• A login to Amazon AWS service (http://aws.amazon.com/console/). If you don't have an account, Amazon provides free sign up for S3.
  Note: Amazon requires a credit card in case your usage exceeds free plan usage.
• A bucket configured in Amazon S3 to be used for storing logs. For more information, see Amazon's S3 documentation.
  Note: Periods in S3 bucket names are not supported.

JSON Bucket Policy

When you set up your Amazon S3 bucket, you must add a bucket policy which accept uploads from Umbrella. Copy the following preconfigured JSON and substitute your S3 bucket name for bucketname. Then, paste the Umbrella S3 bucket policy into your Amazon S3 bucket policy.

{
  "Version": "2008-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::568526795995:user/logs"
      },
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::bucketname/*"
    },
    {
      "Sid": "",
      "Effect": "Deny",
      "Principal": {
        "AWS": "arn:aws:iam::568526795995:user/logs"
      },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::bucketname/*"},
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::568526795995:user/logs"
      },
      "Action": "s3:GetBucketLocation",
      "Resource": "arn:aws:s3:::bucketname"
    },
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::568526795995:user/logs"
      },
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::bucketname"
    }
  ]
}

Procedure

1. Navigate to Admin > Log Management and select Use your company-managed Amazon S3 bucket.

2. In the Bucket Name field, type or paste the exact bucket name you created in Amazon S3 and click Verify.
   Umbrella verifies your bucket, connects to it, and saves a README_FROM_UMBRELLA.txt file to your bucket.

3. Open the README_FROM_UMBRELLA.txt file Umbrella saved to your bucket, copy and paste the token listed in it into Token Number, and click Save.

Enable Logging HTTPS Query Parameters

Once activated, you can optionally enable logging of the full HTTPS request, including the query parameters, to your S3 Bucket. This allows you to view the HTTPS query section of a URL, which is not visible within the Umbrella reporting dashboard due to potentially personal or sensitive user information. Visibility into the query parameters of individual search requests can allow you to flag problematic queries for intervention and ensure the security of your users.

Note: HTTPS Query parameters may contain personal or sensitive content. Manage logged data appropriately.

1. Navigate to Admin > Log Management.
2. To enable logging HTTPS query parameters to an S3 Bucket, click on the toggle button next to Log HTTPS Query.

3. A pop-up window appears. Read the message, check the check box, and click Agree.

S3 Bucket Data Path

You can integrate your self-managed AWS S3 bucket with the Cisco Cloud Security App for Splunk. Use the data path to your AWS S3 bucket to set up the integration. The S3 bucket data path contains the following path fields:

<AWS S3 bucket name>-<AWS region>/<AWS S3 bucket directory prefix>

• AWS S3 bucket name and AWS region—the name of your AWS S3 bucket, a dash (-), and the AWS region.
• AWS S3 bucket directory prefix—the directory prefix (customer folder name) to the AWS S3 bucket.

Sample S3 Bucket Data Path:

my_company_name-us-west-1/dnslogs

Use the data path to your self-managed S3 bucket to:

• Download log files with the AWS CLI.
• Set up your AWS S3 bucket with the Cisco Cloud Security App for Splunk. The Cisco Cloud Security App for Splunk enables you to analyze your Umbrella logs found in your AWS S3 bucket. For more information, see Cisco Cloud Security App for Splunk.

Download Files From the S3 Bucket Locally

You can use the Amazon command-line interface (CLI) to download files from a self-managed S3 bucket to your local directory.

Prerequisites

• Install the AWS CLI to your system.

Run the AWS CLI to download your files from an S3 bucket to your local directory. To run the AWS CLI command in test mode (without syncing files), use the --dryrun flag.

AWS CLI command syntax:

aws s3 sync s3://DATAPATH /path/to/local/directory/

Detailed sample command:

aws s3 sync s3://mycompany-us-west-1/dnslogs /opt/splunk/etc/apps/TA-cisco_umbrella/data/

Upgrade Reports < Enable Logging to Your Own S3 Bucket > Enable Logging to a Cisco-managed S3 Bucket