tessl/pypi-azure-mgmt-security
Microsoft Azure Security Center Management Client Library for Python
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
security-assessment-monitoring.mddocs/
Security Assessment and Monitoring
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.
Capabilities
Security Alerts Management
Manage security alerts generated by Azure Security Center's threat detection capabilities, including viewing, investigating, and updating alert states.
def list(
filter: Optional[str] = None,
select: Optional[str] = None,
expand: Optional[str] = None,
auto_dismiss_rule_name: Optional[str] = None,
**kwargs: Any
) -> Iterator[Alert]
"""
List all security alerts in the subscription.
Parameters:
- filter (str, optional): OData filter for results
- select (str, optional): OData select for specific fields
- expand (str, optional): OData expand for related data
- auto_dismiss_rule_name (str, optional): Name of auto-dismiss rule
Returns:
Iterator[Alert]: Iterator of Alert objects
"""
def list_by_resource_group(
resource_group_name: str,
filter: Optional[str] = None,
select: Optional[str] = None,
expand: Optional[str] = None,
auto_dismiss_rule_name: Optional[str] = None,
**kwargs: Any
) -> Iterator[Alert]
"""
List security alerts in a specific resource group.
Parameters:
- resource_group_name (str): Name of the resource group
- filter (str, optional): OData filter for results
- select (str, optional): OData select for specific fields
- expand (str, optional): OData expand for related data
- auto_dismiss_rule_name (str, optional): Name of auto-dismiss rule
Returns:
Iterator[Alert]: Iterator of Alert objects
"""
def list_subscription_level_by_region(
asc_location: str,
filter: Optional[str] = None,
select: Optional[str] = None,
expand: Optional[str] = None,
auto_dismiss_rule_name: Optional[str] = None,
**kwargs: Any
) -> Iterator[Alert]
"""
List subscription-level alerts in a specific region.
Parameters:
- asc_location (str): Azure Security Center location
- filter (str, optional): OData filter for results
- select (str, optional): OData select for specific fields
- expand (str, optional): OData expand for related data
- auto_dismiss_rule_name (str, optional): Name of auto-dismiss rule
Returns:
Iterator[Alert]: Iterator of Alert objects
"""
def get_subscription_level(
asc_location: str,
alert_name: str,
**kwargs: Any
) -> Alert:
"""
Get details of a specific subscription-level alert.
Parameters:
- asc_location (str): Azure Security Center location
- alert_name (str): Name of the alert
Returns:
Alert: Alert details
"""
def get_resource_group_level(
asc_location: str,
resource_group_name: str,
alert_name: str,
**kwargs: Any
) -> Alert:
"""
Get details of a specific resource group-level alert.
Parameters:
- asc_location (str): Azure Security Center location
- resource_group_name (str): Name of the resource group
- alert_name (str): Name of the alert
Returns:
Alert: Alert details
"""
def update_subscription_level_state_to_dismiss(
asc_location: str,
alert_name: str,
**kwargs: Any
) -> None:
"""
Dismiss a subscription-level alert.
Parameters:
- asc_location (str): Azure Security Center location
- alert_name (str): Name of the alert to dismiss
Returns:
None
"""
def update_subscription_level_state_to_activate(
asc_location: str,
alert_name: str,
**kwargs: Any
) -> None:
"""
Activate a subscription-level alert.
Parameters:
- asc_location (str): Azure Security Center location
- alert_name (str): Name of the alert to activate
Returns:
None
"""
def update_resource_group_level_state_to_dismiss(
asc_location: str,
resource_group_name: str,
alert_name: str,
**kwargs: Any
) -> None:
"""
Dismiss a resource group-level alert.
Parameters:
- asc_location (str): Azure Security Center location
- resource_group_name (str): Name of the resource group
- alert_name (str): Name of the alert to dismiss
Returns:
None
"""
def update_resource_group_level_state_to_activate(
asc_location: str,
resource_group_name: str,
alert_name: str,
**kwargs: Any
) -> None:
"""
Activate a resource group-level alert.
Parameters:
- asc_location (str): Azure Security Center location
- resource_group_name (str): Name of the resource group
- alert_name (str): Name of the alert to activate
Returns:
None
"""
def simulate(
asc_location: str,
alert_simulator_request_body: AlertSimulatorRequestBody,
**kwargs: Any
) -> None:
"""
Simulate security alerts for testing purposes.
Parameters:
- asc_location (str): Azure Security Center location
- alert_simulator_request_body (AlertSimulatorRequestBody): Simulation request
Returns:
None
"""Security Assessments
Manage security assessments that evaluate resources against security recommendations and best practices.
def list(
scope: str,
**kwargs: Any
) -> Iterator[SecurityAssessmentResponse]:
"""
List security assessments for a specific scope.
Parameters:
- scope (str): Resource scope (subscription, resource group, or resource)
Returns:
Iterator[SecurityAssessmentResponse]: Iterator of SecurityAssessmentResponse objects
"""
def get(
resource_id: str,
assessment_name: str,
expand: Optional[str] = None,
**kwargs: Any
) -> SecurityAssessmentResponse:
"""
Get details of a specific security assessment.
Parameters:
- resource_id (str): Resource ID of the assessed resource
- assessment_name (str): Name or ID of the assessment
- expand (str, optional): Comma-separated list of fields to expand
Returns:
SecurityAssessmentResponse: Assessment details
"""
def create_or_update(
scope: str,
assessment_name: str,
assessment: SecurityAssessment,
**kwargs: Any
) -> SecurityAssessment:
"""
Create or update a security assessment.
Parameters:
- scope (str): Resource scope
- assessment_name (str): Name or ID of the assessment
- assessment (SecurityAssessment): Assessment data
Returns:
SecurityAssessment: Created or updated assessment
"""
def delete(
scope: str,
assessment_name: str,
**kwargs: Any
) -> None:
"""
Delete a security assessment.
Parameters:
- scope (str): Resource scope
- assessment_name (str): Name or ID of the assessment
Returns:
None
"""Assessments Metadata
Manage metadata for security assessments, including assessment definitions, severity, and recommendations.
def list(
**kwargs: Any
) -> Iterator[SecurityAssessmentMetadata]:
"""
List assessment metadata for all assessments.
Returns:
Iterator[SecurityAssessmentMetadata]: Iterator of assessment metadata
"""
def list_by_subscription(
**kwargs: Any
) -> Iterator[SecurityAssessmentMetadata]:
"""
List assessment metadata in the current subscription.
Returns:
Iterator[SecurityAssessmentMetadata]: Iterator of assessment metadata
"""
def get(
assessment_metadata_name: str,
**kwargs: Any
) -> SecurityAssessmentMetadata:
"""
Get metadata for a specific assessment.
Parameters:
- assessment_metadata_name (str): Name of the assessment metadata
Returns:
SecurityAssessmentMetadata: Assessment metadata
"""
def get_in_subscription(
assessment_metadata_name: str,
**kwargs: Any
) -> SecurityAssessmentMetadata:
"""
Get assessment metadata within subscription scope.
Parameters:
- assessment_metadata_name (str): Name of the assessment metadata
Returns:
SecurityAssessmentMetadata: Assessment metadata
"""
def create_in_subscription(
assessment_metadata_name: str,
assessment_metadata: SecurityAssessmentMetadata,
**kwargs: Any
) -> SecurityAssessmentMetadata:
"""
Create assessment metadata within subscription scope.
Parameters:
- assessment_metadata_name (str): Name of the assessment metadata
- assessment_metadata (SecurityAssessmentMetadata): Metadata to create
Returns:
SecurityAssessmentMetadata: Created assessment metadata
"""
def delete_in_subscription(
assessment_metadata_name: str,
**kwargs: Any
) -> None:
"""
Delete assessment metadata from subscription.
Parameters:
- assessment_metadata_name (str): Name of the assessment metadata
Returns:
None
"""Secure Scores
Track and manage secure scores that measure security posture across your environment.
def list(
**kwargs: Any
) -> Iterator[SecureScore]:
"""
List secure scores for the subscription.
Returns:
Iterator[SecureScore]: Iterator of SecureScore objects
"""
def get(
secure_score_name: str,
**kwargs: Any
) -> SecureScore:
"""
Get details of a specific secure score.
Parameters:
- secure_score_name (str): Name of the secure score
Returns:
SecureScore: Secure score details
"""Secure Score Controls
Manage secure score controls that define security requirements and contribute to overall secure scores.
def list(
expand: Optional[str] = None,
**kwargs: Any
) -> Iterator[SecureScoreControlDetails]:
"""
List secure score controls.
Parameters:
- expand (str, optional): Fields to expand in the response
Returns:
Iterator[SecureScoreControlDetails]: Iterator of control details
"""
def list_by_secure_score(
secure_score_name: str,
expand: Optional[str] = None,
**kwargs: Any
) -> Iterator[SecureScoreControlDetails]:
"""
List secure score controls for a specific secure score.
Parameters:
- secure_score_name (str): Name of the secure score
- expand (str, optional): Fields to expand in the response
Returns:
Iterator[SecureScoreControlDetails]: Iterator of control details
"""
def get(
secure_score_control_name: str,
expand: Optional[str] = None,
**kwargs: Any
) -> SecureScoreControlDetails:
"""
Get details of a specific secure score control.
Parameters:
- secure_score_control_name (str): Name of the control
- expand (str, optional): Fields to expand in the response
Returns:
SecureScoreControlDetails: Control details
"""Secure Score Control Definitions
Manage definitions for secure score controls.
def list(
**kwargs: Any
) -> Iterator[SecureScoreControlDefinitionItem]:
"""
List secure score control definitions.
Returns:
Iterator[SecureScoreControlDefinitionItem]: Iterator of control definitions
"""
def list_by_subscription(
**kwargs: Any
) -> Iterator[SecureScoreControlDefinitionItem]:
"""
List control definitions within subscription scope.
Returns:
Iterator[SecureScoreControlDefinitionItem]: Iterator of control definitions
"""
def get(
secure_score_control_definition_name: str,
**kwargs: Any
) -> SecureScoreControlDefinitionItem:
"""
Get definition of a specific secure score control.
Parameters:
- secure_score_control_definition_name (str): Name of the control definition
Returns:
SecureScoreControlDefinitionItem: Control definition
"""
def get_by_subscription(
secure_score_control_definition_name: str,
**kwargs: Any
) -> SecureScoreControlDefinitionItem:
"""
Get control definition within subscription scope.
Parameters:
- secure_score_control_definition_name (str): Name of the control definition
Returns:
SecureScoreControlDefinitionItem: Control definition
"""Tasks
Manage security tasks and recommendations generated by Azure Security Center.
def list(
filter: Optional[str] = None,
**kwargs: Any
) -> Iterator[SecurityTask]:
"""
List security tasks for the subscription.
Parameters:
- filter (str, optional): OData filter for results
Returns:
Iterator[SecurityTask]: Iterator of SecurityTask objects
"""
def list_by_home_region(
asc_location: str,
filter: Optional[str] = None,
**kwargs: Any
) -> Iterator[SecurityTask]:
"""
List security tasks in the subscription's home region.
Parameters:
- asc_location (str): Azure Security Center location
- filter (str, optional): OData filter for results
Returns:
Iterator[SecurityTask]: Iterator of SecurityTask objects
"""
def list_by_resource_group(
resource_group_name: str,
asc_location: str,
filter: Optional[str] = None,
**kwargs: Any
) -> Iterator[SecurityTask]:
"""
List security tasks for a specific resource group.
Parameters:
- resource_group_name (str): Name of the resource group
- asc_location (str): Azure Security Center location
- filter (str, optional): OData filter for results
Returns:
Iterator[SecurityTask]: Iterator of SecurityTask objects
"""
def get_subscription_level_task(
asc_location: str,
task_name: str,
**kwargs: Any
) -> SecurityTask:
"""
Get details of a specific subscription-level security task.
Parameters:
- asc_location (str): Azure Security Center location
- task_name (str): Name of the task
Returns:
SecurityTask: Task details
"""
def get_resource_group_level_task(
resource_group_name: str,
asc_location: str,
task_name: str,
**kwargs: Any
) -> SecurityTask:
"""
Get details of a specific resource group-level security task.
Parameters:
- resource_group_name (str): Name of the resource group
- asc_location (str): Azure Security Center location
- task_name (str): Name of the task
Returns:
SecurityTask: Task details
"""
def update_subscription_level_task_state(
asc_location: str,
task_name: str,
task_update_action_type: str,
**kwargs: Any
) -> None:
"""
Update the state of a subscription-level security task.
Parameters:
- asc_location (str): Azure Security Center location
- task_name (str): Name of the task
- task_update_action_type (str): Action to perform (Activate, Dismiss)
Returns:
None
"""
def update_resource_group_level_task_state(
resource_group_name: str,
asc_location: str,
task_name: str,
task_update_action_type: str,
**kwargs: Any
) -> None:
"""
Update the state of a resource group-level security task.
Parameters:
- resource_group_name (str): Name of the resource group
- asc_location (str): Azure Security Center location
- task_name (str): Name of the task
- task_update_action_type (str): Action to perform (Activate, Dismiss)
Returns:
None
"""Types
class Alert:
id: Optional[str]
name: Optional[str]
type: Optional[str]
display_name: Optional[str]
description: Optional[str]
remediation_steps: Optional[List[str]]
severity: Optional[str] # High, Medium, Low, Informational
intent: Optional[str] # MITRE ATT&CK intent
start_time_utc: Optional[datetime]
end_time_utc: Optional[datetime]
time_generated_utc: Optional[datetime]
product_name: Optional[str]
product_component_name: Optional[str]
status: Optional[str] # Active, Resolved, Dismissed
entities: Optional[List[AlertEntity]]
extended_properties: Optional[Dict[str, Any]]
compromised_entity: Optional[str]
tactics: Optional[List[str]] # MITRE ATT&CK tactics
techniques: Optional[List[str]] # MITRE ATT&CK techniques
supporting_evidence: Optional[AlertPropertiesSupportingEvidence]
processing_end_time: Optional[datetime]
alert_uri: Optional[str]
system_alert_id: Optional[str]
correlation_key: Optional[str]
vendor_name: Optional[str]
alert_type: Optional[str]
version: Optional[str]
class SecurityAssessment:
id: Optional[str]
name: Optional[str]
type: Optional[str]
display_name: Optional[str]
status: Optional[AssessmentStatus]
additional_data: Optional[Dict[str, str]]
links: Optional[AssessmentLinks]
metadata: Optional[SecurityAssessmentMetadataProperties]
partners_data: Optional[SecurityAssessmentPartnerData]
class AssessmentStatus:
code: Optional[str] # Healthy, Unhealthy, NotApplicable
cause: Optional[str]
description: Optional[str]
first_evaluation_date: Optional[datetime]
status_change_date: Optional[datetime]
class SecurityAssessmentMetadata:
id: Optional[str]
name: Optional[str]
type: Optional[str]
display_name: Optional[str]
policy_definition_id: Optional[str]
description: Optional[str]
remediation_description: Optional[str]
category: Optional[List[str]]
severity: Optional[str] # High, Medium, Low
user_impact: Optional[str] # High, Moderate, Low
implementation_effort: Optional[str] # High, Moderate, Low
threats: Optional[List[str]]
preview: Optional[bool]
assessment_type: Optional[str] # BuiltIn, CustomPolicy, CustomerManaged
partner_data: Optional[SecurityAssessmentMetadataPartnerData]
publication_date: Optional[datetime]
planned_deprecation_date: Optional[datetime]
tactics: Optional[List[str]] # MITRE ATT&CK tactics
techniques: Optional[List[str]] # MITRE ATT&CK techniques
class SecureScore:
id: Optional[str]
name: Optional[str]
type: Optional[str]
display_name: Optional[str]
current_score: Optional[float]
max_score: Optional[int]
percentage: Optional[float]
weight: Optional[int]
class SecureScoreControlDetails:
id: Optional[str]
name: Optional[str]
type: Optional[str]
display_name: Optional[str]
description: Optional[str]
max_score: Optional[int]
current_score: Optional[float]
percentage: Optional[float]
healthy_resource_count: Optional[int]
unhealthy_resource_count: Optional[int]
not_applicable_resource_count: Optional[int]
weight: Optional[int]
definition: Optional[SecureScoreControlDefinitionItem]
class SecurityTask:
id: Optional[str]
name: Optional[str]
type: Optional[str]
state: Optional[str] # Active, Resolved, Dismissed
creation_time_utc: Optional[datetime]
security_task_parameters: Optional[SecurityTaskParameters]
last_state_change_time_utc: Optional[datetime]
sub_state: Optional[str]
resource_id: Optional[str]
class AlertEntity:
additional_properties: Optional[Dict[str, Any]]
type: Optional[str]
class AlertSimulatorRequestBody:
bundles: Optional[List[AlertSimulatorBundlesRequestProperties]]Usage Examples
Working with Security Alerts
from azure.identity import DefaultAzureCredential
from azure.mgmt.security import SecurityCenter
credential = DefaultAzureCredential()
client = SecurityCenter(credential, "subscription-id")
# List all active alerts
alerts = client.alerts.list(filter="properties/status eq 'Active'")
for alert in alerts:
print(f"Alert: {alert.display_name}")
print(f"Severity: {alert.severity}")
print(f"Description: {alert.description}")
# Dismiss high severity alerts after investigation
if alert.severity == "High":
# Get alert location from ID
location = alert.id.split('/')[8] # Extract location from resource ID
client.alerts.update_subscription_level_state_to_dismiss(
location, alert.name
)
# Get specific alert details
alert_detail = client.alerts.get_subscription_level("eastus", "alert-name")
print(f"Alert entities: {len(alert_detail.entities)}")
print(f"MITRE tactics: {alert_detail.tactics}")Security Assessment Management
# List all security assessments
assessments = client.assessments.list("subscriptions/sub-id")
unhealthy_assessments = [
a for a in assessments
if a.status.code == "Unhealthy"
]
print(f"Found {len(unhealthy_assessments)} unhealthy assessments")
# Get assessment details
assessment = client.assessments.get(
"subscriptions/sub-id",
"assessment-id",
expand="links,metadata"
)
print(f"Assessment: {assessment.display_name}")
print(f"Status: {assessment.status.description}")Secure Score Monitoring
# Get secure scores
scores = client.secure_scores.list()
for score in scores:
print(f"Score: {score.current_score}/{score.max_score} ({score.percentage}%)")
# Get detailed control information
controls = client.secure_score_controls.list(expand="definition")
for control in controls:
if control.percentage < 50: # Focus on low-performing controls
print(f"Control: {control.display_name}")
print(f"Current: {control.current_score}/{control.max_score}")
print(f"Healthy resources: {control.healthy_resource_count}")
print(f"Unhealthy resources: {control.unhealthy_resource_count}")Install with Tessl CLI
npx tessl i tessl/pypi-azure-mgmt-security