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
gcloud scc findings create FINDING_NAME \ --organization=PARENT_ID \ --location=LOCATION \ --source=SOURCE_ID \ --state=STATE \ --category=CATEGORY \ --event-time=EVENT_TIME \ --resource-name=RESOURCE_NAME
Replace the following:
FINDING_NAME
: the name of the finding.PARENT_ID
: the numeric ID of the parent organization.LOCATION
: if data residency is enabled, the Security Command Center location in which to create a finding; if data residency is not enabled, use the valueglobal
.SOURCE_ID
: the numeric ID of the source for the finding.STATE
: the state of the finding; useACTIVE
if the finding needs attention orINACTIVE
if the finding has been addressed.CATEGORY
: the taxonomy group that the finding belongs to; for example,AUDIT_LOGGING_DISABLED
.EVENT_TIME
: the time when the event occurred, formatted as an RFC 822 timestamp or another timestamp format that the gcloud CLI supports.RESOURCE_NAME
: the full resource name of the resource that the finding applies to.
Go
Java
Node.js
Python
For information on how long findings data is stored in Security Command Center, read Findings retention.
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
gcloud scc findings update \ PARENT/PARENT_ID/sources/SOURCE_ID/locations/LOCATION/findings/FINDING_NAME \ --state=STATE
Replace the following:
PARENT
: the level of the resource hierarchy where the finding is located; useorganizations
,folders
, orprojects
.PARENT_ID
: the numeric ID of the parent organization, folder, or project, or the alphanumeric ID of the parent project.SOURCE_ID
: the numeric ID of the source for the finding.LOCATION
: if data residency is enabled, the Security Command Center location in which to update a finding; if data residency is not enabled, use the valueglobal
.FINDING_NAME
: the finding to update.STATE
: the state of the finding; useACTIVE
if the finding needs attention orINACTIVE
if the finding has been addressed.
Go
Java
Node.js
What's next
Learn more about accessing Security Command Center using client libraries.