This guide walks you through creating and updating findings using the Security Command Center API.
Before you begin
Before you create and update findings, you need to complete the following:
To complete this guide, you must have the Identity and Access Management (IAM) Security
Center Findings Editor (securitycenter.findingsEditor
) role at the
organization level. For more information on
Security Command Center roles, see
Access control.
If you want to create findings with security marks, you must also have an IAM role that includes permissions for the kind of mark that you want to use:
- Asset Security Marks Writer (
securitycenter.assetSecurityMarksWriter
) - Finding Security Marks Writer (
securitycenter.findingSecurityMarksWriter
)
For more information about marks, see Using Security Command Center security marks.
Creating a finding
Create an active finding for a source.
gcloud
# ORGANIZATION=12344321 # SOURCE=43211234 # FINDING_ID=testfindingid # EVENT_TIME follows the format YYYY-MM-DDThh:mm:ss.ffffffZ EVENT_TIME=2019-02-28T07:00:06.861Z STATE=ACTIVE CATEGORY=MEDIUM_RISK_ONE RESOURCE_NAME=//cloudresourcemanager.googleapis.com/projects/PROJECT_ID gcloud scc findings create $FINDING_ID \ --source $SOURCE \ --organization $ORGANIZATION \ --state $STATE \ --category $CATEGORY \ --event-time $EVENT_TIME --resource-name $RESOURCE_NAME
For more examples, run:
gcloud scc findings create --help
Python
Java
Go
Node.js
For information on how long findings data is stored in Security Command Center, read Findings retention.
Creating a finding with Source Properties
Security Command Center allows Sources to add context to findings through key-value metadata called "Source Properties." Source Properties can be initialized at creation time. The example below shows how to create a finding with source properties.
Create a finding with source properties. The length of the key names in the
source_properties
map must be from 1 to 255 characters, and must start with a
letter and contain only alphanumeric characters or underscores.
Security Command Center only supports values of boolean, number, and string.
gcloud
# ORGANIZATION=12344321 # SOURCE=43211234 # FINDING_ID=testfindingid # EVENT_TIME follows the format YYYY-MM-DDThh:mm:ss.ffffffZ EVENT_TIME=2019-02-28T07:00:06.861Z STATE=ACTIVE CATEGORY=MEDIUM_RISK_ONE SOURCE_PROPERTY_KEY=gcloud_client_test SOURCE_PROPERTY_VALUE=value RESOURCE_NAME=//cloudresourcemanager.googleapis.com/projects/PROJECT_ID gcloud scc findings create $FINDING_ID \ --source $SOURCE \ --organization $ORGANIZATION \ --state $STATE \ --category $CATEGORY \ --event-time $EVENT_TIME \ --source-properties $SOURCE_PROPERTY_KEY=$SOURCE_PROPERTY_VALUE --resource-name $RESOURCE_NAME
- More source properties can be added using a comma-separated list of key/value pairs.
For more examples, run:
gcloud scc findings create --help
Python
Java
Go
Node.js
Update a finding's source properties
This example shows how to update individual source properties and the event time. It uses field masks to only update specific fields. Without the field masks, the new values replace all mutable fields on the finding.
As with creating a new finding, the key names in the source_properties
map
must be between 1 and 255 characters, and must start with a letter and contain
alphanumeric characters or underscores only. Security Command Center only
supports values of boolean, number, and string.
gcloud
# ORGANIZATION=12344321 # SOURCE=43211234 # FINDING_ID=testfindingid # EVENT_TIME follows the format YYYY-MM-DDThh:mm:ss.ffffffZ EVENT_TIME=2019-02-28T08:00:06.861Z SOURCE_PROPERTY_KEY=gcloud_client_test SOURCE_PROPERTY_VALUE=VALUE UPDATE_MASK=source_properties,event_time gcloud scc findings update $FINDING_ID \ --source $SOURCE \ --organization $ORGANIZATION \ --event-time $EVENT_TIME \ --source-properties $SOURCE_PROPERTY_KEY=$SOURCE_PROPERTY_VALUE \ --update-mask=$UPDATE_MASK
- Use --update-mask '' (empty) to override all mutable fields.
- More source properties can be added using a comma-separated list of key/value pairs.
For more examples, run:
gcloud scc findings update --help
Python
Java
Go
Node.js
Updating a finding's state
Security Command Center also provides an API to only update a finding's state. This API exists to provide a means of updating just the state of a finding. It is a simple API that also allows for permissioning principals to only be able to modify the state and no other aspect of a finding. The example below shows how to change a finding's state to inactive.
gcloud
# ORGANIZATION=12344321 # SOURCE=43211234 # FINDING_ID=testfindingid # EVENT_TIME follows the format YYYY-MM-DDThh:mm:ss.ffffffZ EVENT_TIME=2019-02-28T09:00:06.861Z STATE=INACTIVE gcloud scc findings update $FINDING_ID \ --source $SOURCE \ --organization $ORGANIZATION \ --state $STATE \ --event-time $EVENT_TIME
For more examples, run:
gcloud scc findings update --help
Python
Java
Go
Node.js
Verifying finding permissions
Creating and updating findings requires one of the following IAM permissions:
- Creating and updating findings:
securitycenter.findings.update
. - Updating findings only:
securitycenter.findings.setState
.
If you can't create findings for a source, use the following code to confirm that your account has the required permissions listed in the Before you begin section. If you don't have the necessary permissions, see Creating and managing security sources to set up the appropriate IAM policies.
Python
Java
Go
Node.js
What's next
Learn more about accessing Security Command Center using client libraries.