Overview

Veza Query Language (VQL) is a powerful and flexible language designed for querying Veza's Identity Graph. It supplements the original Query Builder interface and Assessment Query API, and implements familiar SQL-like conventions for specifying source and destination entities, filters, and other query parameters.

VQL expressions aim to be intuitive and close to natural language, providing a bridge between everyday speech and the full functionality of Veza graph search. With VQL, you can construct complex queries to explore relationships, filter entities based on attributes, and analyze permissions within your identity and access data.

You can use VQL to:

• Apply filters using a range of operators to refine your search results.

• Query relationships between entities, including intermediate node requirements.

• Customize how results appear by including destination nodes and path summaries.

VQL queries follow consistent patterns for different types of operations:

Getting Started

To begin using VQL, first familiarize yourself with its basic syntax and components. A VQL query starts with a SHOW statement specifying the source entities.

Example:

This query retrieves all AWS S3 Buckets discovered by Veza.

You can then extend your queries by adding filters, relationships, and other options.

Example with Filters and Relationships:

This query retrieves all active AWS IAM Users and shows the S3 Buckets they are related to.

To learn more about how Veza search concepts can be expressed with VQL, see the examples queries below and the .

Concepts and Syntax

VQL queries are composed of several key elements:

• Target node types: The entities you want to retrieve (e.g., AwsIamUser, OktaUser).

• Filters: Conditions applied to source or destination nodes in the WHERE clause.

Basic query structure:

VQL supports a variety of operators for filters, including:

• Comparison Operators: =, !=, <, >, <=, >=

• String Operators: STARTS_WITH,

For details on operators and their usage, see .

Example Queries

Query All S3 Buckets

Retrieve all AWS S3 Buckets:

Query IAM Users Related to S3 Buckets

List all AWS IAM Users who have access to S3 Buckets:

Apply Attribute Filters

List active AWS IAM Users in the Engineering department:

Include Destination Nodes

Show AWS IAM Users and the S3 Buckets they can access:

Use Path Requirements

Find AWS IAM Users connected to S3 Buckets via an IAM Role:

Exclude Specific Paths

Find AWS IAM Users related to S3 Buckets but not through an IAM Group:

Filter by Over-Provisioned Score

Retrieve AWS IAM Roles with an over-provisioned score greater than 85:

Enrich Results with Related Entity Data

Show Okta Users related to AWS IAM Roles, enriched with Workday employee data:

Enrich with multiple types at once:

Filter by Related Entity Count

Find AWS IAM Users who have access to more than 10 S3 Buckets:

Query Using Time Functions

Retrieve users who have logged in within the last 30 days:

Executing VQL Queries

There are two ways to execute VQL queries:

1. VQL API: Execute VQL queries programmatically through Veza's Assessment Query API endpoints

2. VQL Playground: Coming soon - a GUI experience for constructing and executing queries

Using the VQL API

Veza two /v1 API endpoints for executing VQL queries:

• Get Results (Nodes) - /api/v1/assessments/vql:nodes: Returns detailed results including source nodes, their properties, and access relationship information

• Get Results (Count) - /api/v1/assessments/vql:result: Returns result counts, ideal for metrics and reporting use cases

For detailed API documentation, authentication requirements, and example usage, refer to the .

Example API request:

The response supports pagination, and returns a JSON object with the query results, for example:

Resources

To learn more about VQL capabilities, see the following resources:

• : Learn how to construct basic queries with examples

• : Guide to VQL syntax, operators, and advanced features

• : API documentation for executing VQL queries programmatically

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.

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

• 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.

For the detailed VQL specification, see .

Query for Entities

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:

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:

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:

Conversely, to list S3 Buckets accessible by IAM Users:

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:

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:

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

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:

This output format is equivalent to the option in Query Builder or the format of an .

Including Summary Entities

VQL supports 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:

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:

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

Using Over-Provisioned Score

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

Using Pagination

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

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

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

Overview

You can programmatically execute Veza Query Language (VQL) queries through Veza's Assessment Query API. This interface allows you to run VQL queries against Veza's Access Graph and retrieve results using standard REST API calls.

VQL vs. Traditional Approaches

VQL offers a simplified way to interact with Veza's Assessment Query APIs, enabling:

• Automated compliance monitoring

• Cross-platform integration

• Custom investigation and reporting tools built on top of the Veza graph

While Veza's traditional JSON-based interfaces provide robust programmatic functionality, they are developer-focused and require detailed specification of all query components. VQL, with its SQL-like syntax, is more accessible to security practitioners who may already be familiar with similar query languages.

Example Comparison

Here's how the same query appears in both formats:

Traditional JSON Format:

Equivalent VQL:

VQL's concise syntax makes queries easier to write, review, and troubleshoot while maintaining the power of Veza's assessment capabilities.

Requirements

To use the VQL API, you will need:

• A valid API token. For details on obtaining and using API tokens, see .

• Basic understanding of VQL syntax (see )

• VQL features enabled in your Veza instance

API Endpoints

The VQL API provides two primary endpoints for retrieving query results: and .

Get Query Results (Count)

This endpoint retrieves result counts for a VQL query. These queries can execute faster and are optimal for metrics, reporting, and dashboard use cases where you need the total count rather than detailed node information.

Get Query Results (Nodes)

The vql:nodes endpoint retrieves detailed results for VQL queries, showing source nodes, their properties, and access relationship information. This format is useful for security analysis, access reviews, and permission auditing.

Example Request

This example asks: "Show me all active Okta users who have access to AWS S3 buckets, include details about those buckets, and limit results to 50 entries."

Understanding the API Response

When you send a VQL query, Veza returns a structured JSON response with results based on the latest graph data. The response contains:

• Path Values: Each entry represents a connection between a source and destination node

• Source: Details about the source node, including properties and risk level

• Permissions: Both high-level ("abstract") permissions and specific ("concrete") permissions

Example Response

Pagination

For queries that return large result sets, use pagination to retrieve results in manageable chunks using the LIMIT and AFTER CURSOR keywords in your VQL query:

1. Make an initial request with a specified limit (e.g., LIMIT 50)

2. Check if has_more is true in the response

3. If more results exist, make subsequent requests using the cursor token from the previous response with AFTER CURSOR 'token'

Example initial request:

For subsequent requests, use the cursor token from the previous response:

Related Documentation

• - Complete documentation of VQL query syntax

• - Examples and usage patterns

• - General information about the Assessment Query API

This document provides information about the VQL (Veza Query Language) query specification, which offers a SQL-like interface to the Assessment Query API. See the Quick Start Guide for detailed usage and examples.

• Concepts

• VQL Expression Syntax

Concepts

Early Access: VQL is subject to modifications as we add and improve functionality. Future updates will aim to preserve compatibility with earlier versions.

A VQL query is composed of the following components:

• Source Nodes: Node types in VQL represent entity types within Veza's Identity Graph. Each node type can have many individual instances, returned as rows in the query output.

• Path requirements: Graph nodes can be interrelated, forming complex graph structures. Specifying related nodes filters results with a matching relationship.

• Filters and Modifiers: Filter expressions (WHERE clauses) to constrain results based on attributes or other criteria.

VQL Expression Syntax

A VQL query always includes a SHOW statement describing the source node type. The general syntax is:

NodeSpec Syntax

A NodeSpec describes a source or destination entity type. It can include attribute selection (which columns to return) and filters using a WHERE clause. The full syntax is:

Basic Components:

• NodeType: The type of node (e.g., AwsIamUser, OktaGroup)

• Attribute Selection: Optional curly braces { } containing a comma-separated list of attributes to include in the results

Usage Examples

Basic node specification (returns all attributes):

Select specific attributes to display:

Apply filters without attribute selection:

Combine attribute selection and filters:

In this more complex example, we select specific attributes for both the source (OktaUser) and destination (S3Bucket) nodes while also applying filters to the results:

Where Clause Operators

A range of operators can be used to filter results depending on node properties. Currently, VQL supports the comparison operators:

Comparison Operators

Data Types and Restrictions

• Data Types: VQL supports boolean, integer, string, and null data types.

• Case Sensitivity: VQL is typically case-sensitive for:

  • Node Types: Must be written exactly as defined (e.g., AwsIamUser, not awsiamuser

Entity Attributes

Entity attributes in VQL are used to filter and select graph nodes. They consist solely of alphanumeric characters or underscores (e.g., last_login, email_address).

Permissions

In addition to attribute filters, VQL queries can use permission filters. Both system permissions and effective permissions are supported.

System Permissions

System permissions are raw, system-level permissions and vary depending on the specific integration and resource. The following query identifies users that specifically have the ability to create new S3 buckets:

• ANY: Used to filter for any of the supplied permissions (logical OR).

• ALL: Ensures that all permissions passed should be present on the resource (logical AND).

Effective Permissions

Veza supports nine different effective permissions. These are abstracted permissions that express system permissions in common groups:

• METADATA_READ

• METADATA_WRITE

• METADATA_CREATE

The following query shows all AWS IAM Roles that grant effective permissions to read or write S3 bucket metadata:

Effective permissions filters require a destination type (specified by the RELATED TO clause).

Intermediate Nodes

Intermediate node options include or exclude results based on certain node types within the path, for analyzing complex relationships that involve hierarchies of groups, roles, or entities. These queries are often used to find users whose access is (or is not) granted by group membership or role assignment:

• Including Intermediate Nodes:

• Excluding Intermediate Nodes:

Modifiers and Filters

Use the WHERE clause to apply filters. You can combine multiple conditions with AND or OR statements:

Example:

Pagination

VQL supports pagination for queries that return large result sets. Two keywords control pagination behavior:

• LIMIT: Restricts the number of results returned in a single query

• AFTER CURSOR: Used with a cursor token to retrieve the next set of results

Example of initial query with limit:

For subsequent requests, use the cursor token from the previous response:

Enrichment Clauses

Enrichment clauses join additional node types to query results, augmenting source or destination nodes with related entity data from adjacent integrations. For example, you can enrich IAM role results with employee records from Workday, or annotate destination resources with metadata from another system.

Multiple enrichment clauses can appear in a single query. To enrich with more than one node type, provide a comma-separated list in parentheses.

Enrich source nodes with a single type:

Enrich source nodes with multiple types:

Enrich source and destination nodes separately:

Combine enrichment with query options and pagination:

Result Output

By default, queries return a list of source entity types and attributes. Use the RESULT INCLUDE clause to specify how query results appear:

• DESTINATION NODES: Includes information about related destination nodes.

• DESTINATION NODE COUNT: Provides a count of related destination nodes.

• PATH SUMMARY: Summarizes the paths between source and destination nodes.

Example: