Provide Plerion Access To KMS Keys

This user guide provides instructions on how to grant Plerion Appliance access to your Customer Managed KMS Keys (Key Management Service). By granting access, you allow the CWPP (Cloud Workload Protection Platform) Appliance to scan encrypted resources that are encrypted with those keys. To enable or update CWPP integration, please refer to the following guides:

  1. Onboarding CWPP Integration
  2. Updating Integration

Granting Plerion Appliance Access to KMS Keys

To grant Plerion Appliance access to your KMS keys, you have two modes:

  1. All KMS Keys
  2. Selected KMS Keys

The modes can be selected or updated during the onboarding process or by updating the integration. KMS Customer Managed Keys

All KMS Keys mode (ALL_KEYS)

In the All KMS keys mode, Plerion Appliance is granted access to all KMS keys in the account that delegate to the IAM account. However, you have the option to restrict access to certain keys by applying the "PlerionAccess: Denied" tag. This is the recommended option to use if you have a large number of KMS keys in your account.

When ALL KMS Keys mode is selected, the following statement is added to the PlerionApplianceRole IAM policy:

{
  "Effect": "Allow",
  "Sid": "PlerionKmsCmkAccess",
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:ReEncrypt*",
    "kms:GenerateDataKey*",
    "kms:DescribeKey",
    "kms:CreateGrant"
  ],
  "Resource": ["arn:aws:kms:*:*:key/*"],
  "Condition": {
    "StringNotEqualsIgnoreCase": {
      "aws:ResourceTag/PlerionAccess": "Denied"
    }
  }
}

The above statement grants PlerionAccessRole access to all keys that do not have the PlerionAccess tag with the value Denied.

Denying Access to Certain Keys

To deny access to certain keys for the Plerion Appliance, you can apply the "PlerionAccess: Denied" tag to those specific keys. By doing so, the Plerion Appliance will be restricted from accessing those keys.

Here's how you can deny access to certain keys:

  1. Navigate to the KMS Console => Customer managed keys.

  2. Select your key and in the Key Policy tab, click on the Edit button.

  3. Add Tag PlerionAccess with the value Denied to the Key.

    • Navigate to the Tag tab of the Key
    • Click on the Edit Button
    • Click on the Add tag button and enter PlerionAccess into the Tag Key field and Denied into the Tag Value field.
    • Finally, Click on the Save button.

    Add KMS Tag PlerionAccess

Selected KMS Keys Mode (SELECTED_KEYS)

The Selected KMS Keys mode in Plerion grants access exclusively to KMS keys that have been tagged with "PlerionAccess: Granted". By default, no KMS keys are granted access.

When Selected KMS Keys mode is selected, the following statement is added to the PlerionApplianceRole IAM policy:

{
  "Effect": "Allow",
  "Sid": "PlerionKmsCmkAccess",
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:ReEncrypt*",
    "kms:GenerateDataKey*",
    "kms:DescribeKey",
    "kms:CreateGrant"
  ],
  "Resource": ["arn:aws:kms:*:*:key/*"],
  "Condition": {
    "StringEqualsIgnoreCase": {
      "aws:ResourceTag/PlerionAccess": "Granted"
    }
  }
}

The above statement allows access only to the keys that have the PlerionAccess tag with the value Granted.

Granting Access to Certain Keys

To grant access to certain keys for the Plerion Appliance, you can apply the "PlerionAccess: Granted" tag to those specific keys. By doing so, the Plerion Appliance will be granted access to those keys.

Here's how you can grant access to certain keys:

  1. Navigate to the KMS Console => Customer managed keys.

  2. Select your key and in the Key Policy tab, click on the Edit button.

  3. Add Tag PlerionAccess with the value Granted to the Key.

    • Navigate to the Tag tab of the Key
    • Click on the Edit Button
    • Click on the Add tag button and enter PlerionAccess into the Tag Key field and Granted into the Tag Value field.
    • Finally, Click on the Save button.

    Add KMS Tag PlerionAccess

Granting access to KMS keys that don't delegate to IAM account

If the KMS key policy doesn't grant access to the IAM account using the principal arn:aws:iam::<AWS account ID>:root, you need to follow additional steps alongside the previous instructions to grant access to the Plerion Appliance Role.

Granting Access to Same Account KMS Keys

If the KMS key is in the same AWS account, follow these steps to grant access to the Plerion Appliance Role:

  1. Navigate to the KMS Console => Customer managed keys.
  2. Select your key and in the Key Policy tab, click on the Edit button.
  3. Add the below statement to your key policy Statement.
JSON
{
  "Sid": "Grant PlerionApplianceRole access to decrypt",
  "Effect": "Allow",
  "Principal": {
    "AWS": "*"
  },
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:ReEncrypt*",
    "kms:GenerateDataKey",
    "kms:DescribeKey"
  ],
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "aws:PrincipalAccount": "${aws:ResourceAccount}",
      "aws:PrincipalTag/PlerionApplianceRole": "True"
    }
  }
},
{
  "Sid": "Grant PlerionAccessRole to access key metadata",
  "Effect": "Allow",
  "Principal": {
    "AWS": "*"
  },
  "Action": ["kms:Describe*", "kms:List*", "kms:Get*"],
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "aws:PrincipalAccount": "${aws:ResourceAccount}",
      "aws:PrincipalTag/RolePurpose": "PlerionAccess"
    }
  }
}

The policy statement above accomplishes the following:

  • Grants the PlerionApplianceRole access to decrypt. The PlerionApplianceRole is tagged with PlerionApplianceRole: True. The PlerionApplianceRole is used by the Plerion Appliance to perform decryption operations.
  • Grants the PlerionAccessRole access to key metadata. The PlerionAccessRole is tagged with RolePurpose: PlerionAccess. The PlerionAccessRole is used by the Plerion control plane to verify if the appliance has proper access to the key and to retrieve key metadata.
  1. Click on the save button.
  2. If you have selected the Selected KMS Key mode, make sure to follow the steps outlined in the Granting access to certain Keys section of this user guide. This will involve navigating to the KMS Console, selecting the desired key, and adding the necessary tag (PlerionAccess: Granted) to grant access to the Plerion system.

Granting Access to Cross-Account KMS Keys

If the KMS key is in a different AWS account, follow these steps to grant access to the Plerion Appliance Role:

  1. Navigate to the KMS Console => Customer managed keys.
  2. Select your key and in the Key Policy tab, click on the Edit button.
  3. Add the below statement to your key policy Statement and replace <AWS_INTEGRATION_ACCOUNT> with the AWS account ID of the account where the Plerion integration is configured.
JSON
{
  "Sid": "Grant PlerionApplianceRole access to decrypt",
  "Effect": "Allow",
  "Principal": {
    "AWS": "*"
  },
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:ReEncrypt*",
    "kms:GenerateDataKey",
    "kms:DescribeKey"
  ],
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "aws:PrincipalAccount": "<AWS_INTEGRATION_ACCOUNT>",
      "aws:PrincipalTag/PlerionApplianceRole": "True"
    }
  }
},
{
  "Sid": "Grant PlerionAccessRole to access key metadata",
  "Effect": "Allow",
  "Principal": {
    "AWS": "*"
  },
  "Action": ["kms:Describe*", "kms:List*", "kms:Get*"],
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "aws:PrincipalAccount": "<AWS_INTEGRATION_ACCOUNT>",
      "aws:PrincipalTag/RolePurpose": "PlerionAccess"
    }
  }
}

The policy statement above accomplishes the following:

  • Grants the PlerionApplianceRole access to decrypt. The PlerionApplianceRole is tagged with PlerionApplianceRole: True. The PlerionApplianceRole is used by the Plerion Appliance to perform decryption operations.
  • Grants the PlerionAccessRole access to key metadata. The PlerionAccessRole is tagged with RolePurpose: PlerionAccess. The PlerionAccessRole is used by the Plerion control plane to verify if the appliance has proper access to the key and to retrieve key metadata.
  1. Click on the save button.
  2. If you have selected the Selected KMS Key mode, make sure to follow the steps outlined in the Granting access to certain Keys section of this user guide. This will involve navigating to the KMS Console, selecting the desired key, and adding the necessary tag (PlerionAccess: Granted) to grant access to the Plerion system.

Troubleshooting

[Error MissingPermission] PlerionAccessRole is missing kms:<Action> permission when accessing key <Key ARN>

CMK access denied

This error occurs when PlerionAccessRole doesn't have sufficient permissions to access the key's metadata. It happens when the KMS key policy doesn't delegate access to the IAM account with the principal arn:aws:iam::<AWS account ID>:root. To resolve this, refer to the guide Granting access to KMS keys that don't delegate to IAM account for granting access to the PlerionAccessRole.

Onboarding an AWS Account with CDRTroubleshooting CWPP Scan Errors