Veza ships with hundreds of pre-built security queries, organized by integration, category, and use case. Many of these out-of-the-box queries are featured in Veza's dashboards. You can customize reports and dashboards by cloning existing queries, editing them, or creating new queries.

This flexibility enables tailoring Veza insights to your specific security needs and environment. You can use saved queries to:

Managing saved queries

On the Saved Queries page, use the Actions button to the right of each query to choose from available actions, which include:

• View Alerts: Review alert details for the query.

• Clone: Create a copy of the query.

• Delete: Remove the query.

• Open in Query Builder: Edit the query.

Editing saved queries

Editing saved queries allows you to refine and customize your security assessments as your environment evolves, and ensure that your security insights remain relevant and accurate over time. You might edit a query to:

• Adjust filters to include or exclude specific entities

• Modify the query scope as new integrations are added

• Update risk levels or alert conditions

• Fine-tune the query for better performance or more targeted results

To edit a saved query:

1. Open the Access Intelligence > Saved Queries page and find a query you want to edit or act on.

3. Make any changes and click Save to finish saving the query.

Use the Query Builder Save menu to perform specific actions for the query:

• Quick Save: Quickly save any new filters without changing other settings.

• Save as New: Copy this query to modify it while preserving the original.

• View Details: Show configuration details and metadata for this saved query.

• Edit Configuration: Modify the basic settings of this query, such as name, description, and visibility.

• Edit Rules: Configure or modify alert rules associated with this query.

• Edit Reports: Add this query to reports or remove it from reports it's currently part of.

• Export to CSV: Download the current query results as a comma-separated values (CSV) file.

• Export to Snowflake: Send the query results to a connected Snowflake database.

• Schedule Export: Set up an automated, recurring export of this query's results.

• Copy Query Spec API: Copy the API specification for this query for use with the Veza Query Builder API.

• View Query Spec API: Display the API specification for this query for reference or debugging.

Viewing saved query results

Veza offers different ways to view and analyze saved query results, each suited to different use cases.

We recommend starting with the Query Details view for a quick, accessible overview of your results. From there, you can dive deeper into other views as needed for more detailed analysis.

You can access each view using the Actions menu on the Saved Queries page:

• Query Details: A simplified view of your query results, ideal for:

  • Quick overviews of key findings

  • Reviewing trends and changes over time

  • Accessing associated risks, rules, and reports

• Query Builder: A comprehensive, tabular view of results and query editor. Use this when you need to:

  • Perform detailed analysis of all entity attributes

  • Apply additional filters or modify the query

  • Export granular data for further processing

• Graph: A visual representation of entities and their relationships. This view is best for:

  • Understanding complex access paths

  • Identifying indirect or unexpected connections

  • Exporting a clear picture of your security posture for stakeholders

• Trend Chart: Shows changes in query results over time. Use this to:

  • Track the effectiveness of security measures

  • Identify patterns or anomalies in access behaviors

  • Generate visual reports for compliance and auditing purposes

Assign Risk Levels to Saved Queries

Assigning risk levels to saved queries can help prioritize security efforts and enhance visibility into your organization's risk landscape. By doing so, you:

• Highlight critical security issues that require immediate attention

• Provide context for decision-making during access reviews

• Enable risk-based reporting and tracking of security improvements over time

• Facilitate communication about security priorities across teams and to leadership

• Automate risk-based alerting and response workflows

This risk-based approach allows you to focus resources on the most significant threats to your organization's security posture, making your security operations more efficient and effective.

1. Find the query on the Access Visibility > Saved Queries page.

2. Expand the Actions dropdown menu and click Set Risk Level.

3. Use the dropdown menu to set the risk level to None, Low, Medium, High, or Critical.

4. Click Save.

Defining custom risks using saved queries can help reviewers make decisions during access reviews, track risk burndown, and provide visibility into your most critical identities, access controls, services, and resources.

Assign Rules to Saved Queries

Adding rules to saved queries enables automated monitoring and response to changes in your security posture. By creating rules, you can:

• Get notifications when critical access patterns change

• Automate the creation of access reviews for specific conditions

• Trigger remediation workflows when potential risks are detected

• Maintain continuous compliance with internal policies and external regulations

Rules transform static queries into dynamic security controls, helping you proactively manage access risks.

To assign rules to a saved query:

1. Choose Manage Rules from the actions dropdown menu.

2. 1. Click Add New Rule.

   2. Details: Give the rule a name, description, and severity level for categorizing the rule.

   3. Conditions: Trigger the alert based on changes in the query results, or when results have specific properties (often referred to as attributes).

   4. Action | Send Alert: Create alerts shown on the Access Intelligence > Rules & Alerts page, and optionally them using Veza Actions.

Early Access: System search mode for all providers and Path Summaries are support-enabled features. Contact the Veza customer success team to enable them.

This document provides some example usages of Required and Excluded related entity types, applying Attribute Filters on intermediate entity properties, and System search mode. The techniques and concepts are generally applicable to role-based platforms such as Microsoft Azure and Google Cloud.

Background

Required entities

Queries can filter results based on relationships to other entities, by specifying required or excluded entity types. Adding a "required" or "excluded" entity allows for additional constraints on those entities, such as attribute filters on an intermediate policy or group name. Used in Search and Workflows these filters can help understand and review role-based access controls for a range of cloud platforms and data systems.

Role-based access control

Authorization within Google Cloud has several characteristics that differ from how other providers such as Amazon implement identity and access management (IAM):

• A role-via-binding IAM model separates the two components of permissions and resources, and allows them to be arbitrarily paired.

• Policies granting resource access can be directly applied to resources, OR applied at the organization, project, or folder level, and can apply hierarchically. Permissions can apply directly to a user, or to a group the user is a member of.

• In this model, Veza Effective Permissions calculations for search results represent all user or group, role, and policy combinations that cumulatively result in access to a resource.

Query modes

• To apply attribute filters on properties of related entities, specify them for Required entities. Excluded entity types cannot be Workflow Summary entities, and vice versa.

• Note that in the default Effective search mode, the Authorization Graph Explain Effective Permissions action will show the raw authorization relationships that constitute the effective permission calculation. However, constraints cannot apply to some intermediate entities in effective mode.

Filter users by group membership or role binding

The role assigned to an identity in a Google organization define the actions it can take on resources and settings. To make informed decisions about an individual identity's level of access within an organization, it is important to understand what roles govern their assigned permissions.

Authorization Graph, Query Builder, and Workflows can use System mode to search and filter on intermediate authorization entities. These entities can include types such as Role Bindings and Group Assignments, connecting the source and destination entities.

You can create certifications and rules that audit the owner, manager, or member status of Google Users and resources by adding a filter on the name attribute of system mode "Google Group Membership" required entity. System mode also allows you to exclude or require intermediate entities such as policy bindings.

Search directly-assigned and inherited policies

Policies applied at the Google Organization, Folder(s), and Project levels are hierarchical (in that order), and inherited by resources lower in the hierarchy. Alternately, permissions can result from a policy attached directly to the resource it grants access on.

You can use Veza to identify cases a directly-assigned policy allows permissions on a resource. You can also review access governed by policies inherited from a upper-level resource in the organization’s resource hierarchy:

To review access granted by a policy attached to the resource it applies to, the workflow query must exclude all resource types with hierarchical precedence over the destination resource in the organization. This includes any superior organizations, folders, or projects. For example:

• For access granted by lower-level policy: exclude entity types Google Folder and Google Organization

• For folder permissions inherited from Organization or Folder(s): exclude entity types Google Project

To create a query that returns only results with permissions from directly-applied policies:

• Create a workflow, and enable system mode

• Specify the source and destination (Google User to Google Storage Bucket)

• Expand Advanced Options > Exclude Entity Types

• Add Google Organization, Google Folder, Google Project

• Finish customizing the workflow and save it

When generated, the certification will review only users whose authorization path does not include organization-level, folder-level or project-level permissions.

To query for resource access inherited at the organization, folder or project level:

• Create a workflow, and enable system mode

• Specify the source and destination (Google User to BigQuery Service)

• Expand Advanced Options > Require Entity Types

• Add Google Project

• Finish customizing the workflow and save it

Certifications on this workflow will include only users whose authorization path derives from organization-level, folder-level, or project-level permissions.

Review users with "direct access" (not managed by group)

Human and non-human identities are typically granted access by a group and role representing their department or function. Search and Workflows can be fine-tuned to identify users granted discretionary access to resources, but are not assigned to an appropriate group. For example:

• Search direct User to Role access: exclude Google Group entities to return results with paths that do not contain any groups.

• Search access that is (or is not) managed by a specific group or policy by setting attribute filters on group or policy.

Filter by group membership

Google Users can be owners, managers, or members of their assigned groups. You can customize certifications to only review users granted access by means of a specific intermediate role-based access control entity, such as a contractors group. Adding a filter on the Google Group Membership Membership Type will constrain results by group membership (Owner, Manager, or Direct Member).

To search for all users with a given group membership type:

1. Start a query in system mode

2. Pick Google User for the source entity category to search

3. Pick the resource (such as Google Project or Service) to review access to

4. Pick Require Entity Types > Google Group Membership

5. Add a constraint on the "Membership Type" attribute ("Owner", "Manager", or "Direct Member")

Two methods are useful for finding specific types of members for a particular group. For example, to find all Managers of the "Developers" group:

• Single constraint on Group Membership entity name = "<Group> <Plural of MembershipType>" (Developers Managers)

• Two constraints: Group Membership membership_type = "Manager", Group entity "name" = "<Group>"(Developers)

Early Access: Search Modes: This feature requires support to enable. Contact the Veza support team to enable this option.

Changing the query mode lets you show Effective Permissions from source to destination entities OR information about additional intermediate entity types such as roles and policy bindings.

• Effective mode calculates and shows all possible actions, after accounting for any potential restrictions (such as policy deny statements and other controls). Effective Permissions represent all the metadata and non-data actions the principal can take on a resource.

• System mode shows the configured permissions and access path, before processing potentially overriding policies such as deny statements, service control policies (SCPs), and network policies. system mode is useful for understanding, certifying, and enforcing rules based on User > Policy > Resource relationships and other role-based access controls.

Permissions in system mode

Search and Workflows present a natural-language summary of the actions that identities can ultimately take on a resource, in the form of Effective Permissions (EP). The default Effective mode shows the cumulative level of access a principal has on a resource, after accounting for all roles, groups, and elements such as policy "deny" statements.

In Effective mode, you can click on a single Permission node in Authorization Graph and click Explain Effective Permissions to view the configured system-level authorization relationships that result in the EP calculation. Typically, this will show additional entities such as policies, groups, and roles configured for the principal.

System mode enables visualization and constraints on raw authorization nodes such as role bindings and group memberships, and the exact permissions connecting identities, policies, and resources.

In general, enabling system mode can add additional context to understand and map Role Based Access Controls for Google Cloud Platform and Microsoft Azure AD. System mode is especially useful for searching and filtering on the intermediate entities such as roles and groups connecting identities and resources.

• Role Bindings entities assign specific permissions to a specific user or group in a Google Organization. Graph view consolidates duplicate Role Bindings by Role name, or by Role name and Policy Resource pair.

• Policy Resource nodes represent the specific resource types that a role binding applies to. Graph shows relationships for Role Bindings and the resources in the search, indicating the resource hierarchy and the level of the hierarchy the Role applies.

• The Google Folder hierarchy is a visual representation of the Organization structure.

• "Group" is a term used to describe a collection of users in a Google Organization. The visualization will also show the relationship between a User and a Role Binding, and any intermediate Group entities.

Search interfaces

Each search mode can answer questions such as:

• Graph: "What policies enable Microsoft Azure AD identities to reach sensitive Google Cloud projects?"

• Query Builder: "How many Okta users can view tickets in our service desk application?"

Graph search is ideal for checking the blast radius of a risk, inspecting all the resources an identity can access, and exploring connections between different entity types.

For example, you could create a query to warn whenever the number of users with access to a resource changes or when users become dormant. Queries will return results based on the chosen entity or type of entity, a specified destination, and any applied filters. Columns will contain additional entity properties and permission details.

Saved searches and built-in insights

When viewing Saved Queries and Veza Insights, you can view the results in Authorization Graph or open the original query in Query Builder. To customize an assessment, open it in the Query Builder. You can modify the underlying conditions or save a copy before adding it to a report.

Search Resources

See the following pages for more about Veza search interfaces and concepts:

Creating a query

To start building a custom query, go to Access Search > Query Builder. Every query begins by specifying the entity category to return in the results. You can click on a result name to see additional entity details and add columns for any additional attributes that Veza supports.

For example, you can show relationships between users managed in an identity provider, and databases they can access:

1. Create a simple query:

   • Go to Access Visibility > Query Builder

   • Choose Okta User as the source Entity Type

   • Add a destination by choosing Snowflake Database as the Related To entity

2. Inspect the results. Each result represents the total access for a user.

   • Click the number of Snowflake Databases to review all the databases and permissions the user relates to.

   • Review the result attributes. Every attribute Veza collects or generates for an entity is included in a unique row you can enable or disable, and apply filters on.

3. Show or hide columns to make the output more readable and focus on the most important metadata.

   • Click Columns to list all available attributes. Scroll down to show or hide any one of them.

   • Sort by columns such as the total number of relationships and Risk Score. Risk Score depends on the total number of queries with a risk level that an entity is in the results of.

To create meaningful insights for use in reports and alerts, you will want to refine the search by adding filters on entity attributes, and constraints on relationships, such as whether a result involves a specific group or role.

The query results will update dynamically, narrowing based on the options you apply. The finished query can be fine-tuned, for example, to

• Only show identities with specific capabilities on a resource with a permissions filter

• Filter based on a naming pattern with regular expressions

• Filter results by last access date or activity status

• Only show results for an individual provider account or tenant

• Run the query against a specific graph snapshot

• Show results with or without a relationship to an intermediate group, role, or policy

The rest of this document describes all Query Builder options. You can review built-in Saved Queries for inspiration, or see the following topics for more information:

Basic options

A query starts with a source, which can be an entity type (such as Active Directory User) or supertype (such as any User). To show all the entities Veza has discovered, pick from the Entity Type dropdown and run the query. From there, you can filter by tags, permissions, or attributes to create meaningful queries based on your needs and environment. To view past configurations, use the time machine,

Queries can be resource-centric or principal-centric, depending on your choices. For example, you can search for all S3 buckets associated with IdP users, or IdP identities with access to S3.

• You can filter the source destination type to only get results that are recently active, disabled, or meet criteria based on any other metadata Veza has collected.

• Filter the related entity type to get results related to destinations that meet that criteria, such as databases flagged for PCI compliance.

• Adding a related entity will only return results with a relationship to entities of the chosen type (such as "Okta Users with Snowflake Table permissions").

• To filter on a range of attributes and possible values, you can combine attribute filters with AND or OR statements, and use regular expressions.

Advanced options

Use the advanced options section to create a more specific search. These options apply constraints based on relationship qualities such as the number of related entities, or the existence of an intermediate entity. They are often used to identify cases where access is (or is not) enabled by a specific group or role, or filter out results based on intermediate entity attributes. Advanced options can:

• Filter on how many possible source entities a result relates to (e.g. "No more than 1" or "80% of the total").

• Find entities that aren't related.

• Inspect and create rules around complex relationships such as nested roles or groups.

• Find all “Super Users” related to a given percentage of all possible roles or other entities.

Result options

By default, Query Builder returns entities of the source type that meet the search criteria, including a total count. Query Builder can optionally return a result for each unique relationship. In this mode, you can further show a summary of entities in the path enabling the connection. These features can be useful when inspecting relationships between identities, RBAC controls, and resources.

To change the result mode, click show {destination entities} above the search results. You will notice that several rows can now appear for each user. This is because a result is now returned for each unique source > destination pair.

Click Show Summary Entities to add a column indicating when the selected Summary Entities exist in the path (for example, the group connecting an identity and a resource).

• The results show the source User, intermediate groups and roles, and the Database the user can access.

• Click an entry in the Summary Entities column to view the full path and more details.

• The Permissions columns show the actions the source can take on the resource. These appear in both provider-native System terms and the Effective Create/Read/Update/Delete capabilities each system permission corresponds to.

Heatmaps

Heatmaps show a visualization of how privileges are distributed for a given source entity type and related entity type, such as users related to the most roles. This view can be useful for finding overly-broad IAM roles or policies, over-permissioned users, or resources that are widely accessible.

To open a heatmap:

1. Search for two related entity types.

2. Click View as Heatmaps.

3. Click Edit Thresholds to change how entities are color-coded

4. Click View as Table to go back to the search results.

Entities with the most relationships (sorted by highest to lowest count) appear on the left, and entities with the least sorted on the right in green. Alter the query to update results based on a filter or other constraints.

Saving a query

In Query Builder, use the Save button add the query to the Saved Queries list. This enables integrating the query with other features, such as:

• Setting a risk level or sorting with labels

• Adding rules to trigger alerts based on the query

• Including the query in reports or on the dashboard

Query details

• Labels organize queries and can automatically populate reports. You can pick from existing labels or create them when saving a query.

• Adding a Risk Level highlights query results with a critical or warning indicator, and enables risk score calculation for monitoring and evaluating entities that meet the search criteria.

• Query Visibility determines whether other non-admin users can view and edit the saved query.

Rules and alerts

Rules inform Veza operators and trigger events when query results change, or when the attributes of entities in the results change. Set the criteria for the rule to trigger alerts on the conditions section.

Alerts can integrate with other systems depending on the notifications and webhooks an administrator has configured. You can set these destinations in the rule actions sections,

Reports

Additional options

• Click View to inspect the request in JSON format.

• Click Copy to immediately add it to your clipboard for pasting into another application.

See the following sections to learn more about Authorization Graph search.

Overview

Use the Search Bar at the top of the graph to:

• search for individual entities by name or all entities the same category (such as AWS S3 Bucket).

• save the current graph view, export to a PNG, or create a shareable link.

• open Tables view or switch to the Query Builder.

• pick a historic snapshot to run the search against.

The search bar will autocomplete to show possible entities and entity types such as Users, Resources, and Services matching the keyword. Clicking See All Results will open a detailed view of the results.

Use the search options menu on the left side of the graph to:

• expand the search by adding a relationship to another entity or entity type.

• toggle highlighting of Risks and other entities of interest.

• enable color-coding by provider account.

• set the visibility of entity types shown in search results.

After you have found a view you want to share with other team members or return to later, you can:

• Save a shortcut to your current graph view by clicking the save icon on the top action bar and adding a title on the modal that follows. You can recall saved views from the Saved Graphs submenu.

• Share a direct link to the graph view.

• Save or copy the current view in PNG format.

Graph search options

Searching for a named entity will show the full authorization path for that entity. Optionally searching by entity category will show all entities of that type. After specifying a source entity, you can use the relates to option to search for relationships connecting two entity types.

Depending on the search, results can include all relationships for a single named entity, or show the relationships for all entities of the source and destination types. For example, you show the full authorization path for a single User entity or show connections between all S3 buckets and Okta users.

Graph search navigation

The initial search results view will show no results until you have entered a search term. After providing a search condition, the results will update and you can begin exploring the output. The columns will adapt based on the authorization relationships you are currently inspecting.

Search results appear within containers and columns, depending on the entity category and visible relationships. Identities typically appear on the left side of the graph, with data stores on the right. When several entities have the same name, a number appears next to the entity name to indicate the provider.

Click the actions dropdown next to a column name to show or hide specific entities within it. You can zoom or center with the controls at the bottom of the graph.

You can undo and redo your most recent action from the action bar at the bottom of the screen. The current search conditions appear on the left.

Graph snapshots

You can view the historic state of your cloud authorization infrastructure at a past date with Veza snapshots. Pick a calendar date from the dropdown menu, and current and future searches will return relationships and metadata from the chosen point in time.

In the current release, Veza retains graph snapshots for 31 days.

To change the snapshot for the graph query, click the Graph History icon from the top action bar.

Depending on Veza system settings, search results will:

• Refresh when adding or removing parameters (default), or

• Update when clicking the Execute Query button

Table view and graph export

Tables View can be useful for working with many search results. After you have fine-tuned the search, you can export it for additional processing in CSV format, or export it in PDF format to share with other teams:

• Click View AG relationships in table on the graph search bar

• Click Export at the top of the table.

Locking graph paths

A path connecting two entities represents a relationship (granting or denying access to a resource). You can click on the connection to lock the path and hide all other entities.

Graph relationship options

The bottom section of the Navigation bar holds graph visibility controls, in the “Show or Hide Relationships” section. You can collapse a layer (leaving the heading visible but hiding all entities within it), or remove the layer entirely.

You can use this to pick columns and entities to include in search results and graph exports to customize a view before sharing it, or to show only the most important details.

Additionally, the actions dropdown next to a column name provides the option to filter entities in a layer, collapse the layer, or pick specific items to include in the view. You can opt to show only entities associated with a Risk, or only the entities highlighted by a locked path (if enabled for the current search).

After opening a Graph search from the Saved Queries page or the Graph actions sidebar, use Relationship Options to additional layers for an optimal view.

Graph display options

The navigation menu provides several options to additionally refine your search:

• Highlight Entities of Interest > Deactivated Users: Highlight users that Veza identified as dormant.

• Advanced View: Some entities are not shown by default, for better performance and visual clarity. To show all related nodes, toggle "Advanced" in the search options. Depending on your search, the additional nodes might appear in existing layers, or new ones.

• Enable Pagination: Optimizes review of large result sets. When enabled, Left and Right arrows appear at the top of the screen, and limits the number of Currently Showing entities to 10. Each page of results shows just the relationships for the current leftmost entities. To limit layers other than the starting one, click ... to open the layer actions dropdown.

Graph actions sidebar

Clicking an entity in Authorization Graph search results will expand the actions sidebar. This menu provides additional details and search options for the chosen entity. Possible actions vary depending on your search and appear under Basic Actions, Actions, and the Properties section.

Entities with hierarchical relationships

Some entities, such as AWS IAM roles or AzureAD groups, can have nested relationships. Graph search indicates these relationships with a blue path between nodes within a layer, and an icon.

Click "Show Hierarchy" on the actions sidebar to open a horizontal view:

To show only top-level (or only nested) entities of the chosen category, apply an attribute filter on the hierarchical level property of the role, group, or policy.

Early Access: Graph Search Advanced Options: This feature enables showing or hiding entities and relationships that assumed by way of a secondary entity, such as a nested group or hierarchical role.

• For example, when searching for entity types such as AWS IAM Role > Redshift Database, you can opt to show or hide relationships that involve an assumed AWS IAM Role. Hiding assumed roles will show only paths where roles grant permissions directly to the resource, excluding relationships that involve assumed secondary roles.

• Similarly, for User > Local Group searches, hiding assumed entities will exclude groups the user is indirectly a member of rather than showing all indirect assignments and nested groups.

Effective permissions

Explaining Permissions: To explain single effective permissions with the same name, click the node to open the actions sidebar and click Ungroup. To show the full details for a single effective permission, click the EP node top open the actions sidebar and click Explain Effective Permissions.

• Effective Permissions can be Data (C)create, (R)ead, (W)rite, (D)elete, (N)on-Data, and (M)etadata.

• An Effective Permission labeled S (Sub) indicates when permissions do not apply directly to the related service, but that an identity has permissions on any resources under that service. For example, if an identity has an S EP node connecting to a KMS Service in an AWS account, the identity has permissions on some underlying EKS clusters.

Veza automatically parses entity metadata, such as storage bucket configuration settings, and user attributes such as manager or mfa_status. This metadata enables fine-grained searches with filters that target these entity attributes.

You can use filters to restrict a search, query, or workflow to return only results with attributes that meet a specified condition. For example:

• Only show identities with a certain manager, department, or activity status.

• Only show resources with a specific configuration, such as S3 Access Control List settings.

• Search by hierarchical group or sub-resource level.

• Only include entities that are in the results of another query.

Attribute filters

Add attribute filters to constrain results based on entity metadata, For example, to identify users by Date Created or Date Updated, or find storage buckets with no access logs. Combine attribute filters in groups to create more specific conditions, for example, to find users where "Is Active" is "False" and "Country Code" is "US".

Click + Add attribute Filter Group from the search bar to apply a constraint on an entity property:

1. Pick the Entity Type to filter. In Authorization Graph, the available entities depend on the layers currently enabled under Advanced Options. Changing the search mode can show extra entity types for some integrations. 1, Pick whether to use AND or OR for the filter group. This determines the behavior of grouped filters on an entity type.

2. Pick an Attribute Field to filter on. The available options depend on the chosen entity type.

3. Pick a filter Operator. You can change the default EQUALS to NOT or INCLUDES, or other operators depending on the attribute.

4. Pick the Attribute Value to filter.

   • The search bar will autocomplete when the Attribute Field is Name and the condition is EQUALS.

   • For timestamp-type fields, you can specify an absolute or relative date to filter values before or after a given point in time.

Tag filters

To add a column displaying any tags on the result source or destination, enable the Show tags checkboxes under Advanced Options.

To filter on tags, click Add Tag Filter on the left sidebar. After specifying an entity category to filter, the search field will autocomplete to suggest existing tags.

• Filtering the query source by tags will restrict the search results to only show entities with a matching cloud provider or Veza tag (such as S3 buckets tagged for compliance, or users belonging to department:finance).

• Filtering the destination by tags will restrict the search results to only return source entities with a relationship to entities with the specified tag.

Permission filters

You can use permission filters to find, for example, only service accounts with push permissions to production repositories, or IdP users with the ability to change S3 bucket Access Control Lists.

• System (sometimes called "configured" "or "raw") permissions are individual privileges defined by the provider, such as s3:BucketDelete for AWS IAM.

• Effective permissions are a System permission’s Create|Read|Update|Delete equivalent, for example, Data Write or Metadata Delete.

To filter by permissions, expand the Permissions section. Permission filters can have an OR or AND operator.

• Use OR to find results with any of the specified permissions

• Use AND to find results with all of the specified permissions

Permission filters for Graph can only apply to Effective Permissions. To filter by system permission:

• Switch to System mode

• Click Add Attribute Filter

• For the Entity Type, specify the "grouped" permission category to filter

• For the Attribute, click Permission

• Click the Value field to populate the dropdown.

Filtering principal-based queries by permissions will limit the search results to only return entities allowed to perform the specified action(s) on the destination resource. For resource-based queries, adding permissions will limit the search results to resources one or more principals have authorization to.

Use the Results of One Query to Filter Another Query

Saved query filters are a type of Query Builder filter that uses the output of one query to filter another. Some conditions are too complex for a single query or are more easily expressed in a sequence. For these cases, you can create a pipeline of saved query filters. These are similar to a sub-query in SQL, filtering entities with a matching id.

Tasks you can accomplish with this method include:

• Finding all Box folders accessible by Okta users in a country, and then finding all users outside the country who also have access to those folders.

• Getting Over Provisioned Scores for Snowflake Roles that can be assumed by Snowflake users who are not connected to an Okta user.

To use a query pipeline:

1. Create and save the sub-query. The saved query must have the same source entity type as the entities in the new query to which this filter will apply.

2. Create a new query. Add a source and optional destination entity types.

3. Click Add Attribute Filter Group.

4. Select the Entity Type to filter and click Add Saved Query.

   • Operator: In will filter any results that are in the output of the saved query. Not In will only show results that do not appear in the sub-query.

   • Saved Query: Choose from the list of saved queries. Only queries returning the same results as the Entity Type will appear in the list.

   Note: You can add additional saved query filters, either in the same group or a new filter group.

5. Click Save to apply the filter.

You can chain several queries in this manner. Search times may increase when adding many sub-queries.

Overview

A regular expression is a sequence of characters that define a pattern of symbols to match in search results. At the most basic level, a regular expression works similarly to text search: the regular expression production will match the exact text string "production". More complex expressions can match a pair of values, such as dev|production, or match a sequence of possible characters: [A-Za-z0-9].

Examples

Using a regular expression when filtering results by attribute can enable flexible searches, workflows, and alert rules. Notably, regular expressions allow for matching more than one combination (OR), unlike contains and does not contain filters (where all conditions must be true).

• Filter by multiple regions: (us-(east|west)-\d+)

• Match text containing a string: (.*production.*)

• Filter data resources in all US regions: (us-[A-Za-z]*)

• Check if a value is an expected format, such as a standard email: \b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b

Notes and Resources

Regular expressions can contain character literals, operators, and constructs. For more information, see:

A variety of sandboxes can be found online for learning, building, and testing regular expressions.

Supported Expressions

• Special characters such as *+?()| must be escaped with \

Possible expressions include:

Composites

• xy - x followed by y

• x|y - x or y (prefer x)

Repetitions

• x* - zero or more x, prefer more

• x+ - one or more x, prefer more

• x? - zero or one x, prefer one

• x{n,} - n or more x, prefer more

• x{n} - exactly n x

• x*? - zero or more x, prefer fewer

• x+? - one or more x, prefer fewer

• x?? - zero or one x, prefer zero

• x{n,}? - n or more x, prefer fewer

• x{n}? - exactly n x

Grouping

• (re) - numbered capturing group (submatch)

• (?P<name>re) - named & numbered capturing group (submatch)

• (?:re) - non-capturing group

• (?flags) - set flags within current group; non-capturing

• (?flags:re) - set flags during re; non-capturing

Flags

• i case-insensitive (default false)

• m multi-line mode (default false)

• s let . match (default false)

• U ungreedy: swap meaning of x* and x*?, x+ and x+? (default false)

Flag syntax is xyz (set) or -xyz (clear) or xy-z (set xy, clear z).

Empty Strings

• ^ - at beginning of text or line

• $ - at end of text

Character Class Elements

• . - any character, possibly including newline.

• x - single character

• A-Z - character range (inclusive)

• \d - Perl character class

• [:class:] - ASCII character class class

• \p{class} - Unicode character class class

• \pF - Unicode character class F (one-letter name

• [\d] - digits (≡ \d)

• [^\d] - not digits (≡ \D)

• [\D] - not digits (≡ \D)

• [^\D] - not not digits (≡ \d)

Perl character classes (ASCII-only)

• \d - digits (≡ [0-9)

• \D - not digits (≡ [^0-9)

• \s - whitespace (≡ [\t\n\f)

• \S - not whitespace (≡ [^\t\n\f)

• \w - word characters (≡ [0-9A-Za-z_)

• \W - not word characters (≡ [^0-9A-Za-z_)

ASCII Character Class

• [[:alnum:]] - alphanumeric (≡ [0-9A-Za-z])

• [[:alpha:]] - alphabetic (≡ [A-Za-z])

• [[:ascii:]] - ASCII (≡ [\x00-\x7F])

• [[:blank:]] - blank (≡ [\t ])

• [[:cntrl:]] - control (≡ [\x00-\x1F\x7F])

• [[:digit:]] - digits (≡ [0-9])

• [[:graph:]] - graphical (≡ [!-~])

• [[:lower:]] - lower case (≡ [a-z])

• [[:print:]] - printable (≡ [ -~] ≡ [ [:graph:]])

• [[:punct:]] - punctuation (≡ [!-/:-@[-{-~])

• [[:space:]] - whitespace (≡ [\t\n\v\f\r ])

• [[:upper:]] - upper case (≡ [A-Z])

• [[:word:]] - word characters (≡ [0-9A-Za-z_])

• [[:xdigit:]] - hex digit (≡ [0-9A-Fa-f])

Role assumption in AWS is managed through sets of policies and trust relationships. When an IAM role (the assumer) assumes another role (the assumee), it temporarily acquires the permissions assigned to the assumee. Two main components govern assume role operations:

• IAM Policies attached to the assumee role define what actions the role can perform, and on which resources.

• Trust Policies attached to the assumee role, specifying which principals (users, roles, or AWS services) can assume the role under what conditions.

Assumed roles in graph search

In Authorization Graph, the dot on the right side of an assumer role will connect to the dot on the left side of its assumee roles. In this example search, the AAD-Admin role can assume a variety of other roles:

The Explain Assume Role tool offers insight into these relationships. It visually represents how roles are interconnected, including the policies and policy statements that enable the operation.

To explain assumed roles:

1. Go to Access Visibility > Graph and search for a relationship involving AWS IAM Roles, such as Okta Users to AWS S3 buckets.

2. In the search results, click on an AWS IAM Role that can assume another role.

3. In the actions sidebar, click Explain Assume Role.

4. Inspect the results in the Explain Assumed Roles view:

   • Assumer: The origin role, which you picked in Authorization Graph.

   • Assumee: The assumed role. Use the dropdown menu to select other roles available to the assumer.

   • Policy: The AWS IAM Policy entity (such as an inline policy), which specifies actions and resources available to users with the role.

   • Policy Statement: The specific statement within the policy allowing the assume role operation.

   • Policy (Trust): The role-specific trust policy attached to the assumee, defining the principals allowed to assume it, and additional conditions, ex:

In this example, The Assumer role, Cct02aSu, can assume the permissions of an Assumee role DBWriteGroup. The AdministratorAccess policy linked to the Assumer outlines the general permissions. The corresponding policy statement specifies conditions under which role assumption can occur. The DBWriteGroup Trust Policy establishes a trust relationship, allowing the Assumer role to assume the Assumee role, possibly under specific conditions.

Early Access: Tagged Entity Search: This feature requires support to enable. Please contact your Veza customer success team for more details, and to enable the feature.

Searching for Tagged Entities

Use the Access Search > Tagged Entities panel to view all tagged entities. You can filter to show only results with tags that have a specific type, key, or value.

Each row shows a single tagged entity, identified by the Name and ID columns. The Tags column lists the tags applied to each entity. From this screen, you can:

• Remove a Veza Tag by clicking on the x next to the tag name (Veza tags are shown in purple).

• Show authorization relationships for the entity in graph search (Open in Authorization Graph).

• Click on an entity name to view additional details and node properties.

Use the dropdown menus at the top of the screen to filter the list of tags:

• Tag Type: show only Veza, AWS, or Google Cloud Platform tags or labels

• Key: show only tags with a matching key (such as environment)

• Value: show only tags with a matching value, (such as production)

Viewing tags discovered by Veza

To see all cloud native and Veza tags that exist on entities in the data catalog, open Data Catalog > Tags. Choose a tab to show AWS, GCP, or Veza tags (the options will depend on your configured providers). Each row represents a key:value pair Veza has discovered.

You can use this panel to view all Tags, and open results in Tagged Entity Search:

1. Open the Veza Tags, AWS Tags, or GCP Tags tab.

2. Use the search bar to filter the results if needed.

3. Click View all tagged entities.

To to remove a Veza Tag from the entities it applies to using Data Catalog > Tags:

1. Open the Veza Tags tab.

2. Filter to find the specific tag.

3. Click View All Tagged Entities

4. Find the entity on the Tagged Entities list, and click Remove Tag.

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.

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

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

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": "jsmith@example.com",
          "first_name": "John",
          "identity_type": "HUMAN",
          "idp_unique_id": "jsmith@example.com",
          "is_active": true,
          "last_login_at": "2024-08-02T05:52:42Z",
          "last_name": "Smith",
          "login": "jsmith@example.com",
          "mfa_active": true,
          "mfa_factors": [
            "question"
          ],
          "name": "jsmith@example.com",
          "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:

Veza Tags provide a way to add additional metadata to entities such as identities, policies, or data resources. You can create Veza tags and apply them to any object in the Access Graph, and use these tags to filter search results (along with any cloud-native tags Veza has discovered).

Overview

Cloud service providers such as AWS and Google Cloud offer ways to tag and label resources, identities, and other objects within an account or service. These provider-specific, cloud-native tags are typically used to enforce policies and enable automation. Tags and labels can also classify resources for business processes (such as spend management), or track technical metadata such as version or development environment.

Veza Tags enable the application of consistent tagging strategies across all identities, resources, and any other entities in the data catalog, regardless of cloud provider. Security teams can use Veza Tags to categorize entities and create rule-based policies without exposing the values or tagging scheme to AWS or GCP users.

Viewing Entity Tags

You might notice that some tags are already applied to your identity and data entities, as Veza automatically ingests pre-existing tags during discovery. You can see the provider-native or Veza tags for any entity using the Authorization Graph actions sidebar:

Like AWS tags, Veza tags have a key and an optional value. For example, a tag with the key Departments could have a value such as Engineering, Finance, or Sales. The DataCompliance key can be granted additional context with a value such as PCI, GDPR, or SOX:

You can view all AWS or Google tags and labels on entities in the Veza data catalog by browsing under the Configurations menu.

Search for Tagged Entities

It's not currently possible to search by tag key or value from Authorization Graph or Query Builder. However, you can add filters to only show entities with a given tag.

• Use the Data Catalog > Tags panel to review all the Veza Tags or cloud-native tags Veza has discovered, with the option to open any item in Tagged Entity Search.

Creating and Applying Veza Tags

You can create a new tag, or pick an existing one on the modal that appears.

To remove a tag from an entity:

1. Search for the entity using Authorization Graph or Query Builder *. From Query Builder, click on the result name to view details *. From Graph, click on the node to expand the actions sidebar, and choose View Details or Veza Tags

2. Any applied Veza Tags are shown in purple. Click the "x" next to a tag to remove it from the entity.

Tag Administration

The Data Catalog > Tags panel lists all the tags that Veza users have created, with additional tabs for any cloud native tags Veza has discovered. You can sort the list by key or title, or create a new tag from this panel:

1. Click the "Add New" button to create a new tag

2. Enter a key and value, and save your changes

3. Once populated, the tag can be assigned to entities and used as a filter

Using Tags in Search

To filter an Authorization Graph search by a Veza tag or external tag, click "Add tags" in the Filter by Tag section of the graph Search menu. Select an entity type to filter, and choose from the list of available tags.

Once the tag has been added to your search, the layer where the filter is applied will collapse to only include entities with a matching AWS or Veza Tag. You can see any tags filtering your current search on the search sidebar:

Note that tag-based filters are applied to a single entity type at a time. You can still filter multiple entity types by a Veza tag by applying the filter to each layer.

Tagging for custom apps and identity providers

{
  "name": "BitBucket",
  "tags": [
            {
              "key": "instanceTag1key",
              "value": "instanceTag1Val"
            },
            {
              "key": "instanceTag2key"
            }
          ],
  "projects": [
    {
      "name": "Project 1",
      "repos": [
        {
          "name": "Repo 1",
          "tags": [
            {
              "key": "repoTag1key",
              "value": "repoTag1Val"
            },
            {
              "key": "repoTag2key"
            }
          ]
        }
      ],
      "tags": [
        {
          "key": "projectTag1key",
          "value": "projectTag1Val"
        },
        {
          "key": "projectTag2key"
        }
      ]
    }
  ],
  "groups": [
    {
      "name": "Test Group 1",
      "tags": [
        {
          "key": "groupTag1key",
          "value": "groupTag1Val"
        },
        {
          "key": "groupTag2key"
        }
      ],
      "global_permissions": "ProjectCreator"
    }
  ],
  "users": [
    {
      "name": "User1",
      "email": "user1@testme.com",
      "identity": "user1@testme.com",
      "global_permissions": "BitbucketUser",
      "tags": [
        {
          "key": "userTag1key",
          "value": "userTag1Val"
        },
        {
          "key": "userTag2key"
        }
      ]
    }
  ]
}

Overview

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:

{
  "query_type": "SOURCE_TO_DESTINATION",
  "source_node_types": {
    "nodes": [
      {
        "node_type": "AwsIamUser",
        "condition_expression": {
          "specs": [
            {
              "fn": "EQ",
              "property": "is_active",
              "value": true
            }
          ]
        }
      }
    ]
  },
  "destination_node_types": {
    "nodes": [
      {
        "node_type": "S3Bucket"
      }
    ]
  }
}

Equivalent VQL:

SHOW AwsIamUser WHERE is_active = true RELATED_TO S3Bucket

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:

• VQL features enabled in your Veza instance

API Endpoints

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

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

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

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

Example Response

{
  "path_values": [
    {
      "source": {
        "id": "00u5pqrs7xyP9uvw30z9",
        "type": "OktaUser",
        "properties": {
          "email": "jsmith@example.com",
          "name": "jsmith@example.com",
          "first_name": "John",
          "last_name": "Smith",
          "is_active": true,
          "identity_type": "HUMAN"
        },
        "risk_level": "CRITICAL"
      },
      "abstract_permissions": [
        "MetadataRead"
      ],
      "concrete_permissions": [
        "s3:ListBucket"
      ],
      "destination": {
        "id": "arn:aws:s3:::aws-cloudtrail-logs-123456789012-abcdef12",
        "type": "S3Bucket",
        "properties": {
          "name": "aws-cloudtrail-logs-123456789012-abcdef12",
          "region": "us-east-1",
          "block_public_access_enabled": true
        },
        "risk_level": "LOW"
      }
    }
  ],
  "cursor": "eyJsaW1pdCI6NTAsInN0YXJ0IjpbInNlcV9pZP...",
  "has_more": true
}

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:

{
  "query": "SHOW SnowflakeUser RELATED TO SnowflakeTable WITH EFFECTIVE PERMISSIONS = ANY ('DATA_DELETE') LIMIT 50;"
}

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

{
  "query": "SHOW SnowflakeUser RELATED TO SnowflakeTable WITH EFFECTIVE PERMISSIONS = ANY ('DATA_DELETE') AFTER CURSOR 'elcl9uYW1lIjoicjJkMiJ9fQ==' LIMIT 50;"
}

Related Documentation

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:

SHOW [NodeSpec] -- Specifies the source node type
[ [NOT] RELATED TO [NodeSpec]] -- Filters results by related node type
[WITH | NOT WITH] PATH [NodeSpec] -- Filters on intermediate nodes
[WHERE (filter expressions)]
[RESULT INCLUDE [DESTINATION NODES | DESTINATION NODE COUNT | PATH SUMMARY]]
[HAVING [entity_result_count (condition) | percentage_of_total_count (condition)]]
[WITH QUERY OPTIONS (options)]
[AFTER CURSOR 'cursor_token'] -- For pagination, use cursor token from previous results
[LIMIT <number>]; -- Limit number of results returned

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:

[NodeType] [{ attribute1, attribute2, ... }] [WHERE (<attribute_name> <operator> <value> [AND|OR] ...)]

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

• WHERE: Optional clause that applies attribute-based filters to the nodes using the selected operators

Usage Examples

Basic node specification (returns all attributes):

SHOW AwsIamUser

Select specific attributes to display:

SHOW AwsIamUser { created_at, is_active, full_admin }

Apply filters without attribute selection:

SHOW AwsIamUser WHERE is_active = true

Combine attribute selection and filters:

SHOW AwsIamUser { created_at, email } WHERE is_active = true AND risk_score > 70

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:

SHOW OktaUser { email, last_login_at, department }
WHERE last_login_at >= CURRENT_DATE - 30
RELATED TO S3Bucket
WHERE block_public_acls = false
WITH PATH OktaGroup
WITH QUERY OPTIONS ( over_provisioned_score > 85 )

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

  • Attribute Names: Must match the exact casing (e.g., is_active, not Is_Active).

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:

SHOW AwsIamUser
RELATED TO S3Bucket
WITH SYSTEM PERMISSIONS = ANY ('s3:CreateBucket');

• 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

• METADATA_DELETE

• DATA_READ

• DATA_WRITE

• DATA_CREATE

• DATA_DELETE

• NON_DATA

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

SHOW AwsIamRole
RELATED TO S3Bucket
WHERE is_active = false
WITH EFFECTIVE PERMISSIONS = ALL ('METADATA_READ', 'METADATA_WRITE');

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:

  Copy

  SHOW OktaUser
  RELATED TO SnowflakeTable
  WITH PATH SnowflakeUser;

• Excluding Intermediate Nodes:

  Copy

  SHOW OktaUser
  RELATED TO SnowflakeTable
  NOT WITH PATH OktaGroup;

Modifiers and Filters

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

Example:

SHOW AwsIamUser
WHERE is_active = true AND risk_score > 70;

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:

SHOW AwsIamUser
RELATED TO S3Bucket
LIMIT 50;

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

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

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:

SHOW AwsIamUser
RELATED TO S3Bucket
RESULT INCLUDE DESTINATION NODES;

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

• Copy

  SHOW S3Bucket;

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

  Copy

  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.

  Copy

  SHOW AwsIamUser
  RELATED TO S3Bucket
  RESULT INCLUDE DESTINATION NODES;

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:

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;

Including Summary Entities

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;

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

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