Workspace and Queries

The Return section of the Query Builder lists what is returned by your query. By default, entire asset objects, such as an Asset, User, or Vulnerability, are returned. When entire assets objects are returned, you can inspect all of the contained properties by clicking an asset in the results.

However, sometimes you have a very specific intention and are only interested in specific properties. Rather than returning the entire object and having to drill into them or adjust the columns of the results table to show specific properties, you can simply return individual properties explicitly. When you do this the returned properties are displayed as columns in the results table.

You can return any combination of specific properties and entire objects which is helpful when you want to focus on specific properties but still want to be able to drill into the corresponding asset objects to examine all properties and relationships.

To change what is returned by a query:

1. Click the query name to open the Query Builder interface.
2. Click Edit return properties or Edit for an item in the Return section.
3. Select or de-select any asset types using the checkboxes.
4. Expand the Add properties drop-down menu and select or de-select any checkboxes.
5. Optionally, provide an alias for each property you added.
6. Click Apply.
7. Click Execute query.

If you've added multiple asset types to the Query Builder using relationships, you can also add the type or property to the Return list using the Menu next to the desired type or property.

You can control the ordering of returned query results using the Sort control within the Return section of the query builder. Alternatively, you can click the Set sort order button if an order is not yet specified and provide an order using the asset type and property drop-down menus.

Cybersecurity posture is a matter of how various entities relate to each other across your cyber estate. For example, which compute devices (Assets) are subject to which vulnerabilities or other exposures and how do those devices relate to your critical business services or network topology. Surface Command models all of these relationships in a graph. This helps organizations understand the state of their posture and be able to assess where their most significant risk exists.

An asset can have several relationships to another asset type through different properties. For example, an Asset might have several relationships to a User asset, such as Business Owners and Technical Owners. You can have the query match on any relationship or you can limit it to a specific relationship between two asset types.

You can leverage relationships in a query to look for undesirable conditions such as Machines which have relationships to Vulnerabilities with certain characteristics or to users without MFA enabled.

To add a relationship to a query:

1. Click Add relationship on the asset type.
2. Select an asset type from the Relationship to dropdown menu. The Query Builder displays all possible asset types to which the current asset might have a relationship based on the unified model.
3. Optionally, select a path for the relationship. By default, the first and most direct path is selected.
4. Optionally, specify the relationship of interest and condition.
   1. In the first field, select any or a supported property name. The property name specifies the type of relationship.
      1. Choose any to get matches for any relationship between the asset types, regardless of the type of relationship. For example, the any setting would match any relationship between a Machine and User, regardless of whether the relationship is business owner, technical owner, or last logged in user, etc.
      2. Choose a relationship property to specify the specific relationship you’re interested in. For example, where there is a relationship between Asset and User, you can select Business Owner to match only where the User asset is related through the Business Owner property/relationship.
   2. In the second field, select the relationship condition. Choose exists (default) to match only when the specified relationship is present. Choose optional to not require that a relationship exists but to be able to reference the related asset when it does exist.
5. Click Apply to add the relationship constraint to the query.
6. Repeat these steps as necessary to add more relationships to the query.
7. Click Execute query.

You can also adjust the relationship and condition or remove the relationship at any time from the Query Builder.

You can limit your results to specific properties and values. For example, you might want to see all Assets with a Windows operating system.

To add a filter:

1. Next to any asset or property in the Query Builder, click the Filter result. The Filter asset type window opens.
2. Select whether you want filter on properties of the Unified model or on properties from a specific Connector that has been correlated with the asset.
3. Select the property you want to filter on.
4. Select the condition and if required, a value. For example, an is equal to condition requires a value while an is true condition does not. Only assets that meet the specified conditions will match the query.
5. Optionally, click + to add additional filters.

If you have multiple filters, you can also decide on the logic for the filters:

• All (default) - matches assets that meet every filter (an AND)
• Any - matches assets that meet any one of the filters (an OR).
• Advanced - allows you to construct arbitrary Boolean logic across any number of filter conditions.

To construct Advanced filter expressions, start by clicking on the Advanced tab of the filter dialog, which shows the Advanced condition field. Provide your filter expression using the numbers that correspond to the added filters, parentheses, and Boolean operators (AND, OR, and NOT). The field will inform you if your expression is invalid for some reason.

Filters can be edited at any time by clicking the Filter result next to the respective asset type.

When you query in Surface Command, the system search for a graph pattern not individual graph nodes. For example, if you query for all Asset and Vulnerabilities relationships, the results contain all unique combinations of Asset-to-Vulnerability relationships. This means if there was only 1 Asset but it had relationships to 10 vulnerabilities, the results would contain 10 rows. If your query only returned Assets, all 10 rows would be identical. If your query returned Assets and Vulnerabilities, each row would contain the same Asset but a different Vulnerability, which can create confusion. Because of this, you may want to ensure distinct results.

To remove duplicate results from a query:

1. In the Query Builder, toggle on Distinct.
2. Click Execute query.

You can save a query to reuse it or allow other users to use it.

To save a query:

1. In the Query Builder, click Execute query.
2. In the results table, click Save query.
3. Provide a name and description for the query.
4. Optionally, add tags.
5. Optionally, toggle on Create widgets. This allows the query to be used for Widgets. You can always turn this off or on later.
6. Click Save.

A simple example when looking for Assets running Windows would look like this:

sql
1
MATCH (m:Machine)
2
WHERE m.os_family ICONTAINS 'Windows'
3
RETURN m

You can also incorporate relationships between assets. For example, a query for Assets running Windows with Vulnerabilities exceeding a CVSS score of 7.0 would look like this:

sql
1
MATCH (m:Machine)--(v:Vulnerability) 
2
WHERE m.os_family ICONTAINS 'Windows' AND v.cvss > 7 
3
RETURN m

When want to know the technical name of a property so you can add it to your Cypher query’s WHERE or RETURN clause, you can find it in a couple ways:

• If it’s a column being displayed in the query results table, you can hover on the column header and click Copy.
• If it’s not being displayed as a column in the results table, you can either add it as a column or access it from the associated object’s details page.

To find the technical name of a property from the details view of the associated object:

1. Click a row in the query results table to display the asset properties panel.
2. Next to a property's name, hover on the Information to display details about the property.
3. Click Copy next to the technical property name.

Auto-complete relationships:

As you start to type out a query, the editor uses its understanding of asset types and the relationship model to offer auto-complete options. For example, if you start your query by typing MATCH (m:Machine)—(vuln the editor knows that the Machine type has a relationship to the Vulnerability type and offers an auto-complete option. Click the relationship you want and then keep typing. The editor provides auto-complete options for property names and when specifying a WHERE clause filter or RETURN value.

Case sensitivity:

Some things in Cypher are case sensitive, including asset types, relationship labels, and property names. Cypher keywords and functions, like MATCH and COUNT() are case insensitive but it improves readability to provide them in uppercase.

Comments:

Adding comments helps document the intent of the query and lessens maintenance. You can add comments on a single line using //. Multi-line or inline comments start with /* and end with */.

New lines:

When using the Advanced Query editor, use Shift + Enter to add a new line without submitting the query. Adding new lines improves readability.

Quoting strings containing spaces:

Use single or double quotes for strings containing spaces. In this example, the operating_system value is a string. However, the encrypted property is a Boolean, which does not require quotes:

sql
1
MATCH (m:Machine)--(s:Storage) 
2
WHERE m.operating_system = 'Ubuntu Linux 18.04' 
3
AND NOT s.encrypted = true 
4
RETURN m

Previous queries:

When starting a new Cypher query, use the up and down arrow keys to step through recent Cypher queries.

You can edit the following things for a saved query:

• The query itself using the Query Builder or the Advanced Query editor
• Saved query details, for example, its name and description
• Actions (Workflows) associated with the query
  • You can only add Workflows that already exist. You can also schedule the workflow to run at a specified frequency.
• Widgets
  • You can toggle on or off the ability to use the query for widgets as well as create widgets. Visit Dashboards and Widgets for details.