Skip to content

Commit 0f3d9c6

Browse files
tkykenmttkykenmt
authored
docs: add alerting-access-control report for v3.5.0 (#2598)
1 parent 652ec69 commit 0f3d9c6

File tree

5 files changed

+184
-0
lines changed

5 files changed

+184
-0
lines changed

‎docs/features/alerting/alerting-access-control.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
tags:
3+
- alerting
4+
---
5+
# Alerting Access Control
6+
7+
## Summary
8+
9+
The Alerting plugin provides role-based access control mechanisms to restrict which users can access monitor results in notification templates. This security feature prevents potential exposure of sensitive data through alert notifications by allowing administrators to specify which user roles are permitted to include query results in notification message templates.
10+
11+
## Details
12+
13+
### Architecture
14+
15+
```mermaid
16+
flowchart TB
17+
subgraph "Monitor Execution"
18+
A[Monitor Trigger] --> B[TriggerExecutionContext]
19+
B --> C{Check Access Control}
20+
end
21+
22+
subgraph "Access Control Check"
23+
C --> D{Setting Configured?}
24+
D -->|No| E[Return full results]
25+
D -->|Yes| F{Monitor roles ∩<br/>Allowed roles?}
26+
F -->|Yes| E
27+
F -->|No| G[Return empty results]
28+
end
29+
30+
subgraph "Notification"
31+
E --> H[Template with results]
32+
G --> I[Template without results]
33+
H --> J[Send Notification]
34+
I --> J
35+
end
36+
```
37+
38+
### Configuration
39+
40+
| Setting | Description | Default | Scope |
41+
|---------|-------------|---------|-------|
42+
| `plugins.alerting.notification_context_results_allowed_roles` | List of user roles allowed to include results in notification templates | `[]` (empty - all roles allowed) | Cluster |
43+
44+
### Behavior Matrix
45+
46+
| Setting State | Monitor User Roles | Result Access |
47+
|---------------|-------------------|---------------|
48+
| Not configured | Any | Full results |
49+
| Configured with `["admin"]` | `["admin", "user"]` | Full results |
50+
| Configured with `["admin"]` | `["user"]` | Empty results |
51+
| Configured with `["admin", "analyst"]` | `["analyst"]` | Full results |
52+
53+
### Usage Example
54+
55+
Configure allowed roles:
56+
57+
```json
58+
PUT _cluster/settings
59+
{
60+
"persistent": {
61+
"plugins.alerting.notification_context_results_allowed_roles": ["admin", "security_analyst"]
62+
}
63+
}
64+
```
65+
66+
In notification templates, `{{ctx.results}}` will:
67+
- Return query results for monitors owned by users with `admin` or `security_analyst` roles
68+
- Return an empty list for monitors owned by users without these roles
69+
70+
## Limitations
71+
72+
- Cluster-wide setting only; cannot be configured per-monitor
73+
- Affects all existing monitors immediately when changed
74+
- Only controls `results` field in templates; other context fields remain accessible
75+
- Document-level monitors always return empty results in templates by design
76+
77+
## Change History
78+
79+
- **v3.5.0** (2026-01-26): Initial implementation - Added `NOTIFICATION_CONTEXT_RESULTS_ALLOWED_ROLES` setting for role-based access control of trigger execution context results
80+
81+
## References
82+
83+
### Documentation
84+
85+
- [Alerting Security](https://opensearch.org/docs/latest/observing-your-data/alerting/security/) - Official documentation on alerting security and access control
86+
87+
### Pull Requests
88+
89+
| Version | PR | Description |
90+
|---------|-----|-------------|
91+
| v3.5.0 | [#1991](https://github.com/opensearch-project/alerting/pull/1991) | Access control for results in trigger execution context |
92+
93+
### Related Issues
94+
95+
- [#1986](https://github.com/opensearch-project/alerting/issues/1986) - Feature request: Access control for using monitor results in email template

‎docs/features/alerting/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
| Document | Description |
44
|----------|-------------|
5+
| [alerting-access-control](alerting-access-control.md) | Alerting Access Control |
56
| [alerting-integration](alerting-integration.md) | Alerting Integration |
67
| [alerting-ppl-alerting](alerting-ppl-alerting.md) | PPL Alerting |
78
| [alerting](alerting.md) | Alerting |

‎docs/features/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ Cumulative feature documentation across all versions.
44

55
## alerting
66

7+
- Alerting Access Control
78
- Alerting Integration
89
- Cross-Cluster & Remote Monitors
910

‎docs/releases/v3.5.0/features/alerting/alerting-access-control.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
tags:
3+
- alerting
4+
---
5+
# Alerting Access Control
6+
7+
## Summary
8+
9+
OpenSearch v3.5.0 introduces role-based access control for trigger execution context results in the Alerting plugin. A new cluster setting `plugins.alerting.notification_context_results_allowed_roles` allows administrators to restrict which user roles can include query results in notification message templates, preventing potential exposure of sensitive data through alert notifications.
10+
11+
## Details
12+
13+
### What's New in v3.5.0
14+
15+
This release adds a security enhancement to control access to monitor results in notification templates. When configuring alerting actions, users can include `ctx.results` in message templates to interpolate query results that triggered the alert. While useful, this could expose sensitive data through unencrypted notifications like email.
16+
17+
### New Configuration Setting
18+
19+
| Setting | Description | Default |
20+
|---------|-------------|---------|
21+
| `plugins.alerting.notification_context_results_allowed_roles` | List of user roles allowed to include results in notification templates | `[]` (empty - all roles allowed) |
22+
23+
### Behavior
24+
25+
```mermaid
26+
flowchart TB
27+
A[Trigger Execution] --> B{Setting Configured?}
28+
B -->|No| C[Include results in template context]
29+
B -->|Yes| D{Monitor roles intersect<br/>allowed roles?}
30+
D -->|Yes| C
31+
D -->|No| E[Return empty results in template context]
32+
C --> F[Notification sent with results]
33+
E --> G[Notification sent without results]
34+
```
35+
36+
- **Setting not configured (default)**: Original behavior preserved - all monitors can include results in notification templates
37+
- **Setting configured with roles**: Only monitors owned by users with at least one matching role can access results in templates
38+
- **No role intersection**: The `results` field in the template context returns an empty list
39+
40+
### Technical Changes
41+
42+
The implementation modifies the `TriggerExecutionContext` class hierarchy:
43+
44+
| Class | Change |
45+
|-------|--------|
46+
| `TriggerExecutionContext` | Added `templateResults` property with role-based filtering logic |
47+
| `QueryLevelTriggerExecutionContext` | Updated to pass `ClusterSettings` and use `templateResults` |
48+
| `BucketLevelTriggerExecutionContext` | Updated to pass `ClusterSettings` and use `templateResults` |
49+
| `DocumentLevelTriggerExecutionContext` | Updated to pass `ClusterSettings` and use `templateResults` |
50+
| `AlertingSettings` | Added `NOTIFICATION_CONTEXT_RESULTS_ALLOWED_ROLES` setting |
51+
52+
### Usage Example
53+
54+
To restrict results access to only `admin` and `security_analyst` roles:
55+
56+
```json
57+
PUT _cluster/settings
58+
{
59+
"persistent": {
60+
"plugins.alerting.notification_context_results_allowed_roles": ["admin", "security_analyst"]
61+
}
62+
}
63+
```
64+
65+
With this setting, monitors created by users without these roles will have empty `results` in their notification templates, even if they use `{{ctx.results}}` in the message body.
66+
67+
## Limitations
68+
69+
- The setting applies cluster-wide and cannot be configured per-monitor
70+
- Existing monitors are affected immediately when the setting is changed
71+
- The setting only affects the `results` field in notification templates; other context fields remain accessible
72+
- Document-level monitors always return empty results in templates (by design, as they don't populate results in the execution context)
73+
74+
## References
75+
76+
### Pull Requests
77+
78+
| PR | Description | Related Issue |
79+
|----|-------------|---------------|
80+
| [#1991](https://github.com/opensearch-project/alerting/pull/1991) | Access control for results in trigger execution context | [#1986](https://github.com/opensearch-project/alerting/issues/1986) |
81+
82+
### Related Issues
83+
84+
- [#1986](https://github.com/opensearch-project/alerting/issues/1986) - Feature request: Access control for using monitor results in email template

‎docs/releases/v3.5.0/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# OpenSearch v3.5.0 Release
22

3+
## alerting
4+
- Alerting Access Control
5+
36
## anomaly-detection
47
- Anomaly Detection Correlation
58

0 commit comments

Comments
 (0)