Azure Custom Role Designer

A powerful CLI tool for platform engineers to create, update, and manage Azure custom roles with granular control over permissions.

Features

• Create roles from scratch - Start with an empty role definition
• Cherry-pick permissions - Select specific permissions from existing roles
• Merge permissions - Combine permissions from one or more existing roles with filtering capabilities
• Remove permissions - Filter and exclude specific permissions with advanced filtering
• Filter by string - Search permissions by action name pattern
• Filter by type - Separate control and data plane permissions
• Persist roles - Save and load role definitions locally and to Azure

Installation

Option 1: Install from the repository (Recommended)

# Clone/navigate to the project
cd azure-custom-role-tool

# Install in development mode
pip install -e .

# Or install normally
pip install .

Option 2: Install with all dependencies

pip install azure-custom-role-tool

Option 3: Install from source with all requirements

git clone <repo-url>
cd azure-custom-role-tool
pip install .

Quick Start

Using the installed command

# Check version
azure-custom-role-tool --version

# Interactive mode
azure-custom-role-tool

# Or use specific commands
azure-custom-role-tool create --name "My Custom Role" --description "Custom role for my team"
azure-custom-role-tool merge --roles "devops-developer,reader" --filter "Storage"
azure-custom-role-tool remove --filter "Delete"

Using the module directly

# Check version
python -m azure_custom_role_tool --version

# Run as module
python -m azure_custom_role_tool

# Or use the module in your Python code
from azure_custom_role_tool import RoleManager, PermissionFilter, __version__
print(f"Using Azure Custom Role Tool v{__version__}")
manager = RoleManager()
role = manager.create_role("MyRole", "My custom role")

Usage

Interactive Mode

Run the tool without arguments or use the console command to enter console mode:

azure-custom-role-tool console

This launches an interactive menu where you can:

1. Create a new role
2. Load an existing role
3. Merge permissions
4. Remove permissions
5. Filter and view permissions
6. Save/publish the role

Interactive Features:

• Command History: Use arrow keys (↑/↓) to navigate through previous commands
• Persistent History: Command history is saved to ~/.azure-custom-role-tool-history and persists across sessions
• Context Help: Type help <command> to see detailed help for any command
• State Preservation: The current role remains loaded across multiple commands within the session

Command Line Mode

# Create a new role
azure-custom-role-tool create --name "Name" --description "Description" --subscription-id xx-xx-xx

# Start from existing role
azure-custom-role-tool load --name "existing-role"

# Merge multiple roles
azure-custom-role-tool merge --roles role1,role2,role3 --filter "Storage" --filter-type control

# Remove permissions
azure-custom-role-tool remove --filter "*/Delete/*" --filter-type data

# List available roles
azure-custom-role-tool list

# View role details
azure-custom-role-tool view --name "role-name"

# Save role locally
azure-custom-role-tool save --name "role-name" --output roles/my-role.json

# Publish to Azure
azure-custom-role-tool publish --name "role-name"

Configuration

Create a .env file for Azure authentication:

AZURE_SUBSCRIPTION_ID=your-subscription-id
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret

Or use Azure CLI authentication (default).

File Structure

azure-custom-role-tool/
├── custom_role_designer.py      # Main CLI tool
├── role_manager.py              # Role management logic
├── permission_filter.py          # Filtering and search
├── azure_client.py              # Azure SDK integration
├── requirements.txt             # Dependencies
├── roles/                       # Local role definitions
├── examples/                    # Example role definitions
└── tests/                       # Unit tests

Architecture

Role Definition Schema

Roles are stored as JSON files conforming to Azure custom role definition format:

{
  "Name": "Custom Role Name",
  "IsCustom": true,
  "Description": "Role description",
  "Type": "CustomRole",
  "Permissions": [
    {
      "Actions": ["Microsoft.Storage/*/read"],
      "NotActions": ["Microsoft.Storage/*/delete"],
      "DataActions": ["Microsoft.Storage/storageAccounts/blobServices/containers/blobs/*"],
      "NotDataActions": []
    }
  ],
  "CreatedOn": "2024-01-01",
  "UpdatedOn": "2024-01-01"
}

Permission Type Classification

• Control Plane: Management operations (e.g., Microsoft.Compute/virtualMachines/start/action)
• Data Plane: Data operations (e.g., Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read)

Examples

See the examples/ directory for pre-built roles like:

• devops-developer.json - DevOps developer permissions
• junior-developer.json - Junior developer restricted permissions
• senior-developer.json - Senior developer full permissions

Contributing

For issues or feature requests, open a GitHub issue.

License

MIT - Paulo Correia