az-rbac-watch

CLI for Azure RBAC drift detection, governance guardrails, and change tracking.

What it does

Six focused commands in one tool:

• discover — generate a baseline policy YAML from current RBAC assignments
• scan — detect drift from your declared baseline
• audit — detect forbidden patterns and governance violations
• validate — check policy syntax offline
• snapshot — capture current RBAC state as JSON
• diff — compare snapshots to track changes over time

Neither OPA nor Azure Policy can natively scan Azure RBAC assignments. az-rbac-watch fills that gap with a CLI designed for local use, scheduled checks, and CI/CD pipelines.

Installation

# One-liner bootstrap (installs uv if needed, then puts az-rbac-watch on your PATH)
curl -fsSL https://raw.githubusercontent.com/maxvanp/az-rbac-watch/main/scripts/install.sh | sh

Manual install with uv:

uv tool install az-rbac-watch
uv tool update-shell

Fallback with pipx:

pipx install az-rbac-watch

The bootstrap script can install a compatible Python automatically through uv. You still need Azure CLI for authentication.

Shell completion

Enable tab completion for bash, zsh, or fish:

az-rbac-watch --install-completion

Restart your shell after installation.

Quick start

1. Authenticate

az login

2. Discover existing assignments

# Single subscription
az-rbac-watch discover -t <tenant-id> -s <subscription-id> -o my_policy.yaml

# All accessible scopes
az-rbac-watch discover -t <tenant-id> -o my_policy.yaml

3. Scan for drift (RBAC as Code)

The scan command compares actual RBAC assignments against your baseline rules. Any assignment not covered by a baseline rule is reported as DRIFT.

# Console output
az-rbac-watch scan -p my_policy.yaml

# HTML report
az-rbac-watch scan -p my_policy.yaml -o report.html

# JSON (CI/CD)
az-rbac-watch scan -p my_policy.yaml --format json

4. Audit guardrails (Policy as Code)

The audit command checks governance rules (forbidden patterns). Any assignment matching a governance rule is reported as a violation.

# Console output
az-rbac-watch audit -p my_policy.yaml

# HTML report
az-rbac-watch audit -p my_policy.yaml -o report.html

# JSON (CI/CD)
az-rbac-watch audit -p my_policy.yaml --format json

A starter kit with common governance rules is available in examples/deny_rules_starter.yaml.

4b. Framework compliance (CIS Benchmark)

# Audit with CIS Azure Foundations Benchmark mapping
az-rbac-watch audit -p my_policy.yaml --framework CIS -o compliance.html

# Console summary only
az-rbac-watch audit -p my_policy.yaml --framework CIS

5. Validate policy syntax (offline)

az-rbac-watch validate -p my_policy.yaml

6. Capture RBAC snapshots

# From a policy file
az-rbac-watch snapshot -p my_policy.yaml -o snapshot_2026-03-09.json

# From explicit scopes
az-rbac-watch snapshot -t <tenant-id> -s <subscription-id> -o snapshot.json

7. Compare snapshots (change tracking)

# Console output
az-rbac-watch diff snapshot_old.json snapshot_new.json

# JSON (CI/CD)
az-rbac-watch diff snapshot_old.json snapshot_new.json --format json -o changes.json

Core workflow

Use discover once to capture your current baseline, then run scan and audit continuously. Add snapshot and diff when you want explicit change tracking between two points in time.

Two axes, one tool

You can use both in the same policy file. Each command focuses on its rule type and ignores the other.

Scope modes

The policy model supports two scope modes:

• scope: explicit (default) — only scans subscriptions and management groups listed in the YAML
• scope: all — auto-discovers all accessible scopes at scan time, with optional exclusions

scope: all
exclude_subscriptions:
  - "22222222-2222-2222-2222-222222222222"
exclude_management_groups:
  - "mg-sandbox"

CLI exclusions (--exclude-subscription, --exclude-management-group) apply on top of YAML exclusions.

CLI reference

az-rbac-watch scan

Detects RBAC drift — compares actual state against baseline rules.

az-rbac-watch audit

Checks governance guardrails — evaluates governance rules against actual state.

az-rbac-watch discover

az-rbac-watch validate

az-rbac-watch snapshot

Captures a full RBAC snapshot (assignments + role definitions) as JSON.

az-rbac-watch diff

Compares two snapshots and shows RBAC changes (added, removed, modified assignments).

HTML format is auto-detected when --output ends with .html.

Exit codes

The diff command returns 0 for no changes, 1 for changes detected.

Example CI/CD usage:

# Check drift
az-rbac-watch scan -p policy.yaml --format json -o drift.json
scan_exit=$?

# Check guardrails
az-rbac-watch audit -p policy.yaml --format json -o audit.json
audit_exit=$?

if [ "$scan_exit" -eq 1 ] || [ "$audit_exit" -eq 1 ]; then
  echo "Non-compliant — review reports"
elif [ "$scan_exit" -eq 2 ] || [ "$audit_exit" -eq 2 ]; then
  echo "Scan error — check credentials and permissions"
fi

Troubleshooting

Authentication error

• Run az login to refresh your credentials
• Verify DefaultAzureCredential can authenticate (check AZURE_* env vars or managed identity)

Access denied

• The scanning principal needs Microsoft.Authorization/roleAssignments/read on each scoped subscription/MG
• Check with: az role assignment list --scope /subscriptions/<id> --assignee <principal-id>

Names not resolved (UUIDs shown)

• The App Registration (or user) needs Directory.Read.All permission on Microsoft Graph
• Run with --verbose to see Graph API errors in the logs

Throttling

• Azure ARM API rate-limits parallel requests
• Reduce parallelism: the default is 4 workers (configurable in code via max_workers)
• Wait a few minutes and retry

Full traceback

• Use --debug to see the complete Python traceback on any error

GitHub Actions

Use the composite action to integrate az-rbac-watch into your CI/CD pipelines.

Basic usage

- uses: maxvanp/az-rbac-watch@v0.5.0
  with:
    mode: scan
    policy: policy.yaml
    format: json
    output: report.json

Available modes

Example workflows

Ready-to-use workflow templates are available in examples/workflows/:

• rbac-scheduled-scan.yml — Daily scan + audit with artifact reports
• rbac-pr-check.yml — Validate policy files on pull requests
• rbac-snapshot-diff.yml — Weekly snapshot comparison with change detection

Copy the desired workflow to .github/workflows/ in your repository and configure the required secrets.

Inputs

Outputs

Rule match operators

All comparisons are case-insensitive. Conditions are combined with AND logic.

Name-based operators require Graph API access. If unavailable, they evaluate to false (no false positives).

Required Azure permissions

• Microsoft.Authorization/roleAssignments/read on scanned scopes
• Directory.Read.All (Graph API, for display name resolution)

License

MIT