This page describes how to create and edit Security Command Center findings queries by using the Query editor panel on the Findings page in the Google Cloud console and the Security Operations console.
Use queries to retrieve specific findings and filter the findings that are displayed in the findings query results.
Work with findings in the Security Command Center Enterprise consoles
If you are a Security Command Center Enterprise customer, you can work with findings in two consoles:
- Google Cloud console: available in all service tiers
- Security Operations console: available in the Enterprise tier only
For more information, see Security Command Center Enterprise consoles.
Edit findings queries
In the Query editor panel, you can add filters to your queries to select findings based on their property or attribute values. You can filter for things like the presence of values, the absence of values, or the matching of a partial string.
For information about how to edit a findings query, click the tab for the console that you are using.
Google Cloud console
- In the Google Cloud console, go to the Findings page of Security Command Center.
- Select your Google Cloud project or organization. The Findings page loads with the default query displayed in the Query preview field.
- At the right of the Query preview section, click edit Edit Query to open the Query editor panel.
- Select Add filter to navigate, search for, and add predefined attribute filters to the query.
- Select a finding attribute or type its name in the Search finding attributes box. A list of the available sub-attributes displays.
- Select a sub-attribute. A selection field displays where you can build the query statement using the sub-attribute you selected, a query operator, and one or more values for the sub-attribute.
- Select the operator and one or more values for the sub-attribute from the panel. For more information about query operators and functions that they use, see Query operators in the Add filters menu.
- Click Apply.
The dialog closes and your query is updated.
- Repeat until the findings query contains all the attributes you want.
The Select filter dialog lets you choose supported finding attributes and values.
When you're working in the query builder on the Findings page, the Quick filters section is deactivated to avoid conflicts between the two.
Security Operations console
-
In the Security Operations console, go to the Findings page.
https://CUSTOMER_SUBDOMAIN.backstory.chronicle.security/posture/findings
Replace
CUSTOMER_SUBDOMAIN
with your customer-specific identifier. - In the Query editor panel, click Add filter. The Add Filter dialog appears. This dialog lets you choose supported finding attributes and values.
- In the Category box, select or enter a finding attribute.
- In the Attribute name box, select or enter a sub-attribute.
- In the Operator box, select an evaluation option for the values of the selected sub-attribute. For more information about the evaluation options and the operators that you can use, see Query operators in the Add filters menu.
- Select Apply.
The dialog closes and your query is updated.
- Repeat this process until the findings query contains all the attributes
that you want to filter on.
To clear the filters, click Reset.
Alternatively, you can manually form a findings query the same way you form a findings filter using the Security Command Center API. As you type in your query, an autocomplete menu appears, where you can select filter names, functions, and values. To manually open the autocomplete menu, press Control+Space.
As you edit a query, the editor highlights any errors in the query, so that you can correct the errors before you submit the query.
Query operators
The query statements for Security Command Center findings support the operators that most Google Cloud APIs support.
The following list shows the use of various operators:
state="ACTIVE" AND NOT mute="MUTED"
create_time>"2023-08-15T19:05:32.428Z"
resource.parent_name:"prod"
severity="CRITICAL" OR severity="HIGH"
The following list shows all of the operators and functions that are supported in query statements for findings:
- For strings:
=
for full equality:
for partial string matching
- For numbers:
<
,>
,<=
,>=
for inequalities=
,!=
for equality
- For booleans:
=
for equality
- For logical relationships:
AND
OR
NOT
or-
- For grouping expressions:
(
,)
(parentheses)
- For arrays:
contains()
, a function for querying findings with an array field that contains at least one element that matches the specified filtercontainsOnly()
, a function for querying findings with an array field that only contains elements that match the specified filter
- For IP addresses:
inIpRange()
, a function for querying IP addresses within a specified CIDR range
Query operators in the Add filters menu
For information about the query operators that are used in Add filters menu, click the tab for the console that you are using.
Google Cloud console
In the Add filters menu of the Query editor in the Google Cloud console, query operators and functions are represented by words or phrases, such as the following:
- Equals: matches findings with this exact attribute value.
- Does not equal: matches findings that don't have this exact attribute value.
- After: matches findings with a creation or update time after a specified time.
- Before: matches findings with a creation or update time before a specified time.
- Has: matches findings with attribute values that contain the text you enter in the Keyword field.
- Does not have: matches findings with attribute values that don't contain the text you enter in the Keyword field.
- For finding attributes that contain arrays:
- Contains any: matches findings that have an array value that contains any of the text that you enter in the Keyword field.
- Contains all: matches findings that have an array value that contains all of the text that you enter in the Keyword field.
- Contains none: matches findings that don't have an array value that contains the text you enter in the Keyword field.
- Contains only: matches findings that have an array attribute that contains only the value that you enter in the Keyword field, and no other values.
- For IP addresses:
- Any within IP range: matches findings that have an IP address in a specified CIDR range.
- Does not have any within IP range: matches findings that have an IP address that is not in a specified CIDR range.
Security Operations console
In the query operators and functions are represented by the following:
Add filters menu of the Query editor in the Security Operations console,- Equals: matches findings with this exact attribute value.
- Does not equal: matches findings that don't have this exact attribute value.
- After: matches findings with a creation or update time after your specified time.
- Before: matches findings with a creation or update time before your specified time.
- Has: matches findings with attribute values that contain the text that you enter in the Keyword field.
- Does not have: matches findings with attribute values that don't contain the text that you enter in the Keyword field.
- Greater than: matches findings with attribute values that are higher than your specified value.
- Less than: matches findings with attribute values that are lower than your specified value.
- Any within IP range: matches findings that have an IP address in a specified CIDR range.
- Does not have any within IP range: matches findings that have an IP address that is not in a specified CIDR range.
Query functions
A query function provides more complex evaluations of attribute values than the common query operators.
The contains
function
Use the contains
function to evaluate attributes or attribute subfields
that can appear multiple times in the same finding.
Internally, these attributes or attribute subfields are stored in the elements of an array data structure, so they are referred to as array-type attributes.
For example, certain findings can reference multiple network
connections, so the connections
attribute is an array-type attribute.
Similarly, certain threat findings can reference multiple
IP addresses as indicators of a compromise, so the ip_addresses
subfield of the indicator
attribute is an array-type attribute.
The contains
function uses the following syntax:
contains(ARRAY_ATTRIBUTE_NAME, SUBFILTER)
Replace the following:
ARRAY_ATTRIBUTE_NAME
: the name of the array-type attribute that is stored in an array. If the array-type attribute is a subfield of another attribute, specify the attribute name and the subfield name separated by a dot.In the following example, the array-type attribute,
ip_addresses
, is a subfield ofindicator
, so both are specified in theARRAY_ATTRIBUTE_NAME
position:contains(indicator.ip_addresses, elem="192.0.2.80")
SUBFILTER
: an expression that defines how to evaluate each instance of the array-type attribute. Standard Security Command Center query operators and evaluation statements are supported.If the value to check is in a subfield of an array-type attribute, specify the subfield name on the left of the expression. The following
contains
function evaluates each element of an array ofconnections
, which is an array-type attribute that contains subfields. The values being queried for are in thedestination_ip
subfield, which is not an array-type field. The values to query for are specified with the subfield name,destination_ip
, instead of theelem
parameter.contains(connections, destination_ip="192.0.2.80")
If the subfield is the array-type attribute, specify the array-type attribute on the left of the expression with its parent and use the
elem
parameter on the right of the expression to specify the value to search for. For example, the followingcontains
function evaluates each element of an array ofip_addresses
, which is a subfield of theindicator
attribute. Theindicator
attribute is not an array-type field.contains(indicator.ip_addresses, elem="192.0.2.80")
The contains
function in the Add filter menu
In the Add filter menu, depending on the finding attribute that
you are evaluating, the contains
function is listed explicitly
or it gets included automatically when you select another filter option
that requires it.
For example, for the IP addresses sub-field of the Indicator attribute, you can select the following filter options:
- Contains any
- Contains all
- Contains none
In contrast, if you are filtering on the Destination IP sub-field of
the Connections attribute and select Any within IP range, the
contains
functions gets added to the query statement automatically,
as shown in the following example:
contains(connections, inIpRange(destination_ip, "2001:db8::/32"))
For more information about the contains
function, see
Filtering on array-type fields.
The containsOnly
function
The containsOnly
function lets you query findings for array-type attributes or
subfields that contain only the values that are specified in the subfilter, and
no others.
The containsOnly
function uses the following syntax:
containsOnly(ARRAY_ATTRIBUTE_NAME,SUBFILTER)
Replace the following:
ARRAY_ATTRIBUTE_NAME
: the name of the array-type attribute. If the array-type attribute is a subfield of another attribute, specify the attribute name and the subfield name separated by a dot. When you are running queries using the Google Cloud console, this function only supports theiam_bindings.member
and theiam_bindings.role
array attributes.SUBFILTER
: an expression that defines how to evaluate each element of the array-type attribute. Standard Security Command Center query operators and evaluation statements are supported.
In the Add filter menu, the following filter options use the containsOnly
function:
IAM binding > Member: selects only findings that include the specified users, service accounts, or groups.
IAM binding > Role: selects only findings that include the specified roles.
The following example shows a findings query in the Google Cloud console
that returns active, unmuted findings for users in the example-group
group:
state="ACTIVE" AND NOT mute="MUTED" AND containsOnly(iam_bindings,member="group:example-group@example.com")
The inIpRange
function
The inIpRange
function checks whether the IP address in a selected
finding attribute is within a range of IP addresses that
you specify by using CIDR notation (a CIDR range). The following shows
the syntax of the inIpRange
function:
inIpRange(ATTRIBUTE_WITH_IP, "CIDR_RANGE")
In the Add filter menu, the following filter
options use the inIpRange
function:
- Any within IP range: selects only findings that contain IP addresses within the specified range.
- Does not have any within IP range: selects only findings that don't contain IP addresses within the specified range.
The following example shows a findings query in the Google Cloud console
that returns active, unmuted findings in which the caller_ip
sub-field
of the access
object contains an IPv6 address in the CIDR range of 2001:db8::/32
:
state="ACTIVE" AND NOT mute="MUTED" AND inIpRange(access.caller_ip, "2001:db8::/32")
The following example shows a findings query that returns active,
unmuted findings in which the caller_ip
sub-field of the access
object does not contain an IP address in the IPv4 CIDR range of 192.0.2.0/24
:
state="ACTIVE" AND NOT mute="MUTED" AND NOT inIpRange(access.caller_ip, "192.0.2.0/24")
If an IP address is in an attribute that can appear
multiple times in a finding, use the contains
function with
the inIpRange
function to check each instance of the attribute
for the IP address. For example:
contains(connections, inIpRange(source_ip, "192.0.2.0/24"))
For more information about the contains()
function, see The contains
function.
Finding attributes for queries
Security Command Center selects the findings to display by evaluating the attributes of each stored finding against the attribute filters that you specify in the query.
You can query most finding attributes. Some attributes are common to all findings. Other attributes might be specific to a particular security issue, finding category, or detection service.
In the Add filter menu of the Query editor panel, the options that you can apply to an attribute filter are different depending on the type of attribute you select and whether the attribute has sub-fields or an array of values.
In the Add filter menu, click any of the following top-level attributes to display the sub-attributes and values that you can use in a findings query:
- Finding
- Resource
- Access (
access
) - Attack exposure score
- Backup Disaster Recovery
- Compliances (
compliances[]
) - Connections (
connections[]
) - Contacts
- Containers
- Database
- Exfiltration (
exfiltration
) - Files
- IAM binding (
iamBindings[]
) - Indicator
- Kernel rootkit
- Kubernetes
- MITRE ATT&CK (
mitreAttack
) - Processes (
processes[]
) - Security posture
- Sensitive Data Protection
- Vulnerability