0
# Security Alerts
1
2
Real-time security monitoring and alerting for privileged access with configurable alert definitions, incident management, and automated remediation capabilities. The alerts system helps organizations proactively identify and respond to security risks in their authorization configurations.
3
4
## Capabilities
5
6
### Alert Management
7
8
Monitor and manage security alerts that are triggered by suspicious or risky authorization activities.
9
10
```python { .api }
11
def get(scope: str, alert_id: str) -> Alert:
12
"""
13
Get details of a specific security alert.
14
15
Parameters:
16
- scope: The scope where the alert was triggered
17
- alert_id: ID of the alert
18
19
Returns:
20
Alert object with alert details and incidents
21
"""
22
23
def list_for_scope(scope: str, filter: Optional[str] = None) -> Iterator[Alert]:
24
"""
25
List security alerts for a specific scope.
26
27
Parameters:
28
- scope: The scope to list alerts for
29
- filter: OData filter expression (optional)
30
31
Returns:
32
Iterator of Alert objects
33
"""
34
35
def update(scope: str, alert_id: str, parameters: Alert) -> Alert:
36
"""
37
Update a security alert (e.g., dismiss, acknowledge).
38
39
Parameters:
40
- scope: The scope of the alert
41
- alert_id: ID of the alert to update
42
- parameters: Updated alert properties
43
44
Returns:
45
Updated Alert object
46
"""
47
48
def refresh(scope: str, alert_id: str) -> None:
49
"""
50
Refresh a specific alert to scan for new incidents.
51
52
Parameters:
53
- scope: The scope of the alert
54
- alert_id: ID of the alert to refresh
55
"""
56
57
def refresh_all(scope: str) -> None:
58
"""
59
Refresh all alerts in a scope to scan for new incidents.
60
61
Parameters:
62
- scope: The scope to refresh alerts for
63
"""
64
```
65
66
### Alert Configuration
67
68
Configure alert settings and thresholds to customize security monitoring behavior.
69
70
```python { .api }
71
def get(scope: str, alert_id: str) -> AlertConfiguration:
72
"""
73
Get configuration for a specific alert type.
74
75
Parameters:
76
- scope: The scope of the alert configuration
77
- alert_id: ID of the alert to get configuration for
78
79
Returns:
80
AlertConfiguration object with current settings
81
"""
82
83
def list_for_scope(scope: str) -> Iterator[AlertConfiguration]:
84
"""
85
List alert configurations for a scope.
86
87
Parameters:
88
- scope: The scope to list configurations for
89
90
Returns:
91
Iterator of AlertConfiguration objects
92
"""
93
94
def update(scope: str, alert_id: str, parameters: AlertConfiguration) -> AlertConfiguration:
95
"""
96
Update alert configuration settings.
97
98
Parameters:
99
- scope: The scope of the alert configuration
100
- alert_id: ID of the alert to configure
101
- parameters: Updated configuration parameters
102
103
Returns:
104
Updated AlertConfiguration object
105
"""
106
```
107
108
### Alert Definitions
109
110
Discover available alert types and their definitions that can be configured for monitoring.
111
112
```python { .api }
113
def get(scope: str, alert_definition_id: str) -> AlertDefinition:
114
"""
115
Get details of a specific alert definition.
116
117
Parameters:
118
- scope: The scope to get the alert definition for
119
- alert_definition_id: ID of the alert definition
120
121
Returns:
122
AlertDefinition object with definition details
123
"""
124
125
def list_for_scope(scope: str) -> Iterator[AlertDefinition]:
126
"""
127
List available alert definitions for a scope.
128
129
Parameters:
130
- scope: The scope to list alert definitions for
131
132
Returns:
133
Iterator of AlertDefinition objects
134
"""
135
```
136
137
### Alert Incidents
138
139
Manage individual security incidents that are associated with alerts.
140
141
```python { .api }
142
def get(scope: str, alert_id: str, alert_incident_id: str) -> AlertIncident:
143
"""
144
Get details of a specific alert incident.
145
146
Parameters:
147
- scope: The scope of the alert incident
148
- alert_id: ID of the parent alert
149
- alert_incident_id: ID of the specific incident
150
151
Returns:
152
AlertIncident object with incident details
153
"""
154
155
def list_for_scope(scope: str, alert_id: str) -> Iterator[AlertIncident]:
156
"""
157
List incidents for a specific alert.
158
159
Parameters:
160
- scope: The scope of the alert
161
- alert_id: ID of the alert to list incidents for
162
163
Returns:
164
Iterator of AlertIncident objects
165
"""
166
167
def remediate(scope: str, alert_id: str, alert_incident_id: str) -> None:
168
"""
169
Remediate (resolve) a specific alert incident.
170
171
Parameters:
172
- scope: The scope of the alert incident
173
- alert_id: ID of the parent alert
174
- alert_incident_id: ID of the incident to remediate
175
"""
176
```
177
178
### Alert Operations
179
180
Monitor and manage long-running alert operations and background processes.
181
182
```python { .api }
183
def get(scope: str, operation_id: str) -> AlertOperation:
184
"""
185
Get status of a long-running alert operation.
186
187
Parameters:
188
- scope: The scope of the alert operation
189
- operation_id: ID of the operation to check
190
191
Returns:
192
AlertOperation object with operation status
193
"""
194
195
def list_for_scope(scope: str) -> Iterator[AlertOperation]:
196
"""
197
List all alert operations for a scope.
198
199
Parameters:
200
- scope: The scope to list alert operations for
201
202
Returns:
203
Iterator of AlertOperation objects representing running or completed operations
204
"""
205
206
def cancel(scope: str, operation_id: str) -> None:
207
"""
208
Cancel a running alert operation.
209
210
Parameters:
211
- scope: The scope of the alert operation
212
- operation_id: ID of the operation to cancel
213
"""
214
```
215
216
## Usage Examples
217
218
### Configuring Security Alerts
219
220
```python
221
from azure.mgmt.authorization.models import AlertConfiguration
222
223
# Enable and configure an alert for excessive permissions
224
alert_config = AlertConfiguration(
225
is_enabled=True,
226
threshold={
227
"percentage_threshold": 80,
228
"time_period": "P7D" # 7 days
229
},
230
notification_settings={
231
"default_recipients": True,
232
"notification_level": "All",
233
"additional_recipients": ["security-team@company.com"]
234
}
235
)
236
237
# Update the alert configuration
238
updated_config = client.alert_configurations.update(
239
scope="/subscriptions/your-subscription-id",
240
alert_id="TooManyOwnersAssignedToResource",
241
parameters=alert_config
242
)
243
```
244
245
### Managing Alert Incidents
246
247
```python
248
# List all active alerts in a subscription
249
active_alerts = client.alerts.list_for_scope(
250
scope="/subscriptions/your-subscription-id",
251
filter="alertState eq 'Active'"
252
)
253
254
for alert in active_alerts:
255
print(f"Alert: {alert.alert_definition.display_name}")
256
print(f"Severity: {alert.alert_definition.severity}")
257
print(f"Incident Count: {len(alert.alert_incidents or [])}")
258
259
# List incidents for this alert
260
incidents = client.alert_incidents.list_for_scope(
261
scope="/subscriptions/your-subscription-id",
262
alert_id=alert.name
263
)
264
265
for incident in incidents:
266
if incident.state == "Active":
267
print(f" Active Incident: {incident.name}")
268
print(f" Reason: {incident.reason}")
269
270
# Remediate the incident if it's a false positive
271
if should_remediate_incident(incident):
272
client.alert_incidents.remediate(
273
scope="/subscriptions/your-subscription-id",
274
alert_id=alert.name,
275
alert_incident_id=incident.name
276
)
277
print(f" Remediated incident: {incident.name}")
278
```
279
280
### Refreshing Alert Data
281
282
```python
283
# Refresh all alerts to scan for new incidents
284
client.alerts.refresh_all(scope="/subscriptions/your-subscription-id")
285
286
# Refresh a specific alert
287
client.alerts.refresh(
288
scope="/subscriptions/your-subscription-id",
289
alert_id="TooManyOwnersAssignedToResource"
290
)
291
292
# Check refresh operation status
293
operation = client.alert_operation.get(
294
scope="/subscriptions/your-subscription-id",
295
operation_id="operation-guid"
296
)
297
298
print(f"Operation Status: {operation.status}")
299
if operation.status == "Succeeded":
300
print("Alert refresh completed successfully")
301
```
302
303
### Dismissing Alerts
304
305
```python
306
from azure.mgmt.authorization.models import Alert
307
308
# Dismiss an alert as a false positive
309
alert_update = Alert(
310
alert_state="Dismissed",
311
last_modified_date_time=datetime.utcnow()
312
)
313
314
dismissed_alert = client.alerts.update(
315
scope="/subscriptions/your-subscription-id",
316
alert_id="alert-id",
317
parameters=alert_update
318
)
319
320
print(f"Alert dismissed: {dismissed_alert.alert_definition.display_name}")
321
```
322
323
### Querying Alert Definitions
324
325
```python
326
# List all available alert definitions
327
alert_definitions = client.alert_definitions.list_for_scope(
328
scope="/subscriptions/your-subscription-id"
329
)
330
331
print("Available Alert Types:")
332
for definition in alert_definitions:
333
print(f"- {definition.display_name}")
334
print(f" Severity: {definition.severity}")
335
print(f" Description: {definition.description}")
336
print(f" Mitigate: {definition.mitigation_steps}")
337
print()
338
```
339
340
## Types
341
342
### Alert Core Types
343
344
```python { .api }
345
class AlertProperties:
346
alert_definition_id: Optional[str]
347
scope: Optional[str]
348
alert_state: Optional[str]
349
last_scanned_date_time: Optional[datetime]
350
last_modified_date_time: Optional[datetime]
351
alert_incidents: Optional[List[AlertIncident]]
352
is_active: Optional[bool]
353
354
class AlertDefinitionProperties:
355
display_name: Optional[str]
356
scope: Optional[str]
357
description: Optional[str]
358
severity: Optional[str]
359
security_impact: Optional[str]
360
remediations: Optional[str]
361
how_to_prevent: Optional[str]
362
mitigation_steps: Optional[str]
363
is_configuration_alert: Optional[bool]
364
is_incident_alert: Optional[bool]
365
366
class AlertConfigurationProperties:
367
alert_definition: Optional[AlertDefinition]
368
scope: Optional[str]
369
is_enabled: Optional[bool]
370
threshold: Optional[dict]
371
notification_settings: Optional[AlertNotificationSettings]
372
```
373
374
### Alert Incident Types
375
376
```python { .api }
377
class AlertIncidentProperties:
378
alert_incident_id: Optional[str]
379
alert_id: Optional[str]
380
state: Optional[str]
381
reason: Optional[str]
382
alert_incident_link: Optional[str]
383
remediate_alert_incident_link: Optional[str]
384
385
class AlertNotificationSettings:
386
default_recipients: Optional[bool]
387
notification_level: Optional[str]
388
additional_recipients: Optional[List[str]]
389
390
class AlertOperation:
391
id: Optional[str]
392
name: Optional[str]
393
status: Optional[str]
394
status_detail: Optional[str]
395
error: Optional[dict]
396
last_action_date_time: Optional[datetime]
397
```
398
399
### Alert Threshold Types
400
401
```python { .api }
402
class AlertThreshold:
403
percentage_threshold: Optional[int]
404
duration_threshold: Optional[str]
405
time_period: Optional[str]
406
minimum_number_of_incidents: Optional[int]
407
408
class AlertConfigurationThreshold:
409
value: Optional[int]
410
unit: Optional[str]
411
operator: Optional[str]
412
```
413
414
## Constants
415
416
### Alert States
417
418
```python { .api }
419
class AlertState:
420
ACTIVE = "Active"
421
DISMISSED = "Dismissed"
422
RESOLVED = "Resolved"
423
424
class AlertIncidentState:
425
ACTIVE = "Active"
426
REMEDIATED = "Remediated"
427
428
class AlertSeverity:
429
HIGH = "High"
430
MEDIUM = "Medium"
431
LOW = "Low"
432
UNKNOWN = "Unknown"
433
```
434
435
### Alert Types
436
437
```python { .api }
438
class AlertType:
439
TOO_MANY_OWNERS_ASSIGNED_TO_RESOURCE = "TooManyOwnersAssignedToResource"
440
TOO_MANY_PERMANENT_OWNERS_ASSIGNED_TO_RESOURCE = "TooManyPermanentOwnersAssignedToResource"
441
DUPLICATE_RESOURCE_PERMISSIONS = "DuplicateResourcePermissions"
442
TOO_MANY_GLOBAL_ADMINISTRATORS_ASSIGNED_TO_TENANT = "TooManyGlobalAdministratorsAssignedToTenant"
443
REDUNDANT_MEMBERSHIP_IN_ROLE_ASSIGNABLE_GROUP = "RedundantMembershipInRoleAssignableGroup"
444
PRIVILEGED_ROLE_ASSIGNED_OUTSIDE_PRIVILEGED_IDENTITY_MANAGEMENT = "PrivilegedRoleAssignedOutsidePrivilegedIdentityManagement"
445
INVALID_LICENSE_ALERT = "InvalidLicenseAlert"
446
447
class NotificationLevel:
448
NONE = "None"
449
CRITICAL = "Critical"
450
ALL = "All"
451
452
class OperationStatus:
453
NOT_STARTED = "NotStarted"
454
RUNNING = "Running"
455
SUCCEEDED = "Succeeded"
456
FAILED = "Failed"
457
CANCELLED = "Cancelled"
458
```
459
460
### Alert Remediation Actions
461
462
```python { .api }
463
class RemediationAction:
464
REMOVE_ASSIGNMENT = "RemoveAssignment"
465
REDUCE_ASSIGNMENT_SCOPE = "ReduceAssignmentScope"
466
CONVERT_TO_ELIGIBLE = "ConvertToEligible"
467
APPLY_CONDITIONAL_ACCESS = "ApplyConditionalAccess"
468
ENABLE_PIM = "EnablePIM"
469
REVIEW_PERMISSIONS = "ReviewPermissions"
470
```
471
472
## Error Handling
473
474
Common alert-specific exceptions:
475
476
- **BadRequestError**: Invalid alert configuration or malformed alert parameters
477
- **ForbiddenError**: Insufficient permissions to manage alerts or access alert data
478
- **ResourceNotFoundError**: Alert, incident, or configuration not found
479
- **ServiceUnavailableError**: Alert service temporarily unavailable
480
- **TooManyRequestsError**: Rate limiting on alert operations
481
482
```python
483
from azure.core.exceptions import BadRequestError, ServiceUnavailableError
484
485
try:
486
alert_config = client.alert_configurations.update(scope, alert_id, parameters)
487
except BadRequestError as e:
488
print(f"Invalid alert configuration: {e.message}")
489
except ServiceUnavailableError:
490
print("Alert service is temporarily unavailable, please try again later")
491
except ForbiddenError:
492
print("Insufficient permissions to configure alerts")
493
```
494
495
## Common Alert Scenarios
496
497
### High-Risk Alert Types
498
499
**Too Many Owners Assigned To Resource**
500
- Monitors resources with excessive number of owners
501
- Helps prevent privilege sprawl and reduces attack surface
502
- Configurable threshold for number of owners
503
504
**Privileged Role Assigned Outside PIM**
505
- Detects privileged roles assigned without going through PIM
506
- Ensures all privileged access follows governance policies
507
- Critical for maintaining just-in-time access controls
508
509
**Too Many Global Administrators**
510
- Monitors tenant-level administrative roles
511
- Prevents excessive tenant-wide privileges
512
- Configurable threshold for global admin count
513
514
**Duplicate Resource Permissions**
515
- Identifies redundant permission assignments
516
- Helps optimize role assignments and reduce complexity
517
- Detects overlapping permissions from multiple sources
518
519
### Alert Response Workflow
520
521
1. **Detection**: Alerts automatically scan for security risks
522
2. **Notification**: Security teams receive notifications based on configuration
523
3. **Investigation**: Review alert details and associated incidents
524
4. **Remediation**: Take appropriate action (remove access, convert to eligible, etc.)
525
5. **Resolution**: Mark incidents as remediated or dismiss false positives
526
527
### Integration with Compliance
528
529
Alerts support compliance requirements by:
530
- Providing audit trails of security events
531
- Enabling automated detection of policy violations
532
- Supporting regular access certification processes
533
- Generating reports for compliance reviews