Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions,
see Getting Started with Amazon Web Services in China
(PDF).
Tagging Amazon Security Hub resources
A tag is an optional label that you can define and assign
to Amazon resources, including certain types of Amazon 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 Amazon 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 Amazon. 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 Amazon Web Services account and only in the
Amazon Web Services 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 Amazon Web Services Region.
They aren't applied to any associated, supporting resources that Security Hub
creates, uses, or maintains for you in other Amazon Web 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 Amazon Resource Groups or the Amazon Web 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 Amazon Web Services, including Amazon 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 Amazon 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 Amazon Web Services, including Security Hub.
For additional tagging tips and best practices, see Tagging your Amazon resources
in the Tagging Amazon Resources User Guide.
After you start tagging resources, you can define tag-based, resource-level permissions in
Amazon Identity and Access Management (IAM) policies. By using tags in this way, you can implement granular
control of which users and roles in your Amazon Web Services 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
Amazon 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 Amazon resources
using tags in the IAM User Guide.
To add tags to an individual Amazon 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 Amazon 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 Amazon 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 & Amazon 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 Amazon 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 Amazon 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-cn: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
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-cn: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-cn: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 Amazon Resource Groups Tagging
API.
- Console
-
To review the tags for a resource
Using the credentials of the Security Hub administrator, open the Amazon Security Hub console at https://console.amazonaws.cn/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 & Amazon 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 Amazon 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-cn: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 Amazon Resource Groups Tagging API. In your
request, set the value for the ResourceTypeFilters
parameter to
securityhub
. To do this using the Amazon 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 Amazon 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 Amazon 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 Amazon Identity and Access Management (IAM) policies that might
use the tag to control access to resources.
- Security Hub API & Amazon 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
Amazon 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 Amazon 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-cn: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
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-cn: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 Amazon 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 Amazon Resource Groups Tagging API.
Removing tags from a resource can affect access to the resource. Before you remove
a tag, review any Amazon Identity and Access Management (IAM) policies that might use the tag to control
access to resources.
- Security Hub API & Amazon 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 Amazon 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-cn: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-cn: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.