Tagging AWS 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 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 assign tags to the following types of Security Hub resources: automation rules, configuration policies, and the
Hub resource.
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 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: _ . : / = + - @
-
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, the tags are applied only to the
resource that's stored directly in Security Hub in the applicable AWS Region.
They aren't applied to any associated, supporting resources that Security Hub
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 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 resources.
-
If you delete a resource, any tags that are assigned to the resource are also
deleted.
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 resources, you can use the Security Hub console, the Security Hub
API, or the AWS Resource Groups Tagging API. With Security Hub,
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.
For additional tagging tips and best practices, see Tagging your AWS resources
in the Tagging AWS Resources User Guide.
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 in the Condition
element of IAM policies.
For example, you can create an IAM policy that allows a user to have full access to all
AWS Security Hub resources, if the Owner tag for the resource specifies their
username:
{
"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 in the IAM User Guide.
To add tags to an individual AWS Security Hub
resource, you can use the Security Hub console or the Security Hub
API. The console doesn't support adding tags to the Hub resource.
To add tags to multiple Security Hub
resources at the same time, use the tagging operations of the AWS Resource Groups Tagging
API.
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 a tag to a resource
When you create an automation rule or a configuration policy, the Security Hub
console provides options for adding tags to it. You can provide the tag key
and tag value in the Tags section.
- Security Hub API & AWS CLI
-
To add a tag to a resource
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:
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 operation of the Security Hub API or, if you're using
the AWS CLI, run the tag-resource 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 (\)
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 key=Environment,value=Prod
Where:
-
resource-arn specifies the ARN of the configuration policy to
add a tag to.
-
Environment
-
ProdEnvironment
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 key=Environment,value=Prod key=CostCenter,value=12345 key=Owner,value=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 key=Owner,value=
If a tagging operation succeeds, Security Hub returns an empty HTTP 200 response. Otherwise,
Security Hub returns an HTTP 4xx or 500
response that indicates why the operation failed.
You can review the tags (both tag keys and tag values) for a Security Hub automation rule or configuration policy by
using the Security Hub console or the Security Hub API. The console doesn't support reviewing tags for the Hub resource.
To review tags for multiple Security Hub
resources at the same time, use the tagging operations of the AWS Resource Groups Tagging
API.
- Console
-
To review the tags for a resource
Using the credentials of the Security Hub administrator, open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.
-
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 API & AWS CLI
-
To review the tags for a resource
To retrieve and review the tags for an existing resource, invoke the ListTagsForResource 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 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 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 resources that have tags and all
the tags that are assigned to each of those resources, use the GetResources 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 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 resource that has tags. Each
object specifies the ARN of a Security Hub resource, and the tag keys and
values that are assigned to the resource.
To edit tags (tag keys or tag values) for an AWS Security Hub resource, you can use the
Security Hub API. The Security Hub console currently doesn't support tag editing.
To edit tags for multiple Security Hub resources at
the same time, use the tagging operations of the AWS Resource Groups Tagging
API.
Editing the tags for a resource can affect access to the resource. Before you edit
a tag key or value for a resource, review any AWS Identity and Access Management (IAM) policies that might
use the tag to control access to resources.
- Security Hub API & AWS CLI
-
To edit the tags for a resource
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 and add a new tag.
To edit or remove only the tag value that's associated with a tag key, overwrite the
existing value by using the TagResource operation of the Security Hub API. If you're using the
AWS CLI, run the tag-resource 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 (\) 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 key=Environment,value=Test
Where:
-
resource-arn specifies the ARN of the configuration policy.
-
Environment
-
TestEnvironment
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 key=Owner,value=
If the operation succeeds, Security Hub returns an empty HTTP 200 response. Otherwise,
Security Hub returns an HTTP 4xx or 500
response that indicates why the operation failed.
To remove tags from an AWS Security Hub resource, you can use the
Security Hub API. The Security Hub console currently doesn't support tag removal.
To remove tags from multiple Security Hub resources at the same time, use the tagging operations of the AWS Resource Groups Tagging API.
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 API & AWS CLI
-
To remove tags from a resource
To remove one or more tags from a resource programmatically, use the UntagResource operation of the Security Hub 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 instead of removing the
tag.
If you're using the AWS CLI, run the untag-resource 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
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 returns an empty HTTP 200 response. Otherwise,
Security Hub returns an HTTP 4xx or 500
response that indicates why the operation failed.
