Security Command Center findings model the potential security risks of an organization's assets. A finding always relates to a specific asset in Security Command Center.
This guide shows you how to use Security Command Center client libraries to access an organization's findings. Each finding belongs to a source. Most detectors or finding providers produce findings within the same source.
Before you begin
Before you set up a source, you need to complete the following:
Page size
All Security Command Center list APIs are paginated. Each response returns a page of results and a token to return the next page. The page size is configurable. The default pageSize is 10, it can be set to a minimum of 1, and maximum of 1000.
Findings retention
Findings contain a series of event_time
snapshots that capture the state and properties
of the finding each time the associated vulnerability or threat is encountered during scans.
Security Command Center stores finding snapshots for 13 months from their event_time
, or the
time the event took place. After 13 months, finding snapshots and their data are deleted from the
Security Command Center database and cannot be recovered. This results in fewer snapshots in a finding,
limiting the ability to view the history of a finding and how it's changed over time.
A finding persists in Security Command Center as long as it contains at least one snapshot with an
event_time
more recent than 13 months. To keep findings and all of their data for
longer periods, export them to another storage location. Read Exporting
Security Command Center data for instructions.
Listing all findings in an organization
gcloud
# ORGANIZATION_ID=organization-id gcloud scc findings list $ORGANIZATION_ID
For more examples, run:
gcloud scc findings list --help
Python
Java
Go
Node.js
The output for each finding resembles the following:
finding:
category: 'Persistence: IAM Anomalous Grant'
createTime: '2020-09-13T12:30:10.248Z'
eventTime: '2020-09-13T12:30:09.528Z'
name: organizations/organization-id/sources/source-id/findings/finding-id
parent: organizations/organization-id/sources/source-id
resourceName: //cloudresourcemanager.googleapis.com/projects/project-number
securityMarks:
name: organizations/organization-id/sources/source-id/findings/finding-id/securityMarks
sourceProperties:
affectedResources:
- gcpResourceName: //cloudresourcemanager.googleapis.com/projects/project-number
detectionCategory:
indicator: audit_log
ruleName: iam_anomalous_grant
subRuleName: service_account_granted_sensitive_role_to_member
technique: persistence
detectionPriority: HIGH
evidence:
- sourceLogId:
insertId: insert-id
projectId: project-id
timestamp:
nanos: 183000000
seconds: '1600000206'
findingId: finding-id
properties:
sensitiveRoleGrant:
bindingDeltas:
- action: ADD
member: user:user-email@gmail.com
role: roles/editor
members:
- user:user-email@gmail.com
principalEmail: principal-email.iam.gserviceaccount.com
sourceId:
customerOrganizationNumber: 'organization-id'
projectNumber: 'project-number'
state: ACTIVE
resource:
name: //cloudresourcemanager.googleapis.com/projects/project-number
parentDisplayName: organization-name
parentName: //cloudresourcemanager.googleapis.com/folders/folder-id
projectDisplayName: project-id
projectName: //cloudresourcemanager.googleapis.com/projects/project-number
Filtering findings
An organization might have many findings. The preceding example doesn't use a filter, so all finding records are returned. Security Command Center enables you to use finding filters to get information about only the findings you want, and limit the parent to a specific source.
Finding filters are like "where" clauses in SQL statements, except instead of columns, they apply to the objects returned by the API.
Below is an example of only listing findings that have a category
"MEDIUM_RISK_ONE
". Specific categories might change and you should consult
the documentation of a finding provider to determine the categories they use.
gcloud
# ORGANIZATION_ID=organization-id # SOURCE_ID="source-id" FILTER="category=\"MEDIUM_RISK_ONE\"" gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID --filter="$FILTER"
For more examples, run:
gcloud scc findings list --help
Python
Java
Go
Node.js
Security Command Center also supports full JSON arrays and objects as potential property types. You can filter on:
- Array elements
- Full JSON objects with partial string match within the object
- JSON object subfields
Sub-fields must be numbers, strings, or booleans and they must use the following operators:
- Strings:
- Full equality
=
- Partial string matching
:
- Full equality
- Numbers:
- Inequalities
<
,>
,<=
,>=
- Equality
=
- Inequalities
- Booleans:
- Equality
=
- Equality
The examples later on this page assume the following JSON object is a source property on a finding:
{
"outer_object": {
"middle_object": {
"deeply_nested_object": {
"x": 123,
},
"y": "some-string-value",
},
"z": "some-other-string-value",
"u": ["list-element-1", "list-element-2", "list-element-3", ],
},
}
Filtering findings example
In this example, the previous JSON object is a source property named
my_property
on a finding. The following example includes queries for findings
that have the object as a property. You can also use these filters with other
filters using AND
and OR
in your query.
# ORGANIZATION_ID=organization-id
# SOURCE_ID="source-id"
gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID \
--filter="source_properties.my_property.outer_object.middle_object.deeply_nested_object.x = 123"
gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID \
--filter="source_properties.my_property.outer_object.middle_object.y = \"some-string-value\""
gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID \
--filter="source_properties.my_property.outer_object.middle_object.y : \"string-value\""
gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID \
--filter="source_properties.my_property.outer_object.z = \"some-other-string-value\""
gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID \
--filter="source_properties.my_property.outer_object.z : \"other-string-value\""
gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID \
--filter="source_properties.my_property.outer_object.u : \"list-element-1\""
gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID \
--filter="source_properties.my_property.outer_object.u : \"list-element-2\""
gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID \
--filter="source_properties.my_property.outer_object.u : \"list-element-3\""
Sorting findings example
You can sort findings by strict subfields that are primitive types—strings,
numbers, and booleans. In this example, the previous JSON object is a source
property named my_property
on a finding. The following example includes
queries to sort the finding fields:
# ORGANIZATION_ID=organization-id
# SOURCE_ID="source-id"
gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID \
--order-by="source_properties.my_property.outer_object.middle_object.deeply_nested_object.x DESC"
gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID \
--order-by="source_properties.my_property.outer_object.middle_object.deeply_nested_object.x"
gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID \
--order-by="source_properties.my_property.outer_object.middle_object.y DESC"
gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID \
--order-by="source_properties.my_property.outer_object.middle_object.y"
gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID \
--order-by="source_properties.my_property.outer_object.z DESC"
gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID \
--order-by="source_properties.my_property.outer_object.z"
Point-in-time queries
Security Command Center lets you list findings as of a particular snapshot time, up to 13 months old. Read findings retention for more information.
gcloud
# ORGANIZATION_ID=organization-id # SOURCE_ID="source-id" # READ_TIME follows the format YYYY-MM-DDThh:mm:ss.ffffffZ READ_TIME=2019-02-28T07:00:06.861Z gcloud scc findings list $ORGANIZATION_ID --source=$SOURCE_ID --read-time=$READ_TIME
For more examples, run:
gcloud scc findings list --help
Python
Java
Go
Node.js
Filter examples
Following are some other useful finding filters.
Findings that occurred after a point-in-time
These example filters match findings that most recently occurred after
Wednesday, June 5, 2019 10:12:05 PM GMT. With the event_time
filter, you can
express time using the following formats and types:
Unix time (in milliseconds) as an integer literal
"event_time > 1559772725000"
RFC 3339 as a string literal
"event_time > \"2019-06-05T22:34:40+00:00\""