Azure PIM CLI (azpim)

명령줄 인터페이스 도구로, 터미널에서 직접 Azure Privileged Identity Management(PIM) 역할 활성화를 관리할 수 있습니다.

기능

• 🔐 역할 활성화 - 적격 Azure PIM 역할을 신속하게 활성화
• 🔓 역할 비활성화 - 더 이상 필요하지 않은 활성 역할을 비활성화
• 📋 대화형 메뉴 - 사용자 친화적인 메뉴 기반 인터페이스
• ✨ 아름다운 UI - 스피너와 색상이 적용된 정돈된 터미널 경험
• 🔄 다중 역할 지원 - 한 번에 여러 역할 활성화 또는 비활성화
• 📊 상태 추적 - 활성화/비활성화 상태에 대한 실시간 피드백
• 💾 프리셋 - 활성화/비활성화 구성을 저장하고 재사용
• ⭐ 즐겨찾기 - 구독을 즐겨찾기로 표시하여 빠르게 접근
• 🗃️ 구독 캐시 - 구독 자동 캐싱(6시간 TTL)으로 시작 시간 단축
• 🚀 비대화형 모드 - 스크립팅 및 자동화를 위한 CLI 플래그
• 🔔 업데이트 알림 - 자동 업데이트 확인 및 구성 가능한 동작
• 📤 JSON 출력 - 다른 도구와 통합하기 위한 기계 판독 가능 출력
• 👤 사용자별 데이터 격리 - Azure 사용자 ID별로 구성 및 캐시 저장

사전 요구 사항

azpim을 사용하기 전에 다음이 필요합니다:

1. Node.js (v18 이상)
2. Azure CLI 설치 및 구성
3. Azure 계정 PIM 적격 역할 보유

Azure CLI 설정

# Azure CLI 설치 (아직 설치되지 않은 경우)
# 참고: https://docs.microsoft.com/en-us/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는 하루에 최대 한 번(텍스트 모드에서만) 짧은 "업데이트 가능" 힌트를 표시합니다.
• 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

사용 가능한 플래그

공통 플래그 (활성화/비활성화):

• --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에서 확인

일반적인 워크플로

# 프리셋 생성 (대화형 마법사)
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의 기본 프리셋으로 설정할 수 있습니다.

• 기본 프리셋은 원샷(one-shot) 흐름을 실행할 때 필수 플래그를 명시적으로 제공하지 않은 경우 자동으로 적용됩니다.
• 예: 기본 활성화 프리셋을 설정하면, 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

일반적인 워크플로

# 모든 즐겨찾기 나열
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은 시작 시간을 개선하기 위해 구독 정보를 자동으로 캐싱합니다. 캐시는 6시간 TTL(Time-To-Live)을 가지며 만료 시 자동으로 새로고침됩니다.

캐시 위치

캐시 파일은 사용자별로 저장됩니다:

• 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
# or
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      # 구독 캐싱 (6시간 TTL)
│   │   └── 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 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 열기