Skip to content

Commit 63ded01

Browse files
nscuronscuro
authored
Add notification concept and reference docs (#18)
Signed-off-by: nscuro <nscuro@protonmail.com>
1 parent 028ea00 commit 63ded01

8 files changed

Lines changed: 277 additions & 5 deletions

File tree

‎docs/concepts/.pages‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
title: Concepts
22
nav:
33
- index.md
4-
- access-control.md
5-
- vulnerability-policies.md
4+
- About access control: access-control.md
5+
- About notifications: notifications.md
6+
- About vulnerability policies: vulnerability-policies.md
67
- ...

‎docs/concepts/access-control.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Access control
1+
# About access control
22

33
Dependency-Track uses a role-based access control model built around **permissions**,
44
**teams**, and **users**. Teams hold permissions, and users inherit the

‎docs/concepts/architecture/design/notifications.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ and defaults to 100.
111111
### Routing
112112

113113
The router evaluates each notification against all enabled
114-
[alerts](../../../reference/notifications/publishers.md).
114+
[alerts](../../notifications.md#alerts).
115115
A rule matches if:
116116

117117
* Its scope matches the notification's scope

‎docs/concepts/notifications.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# About notifications
2+
3+
## Introduction
4+
5+
Dependency-Track includes a robust and configurable notification framework,
6+
capable of alerting users or systems about the occurrences of various events
7+
in the platform.
8+
9+
## Alerts
10+
11+
Alerts, a.k.a. *notification rules*, are configurations that specify which notifications
12+
are sent to which destinations. An alert defines the scope, groups, and level of notifications
13+
it is interested in, and optionally restricts matching to specific projects or tags.
14+
15+
Alerts can further be refined with a *filter expression*, written in [CEL], that evaluates
16+
against the content of each notification. This allows filtering by properties such as
17+
vulnerability severity, CVSS score, or component name, without requiring dedicated UI controls
18+
for each filter criterion. Refer to [Filter expressions](../reference/notifications/filter-expressions.md)
19+
for details.
20+
21+
## Publishers
22+
23+
Publishers are software components that send notifications emitted by the platform
24+
to a destination system. Dependency-Track supports multiple publishers, ranging from
25+
email to Webhook. Refer to [Publishers](../reference/notifications/publishers.md) for details.
26+
27+
## Templates
28+
29+
Templates define how the platform-internal representation of notifications
30+
(see [Notification schema](../reference/schemas/notification.md)) is transformed
31+
to match the expectation of notification recipients.
32+
33+
While each [publisher](#publishers) ships with a default template, administrators
34+
can also configure custom templates.
35+
36+
## Levels
37+
38+
Notifications can have one of three possible levels:
39+
40+
* Informational
41+
* Warning
42+
* Error
43+
44+
These levels behave similar to logging levels, in that they allow [alerts](#alerts)
45+
to define the verbosity of notifications being sent:
46+
47+
* Configuring an alert for level *Informational* will match notifications of level *Informational*, *Warning*, and *Error*.
48+
* Configuring an alert for level *Warning* will match notifications of level *Warning* and *Error*.
49+
* Configuring an alert for level *Error* will only match notifications of level *Error*.
50+
51+
## Scopes
52+
53+
Notifications are emitted for different *scopes*. A scope broadly categorises the *subject*
54+
of a notification.
55+
56+
* **SYSTEM**: Informs about system-level events, such as users being created, or integrations failing.
57+
* **PORTFOLIO**: Informs about portfolio-level events, such as BOM uploads, or newly identified vulnerabilities.
58+
59+
## Groups
60+
61+
A group is a granular classification of notification subjects within a [scope](#scopes).
62+
For example, the `NEW_VULNERABILITY` group within the `PORTFOLIO` scope identifies notifications
63+
emitted whenever a new vulnerability is found.
64+
65+
Refer to [Notification groups](../reference/notifications/groups.md) for the full list
66+
of groups, their scopes, levels, and triggers.
67+
68+
## Triggers
69+
70+
Notifications are produced via one of two triggers:
71+
72+
| Trigger | Description |
73+
|:---------|:------------------------------------------------------------|
74+
| Event | An event is emitted by the system under certain conditions. |
75+
| Schedule | The notification is sent based on a planned schedule. |
76+
77+
* Notifications triggered by events are ideal for near real-time automation,
78+
and integrations into chat platforms.
79+
* Notifications triggered on a schedule are typically used to communicate high-level summaries,
80+
and are thus a better fit for reporting purposes.
81+
82+
Each [group](#groups) supports exactly one trigger type. Most groups are event-triggered;
83+
the summary groups (`NEW_VULNERABILITIES_SUMMARY`, `NEW_POLICY_VIOLATIONS_SUMMARY`)
84+
are schedule-triggered.
85+
86+
[CEL]: https://cel.dev/

‎docs/concepts/vulnerability-policies.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Vulnerability policies
1+
# About vulnerability policies
22

33
Vulnerability policies let organisations encode how specific vulnerabilities should be triaged across
44
the portfolio. Where a [standard policy](../reference/vulnerability-policies.md) raises violations, a vulnerability policy acts

‎docs/reference/notifications/.pages‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
nav:
2+
- Groups: groups.md
23
- Publishers: publishers.md
34
- Filter expressions: filter-expressions.md

‎docs/reference/notifications/filter-expressions.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ Without a filter expression, an alert matches all notifications that satisfy its
1010
level, and project or tag restrictions. A filter expression adds a further condition: the
1111
notification is only dispatched when the expression evaluates to `true`.
1212

13+
See [Notification groups](groups.md) for the full list of groups that can be matched.
14+
1315
![Filter expression field in the alert editor](./images/filter-expression-editor.png)
1416

1517
## Syntax

‎docs/reference/notifications/groups.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# Notification groups
2+
3+
A *group* is a granular classification of a notification's subject. Every group
4+
belongs to one of two scopes: `SYSTEM` (platform-level events) or `PORTFOLIO`
5+
(events about projects, components, or findings). Every group also has a single
6+
trigger type: `Event` for ad-hoc notifications emitted in response to a system
7+
event, or `Schedule` for notifications produced periodically by a cron schedule.
8+
9+
Subject schemas for each group are documented in the
10+
[notification schema reference](../schemas/notification.md).
11+
12+
## SYSTEM scope
13+
14+
### `ANALYZER`
15+
16+
- **Trigger:** Event
17+
- **Level:** Any
18+
19+
Generated as a result of interacting with an external source of vulnerability
20+
intelligence.
21+
22+
### `CONFIGURATION`
23+
24+
- **Trigger:** Event
25+
- **Level:** Any
26+
27+
Generated as a result of platform configuration changes or configuration errors.
28+
29+
### `DATASOURCE_MIRRORING`
30+
31+
- **Trigger:** Event
32+
- **Level:** Any
33+
34+
Generated when performing mirroring of one of the supported datasources, such as
35+
the NVD.
36+
37+
### `FILE_SYSTEM`
38+
39+
- **Trigger:** Event
40+
- **Level:** Any
41+
42+
Generated as a result of a file system operation. These are typically only
43+
generated on error conditions.
44+
45+
### `INTEGRATION`
46+
47+
- **Trigger:** Event
48+
- **Level:** Any
49+
50+
Generated as a result of interacting with an external integration.
51+
52+
### `REPOSITORY`
53+
54+
- **Trigger:** Event
55+
- **Level:** Any
56+
57+
Generated as a result of interacting with one of the supported repositories,
58+
such as Maven Central, RubyGems, or npm.
59+
60+
### `USER_CREATED`
61+
62+
- **Trigger:** Event
63+
- **Level:** Informational
64+
65+
Generated as a result of a user creation.
66+
67+
### `USER_DELETED`
68+
69+
- **Trigger:** Event
70+
- **Level:** Informational
71+
72+
Generated as a result of a user deletion.
73+
74+
## PORTFOLIO scope
75+
76+
### `BOM_CONSUMED`
77+
78+
- **Trigger:** Event
79+
- **Level:** Informational
80+
81+
Generated whenever a supported BOM is ingested and identified.
82+
83+
### `BOM_PROCESSED`
84+
85+
- **Trigger:** Event
86+
- **Level:** Informational
87+
88+
Generated after a supported BOM is ingested, identified, and successfully
89+
processed.
90+
91+
### `BOM_PROCESSING_FAILED`
92+
93+
- **Trigger:** Event
94+
- **Level:** Error
95+
96+
Generated whenever a BOM upload process fails.
97+
98+
### `BOM_VALIDATION_FAILED`
99+
100+
- **Trigger:** Event
101+
- **Level:** Error
102+
103+
Generated whenever an invalid BOM is uploaded.
104+
105+
### `NEW_VULNERABILITY`
106+
107+
- **Trigger:** Event
108+
- **Level:** Informational
109+
110+
Generated whenever a new vulnerability is identified.
111+
112+
### `NEW_VULNERABLE_DEPENDENCY`
113+
114+
- **Trigger:** Event
115+
- **Level:** Informational
116+
117+
Generated as a result of a vulnerable component becoming a dependency of a
118+
project.
119+
120+
### `POLICY_VIOLATION`
121+
122+
- **Trigger:** Event
123+
- **Level:** Informational
124+
125+
Generated whenever a policy violation is identified.
126+
127+
### `PROJECT_AUDIT_CHANGE`
128+
129+
- **Trigger:** Event
130+
- **Level:** Informational
131+
132+
Generated whenever an analysis or suppression state has changed on a finding
133+
from a project.
134+
135+
### `PROJECT_CREATED`
136+
137+
- **Trigger:** Event
138+
- **Level:** Informational
139+
140+
Generated whenever a new project is created.
141+
142+
### `PROJECT_VULN_ANALYSIS_COMPLETE`
143+
144+
- **Trigger:** Event
145+
- **Level:** Informational
146+
147+
Generated when vulnerability analysis for a project completes.
148+
149+
### `VEX_CONSUMED`
150+
151+
- **Trigger:** Event
152+
- **Level:** Informational
153+
154+
Generated whenever a VEX document is ingested.
155+
156+
### `VEX_PROCESSED`
157+
158+
- **Trigger:** Event
159+
- **Level:** Informational
160+
161+
Generated after a VEX document is ingested and successfully processed.
162+
163+
### `VULNERABILITY_RETRACTED`
164+
165+
- **Trigger:** Event
166+
- **Level:** Informational
167+
168+
Generated whenever a previously reported vulnerability is retracted.
169+
170+
### `NEW_VULNERABILITIES_SUMMARY`
171+
172+
- **Trigger:** Schedule
173+
- **Level:** Informational
174+
175+
Summaries of new vulnerabilities identified in a set of projects.
176+
177+
### `NEW_POLICY_VIOLATIONS_SUMMARY`
178+
179+
- **Trigger:** Schedule
180+
- **Level:** Informational
181+
182+
Summary of new policy violations identified in a set of projects.

0 commit comments

Comments
 (0)