Workspace and Queries

The Workspace is used for building queries, which can then be used to create widgets and dashboards and power insights into your Attack Surface. You can build a query for ad-hoc exploration, reuse, generating widgets for dashboards, or even scheduling automated actions. Queries can also interact with Reference Lists.

Building queries

Queries can be built using the Query Builder or Advanced query (Cypher). You can add queries to your Workspace indefinitely and they will never be deleted until you remove the query or clear your Workspace. However, if you don’t use the Workspace page for a while, you may need to re-execute your queries when you open the Workspace again.

Using Query Builder

Query Builder allows you to build queries with a graphical interface without having to learn the querying language used for interfacing with Attack Surface Management (Surface Command). When you add a query to the Workspace, the Query Builder is selected by default. Query Builder queries are composed of a selectable asset types (derived from the unified model) and a search pattern, which can consist of property filters and relationships to other asset types.

⚠️

Understand the unified asset model first

Before you build a query, you should understand the unified model and the difference between unified asset types and the asset types from information sources. Visit Explore unified properties for details.

To use the Query Builder (basic query example):

Log in to the Command Platform.
Navigate Attack Surface Management (Surface Command) > Workspace. Any recently-used queries are displayed.
Click + Query. The Query Builder opens within the Workspace page.
Optionally, to see all asset types (including source-specific types), toggle on Show all types. By default, only the unified asset types are available to be selected.
Select an asset type you’re interested in querying for. You can scroll through the asset types listed in the Query Builder or use the search field to find a specific type.
Click Execute query. All assets of the selected type are returned.

By default, the entirety of asset objects are returned, including all of their properties. You can determine which properties are displayed in the results table by clicking Manage table columns. You can continue to build your query by specifying which properties to return, adding relationships to other asset types, filtering on property values, and saving the query as described in the following sections. For more information on exploring and interacting with the Asset table, explore Assets.

Add or edit query results

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.

ℹ️

Returning specific properties?

If you are only returning specific properties, you won’t be able see all of the other properties and relationships and you won’t be able to generate a graph.

To change what is returned by a query:

Click the query name to open the Query Builder interface.
Click Edit return properties or Edit for an item in the Return section.
Select or de-select any asset types using the checkboxes.
Expand the Add properties drop-down menu and select or de-select any checkboxes.
Optionally, provide an alias for each property you added.
Click Apply.
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.

Order query results

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.

Add relationships to a query

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. Attack Surface Management (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:

Click Add relationship on the asset type.
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.
Optionally, select a path for the relationship. By default, the first and most direct path is selected.
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.
Click Apply to add the relationship constraint to the query.
Repeat these steps as necessary to add more relationships to the query.
Click Execute query.

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

Filter query results

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:

Next to any asset or property in the Query Builder, click the Filter result. The Filter asset type window opens.
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.
Select the property you want to filter on.
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.
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.

Remove duplicate results

When you query in Attack Surface Management (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:

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

Save a query

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

To save a query:

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

Using Cypher (Advanced Query)

Advanced query allows you to manually compose complex queries with the standards-based openCypher query language (also referred to as Cypher). To learn more about using Cypher, review Query your attack surface with Cypher (Advanced query) for more information.

Working with saved queries

Any queries that have been saved are viewable from Saved Queries in the Attack Surface Management (Surface Command) navigation menu. From this page, you can edit the query, execute the query with or without actions (Workflows), copy the query, or delete the query.

Edit a saved query

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.

Working with reference lists

A reference list is data loaded from a Microsoft Excel (.xlsx) or .csv file instead of a Connector and used as lookup data in queries. To view all reference lists, click Reference Lists in the Attack Surface Management (Surface Command) navigation menu. From this page, you can:

Upload a new reference list
View the contents of a reference list
Edit the reference list configuration (tags and a description)
Upload new data to an existing reference list
Delete a reference list

To upload a reference list:

Click + List.
Provide a name and type. The type is used in queries and cannot be changed once the reference list is created.
Optionally, provide a description and tags.
Optionally, toggle off Use first row as column header.
Provide the field separator for the list.
Upload the file.
Click Submit.

Querying unified properties

When querying unified types, you typically filter on unified properties rather than source-specific fields. By default, filters and Cypher queries compare against the best fulfilling value for a unified property.

However, some property types behave differently to make it easier to discover underlying source data.

String and array properties

For string and array properties, comparisons are performed across all fulfilling values by default. A match evaluates to true if any source value matches.

This behavior helps surface data that might not be visible from the best value alone.

Example:

A user appears in two sources with different name values:

Christopher
Chris

If the best value is Chris, a filter on user.name that matches either Christopher or Chris will still return the record. In tables, the name will display as Chris, but you can access all values using functions such as every(user.name).

Advanced property filtering behavior

Force filtering on the best value

To compare only against the best fulfilling value of a string property, use the top() function:


MATCH (a:Asset)
WHERE top(a.name) = "some_name"
RETURN a

For single-value property types—such as enumerations, booleans, numeric values, and dates—the best value is always used for filtering and sorting.

Boolean properties and null values

If a boolean property is never fulfilled by any source, it is treated as FALSE in filters.

For example, if no source sets machine.active, then:

NOT machine.active will match the asset

To explicitly check for missing or false values, use:

machine.active IS NULL
machine.active = FALSE

Matching across all fulfilling values

To explicitly match against all fulfilling values of a property, use the every() function:


MATCH (a:Asset)
WHERE TRUE IN every(a.active)
RETURN a