AWS AmazonCloudWatch documentation change
Summary
Updated CloudWatch Logs API key documentation to emphasize security best practices, including recommending SigV4 authentication over API keys, adding detailed key rotation procedures, expanding compromised key response steps, and adding a new 'Security best practices for API keys' section.
Security assessment
The changes significantly enhance security documentation by adding proactive guidance (key rotation, best practices) and improving incident response procedures for compromised keys. However, there is no concrete evidence in the diff that these changes are in direct response to a specific, newly discovered security vulnerability or incident. The changes are preventative and educational in nature.
Diff
diff --git a/AmazonCloudWatch/latest/logs/CWL_HTTP_Endpoints_BearerTokenAuth.md b/AmazonCloudWatch/latest/logs/CWL_HTTP_Endpoints_BearerTokenAuth.md index 8aab5902e..6506a5d0b 100644 --- a//AmazonCloudWatch/latest/logs/CWL_HTTP_Endpoints_BearerTokenAuth.md +++ b//AmazonCloudWatch/latest/logs/CWL_HTTP_Endpoints_BearerTokenAuth.md @@ -5 +5 @@ -Option 1: Simplified setup using the AWS console (recommended)Option 2: Manual setupControl permissions for generating and using CloudWatch Logs API keysHandle compromised CloudWatch Logs API keysLogging API key usage with CloudTrail +Option 1: Quick start using the AWS consoleOption 2: Manual setupControl permissions for generating and using CloudWatch Logs API keysRotating API keysResponding to a compromised API keySecurity best practices for API keysLogging API key usage with CloudTrail @@ -21,0 +22,4 @@ Before you can send logs using bearer token authentication with any of the HTTP +###### Important + +We recommend using SigV4 authentication with short-term credentials for all workloads where this is possible. SigV4 provides the strongest security posture. Restrict the use of API keys (bearer tokens) to scenarios where short-term credential-based authentication is not feasible. When you are ready to incorporate CloudWatch Logs into applications with greater security requirements, you should switch to short-term credentials. For more information, see [Alternatives to long-term access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles) in the _IAM User Guide_. + @@ -26 +30 @@ API key (bearer token) for HTTP endpoint access is currently in preview and avai -## Option 1: Simplified setup using the AWS console (recommended) +## Option 1: Quick start using the AWS console @@ -307 +311 @@ This policy will prevent the creation of credentials for all AWS services that s -## Handle compromised CloudWatch Logs API keys +## Rotating API keys @@ -309 +313 @@ This policy will prevent the creation of credentials for all AWS services that s -If your API key becomes compromised, you should revoke permissions to use it. You can use the following IAM API operations to manage compromised keys: +Regularly rotating your API keys reduces the risk of unauthorized access. We recommend establishing a rotation schedule that aligns with your organization's security policies. @@ -311 +315 @@ If your API key becomes compromised, you should revoke permissions to use it. Yo - * [UpdateServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateServiceSpecificCredential.html) – Set the status of the key to inactive. You can reactivate the key later. +### Rotation process @@ -313 +317 @@ If your API key becomes compromised, you should revoke permissions to use it. Yo - * [ResetServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ResetServiceSpecificCredential.html) – Reset the key. This generates a new password for the key. +To rotate an API key without interrupting log delivery, follow this procedure: @@ -315 +319 @@ If your API key becomes compromised, you should revoke permissions to use it. Yo - * [DeleteServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteServiceSpecificCredential.html) – Delete the key permanently. + 1. Create a new (secondary) credential for the IAM user: @@ -316,0 +321,4 @@ If your API key becomes compromised, you should revoke permissions to use it. Yo + aws iam create-service-specific-credential \ + --user-name cloudwatch-logs-hlc-user \ + --service-name logs.amazonaws.com \ + --credential-age-days 90 @@ -317,0 +326 @@ If your API key becomes compromised, you should revoke permissions to use it. Yo + 2. (Optional) Store the new credential in AWS Secrets Manager for secure retrieval and automated rotation. @@ -318,0 +328 @@ If your API key becomes compromised, you should revoke permissions to use it. Yo + 3. Import the new credential into your vendor's portal or update your application configuration to use the new API key. @@ -320 +330 @@ If your API key becomes compromised, you should revoke permissions to use it. Yo -###### Note + 4. Set the original credential to inactive: @@ -322 +332,4 @@ If your API key becomes compromised, you should revoke permissions to use it. Yo -To carry out these actions through the API, you must authenticate with AWS credentials and not with a CloudWatch Logs API key. + aws iam update-service-specific-credential \ + --user-name cloudwatch-logs-hlc-user \ + --service-specific-credential-id ACCA1234EXAMPLE1234 \ + --status Inactive @@ -324 +337 @@ To carry out these actions through the API, you must authenticate with AWS crede -### Change the status of a CloudWatch Logs API key + 5. Verify that log delivery is not impacted by monitoring the `IncomingBytes` metric for your log group in CloudWatch. For more information, see [Monitoring with CloudWatch metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html). @@ -326 +339 @@ To carry out these actions through the API, you must authenticate with AWS crede -To deactivate a key, use the [update-service-specific-credential](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/update-service-specific-credential.html) command: + 6. After confirming successful delivery with the new key, delete the previous credential: @@ -327,0 +341,2 @@ To deactivate a key, use the [update-service-specific-credential](https://awscli + aws iam delete-service-specific-credential \ + --service-specific-credential-id ACCA1234EXAMPLE1234 @@ -329 +344,9 @@ To deactivate a key, use the [update-service-specific-credential](https://awscli - aws iam update-service-specific-credential \ + + + +### Monitoring key expiration + +To check the creation date and status of your existing API keys, use the [list-service-specific-credentials](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/list-service-specific-credentials.html) command: + + + aws iam list-service-specific-credentials \ @@ -331,2 +354 @@ To deactivate a key, use the [update-service-specific-credential](https://awscli - --service-specific-credential-id ACCA1234EXAMPLE1234 \ - --status Inactive + --service-name logs.amazonaws.com @@ -334 +356 @@ To deactivate a key, use the [update-service-specific-credential](https://awscli -To reactivate the key, change the status to `Active`. +The response includes `CreateDate` and `Status` for each credential. Use this information to identify keys that are approaching expiration or have been active longer than your rotation policy allows. @@ -336 +358 @@ To reactivate the key, change the status to `Active`. -### Reset a CloudWatch Logs API key +## Responding to a compromised API key @@ -338 +360 @@ To reactivate the key, change the status to `Active`. -If the value of your key has been compromised or you no longer have it, reset it using the [reset-service-specific-credential](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/reset-service-specific-credential.html) command. The key must not have expired yet. If it's already expired, delete the key and create a new one. +If you suspect that an API key has been compromised, take the following steps immediately: @@ -339,0 +362 @@ If the value of your key has been compromised or you no longer have it, reset it + 1. **Deactivate the key immediately** to prevent further unauthorized use: @@ -341,2 +364,4 @@ If the value of your key has been compromised or you no longer have it, reset it - aws iam reset-service-specific-credential \ - --service-specific-credential-id ACCA1234EXAMPLE1234 + aws iam update-service-specific-credential \ + --user-name cloudwatch-logs-hlc-user \ + --service-specific-credential-id ACCA1234EXAMPLE1234 \ + --status Inactive @@ -344 +369 @@ If the value of your key has been compromised or you no longer have it, reset it -### Delete a CloudWatch Logs API key + 2. **Review CloudTrail logs** to determine the scope of unauthorized access. See Logging API key usage with CloudTrail for how to enable auditing of API key usage. @@ -346 +371 @@ If the value of your key has been compromised or you no longer have it, reset it -If you no longer need a key or it has expired, delete it using the [delete-service-specific-credential](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/delete-service-specific-credential.html) command: + 3. **Create a replacement key** following the rotation process described in Rotation process. @@ -347,0 +373 @@ If you no longer need a key or it has expired, delete it using the [delete-servi + 4. **Delete the compromised key** after the replacement is in place: @@ -352,4 +378 @@ If you no longer need a key or it has expired, delete it using the [delete-servi -### Attach IAM policies to remove permissions for using a CloudWatch Logs API key - -To prevent an identity from making calls with a CloudWatch Logs API key, attach the following policy to the IAM user associated with the key: - + 5. **Attach a deny policy** if you need to immediately block all bearer token access for the IAM user while you investigate: @@ -365,0 +389,35 @@ To prevent an identity from making calls with a CloudWatch Logs API key, attach + + + +###### Note + +To carry out these actions through the API, you must authenticate with AWS credentials and not with a CloudWatch Logs API key. + +You can also use the following IAM API operations to manage compromised keys: + + * [ResetServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ResetServiceSpecificCredential.html) – Reset the key to generate a new password without deleting the credential. The key must not have expired. + + + + +## Security best practices for API keys + +Follow these best practices to protect your CloudWatch Logs API keys: + + * **Never embed API keys in source code.** Do not hard-code API keys in application code or commit them to version control systems. If a key is accidentally committed to a public repository, AWS automated scanning may flag it and you should rotate the key immediately. + + * **Use a secrets manager.** Store API keys in [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) or an equivalent secrets management solution. This enables centralized access control, audit logging, and automated rotation. + + * **Set an expiration on all keys.** Always specify a `--credential-age-days` value when creating API keys. To enforce a maximum key lifetime across your organization, use the `iam:ServiceSpecificCredentialAgeDays` IAM condition key. For an example, see Allow the creation of CloudWatch Logs keys only if they expire within 90 days. + + * **Apply least-privilege permissions.** Scope the IAM user's permissions to only the log groups and actions required. Use the managed [CloudWatchLogsAPIKeyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) policy as a starting point and restrict further as needed. + + * **Enable CloudTrail logging.** Audit API key usage by enabling CloudTrail data events for `AWS::Logs::LogGroupAuthorization`. See Logging API key usage with CloudTrail. + + * **Monitor with IAM Access Analyzer.** Use [IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/what-is-access-analyzer.html) to identify unused credentials and overly permissive policies associated with your API key IAM users. + + * **Rotate keys regularly.** Establish a rotation schedule and follow the process described in Rotating API keys. + + + +