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.

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.

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

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

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.

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.

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

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

• Destination: Information about the destination node the source can access

Example Response

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:

• - Complete documentation of VQL query syntax

• - Examples and usage patterns

• - General information about the Assessment Query API

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.

  Copy

  SHOW S3Bucket;

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

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.

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:

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:

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:

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 .

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:

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:

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

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:

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

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.

• Search by system permissions and effective permissions for full visibility into access and entitlements.

• Enrich query results with related entity data from adjacent integrations using enrichment clauses.

VQL queries follow consistent patterns for different types of operations:

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 .

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.

• Relationships: Filter results based on connected entities, specified in the RELATED TO clause.

Basic query structure:

VQL supports a variety of operators for filters, including:

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

• String Operators: STARTS_WITH, ENDS_WITH,

For details on operators and their usage, see .

Retrieve all AWS S3 Buckets:

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

List active AWS IAM Users in the Engineering department:

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

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

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

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

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

Enrich with multiple types at once:

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

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

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

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:

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