Azure PIM CLI (azpim)

Ein Kommandozeilen-Tool zur Verwaltung von Azure Privileged Identity Management (PIM)-Rollenaktivierungen direkt von Ihrem Terminal aus.

Funktionen

• 🔐 Rollenaktivierung – Schnelle Aktivierung berechtigter Azure PIM-Rollen
• 🔓 Rollendeaktivierung – Deaktivieren aktiver Rollen, wenn sie nicht mehr benötigt werden
• 📋 Interaktives Menü – Benutzerfreundliche, menügesteuerte Oberfläche
• ✨ Schöne Benutzeroberfläche – Poliertes Terminal-Erlebnis mit Spinnern und Farben
• 🔄 Multi-Rollen-Unterstützung – Mehrere Rollen gleichzeitig aktivieren oder deaktivieren
• 📊 Statusverfolgung – Echtzeit-Feedback zum Aktivierungs-/Deaktivierungsstatus
• 💾 Presets – Speichern und Wiederverwenden von Aktivierungs-/Deaktivierungskonfigurationen
• ⭐ Favoriten – Abonnements als Favoriten markieren für schnellen Zugriff
• 🗃️ Abonnement-Cache – Automatisches Caching von Abonnements (6 Stunden TTL) für schnelleren Start
• 🚀 Nicht-interaktiver Modus – CLI-Flags für Skripterstellung und Automatisierung
• 🔔 Update-Benachrichtigungen – Automatische Update-Prüfungen mit konfigurierbarem Verhalten
• 📤 JSON-Ausgabe – Maschinenlesbare Ausgabe zur Integration mit anderen Tools
• 👤 Pro-Benutzer-Datenisolierung – Konfiguration und Cache werden pro Azure-Benutzer-ID gespeichert

Voraussetzungen

Stellen Sie vor der Verwendung von azpim Folgendes sicher:

1. Node.js (v18 oder höher)
2. Azure CLI installiert und konfiguriert
3. Azure-Konto mit PIM-berechtigten Rollen

Azure CLI Einrichtung

# Azure CLI installieren (falls nicht installiert)
# Siehe: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli

# Bei Azure anmelden
az login

# Überprüfen, ob Sie angemeldet sind
az account show

Installation

Globale Installation (Empfohlen)

# Mit npm
npm install -g azpim

# Mit pnpm
pnpm add -g azpim

# Mit yarn
yarn global add azpim

Nach der Installation steht der Befehl azpim global zur Verfügung.

Migration von azp-cli

Wenn Sie zuvor azp-cli verwendet haben, befinden sich Ihre Presets in ~/.config/azp-cli/ (bzw. %APPDATA%\azp-cli\ unter Windows). So migrieren Sie:

1. Kopieren Sie Ihre presets.json in das neue Verzeichnis: ~/.config/azpim/ (bzw. %APPDATA%\azpim\)
2. Deinstallieren Sie das alte Paket: npm uninstall -g azp-cli

Aus dem Quellcode (Entwicklung)

# Repository klonen
git clone https://github.com/tapanmeena/azpim.git
cd azpim

# Abhängigkeiten installieren
pnpm install

# Projekt erstellen
pnpm build

# Global für die Entwicklung verknüpfen
npm link

Verwendung

Das CLI ausführen

# Nach globaler Installation
azpim

# Oder mit spezifischen Befehlen
azpim activate
azpim deactivate
azpim preset list
azpim update

# Entwicklungsmodus (aus dem Quellcode)
pnpm dev

Befehle

Globale Flags:

• --debug – Debug-Logging aktivieren
• --version – Versionsnummer anzeigen

Preset-Unterbefehle

Favoriten-Unterbefehle

Updates

Sie können prüfen, ob eine neuere Version verfügbar ist:

azpim update
# Alias
azpim upgrade

Hinweise:

• azpim update beendet sich mit Code 0, wenn aktuell, mit 2, wenn ein Update verfügbar ist, und mit 1 bei Fehler.
• --check-only – Nur Status prüfen und anzeigen, ohne Upgrade-Anweisungen.
• --output json liefert eine strukturierte Antwort, die für Skripte geeignet ist.
• Standardmäßig zeigen azpim activate und azpim deactivate ebenfalls einen kurzen "Update verfügbar"-Hinweis (nur Textmodus) höchstens einmal pro Tag an.
• Deaktivieren Sie Update-Prüfungen über AZPIM_NO_UPDATE_NOTIFIER=1 (oder AZPIM_DISABLE_UPDATE_CHECK=1).

Der Update-Check-Cache wird zusammen mit den Presets in Ihrem Konfigurationsverzeichnis gespeichert:

• macOS/Linux: ~/.config/azpim/update-check.json (oder $XDG_CONFIG_HOME/azpim/update-check.json)
• Windows: %APPDATA%\azpim\update-check.json

Nicht-interaktiver Modus (Automatisierung)

Verwenden Sie Flags, um PIM-Rollen direkt ohne das interaktive Menü zu aktivieren oder zu deaktivieren – ideal für Skripterstellung und CI/CD-Workflows.

Aktivierungsbeispiele

# Einzelne Rolle nach Namen aktivieren (nicht-interaktiv)
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --duration-hours 2 \
   --justification "Break-glass für Vorfall" \
   --output json

# Mehrere Rollen aktivieren (--role-name wiederholen)
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --role-name "User Access Administrator"

# Wenn ein Rollenname mehreren berechtigten Rollen (unterschiedliche Bereiche) entspricht,
# führt --non-interactive zu einem Fehler, es sei denn, Sie erlauben explizit die Aktivierung aller Übereinstimmungen
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --allow-multiple

# Vorschau, was passieren würde, ohne Anfragen zu senden
azpim activate --non-interactive --dry-run \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --output json

Deaktivierungsbeispiele

# Bestimmte Rollen deaktivieren
azpim deactivate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --justification "Aufgabe erledigt"

# Über alle Abonnements hinweg deaktivieren (subscription-id weglassen)
azpim deactivate --non-interactive --yes \
   --role-name "Contributor" \
   --allow-multiple

Verfügbare Flags

Gemeinsame Flags (aktivieren/deaktivieren):

• --non-interactive – Interaktive Eingabeaufforderungen deaktivieren
• -y, --yes – Bestätigungsaufforderungen überspringen
• --subscription-id <id> – Zielabonnement (optional bei Deaktivierung)
• --role-name <name> – Zielrollenname(n) (kann wiederholt werden)
• --allow-multiple – Mehrere Rollenübereinstimmungen zulassen
• --dry-run – Vorschau ohne Ausführung
• --output <text|json> – Ausgabeformat (Standard: text)
• --quiet – Nicht wesentliche Ausgabe unterdrücken

Aktivierungsspezifisch:

• --duration-hours <n> – Dauer (1–8 Stunden, Standard variiert je nach Rolle)
• --justification <text> – Begründung für die Aktivierung

Deaktivierungsspezifisch:

• --justification <text> – Begründung für die Deaktivierung (optional)

Presets

Presets ermöglichen es Ihnen, Ihre täglichen Aktivierungs-/Deaktivierungsroutinen (Abonnement + Rollennamen + Dauer + Begründung) zu speichern und mit --preset <name> wiederzuverwenden.

Speicherort der Presets

Standardmäßig werden Presets in einer benutzerspezifischen Konfigurationsdatei gespeichert:

• macOS/Linux: ~/.config/azpim/presets.json (oder $XDG_CONFIG_HOME/azpim/presets.json)
• Windows: %APPDATA%\azpim\presets.json

Überschreiben Sie den Speicherort mit:

• AZPIM_PRESETS_PATH=/pfad/zu/presets.json

Inhalt der Presets

Ein Preset kann einen oder beide Blöcke definieren:

• activate: subscriptionId, roleNames[], durationHours, justification, allowMultiple
• deactivate: subscriptionId (optional), roleNames[], justification, allowMultiple

justification unterstützt einfache Vorlagen:

• ${date} → YYYY-MM-DD
• ${datetime} → ISO-Zeitstempel
• ${userPrincipalName} – aufgelöst über Microsoft Graph /me

Übliche Workflows

# Preset erstellen (interaktiver Assistent)
azpim preset add daily-ops

# Preset mit Azure-Integration erstellen (holt Abonnements/Rollen)
azpim preset add daily-ops --from-azure

# Preset bearbeiten (interaktiver Assistent)
azpim preset edit daily-ops

# Alle Presets auflisten
azpim preset list

# Details eines Presets anzeigen
azpim preset show daily-ops

# Preset entfernen
azpim preset remove daily-ops

# Preset verwenden (Flags überschreiben weiterhin Preset-Werte)
azpim activate --preset daily-ops --yes

# Nicht-interaktiver Lauf mit dem Preset
azpim activate --preset daily-ops --non-interactive --yes --output json

# Deaktivierung mit einem Preset
azpim deactivate --preset daily-ops --non-interactive --yes

Standard-Presets

Wenn Sie ein Preset über azpim preset add erstellen, können Sie es optional als Standard für activate und/oder deactivate festlegen.

• Standard-Presets werden automatisch angewendet, wenn Sie einen One-Shot-Flow ausführen und die erforderlichen Flags nicht explizit angegeben haben.
• Beispiel: Nach dem Festlegen eines Standard-Aktivierungs-Presets kann azpim activate --non-interactive --yes funktionieren, ohne --subscription-id/--role-name anzugeben.

Beispiel-Sitzung

╔════════════════════════════════════════════════════╗
║     Azure PIM CLI - Rollenaktivierungsmanager       ║
╚════════════════════════════════════════════════════╝

✔ Authentifizierung erfolgreich

┌─ Benutzerinformationen ─────────────────────────────
│ Name: Max Mustermann
│ E-Mail: [email protected]
└──────────────────────────────────────────────────────

✔ 3 Abonnement(s) gefunden

? Was möchten Sie tun?
❯ ▶ Rolle(n) aktivieren
  ◼ Rolle(n) deaktivieren
  ✕ Beenden

Rollenaktivierungs-Ablauf

1. Wählen Sie ein Abonnement aus Ihren verfügbaren Azure-Abonnements aus
2. Wählen Sie eine oder mehrere berechtigte Rollen zur Aktivierung aus
3. Geben Sie die Aktivierungsdauer an (1–8 Stunden)
4. Geben Sie eine Begründung für die Aktivierung an
5. Bestätigen und aktivieren

Rollendeaktivierungs-Ablauf

1. Alle aktuell aktiven Rollen über Abonnements hinweg anzeigen
2. Zu deaktivierende Rollen auswählen
3. Deaktivierung bestätigen

Favoriten

Favoriten ermöglichen es Ihnen, bestimmte Abonnements für den schnellen Zugriff zu markieren. Favoriten-Abonnements werden im interaktiven Menü oben in der Abonnementliste angezeigt.

Speicherort der Favoriten

Standardmäßig werden Favoriten benutzerspezifisch gespeichert:

• macOS/Linux: ~/.config/azpim/users/<userId>/favorites.json
• Windows: %APPDATA%\azpim\users\<userId>\favorites.json

Überschreiben Sie den Speicherort mit:

• AZPIM_FAVORITES_PATH=/pfad/zu/favorites.json

Übliche Workflows

# Alle Favoriten auflisten
azpim favorites list
azpim fav list

# Abonnement zu Favoriten hinzufügen
azpim favorites add <subscription-id>

# Hinzufügen, auch wenn das Abonnement nicht im Cache ist
azpim favorites add <subscription-id> --force

# Abonnement aus Favoriten entfernen
azpim favorites remove <subscription-id>

# Alle Favoriten löschen
azpim favorites clear

# Favoriten in eine Datei exportieren
azpim favorites export ./my-favorites.json

# Favoriten aus einer Datei importieren (ersetzt vorhandene)
azpim favorites import ./my-favorites.json

# Favoriten importieren und mit vorhandenen zusammenführen
azpim favorites import ./my-favorites.json --merge

# Abonnement-Cache aktualisieren
azpim favorites refresh

Abonnement-Cache

azpim speichert Abonnementinformationen automatisch zwischen, um die Startzeit zu verbessern. Der Cache hat eine TTL (Time-to-Live) von 6 Stunden und wird bei Ablauf automatisch aktualisiert.

Speicherort des Caches

Cache-Dateien werden benutzerspezifisch gespeichert:

• macOS/Linux: ~/.config/azpim/users/<userId>/subscriptions-cache.json
• Windows: %APPDATA%\azpim\users\<userId>\subscriptions-cache.json

Cache aktualisieren

# Cache des Abonnement-Cache erzwingen
azpim favorites refresh

Entwicklung

Verfügbare Skripte

# Im Entwicklungsmodus mit Hot-Reload ausführen
pnpm dev

# TypeScript-Projekt erstellen
pnpm build

# Erstellte Anwendung ausführen
pnpm start

# Codebasis linten
pnpm lint

Changelog und Releases

Dieses Repository verwendet das Keep a Changelog-Format in CHANGELOG.md.

Empfohlene Commit-Nachrichten

Für beste Ergebnisse verwenden Sie Conventional Commits:

• feat: ... (neue Funktion) → Minor-Bump
• fix: ... (Fehlerbehebung) → Patch-Bump
• chore: ..., docs: ..., refactor: ... (kein Bump, es sei denn, es ist ein Breaking Change)

Ein Release erstellen

1. Stellen Sie sicher, dass CHANGELOG.md aktuelle Einträge unter Unreleased enthält.

2. Führen Sie einen der folgenden Befehle aus:

# Ermittelt automatisch die nächste Version aus Commits, aktualisiert CHANGELOG.md,
# erhöht die Version in package.json und erstellt einen Git-Tag.
pnpm release

# Vorschau, was sich ändern würde
pnpm release:dry

# Erzwingen eines bestimmten Bumps, falls erforderlich
pnpm release -- --release-as patch
pnpm release -- --release-as minor
pnpm release -- --release-as major

3. Pushen Sie Commits + Tags:

git push --follow-tags

4. Auf npm veröffentlichen (falls gewünscht):

npm publish
# oder
pnpm publish

Projektstruktur

azpim/
├── src/
│   ├── index.ts                        # CLI-Einstiegspunkt und Befehlsdefinitionen
│   ├── core/                           # Grundlegende Hilfsprogramme (keine Domänenlogik)
│   │   ├── constants.ts                # Gemeinsame magische Werte und Standardwerte
│   │   ├── errors.ts                   # Einheitliche Fehlerbehandlung
│   │   ├── json-store.ts              # Generische JSON-Datei-Persistenz
│   │   ├── paths.ts                    # Auflösung von Konfigurations-/Daten-Dateipfaden
│   │   └── ui.ts                       # Terminal-UI (Spinner, Formatierung, Farben)
│   ├── azure/                          # Azure SDK-Wrapper
│   │   ├── auth.ts                     # Azure CLI-Anmeldeinformationen + Graph-/me-Abfrage
│   │   └── azure-pim.ts               # PIM-Rollenaktivierungs-/Deaktivierungs-API
│   ├── data/                           # Lokale Datenpersistenz
│   │   ├── favorites.ts               # Favoritenverwaltung
│   │   ├── presets.ts                  # Preset-Konfiguration und -Validierung
│   │   ├── subscription-cache.ts      # Abonnement-Caching (6 Stunden TTL)
│   │   └── update-check.ts            # Update-Benachrichtigungssystem
│   └── cli/                            # Interaktive Abläufe und Befehlsgerüste
│       ├── cli.ts                      # Hauptmenü-Schleife und gemeinsame Helfer
│       ├── command-handler.ts         # Wiederverwendbarer Befehls-Wrapper (Auth, UI, Fehler)
│       ├── activate-flow.ts           # Rollenaktivierung (one-shot + interaktiv)
│       ├── deactivate-flow.ts         # Rollendeaktivierung (one-shot + interaktiv)
│       ├── subscription-selector.ts   # Abonnementsuche/-auswahl mit Favoriten
│       ├── favorites-manager.ts       # Interaktives Favoritenverwaltungsmenü
│       └── presets-cli.ts             # Assistenten zum Hinzufügen/Bearbeiten/Verwalten von Presets
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── README.md

Architektur

Die Codebasis folgt einer geschichteten Modulstruktur:

• core/ – Null-Abhängigkeits-Hilfsprogramme, die im gesamten Projekt gemeinsam genutzt werden. json-store.ts bietet ein generisches Lade-/Speichermuster, das von allen Datenpersistenzdateien verwendet wird. errors.ts zentralisiert die Fehlererkennung und die Fehlerbehandlung auf BefehlsEbene. constants.ts eliminiert magische Werte.
• azure/ – Dünne Wrapper um Azure SDKs (@azure/identity, @azure/arm-authorization) und einen leichten Microsoft Graph /me-Aufruf über natives fetch. Keine UI-Logik.
• data/ – Lokale Dateipersistenz (Favoriten, Presets, Abonnement-Cache, Update-Status). Alle verwenden json-store für konsistentes Datei-I/O.
• cli/ – Benutzerorientierte interaktive Abläufe und Befehlsgerüste. stellt einen -Wrapper bereit, der Boilerplate (Auth, UI-Einrichtung, Fehlerbehandlung) für alle Commander-Befehle eliminiert. Aktivierungs- und Deaktivierungsabläufe teilen sich eine -Funktion aus .

Technologie-Stack

• TypeScript – Typsicheres JavaScript
• Commander.js – CLI-Framework
• Inquirer.js – Interaktive Eingabeaufforderungen
• Ora – Elegante Terminal-Spinner
• Chalk – Terminal-String-Styling
• Azure SDK – Azure-Dienstintegration

Umgebungsvariablen

Fehlerbehebung

Fehler "Azure CLI nicht gefunden"

Stellen Sie sicher, dass die Azure CLI installiert und im PATH verfügbar ist:

az --version

Authentifizierungsfehler

1. Stellen Sie sicher, dass Sie bei der Azure CLI angemeldet sind:

   root@kitploit:~

   az login
   

2. Überprüfen Sie, ob Ihr Konto über PIM-berechtigte Rollen verfügt:

   root@kitploit:~

   az account show
   

3. Prüfen Sie, ob Sie die erforderlichen Berechtigungen in Azure AD haben

Keine Abonnements gefunden

• Überprüfen Sie, ob Ihr Azure-Konto Zugriff auf Abonnements hat
• Versuchen Sie, Ihre Azure CLI-Anmeldung zu aktualisieren: az login --refresh

Lizenz

Dieses Projekt ist unter der ISC-Lizenz lizenziert.

Autor

Tapan Meena – [email protected]

Mitwirken

Beiträge sind willkommen! Bitte zögern Sie nicht, einen Pull-Request zu erstellen.

1. Forken Sie das Repository
2. Erstellen Sie einen Feature-Branch (git checkout -b feature/amazing-feature)
3. Committen Sie Ihre Änderungen (git commit -m 'Füge eine tolle Funktion hinzu')
4. Pushen Sie den Branch (git push origin feature/amazing-feature)
5. Öffnen Sie einen Pull-Request