2023/06/07 - Amazon CloudWatch Logs - 3 new 1 updated api methods
Changes This change adds support for account level data protection policies using 3 new APIs, PutAccountPolicy, DeleteAccountPolicy and DescribeAccountPolicy. DescribeLogGroup API has been modified to indicate if account level policy is applied to the LogGroup via "inheritedProperties" list in the response.
Creates an account-level data protection policy that applies to all log groups in the account. A data protection policy can help safeguard sensitive data that's ingested by your log groups by auditing and masking the sensitive log data. Each account can have only one account-level policy.
Warning
Sensitive data is detected and masked when it is ingested into a log group. When you set a data protection policy, log events ingested into the log groups before that time are not masked.
If you use PutAccountPolicy to create a data protection policy for your whole account, it applies to both existing log groups and all log groups that are created later in this account. The account policy is applied to existing log groups with eventual consistency. It might take up to 5 minutes before sensitive data in existing log groups begins to be 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.
To use the PutAccountPolicy operation, you must be signed on with the logs:PutDataProtectionPolicy and logs:PutAccountPolicy permissions.
The PutAccountPolicy operation applies to all log groups in the account. You can also use PutDataProtectionPolicy to create a data protection policy that applies to just one log group. If a log group has its own data protection policy and the account also has an account-level data protection policy, then the two policies are cumulative. Any sensitive term specified in either policy is masked.
See also: AWS API Documentation
Request Syntax
client.put_account_policy(
policyName='string',
policyDocument='string',
policyType='DATA_PROTECTION_POLICY',
scope='ALL'
)
string
[REQUIRED]
A name for the policy. This must be unique within the account.
string
[REQUIRED]
Specify the data protection policy, in JSON.
This policy must include two JSON blocks:
The first block must include both a DataIdentifer array and an Operation property with an Audit action. The DataIdentifer 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 an Audit action is required to find the sensitive data terms. This Audit action must contain a FindingsDestination object. You can optionally use that FindingsDestination 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 an Operation property with an Deidentify action. The DataIdentifer array must exactly match the DataIdentifer array in the first block of the policy. The Operation property with the Deidentify 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.
Warning
The contents of the two DataIdentifer arrays must match exactly.
In addition to the two JSON blocks, the policyDocument can also include Name , Description , and Version fields. The Name is different than the operation's policyName parameter, and is used as a dimension when CloudWatch Logs reports audit findings metrics to CloudWatch.
The JSON specified in policyDocument can be up to 30,720 characters.
string
[REQUIRED]
Currently the only valid value for this parameter is DATA_PROTECTION_POLICY .
string
Currently the only valid value for this parameter is GLOBAL , which specifies that the data protection policy applies to all log groups in the account. If you omit this parameter, the default of GLOBAL is used.
dict
Response Syntax
{
'accountPolicy': {
'policyName': 'string',
'policyDocument': 'string',
'lastUpdatedTime': 123,
'policyType': 'DATA_PROTECTION_POLICY',
'scope': 'ALL',
'accountId': 'string'
}
}
Response Structure
(dict) --
accountPolicy (dict) --
The account policy that you created.
policyName (string) --
The name of the account policy.
policyDocument (string) --
The policy document for this account policy.
The JSON specified in policyDocument can be up to 30,720 characters.
lastUpdatedTime (integer) --
The date and time that this policy was most recently updated.
policyType (string) --
The type of policy for this account policy.
scope (string) --
The scope of the account policy.
accountId (string) --
The Amazon Web Services account ID that the policy applies to.
Deletes a CloudWatch Logs account policy.
To use this operation, you must be signed on with the logs:DeleteDataProtectionPolicy and logs:DeleteAccountPolicy permissions.
See also: AWS API Documentation
Request Syntax
client.delete_account_policy(
policyName='string',
policyType='DATA_PROTECTION_POLICY'
)
string
[REQUIRED]
The name of the policy to delete.
string
[REQUIRED]
The type of policy to delete. Currently, the only valid value is DATA_PROTECTION_POLICY .
None
Returns a list of all CloudWatch Logs account policies in the account.
See also: AWS API Documentation
Request Syntax
client.describe_account_policies(
policyType='DATA_PROTECTION_POLICY',
policyName='string',
accountIdentifiers=[
'string',
]
)
string
[REQUIRED]
Use this parameter to limit the returned policies to only the policies that match the policy type that you specify. Currently, the only valid value is DATA_PROTECTION_POLICY .
string
Use this parameter to limit the returned policies to only the policy with the name that you specify.
list
If you are using an account that is set up as a monitoring account for CloudWatch unified cross-account observability, you can use this to specify the account ID of a source account. If you do, the operation returns the account policy for the specified account. Currently, you can specify only one account ID in this parameter.
If you omit this parameter, only the policy in the current account is returned.
(string) --
dict
Response Syntax
{
'accountPolicies': [
{
'policyName': 'string',
'policyDocument': 'string',
'lastUpdatedTime': 123,
'policyType': 'DATA_PROTECTION_POLICY',
'scope': 'ALL',
'accountId': 'string'
},
]
}
Response Structure
(dict) --
accountPolicies (list) --
An array of structures that contain information about the CloudWatch Logs account policies that match the specified filters.
(dict) --
A structure that contains information about one CloudWatch Logs account policy.
policyName (string) --
The name of the account policy.
policyDocument (string) --
The policy document for this account policy.
The JSON specified in policyDocument can be up to 30,720 characters.
lastUpdatedTime (integer) --
The date and time that this policy was most recently updated.
policyType (string) --
The type of policy for this account policy.
scope (string) --
The scope of the account policy.
accountId (string) --
The Amazon Web Services account ID that the policy applies to.
{'logGroups': {'inheritedProperties': ['ACCOUNT_DATA_PROTECTION']}}
Lists the specified log groups. You can list all your log groups or filter the results by prefix. The results are ASCII-sorted by log group name.
CloudWatch Logs doesn’t support IAM policies that control access to the DescribeLogGroups action by using the aws:ResourceTag/key-name condition key. Other CloudWatch Logs actions do support the use of the aws:ResourceTag/key-name condition key to control access. For more information about using tags to control access, see Controlling access to Amazon Web Services resources using tags.
If you are using CloudWatch cross-account observability, you can use this operation in a monitoring account and view data from the linked source accounts. For more information, see CloudWatch cross-account observability.
See also: AWS API Documentation
Request Syntax
client.describe_log_groups(
accountIdentifiers=[
'string',
],
logGroupNamePrefix='string',
logGroupNamePattern='string',
nextToken='string',
limit=123,
includeLinkedAccounts=True|False
)
list
When includeLinkedAccounts is set to True , use this parameter to specify the list of accounts to search. You can specify as many as 20 account IDs in the array.
(string) --
string
The prefix to match.
Note
logGroupNamePrefix and logGroupNamePattern are mutually exclusive. Only one of these parameters can be passed.
string
If you specify a string for this parameter, the operation returns only log groups that have names that match the string based on a case-sensitive substring search. For example, if you specify Foo , log groups named FooBar , aws/Foo , and GroupFoo would match, but foo , F/o/o and Froo would not match.
If you specify logGroupNamePattern in your request, then only arn , creationTime , and logGroupName are included in the response.
Note
logGroupNamePattern and logGroupNamePrefix are mutually exclusive. Only one of these parameters can be passed.
string
The token for the next set of items to return. (You received this token from a previous call.)
integer
The maximum number of items returned. If you don't specify a value, the default is up to 50 items.
boolean
If you are using a monitoring account, set this to True to have the operation return log groups in the accounts listed in accountIdentifiers .
If this parameter is set to true and accountIdentifiers contains a null value, the operation returns all log groups in the monitoring account and all log groups in all source accounts that are linked to the monitoring account.
dict
Response Syntax
{
'logGroups': [
{
'logGroupName': 'string',
'creationTime': 123,
'retentionInDays': 123,
'metricFilterCount': 123,
'arn': 'string',
'storedBytes': 123,
'kmsKeyId': 'string',
'dataProtectionStatus': 'ACTIVATED'|'DELETED'|'ARCHIVED'|'DISABLED',
'inheritedProperties': [
'ACCOUNT_DATA_PROTECTION',
]
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
logGroups (list) --
The log groups.
If the retentionInDays value is not included for a log group, then that log group's events do not expire.
(dict) --
Represents a log group.
logGroupName (string) --
The name of the log group.
creationTime (integer) --
The creation time of the log group, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
retentionInDays (integer) --
The number of days to retain the log events in the specified log group. Possible values are: 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1096, 1827, 2192, 2557, 2922, 3288, and 3653.
To set a log group so that its log events do not expire, use DeleteRetentionPolicy.
metricFilterCount (integer) --
The number of metric filters.
arn (string) --
The Amazon Resource Name (ARN) of the log group.
storedBytes (integer) --
The number of bytes stored.
kmsKeyId (string) --
The Amazon Resource Name (ARN) of the KMS key to use when encrypting log data.
dataProtectionStatus (string) --
Displays whether this log group has a protection policy, or whether it had one in the past. For more information, see PutDataProtectionPolicy.
inheritedProperties (list) --
Displays all the properties that this log group has inherited from account-level settings.
(string) --
nextToken (string) --
The token for the next set of items to return. The token expires after 24 hours.