Set up Audit Logs

Table of contents

• What are audit logs?
• Audit log delivery
• Event details
• Events captured by the audit log
• Requirements
• Audit logs set up
  • Audit logs AWS Configuration
  • Audit logs Azure Configuration

What are audit logs?

Audit logs allow customers to track and view all the changes made in their organization. They provide visibility and are useful for investigating an incident or getting a detailed report on relevant events (such as changes to roles and permissions, users invited, spaces deleted, etc.).

The audit logs feature securely transfers this information to your own storage (an AWS S3 bucket or Azure Blob Store), ensuring that you have a clear and accessible history of actions for monitoring and analysis purposes.

Audit log delivery

Audit logs are shipped to your AWS S3 Bucket or Azure Blob Store. Storing the audit logs in storage that you own helps you to have control and will allow you to ensure that audit logs are kept for as long as necessary. By storing the data in your own storage you have the following benefits:

• Consistency: This way you can apply the same rules and policies to this as you do for other similar data. You can control who has access to it.
• Data retention: This enables you to store it for as long as you need to maintain compliance for your company.
• Data analysis: And it allows you to serve this data to the tools you already use for analysis.

Events captured by the audit log

Event details

Audit event logs adhere to the OCSF standard. Currently all logs are logged under the Application Activity category and more specifically the Web Resource Activity sub-category. This enables seamless integrations and will be the stable schema from now on, meaning these logs are safe to use in integrations. An example of an audit log when an entry is updated can be found below.

  {
    "activity_name": "Update",
    "activity_id": 3,
    "category_uid": "6",
    "class_uid": "6001",
    "type_uid": "600101",
    "time": "yyyy-MM-dd hh:mm:ss.SSS",
    "actor": { "type": "user", "id": "<user_id>" },
    "enrichments": [
      {
        "name": "http_request.url.path",
        "type": "Space",
        "value": "/spaces/<space_id>/environments/<environment_id>/entries/<entry_id>/published",
        "data": { "id": "<space_id>" }
      }
    ],
    "severity_id": 0,
    "http_request": {
      "http_method": "PUT",
      "referrer": "https://app.contentful.com/",
      "url": {
        "path": "/spaces/<space_id>/environments/<environment_id>/entries/<entry_id>/published"
      }
    },
    "http_response": { "code": 200 },
    "web_resources": [{ "type": "Entry", "uid": "entry_id" }],
    "metadata": {
      "version": "1.3.0",
      "uid": "<request-id>"
    }
  },

How to read an audit log

Since audit logs abide by the OCSF standards some common parameters will always be the same. However, some properties have specific nuances due to being generated from the Contentful platform. The following guide will explain what each piece of the audit logs means and how to read it.

Activity

The properties prefixed with activity describe the type of event that occurred, and whether a resource (e.g. a space, environment, or locales) was updated, created, or deleted. Below is a table mapping the IDs to their names as well as their descriptions.

Category

The category properties refer to the OCSF categories and subcategories under which a specific log falls. As stated earlier at this moment all audit logs fall under the Application Activity category and more specifically the Web Resource Activity sub-category this may expand in the future but for now integrations can be built around this type of log specifically. Below is a description for each property that is relevant to the category in this log.

Actor

The actor property describes the user or app that acted on the resource by providing their user_id.

Severity

As quoted in the OCSF documentation the severity_id is “The normalized severity is a measurement of the effort and expense required to manage and resolve an event or incident. Smaller numerical values represent lower impact events, and larger numerical values represent higher impact events.” Below is a table mapping each ID to its description.

HTTP Request

The http_request object describes the original HTTP request that resulted in the log, the below table provides further details on what each property means.

HTTP Response

This http_response object contains the code referring to the HTTP Response code that the query resulted allowing for it to be established if the request was successful or not.

Enrichments

The enrichments property provides an array of objects that enrich other properties in the logs. More details can be found in the OCSF docs. Given the example log above each property would mean the following:

Web Resources

The web_resources property contains an array of entities that were affected by this request these can be environments, locales, content types or entries, etc. The properties of the objects contained in the array are as described below:

Metadata

The metadata property contains miscellaneous data that doesn’t fit well in the rest of the log but may still be useful. At this moment only two properties can be found in this object and the below table describes them.

Requirements

AWS or Azure account: An active AWS or Azure account is necessary.

Stopping the audit logs delivery

To stop the delivery of the audit logs, please contact our support

Audit logs set up

To set up your infrastructure to receive Audit Logs, you will need to make some configuration changes and share some information with Contentful.

The exact process is dependant on your storage provider. Please follow the appropriate guide from the list:

Audit logs AWS Configuration

As part of enabling audit log shipping to your AWS S3 bucket, you need to create an AWS IAM role that Contentful can assume. This will allow Contentful to securely transfer audit logs to your AWS S3 bucket without the need to store any credentials.

Prerequisites

• An AWS account with permissions to create IAM roles and edit S3 bucket policies.
• Contentful's AWS account IDs:
  • For US customers: 606137763417
  • For EU data residency customers: 101997328120

Step 1: Create an S3 Bucket

1. Log in to your AWS Management Console.
2. Navigate to S3, click Create bucket.
3. Enter a unique bucket name and select the region where you want the bucket to reside. Note: you will need to enter this name later.
4. Configure options as required (e.g., versioning, logging, tags).
5. Review and create the bucket.

Step 2: Create a New IAM Policy

1. Log in to your AWS Management Console.
2. Navigate to IAM -> Policies -> Create policy.
3. Select the JSON tab and paste the following policy, replacing with the name of your S3 bucket (from Step 1). Make sure to keep the /* at the end:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::<Your-S3-Bucket-Name>/*"
    }
  ]
}

4. Click Next, give it a meaningful name and description, and then click Create.

Step 3: Create a New IAM Role for Cross-Account Access

1. In the IAM dashboard, go to Roles -> Create role.
2. Select AWS Account under the "Trusted entity type" section, then in the section below select Another AWS account and enter Contentful's AWS account ID:
   • For US customers: 606137763417
   • For EU data residency customers: 101997328120
3. Enable the option Require external ID and insert your Contentful organization ID. The primary function of the external ID is to address and prevent the confused deputy problem. You can find the organization ID in the Contentful web app.
4. Click Next, skip attaching permissions policies now (we will attach the policy created in Step 2).
5. Review, name the role, and then create it.

Step 4: Attach the Policy to the IAM Role

1. Go to the newly created role in IAM -> Roles.
2. Under "Permissions" in the Add permissions dropdown, click Attach policies.
3. Find the policy you created in Step 2, select it, and then click Add permission.

Step 5: Configure Your S3 Bucket Policy

1. Go to S3, find your bucket from Step 1, and then click Permissions.
2. Edit the Bucket policy and add the following statement, replacing with the ARN of the IAM role you created in Step 3 and <Your-S3-Bucket-Name> with the name of your S3 bucket. Make sure to keep the /* at the end of the bucket ARN:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "<Your-IAM-Role-ARN>"
      },
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::<Your-S3-Bucket-Name>/*"
    }
  ]
}

3. Save the changes.

Step 6: Fill in Storage provider settings form in Contentful web application

In Contentful, navigate to Organization settings -> Audit logs. Pick Amazon AWS as a Storage provider option and fill in the form with the following details:

• Your AWS account ID
• S3 Bucket name
• ARN of IAM role to assume
• AWS Region

Now you can test the connection and, if successfull, Save the configuration.

By following these steps, you've securely enabled Contentful to ship logs to your AWS S3 bucket. Contentful will use AWS STS to assume the role you've created, ensuring a secure and efficient transfer of audit log data.

Audit Logs Azure Configuration

As part of enabling audit log shipping to your Azure Blob Storage container, you need to create a Shared Access Signature (SAS) user that Contentful can use. This will allow Contentful to securely transfer audit logs directly to your Azure Storage Account container. This guide will help you create a Shared Access Signature (SAS) user specifically for Contentful.

A shared access signature (SAS) provides secure delegated access to resources in your storage account. With a SAS, you have granular control over how a client can access your data. For example:

• What resources the client may access

• What permissions they have to those resources

• How long the SAS is valid

We will use RSA 4096 encryption to secure your SAS Token in-transit and at rest. Access to decrypt is provided only to the Audit Logging system and a small number of people who manage the Audit Logging service. For more information please contact us via support.

Prerequisites

An Azure account with access to create a Blob Store and a SAS Token

Step 1: Create an Azure Storage Account

1. Log in to your Azure Portal

2. Navigate to Storage Accounts -> Create

3. Select the Subscription under which to create the Storage Account

4. Select or Create the Resource Group for the Storage Account

5. Enter a unique storage account name and select the region where you want the account to reside. Note this name, you will need it later

6. Configure options as required (e.g., performance, redundancy, etc)

7. Click Review + create

8. On the Review + create page check that everything correct and if you’re satisfied click Create to create the storage account

Step 2: Create a Container

1. Log in to your Azure Portal

2. Navigate to Storage Accounts and click the one you created in Step 1 to open it

3. On the left sidebar, under Data storage, click Containers

4. In the top toolbar click the + Container button to create a new container

5. Enter a unique container name

6. Configure options as required (e.g., encryption scope, versioning, etc)

7. Review and click Create to create the container

Step 3: Create the SAS Token

1. Log in to your Azure Portal

2. Navigate to Storage Accounts and click the one you created in Step 1 to open it

3. On the left sidebar, under Data storage, click Containers

4. Click the name of the container you create in the steps above

5. On the left sidebar, under Settings, click Shared access tokens

6. Select the Permissions dropdown, deselect Read, then select Create and Write

7. Set an expiry date that complies with your secret rotation policy

8. Click Generate SAS token and URL

9. Copy the value of the Blob SAS URL field that's displayed. You will use this URL in the next steps

Step 4: Fill in Storage provider settings form in Contentful web application

In Contentful, navigate to Organization settings -> Audit logs. Pick Microsoft Azure as a Storage provider option and paste the blob SAS URL from the previous step into Blob SAS URL field. Now you can test the connection and, if successfull, Save the configuratio.