bt-cli 0.4.29
BeyondTrust Platform CLI (unofficial) - Password Safe, Entitle, PRA, EPM
License: MIT
Requires Python: >=3.9
Keywords: beyondtrust, cli, pam, password-safe, privileged-access, security

# BT-CLI

Unofficial BeyondTrust Platform CLI - manage privileged access across your environment from a single command line.

## Supported Products

| Product | Command | Description |
|---------|---------|-------------|
| **Password Safe** | `bt pws` | Credential vaulting, secrets management, password rotation |
| **Entitle** | `bt entitle` | Just-in-time access requests and approval workflows |
| **PRA** | `bt pra` | Privileged remote access - jump items, sessions, vault |
| **EPM Windows** | `bt epmw` | Endpoint privilege management - computers, policies, admin requests |

## Installation

```bash
pip install bt-cli
bt version
```

## Configuration

Set environment variables for each product you want to use. You only need to configure the products you'll use.

### Password Safe

```bash
# Option 1: OAuth (recommended)
export BT_PWS_API_URL=https://your-server/BeyondTrust/api/public/v3
export BT_PWS_CLIENT_ID=your-client-id
export BT_PWS_CLIENT_SECRET=your-client-secret

# Option 2: API Key
export BT_PWS_API_URL=https://your-server/BeyondTrust/api/public/v3
export BT_PWS_API_KEY=your-api-key
```

### Entitle

```bash
export BT_ENTITLE_API_URL=https://api.us.entitle.io
export BT_ENTITLE_API_KEY=your-api-key
```

### PRA (Privileged Remote Access)

```bash
export BT_PRA_API_URL=https://your-site.beyondtrustcloud.com
export BT_PRA_CLIENT_ID=your-client-id
export BT_PRA_CLIENT_SECRET=your-client-secret
```

### EPM Windows

```bash
export BT_EPM_API_URL=https://your-site-services.epm.bt3ng.com
export BT_EPM_CLIENT_ID=your-client-id
export BT_EPM_CLIENT_SECRET=your-client-secret
```

### Using a .env File

Create a `.env` file and source it before running commands:

```bash
source .env
bt pws auth test
```

### Test Your Configuration

```bash
bt pws auth test      # Test Password Safe connection
bt entitle auth test  # Test Entitle connection
bt pra auth test      # Test PRA connection
bt epmw auth test     # Test EPM Windows connection
```

---

## Command Reference

### Password Safe (`bt pws`)

#### Systems
```bash
bt pws systems list                    # List all managed systems
bt pws systems list -o json            # Output as JSON
bt pws systems get <system-id>         # Get system details
bt pws systems create -n "name" -i "10.0.1.50" -w <workgroup-id> -p <platform-id>
bt pws systems delete <system-id>
```

#### Accounts
```bash
bt pws accounts list                   # List all managed accounts
bt pws accounts list -s <system-id>    # List accounts for a system
bt pws accounts get <account-id>       # Get account details
```

#### Credentials (Checkout/Checkin)
```bash
bt pws credentials request <system> <account>     # Request credential checkout
bt pws credentials show <request-id>              # Show checked-out password
bt pws credentials checkin <request-id>           # Check in credential
```

#### Secrets Safe
```bash
bt pws secrets safes list              # List safes
bt pws secrets folders list <safe>     # List folders in a safe
bt pws secrets list <safe> <folder>    # List secrets
bt pws secrets get <safe> <folder> <title>        # Get secret value
bt pws secrets create <safe> <folder> <title> <value>
```

#### Quick Commands (Workflows)
```bash
# Checkout a credential (combines request + show)
bt pws quick checkout -s "system-name" -a "account-name"
bt pws quick checkout -s "system-name" -a "account-name" --raw  # Password only

# Onboard a new system with account
bt pws quick onboard -n "hostname" -i "10.0.1.50" -w <workgroup-id> -f <functional-account-id>

# Offboard (remove system and accounts)
bt pws quick offboard -s "system-name"
```

#### Other Commands
```bash
bt pws workgroups list                 # List workgroups
bt pws platforms list                  # List platforms
bt pws functional list                 # List functional accounts
```

---

### Entitle (`bt entitle`)

#### Integrations
```bash
bt entitle integrations list           # List all integrations
bt entitle integrations get <id>       # Get integration details
```

#### Resources
```bash
bt entitle resources list              # List all resources
bt entitle resources list -s "search"  # Search resources
bt entitle resources get <id>          # Get resource details
```

#### Bundles
```bash
bt entitle bundles list                # List access bundles
bt entitle bundles get <id>            # Get bundle details
```

#### Workflows
```bash
bt entitle workflows list              # List approval workflows
bt entitle workflows get <id>          # Get workflow details
```

#### Permissions
```bash
bt entitle permissions list            # List all permissions
bt entitle permissions list -u <user>  # List user's permissions
bt entitle permissions revoke <id>     # Revoke a permission
```

#### Users
```bash
bt entitle users list                  # List users
bt entitle users get <id>              # Get user details
```

---

### PRA (`bt pra`)

#### Jump Items - Shell (SSH)
```bash
bt pra jump-items shell list           # List SSH jump items
bt pra jump-items shell get <id>       # Get jump item details
bt pra jump-items shell create -n "name" -h "hostname" -j <jumpoint-id> -g <jump-group-id>
bt pra jump-items shell delete <id>
```

#### Jump Items - RDP
```bash
bt pra jump-items rdp list             # List RDP jump items
bt pra jump-items rdp create -n "name" -h "hostname" -j <jumpoint-id> -g <jump-group-id>
```

#### Vault Accounts
```bash
bt pra vault list                      # List vault accounts
bt pra vault get <id>                  # Get vault account details
bt pra vault checkout <id>             # Checkout credentials
bt pra vault checkin <id>              # Checkin credentials
bt pra vault rotate <id>               # Rotate password
```

#### Jump Groups
```bash
bt pra jump-groups list                # List jump groups
bt pra jump-groups get <id>            # Get group details
bt pra jump-groups create -n "name"    # Create jump group
```

#### Jumpoints
```bash
bt pra jumpoints list                  # List jumpoints
bt pra jumpoints get <id>              # Get jumpoint details
```

#### Quick Commands
```bash
# Create shell jump with vault account
bt pra quick shell-jump -n "name" -h "host" -j <jumpoint> -g <group> --vault-account <account-id>
```

---

### EPM Windows (`bt epmw`)

#### Computers
```bash
bt epmw computers list                 # List managed computers
bt epmw computers list -o json         # Output as JSON
bt epmw computers get <id>             # Get computer details
bt epmw computers archive <id>         # Archive (remove) computer
```

#### Groups
```bash
bt epmw groups list                    # List computer groups
bt epmw groups get <id>                # Get group details
```

#### Policies
```bash
bt epmw policies list                  # List policies
bt epmw policies get <id>              # Get policy details
bt epmw policies download <id>         # Download policy XML
```

#### Admin Requests
```bash
bt epmw requests list                  # List pending requests
bt epmw requests list --status approved
bt epmw requests approve <id>          # Approve request
bt epmw requests deny <id> -r "reason" # Deny request
```

#### Events & Audits
```bash
bt epmw events list                    # List recent events
bt epmw events list --hours 48         # Events from last 48 hours
bt epmw events search -q "keyword"     # Search events
bt epmw audits list                    # List audit logs
```

---

### Cross-Product Commands (`bt quick`)

For environments with both Password Safe and PRA (PASM):

```bash
# Onboard system to both PWS and PRA
bt quick pasm-onboard -n "hostname" -i "10.0.1.50" -w <workgroup> -j <jumpoint> -g <jump-group>

# Offboard from both
bt quick pasm-offboard -n "hostname"

# Search across both products
bt quick pasm-search -q "hostname"
```

---

## Output Formats

All list commands support multiple output formats:

```bash
bt pws systems list              # Default table format
bt pws systems list -o json      # JSON output
bt pws systems list -o json | jq # Pipe to jq for processing
```

### Scripting with Raw Output

```bash
# Get just the password for scripting
PASSWORD=$(bt pws quick checkout -s "server" -a "admin" --raw)

# Use in SSH
sshpass -p "$PASSWORD" ssh admin@server
```

---

## Concepts

### Password Safe: Functional vs Managed Accounts

**Functional accounts** are service accounts used BY Password Safe to connect to and manage systems. They perform password rotation, discovery, and other automated tasks.

**Managed accounts** are the accounts ON systems that Password Safe stores and rotates passwords for. These are what users check out.

```bash
# List functional accounts (for system management)
bt pws functional list

# List managed accounts (for checkout)
bt pws accounts list
```

### PRA: Jump Items and Jumpoints

**Jumpoints** are agents installed in your network that facilitate connections. **Jump items** are the actual connection definitions (SSH, RDP, etc.) that use jumpoints.

```bash
# Find available jumpoints
bt pra jumpoints list

# Create a jump item using a jumpoint
bt pra jump-items shell create -n "my-server" -h "10.0.1.50" -j <jumpoint-id> -g <group-id>
```

---

## Troubleshooting

### Authentication Errors

```bash
# Test connectivity
bt pws auth test

# Enable debug output to see API calls
export BT_SHOW_REST=true
bt pws systems list
```

### SSL Certificate Issues

For self-signed certificates (not recommended for production):

```bash
export BT_SSL_INSECURE_ALLOW=true
```

### Common Issues

| Error | Solution |
|-------|----------|
| 401 Unauthorized | Check credentials in environment variables |
| 403 Forbidden | Verify API user has required permissions |
| 404 Not Found | Check API URL format and resource IDs |
| Connection refused | Verify URL and network connectivity |
| EPMW 405 on delete | Use `archive` instead of `delete` for computers |

---

## License

MIT License - This is an unofficial tool not affiliated with or supported by BeyondTrust.