CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-azure-mgmt-authorization

Microsoft Azure Authorization Management Client Library for Python providing RBAC, PIM, and access control capabilities

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

alerts.mddocs/

Security Alerts

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.

Capabilities

Alert Management

Monitor and manage security alerts that are triggered by suspicious or risky authorization activities.

def get(scope: str, alert_id: str) -> Alert:
    """
    Get details of a specific security alert.
    
    Parameters:
    - scope: The scope where the alert was triggered
    - alert_id: ID of the alert
    
    Returns:
    Alert object with alert details and incidents
    """

def list_for_scope(scope: str, filter: Optional[str] = None) -> Iterator[Alert]:
    """
    List security alerts for a specific scope.
    
    Parameters:
    - scope: The scope to list alerts for
    - filter: OData filter expression (optional)
    
    Returns:
    Iterator of Alert objects
    """

def update(scope: str, alert_id: str, parameters: Alert) -> Alert:
    """
    Update a security alert (e.g., dismiss, acknowledge).
    
    Parameters:
    - scope: The scope of the alert
    - alert_id: ID of the alert to update
    - parameters: Updated alert properties
    
    Returns:
    Updated Alert object
    """

def refresh(scope: str, alert_id: str) -> None:
    """
    Refresh a specific alert to scan for new incidents.
    
    Parameters:
    - scope: The scope of the alert
    - alert_id: ID of the alert to refresh
    """

def refresh_all(scope: str) -> None:
    """
    Refresh all alerts in a scope to scan for new incidents.
    
    Parameters:
    - scope: The scope to refresh alerts for
    """

Alert Configuration

Configure alert settings and thresholds to customize security monitoring behavior.

def get(scope: str, alert_id: str) -> AlertConfiguration:
    """
    Get configuration for a specific alert type.
    
    Parameters:
    - scope: The scope of the alert configuration
    - alert_id: ID of the alert to get configuration for
    
    Returns:
    AlertConfiguration object with current settings
    """

def list_for_scope(scope: str) -> Iterator[AlertConfiguration]:
    """
    List alert configurations for a scope.
    
    Parameters:
    - scope: The scope to list configurations for
    
    Returns:
    Iterator of AlertConfiguration objects
    """

def update(scope: str, alert_id: str, parameters: AlertConfiguration) -> AlertConfiguration:
    """
    Update alert configuration settings.
    
    Parameters:
    - scope: The scope of the alert configuration
    - alert_id: ID of the alert to configure
    - parameters: Updated configuration parameters
    
    Returns:
    Updated AlertConfiguration object
    """

Alert Definitions

Discover available alert types and their definitions that can be configured for monitoring.

def get(scope: str, alert_definition_id: str) -> AlertDefinition:
    """
    Get details of a specific alert definition.
    
    Parameters:
    - scope: The scope to get the alert definition for
    - alert_definition_id: ID of the alert definition
    
    Returns:
    AlertDefinition object with definition details
    """

def list_for_scope(scope: str) -> Iterator[AlertDefinition]:
    """
    List available alert definitions for a scope.
    
    Parameters:
    - scope: The scope to list alert definitions for
    
    Returns:
    Iterator of AlertDefinition objects
    """

Alert Incidents

Manage individual security incidents that are associated with alerts.

def get(scope: str, alert_id: str, alert_incident_id: str) -> AlertIncident:
    """
    Get details of a specific alert incident.
    
    Parameters:
    - scope: The scope of the alert incident
    - alert_id: ID of the parent alert
    - alert_incident_id: ID of the specific incident
    
    Returns:
    AlertIncident object with incident details
    """

def list_for_scope(scope: str, alert_id: str) -> Iterator[AlertIncident]:
    """
    List incidents for a specific alert.
    
    Parameters:
    - scope: The scope of the alert
    - alert_id: ID of the alert to list incidents for
    
    Returns:
    Iterator of AlertIncident objects
    """

def remediate(scope: str, alert_id: str, alert_incident_id: str) -> None:
    """
    Remediate (resolve) a specific alert incident.
    
    Parameters:
    - scope: The scope of the alert incident
    - alert_id: ID of the parent alert
    - alert_incident_id: ID of the incident to remediate
    """

Alert Operations

Monitor and manage long-running alert operations and background processes.

def get(scope: str, operation_id: str) -> AlertOperation:
    """
    Get status of a long-running alert operation.
    
    Parameters:
    - scope: The scope of the alert operation
    - operation_id: ID of the operation to check
    
    Returns:
    AlertOperation object with operation status
    """

def list_for_scope(scope: str) -> Iterator[AlertOperation]:
    """
    List all alert operations for a scope.
    
    Parameters:
    - scope: The scope to list alert operations for
    
    Returns:
    Iterator of AlertOperation objects representing running or completed operations
    """

def cancel(scope: str, operation_id: str) -> None:
    """
    Cancel a running alert operation.
    
    Parameters:
    - scope: The scope of the alert operation
    - operation_id: ID of the operation to cancel
    """

Usage Examples

Configuring Security Alerts

from azure.mgmt.authorization.models import AlertConfiguration

# Enable and configure an alert for excessive permissions
alert_config = AlertConfiguration(
    is_enabled=True,
    threshold={
        "percentage_threshold": 80,
        "time_period": "P7D"  # 7 days
    },
    notification_settings={
        "default_recipients": True,
        "notification_level": "All",
        "additional_recipients": ["security-team@company.com"]
    }
)

# Update the alert configuration
updated_config = client.alert_configurations.update(
    scope="/subscriptions/your-subscription-id",
    alert_id="TooManyOwnersAssignedToResource",
    parameters=alert_config
)

Managing Alert Incidents

# List all active alerts in a subscription
active_alerts = client.alerts.list_for_scope(
    scope="/subscriptions/your-subscription-id",
    filter="alertState eq 'Active'"
)

for alert in active_alerts:
    print(f"Alert: {alert.alert_definition.display_name}")
    print(f"Severity: {alert.alert_definition.severity}")
    print(f"Incident Count: {len(alert.alert_incidents or [])}")
    
    # List incidents for this alert
    incidents = client.alert_incidents.list_for_scope(
        scope="/subscriptions/your-subscription-id",
        alert_id=alert.name
    )
    
    for incident in incidents:
        if incident.state == "Active":
            print(f"  Active Incident: {incident.name}")
            print(f"  Reason: {incident.reason}")
            
            # Remediate the incident if it's a false positive
            if should_remediate_incident(incident):
                client.alert_incidents.remediate(
                    scope="/subscriptions/your-subscription-id",
                    alert_id=alert.name,
                    alert_incident_id=incident.name
                )
                print(f"  Remediated incident: {incident.name}")

Refreshing Alert Data

# Refresh all alerts to scan for new incidents
client.alerts.refresh_all(scope="/subscriptions/your-subscription-id")

# Refresh a specific alert
client.alerts.refresh(
    scope="/subscriptions/your-subscription-id",
    alert_id="TooManyOwnersAssignedToResource"
)

# Check refresh operation status
operation = client.alert_operation.get(
    scope="/subscriptions/your-subscription-id",
    operation_id="operation-guid"
)

print(f"Operation Status: {operation.status}")
if operation.status == "Succeeded":
    print("Alert refresh completed successfully")

Dismissing Alerts

from azure.mgmt.authorization.models import Alert

# Dismiss an alert as a false positive
alert_update = Alert(
    alert_state="Dismissed",
    last_modified_date_time=datetime.utcnow()
)

dismissed_alert = client.alerts.update(
    scope="/subscriptions/your-subscription-id",
    alert_id="alert-id",
    parameters=alert_update
)

print(f"Alert dismissed: {dismissed_alert.alert_definition.display_name}")

Querying Alert Definitions

# List all available alert definitions
alert_definitions = client.alert_definitions.list_for_scope(
    scope="/subscriptions/your-subscription-id"
)

print("Available Alert Types:")
for definition in alert_definitions:
    print(f"- {definition.display_name}")
    print(f"  Severity: {definition.severity}")
    print(f"  Description: {definition.description}")
    print(f"  Mitigate: {definition.mitigation_steps}")
    print()

Types

Alert Core Types

class AlertProperties:
    alert_definition_id: Optional[str]
    scope: Optional[str]
    alert_state: Optional[str]
    last_scanned_date_time: Optional[datetime]
    last_modified_date_time: Optional[datetime]
    alert_incidents: Optional[List[AlertIncident]]
    is_active: Optional[bool]

class AlertDefinitionProperties:
    display_name: Optional[str]
    scope: Optional[str]
    description: Optional[str]
    severity: Optional[str]
    security_impact: Optional[str]
    remediations: Optional[str]
    how_to_prevent: Optional[str]
    mitigation_steps: Optional[str]
    is_configuration_alert: Optional[bool]
    is_incident_alert: Optional[bool]

class AlertConfigurationProperties:
    alert_definition: Optional[AlertDefinition]
    scope: Optional[str]
    is_enabled: Optional[bool]
    threshold: Optional[dict]
    notification_settings: Optional[AlertNotificationSettings]

Alert Incident Types

class AlertIncidentProperties:
    alert_incident_id: Optional[str]
    alert_id: Optional[str]
    state: Optional[str]
    reason: Optional[str]
    alert_incident_link: Optional[str]
    remediate_alert_incident_link: Optional[str]

class AlertNotificationSettings:
    default_recipients: Optional[bool]
    notification_level: Optional[str]
    additional_recipients: Optional[List[str]]

class AlertOperation:
    id: Optional[str]
    name: Optional[str]
    status: Optional[str]
    status_detail: Optional[str]
    error: Optional[dict]
    last_action_date_time: Optional[datetime]

Alert Threshold Types

class AlertThreshold:
    percentage_threshold: Optional[int]
    duration_threshold: Optional[str]
    time_period: Optional[str]
    minimum_number_of_incidents: Optional[int]

class AlertConfigurationThreshold:
    value: Optional[int]
    unit: Optional[str]
    operator: Optional[str]

Constants

Alert States

class AlertState:
    ACTIVE = "Active"
    DISMISSED = "Dismissed"
    RESOLVED = "Resolved"

class AlertIncidentState:
    ACTIVE = "Active"
    REMEDIATED = "Remediated"

class AlertSeverity:
    HIGH = "High"
    MEDIUM = "Medium"
    LOW = "Low"
    UNKNOWN = "Unknown"

Alert Types

class AlertType:
    TOO_MANY_OWNERS_ASSIGNED_TO_RESOURCE = "TooManyOwnersAssignedToResource"
    TOO_MANY_PERMANENT_OWNERS_ASSIGNED_TO_RESOURCE = "TooManyPermanentOwnersAssignedToResource"
    DUPLICATE_RESOURCE_PERMISSIONS = "DuplicateResourcePermissions"
    TOO_MANY_GLOBAL_ADMINISTRATORS_ASSIGNED_TO_TENANT = "TooManyGlobalAdministratorsAssignedToTenant"
    REDUNDANT_MEMBERSHIP_IN_ROLE_ASSIGNABLE_GROUP = "RedundantMembershipInRoleAssignableGroup"
    PRIVILEGED_ROLE_ASSIGNED_OUTSIDE_PRIVILEGED_IDENTITY_MANAGEMENT = "PrivilegedRoleAssignedOutsidePrivilegedIdentityManagement"
    INVALID_LICENSE_ALERT = "InvalidLicenseAlert"

class NotificationLevel:
    NONE = "None"
    CRITICAL = "Critical"
    ALL = "All"

class OperationStatus:
    NOT_STARTED = "NotStarted"
    RUNNING = "Running"
    SUCCEEDED = "Succeeded"
    FAILED = "Failed"
    CANCELLED = "Cancelled"

Alert Remediation Actions

class RemediationAction: 
    REMOVE_ASSIGNMENT = "RemoveAssignment"
    REDUCE_ASSIGNMENT_SCOPE = "ReduceAssignmentScope"
    CONVERT_TO_ELIGIBLE = "ConvertToEligible"
    APPLY_CONDITIONAL_ACCESS = "ApplyConditionalAccess"
    ENABLE_PIM = "EnablePIM"
    REVIEW_PERMISSIONS = "ReviewPermissions"

Error Handling

Common alert-specific exceptions:

  • BadRequestError: Invalid alert configuration or malformed alert parameters
  • ForbiddenError: Insufficient permissions to manage alerts or access alert data
  • ResourceNotFoundError: Alert, incident, or configuration not found
  • ServiceUnavailableError: Alert service temporarily unavailable
  • TooManyRequestsError: Rate limiting on alert operations
from azure.core.exceptions import BadRequestError, ServiceUnavailableError

try:
    alert_config = client.alert_configurations.update(scope, alert_id, parameters)
except BadRequestError as e:
    print(f"Invalid alert configuration: {e.message}")
except ServiceUnavailableError:
    print("Alert service is temporarily unavailable, please try again later")
except ForbiddenError:
    print("Insufficient permissions to configure alerts")

Common Alert Scenarios

High-Risk Alert Types

Too Many Owners Assigned To Resource

  • Monitors resources with excessive number of owners
  • Helps prevent privilege sprawl and reduces attack surface
  • Configurable threshold for number of owners

Privileged Role Assigned Outside PIM

  • Detects privileged roles assigned without going through PIM
  • Ensures all privileged access follows governance policies
  • Critical for maintaining just-in-time access controls

Too Many Global Administrators

  • Monitors tenant-level administrative roles
  • Prevents excessive tenant-wide privileges
  • Configurable threshold for global admin count

Duplicate Resource Permissions

  • Identifies redundant permission assignments
  • Helps optimize role assignments and reduce complexity
  • Detects overlapping permissions from multiple sources

Alert Response Workflow

  1. Detection: Alerts automatically scan for security risks
  2. Notification: Security teams receive notifications based on configuration
  3. Investigation: Review alert details and associated incidents
  4. Remediation: Take appropriate action (remove access, convert to eligible, etc.)
  5. Resolution: Mark incidents as remediated or dismiss false positives

Integration with Compliance

Alerts support compliance requirements by:

  • Providing audit trails of security events
  • Enabling automated detection of policy violations
  • Supporting regular access certification processes
  • Generating reports for compliance reviews

Install with Tessl CLI

npx tessl i tessl/pypi-azure-mgmt-authorization

docs

access-reviews.md

alerts.md

auth-config.md

core-rbac.md

index.md

legacy-admin.md

metrics.md

pim.md

tile.json