Azure PIM CLI (azpim)

ターミナルから直接Azure Privileged Identity Management (PIM) ロールのアクティベーションを管理するためのコマンドラインインターフェースツールです。

機能

• 🔐 ロールのアクティベーション - 対象となるAzure PIMロールをすばやくアクティベート
• 🔓 ロールの非アクティブ化 - 不要になったアクティブロールを非アクティブ化
• 📋 インタラクティブメニュー - ユーザーフレンドリーなメニュー駆動インターフェース
• ✨ 美しいUI - スピナーとカラーを備えた洗練されたターミナル体験
• 🔄 マルチロール対応 - 複数のロールを一度にアクティベートまたは非アクティブ化
• 📊 ステータストラッキング - アクティベーション/非アクティブ化の状況をリアルタイムに表示
• 💾 プリセット - アクティベーション/非アクティブ化の設定を保存して再利用
• ⭐ お気に入り - サブスクリプションをお気に入りに登録して素早くアクセス
• 🗃️ サブスクリプションキャッシュ - サブスクリプションの自動キャッシュ（TTL 6時間）による高速起動
• 🚀 非対話モード - スクリプトと自動化のためのCLIフラグ
• 🔔 更新通知 - 設定可能な動作で自動更新チェック
• 📤 JSON出力 - 他ツールとの統合のための機械可読な出力
• 👤 ユーザーごとのデータ分離 - AzureユーザーIDごとに設定とキャッシュを保存

前提条件

azpimを使用する前に、次のものが揃っていることを確認してください。

1. Node.js（v18以上）
2. Azure CLIがインストールおよび構成されている
3. AzureアカウントにPIM対象ロールがある

Azure CLIのセットアップ

# Azure CLIのインストール（未インストールの場合）
# 参照: https://docs.microsoft.com/ja-jp/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/（Windowsの場合は%APPDATA%\azp-cli\）に保存されています。移行するには：

1. presets.jsonを新しい場所（~/.config/azpim/、Windowsの場合は%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 - バージョン番号を表示

プリセットのサブコマンド

お気に入りのサブコマンド

アップデート

新しいバージョンが利用可能かどうかを確認できます。

azpim update
# エイリアス
azpim upgrade

注意事項：

• azpim updateは、最新の場合は終了コード0、更新可能な場合は2、エラーの場合は1を返します。
• --check-only - アップグレード手順を表示せず、ステータスのみをチェックして表示します。
• --output jsonは、スクリプトで使用可能な構造化レスポンスを返します。
• デフォルトでは、azpim activateとazpim deactivateは、1日に1回まで「更新可能」という短いヒント（テキストモードのみ）を表示します。
• 更新チェックを無効にするには、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 "インシデント対応のための緊急アクセス" \
   --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 "タスク完了"

# すべてのサブスクリプションにわたって非アクティブ化（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 <name> で再利用できます。

プリセットファイルの場所

デフォルトでは、プリセットはユーザーごとの設定ファイルに保存されます。

• macOS/Linux: ~/.config/azpim/presets.json（または$XDG_CONFIG_HOME/azpim/presets.json）
• Windows: %APPDATA%\azpim\presets.json

場所を上書きするには：

• AZPIM_PRESETS_PATH=/path/to/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

# 1つのプリセットの詳細を表示
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のデフォルトとして設定することもできます。

• デフォルトプリセットは、ワンショットフローを実行する際に必要なフラグを明示的に指定していない場合に自動的に適用されます。
• 例：デフォルトのアクティベートプリセットを設定した後、azpim activate --non-interactive --yes は --subscription-idや--role-nameを指定しなくても動作できます。

セッション例

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

✔ 認証成功

┌─ ユーザー情報 ──────────────────────────────────
│ 名前: 山田 太郎
│ メール: [email protected]
└──────────────────────────────────────────────────────

✔ 3件のサブスクリプションが見つかりました

? 何をしますか？
❯ ▶ ロールのアクティベート
  ◼ ロールの非アクティブ化
  ✕ 終了

ロールアクティベーションフロー

1. 利用可能なAzureサブスクリプションから1つを選択
2. アクティベートする対象ロールを1つ以上選択
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=/path/to/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

変更履歴とリリース

このリポジトリでは、CHANGELOG.mdに Keep a Changelog 形式を使用しています。

推奨コミットメッセージ

最良の結果を得るには、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エントリポイントとコマンド定義
│   ├── core/                           # 基本ユーティリティ（ドメインロジックなし）
│   │   ├── constants.ts                # 共有マジック値とデフォルト
│   │   ├── errors.ts                   # 統一エラーハンドリングユーティリティ
│   │   ├── json-store.ts              # 汎用JSONファイル永続化
│   │   ├── paths.ts                    # 設定/データファイルパスの解決
│   │   └── ui.ts                       # ターミナルUI（スピナー、書式設定、色）
│   ├── azure/                          # Azure SDKラッパー
│   │   ├── auth.ts                     # Azure CLI資格情報 + Graph /me ルックアップ
│   │   └── azure-pim.ts               # PIMロールアクティベーション/非アクティブ化API
│   ├── data/                           # ローカルデータ永続化
│   │   ├── favorites.ts               # お気に入り管理
│   │   ├── presets.ts                  # プリセット設定と検証
│   │   ├── subscription-cache.ts      # サブスクリプションキャッシュ（TTL 6時間）
│   │   └── update-check.ts            # 更新通知システム
│   └── cli/                            # インタラクティブフローとコマンドスキャフォールディング
│       ├── cli.ts                      # メインメニューループと共有ヘルパー
│       ├── command-handler.ts         # 再利用可能なコマンドラッパー（認証、UI、エラー）
│       ├── activate-flow.ts           # ロールアクティベーション（ワンショット＋インタラクティブ）
│       ├── deactivate-flow.ts         # ロール非アクティブ化（ワンショット＋インタラクティブ）
│       ├── subscription-selector.ts   # お気に入りによるサブスクリプション検索/選択
│       ├── favorites-manager.ts       # インタラクティブお気に入り管理メニュー
│       └── presets-cli.ts             # プリセット追加/編集/管理ウィザード
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── README.md

アーキテクチャ

コードベースは階層化されたモジュール構造に従っています。

• core/ — プロジェクト全体で共有される依存関係のないユーティリティ。json-store.tsは、すべてのデータ永続化ファイルで使用される汎用のロード/セーブパターンを提供します。errors.tsはエラー抽出とコマンドレベルのエラーハンドリングを一元化します。constants.tsはマジック値を排除します。
• azure/ — Azure SDK（@azure/identity、@azure/arm-authorization）と、ネイティブfetchを使用した軽量なMicrosoft Graph /me呼び出しの薄いラッパー。UIロジックは含まれません。
• data/ — ローカルファイル永続化（お気に入り、プリセット、サブスクリプションキャッシュ、更新状態）。すべてjson-storeを使用して一貫したファイルI/Oを行います。
• cli/ — ユーザー向けインタラクティブフローとコマンドスキャフォールディング。command-handler.tsは、すべてのCommanderコマンドにわたって定型コード（認証、UI設定、エラーハンドリング）を排除するラッパーを提供します。アクティベーションと非アクティブ化フローは、の関数を共有します。

技術スタック

• TypeScript - 型安全なJavaScript
• Commander.js - CLIフレームワーク
• Inquirer.js - インタラクティブプロンプト
• Ora - エレガントなターミナルスピナー
• Chalk - ターミナル文字列スタイリング
• Azure SDK - Azureサービス統合

環境変数

トラブルシューティング

「Azure CLIが見つかりません」エラー

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]

コントリビューション

コントリビューションを歓迎します！プルリクエストを遠慮なく送信してください。

1. リポジトリをフォーク
2. 機能ブランチを作成（git checkout -b feature/amazing-feature）
3. 変更をコミット（git commit -m '素晴らしい機能を追加'）
4. ブランチにプッシュ（git push origin feature/amazing-feature）
5. プルリクエストを開く