Amazon CloudWatch Logs

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.

DeleteAccountPolicy (new) Link ¶

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'
)
type policyName

string

param policyName

[REQUIRED]

The name of the policy to delete.

type policyType

string

param policyType

[REQUIRED]

The type of policy to delete. Currently, the only valid value is DATA_PROTECTION_POLICY .

returns

None

DescribeAccountPolicies (new) Link ¶

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',
    ]
)
type policyType

string

param policyType

[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 .

type policyName

string

param policyName

Use this parameter to limit the returned policies to only the policy with the name that you specify.

type accountIdentifiers

list

param accountIdentifiers

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) --

rtype

dict

returns

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.

PutAccountPolicy (new) Link ¶

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'
)
type policyName

string

param policyName

[REQUIRED]

A name for the policy. This must be unique within the account.

type policyDocument

string

param policyDocument

[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.

type policyType

string

param policyType

[REQUIRED]

Currently the only valid value for this parameter is DATA_PROTECTION_POLICY .

type scope

string

param scope

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.

rtype

dict

returns

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.

DescribeLogGroups (updated) Link ¶
Changes (response)
{'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
)
type accountIdentifiers

list

param accountIdentifiers

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) --

type logGroupNamePrefix

string

param logGroupNamePrefix

The prefix to match.

Note

logGroupNamePrefix and logGroupNamePattern are mutually exclusive. Only one of these parameters can be passed.

type logGroupNamePattern

string

param logGroupNamePattern

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.

type nextToken

string

param nextToken

The token for the next set of items to return. (You received this token from a previous call.)

type limit

integer

param limit

The maximum number of items returned. If you don't specify a value, the default is up to 50 items.

type includeLinkedAccounts

boolean

param includeLinkedAccounts

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.

rtype

dict

returns

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.