Veza Query Language

Early Access: VQL is currently provided in Early Access, and we're excited for your feedback on what we hope will be a major stride forward for ease of use and flexibility for Veza search. Please contact our support team to enable the feature, and reach out with your input and questions.

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.

VQL queries follow consistent patterns for different types of operations:

-- Basic entity query
SHOW <entity_type>;

-- Query with filters
SHOW <entity_type>
WHERE <property>[operator]<value>;

-- Relationship query
SHOW <entity_type>
RELATED TO <entity_type>;

-- Complex query with multiple conditions
SHOW <entity_type>
WHERE <condition1> AND <condition2>
RELATED TO <entity_type>
WITH PATH <entity_type>
RESULT INCLUDE DESTINATION NODES;
HAVING entity_result_count > 10;

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:

SHOW S3Bucket;

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:

SHOW AwsIamUser
WHERE is_active = true
RELATED TO S3Bucket
RESULT INCLUDE DESTINATION NODES;

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 Quick Start Guide.

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.

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

• Intermediate Nodes: Include or exclude results with certain nodes in the path (i.e, intermediate groups or roles) using WITH PATH or NOT WITH PATH.

• Result Options: Customize the output to INCLUDE DESTINATION NODES or INCLUDE PATH SUMMARY to get results as source and destination pairs.

• Query Options: Options for query execution, such as filtering by over-provisioned score, and pagination.

Basic query structure:

SHOW [SourceNodeSpec]
[ [NOT] RELATED TO [DestinationNodeSpec]]
[WHERE (filter conditions)]
[WITH | NOT WITH] PATH [IntermediateNodeSpec]
HAVING [ ENTITY_RESULT_COUNT | PERCENTAGE_OF_TOTAL_COUNT] [>|>=<|<=|!=] <numeric_value> ]
[RESULT INCLUDE [DESTINATION NODES | DESTINATION NODE COUNT | PATH SUMMARY]]
[WITH QUERY OPTIONS (options)];

VQL supports a variety of operators for filters, including:

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

• String Operators: STARTS_WITH, ENDS_WITH, CONTAINS, REGEX

• List Operators: IN, LIST_CONTAINS, LIST_ANY_ELEMENT_EQ

• Logical Operators: AND, OR

• Date/Time Operators: created_at < CURRENT_DATE - 30, created_at < 2023-10-05 14:30:00.123

For details on operators and their usage, see VQL Syntax.

Example Queries

Query All S3 Buckets

Retrieve all AWS S3 Buckets:

SHOW S3Bucket;

Query IAM Users Related to S3 Buckets

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

SHOW AwsIamUser
RELATED TO S3Bucket;

Apply Attribute Filters

List active AWS IAM Users in the Engineering department:

SHOW OktaUser
WHERE is_active = true AND department = 'Engineering';

Include Destination Nodes

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

SHOW AwsIamUser
RELATED TO S3Bucket
RESULT INCLUDE DESTINATION NODES;

Use Path Requirements

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

SHOW AwsIamUser
RELATED TO S3Bucket
WITH PATH AwsIamRole;

Exclude Specific Paths

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

SHOW AwsIamUser
RELATED TO S3Bucket
NOT WITH PATH AwsIamRole;

Filter by Over-Provisioned Score

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

SHOW AwsIamRole
RELATED TO S3Bucket
WITH query options (over_provisioned_score > 85);

Filter by Related Entity Count

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

SHOW AwsIamUser
RELATED TO S3Bucket
HAVING entity_result_count > 10;

Query Using Time Functions

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

SHOW OktaUser
WHERE last_login_at >= CURRENT_DATE - 30;

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 VQL API Reference.

Example API request:

POST /api/v1/assessments/vql:nodes
{
  "query": "SHOW OktaUser WHERE is_active = true RELATED TO S3Bucket RESULT INCLUDE DESTINATION NODES LIMIT 50;"
}

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

{
  "values": [],
  "path_values": [
    {
      "source": {
        "id": "00u5pqrs7xyP9uvw30z9",
        "type": "OktaUser",
        "properties": {
          "activated_at": "2023-06-12T15:21:34Z",
          "created_at": "2023-04-20T04:30:37Z",
          "credentials_provider_name": "OKTA",
          "credentials_provider_type": "OKTA",
          "datasource_id": "example.oktapreview.com",
          "email": "[e-mail]",
          "first_name": "John",
          "identity_type": "HUMAN",
          "idp_unique_id": "[e-mail]",
          "is_active": true,
          "last_login_at": "2024-08-02T05:52:42Z",
          "last_name": "Smith",
          "login": "[e-mail]",
          "mfa_active": true,
          "mfa_factors": [
            "question"
          ],
          "name": "[e-mail]",
          "okta_user_type_id": "otyf8xyz92hv7mnP60j9",
          "owners": "[{\"entity_id\":\"00ukmnop51qR3s4TU6e8\",\"entity_type\":\"OktaUser\",\"entity_name\":\"Maria Rodriguez\"}]",
          "password_exists": true,
          "password_last_set": "2024-08-02T05:52:42Z",
          "provider_id": "example.oktapreview.com",
          "recovery_question_exists": true,
          "risk_score": 100,
          "status": "ACTIVE",
          "status_updated_at": "2024-08-02T05:52:42Z",
          "updated_at": "2025-01-16T05:53:38Z"
        },
        "risk_level": "CRITICAL"
      },
      "abstract_permissions": [
        "MetadataRead"
      ],
      "concrete_permissions": [
        "s3:ListBucket"
      ],
      "destination": {
        "id": "arn:aws:s3:::aws-cloudtrail-logs-123456789012-abcdef12",
        "type": "S3Bucket",
        "properties": {
          "allows_acls": false,
          "aws_account_id": "123456789012",
          "aws_account_name": "",
          "block_public_access_enabled": true,
          "block_public_acls": true,
          "block_public_policy": true,
          "created_at": "2024-05-04T04:50:42Z",
          "datasource_id": "123456789012:s3",
          "default_encryption_enabled": true,
          "default_retention_mode": "DISABLED",
          "hosts_website": false,
          "ignore_public_acls": true,
          "name": "aws-cloudtrail-logs-123456789012-abcdef12",
          "object_lock_enabled": false,
          "object_ownership_controls": "BucketOwnerEnforced",
          "provider_id": "123456789012",
          "region": "us-east-1",
          "replication_rules_count": 0,
          "request_payer": "BucketOwner",
          "restrict_public_buckets": true,
          "risk_score": 27,
          "server_access_logs_enabled": false
        },
        "risk_level": "LOW"
      }
    }
  ],
  "next_page_token": "",
  "has_more": false
}

Resources

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

• VQL Quick Start: Learn how to construct basic queries with examples
• VQL Syntax Reference: Guide to VQL syntax, operators, and advanced features
• VQL API Reference: API documentation for executing VQL queries programmatically