# Tagging Security Hub resources
A *tag* is an optional label that you can define and assign to AWS resources, including certain types of AWS Security Hub CSPM resources. Tags can help you identify, categorize, and manage resources in different ways, such as by purpose, owner, environment, or other criteria. For example, you can use tags to distinguish between resources, identify resources that support certain compliance requirements or workflows, or allocate costs.
You can add tags to the following types of Security Hub CSPM resources:
+ Automation rules
+ Configuration policies
+ `Hub` resource
## Tagging fundamentals
A resource can have as many as 50 tags. Each tag consists of a required *tag key* and an optional *tag value*, both of which you define. A *tag key* is a general label that acts as a category for a more specific tag value. A *tag value* acts as a descriptor for a tag key.
For example, if you create different automation rules for different environments (one set of automation rules for test accounts and another for production accounts), you might assign an `Environment` tag key to those rules. The associated tag value might be `Test` for the rules that are associated with test accounts, and `Prod` for the rules that are associated with production accounts and OUs.
As you define and assign tags to AWS Security Hub CSPM resources, keep the following in mind:
+ Each resource can have a maximum of 50 tags.
+ For each resource, each tag key must be unique and it can have only one tag value.
+ Tag keys and values are case sensitive. As a best practice, we recommend that you define a strategy for capitalizing tags and implement that strategy consistently across your resources.
+ A tag key can have a maximum of 128 UTF-8 characters. A tag value can have a maximum of 256 UTF-8 characters. The characters can be letters, numbers, spaces, or the following symbols: \$1 . : / = \$1 - @
+ The `aws:` prefix is reserved for use by AWS. You can’t use it in any tag keys or values that you define. In addition, you can't change or remove tag keys or values that use this prefix. Tags that use this prefix don’t count against the quota of 50 tags per resource.
+ Any tags that you assign are available only for your AWS account and only in the AWS Region in which you assign them.
+ If you assign tags to a resource by using Security Hub CSPM, the tags are applied only to the resource that's stored directly in Security Hub CSPM in the applicable AWS Region. They aren't applied to any associated, supporting resources that Security Hub CSPM creates, uses, or maintains for you in other AWS services. For example, if you assign tags to an automation rule that updates findings related to Amazon Simple Storage Service (Amazon S3), the tags are applied only to your automation rule in Security Hub CSPM for the specified Region. They aren't applied to your S3 buckets. To also assign tags to an associated resource, you can use AWS Resource Groups or the AWS service that stores the resource—for example, Amazon S3 for an S3 bucket. Assigning tags to associated resources can help you identify supporting resources for your Security Hub CSPM resources.
+ If you delete a resource, any tags that are assigned to the resource are also deleted.
**Important**
Do not store confidential or other types of sensitive data in tags. Tags are accessible from many AWS services, including AWS Billing and Cost Management. They aren't intended to be used for sensitive data.
To add and manage tags for Security Hub CSPM resources, you can use the Security Hub CSPM console, the Security Hub CSPM API, or the AWS Resource Groups Tagging API. With Security Hub CSPM, you can add tags to a resource when you create the resource. You can also add and manage tags for individual existing resources. With Resource Groups, you can add and manage tags in bulk for multiple existing resources spanning multiple AWS services, including Security Hub CSPM.
For additional tagging tips and best practices, see [Tagging your AWS resources](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html) in the *Tagging AWS Resources User Guide*.
## Using tags in IAM policies
After you start tagging resources, you can define tag-based, resource-level permissions in AWS Identity and Access Management (IAM) policies. By using tags in this way, you can implement granular control of which users and roles in your AWS account have permission to create and tag resources, and which users and roles have permission to add, edit, and remove tags more generally. To control access based on tags, you can use [tag-related condition keys](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecurityhub.html#awssecurityhub-policy-keys) in the [Condition element](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html) of IAM policies.
For example, you can create an IAM policy that allows a user to have full access to all AWS Security Hub CSPM resources, if the `Owner` tag for the resource specifies their username:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ModifyResourceIfOwner",
"Effect": "Allow",
"Action": "securityhub:*",
"Resource": "*",
"Condition": {
"StringEqualsIgnoreCase": {"aws:ResourceTag/Owner": "${aws:username}"}
}
}
]
}
```
------
If you define tag-based, resource-level permissions, the permissions take effect immediately. This means that your resources are more secure as soon as they're created, and you can quickly start enforcing the use of tags for new resources. You can also use resource-level permissions to control which tag keys and values can be associated with new and existing resources. For more information, see [Controlling access to AWS resources using tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html) in the *IAM User Guide*.
# Adding tags to Security Hub CSPM resources
A *tag* is a label that you can define and assign to AWS resources, including certain types of AWS Security Hub CSPM resources. By using tags, you can identify, categorize, and manage resources in different ways, such as by purpose, owner, environment, or other criteria. For example, you can use tags to: apply policies, allocate costs, distinguish between versions of resources, or identify resources that support certain compliance requirements or workflows.
You can add tags to the following types of Security Hub CSPM resources:
+ Automation rules
+ Configuration policies
+ `Hub` resource
A resource can have as many as 50 tags. Each tag consists of a required *tag key* and an optional *tag value*. A *tag key* is a general label that acts as a category for a more specific tag value. A *tag value* acts as a descriptor for a tag key. For more information about tagging options and requirements, see [Tagging fundamentals](tagging-resources.md#tags-basics).
To add tags to a Security Hub CSPM resource, you can use the Security Hub CSPM console or the Security Hub CSPM API. However, the console doesn't support adding tags to the `Hub` resource.
After adding tags, you can edit the tag and change the tag key or tag value.
To add or edit tags for multiple Security Hub CSPM resources at the same time, use the tagging operations of the [AWS Resource Groups Tagging API](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/overview.html).
**Important**
Adding tags to a resource can affect access to the resource. Before you add a tag to a resource, review any AWS Identity and Access Management (IAM) policies that might use tags to control access to resources.
------
#### [ Console ]
**To add tags to a Security Hub CSPM resource (console)**
When you create an automation rule or a configuration policy, the Security Hub CSPM console provides options for adding tags to it. You can provide the tag key and tag value in the **Tags** section.
------
#### [ Security Hub CSPM API ]
**To add tags to a Security Hub CSPM resource (API)**
To create a resource and add one or more tags to it programmatically, use the appropriate operation for the type of resource that you want to create:
+ To create a configuration policy and add one or more tags to it, invoke the [CreateConfigurationPolicy](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_CreateConfigurationPolicy.html) API or, if you're using the AWS CLI, run the [create-configuration-policy](https://docs.aws.amazon.com/cli/latest/reference/securityhub/create-configuration-policy.html) command.
+ To create an automation rule and add one or more tags to it, invoke the [CreateAutomationRule](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_CreateAutomationRule.html) API or, if you're using the AWS CLI, run the [create-automation-rule](https://docs.aws.amazon.com/cli/latest/reference/securityhub/create-automation-rule.html) command.
+ To enable Security Hub CSPM and add one or more tags to your `Hub` resource, invoke the [EnableSecurityHub](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_EnableSecurityHub.html) API or, if you're using the AWS Command Line Interface (AWS CLI), run the [enable-security-hub](https://docs.aws.amazon.com/cli/latest/reference/securityhub/enable-security-hub.html) command.
In your request, use the `tags` parameter to specify the tag key and optional tag value for each tag to add to the resource. The `tags` parameter specifies an array of objects. Each object specifies a tag key and its associated tag value.
To add one or more tags to an existing resource, use the [TagResource](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_TagResource.html) operation of the Security Hub CSPM API or, if you're using the AWS CLI, run the [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/securityhub/tag-resource.html) command. In your request, specify the Amazon Resource Name (ARN) of the resource that you want to add a tag to. Use the `tags` parameter to specify the tag key (`key`) and optional tag value (`value`) for each tag to add. The `tags` parameter specifies an array of objects, one object for each tag key and its associated tag value.
For example, the following AWS CLI command adds an `Environment` tag key with a `Prod` tag value to the specified configuration policy. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability.
**Example CLI command:**
```
$ aws securityhub tag-resource \
--resource-arn arn:aws:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
--tags '{"Environment":"Prod"}'
```
Where:
+ `resource-arn` specifies the ARN of the configuration policy to add a tag to.
+ `Environment` is the tag key of the tag to add to the rule.
+ `Prod` is the tag value for the specified tag key (`Environment`).
In the following example, the command adds several tags to the configuration policy.
```
$ aws securityhub tag-resource \
--resource-arn arn:aws:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
--tags '{"Environment":"Prod", "CostCenter":"12345", "Owner":"jane-doe"}'
```
For each object in a `tags` array, both the `key` and `value` arguments are required. However, the value for the `value` argument can be an empty string. If you don’t want to associate a tag value with a tag key, don't specify a value for the `value` argument. For example, the following command adds an `Owner` tag key with no associated tag value:
```
$ aws securityhub tag-resource \
--resource-arn arn:aws:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
--tags '{"Owner":""}'
```
If a tagging operation succeeds, Security Hub CSPM returns an empty HTTP 200 response. Otherwise, Security Hub CSPM returns an HTTP 4*xx* or 500 response that indicates why the operation failed.
------
# Editing tags for Security Hub CSPM resources
As your environment or requirements change over time, you can evaluate existing tags for your AWS Security Hub CSPM resources and change the tags as necessary. A *tag* is a label that you define and assign to one or more AWS resources, including certain types of Macie resources. Each tag consists of a required *tag key* and an optional *tag value*. A *tag key* is a general label that acts as a category for a more specific tag value. A *tag value* acts as a descriptor for a tag key.
Tags can help you identify, categorize, and manage resources in different ways, such as by purpose, owner, environment, or other criteria. For example, you can use tags to: apply policies, allocate costs, distinguish between versions of resources, or identify resources that support certain compliance requirements or workflows.
You can add tags to the following types of Security Hub CSPM resources:
+ Automation rules
+ Configuration policies
+ `Hub` resource
To edit tag keys or tag values for a Security Hub CSPM resource, you can use the Security Hub CSPM API. The Security Hub CSPM console currently doesn't support tag editing.
**Important**
Editing tags for a resource can affect access to the resource. Before you edit a tag for a resource, review any AWS Identity and Access Management (IAM) policies that might use tags to control access to resources.
------
#### [ Security Hub CSPM API ]
**To edit tags for a Security Hub CSPM resource (API)**
When you edit a tag for a resource programmatically, you overwrite the existing tag with new values. Therefore, the best way to edit a tag depends on whether you want to edit a tag key, a tag value, or both. To edit a tag key, [remove the current tag](tags-remove.md) and [add a new tag](tags-add.md).
To edit or remove only the tag value that's associated with a tag key, overwrite the existing value by using the [TagResource](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_TagResource.html) operation of the Security Hub CSPM API. If you're using the AWS CLI, run the [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/securityhub/tag-resource.html) command. In your request, specify the Amazon Resource Name (ARN) of the resource whose tag value you want to edit or remove.
To edit a tag value, use the `tags` parameter to specify the tag key whose tag value you want to change. You should also specify the new tag value for the key. For example, the following AWS CLI command changes the tag value from `Prod` to `Test` for the `Environment` tag key that's assigned to the specified automation rule. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability.
```
$ aws securityhub tag-resource \
--resource-arn arn:aws:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
--tags '{"Environment":"Test"}'
```
Where:
+ `resource-arn` specifies the ARN of the configuration policy.
+ `Environment` is the tag key that's associated with the tag value to change.
+ `Test` is the new tag value for the specified tag key (`Environment`).
To remove a tag value from a tag key, don’t specify a value for the `value` argument of the key in the `tags` parameter. For example:
```
$ aws securityhub tag-resource \
--resource-arn arn:aws:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
--tags '{"Owner":""}'
```
If the operation succeeds, Security Hub CSPM returns an empty HTTP 200 response. Otherwise, Security Hub CSPM returns an HTTP 4*xx* or 500 response that indicates why the operation failed.
------
# Reviewing tags for Security Hub CSPM resources
After you add or edit tags for AWS Security Hub CSPM resources, you can view what tag keys and tag values a resource currently has. A *tag* is a label that you define and assign to one or more AWS resources, including certain types of Macie resources. Each tag consists of a required *tag key* and an optional *tag value*. A *tag key* is a general label that acts as a category for a more specific tag value. A *tag value* acts as a descriptor for a tag key.
Tags can help you identify, categorize, and manage resources in different ways, such as by purpose, owner, environment, or other criteria. For example, you can use tags to: apply policies, allocate costs, distinguish between versions of resources, or identify resources that support certain compliance requirements or workflows.
You can add tags to the following types of Security Hub CSPM resources:
+ Automation rules
+ Configuration policies
+ `Hub` resource
You can review the tags for a Security Hub CSPM automation rule or configuration policy by using the Security Hub CSPM console or the Security Hub CSPM API. The console doesn't support reviewing tags for the `Hub` resource. Programmatically, you can review tags for any resource.
To review tags for multiple Security Hub CSPM resources at the same time, use the tagging operations of the [AWS Resource Groups Tagging API](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/overview.html).
------
#### [ Console ]
**To review tags for a Security Hub CSPM resource (console)**
1. Using the credentials of the Security Hub CSPM administrator, open the AWS Security Hub CSPM console at [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/).
1. Depending on the type of resource that you want to add a tag to, do one of the following:
+ To review the tags for an automation rule, choose **Automations** in the navigation pane. Then, choose an automation rule.
+ To review the tags for a configuration policy, choose **Configuration** in the navigation pane. Then, on the **Policies** tab, select the option next to a configuration policy. A side panel opens that shows you the number of tags assigned to the policy. You can expand the **Tags** header to see the tag keys and tag values.
The **Tags** section lists all the tags that are currently assigned to the resource.
------
#### [ Security Hub CSPM API ]
**To review tags for a Security Hub CSPM resource (API)**
To retrieve and review the tags for an existing resource, invoke the [ListTagsForResource](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_ListTagsForResource.html) API. In your request, use the `resourceArn` parameter to specify the Amazon Resource Name (ARN) of the resource.
If you're using the AWS CLI, run the [list-tags-for-resource](https://docs.aws.amazon.com/cli/latest/reference/securityhub/list-tags-for-resource.html) command and use the `resource-arn` parameter to specify the ARN of the resource. For example:
```
$ aws securityhub list-tags-for-resource --resource-arn arn:aws:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
```
If the operation succeeds, Security Hub CSPM returns a `tags` array. Each object in the array specifies a tag (both the tag key and tag value) that's currently assigned to the resource. For example:
```
{
"tags": [
{
"key": "Environment",
"value": "Prod"
},
{
"key": "CostCenter",
"value": "12345"
},
{
"key": "Owner",
"value": ""
}
]
}
```
Where `Environment`, `CostCenter`, and `Owner` are the tag keys that are assigned to the resource. `Prod` is the tag value that's associated with the `Environment` tag key. `12345` is the tag value that's associated with the `CostCenter` tag key. The `Owner` tag key doesn't have an associated tag value.
To retrieve a list of all the Security Hub CSPM resources that have tags and all the tags that are assigned to each of those resources, use the [GetResources](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_GetResources.html) operation of the AWS Resource Groups Tagging API. In your request, set the value for the `ResourceTypeFilters` parameter to `securityhub`. To do this using the AWS CLI, run the [get-resources](https://docs.aws.amazon.com/cli/latest/reference/resourcegroupstaggingapi/get-resources.html) command and set the value for the `resource-type-filters` parameter to `securityhub`. For example:
```
$ aws resourcegroupstaggingapi get-resources -\-resource-type-filters "securityhub"
```
If the operation succeeds, Resource Groups returns a `ResourceTagMappingList` array. The array contains one object for each Security Hub CSPM resource that has tags. Each object specifies the ARN of a Security Hub CSPM resource, and the tag keys and values that are assigned to the resource.
------
# Removing tags from Security Hub CSPM resources
If you add tags to an AWS Security Hub CSPM resource, you can subsequently remove one or more of them. A *tag* is a label that you define and assign to AWS resources, including certain types of Security Hub CSPM resources. You can add, edit, and remove tags from the following types of Security Hub CSPM resources: automation rules, configuration policies, and the `Hub` resource.
To remove tags from an individual AWS Security Hub CSPM resource, you can use the Security Hub CSPM API. The Security Hub CSPM console currently doesn't support tag removal.
To remove tags from multiple Security Hub CSPM resources at the same time, use the tagging operations of the [AWS Resource Groups Tagging API](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/overview.html).
**Important**
Removing tags from a resource can affect access to the resource. Before you remove a tag, review any AWS Identity and Access Management (IAM) policies that might use the tag to control access to resources.
------
#### [ Security Hub CSPM API ]
**To remove tags from a Security Hub CSPM resource (API)**
To remove one or more tags from a resource programmatically, use the [UntagResource](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_UntagResource.html) operation of the Security Hub CSPM API. In your request, use the `resourceArn` parameter to specify the Amazon Resource Name (ARN) of the resource to remove a tag from. Use the `tagKeys` parameter to specify the tag key of the tag to remove. To remove multiple tags, append the `tagKeys` parameter and argument for each tag to remove, separated by an ampersand (&)—for example, `tagKeys=key1&tagKeys=key2`. To remove only a specific tag value (not a tag key) from a resource, [edit the tag](tags-update.md) instead of removing the tag.
If you're using the AWS CLI, run the [untag-resource](https://docs.aws.amazon.com/cli/latest/reference/securityhub/untag-resource.html) command to remove one or more tags from a resource. For the `resource-arn` parameter, specify the ARN of the resource to remove a tag from. Use the `tag-keys` parameter to specify the tag key of the tag to remove. For example, the following command removes the `Environment` tag (both the tag key and tag value) from the specified configuration policy:
```
$ aws securityhub untag-resource \
--resource-arn arn:aws:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
--tag-keys Environment
```
Where `resource-arn` specifies the ARN of the configuration policy to remove a tag from, and `Environment` is the tag key of the tag to remove.
To remove multiple tags from a resource, add each additional tag key as an argument for the `tag-keys` parameter. For example:
```
$ aws securityhub untag-resource \
--resource-arn arn:aws:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
--tag-keys Environment Owner
```
If the operation succeeds, Security Hub CSPM returns an empty HTTP 200 response. Otherwise, Security Hub CSPM returns an HTTP 4*xx* or 500 response that indicates why the operation failed.
------