Azure PIM CLI (azpim)

Uma ferramenta de interface de linha de comando para gerenciar ativações de funções do Azure Privileged Identity Management (PIM) diretamente do seu terminal.

Recursos

• 🔐 Ativação de Funções - Ative rapidamente funções elegíveis do Azure PIM
• 🔓 Desativação de Funções - Desative funções ativas quando não forem mais necessárias
• 📋 Menu Interativo - Interface amigável orientada por menus
• ✨ Interface Bonita - Experiência de terminal refinada com spinners e cores
• 🔄 Suporte a Múltiplas Funções - Ative ou desative várias funções de uma só vez
• 📊 Acompanhamento de Status - Feedback em tempo real sobre o status de ativação/desativação
• 💾 Predefinições - Salve e reutilize configurações de ativação/desativação
• ⭐ Favoritos - Marque assinaturas como favoritas para acesso rápido
• 🗃️ Cache de Assinaturas - Cache automático de assinaturas (TTL de 6 horas) para inicialização mais rápida
• 🚀 Modo Não Interativo - Flags de CLI para scripts e automação
• 🔔 Notificações de Atualização - Verificações automáticas de atualização com comportamento configurável
• 📤 Saída JSON - Saída legível por máquina para integração com outras ferramentas
• 👤 Isolamento de Dados por Usuário - Configuração e cache armazenados por ID de usuário do Azure

Pré-requisitos

Antes de usar o azpim, certifique-se de ter:

1. Node.js (v18 ou superior)
2. Azure CLI instalado e configurado
3. Conta do Azure com funções elegíveis para PIM

Configuração da Azure CLI

# Instalar a Azure CLI (se não estiver instalada)
# Veja: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli

# Fazer login no Azure
az login

# Verificar se está logado
az account show

Instalação

Instalação Global (Recomendada)

# Usando npm
npm install -g azpim

# Usando pnpm
pnpm add -g azpim

# Usando yarn
yarn global add azpim

Após a instalação, o comando azpim estará disponível globalmente.

Migrando do azp-cli

Se você usava o azp-cli anteriormente, suas predefinições estão armazenadas em ~/.config/azp-cli/ (ou %APPDATA%\azp-cli\ no Windows). Para migrar:

1. Copie seu presets.json para o novo local: ~/.config/azpim/ (ou %APPDATA%\azpim\)
2. Desinstale o pacote antigo: npm uninstall -g azp-cli

A partir do Código Fonte (Desenvolvimento)

# Clonar o repositório
git clone https://github.com/tapanmeena/azpim.git
cd azpim

# Instalar dependências
pnpm install

# Compilar o projeto
pnpm build

# Vincular globalmente para desenvolvimento
npm link

Uso

Executando a CLI

# Após instalação global
azpim

# Ou com comandos específicos
azpim activate
azpim deactivate
azpim preset list
azpim update

# Modo de desenvolvimento (a partir do código fonte)
pnpm dev

Comandos

Flags Globais:

• --debug - Ativar log de depuração
• --version - Mostrar número da versão

Subcomandos de Predefinições

Subcomandos de Favoritos

Atualizações

Você pode verificar se há uma versão mais recente disponível:

azpim update
# alias
azpim upgrade

Notas:

• azpim update sai com código 0 quando atualizado, 2 quando uma atualização está disponível e 1 em caso de erro.
• --check-only - Apenas verificar e imprimir o status sem mostrar instruções de atualização.
• --output json retorna uma resposta estruturada adequada para scripts.
• Por padrão, azpim activate e azpim deactivate também mostrarão uma breve dica "atualização disponível" (apenas modo texto) no máximo uma vez por dia.
• Desative as verificações de atualização via AZPIM_NO_UPDATE_NOTIFIER=1 (ou AZPIM_DISABLE_UPDATE_CHECK=1).

O cache de verificação de atualização é armazenado junto com as predefinições no diretório de configuração:

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

Modo Não Interativo (Automação)

Use flags para ativar ou desativar funções do PIM diretamente, sem passar pelo menu interativo, perfeito para scripts e fluxos de trabalho CI/CD.

Exemplos de Ativação

# Ativar uma única função pelo nome (não interativo)
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --duration-hours 2 \
   --justification "Break-glass for incident" \
   --output json

# Ativar múltiplas funções (repetir --role-name)
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --role-name "User Access Administrator"

# Se um nome de função corresponder a várias funções elegíveis (diferentes escopos),
# --non-interactive gerará erro a menos que você permita explicitamente ativar todas as correspondências
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --allow-multiple

# Visualizar o que aconteceria sem enviar solicitações
azpim activate --non-interactive --dry-run \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --output json

Exemplos de Desativação

# Desativar funções específicas
azpim deactivate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --justification "Task completed"

# Desativar em todas as assinaturas (omitir subscription-id)
azpim deactivate --non-interactive --yes \
   --role-name "Contributor" \
   --allow-multiple

Flags Disponíveis

Flags comuns (ativar/desativar):

• --non-interactive - Desabilitar prompts interativos
• -y, --yes - Pular prompts de confirmação
• --subscription-id <id> - Assinatura de destino (opcional para desativar)
• --role-name <name> - Nome(s) da(s) função(ões) a serem direcionadas (pode ser repetido)
• --allow-multiple - Permitir múltiplas correspondências de funções
• --dry-run - Visualizar sem enviar
• --output <text|json> - Formato de saída (padrão: text)
• --quiet - Suprimir saída não essencial

Específico para ativação:

• --duration-hours <n> - Duração (1-8 horas, o padrão varia por função)
• --justification <text> - Justificativa para a ativação

Específico para desativação:

• --justification <text> - Justificativa para a desativação (opcional)

Predefinições

As predefinições permitem salvar suas rotinas diárias de ativação/desativação (assinatura + nomes de funções + duração + justificativa) e reutilizá-las com --preset <name>.

Local do arquivo de predefinições

Por padrão, as predefinições são armazenadas em um arquivo de configuração por usuário:

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

Substitua o local com:

• AZPIM_PRESETS_PATH=/caminho/para/presets.json

Conteúdo da predefinição

Uma predefinição pode definir um ou ambos os blocos:

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

justification suporta templates simples:

• ${date} → YYYY-MM-DD
• ${datetime} → Timestamp ISO
• ${userPrincipalName} → resolvido do Microsoft Graph /me

Fluxos de Trabalho Comuns

# Criar uma predefinição (assistente interativo)
azpim preset add daily-ops

# Criar uma predefinição com integração ao Azure (busca assinaturas/funções)
azpim preset add daily-ops --from-azure

# Editar uma predefinição (assistente interativo)
azpim preset edit daily-ops

# Listar todas as predefinições
azpim preset list

# Mostrar detalhes de uma predefinição
azpim preset show daily-ops

# Remover uma predefinição
azpim preset remove daily-ops

# Usar uma predefinição (flags ainda substituem valores da predefinição)
azpim activate --preset daily-ops --yes

# Execução não interativa usando a predefinição
azpim activate --preset daily-ops --non-interactive --yes --output json

# Desativar usando uma predefinição
azpim deactivate --preset daily-ops --non-interactive --yes

Padrões

Ao criar uma predefinição via azpim preset add, você pode opcionalmente defini-la como padrão para activate e/ou deactivate.

• As predefinições padrão são aplicadas automaticamente quando você executa fluxos únicos e não forneceu explicitamente as flags necessárias.
• Exemplo: após definir uma predefinição de ativação padrão, azpim activate --non-interactive --yes pode funcionar sem especificar --subscription-id/--role-name.

Sessão de Exemplo

╔════════════════════════════════════════════════════╗
║     Azure PIM CLI - Gerenciador de Ativação de Funções        ║
╚════════════════════════════════════════════════════╝

✔ Autenticação bem-sucedida

┌─ Informações do Usuário ──────────────────────────────────
│ Nome: John Doe
│ Email: [email protected]
└──────────────────────────────────────────────────────

✔ 3 assinatura(s) encontrada(s)

? O que você gostaria de fazer?
❯ ▶ Ativar Função(ões)
  ◼ Desativar Função(ões)
  ✕ Sair

Fluxo de Ativação de Função

1. Selecione uma assinatura entre suas assinaturas disponíveis do Azure
2. Escolha uma ou mais funções elegíveis para ativar
3. Especifique a duração da ativação (1-8 horas)
4. Forneça uma justificativa para a ativação
5. Confirme e ative

Fluxo de Desativação de Função

1. Veja todas as funções atualmente ativas em todas as assinaturas
2. Selecione as funções a serem desativadas
3. Confirme a desativação

Favoritos

Os favoritos permitem marcar assinaturas específicas para acesso rápido. Assinaturas favoritas são exibidas no topo das listas de assinaturas no menu interativo.

Local do arquivo de favoritos

Por padrão, os favoritos são armazenados por usuário:

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

Substitua o local com:

• AZPIM_FAVORITES_PATH=/caminho/para/favorites.json

Fluxos de Trabalho Comuns

# Listar todos os favoritos
azpim favorites list
azpim fav list

# Adicionar uma assinatura aos favoritos
azpim favorites add <subscription-id>

# Adicionar mesmo que a assinatura não esteja no cache
azpim favorites add <subscription-id> --force

# Remover uma assinatura dos favoritos
azpim favorites remove <subscription-id>

# Limpar todos os favoritos
azpim favorites clear

# Exportar favoritos para um arquivo
azpim favorites export ./my-favorites.json

# Importar favoritos de um arquivo (substitui os existentes)
azpim favorites import ./my-favorites.json

# Importar favoritos e mesclar com os existentes
azpim favorites import ./my-favorites.json --merge

# Atualizar o cache de assinaturas
azpim favorites refresh

Cache de Assinaturas

O azpim armazena automaticamente em cache as informações de assinatura para melhorar o tempo de inicialização. O cache tem um TTL (time-to-live) de 6 horas e é atualizado automaticamente quando expirado.

Local do cache

Os arquivos de cache são armazenados por usuário:

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

Atualizando o cache

# Forçar atualização do cache de assinaturas
azpim favorites refresh

Desenvolvimento

Scripts Disponíveis

# Executar em modo de desenvolvimento com recarga automática
pnpm dev

# Compilar o projeto TypeScript
pnpm build

# Executar a aplicação compilada
pnpm start

# Verificar lint do código
pnpm lint

Changelog e versões

Este repositório usa o formato Keep a Changelog em CHANGELOG.md.

Mensagens de commit recomendadas

Para melhores resultados, use Conventional Commits:

• feat: ... (nova funcionalidade) → incremento minor
• fix: ... (correção de bug) → incremento patch
• chore: ..., docs: ..., refactor: ... (nenhum incremento a menos que seja breaking)

Lançando uma versão

1. Certifique-se de que CHANGELOG.md tenha entradas atualizadas sob Unreleased.

2. Execute um dos seguintes:

# Determina automaticamente a próxima versão a partir dos commits, atualiza CHANGELOG.md,
# incrementa package.json e cria uma tag git.
pnpm release

# Visualizar o que mudaria
pnpm release:dry

# Forçar um incremento específico, se necessário
pnpm release -- --release-as patch
pnpm release -- --release-as minor
pnpm release -- --release-as major

3. Envie commits + tags:

git push --follow-tags

4. Publique no npm (se desejado):

npm publish
# ou
pnpm publish

Estrutura do Projeto

azpim/
├── src/
│   ├── index.ts                        # Ponto de entrada da CLI e definições de comandos
│   ├── core/                           # Utilitários fundamentais (sem lógica de domínio)
│   │   ├── constants.ts                # Valores mágicos e padrões compartilhados
│   │   ├── errors.ts                   # Utilitários unificados de tratamento de erros
│   │   ├── json-store.ts              # Persistência genérica de arquivos JSON
│   │   ├── paths.ts                    # Resolução de caminhos de arquivo de configuração/dados
│   │   └── ui.ts                       # Interface do terminal (spinners, formatação, cores)
│   ├── azure/                          # Wrappers do SDK do Azure
│   │   ├── auth.ts                     # Credencial da Azure CLI + pesquisa Graph /me
│   │   └── azure-pim.ts               # API de ativação/desativação de funções PIM
│   ├── data/                           # Persistência de dados local
│   │   ├── favorites.ts               # Gerenciamento de favoritos
│   │   ├── presets.ts                  # Configuração e validação de predefinições
│   │   ├── subscription-cache.ts      # Cache de assinaturas (TTL de 6 horas)
│   │   └── update-check.ts            # Sistema de notificação de atualização
│   └── cli/                            # Fluxos interativos e estrutura de comandos
│       ├── cli.ts                      # Loop do menu principal e helpers compartilhados
│       ├── command-handler.ts         # Wrapper de comando reutilizável (auth, UI, erros)
│       ├── activate-flow.ts           # Ativação de função (única + interativa)
│       ├── deactivate-flow.ts         # Desativação de função (única + interativa)
│       ├── subscription-selector.ts   # Pesquisa/seleção de assinatura com favoritos
│       ├── favorites-manager.ts       # Menu interativo de gerenciamento de favoritos
│       └── presets-cli.ts             # Assistentes de adicionar/editar/gerenciar predefinições
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── README.md

Arquitetura

O código segue uma estrutura de módulos em camadas:

• core/ — Utilitários sem dependências compartilhados em todo o projeto. json-store.ts fornece um padrão genérico de carregamento/salvamento usado por todos os arquivos de persistência de dados. errors.ts centraliza a extração de erros e o tratamento de erros em nível de comando. constants.ts elimina valores mágicos.
• azure/ — Wrappers finos ao redor dos SDKs do Azure (@azure/identity, @azure/arm-authorization) e uma chamada leve ao Microsoft Graph /me via fetch nativo. Sem lógica de UI.
• data/ — Persistência de arquivos local (favoritos, predefinições, cache de assinaturas, estado de atualização). Todos usam json-store para E/S de arquivos consistente.
• cli/ — Fluxos interativos voltados ao usuário e estrutura de comandos. fornece um wrapper que elimina código repetitivo (auth, configuração de UI, tratamento de erros) em todos os comandos do Commander. Os fluxos de ativação e desativação compartilham uma função de .

Stack Tecnológica

• TypeScript - JavaScript com tipos
• Commander.js - Framework CLI
• Inquirer.js - Prompts interativos
• Ora - Spinners elegantes no terminal
• Chalk - Estilização de strings no terminal
• Azure SDK - Integração com serviços do Azure

Variáveis de Ambiente

Solução de Problemas

Erro "Azure CLI não encontrado"

Certifique-se de que a Azure CLI está instalada e acessível no seu PATH:

az --version

Erros de Autenticação

1. Certifique-se de que está logado na Azure CLI:

   root@kitploit:~

   az login
   

2. Verifique se sua conta tem funções elegíveis para PIM:

   root@kitploit:~

   az account show
   

3. Verifique se você tem as permissões necessárias no Azure AD

Nenhuma Assinatura Encontrada

• Verifique se sua conta do Azure tem acesso a assinaturas
• Tente atualizar seu login na Azure CLI: az login --refresh

Licença

Este projeto está licenciado sob a Licença ISC.

Autor

Tapan Meena - [email protected]

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

1. Fork o repositório
2. Crie sua branch de funcionalidade (git checkout -b feature/minha-funcionalidade-incrivel)
3. Commit suas mudanças (git commit -m 'Adiciona alguma funcionalidade incrível')
4. Push para a branch (git push origin feature/minha-funcionalidade-incrivel)
5. Abra um Pull Request