Azure PIM CLI (azpim)

Una herramienta de línea de comandos para gestionar activaciones de roles de Azure Privileged Identity Management (PIM) directamente desde tu terminal.

Características

• 🔐 Activación de roles - Activa rápidamente roles elegibles de Azure PIM
• 🔓 Desactivación de roles - Desactiva roles activos cuando ya no sean necesarios
• 📋 Menú interactivo - Interfaz amigable basada en menús
• ✨ Interfaz bonita - Experiencia de terminal pulida con spinners y colores
• 🔄 Soporte multirol - Activa o desactiva varios roles a la vez
• 📊 Seguimiento de estado - Retroalimentación en tiempo real sobre el estado de activación/desactivación
• 💾 Presets - Guarda y reutiliza configuraciones de activación/desactivación
• ⭐ Favoritos - Marca suscripciones como favoritas para acceso rápido
• 🗃️ Caché de suscripciones - Caché automática de suscripciones (TTL de 6 horas) para un inicio más rápido
• 🚀 Modo no interactivo - Flags de CLI para scripting y automatización
• 🔔 Notificaciones de actualización - Comprobaciones automáticas de actualizaciones con comportamiento configurable
• 📤 Salida JSON - Salida legible por máquina para integración con otras herramientas
• 👤 Aislamiento de datos por usuario - Configuración y caché almacenadas por ID de usuario de Azure

Requisitos previos

Antes de usar azpim, asegúrate de tener:

1. Node.js (v18 o superior)
2. Azure CLI instalado y configurado
3. Cuenta de Azure con roles elegibles para PIM

Configuración de Azure CLI

# Instalar Azure CLI (si no está instalado)
# Ver: https://docs.microsoft.com/es-es/cli/azure/install-azure-cli

# Iniciar sesión en Azure
az login

# Verificar que has iniciado sesión
az account show

Instalación

Instalación global (recomendada)

# Usando npm
npm install -g azpim

# Usando pnpm
pnpm add -g azpim

# Usando yarn
yarn global add azpim

Después de la instalación, el comando azpim estará disponible globalmente.

Migración desde azp-cli

Si usabas azp-cli anteriormente, tus presets se almacenan en ~/.config/azp-cli/ (o %APPDATA%\azp-cli\ en Windows). Para migrar:

1. Copia tu presets.json a la nueva ubicación: ~/.config/azpim/ (o %APPDATA%\azpim\)
2. Desinstala el paquete antiguo: npm uninstall -g azp-cli

Desde el código fuente (desarrollo)

# Clonar el repositorio
git clone https://github.com/tapanmeena/azpim.git
cd azpim

# Instalar dependencias
pnpm install

# Construir el proyecto
pnpm build

# Enlazar globalmente para desarrollo
npm link

Uso

Ejecutar la CLI

# Después de la instalación global
azpim

# O con comandos específicos
azpim activate
azpim deactivate
azpim preset list
azpim update

# Modo de desarrollo (desde el código fuente)
pnpm dev

Comandos

Flags globales:

• --debug - Habilitar registro de depuración
• --version - Mostrar número de versión

Subcomandos de preset

Subcomandos de favoritos

Actualizaciones

Puedes verificar si hay una versión más reciente disponible:

azpim update
# alias
azpim upgrade

Notas:

• azpim update termina con código 0 si está actualizado, 2 si hay una actualización disponible y 1 en caso de error.
• --check-only - Solo verificar y mostrar el estado sin mostrar instrucciones de actualización.
• --output json devuelve una respuesta estructurada adecuada para scripts.
• Por defecto, azpim activate y azpim deactivate también mostrarán un breve aviso de "actualización disponible" (solo modo texto) como máximo una vez al día.
• Desactiva las comprobaciones de actualización mediante AZPIM_NO_UPDATE_NOTIFIER=1 (o AZPIM_DISABLE_UPDATE_CHECK=1).

La caché de comprobación de actualizaciones se almacena junto con los presets en tu directorio de configuración:

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

Modo no interactivo (automatización)

Usa flags para activar o desactivar roles de PIM directamente sin pasar por el menú interactivo, perfecto para scripting y flujos de trabajo CI/CD.

Ejemplos de activación

# Activar un solo rol por nombre (no interactivo)
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --duration-hours 2 \
   --justification "Break-glass por incidente" \
   --output json

# Activar múltiples roles (repetir --role-name)
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --role-name "User Access Administrator"

# Si un nombre de rol coincide con varios roles elegibles (diferentes ámbitos),
# --non-interactive dará error a menos que permitas explícitamente activar todas las coincidencias
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --allow-multiple

# Vista previa de lo que sucedería sin enviar solicitudes
azpim activate --non-interactive --dry-run \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --output json

Ejemplos de desactivación

# Desactivar roles específicos
azpim deactivate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --justification "Tarea completada"

# Desactivar en todas las suscripciones (omitir subscription-id)
azpim deactivate --non-interactive --yes \
   --role-name "Contributor" \
   --allow-multiple

Flags disponibles

Flags comunes (activate/deactivate):

• --non-interactive - Deshabilitar indicaciones interactivas
• -y, --yes - Omitir indicaciones de confirmación
• --subscription-id <id> - Suscripción objetivo (opcional para deactivate)
• --role-name <name> - Nombre(s) de rol(es) a objetivo (se puede repetir)
• --allow-multiple - Permitir múltiples coincidencias de roles
• --dry-run - Vista previa sin enviar
• --output <text|json> - Formato de salida (predeterminado: text)
• --quiet - Suprimir salida no esencial

Específicos de activación:

• --duration-hours <n> - Duración (1-8 horas, el predeterminado varía según el rol)
• --justification <text> - Justificación para la activación

Específicos de desactivación:

• --justification <text> - Justificación para la desactivación (opcional)

Presets

Los presets te permiten guardar tus rutinas diarias de activación/desactivación (suscripción + nombres de roles + duración + justificación) y reutilizarlas con --preset <name>.

Ubicación del archivo de presets

Por defecto, los presets se almacenan en un archivo de configuración por usuario:

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

Puedes sobrescribir la ubicación con:

• AZPIM_PRESETS_PATH=/ruta/a/presets.json

Contenido de un preset

Un preset puede definir uno o ambos bloques:

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

justification admite plantillas simples:

• ${date} → YYYY-MM-DD
• ${datetime} → Marca de tiempo ISO
• ${userPrincipalName} → resuelto desde Microsoft Graph /me

Flujos de trabajo comunes

# Crear un preset (asistente interactivo)
azpim preset add daily-ops

# Crear un preset con integración de Azure (obtiene suscripciones/roles)
azpim preset add daily-ops --from-azure

# Editar un preset (asistente interactivo)
azpim preset edit daily-ops

# Listar todos los presets
azpim preset list

# Mostrar detalles de un preset
azpim preset show daily-ops

# Eliminar un preset
azpim preset remove daily-ops

# Usar un preset (los flags aún sobrescriben los valores del preset)
azpim activate --preset daily-ops --yes

# Ejecución no interactiva usando el preset
azpim activate --preset daily-ops --non-interactive --yes --output json

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

Predeterminados

Cuando creas un preset mediante azpim preset add, puedes opcionalmente configurarlo como predeterminado para activate y/o deactivate.

• Los presets predeterminados se aplican automáticamente cuando ejecutas flujos de un solo paso y no has proporcionado explícitamente los flags requeridos.
• Ejemplo: después de configurar un preset de activación predeterminado, azpim activate --non-interactive --yes puede funcionar sin especificar --subscription-id/--role-name.

Ejemplo de sesión

╔════════════════════════════════════════════════════╗
║     Azure PIM CLI - Administrador de activación de roles ║
╚════════════════════════════════════════════════════╝

✔ Autenticación exitosa

┌─ Información del usuario ──────────────────────────
│ Nombre: Juan Pérez
│ Correo electrónico: [email protected]
└──────────────────────────────────────────────────────

✔ Se encontraron 3 suscripción(es)

? ¿Qué te gustaría hacer?
❯ ▶ Activar rol(es)
  ◼ Desactivar rol(es)
  ✕ Salir

Flujo de activación de roles

1. Selecciona una suscripción de tus suscripciones de Azure disponibles
2. Elige uno o más roles elegibles para activar
3. Especifica la duración de la activación (1-8 horas)
4. Proporciona una justificación para la activación
5. Confirma y activa

Flujo de desactivación de roles

1. Ver todos los roles actualmente activos en todas las suscripciones
2. Selecciona los roles a desactivar
3. Confirma la desactivación

Favoritos

Los favoritos te permiten marcar suscripciones específicas para acceso rápido. Las suscripciones favoritas se muestran al principio de las listas de suscripciones en el menú interactivo.

Ubicación del archivo de favoritos

Por defecto, los favoritos se almacenan por usuario:

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

Puedes sobrescribir la ubicación con:

• AZPIM_FAVORITES_PATH=/ruta/a/favorites.json

Flujos de trabajo comunes

# Listar todos los favoritos
azpim favorites list
azpim fav list

# Añadir una suscripción a favoritos
azpim favorites add <subscription-id>

# Añadir incluso si la suscripción no está en caché
azpim favorites add <subscription-id> --force

# Eliminar una suscripción de favoritos
azpim favorites remove <subscription-id>

# Borrar todos los favoritos
azpim favorites clear

# Exportar favoritos a un archivo
azpim favorites export ./my-favorites.json

# Importar favoritos desde un archivo (reemplaza los existentes)
azpim favorites import ./my-favorites.json

# Importar favoritos y fusionar con los existentes
azpim favorites import ./my-favorites.json --merge

# Refrescar la caché de suscripciones
azpim favorites refresh

Caché de suscripciones

azpim almacena automáticamente en caché la información de las suscripciones para mejorar el tiempo de inicio. La caché tiene un TTL (tiempo de vida) de 6 horas y se actualiza automáticamente cuando caduca.

Ubicación de la caché

Los archivos de caché se almacenan por usuario:

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

Refrescar la caché

# Forzar el refresco de la caché de suscripciones
azpim favorites refresh

Desarrollo

Scripts disponibles

# Ejecutar en modo desarrollo con recarga en caliente
pnpm dev

# Construir el proyecto TypeScript
pnpm build

# Ejecutar la aplicación compilada
pnpm start

# Verificar el código con linter
pnpm lint

Registro de cambios y releases

Este repositorio usa el formato Keep a Changelog en CHANGELOG.md.

Mensajes de commit recomendados

Para mejores resultados, usa Conventional Commits:

• feat: ... (nueva funcionalidad) → incremento menor
• fix: ... (corrección de error) → incremento de parche
• chore: ..., docs: ..., refactor: ... (sin incremento a menos que sea rupturista)

Crear un release

1. Asegúrate de que CHANGELOG.md tenga entradas actualizadas bajo Unreleased.

2. Ejecuta uno de los siguientes:

# Determina automáticamente la próxima versión a partir de los commits, actualiza CHANGELOG.md,
# incrementa la versión en package.json y crea una etiqueta git.
pnpm release

# Vista previa de lo que cambiaría
pnpm release:dry

# Forzar un incremento específico si es necesario
pnpm release -- --release-as patch
pnpm release -- --release-as minor
pnpm release -- --release-as major

3. Sube los commits + etiquetas:

git push --follow-tags

4. Publica en npm (si se desea):

npm publish
# o
pnpm publish

Estructura del proyecto

azpim/
├── src/
│   ├── index.ts                        # Punto de entrada de la CLI y definiciones de comandos
│   ├── core/                           # Utilidades fundamentales (sin lógica de dominio)
│   │   ├── constants.ts                # Valores mágicos compartidos y predeterminados
│   │   ├── errors.ts                   # Utilidades unificadas de manejo de errores
│   │   ├── json-store.ts              # Persistencia genérica de archivos JSON
│   │   ├── paths.ts                    # Resolución de rutas de archivos de configuración/datos
│   │   └── ui.ts                       # Interfaz de terminal (spinners, formato, colores)
│   ├── azure/                          # Envoltorios del SDK de Azure
│   │   ├── auth.ts                     # Credencial de Azure CLI + búsqueda de Graph /me
│   │   └── azure-pim.ts               # API de activación/desactivación de roles PIM
│   ├── data/                           # Persistencia local de datos
│   │   ├── favorites.ts               # Gestión de favoritos
│   │   ├── presets.ts                  # Configuración y validación de presets
│   │   ├── subscription-cache.ts      # Caché de suscripciones (TTL de 6 horas)
│   │   └── update-check.ts            # Sistema de notificación de actualizaciones
│   └── cli/                            # Flujos interactivos y andamiaje de comandos
│       ├── cli.ts                      # Bucle principal del menú y ayudantes compartidos
│       ├── command-handler.ts         # Envoltorio de comando reutilizable (auth, UI, errores)
│       ├── activate-flow.ts           # Activación de roles (un solo paso + interactivo)
│       ├── deactivate-flow.ts         # Desactivación de roles (un solo paso + interactivo)
│       ├── subscription-selector.ts   # Búsqueda/selección de suscripciones con favoritos
│       ├── favorites-manager.ts       # Menú interactivo de gestión de favoritos
│       └── presets-cli.ts             # Asistentes para añadir/editar/gestionar presets
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── README.md

Arquitectura

El código sigue una estructura de módulos en capas:

• core/ — Utilidades sin dependencias compartidas en todo el proyecto. json-store.ts proporciona un patrón genérico de carga/guardado usado por todos los archivos de persistencia de datos. errors.ts centraliza la extracción de errores y el manejo de errores a nivel de comando. constants.ts elimina los valores mágicos.
• azure/ — Envoltorios ligeros alrededor de los SDK de Azure (@azure/identity, @azure/arm-authorization) y una llamada ligera a Microsoft Graph /me mediante fetch nativo. Sin lógica de UI.
• data/ — Persistencia local de archivos (favoritos, presets, caché de suscripciones, estado de actualizaciones). Todos usan json-store para E/S consistente de archivos.
• cli/ — Flujos interactivos orientados al usuario y andamiaje de comandos. proporciona un envoltorio que elimina el código repetitivo (auth, configuración de UI, manejo de errores) en todos los comandos de Commander. Los flujos de activación y desactivación comparten una función de .

Stack tecnológico

• TypeScript - JavaScript con tipos seguros
• Commander.js - Framework de CLI
• Inquirer.js - Indicaciones interactivas
• Ora - Spinners elegantes para terminal
• Chalk - Estilo de cadenas en terminal
• Azure SDK - Integración con servicios de Azure

Variables de entorno

Solución de problemas

Error "Azure CLI no encontrado"

Asegúrate de que Azure CLI esté instalado y accesible en tu PATH:

az --version

Errores de autenticación

1. Asegúrate de haber iniciado sesión en Azure CLI:

   root@kitploit:~

   az login
   

2. Verifica que tu cuenta tenga roles elegibles para PIM:

   root@kitploit:~

   az account show
   

3. Comprueba si tienes los permisos necesarios en Azure AD

No se encontraron suscripciones

• Verifica que tu cuenta de Azure tenga acceso a suscripciones
• Intenta refrescar tu inicio de sesión en Azure CLI: az login --refresh

Licencia

Este proyecto está licenciado bajo la Licencia ISC.

Autor

Tapan Meena - [email protected]

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

1. Haz un fork del repositorio
2. Crea tu rama de funcionalidad (git checkout -b feature/caracteristica-increible)
3. Realiza tus cambios (git commit -m 'Añadir alguna característica increíble')
4. Sube la rama (git push origin feature/caracteristica-increible)
5. Abre un Pull Request