Alert rules

An alert rule sends chosen Vulnara events to a channel outside the app: email, a webhook, Slack, Discord or Telegram. Each rule belongs to the workspace, so everyone in it shares the same rules. Alert rules are the only place that decides which events reach which addresses.

What it is for

• Telling a team channel when a scan finishes or fails.
• Feeding Vulnara events into your own systems through a webhook.
• Keeping security staff informed by email without them watching the app.

How it works

When something happens in the workspace, Vulnara looks for active rules that include that event, and sends a message to every recipient of each matching rule.

• Email: one email per address, using a template made for the event where one exists, and a general alert email otherwise.
• Webhook: a POST to each URL, with a JSON body carrying event, tenant and data, or your own template. Your custom headers are sent with it.
• Slack and Discord: a message to each incoming webhook URL, with the event title, its details and a link to Vulnara.
• Telegram: a message from your bot to each chat.

Delivery is best effort. If one recipient fails, the others still get their message.

Events you can choose

In the rule form, events are grouped by resource:

• Organization: Create, Update, Delete, Import Completed.
• Repository: Create, Update, Delete, Scan Started, Scan Completed, Scan Failed.
• Network: Create, Update, Delete, Scan Started, Scan Completed, Scan Failed.
• Git Token: Create, Update, Delete.
• Service Account: Create, Update, Delete.

Through the API, an event is named <resource>.<action>, for example repository.scan.completed or network.scan.failed.

What you can set

• Channel Type: Email, Webhook, Slack, Discord or Telegram.
• Recipients: one or more for the chosen channel:
  • email addresses. Workspace members are offered by name, and you can type any other address, such as a shared inbox;
  • HTTPS webhook URLs;
  • Slack or Discord incoming webhook URLs;
  • Telegram bots, each as a bot token and a chat id.
• Scopes: the events the rule sends. Select all picks every event.
• Custom headers: for webhooks only. Sent with every request, for example an Authorization header.
• Message templates: for the non-email channels, your own message text, for one event or for all events. Templates insert values with {{ variable }} and support the filters upper, lower, title and default('...'). A variable that does not exist is left empty.
• Active: a switch on each rule. An inactive rule sends nothing.

Do it

1. Go to Settings, then Alert rules.
2. Choose Create Alert Rule.
3. Pick a Channel Type and add the recipients. The form shows how to get a Slack, Discord or Telegram webhook or bot for the channel you pick.
4. Pick the Scopes.
5. Choose Create. The rule is active straight away.
6. On the rule, choose Send test to check it works.

To pause a rule, flip its active switch. To change or remove it, use Edit or Delete.

The same operations are in the API: createNotificationScope, updateNotificationScope, deleteNotificationScope, notificationScopes and testNotificationScope. In the CLI, use create_notification_scope and notification_scopes.

Test a rule

Send test delivers a fixed test message to every recipient of the rule straight away, and records the result as the rule's status:

• Operational: every recipient received it.
• Degraded: some recipients received it and some did not.
• Error: no recipient received it.

A test email has the subject "Vulnara alert rule test". Run a test after you create a rule and whenever you change its recipients.

Telegram

1. In Telegram, message @BotFather, send /newbot, and copy the bot token.
2. Send any message to your new bot.
3. In the rule form, paste the bot token and choose Detect chat ID.
4. Choose Add.

Good to know

• Who can manage rules: creating, changing, testing and deleting rules needs the editor role. See Teams and roles.
• Adding a member does not subscribe them: recipients are set per rule. Invite someone to the workspace and they get no alert email until a rule names them.
• Alert email counts towards your plan: each email to each address counts once against the plan's monthly alert email allowance. A rule with 50 addresses uses 50. When the allowance runs out, alert emails stop until the next cycle, but webhook, Slack, Discord and Telegram messages keep going. See Plans, usage and billing.
• Some mail is never held back: invitations, billing and account email are not alert email. They do not count and are always sent.
• Findings stay out of email: emails report counts per severity and link to the scan. They never include a matched secret, a file path or a line number.
• Header values are write-only: after you save a webhook header, its value is never shown again. Its name is.
• Recipients are validated: the form rejects an address or URL that does not fit the channel. A Telegram entry must be <bot_token>:<chat_id>.
• In-app notifications are separate: the notification bell in the app does not depend on alert rules. See Notifications.