Azure PIM CLI (azpim)

أداة سطر أوامر لإدارة تفعيل أدوار Azure Privileged Identity Management (PIM) مباشرة من الطرفية الخاصة بك.

الميزات

• 🔐 تفعيل الدور - تفعيل أدوار Azure PIM المؤهلة بسرعة
• 🔓 إلغاء تنشيط الدور - إلغاء تنشيط الأدوار النشطة عند عدم الحاجة إليها
• 📋 قائمة تفاعلية - واجهة سهلة الاستخدام تعمل بالقوائم
• ✨ واجهة مستخدم جميلة - تجربة طرفية مصقولة مع مؤشرات التحميل والألوان
• 🔄 دعم أدوار متعددة - تفعيل أو إلغاء تنشيط أدوار متعددة في وقت واحد
• 📊 تتبع الحالة - ردود فعل فورية حول حالة التفعيل/إلغاء التنشيط
• 💾 الإعدادات المسبقة - حفظ وإعادة استخدام إعدادات التفعيل/إلغاء التنشيط
• ⭐ المفضلة - وضع علامة على الاشتراكات كمفضلة للوصول السريع
• 🗃️ ذاكرة تخزين مؤقت للاشتراكات - تخزين تلقائي للاشتراكات (مدة صلاحية 6 ساعات) لبدء تشغيل أسرع
• 🚀 وضع غير تفاعلي - علامات CLI للنصوص البرمجية والأتمتة
• 🔔 إشعارات التحديث - فحص تلقائي للتحديثات مع سلوك قابل للتكوين
• 📤 مخرجات JSON - مخرجات قابلة للقراءة آليًا للتكامل مع الأدوات الأخرى
• 👤 عزل البيانات لكل مستخدم - تخزين الإعدادات والذاكرة المؤقتة لكل معرف مستخدم Azure

المتطلبات الأساسية

قبل استخدام azpim، تأكد من أن لديك:

1. Node.js (الإصدار v18 أو أحدث)
2. Azure CLI مثبت ومهيأ
3. حساب Azure بأدوار مؤهلة لـ PIM

إعداد Azure CLI

# Install Azure CLI (if not installed)
# See: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli

# Login to Azure
az login

# Verify you're logged in
az account show

التثبيت

التثبيت العام (موصى به)

# Using npm
npm install -g azpim

# Using pnpm
pnpm add -g azpim

# Using 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

من المصدر (تطوير)

# Clone the repository
git clone https://github.com/tapanmeena/azpim.git
cd azpim

# Install dependencies
pnpm install

# Build the project
pnpm build

# Link globally for development
npm link

الاستخدام

تشغيل CLI

# After global installation
azpim

# Or with specific commands
azpim activate
azpim deactivate
azpim preset list
azpim update

# Development mode (from source)
pnpm dev

الأوامر

العلامات العامة:

• --debug - تمكين تسجيل التصحيح
• --version - إظهار رقم الإصدار

أوامر الإعدادات المسبقة الفرعية

أوامر المفضلة الفرعية

التحديثات

يمكنك التحقق من توفر إصدار أحدث:

azpim update
# alias
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.

أمثلة التفعيل

# Activate a single role by name (non-interactive)
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --duration-hours 2 \
   --justification "Break-glass for incident" \
   --output json

# Activate multiple roles (repeat --role-name)
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --role-name "User Access Administrator"

# If a role name matches multiple eligible roles (different scopes),
# --non-interactive will error unless you explicitly allow activating all matches
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --allow-multiple

# Preview what would happen without submitting requests
azpim activate --non-interactive --dry-run \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --output json

أمثلة إلغاء التنشيط

# Deactivate specific roles
azpim deactivate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --justification "Task completed"

# Deactivate across all subscriptions (omit subscription-id)
azpim deactivate --non-interactive --yes \
   --role-name "Contributor" \
   --allow-multiple

العلامات المتاحة

العلامات المشتركة (تفعيل/إلغاء تنشيط):

• --non-interactive - تعطيل المطالبات التفاعلية
• -y, --yes - تخطي مطالبات التأكيد
• --subscription-id <id> - الاشتراك المستهدف (اختياري لإلغاء التنشيط)
• --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

سير العمل الشائع

# Create a preset (interactive wizard)
azpim preset add daily-ops

# Create a preset with Azure integration (fetches subscriptions/roles)
azpim preset add daily-ops --from-azure

# Edit a preset (interactive wizard)
azpim preset edit daily-ops

# List all presets
azpim preset list

# Show one preset details
azpim preset show daily-ops

# Remove a preset
azpim preset remove daily-ops

# Use a preset (flags still override preset values)
azpim activate --preset daily-ops --yes

# Non-interactive run using the preset
azpim activate --preset daily-ops --non-interactive --yes --output json

# Deactivate using a preset
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        ║
╚════════════════════════════════════════════════════╝

✔ 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=/path/to/favorites.json

سير العمل الشائع

# List all favorites
azpim favorites list
azpim fav list

# Add a subscription to favorites
azpim favorites add <subscription-id>

# Add even if subscription is not in cache
azpim favorites add <subscription-id> --force

# Remove a subscription from favorites
azpim favorites remove <subscription-id>

# Clear all favorites
azpim favorites clear

# Export favorites to a file
azpim favorites export ./my-favorites.json

# Import favorites from a file (replaces existing)
azpim favorites import ./my-favorites.json

# Import favorites and merge with existing
azpim favorites import ./my-favorites.json --merge

# Refresh the subscription cache
azpim favorites refresh

الذاكرة المؤقتة للاشتراكات

يقوم azpim تلقائيًا بتخزين معلومات الاشتراكات مؤقتًا لتحسين وقت بدء التشغيل. للذاكرة المؤقتة مدة صلاحية (TTL) مدتها 6 ساعات ويتم تحديثها تلقائيًا عند انتهائها.

موقع الذاكرة المؤقتة

يتم تخزين ملفات الذاكرة المؤقتة لكل مستخدم:

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

تحديث الذاكرة المؤقتة

# Force refresh the subscription cache
azpim favorites refresh

التطوير

النصوص البرمجية المتاحة

# Run in development mode with hot reload
pnpm dev

# Build the TypeScript project
pnpm build

# Run the built application
pnpm start

# Lint the codebase
pnpm lint

سجل التغييرات والإصدارات

يستخدم هذا المستودع تنسيق Keep a Changelog في CHANGELOG.md.

رسائل الالتزام الموصى بها

للحصول على أفضل النتائج، استخدم Conventional Commits:

• feat: ... (ميزة جديدة) → bump ثانوي
• fix: ... (إصلاح خطأ) → bump تصحيحي
• chore: ...، docs: ...، refactor: ... (لا bump ما لم يكن breaking)

إصدار إصدار

1. تأكد من أن CHANGELOG.md يحتوي على إدخالات محدثة ضمن Unreleased.

2. قم بتشغيل أحد الأوامر التالية:

# Automatically determines next version from commits, updates CHANGELOG.md,
# bumps package.json, and creates a git tag.
pnpm release

# Preview what would change
pnpm release:dry

# Force a specific bump if needed
pnpm release -- --release-as patch
pnpm release -- --release-as minor
pnpm release -- --release-as major

3. ادفع الالتزامات والوسوم:

git push --follow-tags

4. انشر إلى npm (إذا رغبت):

npm publish
# or
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 SDKs (@azure/identity، @azure/arm-authorization) واستدعاء خفيف الوزن لـ Microsoft Graph /me عبر fetch الأصلي. لا يوجد منطق واجهة مستخدم.
• data/ — استمرار البيانات المحلية (المفضلة، الإعدادات المسبقة، ذاكرة الاشتراكات المؤقتة، حالة التحديث). جميعها تستخدم json-store لإدخال/إخراج ملفات متسق.
• cli/ — تدفقات تفاعلية موجهة للمستخدم وسقالات الأوامر. يوفر command-handler.ts غلاف الذي يلغي النمط المتكرر (المصادقة، إعداد واجهة المستخدم، معالجة الأخطاء) عبر جميع أوامر Commander. تشارك تدفقات التفعيل وإلغاء التنشيط دالة من .

مجموعة التقنيات

• TypeScript - جافاسكريبت آمنة من حيث الأنواع
• 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. انسخ (Fork) المستودع
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)