# Code encryption

This feature is available in the[ Enterprise plan](https://www.sonarsource.com/plans-and-pricing/#sonarqube-cloud-features).

## Overview

SonarQube Cloud stores the source code of analyzed projects to properly display analysis results. Code encryption with Customer Managed Key (CMK) also known as Bring your own key (BYOK) provides an additional level of security to help organizations comply with their regulatory and internal policies that require encryption keys to remain under the company’s control.

### AWS standard encryption

Independently of the plan and configuration, your source code is always protected using built-in AWS standard encryption. See [Protecting data with encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingEncryption.html) on AWS documentation website for more details.

### Code encryption with Customer Managed Key (CMK)

The code encryption configuration provides an additional method for user controlled encryption at rest using CMK ensuring that you retain full ownership and control of your most sensitive data, your code.

Benefits:

* **Encrypt code at rest**: Use your own CMK created in AWS Key Management Service (KMS) to encrypt your source code for maximum security and compliance.
* **Meet compliance requirements**: Satisfy regulatory or internal mandates to own and manage the encryption keys of your proprietary data.
* **Control key lifecycle (rotation/revocation)**: As an Enterprise Administrator you can rotate your CMK for proactive security, or immediately disable it in case of an incident to instantly block access to all encrypted data.

### How it works

With CMK, SonarQube uses a least privilege key model, providing you with full control over the lifecycle of your keys and limiting SonarQube’s access to the key usage. You generate and manage your AWS KMS keys and SonarQube only performs encryption and decryption functions using the CMK. You don’t have to grant SonarQube any administrative roles within the AWS KMS account.

The system utilizes envelope encryption (using AES-256) to ensure maximum security. Once an Enterprise Admin configures your AWS KMS Key ARN (Amazon Resource Name) in the Enterprise settings, SonarQube generates a unique Data Encryption Key (DEK) for each project. Your source code is encrypted with these project-specific DEKs, which are in turn protected by your CMK. This architecture ensures that you retain full control over the data lifecycle. If you revoke or disable your key in AWS, access to the encrypted source code within SonarQube Cloud is immediately blocked.<br>

<figure><img src="https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2FqxICBcK1qx7JOYFY4RYf%2Fcode-encryption.png?alt=media&#x26;token=51d00e6d-9b56-4c3f-bc18-56b4eaa7e9f9" alt="You manage your AWS KMS keys and SonarQube only performs encryption and decryption functions"><figcaption></figcaption></figure>

### Caching of data keys

To enhance the performance of code encryption and decryption, and to reduce the reliance on AWS KMS requests, SonarQube's code encryption feature utilizes caching for project data keys. Unencrypted data keys are stored in this cache for a maximum duration of 5 minutes.

In case of key revocation, some projects might be still available for up to 5 minutes due to cached project data keys.

### Irreversibility of CMK code encryption

{% hint style="warning" %}
This feature is irreversible and once enabled, it cannot be disabled or reversed.
{% endhint %}

Before you enable code encryption with CMK on your enterprise, keep the following in mind:

* Once code encryption with your CMK is enabled for your enterprise it cannot be undone or disabled.
* Organizations that are part of the enterprise with the code encryption enabled cannot be downgraded. The only way to detach an organization from the enterprise is to remove it and re-create it elsewhere, which will result in the permanent loss of all historical data.
* Once an organization is added to an enterprise with code encryption enabled, its projects automatically become encrypted.

### Other considerations

Before enabling CMK encryption on your enterprise, consider the following:

* When using Agentic Analysis, the project context is collected and stored by SonarQube Cloud. This context, usually containing project dependencies, build artifacts, type information, and others, is not encrypted with CMK. See [agentic-analysis](https://docs.sonarsource.com/sonarqube-cloud/ai-capabilities/agentic-analysis "mention") for more information.
* When the Sonar analysis scanner uploads the analysis report to SonarQube Cloud, it is saved before the SonarQube processes it. Those reports are not encrypted with a CMK and are removed after 5 days.

## Permissions

The **Administer Enterprise** permission is required to set and manage code encryption for an enterprise. To change permissions, from the **Account** menu select *Your Enterprise* > **Administration** > **Enterprise Permissions** and switch the Administer Enterprise toggle on for specific users.

## Setting up CMK for code encryption&#x20;

{% stepper %}
{% step %}

### Creating CMK in AWS KMS

To set up code encryption, you must create a Symmetric CMK in AWS KMS under your AWS account. Ensure you are in the correct region for your SonarQube Cloud instance.

Please request the information about the SonarQube AWS Account ID and region from [Sonar Help Center](http://help.sonarsource.com/).

1. In **AWS KMS**, create a **Symmetric** key.
2. In the **Key Policy** step, switch to **JSON view** and add the following code to the `Statement` array replacing the `[ACCOUNT_ID]` with the SonarQube AWS Account ID under `Principal`.

```json
{
  "Sid": "Allow SonarQube Cloud use of the key",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::[ACCOUNT_ID]:root"
  },
  "Action": [
    "kms:Decrypt",
    "kms:ReEncrypt*",
    "kms:GenerateDataKey",
    "kms:DescribeKey",
    "kms:CreateGrant"
  ],
  "Resource": "*"
}
```

{% endstep %}

{% step %}

### Configuration in SonarQube Cloud enterprise

You can configure and rotate code encryption for a SonarQube Cloud enterprise.&#x20;

<figure><img src="https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2FpdZktZYk1iUMlWazv9Ex%2Fencryption-add-encryption.png?alt=media&#x26;token=1899cb0b-0dbe-47c3-b62b-d80546a0e548" alt="Add encryption key"><figcaption></figcaption></figure>

1. Go to **Account** menu > *your enterprise* > **Administration** > **Code Encryption**
2. Click **Add encryption key** and enter the key ARN (Amazon Resource Name) from AWS KMS.
3. In the modal, select the checkboxes for:&#x20;
   * *I understand my responsibilities for key management and the risks of irreversible loss of access to data if keys are lost.*
   * *I understand that code encryption cannot be reverted.*

Once the encryption is configured at the enterprise level, the encryption process of all existing projects starts, and all projects created afterward will be encrypted with their first analysis.
{% endstep %}
{% endstepper %}

## Rotating CMK

You have two options for generating new cryptographic material for your CMK.

#### Using SonarQube Cloud CMK rotation

Create a new AWS KMS key with a new ARN and then update the SQC configuration to utilize this new key. See the [#creating-cmk-in-aws-kms](#creating-cmk-in-aws-kms "mention") section for more information on how to create a key.

<figure><img src="https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2FMCDEqRlsMFr0CyHbSZjQ%2Fencryption-cmk-rotation.png?alt=media&#x26;token=fc347eae-4891-4f35-8c8c-8f5482feb145" alt="Rotate encryption key"><figcaption></figcaption></figure>

To rotate CMK:

1. Go to **Account** menu > *your enterprise* > **Administration** > **Code Encryption.**
2. Select the **Rotate encryption key** button.
3. Enter the **New key ARN** (Amazon Resource Name).
4. Select the checkbox for *I understand my responsibilities for key management and the risks of irreversible loss of access to data if keys are lost.*
5. Click **Rotate encryption key.**

The new CMK is used to re-encrypt existing and future data keys, the source code is not re-encrypted. Both old and new CMK should be enabled during the rotation procedure. Upon completion, you can disable the old CMK, but we recommend keeping it for a 30-day retention period.

#### Using AWS KMS key rotation

It’s possible to rotate the key material for an existing AWS KMS key by either enabling automatic key rotation or performing an on-demand rotation. Refer to [AWS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) for more information. SonarQube Cloud operates transparently regarding AWS KMS key rotation, meaning no action is required on the SonarQube Cloud side when the keys are rotated.

## Revoking the encryption key in case of an incident

Should an incident occur, your security team can instantly block access to all encrypted data by revoking the CMK within AWS KMS. To do this, locate the key in the AWS KMS interface, open it, and select **Disable** under **Key actions**.

{% hint style="info" %}
Due to data keys caching, some projects might still be available for up to 5 minutes.
{% endhint %}

## Rotating data keys

After all projects are encrypted, you can manually initiate the rotation of projects’ data keys.

<figure><img src="https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2FUAzJsqBQOY23iRI9cXMR%2Fencryption-rotate-data-keys.png?alt=media&#x26;token=cd9f1891-a238-42fa-b98f-4a5511ed04a5" alt="Rotating data keys"><figcaption></figcaption></figure>

1. Go to **Account** menu > *Your Enterprise* > **Administration** > **Code Encryption**
2. Select the **Rotate data keys** button.

This process is resource-intensive as it requires the re-encryption of all project data. CMK rotation is not possible while data key rotation is in progress. This feature provides an extra layer of security that may be mandatory for some organizations.

## Audit logs

Key operations related to code encryption are securely recorded in the audit logs of the enterprise. The logged events are:

| Event type                                 | Description                   |
| ------------------------------------------ | ----------------------------- |
| `enterprise.master_key_added`              | CMK added                     |
| `enterprise.master_key_rotation_started`   | CMK rotation started          |
| `enterprise.master_key_rotation_completed` | CMK rotation completed        |
| `enterprise.projects_encryption_started`   | Projects encryption started   |
| enterprise.projects\_encryption\_completed | Projects encryption completed |
| `enterprise.data_key_rotation_started`     | Data key rotation started     |
| `enterprise.data_key_rotation_completed`   | Data key rotation completed   |

See [#list-of-logged-events](https://docs.sonarsource.com/sonarqube-cloud/administering-sonarcloud/audit-logs#list-of-logged-events "mention") for more information.

## CMK health status and troubleshooting

The CMK health indicator in the **Encryption key** section displays the status of your CMK. If the status is Unhealthy, it indicates that there’s a problem with the CMK, for example, the key is disabled or some required permissions are missing. When the key is Unhealthy, code from past analyses is still stored encrypted, while the new analyses will fail to store the code.

## Related page

* [](https://docs.sonarsource.com/sonarqube-cloud/administering-sonarcloud/enterprise-security "mention")
* [audit-logs](https://docs.sonarsource.com/sonarqube-cloud/administering-sonarcloud/enterprise-security/audit-logs "mention")