Azure PIM CLI (azpim)

Инструмент командной строки для управления активацией ролей Azure Privileged Identity Management (PIM) непосредственно из терминала.

Возможности

• 🔐 Активация ролей — Быстрая активация доступных ролей Azure PIM
• 🔓 Деактивация ролей — Деактивация активных ролей, когда они больше не нужны
• 📋 Интерактивное меню — Удобный интерфейс с управлением через меню
• ✨ Красивый интерфейс — Полированный терминальный опыт с индикаторами и цветами
• 🔄 Поддержка нескольких ролей — Одновременная активация или деактивация нескольких ролей
• 📊 Отслеживание статуса — Обратная связь в реальном времени о статусе активации/деактивации
• 💾 Пресеты — Сохранение и повторное использование конфигураций активации/деактивации
• ⭐ Избранное — Пометка подписок как избранных для быстрого доступа
• 🗃️ Кэш подписок — Автоматическое кэширование подписок (TTL 6 часов) для ускорения запуска
• 🚀 Неинтерактивный режим — Флаги CLI для скриптов и автоматизации
• 🔔 Уведомления об обновлениях — Автоматическая проверка обновлений с настраиваемым поведением
• 📤 JSON-вывод — Машиночитаемый вывод для интеграции с другими инструментами
• 👤 Изоляция данных по пользователям — Конфигурация и кэш хранятся отдельно для каждого ID пользователя Azure

Предварительные требования

Перед использованием azpim убедитесь, что у вас есть:

1. Node.js (версия 18 или выше)
2. Azure CLI установлен и настроен
3. Учётная запись Azure с ролями, доступными для PIM

Настройка Azure CLI

# Установка Azure CLI (если не установлен)
# См.: https://docs.microsoft.com/ru-ru/cli/azure/install-azure-cli

# Вход в Azure
az login

# Проверка, что вы вошли
az account show

Установка

Глобальная установка (рекомендуется)

# С помощью npm
npm install -g azpim

# С помощью pnpm
pnpm add -g azpim

# С помощью yarn
yarn global add azpim

После установки команда azpim будет доступна глобально.

Миграция с azp-cli

Если вы ранее использовали azp-cli, ваши пресеты хранятся в ~/.config/azp-cli/ (или %APPDATA%\azp-cli\ в Windows). Для миграции:

1. Скопируйте presets.json в новое расположение: ~/.config/azpim/ (или %APPDATA%\azpim\)
2. Удалите старый пакет: npm uninstall -g azp-cli

Из исходников (разработка)

# Клонирование репозитория
git clone https://github.com/tapanmeena/azpim.git
cd azpim

# Установка зависимостей
pnpm install

# Сборка проекта
pnpm build

# Создание глобальной ссылки для разработки
npm link

Использование

Запуск CLI

# После глобальной установки
azpim

# Или с конкретными командами
azpim activate
azpim deactivate
azpim preset list
azpim update

# Режим разработки (из исходников)
pnpm dev

Команды

Глобальные флаги:

• --debug — Включить отладочное логирование
• --version — Показать номер версии

Подкоманды preset

Подкоманды favorites

Обновления

Вы можете проверить, доступна ли новая версия:

azpim update
# псевдоним
azpim upgrade

Примечания:

• azpim update завершается с кодом 0, если версия актуальна, 2, если доступно обновление, и 1 при ошибке.
• --check-only — Только проверить и показать статус без инструкций по обновлению.
• --output json возвращает структурированный ответ, подходящий для скриптов.
• По умолчанию azpim activate и azpim deactivate также будут показывать краткое уведомление о доступном обновлении (только в текстовом режиме) не чаще одного раза в день.
• Отключите проверку обновлений через AZPIM_NO_UPDATE_NOTIFIER=1 (или AZPIM_DISABLE_UPDATE_CHECK=1).

Кэш проверки обновлений хранится вместе с пресетами в вашем каталоге конфигурации:

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

Неинтерактивный режим (автоматизация)

Используйте флаги для активации или деактивации PIM-ролей напрямую, без интерактивного меню — идеально для скриптов и CI/CD.

Примеры активации

# Активация одной роли по имени (неинтерактивно)
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --duration-hours 2 \
   --justification "Break-glass for incident" \
   --output json

# Активация нескольких ролей (повторите --role-name)
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --role-name "User Access Administrator"

# Если имя роли совпадает с несколькими доступными ролями (разные области),
# --non-interactive выдаст ошибку, если явно не разрешить активацию всех совпадений
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --allow-multiple

# Предварительный просмотр того, что произойдёт, без отправки запросов
azpim activate --non-interactive --dry-run \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --output json

Примеры деактивации

# Деактивация конкретных ролей
azpim deactivate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --justification "Task completed"

# Деактивация по всем подпискам (опустите subscription-id)
azpim deactivate --non-interactive --yes \
   --role-name "Contributor" \
   --allow-multiple

Доступные флаги

Общие флаги (activate/deactivate):

• --non-interactive — Отключить интерактивные подсказки
• -y, --yes — Пропустить подтверждения
• --subscription-id <id> — Целевая подписка (необязательно для deactivate)
• --role-name <name> — Имя(имена) ролей (можно повторять)
• --allow-multiple — Разрешить несколько совпадений ролей
• --dry-run — Предварительный просмотр без отправки
• --output <text|json> — Формат вывода (по умолчанию text)
• --quiet — Подавить необязательный вывод

Специфичные для активации:

• --duration-hours <n> — Длительность (1–8 часов, по умолчанию зависит от роли)
• --justification <text> — Обоснование активации

Специфичные для деактивации:

• --justification <text> — Обоснование деактивации (необязательно)

Пресеты

Пресеты позволяют сохранять ваши ежедневные процедуры активации/деактивации (подписка + имена ролей + длительность + обоснование) и повторно использовать их с --preset <имя>.

Расположение файла пресетов

По умолчанию пресеты хранятся в отдельном для каждого пользователя файле:

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

Переопределите расположение с помощью:

• AZPIM_PRESETS_PATH=/путь/к/presets.json

Содержимое пресета

Пресет может определять один или оба блока:

• activate: subscriptionId, roleNames[], durationHours, justification, allowMultiple
• deactivate: subscriptionId (необязательно), roleNames[], justification, allowMultiple

justification поддерживает простые шаблоны:

• ${date} → YYYY-MM-DD
• ${datetime} → метка времени ISO
• ${userPrincipalName} — получается из Microsoft Graph /me

Типичные рабочие процессы

# Создание пресета (интерактивный мастер)
azpim preset add daily-ops

# Создание пресета с интеграцией Azure (загружает подписки/роли)
azpim preset add daily-ops --from-azure

# Редактирование пресета (интерактивный мастер)
azpim preset edit daily-ops

# Список всех пресетов
azpim preset list

# Показать детали одного пресета
azpim preset show daily-ops

# Удалить пресет
azpim preset remove daily-ops

# Использовать пресет (флаги всё ещё переопределяют значения пресета)
azpim activate --preset daily-ops --yes

# Неинтерактивный запуск с пресетом
azpim activate --preset daily-ops --non-interactive --yes --output json

# Деактивация с использованием пресета
azpim deactivate --preset daily-ops --non-interactive --yes

Значения по умолчанию

Когда вы создаёте пресет через azpim preset add, вы можете дополнительно установить его как пресет по умолчанию для activate и/или deactivate.

• Пресеты по умолчанию применяются автоматически при запуске одношаговых процессов, если вы явно не предоставили необходимые флаги.
• Пример: после установки пресета по умолчанию для activate, azpim activate --non-interactive --yes может работать без указания --subscription-id/--role-name.

Пример сеанса

╔════════════════════════════════════════════════════╗
║     Azure PIM CLI - Role Activation Manager        ║
╚════════════════════════════════════════════════════╝

✔ Authentication successful

┌─ User Information ──────────────────────────────────
│ Name: John Doe
│ Email: [email protected]
└──────────────────────────────────────────────────────

✔ Found 3 subscription(s)

? What would you like to do?
❯ ▶ Activate Role(s)
  ◼ Deactivate Role(s)
  ✕ Exit

Процесс активации ролей

1. Выберите подписку из доступных подписок Azure
2. Выберите одну или несколько доступных для активации ролей
3. Укажите длительность активации (1–8 часов)
4. Укажите обоснование активации
5. Подтвердите и активируйте

Процесс деактивации ролей

1. Просмотрите все активные роли по подпискам
2. Выберите роли для деактивации
3. Подтвердите деактивацию

Избранное

Избранное позволяет пометить конкретные подписки для быстрого доступа. Избранные подписки отображаются вверху списков подписок в интерактивном меню.

Расположение файла избранного

По умолчанию избранное хранится отдельно для каждого пользователя:

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

Переопределите расположение с помощью:

• AZPIM_FAVORITES_PATH=/путь/к/favorites.json

Типичные рабочие процессы

# Список всего избранного
azpim favorites list
azpim fav list

# Добавить подписку в избранное
azpim favorites add <subscription-id>

# Добавить, даже если подписка отсутствует в кэше
azpim favorites add <subscription-id> --force

# Удалить подписку из избранного
azpim favorites remove <subscription-id>

# Очистить всё избранное
azpim favorites clear

# Экспортировать избранное в файл
azpim favorites export ./my-favorites.json

# Импортировать избранное из файла (заменяет существующее)
azpim favorites import ./my-favorites.json

# Импортировать избранное и объединить с существующим
azpim favorites import ./my-favorites.json --merge

# Обновить кэш подписок
azpim favorites refresh

Кэш подписок

azpim автоматически кэширует информацию о подписках для ускорения запуска. Кэш имеет TTL (время жизни) 6 часов и автоматически обновляется по истечении срока.

Расположение кэша

Файлы кэша хранятся отдельно для каждого пользователя:

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

Обновление кэша

# Принудительное обновление кэша подписок
azpim favorites refresh

Разработка

Доступные скрипты

# Запуск в режиме разработки с горячей перезагрузкой
pnpm dev

# Сборка TypeScript-проекта
pnpm build

# Запуск собранного приложения
pnpm start

# Проверка кода линтером
pnpm lint

Журнал изменений и релизы

В этом репозитории используется формат Keep a Changelog в файле CHANGELOG.md.

Рекомендуемые сообщения коммитов

Для лучших результатов используйте Conventional Commits:

• feat: ... (новая функция) — минорный бамп
• fix: ... (исправление ошибки) — патч-бамп
• chore: ..., docs: ..., refactor: ... (без бампа, если не ломающее изменение)

Выпуск релиза

1. Убедитесь, что в CHANGELOG.md есть актуальные записи под заголовком Unreleased.

2. Выполните одну из следующих команд:

# Автоматически определяет следующую версию на основе коммитов, обновляет CHANGELOG.md,
# изменяет package.json и создаёт git-тег.
pnpm release

# Предварительный просмотр того, что изменится
pnpm release:dry

# Принудительный конкретный бамп, если необходимо
pnpm release -- --release-as patch
pnpm release -- --release-as minor
pnpm release -- --release-as major

3. Отправьте коммиты + теги:

git push --follow-tags

4. Опубликуйте в npm (если нужно):

npm publish
# или
pnpm publish

Структура проекта

azpim/
├── src/
│   ├── index.ts                        # CLI entry point and command definitions
│   ├── core/                           # Foundational utilities (no domain logic)
│   │   ├── constants.ts                # Shared magic values and defaults
│   │   ├── errors.ts                   # Unified error handling utilities
│   │   ├── json-store.ts              # Generic JSON file persistence
│   │   ├── paths.ts                    # Config/data file path resolution
│   │   └── ui.ts                       # Terminal UI (spinners, formatting, colors)
│   ├── azure/                          # Azure SDK wrappers
│   │   ├── auth.ts                     # Azure CLI credential + Graph /me lookup
│   │   └── azure-pim.ts               # PIM role activation/deactivation API
│   ├── data/                           # Local data persistence
│   │   ├── favorites.ts               # Favorites management
│   │   ├── presets.ts                  # Preset configuration and validation
│   │   ├── subscription-cache.ts      # Subscription caching (6-hour TTL)
│   │   └── update-check.ts            # Update notification system
│   └── cli/                            # Interactive flows and command scaffolding
│       ├── cli.ts                      # Main menu loop and shared helpers
│       ├── command-handler.ts         # Reusable command wrapper (auth, UI, errors)
│       ├── activate-flow.ts           # Role activation (one-shot + interactive)
│       ├── deactivate-flow.ts         # Role deactivation (one-shot + interactive)
│       ├── subscription-selector.ts   # Subscription search/select with favorites
│       ├── favorites-manager.ts       # Interactive favorites management menu
│       └── presets-cli.ts             # Preset add/edit/manage wizards
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── README.md

Архитектура

Кодовая база следует многоуровневой модульной структуре:

• core/ — Утилиты без зависимостей, общие для всего проекта. json-store.ts предоставляет общий шаблон загрузки/сохранения, используемый всеми файлами постоянного хранения. errors.ts централизует извлечение ошибок и обработку ошибок на уровне команд. constants.ts устраняет магические значения.
• azure/ — Тонкие обёртки вокруг Azure SDK (@azure/identity, @azure/arm-authorization) и лёгкий вызов Microsoft Graph /me через нативный fetch. Без логики пользовательского интерфейса.
• data/ — Локальное файловое хранение (избранное, пресеты, кэш подписок, состояние обновлений). Все используют json-store для единообразного ввода-вывода.
• cli/ — Пользовательские интерактивные процессы и scaffolding команд. предоставляет обёртку , которая устраняет шаблонный код (аутентификация, настройка UI, обработка ошибок) для всех команд Commander. Процессы активации и деактивации используют общую функцию из .

Технологический стек

• TypeScript — Типобезопасный JavaScript
• Commander.js — Фреймворк для CLI
• Inquirer.js — Интерактивные подсказки
• Ora — Элегантные спиннеры для терминала
• Chalk — Стилизация строк в терминале
• Azure SDK — Интеграция с сервисами Azure

Переменные окружения

Устранение неполадок

Ошибка «Azure CLI not found»

Убедитесь, что Azure CLI установлен и доступен в вашей PATH:

az --version

Ошибки аутентификации

1. Убедитесь, что вы вошли в Azure CLI:

   root@kitploit:~

   az login
   

2. Проверьте, что ваша учётная запись имеет роли, доступные для PIM:

   root@kitploit:~

   az account show
   

3. Проверьте, есть ли у вас необходимые разрешения в Azure AD

Подписки не найдены

• Проверьте, что ваша учётная запись Azure имеет доступ к подпискам
• Попробуйте обновить сеанс Azure CLI: az login --refresh

Лицензия

Этот проект лицензирован по лицензии ISC.

Автор

Tapan Meena — [email protected]

Участие

Вклад приветствуется! Пожалуйста, не стесняйтесь отправлять Pull Request.

1. Форкните репозиторий
2. Создайте ветку для вашей функции (git checkout -b feature/amazing-feature)
3. Зафиксируйте изменения (git commit -m 'Add some amazing feature')
4. Отправьте в ветку (git push origin feature/amazing-feature)
5. Откройте Pull Request