> 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/insights/rules-and-alerts.md).

# Rules and Alerts

Conditional notifications for risk and anomaly detection

### Overview

Veza's rules engine enables active monitoring of authorization changes within your environment. Rules and Alerts offer ways to establish security baselines based on any custom or built-in assessment query, and trigger notifications and Veza Actions when changes occur. For example, you might use Veza rules to:

* Identity new or removed accounts with superuser permissions on sensitive resources
* Get notifications for storage buckets with incorrect configurations
* Watch for changes to roles, IAM policies, or any other entity Veza has discovered.

When a rule is configured for a saved query, actions will trigger when the query results meet the conditions established by the rule. The baseline query, thresholds, and notification settings for these alert events are set when creating the rule. You can create your own queries to define the rule scope, or choose from built-in assessment queries. Alert notifications can use a webhook, email, or an external integration.

Possible rule and query combinations include:

* When your environment includes one or more Azure AD groups with no users
* When a new AWS IAM policy granting access to `*` resources is detected
* When the number of federated Okta users with AWS DynamoDB access changes
* When there are fewer than 2 principles with permissions for critical administrative tasks (in case one becomes unavailable)

{% hint style="success" %}
To highlight these entities in Search and show risk levels, mark the query as a [Risk](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/insights/risks.md) (in addition to, or instead of, creating an alert rule).
{% endhint %}

Use the actions dropdown menu to create or edit rules for any assessment in a dashboard. You can create and manage rules when saving a query.

**Alert firing logic**: Veza's alert system prevents excessive notifications. Once an alert is triggered by a specific condition—such as the result count exceeding 5—it will not re-trigger for the same condition until the metric falls back to or below 5 and then rises above it again.

### Add a rule to a query

To create a rule for a saved query, go to **Access Visibility** > *Queries*. You can also create a rule directly from the Query Builder or any dashboard.

{% hint style="info" %}
**Rules are not supported for union queries.** A union query combines two or more query sets, added with *+ Add Query Set* in Query Builder. On a union query, *+ Add a new rule* and each rule's edit button are disabled, with the tooltip "Rules are not supported for union queries." The API also rejects creating or updating a rule on a union query. An existing rule can still be deleted.
{% endhint %}

To add a rule for a saved query:

1. On the *Saved Queries* page, filter or search to find a built-in or user-created query. Click *Manage Rules* from the actions menu to edit rules for the query.

   ![Manage rules for a saved query.](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-8d7fa2e0d8a94472f589234fc95d8e8abf9d434c%2Fsaved-queries-manage-rules.png?alt=media)
2. Click *Add a new rule* to open the rule builder:

   !["Add a new rule" to set the severity level, conditions, and actions.](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f044bd9e6350752dc19ca70ecb0a30b257cc0d5a%2Frule-1-add-rule.png?alt=media)
3. Give the rule a name and description, and set the severity level.

   You can configure escalating levels of rules to trigger different actions based on the *severity* level: `High`, `Medium`, or `Low`.

   ![Configure rule details.](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-25cc3aaf31c7cb18a828e670d6dce877b931018e%2Frule-2-details.png?alt=media)
4. Configure rule conditions:

   Choose to trigger the rule based on the number of *Query Results*, or changes in *Query Properties*:

   ![Configure rule conditions.](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-8ba78cb0e668a59aa82d1ca4a695217bd97ce5c3%2Frule-3-conditions.png?alt=media)

   * *Query Results*: Choose an operator (equals, less than, more than, changed by, changed by more than, increased by more than) and count to trigger the rule.
   * *Query Properties*: Choose an attribute that will trigger the rule if it changes.
5. Configure rule actions (optional):

   Check the box to deliver the alert via the selected Veza Action: email, webhook, ServiceNow, or Jira. The alert will include details about the query result that triggered the rule for remediation purposes.

   ![Configure rule actions.](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-07c8841bfed4ac15eac6932f875eec8aec5f5ada%2Frule-4-actions.png?alt=media)

   If you have not configured a supported Veza Action, click *Create Veza Action* to open the builder in a new tab. To enable Webhooks and other destinations, see [Veza Actions](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/administration/administration/notifications.md).
6. Click *Save* to close the rule builder.
7. On the *Save Query* flow, add additional rules as desired.
8. Click *Save Query* to save your changes.

Once saved and enabled, the rule is listed on the **Rules** tab of the **Alerts** page. To open this page, click the **Alerts** bell icon in the top toolbar. On earlier versions, navigate to **Access Visibility** > **Rules and Alerts** from the left sidebar.

### Delivering notifications with alert actions

To deliver the notification via a webhook, email, or Slack, you will first need to create the connection from **Integrations** > [*Veza Actions*](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/administration/administration/notifications.md). When the rule triggers, a JSON payload will be delivered to the destination address, including:

* The query and results that triggered the rule
* The previous query results
* The entities that changed between the two updates

Supported targets for alerts are:

* [Webhooks](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/administration/administration/notifications/destinations/webhooks.md)
* [Jira](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/administration/administration/notifications/destinations/jira.md)
* [ServiceNow](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/administration/administration/notifications/destinations/servicenow.md)
* [Email](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/administration/administration/notifications.md)

### Customizing alert notifications

Alert email notifications use formatted HTML templates that include severity, timestamps, data values, and direct links to alerts and queries. Administrators can customize these templates from **System Settings**.

To customize alert email templates:

1. Navigate to **Administration** > **System Settings**.
2. Scroll to the **Custom Templates** section.
3. Click **Create Template**.
4. Select the event type:
   * **Query Rule Alert**: For threshold-based rule notifications
   * **Risk Alert**: For risk-level notifications
5. Customize the subject and body using [placeholder tokens](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/administration/administration/notifications/email-templates/placeholders-reference.md) such as `{{ALERT_TITLE}}`, `{{SEVERITY}}`, and `{{QUERY_NAME}}`.
6. Click **Save**.

For complete documentation on template customization, placeholders, and examples, see [Customizing email templates](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/administration/administration/notifications/email-templates/customizing-templates.md#access-intelligence-templates).

{% hint style="info" %}
Templates can also be managed programmatically via the [Notification Templates API](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/notification-templates.md#access-security).
{% endhint %}

### Viewing alerts

Veza notifications are always enabled for active rules. The **Alerts** bell icon in the top toolbar shows a badge when new alerts are available. Click the bell to open the **Alerts** page, where alerts can be sorted by date or severity.

* Each row on the **Rules** tab represents a Query with a rule attached, with the option to view query details, edit the rule, or delete the rule.
* The *Query Alerts* tab shows individual alert events for each time the rule has been triggered, including the trigger condition and description.


---

# 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/insights/rules-and-alerts.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.
