0
# Security Assessment and Monitoring
1

2
Core security assessment functionality for Azure Security Center, providing comprehensive security alert management, security assessments, secure score tracking, and security recommendations. This module enables organizations to monitor their security posture and respond to threats effectively.
3

4
## Capabilities
5

6
### Security Alerts Management
7

8
Manage security alerts generated by Azure Security Center's threat detection capabilities, including viewing, investigating, and updating alert states.
9

10
```python { .api }
11
def list(
12
    filter: Optional[str] = None,
13
    select: Optional[str] = None,
14
    expand: Optional[str] = None,
15
    auto_dismiss_rule_name: Optional[str] = None,
16
    **kwargs: Any
17
) -> Iterator[Alert]
18
    """
19
    List all security alerts in the subscription.
20
    
21
    Parameters:
22
    - filter (str, optional): OData filter for results
23
    - select (str, optional): OData select for specific fields  
24
    - expand (str, optional): OData expand for related data
25
    - auto_dismiss_rule_name (str, optional): Name of auto-dismiss rule
26
    
27
    Returns:
28
    Iterator[Alert]: Iterator of Alert objects
29
    """
30

31
def list_by_resource_group(
32
    resource_group_name: str,
33
    filter: Optional[str] = None,
34
    select: Optional[str] = None, 
35
    expand: Optional[str] = None,
36
    auto_dismiss_rule_name: Optional[str] = None,
37
    **kwargs: Any
38
) -> Iterator[Alert]
39
    """
40
    List security alerts in a specific resource group.
41
    
42
    Parameters:
43
    - resource_group_name (str): Name of the resource group
44
    - filter (str, optional): OData filter for results
45
    - select (str, optional): OData select for specific fields
46
    - expand (str, optional): OData expand for related data
47
    - auto_dismiss_rule_name (str, optional): Name of auto-dismiss rule
48
    
49
    Returns:
50
    Iterator[Alert]: Iterator of Alert objects
51
    """
52

53
def list_subscription_level_by_region(
54
    asc_location: str,
55
    filter: Optional[str] = None,
56
    select: Optional[str] = None,
57
    expand: Optional[str] = None,
58
    auto_dismiss_rule_name: Optional[str] = None,
59
    **kwargs: Any
60
) -> Iterator[Alert]
61
    """
62
    List subscription-level alerts in a specific region.
63
    
64
    Parameters:
65
    - asc_location (str): Azure Security Center location
66
    - filter (str, optional): OData filter for results
67
    - select (str, optional): OData select for specific fields
68
    - expand (str, optional): OData expand for related data
69
    - auto_dismiss_rule_name (str, optional): Name of auto-dismiss rule
70
    
71
    Returns:
72
    Iterator[Alert]: Iterator of Alert objects
73
    """
74

75
def get_subscription_level(
76
    asc_location: str,
77
    alert_name: str,
78
    **kwargs: Any
79
) -> Alert:
80
    """
81
    Get details of a specific subscription-level alert.
82
    
83
    Parameters:
84
    - asc_location (str): Azure Security Center location
85
    - alert_name (str): Name of the alert
86
    
87
    Returns:
88
    Alert: Alert details
89
    """
90

91
def get_resource_group_level(
92
    asc_location: str,
93
    resource_group_name: str, 
94
    alert_name: str,
95
    **kwargs: Any
96
) -> Alert:
97
    """
98
    Get details of a specific resource group-level alert.
99
    
100
    Parameters:
101
    - asc_location (str): Azure Security Center location
102
    - resource_group_name (str): Name of the resource group
103
    - alert_name (str): Name of the alert
104
    
105
    Returns:
106
    Alert: Alert details
107
    """
108

109
def update_subscription_level_state_to_dismiss(
110
    asc_location: str,
111
    alert_name: str,
112
    **kwargs: Any
113
) -> None:
114
    """
115
    Dismiss a subscription-level alert.
116
    
117
    Parameters:
118
    - asc_location (str): Azure Security Center location
119
    - alert_name (str): Name of the alert to dismiss
120
    
121
    Returns:
122
    None
123
    """
124

125
def update_subscription_level_state_to_activate(
126
    asc_location: str,
127
    alert_name: str,
128
    **kwargs: Any
129
) -> None:
130
    """
131
    Activate a subscription-level alert.
132
    
133
    Parameters:
134
    - asc_location (str): Azure Security Center location
135
    - alert_name (str): Name of the alert to activate
136
    
137
    Returns:
138
    None
139
    """
140

141
def update_resource_group_level_state_to_dismiss(
142
    asc_location: str,
143
    resource_group_name: str,
144
    alert_name: str,
145
    **kwargs: Any
146
) -> None:
147
    """
148
    Dismiss a resource group-level alert.
149
    
150
    Parameters:
151
    - asc_location (str): Azure Security Center location
152
    - resource_group_name (str): Name of the resource group
153
    - alert_name (str): Name of the alert to dismiss
154
    
155
    Returns:
156
    None
157
    """
158

159
def update_resource_group_level_state_to_activate(
160
    asc_location: str,
161
    resource_group_name: str,
162
    alert_name: str,
163
    **kwargs: Any
164
) -> None:
165
    """
166
    Activate a resource group-level alert.
167
    
168
    Parameters:
169
    - asc_location (str): Azure Security Center location
170
    - resource_group_name (str): Name of the resource group
171
    - alert_name (str): Name of the alert to activate
172
    
173
    Returns:
174
    None
175
    """
176

177
def simulate(
178
    asc_location: str,
179
    alert_simulator_request_body: AlertSimulatorRequestBody,
180
    **kwargs: Any
181
) -> None:
182
    """
183
    Simulate security alerts for testing purposes.
184
    
185
    Parameters:
186
    - asc_location (str): Azure Security Center location
187
    - alert_simulator_request_body (AlertSimulatorRequestBody): Simulation request
188
    
189
    Returns:
190
    None
191
    """
192
```
193

194
### Security Assessments
195

196
Manage security assessments that evaluate resources against security recommendations and best practices.
197

198
```python { .api }
199
def list(
200
    scope: str,
201
    **kwargs: Any
202
) -> Iterator[SecurityAssessmentResponse]:
203
    """
204
    List security assessments for a specific scope.
205
    
206
    Parameters:
207
    - scope (str): Resource scope (subscription, resource group, or resource)
208
    
209
    Returns:
210
    Iterator[SecurityAssessmentResponse]: Iterator of SecurityAssessmentResponse objects
211
    """
212

213
def get(
214
    resource_id: str,
215
    assessment_name: str,
216
    expand: Optional[str] = None,
217
    **kwargs: Any
218
) -> SecurityAssessmentResponse:
219
    """
220
    Get details of a specific security assessment.
221
    
222
    Parameters:
223
    - resource_id (str): Resource ID of the assessed resource
224
    - assessment_name (str): Name or ID of the assessment
225
    - expand (str, optional): Comma-separated list of fields to expand
226
    
227
    Returns:
228
    SecurityAssessmentResponse: Assessment details
229
    """
230

231
def create_or_update(
232
    scope: str,
233
    assessment_name: str,
234
    assessment: SecurityAssessment,
235
    **kwargs: Any
236
) -> SecurityAssessment:
237
    """
238
    Create or update a security assessment.
239
    
240
    Parameters:
241
    - scope (str): Resource scope
242
    - assessment_name (str): Name or ID of the assessment
243
    - assessment (SecurityAssessment): Assessment data
244
    
245
    Returns:
246
    SecurityAssessment: Created or updated assessment
247
    """
248

249
def delete(
250
    scope: str,
251
    assessment_name: str,
252
    **kwargs: Any
253
) -> None:
254
    """
255
    Delete a security assessment.
256
    
257
    Parameters:
258
    - scope (str): Resource scope
259
    - assessment_name (str): Name or ID of the assessment
260
    
261
    Returns:
262
    None
263
    """
264
```
265

266
### Assessments Metadata
267

268
Manage metadata for security assessments, including assessment definitions, severity, and recommendations.
269

270
```python { .api }
271
def list(
272
    **kwargs: Any
273
) -> Iterator[SecurityAssessmentMetadata]:
274
    """
275
    List assessment metadata for all assessments.
276
    
277
    Returns:
278
    Iterator[SecurityAssessmentMetadata]: Iterator of assessment metadata
279
    """
280

281
def list_by_subscription(
282
    **kwargs: Any
283
) -> Iterator[SecurityAssessmentMetadata]:
284
    """
285
    List assessment metadata in the current subscription.
286
    
287
    Returns:
288
    Iterator[SecurityAssessmentMetadata]: Iterator of assessment metadata
289
    """
290

291
def get(
292
    assessment_metadata_name: str,
293
    **kwargs: Any
294
) -> SecurityAssessmentMetadata:
295
    """
296
    Get metadata for a specific assessment.
297
    
298
    Parameters:
299
    - assessment_metadata_name (str): Name of the assessment metadata
300
    
301
    Returns:
302
    SecurityAssessmentMetadata: Assessment metadata
303
    """
304

305
def get_in_subscription(
306
    assessment_metadata_name: str,
307
    **kwargs: Any
308
) -> SecurityAssessmentMetadata:
309
    """
310
    Get assessment metadata within subscription scope.
311
    
312
    Parameters:
313
    - assessment_metadata_name (str): Name of the assessment metadata
314
    
315
    Returns:
316
    SecurityAssessmentMetadata: Assessment metadata
317
    """
318

319
def create_in_subscription(
320
    assessment_metadata_name: str,
321
    assessment_metadata: SecurityAssessmentMetadata,
322
    **kwargs: Any
323
) -> SecurityAssessmentMetadata:
324
    """
325
    Create assessment metadata within subscription scope.
326
    
327
    Parameters:
328
    - assessment_metadata_name (str): Name of the assessment metadata
329
    - assessment_metadata (SecurityAssessmentMetadata): Metadata to create
330
    
331
    Returns:
332
    SecurityAssessmentMetadata: Created assessment metadata
333
    """
334

335
def delete_in_subscription(
336
    assessment_metadata_name: str,
337
    **kwargs: Any
338
) -> None:
339
    """
340
    Delete assessment metadata from subscription.
341
    
342
    Parameters:
343
    - assessment_metadata_name (str): Name of the assessment metadata
344
    
345
    Returns:
346
    None
347
    """
348
```
349

350
### Secure Scores
351

352
Track and manage secure scores that measure security posture across your environment.
353

354
```python { .api }
355
def list(
356
    **kwargs: Any
357
) -> Iterator[SecureScore]:
358
    """
359
    List secure scores for the subscription.
360
    
361
    Returns:
362
    Iterator[SecureScore]: Iterator of SecureScore objects
363
    """
364

365
def get(
366
    secure_score_name: str,
367
    **kwargs: Any
368
) -> SecureScore:
369
    """
370
    Get details of a specific secure score.
371
    
372
    Parameters:
373
    - secure_score_name (str): Name of the secure score
374
    
375
    Returns:
376
    SecureScore: Secure score details
377
    """
378
```
379

380
### Secure Score Controls
381

382
Manage secure score controls that define security requirements and contribute to overall secure scores.
383

384
```python { .api }
385
def list(
386
    expand: Optional[str] = None,
387
    **kwargs: Any
388
) -> Iterator[SecureScoreControlDetails]:
389
    """
390
    List secure score controls.
391
    
392
    Parameters:
393
    - expand (str, optional): Fields to expand in the response
394
    
395
    Returns:
396
    Iterator[SecureScoreControlDetails]: Iterator of control details
397
    """
398

399
def list_by_secure_score(
400
    secure_score_name: str,
401
    expand: Optional[str] = None,
402
    **kwargs: Any
403
) -> Iterator[SecureScoreControlDetails]:
404
    """
405
    List secure score controls for a specific secure score.
406
    
407
    Parameters:
408
    - secure_score_name (str): Name of the secure score
409
    - expand (str, optional): Fields to expand in the response
410
    
411
    Returns:
412
    Iterator[SecureScoreControlDetails]: Iterator of control details
413
    """
414

415
def get(
416
    secure_score_control_name: str,
417
    expand: Optional[str] = None,
418
    **kwargs: Any
419
) -> SecureScoreControlDetails:
420
    """
421
    Get details of a specific secure score control.
422
    
423
    Parameters:
424
    - secure_score_control_name (str): Name of the control
425
    - expand (str, optional): Fields to expand in the response
426
    
427
    Returns:
428
    SecureScoreControlDetails: Control details
429
    """
430
```
431

432
### Secure Score Control Definitions
433

434
Manage definitions for secure score controls.
435

436
```python { .api }
437
def list(
438
    **kwargs: Any
439
) -> Iterator[SecureScoreControlDefinitionItem]:
440
    """
441
    List secure score control definitions.
442
    
443
    Returns:
444
    Iterator[SecureScoreControlDefinitionItem]: Iterator of control definitions
445
    """
446

447
def list_by_subscription(
448
    **kwargs: Any
449
) -> Iterator[SecureScoreControlDefinitionItem]:
450
    """
451
    List control definitions within subscription scope.
452
    
453
    Returns:
454
    Iterator[SecureScoreControlDefinitionItem]: Iterator of control definitions
455
    """
456

457
def get(
458
    secure_score_control_definition_name: str,
459
    **kwargs: Any
460
) -> SecureScoreControlDefinitionItem:
461
    """
462
    Get definition of a specific secure score control.
463
    
464
    Parameters:
465
    - secure_score_control_definition_name (str): Name of the control definition
466
    
467
    Returns:
468
    SecureScoreControlDefinitionItem: Control definition
469
    """
470

471
def get_by_subscription(
472
    secure_score_control_definition_name: str,
473
    **kwargs: Any
474
) -> SecureScoreControlDefinitionItem:
475
    """
476
    Get control definition within subscription scope.
477
    
478
    Parameters:
479
    - secure_score_control_definition_name (str): Name of the control definition
480
    
481
    Returns:
482
    SecureScoreControlDefinitionItem: Control definition
483
    """
484
```
485

486
### Tasks
487

488
Manage security tasks and recommendations generated by Azure Security Center.
489

490
```python { .api }
491
def list(
492
    filter: Optional[str] = None,
493
    **kwargs: Any
494
) -> Iterator[SecurityTask]:
495
    """
496
    List security tasks for the subscription.
497
    
498
    Parameters:
499
    - filter (str, optional): OData filter for results
500
    
501
    Returns:
502
    Iterator[SecurityTask]: Iterator of SecurityTask objects
503
    """
504

505
def list_by_home_region(
506
    asc_location: str,
507
    filter: Optional[str] = None,
508
    **kwargs: Any
509
) -> Iterator[SecurityTask]:
510
    """
511
    List security tasks in the subscription's home region.
512
    
513
    Parameters:
514
    - asc_location (str): Azure Security Center location
515
    - filter (str, optional): OData filter for results
516
    
517
    Returns:
518
    Iterator[SecurityTask]: Iterator of SecurityTask objects
519
    """
520

521
def list_by_resource_group(
522
    resource_group_name: str,
523
    asc_location: str,
524
    filter: Optional[str] = None,
525
    **kwargs: Any
526
) -> Iterator[SecurityTask]:
527
    """
528
    List security tasks for a specific resource group.
529
    
530
    Parameters:
531
    - resource_group_name (str): Name of the resource group
532
    - asc_location (str): Azure Security Center location  
533
    - filter (str, optional): OData filter for results
534
    
535
    Returns:
536
    Iterator[SecurityTask]: Iterator of SecurityTask objects
537
    """
538

539
def get_subscription_level_task(
540
    asc_location: str,
541
    task_name: str,
542
    **kwargs: Any
543
) -> SecurityTask:
544
    """
545
    Get details of a specific subscription-level security task.
546
    
547
    Parameters:
548
    - asc_location (str): Azure Security Center location
549
    - task_name (str): Name of the task
550
    
551
    Returns:
552
    SecurityTask: Task details
553
    """
554

555
def get_resource_group_level_task(
556
    resource_group_name: str,
557
    asc_location: str,
558
    task_name: str,
559
    **kwargs: Any
560
) -> SecurityTask:
561
    """
562
    Get details of a specific resource group-level security task.
563
    
564
    Parameters:
565
    - resource_group_name (str): Name of the resource group
566
    - asc_location (str): Azure Security Center location
567
    - task_name (str): Name of the task
568
    
569
    Returns:
570
    SecurityTask: Task details
571
    """
572

573
def update_subscription_level_task_state(
574
    asc_location: str,
575
    task_name: str,
576
    task_update_action_type: str,
577
    **kwargs: Any
578
) -> None:
579
    """
580
    Update the state of a subscription-level security task.
581
    
582
    Parameters:
583
    - asc_location (str): Azure Security Center location
584
    - task_name (str): Name of the task
585
    - task_update_action_type (str): Action to perform (Activate, Dismiss)
586
    
587
    Returns:
588
    None
589
    """
590

591
def update_resource_group_level_task_state(
592
    resource_group_name: str,
593
    asc_location: str,
594
    task_name: str,
595
    task_update_action_type: str,
596
    **kwargs: Any
597
) -> None:
598
    """
599
    Update the state of a resource group-level security task.
600
    
601
    Parameters:
602
    - resource_group_name (str): Name of the resource group
603
    - asc_location (str): Azure Security Center location
604
    - task_name (str): Name of the task
605
    - task_update_action_type (str): Action to perform (Activate, Dismiss)
606
    
607
    Returns:
608
    None
609
    """
610
```
611

612
## Types
613

614
```python { .api }
615
class Alert:
616
    id: Optional[str]
617
    name: Optional[str]
618
    type: Optional[str]
619
    display_name: Optional[str]
620
    description: Optional[str]
621
    remediation_steps: Optional[List[str]]
622
    severity: Optional[str]  # High, Medium, Low, Informational
623
    intent: Optional[str]    # MITRE ATT&CK intent
624
    start_time_utc: Optional[datetime]
625
    end_time_utc: Optional[datetime]
626
    time_generated_utc: Optional[datetime]
627
    product_name: Optional[str]
628
    product_component_name: Optional[str]
629
    status: Optional[str]    # Active, Resolved, Dismissed
630
    entities: Optional[List[AlertEntity]]
631
    extended_properties: Optional[Dict[str, Any]]
632
    compromised_entity: Optional[str]
633
    tactics: Optional[List[str]]         # MITRE ATT&CK tactics
634
    techniques: Optional[List[str]]      # MITRE ATT&CK techniques
635
    supporting_evidence: Optional[AlertPropertiesSupportingEvidence]
636
    processing_end_time: Optional[datetime]
637
    alert_uri: Optional[str]
638
    system_alert_id: Optional[str]
639
    correlation_key: Optional[str]
640
    vendor_name: Optional[str]
641
    alert_type: Optional[str]
642
    version: Optional[str]
643

644
class SecurityAssessment:
645
    id: Optional[str]
646
    name: Optional[str]
647
    type: Optional[str]
648
    display_name: Optional[str]
649
    status: Optional[AssessmentStatus]
650
    additional_data: Optional[Dict[str, str]]
651
    links: Optional[AssessmentLinks]
652
    metadata: Optional[SecurityAssessmentMetadataProperties]
653
    partners_data: Optional[SecurityAssessmentPartnerData]
654

655
class AssessmentStatus:
656
    code: Optional[str]         # Healthy, Unhealthy, NotApplicable
657
    cause: Optional[str]
658
    description: Optional[str]
659
    first_evaluation_date: Optional[datetime]
660
    status_change_date: Optional[datetime]
661

662
class SecurityAssessmentMetadata:
663
    id: Optional[str] 
664
    name: Optional[str]
665
    type: Optional[str]
666
    display_name: Optional[str]
667
    policy_definition_id: Optional[str]
668
    description: Optional[str]
669
    remediation_description: Optional[str]
670
    category: Optional[List[str]]
671
    severity: Optional[str]      # High, Medium, Low
672
    user_impact: Optional[str]   # High, Moderate, Low  
673
    implementation_effort: Optional[str]  # High, Moderate, Low
674
    threats: Optional[List[str]]
675
    preview: Optional[bool]
676
    assessment_type: Optional[str]        # BuiltIn, CustomPolicy, CustomerManaged
677
    partner_data: Optional[SecurityAssessmentMetadataPartnerData]
678
    publication_date: Optional[datetime]
679
    planned_deprecation_date: Optional[datetime]
680
    tactics: Optional[List[str]]          # MITRE ATT&CK tactics
681
    techniques: Optional[List[str]]       # MITRE ATT&CK techniques
682

683
class SecureScore:
684
    id: Optional[str]
685
    name: Optional[str]
686
    type: Optional[str]
687
    display_name: Optional[str]
688
    current_score: Optional[float]
689
    max_score: Optional[int]
690
    percentage: Optional[float]
691
    weight: Optional[int]
692

693
class SecureScoreControlDetails:
694
    id: Optional[str]
695
    name: Optional[str]
696
    type: Optional[str]
697
    display_name: Optional[str]
698
    description: Optional[str]
699
    max_score: Optional[int]
700
    current_score: Optional[float]
701
    percentage: Optional[float]
702
    healthy_resource_count: Optional[int]
703
    unhealthy_resource_count: Optional[int]
704
    not_applicable_resource_count: Optional[int]
705
    weight: Optional[int]
706
    definition: Optional[SecureScoreControlDefinitionItem]
707

708
class SecurityTask:
709
    id: Optional[str]
710
    name: Optional[str]
711
    type: Optional[str]
712
    state: Optional[str]         # Active, Resolved, Dismissed
713
    creation_time_utc: Optional[datetime]
714
    security_task_parameters: Optional[SecurityTaskParameters]
715
    last_state_change_time_utc: Optional[datetime]
716
    sub_state: Optional[str]
717
    resource_id: Optional[str]
718

719
class AlertEntity:
720
    additional_properties: Optional[Dict[str, Any]]
721
    type: Optional[str]
722

723
class AlertSimulatorRequestBody:
724
    bundles: Optional[List[AlertSimulatorBundlesRequestProperties]]
725
```
726

727
## Usage Examples
728

729
### Working with Security Alerts
730

731
```python
732
from azure.identity import DefaultAzureCredential
733
from azure.mgmt.security import SecurityCenter
734

735
credential = DefaultAzureCredential()
736
client = SecurityCenter(credential, "subscription-id")
737

738
# List all active alerts
739
alerts = client.alerts.list(filter="properties/status eq 'Active'")
740
for alert in alerts:
741
    print(f"Alert: {alert.display_name}")
742
    print(f"Severity: {alert.severity}")
743
    print(f"Description: {alert.description}")
744
    
745
    # Dismiss high severity alerts after investigation
746
    if alert.severity == "High":
747
        # Get alert location from ID
748
        location = alert.id.split('/')[8]  # Extract location from resource ID
749
        client.alerts.update_subscription_level_state_to_dismiss(
750
            location, alert.name
751
        )
752

753
# Get specific alert details
754
alert_detail = client.alerts.get_subscription_level("eastus", "alert-name")
755
print(f"Alert entities: {len(alert_detail.entities)}")
756
print(f"MITRE tactics: {alert_detail.tactics}")
757
```
758

759
### Security Assessment Management
760

761
```python
762
# List all security assessments
763
assessments = client.assessments.list("subscriptions/sub-id")
764
unhealthy_assessments = [
765
    a for a in assessments 
766
    if a.status.code == "Unhealthy"
767
]
768

769
print(f"Found {len(unhealthy_assessments)} unhealthy assessments")
770

771
# Get assessment details
772
assessment = client.assessments.get(
773
    "subscriptions/sub-id",
774
    "assessment-id",
775
    expand="links,metadata"
776
)
777
print(f"Assessment: {assessment.display_name}")
778
print(f"Status: {assessment.status.description}")
779
```
780

781
### Secure Score Monitoring
782

783
```python
784
# Get secure scores
785
scores = client.secure_scores.list()
786
for score in scores:
787
    print(f"Score: {score.current_score}/{score.max_score} ({score.percentage}%)")
788

789
# Get detailed control information
790
controls = client.secure_score_controls.list(expand="definition")
791
for control in controls:
792
    if control.percentage < 50:  # Focus on low-performing controls
793
        print(f"Control: {control.display_name}")
794
        print(f"Current: {control.current_score}/{control.max_score}")
795
        print(f"Healthy resources: {control.healthy_resource_count}")
796
        print(f"Unhealthy resources: {control.unhealthy_resource_count}")
797
```