Quick Start

Example searches for understanding fundamental VQL concepts and options.

Getting Started with VQL

This guide will help you learn VQL through practical examples, starting with basic queries and progressing to more complex scenarios. Use the examples in this document to familiarize yourself with Veza graph search concepts, and how they can be expressed using Veza Query Language (VQL).

• Every query constructed using the Veza Query Language starts with a SHOW statement specifying the entities that will be returned as results. Entities that match the search conditions are shown in rows with detailed entity metadata.

  SHOW S3Bucket;

• After specifying the source node, you can apply filters (WHERE clauses) and relationship constraints (RELATED TO) to further narrow your search.

  SHOW AwsIamUser
  WHERE is_active = true
  RELATED TO S3Bucket;

• By default, the results show the source entity types indicated by the SHOW keywords. Use the INCLUDE clause to change the result output format to include destination nodes and summary entities.

  SHOW AwsIamUser
  RELATED TO S3Bucket
  RESULT INCLUDE DESTINATION NODES;

For the detailed VQL specification, see VQL Syntax.

Query for Entities

The examples below describe some search scenarios for AWS, which you should adapt based on your actual environment. To retrieve an entity's type and attributes, locate the entity in Graph search and click on it to view details. Note that VQL is case-sensitive for node types, attribute names, and string values unless specified otherwise.

A VQL query consists of at least one source specification, which determines the entity type(s) to return as results.

Here is a simple VQL expression that will return all AWS S3 Buckets that Veza has discovered:

SHOW S3Bucket;

By default, the results contain a selection of entity properties and not the full set of attributes. Modify the SHOW statement to retrieve specific properties you're interested in:

SHOW S3Bucket { created_at, block_public_access_enabled };

For each result, columns will include the S3 Bucket creation date and indicate if the Block Public Access option is enabled.

Query for Relationships

VQL allows you to query relationships between interconnected graph entities using a simple syntax. In this example, we return all AWS IAM Users RELATED TO S3 Buckets:

SHOW AwsIamUser
RELATED TO S3Bucket;

Conversely, to list S3 Buckets accessible by IAM Users:

SHOW S3Bucket
RELATED TO AwsIamUser;

Applying Attribute Filters

To only return results that meet certain conditions, include a WHERE clause. In this example, results are constrained to AWS IAM Users related to S3 Buckets that have public ACLs OR have Object Lock Enabled set to true:

SHOW AwsIamUser
RELATED TO S3Bucket
WHERE block_public_acls != true OR object_lock_enabled = true;

Using Path Requirements

Relationships in the Veza graph can include intermediate entities, such as roles, groups, or policies connecting a source to a destination.

In the example below, use the WITH PATH option to only return AWS IAM Users that are connected to S3 Buckets via an intermediate IAM Role:

SHOW AwsIamUser
RELATED TO S3Bucket
WITH PATH AwsIamRole;

Alternately, to exclude paths that include a specific node type:

SHOW AwsIamUser
RELATED TO S3Bucket
NOT WITH PATH AwsIamGroup;

Including Destination Entities

By default, query results are a list of source entities and their attributes. You can optionally get results as source and destination pairs, where each row represents a unique path connecting two entities.

Update the previous example to return the exact S3 Buckets each IAM User can access by adding the RESULT INCLUDE DESTINATION NODES keyword. This will show each combination of IAM Users and S3 Buckets connected by IAM Roles:

SHOW AwsIamUser
RELATED TO S3Bucket
WITH PATH AwsIamRole
RESULT INCLUDE DESTINATION NODES;

This output format is equivalent to the Show Destination Entities option in Query Builder or the format of an Access Review.

Including Summary Entities

VQL supports summary entities to provide insight into the intermediate entities in the path connecting a source and destination. This option can help identify deeply nested groups, inherited roles, and other hierarchical relationships.

Use the following query to include the summary and the sequence of IAM Roles granting access to S3 Buckets in the search results:

SHOW AwsIamUser
RELATED TO S3Bucket
WITH PATH AwsIamRole
RESULT INCLUDE PATH SUMMARY;

Including path summary will automatically include all destination nodes. You don’t need to explicitly use the keyword INCLUDE DESTINATION NODES.

Filtering by Related Entity Count

With VQL, you can filter results based on the number of destination entities a source is related to. This option can help identify widely-accessible resources, users with overly broad permissions or roles or groups that grant access to a wide range of other entities.

Update the example above with a HAVING clause to only return AWS IAM Users who have access to more than 10 S3 Buckets:

SHOW AwsIamUser
RELATED TO S3Bucket
HAVING entity_result_count > 10;

This variation returns users who have access to more than 20% of S3 Buckets:

SHOW AwsIamUser
RELATED TO S3Bucket
HAVING percentage_of_total_count > 20;

Using Over-Provisioned Score

While querying for relationships, add a QUERY OPTION to filter results by Over-Provisioned Score (available for supported integrations):

SHOW AwsIamRole
RELATED TO S3Bucket
WITH QUERY OPTIONS (over_provisioned_score < 85);

Using Pagination

When working with large result sets, use pagination to retrieve results in manageable chunks:

SHOW AwsIamUser
RELATED TO S3Bucket
LIMIT 50;

After receiving the initial results, use the cursor token provided in the response to fetch the next set of results:

SHOW AwsIamUser
RELATED TO S3Bucket
AFTER CURSOR 'elcl9uYW1lIjoicjJkMiJ9fQ=='
LIMIT 50;

Learning More

Experimenting with different node types, filters, and relationship constraints can help identify the best queries for your unique environment and security needs. For the full range of where clause operators and all query options, see VQL Syntax