grant-cli

grant

A CLI tool for elevating Azure permissions via CyberArk Secure Cloud Access (SCA) — without leaving the terminal.

Overview

grant enables terminal-based Azure permission elevation through CyberArk SCA. It wraps the idsec-sdk-golang SDK for authentication and builds a custom SCA Access API client for JIT role elevation.

Key Features:

• Interactive permission elevation with fuzzy search
• Direct elevation with target and role flags
• Favorites management for frequently used roles
• Session status monitoring
• Secure token storage in system keyring

Installation

Binary Releases (Recommended)

Download pre-built binaries from the Releases page.

macOS:

# Intel
curl -LO https://github.com/aaearon/grant-cli/releases/latest/download/grant_Darwin_x86_64.tar.gz
tar xzf grant_Darwin_x86_64.tar.gz
sudo mv grant /usr/local/bin/

# Apple Silicon
curl -LO https://github.com/aaearon/grant-cli/releases/latest/download/grant_Darwin_arm64.tar.gz
tar xzf grant_Darwin_arm64.tar.gz
sudo mv grant /usr/local/bin/

Linux:

curl -LO https://github.com/aaearon/grant-cli/releases/latest/download/grant_Linux_x86_64.tar.gz
tar xzf grant_Linux_x86_64.tar.gz
sudo mv grant /usr/local/bin/

Windows: Download grant_Windows_x86_64.zip from releases and extract to a directory in your PATH.

Go Install

go install github.com/aaearon/grant-cli@latest

From Source

git clone https://github.com/aaearon/grant-cli.git
cd grant-cli
make build

Quick Start

Initial Setup

1. Authenticate (auto-configures on first run):

   grant login
   

   On first run, you'll be prompted for:

   • Identity URL (e.g., https://abc1234.id.cyberark.cloud)
   • Username

   Then follow the interactive prompts to complete MFA authentication. The MFA method will be selected interactively during login.

2. Elevate permissions:

   grant
   

   Select your target and role from the interactive list.

3. Verify active sessions:

   grant status
   

Optional: Run grant configure to reconfigure your Identity URL or username.

Commands

Running grant with no subcommand elevates cloud permissions (the core behavior). Subcommands are listed below.

Command	Description
configure	Configure or reconfigure Identity URL and username (optional — login auto-configures on first run)
login	Authenticate to CyberArk Identity (auto-configures on first run, MFA handled interactively)
logout	Clear cached tokens from keyring
status	Show authentication state and active SCA sessions
favorites	Manage saved role favorites (add/list/remove)
version	Print version information

configure

Configure or reconfigure your CyberArk tenant connection.

grant configure

This command:

• Creates ~/.grant/config.yaml for application settings
• Creates ~/.idsec_profiles/grant.json for SDK authentication
• Prompts for Identity URL (must be HTTPS, format: https://{subdomain}.id.cyberark.cloud)
• Prompts for username

Note: This command is optional. Running grant login for the first time automatically runs configuration. Use configure to change your Identity URL or username.

login

Authenticate to CyberArk Identity with MFA.

grant login

This command:

• First time: Prompts for Identity URL and username, then authenticates
• Subsequent runs: Uses credentials from ~/.idsec_profiles/grant.json
• Prompts for password and MFA challenge (MFA method selected interactively)
• Stores tokens securely in system keyring
• Shows token expiration time on success

Note: Tokens are automatically refreshed during operations if still valid.

logout

Clear all cached tokens from the system keyring.

grant logout

This removes stored authentication tokens but preserves your configuration files.

Default Behavior (Elevate)

Running grant with no subcommand requests JIT (just-in-time) permission elevation for cloud resources.

Interactive mode — select from eligible targets:

grant
grant --provider azure  # explicit provider

Direct mode — specify target and role:

grant --target "Prod-EastUS" --role "Contributor"
grant -t "MyResourceGroup" -r "Owner"

Favorite mode — use a saved favorite:

grant --favorite prod-contrib
grant -f dev-reader

Flags:

• --provider, -p — Cloud provider (default: azure, v1 supports Azure only)
• --target, -t — Target name (subscription, resource group, management group, directory, or resource)
• --role, -r — Role name (e.g., "Contributor", "Reader", "Owner")
• --favorite, -f — Use a saved favorite alias (combines provider, target, and role)
• --duration, -d — Requested session duration in hours (subject to policy limits)

Target matching:

• Matches by workspace name (case-insensitive, partial match)
• Interactive mode provides fuzzy search
• Shows workspace type (subscription, resource group, etc.) and available roles

How it works: For Azure, SCA creates a JIT Azure RBAC role assignment. Your existing az CLI session automatically picks up the elevated permissions — no credentials are returned.

status

Display authentication state and active elevation sessions.

grant status
grant status --provider azure  # filter by provider

Output includes:

• Authentication status (username and token validity)
• Active sessions grouped by cloud provider
• Session details: target name, role, expiration time
• Human-readable time remaining (e.g., "2h 15m")

favorites

Manage saved role combinations for quick elevation.

Add a favorite:

grant favorites add <name>

This interactively prompts for:

• Provider (default: azure)
• Target name
• Role name

List favorites:

grant favorites list

Shows all saved favorites with their provider, target, and role.

Remove a favorite:

grant favorites remove <name>

Example workflow:

# Add a favorite
$ grant favorites add prod-contrib
Provider: azure
Target: Prod-EastUS
Role: Contributor
Favorite 'prod-contrib' added successfully.

# Use the favorite
$ grant --favorite prod-contrib

# List favorites
$ grant favorites list
prod-contrib:
  Provider: azure
  Target: Prod-EastUS
  Role: Contributor

version

Display version information including commit hash and build date.

grant version

Configuration

App Config (~/.grant/config.yaml)

Application settings including default provider and favorites.

Default location: ~/.grant/config.yaml

Override: Set GRANT_CONFIG environment variable to use a custom path.

profile: grant              # SDK profile name
default_provider: azure       # Default cloud provider

favorites:
  prod-contrib:
    provider: azure
    target: "Prod-EastUS"
    role: "Contributor"
  dev-reader:
    provider: azure
    target: "Dev-Subscription"
    role: "Reader"

Fields:

• profile — Name of the SDK profile in ~/.idsec_profiles/ (default: grant)
• default_provider — Default cloud provider for elevation (default: azure)
• favorites — Map of favorite names to provider/target/role combinations

SDK Profile (~/.idsec_profiles/grant.json)

CyberArk Identity SDK profile containing Identity URL and authentication preferences.

Managed by: grant configure command (or auto-created by grant login)

Contains:

• Identity URL (format: https://{subdomain}.id.cyberark.cloud)
• Username
• SDK version metadata

Note: Tokens are NOT stored in this file — they're stored securely in the system keyring. MFA method selection is handled interactively during login.

Environment Variables

Variable	Description	Default
GRANT_CONFIG	Custom path to app config YAML	~/.grant/config.yaml
HOME	User home directory (used for config paths)	System default

How It Works

Azure Elevation Flow

1. List Eligibility: Queries SCA API for roles you're eligible to activate
2. Request Elevation: Submits elevation request with target and role
3. JIT Activation: SCA creates a time-limited Azure RBAC role assignment
4. Automatic Access: Your existing az CLI picks up the new role assignment
5. Session Expiry: Role assignment automatically expires (default: 8 hours, policy-controlled)

Important: No Azure credentials are returned to you. SCA manages the Azure role assignment behind the scenes. Your Azure CLI session uses its existing authentication but gains the new role assignment.

Authentication Flow

1. Initial Authentication: grant login authenticates to CyberArk Identity with MFA
2. Token Storage: Tokens stored securely in system keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service)
3. Token Reuse: Subsequent commands reuse cached tokens if still valid
4. Auto-Refresh: SDK automatically refreshes tokens before expiry
5. Manual Logout: grant logout clears tokens from keyring

Troubleshooting

"Error: failed to load config" or "profile not found"

Cause: Configuration files not created or corrupted.

Solution:

grant login      # Auto-configures on first run
# or
grant configure  # Explicit reconfiguration

"Error: not authenticated" or "authentication required"

Cause: No valid authentication token in keyring.

Solution:

grant login

If login fails, verify:

1. Identity URL is correct (check ~/.idsec_profiles/grant.json - should be https://{subdomain}.id.cyberark.cloud)
2. Username is correct
3. Password is correct
4. MFA device/method is available and working

Elevation succeeds but Azure CLI doesn't see new role

Cause: Azure CLI token cache may be stale.

Solution:

# Refresh Azure CLI token
az account get-access-token --output none

# Or clear Azure CLI cache and re-login
az account clear
az login

"No eligible targets found"

Cause: Either you have no SCA policies granting access, or your policies don't grant Azure access.

Solution:

1. Contact your CyberArk administrator to verify SCA policies
2. Ensure policies grant you access to Azure targets
3. Verify you're using the correct provider: grant --provider azure

"Failed to elevate" or partial success

Cause: Policy may not allow the specific role or target, or session limit reached.

Solution:

1. Check active sessions: grant status
2. Verify the target name and role name are correct
3. Try with different duration: grant --duration 4
4. Contact your CyberArk administrator if role should be available

Interactive selection doesn't appear

Cause: Terminal doesn't support interactive input (e.g., non-TTY, CI environment).

Solution: Use direct mode with explicit flags:

grant --target "MyTarget" --role "Contributor"

"Error: invalid provider" (v1)

Cause: Version 1.x only supports Azure.

Solution: Use --provider azure (or omit the flag, as Azure is the default):

grant --provider azure

Token expired or invalid during operation

Cause: Token expired between operations or keyring access denied.

Solution:

grant logout
grant login

Permission denied accessing keyring (Linux)

Cause: No keyring service available or gnome-keyring / kde-wallet not running.

Solution:

1. Install and start a keyring service:

   # For GNOME
   sudo apt install gnome-keyring
   
   # For KDE
   sudo apt install kwalletmanager
   

2. Or use environment-based auth (not recommended for production)

Development

Running Tests

# Unit tests
make test

# Integration tests (requires binary build)
make test-integration

# All tests
make test-all

Building

# Build binary
make build

# Build with version info
VERSION=1.0.0 make build

Linting

make lint

Contributing

Contributions welcome! Please:

1. Follow existing code patterns and conventions
2. Write tests for new functionality (TDD preferred)
3. Update documentation for user-facing changes
4. Use conventional commits for commit messages

License

MIT