Azure PIM CLI (azpim)

Uno strumento a riga di comando per gestire le attivazioni dei ruoli di Azure Privileged Identity Management (PIM) direttamente dal tuo terminale.

Funzionalità

• 🔐 Attivazione dei ruoli - Attiva rapidamente i ruoli Azure PIM idonei
• 🔓 Disattivazione dei ruoli - Disattiva i ruoli attivi quando non sono più necessari
• 📋 Menu interattivo - Interfaccia intuitiva basata su menu
• ✨ Interfaccia utente curata - Esperienza terminale raffinata con spinner e colori
• 🔄 Supporto multi-ruolo - Attiva o disattiva più ruoli contemporaneamente
• 📊 Monitoraggio dello stato - Feedback in tempo reale sullo stato di attivazione/disattivazione
• 💾 Preset - Salva e riutilizza configurazioni di attivazione/disattivazione
• ⭐ Preferiti - Contrassegna le sottoscrizioni come preferite per un accesso rapido
• 🗃️ Cache delle sottoscrizioni - Memorizzazione automatica delle sottoscrizioni (TTL di 6 ore) per un avvio più rapido
• 🚀 Modalità non interattiva - Flag da riga di comando per scripting e automazione
• 🔔 Notifiche di aggiornamento - Controllo automatico degli aggiornamenti con comportamento configurabile
• 📤 Output JSON - Output leggibile dalle macchine per l'integrazione con altri strumenti
• 👤 Isolamento dati per utente - Configurazione e cache archiviate per ID utente Azure

Prerequisiti

Prima di utilizzare azpim, assicurati di avere:

1. Node.js (versione 18 o successiva)
2. Interfaccia a riga di comando di Azure (Azure CLI) installata e configurata
3. Account Azure con ruoli idonei per PIM

Configurazione dell'interfaccia a riga di comando di Azure

# Installa l'interfaccia a riga di comando di Azure (se non installata)
# Vedi: https://docs.microsoft.com/it-it/cli/azure/install-azure-cli

# Accedi ad Azure
az login

# Verifica di aver effettuato l'accesso
az account show

Installazione

Installazione globale (consigliata)

# Usando npm
npm install -g azpim

# Usando pnpm
pnpm add -g azpim

# Usando yarn
yarn global add azpim

Dopo l'installazione, il comando azpim sarà disponibile globalmente.

Migrazione da azp-cli

Se in precedenza utilizzavi azp-cli, i tuoi preset sono memorizzati in ~/.config/azp-cli/ (o %APPDATA%\azp-cli\ su Windows). Per migrare:

1. Copia il tuo presets.json nella nuova posizione: ~/.config/azpim/ (o %APPDATA%\azpim\)
2. Disinstalla il vecchio pacchetto: npm uninstall -g azp-cli

Dal sorgente (Sviluppo)

# Clona il repository
git clone https://github.com/tapanmeena/azpim.git
cd azpim

# Installa le dipendenze
pnpm install

# Compila il progetto
pnpm build

# Collega globalmente per lo sviluppo
npm link

Utilizzo

Esecuzione dell'interfaccia a riga di comando

# Dopo l'installazione globale
azpim

# Oppure con comandi specifici
azpim activate
azpim deactivate
azpim preset list
azpim update

# Modalità sviluppo (dal sorgente)
pnpm dev

Comandi

Flag globali:

• --debug - Abilita la registrazione di debug
• --version - Mostra il numero di versione

Sottocomandi dei preset

Sottocomandi dei preferiti

Aggiornamenti

Puoi verificare se è disponibile una versione più recente:

azpim update
# alias
azpim upgrade

Note:

• azpim update termina con codice 0 se aggiornato, 2 se è disponibile un aggiornamento e 1 in caso di errore.
• --check-only - Controlla e stampa solo lo stato senza mostrare le istruzioni di aggiornamento.
• --output json restituisce una risposta strutturata adatta agli script.
• Per impostazione predefinita, azpim activate e azpim deactivate mostreranno anche un breve suggerimento "aggiornamento disponibile" (solo in modalità testo) al massimo una volta al giorno.
• Disabilita i controlli di aggiornamento tramite AZPIM_NO_UPDATE_NOTIFIER=1 (o AZPIM_DISABLE_UPDATE_CHECK=1).

La cache del controllo aggiornamenti è memorizzata insieme ai preset nella directory di configurazione:

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

Modalità non interattiva (Automazione)

Usa i flag per attivare o disattivare i ruoli PIM direttamente senza passare attraverso il menu interattivo, perfetto per script e flussi di lavoro CI/CD.

Esempi di attivazione

# Attiva un singolo ruolo per nome (non interattivo)
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --duration-hours 2 \
   --justification "Break-glass per incidente" \
   --output json

# Attiva più ruoli (ripeti --role-name)
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --role-name "User Access Administrator"

# Se un nome ruolo corrisponde a più ruoli idonei (ambiti diversi),
# --non-interactive darà errore a meno che non si consenta esplicitamente l'attivazione di tutte le corrispondenze
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --allow-multiple

# Anteprima di cosa accadrebbe senza inviare richieste
azpim activate --non-interactive --dry-run \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --output json

Esempi di disattivazione

# Disattiva ruoli specifici
azpim deactivate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --justification "Attività completata"

# Disattiva su tutte le sottoscrizioni (ometti subscription-id)
azpim deactivate --non-interactive --yes \
   --role-name "Contributor" \
   --allow-multiple

Flag disponibili

Flag comuni (attivazione/disattivazione):

• --non-interactive - Disabilita i prompt interattivi
• -y, --yes - Salta i prompt di conferma
• --subscription-id <id> - Sottoscrizione di destinazione (opzionale per la disattivazione)
• --role-name <nome> - Nome/i del ruolo da destinare (ripetibile)
• --allow-multiple - Consente corrispondenze multiple di ruoli
• --dry-run - Anteprima senza inviare
• --output <text|json> - Formato di output (predefinito: text)
• --quiet - Sopprime output non essenziali

Specifici per l'attivazione:

• --duration-hours <n> - Durata (1-8 ore, predefinito varia per ruolo)
• --justification <testo> - Motivazione per l'attivazione

Specifici per la disattivazione:

• --justification <testo> - Motivazione per la disattivazione (opzionale)

Preset

I preset ti permettono di salvare le tue routine quotidiane di attivazione/disattivazione (sottoscrizione + nomi ruoli + durata + motivazione) e riutilizzarle con --preset <nome>.

Posizione del file dei preset

Per impostazione predefinita, i preset sono memorizzati in un file di configurazione per utente:

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

Sovrascrivi la posizione con:

• AZPIM_PRESETS_PATH=/percorso/del/presets.json

Contenuto dei preset

Un preset può definire uno o entrambi i blocchi:

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

justification supporta semplici template:

• ${date} → YYYY-MM-DD
• ${datetime} → timestamp ISO
• ${userPrincipalName} → risolto da Microsoft Graph /me

Flussi di lavoro comuni

# Crea un preset (procedura guidata interattiva)
azpim preset add daily-ops

# Crea un preset con integrazione Azure (recupera sottoscrizioni/ruoli)
azpim preset add daily-ops --from-azure

# Modifica un preset (procedura guidata interattiva)
azpim preset edit daily-ops

# Elenca tutti i preset
azpim preset list

# Mostra i dettagli di un preset
azpim preset show daily-ops

# Rimuovi un preset
azpim preset remove daily-ops

# Usa un preset (i flag sovrascrivono comunque i valori del preset)
azpim activate --preset daily-ops --yes

# Esecuzione non interattiva usando il preset
azpim activate --preset daily-ops --non-interactive --yes --output json

# Disattiva usando un preset
azpim deactivate --preset daily-ops --non-interactive --yes

Predefiniti

Quando crei un preset tramite azpim preset add, puoi opzionalmente impostarlo come predefinito per activate e/o deactivate.

• I preset predefiniti vengono applicati automaticamente quando esegui flussi one-shot e non hai fornito esplicitamente i flag necessari.
• Esempio: dopo aver impostato un preset di attivazione predefinito, azpim activate --non-interactive --yes può funzionare senza specificare --subscription-id/--role-name.

Esempio di sessione

╔════════════════════════════════════════════════════╗
║     Azure PIM CLI - Gestore attivazione ruoli      ║
╚════════════════════════════════════════════════════╝

✔ Autenticazione riuscita

┌─ Informazioni utente ────────────────────────────────
│ Nome: Mario Rossi
│ Email: [email protected]
└──────────────────────────────────────────────────────

✔ Trovate 3 sottoscrizione(i)

? Cosa desideri fare?
❯ ▶ Attiva ruolo(i)
  ◼ Disattiva ruolo(i)
  ✕ Esci

Flusso di attivazione del ruolo

1. Seleziona una sottoscrizione tra le tue sottoscrizioni Azure disponibili
2. Scegli uno o più ruoli idonei da attivare
3. Specifica la durata dell'attivazione (1-8 ore)
4. Fornisci una motivazione per l'attivazione
5. Conferma e attiva

Flusso di disattivazione del ruolo

1. Visualizza tutti i ruoli attualmente attivi su tutte le sottoscrizioni
2. Seleziona i ruoli da disattivare
3. Conferma la disattivazione

Preferiti

I preferiti ti consentono di contrassegnare sottoscrizioni specifiche per un accesso rapido. Le sottoscrizioni preferite vengono visualizzate all'inizio degli elenchi delle sottoscrizioni nel menu interattivo.

Posizione del file dei preferiti

Per impostazione predefinita, i preferiti sono memorizzati per utente:

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

Sovrascrivi la posizione con:

• AZPIM_FAVORITES_PATH=/percorso/del/favorites.json

Flussi di lavoro comuni

# Elenca tutti i preferiti
azpim favorites list
azpim fav list

# Aggiungi una sottoscrizione ai preferiti
azpim favorites add <subscription-id>

# Aggiungi anche se la sottoscrizione non è in cache
azpim favorites add <subscription-id> --force

# Rimuovi una sottoscrizione dai preferiti
azpim favorites remove <subscription-id>

# Cancella tutti i preferiti
azpim favorites clear

# Esporta i preferiti in un file
azpim favorites export ./my-favorites.json

# Importa i preferiti da un file (sostituisce quelli esistenti)
azpim favorites import ./my-favorites.json

# Importa i preferiti e unisci con quelli esistenti
azpim favorites import ./my-favorites.json --merge

# Aggiorna la cache delle sottoscrizioni
azpim favorites refresh

Cache delle sottoscrizioni

azpim memorizza automaticamente nella cache le informazioni sulle sottoscrizioni per migliorare i tempi di avvio. La cache ha un TTL (time-to-live) di 6 ore e viene aggiornata automaticamente alla scadenza.

Posizione della cache

I file della cache sono memorizzati per utente:

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

Aggiornamento della cache

# Forza l'aggiornamento della cache delle sottoscrizioni
azpim favorites refresh

Sviluppo

Script disponibili

# Esegui in modalità sviluppo con ricarica a caldo
pnpm dev

# Compila il progetto TypeScript
pnpm build

# Esegui l'applicazione compilata
pnpm start

# Lint del codice
pnpm lint

Changelog e rilasci

Questo repository utilizza il formato Keep a Changelog in CHANGELOG.md.

Messaggi di commit consigliati

Per ottenere i migliori risultati, utilizza i Conventional Commits:

• feat: ... (nuova funzionalità) → incremento minor
• fix: ... (correzione bug) → incremento patch
• chore: ..., docs: ..., refactor: ... (nessun incremento a meno che non sia breaking)

Creazione di un rilascio

1. Assicurati che CHANGELOG.md contenga voci aggiornate sotto Unreleased.

2. Esegui uno dei seguenti comandi:

# Determina automaticamente la versione successiva dai commit, aggiorna CHANGELOG.md,
# incrementa package.json e crea un tag git.
pnpm release

# Anteprima di cosa cambierebbe
pnpm release:dry

# Forza un incremento specifico se necessario
pnpm release -- --release-as patch
pnpm release -- --release-as minor
pnpm release -- --release-as major

3. Invia commit + tag:

git push --follow-tags

4. Pubblica su npm (se desiderato):

npm publish
# oppure
pnpm publish

Struttura del progetto

azpim/
├── src/
│   ├── index.ts                        # Punto di ingresso CLI e definizioni dei comandi
│   ├── core/                           # Utilità fondamentali (nessuna logica di dominio)
│   │   ├── constants.ts                # Valori magici e predefiniti condivisi
│   │   ├── errors.ts                   # Utilità unificate per la gestione degli errori
│   │   ├── json-store.ts              # Persistenza generica di file JSON
│   │   ├── paths.ts                    # Risoluzione dei percorsi dei file di configurazione/dati
│   │   └── ui.ts                       # Interfaccia utente terminale (spinner, formattazione, colori)
│   ├── azure/                          # Wrapper dell'SDK Azure
│   │   ├── auth.ts                     # Credenziali CLI Azure + ricerca Graph /me
│   │   └── azure-pim.ts               # API di attivazione/disattivazione ruolo PIM
│   ├── data/                           # Persistenza locale dei dati
│   │   ├── favorites.ts               # Gestione preferiti
│   │   ├── presets.ts                  # Configurazione e validazione dei preset
│   │   ├── subscription-cache.ts      # Cache delle sottoscrizioni (TTL 6 ore)
│   │   └── update-check.ts            # Sistema di notifica aggiornamenti
│   └── cli/                            # Flussi interattivi e scaffolding dei comandi
│       ├── cli.ts                      # Ciclo principale del menu e helper condivisi
│       ├── command-handler.ts         # Wrapper comandi riutilizzabile (autenticazione, UI, errori)
│       ├── activate-flow.ts           # Attivazione ruolo (one-shot + interattivo)
│       ├── deactivate-flow.ts         # Disattivazione ruolo (one-shot + interattivo)
│       ├── subscription-selector.ts   # Ricerca/selezione sottoscrizione con preferiti
│       ├── favorites-manager.ts       # Menu interattivo di gestione preferiti
│       └── presets-cli.ts             # Procedure guidate per aggiungere/modificare/gestire preset
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── README.md

Architettura

Il codebase segue una struttura modulare a livelli:

• core/ — Utilità a zero dipendenze condivise in tutto il progetto. json-store.ts fornisce un pattern generico di carico/salvataggio utilizzato da tutti i file di persistenza dei dati. errors.ts centralizza l'estrazione degli errori e la gestione degli errori a livello di comando. constants.ts elimina i valori magici.
• azure/ — Wrapper sottili intorno agli SDK Azure (@azure/identity, @azure/arm-authorization) e una chiamata leggera a Microsoft Graph /me tramite fetch nativo. Nessuna logica UI.
• data/ — Persistenza locale dei file (preferiti, preset, cache delle sottoscrizioni, stato aggiornamenti). Tutti utilizzano json-store per I/O file coerente.
• cli/ — Flussi interattivi orientati all'utente e scaffolding dei comandi. fornisce un wrapper che elimina il codice boilerplate (autenticazione, configurazione UI, gestione errori) in tutti i comandi Commander. I flussi di attivazione e disattivazione condividono una funzione da .

Stack tecnologico

• TypeScript - JavaScript type-safe
• Commander.js - Framework CLI
• Inquirer.js - Prompt interattivi
• Ora - Spinner terminali eleganti
• Chalk - Styling delle stringhe nel terminale
• Azure SDK - Integrazione con i servizi Azure

Variabili d'ambiente

Risoluzione dei problemi

Errore "Azure CLI non trovato"

Assicurati che l'interfaccia a riga di comando di Azure sia installata e accessibile nel tuo PATH:

az --version

Errori di autenticazione

1. Assicurati di aver effettuato l'accesso all'interfaccia a riga di comando di Azure:

   root@kitploit:~

   az login
   

2. Verifica che il tuo account abbia ruoli idonei per PIM:

   root@kitploit:~

   az account show
   

3. Controlla di avere le autorizzazioni necessarie in Azure AD

Nessuna sottoscrizione trovata

• Verifica che il tuo account Azure abbia accesso alle sottoscrizioni
• Prova ad aggiornare l'accesso all'interfaccia a riga di comando di Azure: az login --refresh

Licenza

Questo progetto è concesso in licenza con la licenza ISC.

Autore

Tapan Meena - [email protected]

Contributi

I contributi sono benvenuti! Sentiti libero di inviare una Pull Request.

1. Fai un fork del repository
2. Crea il tuo branch per la funzionalità (git checkout -b feature/funzionalità-straordinaria)
3. Esegui il commit delle modifiche (git commit -m 'Aggiungi una funzionalità straordinaria')
4. Invia il branch (git push origin feature/funzionalità-straordinaria)
5. Apri una Pull Request