> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/search/saved-queries/manage-ootb-queries.md).

# Manage Out-of-the-Box Queries

Compare, update, reset, and review removals for the queries Veza ships

**Available in Veza v2026.9.7 and later.**

Veza includes hundreds of out-of-the-box (OOTB) queries, refined over time through product releases. When Veza changes the definition of a query a tenant already has, or drops one from the catalog, the query's details page reports the change and offers a decision about it.

By default, Veza applies those changes automatically. Turning on **staged review** holds each one for an administrator to accept or dismiss instead.

Two facts determine what Veza reports for a query:

* **Whether the query has been edited.** Editing an out-of-the-box query marks it as customized. The query keeps its identity as a system query; it does not become a custom query.
* **Whether Veza has changed the shipped definition.** A change can be an update to the definition, or removal of the entry from the catalog altogether.

{% hint style="info" %}
Veza does not keep a version history for out-of-the-box queries. A comparison is between the definition a query runs on today and the definition Veza ships today.
{% endhint %}

For more on working with saved queries and managing visibility, labels, risk levels, and rules, see [Saved Queries](/4yItIzMvkpAvMVFAamTf/features/search/saved-queries.md).

## How Veza applies out-of-the-box updates

Veza compares the out-of-the-box catalog against the queries in a tenant at two points:

* When the tenant is upgraded or restarted
* When an administrator refreshes static assessment data

Nothing runs the comparison on a schedule in between. When the query definition has changed, the outcome depends on whether staged review is enabled and whether the query has been edited.

| Situation                                                 | Staged review off (default)                                                | Staged review on                              |
| --------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------- |
| The shipped definition changed, and the query is unedited | Applied automatically                                                      | Staged as an update for review                |
| The shipped definition changed, and the query is edited   | Left untouched; no update is staged                                        | Staged as an update for review                |
| The entry was removed from the catalog                    | The query is deleted, along with its risks, reports, and scheduled exports | Staged as a removal for review                |
| A removed entry returned to the catalog                   | The query is restored to the current shipped definition                    | Any staged removal is dismissed automatically |

Even with staged review off, drift on an edited query stays visible: **View Changes** compares it against the definition Veza ships today.

Each team sees its own copy of every out-of-the-box query, so one team's edits and decisions do not affect another's. To propagate an edited out-of-the-box query to other teams, share it on a dashboard (see [Share edited out-of-the-box queries](/4yItIzMvkpAvMVFAamTf/features/insights/dashboards/dashboard-sharing.md#share-edited-out-of-the-box-queries)).

These rules apply whether or not staged review is on:

* **Deleting an out-of-the-box query does not keep it out of your assessments.** If Veza still ships the query, the next check restores it with the current shipped definition. [Disable it](/4yItIzMvkpAvMVFAamTf/features/search/saved-queries.md#disable-and-enable-queries) instead.
* **Queries a team cannot see are not staged.** A query whose target integrations are not configured for a team is hidden from that team's query lists, so Veza updates or removes it automatically. Configuring the integration later surfaces the query with the definition Veza ships at that point.
* **Existing customizations are not flagged retroactively.** When staged review is first enabled, each edited query is matched to the definition Veza ships at that moment. Earlier changes are not reported.

{% hint style="info" %}
Veza does not announce a staged change by email or in digest notifications. A pending decision appears on the query's details page and on the [Review Query Updates](#review-staged-changes-in-bulk) screen, and stays there until the change is accepted or dismissed.
{% endhint %}

## Enable staged review of out-of-the-box updates

Staged review is off by default. Until an administrator turns it on, Veza applies out-of-the-box updates and removals automatically, as described in [How Veza applies out-of-the-box updates](#how-veza-applies-out-of-the-box-updates).

To enable staged review:

1. Go to **Administration** > **System Settings** > **Assessment Queries**.
2. Enable **Stage OOTB Query Updates for Review**.

![The Stage OOTB Query Updates for Review setting](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-ea92ce34174dc397f23dab6dfc3b606cb6678328%2Footb-staging-system-setting.png?alt=media)

Veza reads the setting when it checks the catalog, so a change takes effect at the next restart or static data refresh, not immediately.

Turning the setting off resolves anything already staged, at the next check: an update on an unedited query is applied, an update on an edited query is dismissed, and a staged removal deletes the query.

## Check out-of-the-box status on a query

The **Modifications** field in the query details header bar reports how the query compares with the Veza catalog entry it came from, and the action available in that state.

![Query header bar showing the Modifications field](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-faed721fe3239be7cd26b43cfad10f3f6c4b4d33%2Footb-query-header-bar.png?alt=media)

| Modifications       | Meaning                                                                                                                                                                                                           | Action             |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| **Unchanged**       | The query runs on the definition Veza ships, and nobody has edited it.                                                                                                                                            | None               |
| **Edited**          | Someone has customized the query, so it no longer matches the shipped definition.                                                                                                                                 | **View Changes**   |
| **Removed by Veza** | Veza has dropped the source entry from the out-of-the-box catalog, and the removal is staged for review.                                                                                                          | **Review Removal** |
| **Clone**           | The query is a copy of another query, made with **Clone** or **Save as New**. A clone has no shipped definition of its own, so it offers no action even when an update is staged on the query it was copied from. | None               |

When an update is staged, the action becomes **Update Available** and **Modifications** still reads **Unchanged** or **Edited**.

{% hint style="info" %}
**Limitations.** **Modifications** appears on the query details page only. The **Queries** table has no column or badge for it. To list the queries with a staged update or removal, use [Review Query Updates](#review-staged-changes-in-bulk). The field is omitted altogether for a query built from scratch in [Query Builder](/4yItIzMvkpAvMVFAamTf/features/search/query-builder.md), which has no lineage to report.
{% endhint %}

{% hint style="info" %}
**Permissions.** Accepting or dismissing an update, keeping a removed query, and resetting a query each require a role that can update assessment queries: **Admin**, **Operator**, **Access Reviews Admin**, or **NHI Security Admin**. Deleting a removed query requires a role that can delete assessment queries.
{% endhint %}

## Compare a query with the Veza original

Click **View Changes** to open **Compare With Original Veza Query**, a full-page, read-only comparison.

The two cards show:

| Card                               | Contents                                                                                           |
| ---------------------------------- | -------------------------------------------------------------------------------------------------- |
| Left: **Current Version**          | The definition the query runs on today, attributed to the user who last edited it (**Edited by**). |
| Right: **Original System Version** | The definition Veza ships today, credited to Veza.                                                 |

On an unedited query, both cards read **Original System Version** and are credited to Veza.

Fields that differ are outlined and highlighted on both cards, in the direction the change runs: the card holding the older value is marked in red, and the card holding the newer one in green. On this screen the query's own edits are the newer value, so **Current Version** is green and **Original System Version** is red. Each card shows:

* **Query Name**, **Query Description**, and **Labels**
* **Risk Profile**, **Risk Level**, **Risk Explanation**, and **Risk Remediation**
* **Query Parameters** — the query logic: source entities, relationships, filters, conditions, and intermediate entities
* **Summary Entities**

A field is omitted from a card when that definition leaves it empty. Longer query logic is abbreviated, with a **Show Full Evaluation** link.

![Comparing a query with the Veza original](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-a30d33a3614e40732754cd3c9dafbca1d8ed3f65%2Footb-compare-original.png?alt=media)

If the query is eligible for reset, a **Reset to Original** button appears in the page header. See [Reset a query to its original version](#reset-a-query-to-its-original-version).

{% hint style="info" %}
Veza also compares two settings the cards do not show: the query's result type and whether it is optional. If one of those is the only difference, the query reads as changed but no field is highlighted.

Timestamps, authorship, and internal identifiers are ignored, and tenant and time variables are compared in their unresolved form.
{% endhint %}

Two states are reported in place of a comparison:

* **The original Veza query is no longer available**: Veza has removed the entry from the out-of-the-box catalog, so there is nothing left to compare against. The query keeps running on its current definition.
* **This query has no Veza original**: The query was not derived from an out-of-the-box query.

{% hint style="info" %}
**Checking lineage through the API.** [Get a saved query](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentquery.md) reports whether a query came from the catalog and whether it has been edited.
{% endhint %}

## Review a staged update

When [staged review is enabled](#enable-staged-review-of-out-of-the-box-updates) and Veza ships a new definition for a query in the tenant, the update is held for a decision rather than applied. **Update Available** opens the comparison as **Veza Query Update**, where the right card is titled **Updated System Version** and attributed **Suggested by** Veza. The staged definition is now the newer value, so the highlight direction flips: the right card is green, and the left card, which holds the definition the query runs on today, is red.

![Reviewing a staged out-of-the-box update](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-a92800070aba7fb0fe5084d9e9fd623714bdcad0%2Footb-pending-update.png?alt=media)

Two actions are available:

* **Update Query** replaces the query's definition with the one Veza ships, discarding every customization, including edits to fields the update itself does not change. It behaves exactly like [reset](#reset-a-query-to-its-original-version): the query ID, owners, creation record, and hidden, enabled, or disabled state are all preserved. Veza reports *Query updated to the latest Veza version*.
* **Dismiss** opens the **Dismiss this update?** dialog, which records an optional **Reason**. The query keeps its current definition, and Veza reports *Update dismissed*. Veza does not raise the same update again, but the next definition it ships stages a new one.

![Dismissing a staged out-of-the-box update](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-1db345fbdac373b46117b9026c42b6e9ead097f6%2Footb-dismiss-update.png?alt=media)

A query holds at most one staged update at a time. If Veza ships another definition while an update is still waiting for a decision, the newer one replaces it, so the definition under review is always the most recent.

### Compare a customized query against a staged update

**Available in Veza v2026.10.5 and later.** Earlier releases show two cards for every comparison.

When a query has been edited **and** an update is staged against it, the decision turns on three definitions rather than two, so **Veza Query Update** adds a third card on the left:

| Card                              | Contents                                                                                                                                                                                                                                                                  |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Left: **Original System Version** | The Veza definition the query had just before it was first edited. This is usually what Veza shipped at that time, but it is older if an update was staged and not yet accepted. Credited to Veza, with **Customized** and how long ago the fork was recorded underneath. |
| Middle: **Current Version**       | The definition the query runs on today, attributed to the user who last edited it (**Edited by**).                                                                                                                                                                        |
| Right: **Updated System Version** | The definition Veza ships now, attributed **Suggested by** Veza.                                                                                                                                                                                                          |

![Comparing a customized query against a staged update](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-d8627e13723205f92511bb3793cd2ceb75184db3%2Footb-compare-fork-point.png?alt=media)

Reading left to right separates the two changes the decision depends on: what the team customized (left to middle), and what accepting the update would change (middle to right).

Only the second is outlined. The middle and right cards carry the red and green highlights described above; the left card is for reference and is not highlighted.

The outlines mark every field where the current definition differs from the staged one. This includes the fields the team customized, whether or not Veza's update changes them. In the example above, **Labels** is outlined because the team added `best_practice`, not because the update touches labels.

{% hint style="warning" %}
**Accepting an update discards every customization, not only the ones the update changes.** **Update Query** replaces the whole definition; it does not merge the team's edits with the new Veza version. Each field outlined on **Current Version** reverts to the value on **Updated System Version**, including fields the update leaves identical to what Veza shipped before.

To keep the customizations, **Dismiss** the update instead. Accepting is recorded in the query's change history (**View Change History**) with the previous field values, so they can be read back afterwards. Restoring them means editing the query again.
{% endhint %}

Veza records the forked-from definition the first time a query is edited, through any change that marks it **Edited**, including setting a risk level. The record is cleared when the query is [reset](#reset-a-query-to-its-original-version) and when a staged update is accepted, since both restore the query to a shipped definition; the next edit records a fresh one. The third card appears only when the record exists and an update is staged. Otherwise the comparison stays at two cards:

* **No update is staged.** The third card belongs to the staged-update review. **View Changes** compares two definitions.
* **The query was first edited before v2026.9.28.** Veza began recording fork points in that release, so it has no record of what an earlier edit was made against. [Resetting](#reset-a-query-to-its-original-version) the query and editing it again records one.

## Review a removed out-of-the-box query

When Veza drops a query from the out-of-the-box catalog and staged review is enabled, **Modifications** reads **Removed by Veza** and **Review Removal** opens **Veza Query Removed**. The query has not been changed or disabled; it keeps running until a decision is made. The page shows the definition it runs on today.

![Reviewing a removed out-of-the-box query](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-34b293d376e865c95387b4fce8c61c84db2c0d14%2Footb-query-removed.png?alt=media)

* **Keep Query** retains the query in the tenant and clears the flag. Veza reports *Query kept*, and does not raise the same removal again.
* **Delete Query** asks for confirmation, then permanently deletes the query along with its history. Reports, alerts, and workflows that use it stop returning results, and the deletion cannot be undone. Veza reports *Query deleted*.

{% hint style="info" %}
If Veza returns the query to the catalog before a decision is made, the staged removal is dismissed automatically and the flag clears.
{% endhint %}

## Review staged changes in bulk

{% hint style="info" %}
**Available starting with Veza v2026.10.26.** Earlier releases have no **Veza Query Updates** button, so each staged change is reviewed from its query's details page.
{% endhint %}

**Before you start**, [enable staged review](#enable-staged-review-of-out-of-the-box-updates). The bulk actions require the same roles as the single-query actions (see **Permissions** under [Check out-of-the-box status on a query](#check-out-of-the-box-status-on-a-query)), and updating a removed query also requires a role that can delete assessment queries.

When staged updates or removals are waiting, the **Queries** page shows a **Veza Query Updates** button with the number of queries that need a decision. Select it to open **Review Query Updates**, which lists every staged change in one place.

* The table shows each query's name, its modification status, and when the change was staged. **Modification Status** reads **Edited** or **Removed**, and is blank for an unedited query with a staged update. Filter by it to show only **Edited** or **Removed** queries.
* Select a query to see its staged change: the comparison described in [Review a staged update](#review-a-staged-update), or the definition of a removed query.
* The query name above the change opens its details page in a new tab. Use the arrows to move between queries.

To resolve several queries at once, select up to 100 of them and choose an action:

* **Update Selected Queries** works like **Update Query** on each selected query: its definition is replaced with the one Veza ships. A selected query that Veza removed is deleted instead, so Veza first lists those queries and asks you to confirm.
* **Dismiss Selected Queries** works like **Dismiss** but records no **Reason**: each selected query keeps its current definition. A removed query stays in the tenant, as with **Keep Query**.

{% hint style="warning" %}
**Update Selected Queries can delete queries and discard customizations.** Each removed query in the selection is deleted along with its history, and the deletion cannot be undone. Each edited query loses every customization, as described in [Compare a customized query against a staged update](#compare-a-customized-query-against-a-staged-update). To keep a query, clear it from the selection or dismiss it.
{% endhint %}

Veza reports how many queries it updated or dismissed. A query that someone else resolved in the meantime is reported as already resolved, not as a failure. If any query fails, Veza reports how many succeeded and leaves the failed queries selected so that they can be retried. When no staged changes remain, Veza opens the **Queries** page.

## Reset a query to its original version

Reset restores a customized out-of-the-box query to the definition Veza ships. Use it to discard changes to a query and return it to the current shipped baseline.

**Eligibility.** The option to **Reset to Original System Query** appears only for an out-of-the-box (system-created) query that has been edited. It is not offered for custom queries created in [Query Builder](/4yItIzMvkpAvMVFAamTf/features/search/query-builder.md), for uneditable static queries, or for queries shared with another team.

{% hint style="info" %}
**Resetting through the API.** `POST /api/v1/assessments/queries/{id}:reset` resets any out-of-the-box query, edited or not, and is idempotent. The console offers the action only for queries that have been edited.
{% endhint %}

Reset overwrites the query's content with the shipped default:

* Name, description, and query logic
* Result type and visibility
* Risk level, risk explanation, and remediation guidance
* Integration types, labels, and related query settings

Reset preserves the original query identity and access control:

* The query ID
* Query owners (the users with edit permission)
* Who created the query, and when
* Whether the query is hidden
* Whether the query is enabled or disabled

Resetting also clears the query's edited state, which removes **Reset to Original System Query** from the menu until the query is edited again.

To reset an out-of-the-box query:

1. Open the **Access Visibility** > **Queries** page.
2. Click the **Actions** menu (⋮) for the query to reset, and select **View Query Details**.
3. On the query details page, click **More options** (⋮) and select **Reset to Original System Query**.
4. Review the **Reset to original system query?** dialog — it names the query and warns that the changes made to it, including query logic, filters, risk settings, and labels, are lost and cannot be recovered — then click **Reset query**.

**Reset to Original** on the [comparison page](#compare-a-query-with-the-veza-original) does the same thing.

Veza reports *Query reset to original system query*, and refreshes the query in place.

**After reset.** The query runs on the current shipped definition from the next scheduled assessment run.

* If the reset changes the query's integration types or labels, dependent reports update automatically.
* The reset is recorded in the query's change history (**View Change History**) and in the [audit log](/4yItIzMvkpAvMVFAamTf/administration/administration/events.md).

**Errors and edge cases.**

* **Name conflict**: Reset fails if another out-of-the-box query already uses the shipped name.
* **Original no longer available**: If the original query definition is no longer part of the current Veza release, Veza reports *We couldn't reset this query* and explains that the original system query is no longer available. Retrying does not resolve this.
* **Ineligible query**: Uneditable and shared queries return a permission error. A custom query is rejected because it has no out-of-the-box definition to restore.

{% hint style="info" %}
Reset is separate from [dashboard sharing](/4yItIzMvkpAvMVFAamTf/features/insights/dashboards/dashboard-sharing.md): removing a shared dashboard does not reset or restore a query.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/search/saved-queries/manage-ootb-queries.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.