This page describes how to create and edit Security Command Center findingsqueries by using theQuery editor panel on theFindings page.

Use queries to retrieve specific findings and filter the findings thatare displayed in the findings query results.

Edit findings queries

In theQuery editor panel, you can add filters to your queriesto select findings based on their property or attribute values. You canfilter for things like the presence of values, the absence of values, orthe matching of a partial string.

1. In the Google Cloud console, go to theFindings page of Security Command Center.

   Go to Findings

2. Select your Google Cloud project or organization. TheFindingspage loads with the default query displayed in theQuery preview field.
3. At the right of theQuery preview section, clickeditEdit Query toopen theQuery editor panel.
4. SelectAdd filter to navigate, search for, and add predefined attributefilters to the query.

   TheSelect filter dialog lets you choose supported findingattributes and values.

   1. Select a finding attribute or type its name in theSearch finding attributes box. A list of the available sub-attributes displays.
   2. 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.
   3. 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, seeQuery operators in the Add filters menu.
   4. ClickApply.

      The dialog closes and your query is updated.

   5. Repeat until the findings query contains all the attributes youwant.

When you're working in the query editor on theFindings page, theQuick filters section is deactivated to avoid conflicts between the two.

Alternatively, you can manually form a findings query the same way youform a findings filter using the Security Command Center API.As you type in your query, an autocomplete menu appears, where you can selectfilter names, functions, and values. To manually open the autocomplete menu,pressControl+Space.

• For arrays:
  • contains(), a function forquerying findings with an array field that contains at least one elementthat matches the specified filter
  • containsOnly(), afunction for querying findings with an array field that only containselements that match the specified filter
• For IP addresses:
  • inIpRange(), a functionfor querying IP addresses within a specified CIDR range

Query operators in the Add filters menu

In thefilter_altAdd filter menu of theQuery editor,query operators and functions arerepresented 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 attributevalue.
• After: matches findings with a creation or update time after a specifiedtime.
• Before: matches findings with a creation or update time before aspecified time.
• Greater than: matches findings with attribute values that are higherthan your specified value.
• Less than: matches findings with attribute values that are lower thanyour specified value.
• Has: matches findings with attribute values that contain the text youenter in theKeyword field.
• Does not have: matches findings with attribute values that don't containthe text you enter in theKeyword field.
• For finding attributes that contain arrays:
  • Contains any: matches findings that have an array value thatcontains any of the text that you enter in theKeyword field.
  • Contains all: matches findings that have an array value thatcontains all of the text that you enter in theKeyword field.
  • Contains none: matches findings that don't have an array value thatcontains the text you enter in theKeyword field.
  • Contains only: matches findings that have an array attribute thatcontains only the value that you enter in theKeyword field, and noother values.
• For IP addresses:
  • Any within IP range: matches findings that have an IP address in aspecified CIDR range.
  • Does not have any within IP range: matches findings that have an IPaddress that is not in a specified CIDR range.

Query functions

A query function provides more complex evaluations of attribute valuesthan the common query operators.

Thecontains function

Use thecontains function to evaluate attributes or attribute subfieldsthat can appear multiple times in the same finding.

Internally, these attributes or attribute subfields are stored in theelements of an array data structure, so they arereferred to asarray-type attributes.

For example, certain findings can reference multiple networkconnections, so theconnections attribute is an array-type attribute.Similarly, certain threat findings can reference multipleIP addresses as indicators of a compromise, so theip_addressessubfield of theindicator attribute is an array-type attribute.

Thecontains function uses the following syntax:

contains(ARRAY_ATTRIBUTE_NAME,SUBFILTER)

Replace the following:

• ARRAY_ATTRIBUTE_NAME: the name of the array-typeattribute that is stored in an array. If the array-type attribute is asubfield of another attribute, specify the attribute name and the subfieldname separated by a dot.

  In the following example, the array-type attribute,ip_addresses, isa subfield ofindicator, so both are specified in theARRAY_ATTRIBUTE_NAME position:

  contains(indicator.ip_addresses, elem="192.0.2.80")

• SUBFILTER: an expression thatdefines how to evaluate each instance of the array-type attribute.Standard Security Command Centerquery operators and evaluation statementsare 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 followingcontains 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, whichis not an array-type field. The values to query for are specified withthe 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 attributeon the left of the expression with its parent and use theelem parameter onthe 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")

Thecontains function in the Add filter menu

In theAdd filter menu, depending on the finding attribute thatyou are evaluating, thecontains function is listed explicitlyor it gets included automatically when you select another filter optionthat requires it.

For example, for theIP addresses sub-field of theIndicator attribute,you can select the following filter options:

• Contains any
• Contains all
• Contains none

In contrast, if you are filtering on theDestination IP sub-field oftheConnections attribute and selectAny within IP range, thecontains functions get added to the query statement automatically,as shown in the following example:

contains(connections, inIpRange(destination_ip, "2001:db8::/32"))

For more information about thecontains function, seeFiltering on array-type fields.

ThecontainsOnly function

ThecontainsOnly function lets you query findings for array-type attributes orsubfields that contain only the values that are specified in the subfilter, andno others.

ThecontainsOnly function uses the following syntax:

containsOnly(ARRAY_ATTRIBUTE_NAME,SUBFILTER)

Replace the following:

• ARRAY_ATTRIBUTE_NAME: the name of the array-typeattribute. If the array-type attribute is a subfield of another attribute,specify the attribute name and the subfield name separated by a dot. When youare running queries using the Google Cloud console, this function onlysupports theiam_bindings.member and theiam_bindings.role arrayattributes.

• SUBFILTER: an expression that defines how to evaluateeach element of the array-type attribute. Standard Security Command Center queryoperators and evaluation statements are supported.

In theAdd filter menu, the following filter options use thecontainsOnlyfunction:

• IAM binding > Member: selects only findings that include the specifiedusers, service accounts, or groups.

• IAM binding > Role: selects only findings that include the specifiedroles.

The following example shows a findings query in the Google Cloud consolethat returns active, unmuted findings for users in theexample-group group:

state="ACTIVE"  AND NOT mute="MUTED"AND containsOnly(iam_bindings,member="group:example-group@example.com")

TheinIpRange function

TheinIpRange function checks whether the IP address in a selectedfinding attribute is within a range of IP addresses thatyou specify by using CIDR notation (a CIDR range). The following showsthe syntax of theinIpRange function:

inIpRange(ATTRIBUTE_WITH_IP, "CIDR_RANGE")

In theAdd filter menu, the following filteroptions use theinIpRange function:

• Any within IP range: selects only findings that contain IP addresseswithin the specified range.
• Does not have any within IP range: selects only findings that don'tcontain IP addresses within the specified range.

The following example shows a findings query in the Google Cloud consolethat returns active, unmuted findings in which thecaller_ip sub-fieldof theaccess object contains an IPv6 address in the CIDR range of2001: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 thecaller_ip sub-field of theaccessobject does not contain an IP address in the IPv4 CIDR range of192.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 appearmultiple times in a finding, use thecontains function withtheinIpRange function to check each instance of the attributefor the IP address. For example:

contains(connections, inIpRange(source_ip, "192.0.2.0/24"))

For more information about thecontains() function, seeThecontains function.

Finding attributes for queries

Security Command Center selects the findings to display by evaluatingthe attributes of each stored finding againstthe attribute filters that you specify in the query.

You can query most finding attributes. Some attributes are common toall findings. Other attributes might be specific to a particular securityissue, finding category, or detection service.

In theAdd filter menu of theQuery editor panel, theoptions that you can apply to an attribute filter are different dependingon the type of attribute you select and whether the attribute hassub-fields or an array of values.

In theAdd filter menu, click any of the following top-levelattributes to display the sub-attributes and values that you can use ina findings query:

• Finding
• Resource
• Access (access)
• Attack exposure score
• Backup Disaster Recovery
• Compliances (compliances[])
• Connections (connections[])
• Contacts
• Containers
• Database
• Data Access Events
• Data Flow Events
• Data Retention Deletion Events (DataRetentionDeletionEvent)
• Exfiltration (exfiltration)
• Files
• IAM binding (iamBindings[])
• Indicator
• Kernel rootkit
• Kubernetes
• MITRE ATT&CK (mitreAttack)
• Processes (processes[])
• Security posture
• Sensitive Data Protection
• Vulnerability