PutDataProtectionPolicy
Creates a data protection policy for the specified log group. A data protection policy can help safeguard sensitive data that's ingested by the log group by auditing and masking the sensitive log data.
Important
Sensitive data is detected and masked when it is ingested into the log group. When you set a data protection policy, log events ingested into the log group before that time are not masked.
By default, when a user views a log event that includes masked data, the sensitive data is replaced by asterisks.
A user who has the logs:Unmask
permission can use a
GetLogEvents or
FilterLogEvents
operation with the unmask
parameter set to true
to view the unmasked
log events. Users with the logs:Unmask
can also view unmasked data in the CloudWatch Logs
console by running a CloudWatch Logs Insights query with the unmask
query command.
For more information, including a list of types of data that can be audited and masked, see Protect sensitive log data with masking.
Request Syntax
{
"logGroupIdentifier": "string
",
"policyDocument": "string
"
}
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
- logGroupIdentifier
-
Specify either the log group name or log group ARN.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
[\w#+=/:,.@-]*
Required: Yes
- policyDocument
-
Specify the data protection policy, in JSON.
This policy must include two JSON blocks:
-
The first block must include both a
DataIdentifer
array and anOperation
property with anAudit
action. TheDataIdentifer
array lists the types of sensitive data that you want to mask. For more information about the available options, see Types of data that you can mask.The
Operation
property with anAudit
action is required to find the sensitive data terms. ThisAudit
action must contain aFindingsDestination
object. You can optionally use thatFindingsDestination
object to list one or more destinations to send audit findings to. If you specify destinations such as log groups, Kinesis Data Firehose streams, and S3 buckets, they must already exist. -
The second block must include both a
DataIdentifer
array and anOperation
property with anDeidentify
action. TheDataIdentifer
array must exactly match theDataIdentifer
array in the first block of the policy.The
Operation
property with theDeidentify
action is what actually masks the data, and it must contain the"MaskConfig": {}
object. The"MaskConfig": {}
object must be empty.
For an example data protection policy, see the Examples section on this page.
Important
The contents of two
DataIdentifer
arrays must match exactly.Type: String
Required: Yes
-
Response Syntax
{
"lastUpdatedTime": number,
"logGroupIdentifier": "string",
"policyDocument": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- lastUpdatedTime
-
The date and time that this policy was most recently updated.
Type: Long
Valid Range: Minimum value of 0.
- logGroupIdentifier
-
The log group name or ARN that you specified in your request.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
[\w#+=/:,.@-]*
- policyDocument
-
The data protection policy used for this log group.
Type: String
Errors
For information about the errors that are common to all actions, see Common Errors.
- InvalidParameterException
-
A parameter is specified incorrectly.
HTTP Status Code: 400
- LimitExceededException
-
You have reached the maximum number of resources that can be created.
HTTP Status Code: 400
- OperationAbortedException
-
Multiple concurrent requests to update the same resource were in conflict.
HTTP Status Code: 400
- ResourceNotFoundException
-
The specified resource does not exist.
HTTP Status Code: 400
- ServiceUnavailableException
-
The service cannot complete the request.
HTTP Status Code: 500
Examples
To create a data protection policy
The following example creates a data protection policy in the log group.
Sample Request
POST / HTTP/1.1
Host: logs.<region>.<domain>
X-Amz-Date: <DATE>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=content-type;date;host;user-agent;x-amz-date;x-amz-target;x-amzn-requestid, Signature=<Signature>
User-Agent: <UserAgentString>
Accept: application/json
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Connection: Keep-Alive
X-Amz-Target: Logs_20140328.AssociateKmsKey
{
"logGroupIdentifier": "my-log-group",
"policyDocument": {
"Name": "data-protection-policy",
"Description": "test description",
"Version": "2021-06-01",
"Statement": [
{
"Sid": "audit-policy test",
"DataIdentifier": [
"arn:aws:dataprotection::aws:data-identifier/EmailAddress",
"arn:aws:dataprotection::aws:data-identifier/DriversLicense-US"
],
"Operation": {
"Audit": {
"FindingsDestination": {
"CloudWatchLogs": {
"LogGroup": "EXISTING_LOG_GROUP_IN_YOUR_ACCOUNT"
},
"Firehose": {
"DeliveryStream": "EXISTING_STREAM_IN_YOUR_ACCOUNT"
},
"S3": {
"Bucket": "EXISTING_BUCKET"
}
}
}
}
},
{
"Sid": "redact-policy",
"DataIdentifier": [
"arn:aws:dataprotection::aws:data-identifier/EmailAddress",
"arn:aws:dataprotection::aws:data-identifier/DriversLicense-US"
],
"Operation": {
"Deidentify": {
"MaskConfig": {}
}
}
}
]
}
}
Sample Response
HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: