AWS securityagent documentation change
Summary
Extensive restructuring and expansion of customer-managed keys documentation, including new 'Required KMS permissions' section, detailed key policy examples for CMK-encrypted AWS resources (S3, Secrets Manager, CloudWatch Logs), updated IAM role requirements, and clarification of permission requirements for different service identities.
Security assessment
This change enhances documentation about encryption security features (customer-managed keys) but does not indicate any specific security vulnerability, incident, or weakness being addressed. The changes are primarily organizational improvements, clarification of permission requirements, and addition of examples for integrating with encrypted AWS resources. No evidence of security incident response or vulnerability remediation is present.
Diff
diff --git a/securityagent/latest/userguide/customer-managed-keys.md b/securityagent/latest/userguide/customer-managed-keys.md index 8c673996e..58f055c11 100644 --- a//securityagent/latest/userguide/customer-managed-keys.md +++ b//securityagent/latest/userguide/customer-managed-keys.md @@ -0,0 +1,2 @@ +[View a markdown version of this page](customer-managed-keys.md) + @@ -5 +7 @@ -How customer managed keys workPrerequisitesConfigure a KMS key policyCreate a resource with a customer managed keyKey rotationConsiderations +How customer managed keys workPrerequisitesRequired KMS permissionsCreate a resource with a customer managed keyKey rotationConsiderations @@ -11 +13 @@ By default, AWS Security Agent encrypts all data at rest using AWS-managed encry -AWS Security Agent supports resource-level customer managed keys. When you create a top-level resource such as an Agent Space or integration, you can specify a KMS key to encrypt all data belonging to that resource and its subresources. For example, specifying a customer managed key when creating an Agent Space encrypts all data associated with that Agent Space, including Agent Space configurations, penetration test configurations, jobs, and execution details, security findings, discovered endpoints, and screenshots. +AWS Security Agent supports resource-level customer managed keys. When you create a top-level resource such as an Agent Space or integration, you can specify a KMS key to encrypt all data belonging to that resource and its subresources. For example, specifying a customer managed key when creating an Agent Space encrypts all data associated with that Agent Space, including Agent Space configurations, penetration test configurations, jobs, and execution details, security findings, discovered endpoints, and screenshots. You can also provide AWS resources that are already encrypted with your own customer managed key, such as S3 buckets or CloudWatch Logs log groups. For the required KMS permissions, see Required KMS permissions. @@ -32 +34 @@ The encryption context key follows the format `aws:securityagent:_<resource-type -You can use the encryption context to scope down your KMS key policy to specific resource types. For more information, see Configure a KMS key policy. +You can use the encryption context to scope down your KMS key policy to specific resource types. For more information, see Required KMS permissions. @@ -62 +64,8 @@ For instructions, see [Creating keys](https://docs.aws.amazon.com/kms/latest/dev - * Configure the KMS key policy to grant AWS Security Agent the required permissions. For details, see Configure a KMS key policy. + * Configure the KMS key policy and IAM policies to grant AWS Security Agent the required permissions. For details, see Required KMS permissions. + + + + +## Required KMS permissions + +AWS Security Agent requires KMS permissions in two scenarios: @@ -63,0 +73 @@ For instructions, see [Creating keys](https://docs.aws.amazon.com/kms/latest/dev + * **Encrypting data within AWS Security Agent** – When you specify a customer managed key for an Agent Space or integration, the service needs permissions to use that key for cryptographic operations on your data. @@ -64,0 +75 @@ For instructions, see [Creating keys](https://docs.aws.amazon.com/kms/latest/dev + * **Using CMK-encrypted AWS resources** – When you provide AWS resources encrypted with a customer managed key (such as S3 buckets, CloudWatch Logs log groups, or Secrets Manager secrets), the service needs permissions to use those keys to access the encrypted resources. @@ -67 +77,0 @@ For instructions, see [Creating keys](https://docs.aws.amazon.com/kms/latest/dev -## Configure a KMS key policy @@ -69 +78,0 @@ For instructions, see [Creating keys](https://docs.aws.amazon.com/kms/latest/dev -Your KMS key policy must grant AWS Security Agent permission to use the key for cryptographic operations. The required permissions depend on which resource types you plan to encrypt. @@ -82 +91 @@ AWS Security Agent accesses your KMS key using different identities depending on -Your key policy must include statements for all three identities. +The following sections describe the required permissions for each identity. @@ -84 +93,5 @@ Your key policy must include statements for all three identities. -### Key policy for Agent Spaces +### Key policy + +Your KMS key policy must grant AWS Security Agent permission to use the key for cryptographic operations. The required key policy statements depend on which resource types you plan to encrypt and which CMK-encrypted AWS resources you provide to the service. + +#### Key policy for Agent Spaces @@ -190 +203 @@ To rotate branch keys, your KMS key policy must grant `kms:GenerateDataKeyWithou -### Key policy for integrations +#### Key policy for integrations @@ -193,0 +207,11 @@ The following key policy grants AWS Security Agent the permissions required to e +Replace the following placeholder values in the policy: + + * ` _111122223333_ ` – Your AWS account ID + + * ` _MyRole_ ` – The IAM role you use to manage AWS Security Agent in the console + + * ` _us-east-1_ ` – The AWS Region where you use AWS Security Agent + + + + @@ -258 +282,158 @@ You can combine the Agent Space and integration key policy statements into a sin -### IAM policy for the application role +#### Key policy for CMK-encrypted AWS resources + +If you provide AWS resources encrypted with a customer managed key to AWS Security Agent, you must update the key policy on each resource’s KMS key to grant the necessary permissions. This applies to the following resources: + + * **S3 buckets** – If you provide learning resources from an S3 bucket encrypted with a customer managed key (SSE-KMS), the key policy must allow the penetration test service role to decrypt objects. + + * **Secrets Manager secrets** – If your penetration test credentials are stored in Secrets Manager secrets encrypted with a customer managed key, the key policy must allow the penetration test service role to decrypt those secrets. If the web application creates secrets on your behalf, the key policy must also allow the application role to encrypt those secrets. + + * **CloudWatch Logs log groups** – If the CloudWatch Logs log group used for storing penetration test execution logs is encrypted with a customer managed key, the key policy must allow CloudWatch Logs to validate the KMS key through the service role and allow the CloudWatch Logs service principal to perform cryptographic operations. + + + + +The following key policy statements grant the required permissions for CMK-encrypted resources. Include only the statements that apply to your configuration. If a resource uses the same KMS key you specified for your Agent Space, add these statements to that key’s policy. If a resource uses a different KMS key, add these statements to that key’s policy instead. + +Replace the following placeholder values in the policy: + + * ` _111122223333_ ` – Your AWS account ID + + * ` _MyApplicationRole_ ` – The application role created during AWS Security Agent setup + + * ` _MyPenTestServiceRole_ ` – The penetration test service role + + * ` _us-east-1_ ` – The AWS Region where you use AWS Security Agent + + + + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "AllowKmsKeyAccessForCreatingSecrets", + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam::111122223333:role/MyApplicationRole" + }, + "Action": [ + "kms:GenerateDataKey", + "kms:Decrypt" + ], + "Resource": "*", + "Condition": { + "StringEquals": { + "aws:ResourceAccount": "111122223333" + }, + "StringLike": { + "kms:ViaService": "secretsmanager.*.amazonaws.com", + "kms:EncryptionContext:SecretARN": "arn:aws:secretsmanager:us-east-1:111122223333:secret:*" + } + } + }, + { + "Sid": "AllowKmsKeyDecryptionForS3Objects", + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam::111122223333:role/MyPenTestServiceRole" + }, + "Action": [ + "kms:Decrypt" + ], + "Resource": "*", + "Condition": { + "StringEquals": { + "aws:ResourceAccount": "111122223333" + }, + "StringLike": { + "kms:ViaService": "s3.*.amazonaws.com", + "kms:EncryptionContext:aws:s3:arn": "arn:aws:s3:::YOUR-BUCKET-NAME*" + } + } + }, + { + "Sid": "AllowKmsKeyDecryptionForSecretsManagerSecrets", + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam::111122223333:role/MyPenTestServiceRole" + }, + "Action": [ + "kms:Decrypt" + ], + "Resource": "*", + "Condition": { + "StringEquals": { + "aws:ResourceAccount": "111122223333" + }, + "StringLike": { + "kms:ViaService": "secretsmanager.*.amazonaws.com", + "kms:EncryptionContext:SecretARN": "arn:aws:secretsmanager:us-east-1:111122223333:secret:YOUR-SECRET-NAME*" + } + } + }, + { + "Sid": "AllowKmsKeyValidationForCloudWatchLogsLogGroups", + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam::111122223333:role/MyPenTestServiceRole" + }, + "Action": [ + "kms:DescribeKey" + ], + "Resource": "*", + "Condition": { + "StringEquals": { + "aws:ResourceAccount": "111122223333" + }, + "StringLike": { + "kms:ViaService": "logs.*.amazonaws.com" + } + } + }, + { + "Sid": "AllowKmsKeyAccessForCloudWatchLogsLogGroups", + "Effect": "Allow", + "Principal": { + "Service": "logs.us-east-1.amazonaws.com" + }, + "Action": [ + "kms:Encrypt", + "kms:Decrypt", + "kms:GenerateDataKey" + ], + "Resource": "*", + "Condition": { + "StringEquals": { + "aws:ResourceAccount": "111122223333" + }, + "StringLike": { + "kms:EncryptionContext:aws:logs:arn": "arn:aws:logs:us-east-1:111122223333:log-group:YOUR-LOG-GROUP-NAME*" + } + } + } + ] + } + +###### Note + + * The `AllowKmsKeyDecryptionForS3Objects` statement is required only if you provide learning resources from S3 buckets encrypted with a customer managed key. For more information about configuring SSE-KMS for S3, see [Protecting data with SSE-KMS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html).