This guide describes how to use the Security Command Center Security Command Center API to manage security marks. Security marks, or "marks", are customizable annotations on assets or findings in Security Command Center that let you add your own business context to these objects.
You can add or update security marks only on assets that are supported by Security Command Center. For a list of the assets that Security Command Center supports, see Supported asset types in Security Command Center.
Before you begin
Before you can work with security marks, you need to Set up a service account and SDK.
To add or change security marks, you must have an Identity and Access Management role that includes permissions for the kind of mark that you want to use:
- Asset marks: Asset Security Marks Writer,
securitycenter.assetSecurityMarksWriter
- Finding marks: Finding Security Marks Writer,
securitycenter.findingSecurityMarksWriter
For more information on IAM roles in Security Command Center, see Access control. To learn how to use security marks effectively, see Using Security Command Center security marks.
Adding or updating security marks on assets
When using the Security Command Center API, adding and updating security marks are the
same operation. The example below shows how to add security marks for two key
value pairs (key_a, value_a)
and (key_b, value_b)
.
The following code uses field masks to ensure that only those values are updated. If field masks aren't provided, all security marks are cleared before adding the given keys and values.
gcloud
# ORGANIZATION=12344321 # ASSET=43211234 SECURITY_MARKS="key_a=value_a,key_b=value_b" UPDATE_MASK="marks.key_a,marks.key_b" gcloud scc assets update-marks $ASSET \ --organization $ORGANIZATION \ --security-marks $SECURITY_MARKS \ --update-mask $UPDATE_MASK
For more examples, run:
gcloud scc assets update-marks --help
Python
Java
Go
Node.js
Read Managing policies for information on dedicated asset marks for Security Health Analytics detectors.
Deleting security marks on assets
Deleting specific security marks is accomplished in a similar fashion to adding
or updating them, specifically calling update with a field mask but without
any corresponding value. In the example below, security marks with keys key_a
and key_b
are deleted.
gcloud
# ORGANIZATION=12344321 # ASSET=43211234 UPDATE_MASK="marks.key_a,marks.key_b" gcloud scc assets update-marks $ASSET \ --organization $ORGANIZATION \ --update-mask $UPDATE_MASK
For more examples, run:
gcloud scc assets update-marks --help
Python
Java
Go
Node.js
Adding and deleting security marks in the same request
The technique to add and update security marks and deleting security marks can
be combined into the same request. In the example below, key_a
is updated
while key_b
is deleted.
gcloud
# ORGANIZATION=12344321 # ASSET=43211234 SECURITY_MARKS="key_a=new_value_for_a" UPDATE_MASK="marks.key_a,marks.key_b" gcloud scc assets update-marks $ASSET \ --organization $ORGANIZATION \ --security-marks $SECURITY_MARKS \ --update-mask $UPDATE_MASK
For more examples, run:
gcloud scc assets update-marks --help
gcloud
# ORGANIZATION=12344321 # ASSET=43211234 SECURITY_MARKS="key_a=new_value_for_a" UPDATE_MASK="marks.key_a,marks.key_b" gcloud scc assets update-marks $ASSET \ --organization $ORGANIZATION \ --security-marks $SECURITY_MARKS \ --update-mask $UPDATE_MASK
For more examples, run:
gcloud scc assets update-marks --help
Python
Java
Go
Node.js
Adding Security Marks to Findings
Adding, updating, and deleting security marks on findings follows the same process as updating security marks on assets. The only change is the name of the resource used in the API call. Instead of an asset resource, you provide a finding resource name.
For example, to update security marks on a finding, use the following code:
gcloud
# ORGANIZATION=12344321 # SOURCE=43211234 # FINDING_ID=testfindingid SECURITY_MARKS="key_a=value_a,key_b=value_b" UPDATE_MASK="marks.key_a,marks.key_b" gcloud scc findings update-marks $FINDING_ID \ --source $SOURCE \ --organization $ORGANIZATION \ --security-marks $SECURITY_MARKS \ --update-mask $UPDATE_MASK
For more examples, run:
gcloud scc findings update-marks --help
Python
Java
Go
Node.js
Security marks are processed during batch scans—which run twice daily—and not in real time. There may be a delay of 12 to 24 hours before security marks are processed and enforcement policies that resolve or reopen findings are applied.
Listing assets with security mark filters
After security marks are set on an asset, they can be used in the filter
argument to the ListAssets
API call. For example, to query for all assets
where key_a = value_a
, use the following code:
gcloud
# ORGANIZATION=12344321 FILTER="security_marks.marks.key_a = \"value_a\"" gcloud scc assets list $ORGANIZATION \ --filter "$FILTER"
For more examples, run:
gcloud scc assets list --help
Python
Java
Go
Node.js
Listing findings with security mark filters
After security marks are set on a finding, they can be used in the filter
argument to the ListFindings
API call. For example, to query all assets where
key_a != value_a
, use the following code:
gcloud
# ORGANIZATION=12344321 # SOURCE=43211234 FILTER="NOT security_marks.marks.key_a=\"value_a\"" gcloud scc findings list $ORGANIZATION \ --source $SOURCE \ --filter "$FILTER"
For more examples, run:
gcloud scc findings list --help
Python
Java
Go
Node.js
What's next
- Learn more about listing findings and listing assets.