bt-cli 0.4.7__py3-none-any.whl

bt_cli/core/rest_debug.py

@@ -0,0 +1,221 @@
+"""REST API debugging module for bt-cli.
+
+Provides httpx event hooks to display API call details when --show-rest is enabled.
+"""
+
+import json
+import re
+from typing import Any, Dict
+
+import httpx
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+
+# Global flag for REST debugging
+_show_rest = False
+
+# Console for output
+_console = Console(stderr=True)
+
+
+def set_show_rest(enabled: bool) -> None:
+    """Enable or disable REST API call display."""
+    global _show_rest
+    _show_rest = enabled
+
+
+def is_show_rest() -> bool:
+    """Check if REST debugging is enabled."""
+    return _show_rest
+
+
+def _sanitize_headers(headers: httpx.Headers) -> Dict[str, str]:
+    """Sanitize headers by fully redacting sensitive values.
+
+    Security: Never show any part of sensitive values like tokens or API keys.
+    """
+    sanitized = {}
+    sensitive_patterns = [
+        r"authorization",
+        r"ps-auth",
+        r"x-api-key",
+        r"api-key",
+        r"secret",
+        r"token",
+        r"password",
+        r"bearer",
+    ]
+
+    for key, value in headers.items():
+        key_lower = key.lower()
+        is_sensitive = any(re.search(p, key_lower) for p in sensitive_patterns)
+
+        if is_sensitive and value:
+            # Fully redact sensitive values - never show any characters
+            sanitized[key] = "[REDACTED]"
+        else:
+            sanitized[key] = value
+
+    return sanitized
+
+
+def _sanitize_body(body: Any) -> Any:
+    """Sanitize request/response body by redacting sensitive fields.
+
+    Security: Redact credentials in form data and JSON bodies.
+    """
+    if body is None:
+        return None
+
+    # Sensitive field names (case-insensitive matching)
+    sensitive_fields = {
+        "password", "secret", "token", "api_key", "apikey", "api-key",
+        "client_secret", "client-secret", "clientsecret",
+        "authorization", "bearer", "credential", "credentials",
+        "access_token", "refresh_token", "id_token",
+    }
+
+    if isinstance(body, dict):
+        sanitized = {}
+        for key, value in body.items():
+            key_lower = key.lower().replace("-", "_")
+            if any(s in key_lower for s in sensitive_fields):
+                sanitized[key] = "[REDACTED]"
+            elif isinstance(value, (dict, list)):
+                sanitized[key] = _sanitize_body(value)
+            else:
+                sanitized[key] = value
+        return sanitized
+    elif isinstance(body, list):
+        return [_sanitize_body(item) for item in body]
+    else:
+        return body
+
+
+def _truncate_body(body: Any, max_length: int = 500, sanitize: bool = True) -> str:
+    """Truncate body for display.
+
+    Args:
+        body: Request/response body
+        max_length: Maximum characters to display
+        sanitize: If True, redact sensitive fields before display
+    """
+    if body is None:
+        return "(empty)"
+
+    if isinstance(body, bytes):
+        try:
+            body = body.decode("utf-8")
+        except UnicodeDecodeError:
+            return f"(binary data, {len(body)} bytes)"
+
+    # Sanitize sensitive data before display
+    if sanitize and isinstance(body, (dict, list)):
+        body = _sanitize_body(body)
+
+    if isinstance(body, (dict, list)):
+        body = json.dumps(body, indent=2)
+
+    body_str = str(body)
+    if len(body_str) > max_length:
+        return body_str[:max_length] + f"\n... ({len(body_str) - max_length} more chars)"
+    return body_str
+
+
+def log_request(request: httpx.Request) -> None:
+    """Log outgoing HTTP request."""
+    if not _show_rest:
+        return
+
+    # Build request info
+    method = request.method
+    url = str(request.url)
+    headers = _sanitize_headers(request.headers)
+
+    # Get request body if present
+    body = None
+    if request.content:
+        try:
+            body = json.loads(request.content)
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            body = request.content
+
+    # Build output
+    lines = [
+        f"[bold cyan]{method}[/bold cyan] [white]{url}[/white]",
+        "",
+        "[dim]Headers:[/dim]",
+    ]
+
+    for key, value in headers.items():
+        lines.append(f"  [green]{key}:[/green] {value}")
+
+    if body:
+        lines.append("")
+        lines.append("[dim]Body:[/dim]")
+        body_str = _truncate_body(body, max_length=300)
+        lines.append(f"  {body_str}")
+
+    _console.print(Panel(
+        "\n".join(lines),
+        title="[bold yellow]REST Request[/bold yellow]",
+        border_style="yellow",
+        expand=False,
+    ))
+
+
+def log_response(response: httpx.Response) -> None:
+    """Log HTTP response."""
+    if not _show_rest:
+        return
+
+    # Get status info
+    status_code = response.status_code
+    status_text = response.reason_phrase or ""
+
+    # Color based on status
+    if status_code < 300:
+        status_color = "green"
+    elif status_code < 400:
+        status_color = "yellow"
+    else:
+        status_color = "red"
+
+    # Get response body
+    try:
+        # Need to read the response to get body
+        response.read()
+        body = response.json()
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        body = response.text if response.text else "(empty)"
+    except Exception:
+        body = "(could not read response)"
+
+    # Build output
+    lines = [
+        f"[bold {status_color}]{status_code} {status_text}[/bold {status_color}]",
+        "",
+        "[dim]Response Body:[/dim]",
+        _truncate_body(body, max_length=500),
+    ]
+
+    _console.print(Panel(
+        "\n".join(lines),
+        title="[bold blue]REST Response[/bold blue]",
+        border_style="blue",
+        expand=False,
+    ))
+    _console.print()  # Add spacing between calls
+
+
+def get_event_hooks() -> Dict[str, list]:
+    """Get httpx event hooks for request/response logging.
+
+    Usage:
+        client = httpx.Client(event_hooks=get_event_hooks())
+    """
+    return {
+        "request": [log_request],
+        "response": [log_response],
+    }

bt_cli/data/CLAUDE.md

@@ -0,0 +1,88 @@
+# BT-Admin CLI
+
+BeyondTrust Platform CLI for Password Safe, Entitle, PRA, and EPM Windows.
+
+## Setup
+
+```bash
+cd /home/admin/entitl-sko/bt-cli
+source .venv/bin/activate && source .env
+bt whoami   # Test all connections
+```
+
+## Skills Available
+
+Use these slash commands for detailed product guidance:
+
+| Skill | Purpose |
+|-------|---------|
+| `/bt` | Cross-product commands (PASM onboard/offboard/search) |
+| `/pws` | Password Safe - credentials, systems, secrets |
+| `/pra` | PRA - jump items, vault, SSH CA |
+| `/entitle` | Entitle - JIT access, bundles, workflows |
+| `/epmw` | EPM Windows - computers, policies, requests |
+
+## Command Structure
+
+| Product | Command | Key Operations |
+|---------|---------|----------------|
+| Cross-product | `bt quick` | `pasm-onboard`, `pasm-offboard`, `pasm-search` |
+| Password Safe | `bt pws` | `systems`, `accounts`, `credentials`, `secrets`, `quick` |
+| PRA | `bt pra` | `jump-items`, `vault`, `jump-groups`, `quick` |
+| Entitle | `bt entitle` | `integrations`, `resources`, `bundles`, `permissions` |
+| EPM Windows | `bt epmw` | `computers`, `groups`, `policies`, `requests`, `quick` |
+
+## Common Patterns
+
+```bash
+# All list commands support JSON output
+bt pws systems list -o json
+bt pra jump-items shell list -o json
+
+# Quick commands combine multiple API calls
+bt pws quick checkout -s "system" -a "account"
+bt pws quick onboard -n "host" -i "10.0.1.50" -w 3
+
+# Raw output for scripting
+PASSWORD=$(bt pws quick checkout -s server -a admin --raw)
+```
+
+## API Quirks (Gotchas)
+
+| Product | Pagination | Response Format |
+|---------|------------|-----------------|
+| PWS | `limit`/`offset` | `{"TotalCount": N, "Data": [...]}` |
+| Entitle | `page`/`perPage` | `{"result": [...], "pagination": {...}}` |
+| PRA | `per_page`/`current_page` (1-indexed) | Array (pagination in headers) |
+| EPMW | `pageNumber`/`pageSize` | `{"data": [...], "totalCount": N}` |
+
+**Important:**
+- EPMW computers: Use `archive` not `delete` (405 error)
+- PRA K8s tunnels: Require Linux jumpoint
+- PWS assets: Must create via workgroup endpoint
+- ECM integration: PWS system name must match PRA jump item name
+
+## Key Reference IDs
+
+| Resource | ID | Notes |
+|----------|-----|-------|
+| PWS Workgroup AWS | 3 | |
+| PWS Workgroup Datacenter | 2 | |
+| PWS Functional Account | 7 | SSH key auth |
+| PRA Jumpoint AWS | 3 | |
+| PRA Jumpoint Datacenter | 2 | |
+| PRA ec2-admin SSH CA | 31 | For EC2 provisioning |
+
+## Project Structure
+
+```
+src/bt_cli/
+├── cli.py              # Root dispatcher
+├── core/               # Shared (config, auth, output)
+├── pws/                # Password Safe
+├── pra/                # PRA
+├── entitle/            # Entitle
+└── epmw/               # EPM Windows
+```
+
+Each product follows: `client/` (API), `commands/` (CLI), `models/` (Pydantic)

bt_cli/data/skills/bt/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: bt
+description: BeyondTrust platform CLI cross-product commands. Use when working across PWS, PRA, Entitle, or EPMW together, or for PASM workflows combining Password Safe and PRA.
+---
+
+# BT-Admin Cross-Product Commands
+
+CLI for BeyondTrust platform: Password Safe, PRA, Entitle, EPM Windows.
+
+## IMPORTANT: Destructive Operations
+
+**ALWAYS confirm with the user before running destructive commands:**
+- `delete` - Removes resources permanently
+- `offboard` - Removes systems/accounts from management
+- `archive` - Archives computers (EPMW)
+- `revoke` - Revokes permissions (Entitle)
+
+Before executing any destructive operation:
+1. List what will be affected
+2. Ask user for explicit confirmation
+3. Never use `--force` flag without user approval
+
+## Setup
+
+```bash
+cd /home/admin/entitl-sko/bt-cli
+source .venv/bin/activate && source .env
+```
+
+## Test All Connections
+
+```bash
+bt whoami                    # Test all configured products
+bt whoami -o json            # JSON output
+```
+
+## Cross-Product Quick Commands (`bt quick`)
+
+### PASM Search (PWS + PRA)
+Find systems/accounts across both products. Shows ECM alignment (names must match for credential injection).
+
+```bash
+bt quick pasm-search axion
+bt quick pasm-search web-server -o json
+```
+
+### PASM Onboard (PWS + PRA)
+Onboard a host to both Password Safe and PRA in one command.
+
+```bash
+# Linux SSH host
+bt quick pasm-onboard -n "my-server" -i "10.0.1.50" -w 3 -j 3 -g 24
+
+# Full options
+bt quick pasm-onboard \
+    --name "web-01" \
+    --ip "10.0.1.100" \
+    --workgroup 3 \
+    --jumpoint 3 \
+    --jump-group 24 \
+    --functional-account 7 \
+    --elevation "sudo" \
+    --pra-username "ec2-admin"
+
+# Windows RDP host
+bt quick pasm-onboard -n "win-srv" -i "10.0.2.10" -w 2 -p 1 -j 3 -g 31 --jump-type rdp --port 3389
+
+# Skip one product
+bt quick pasm-onboard -n "pra-only" -i "10.0.1.5" -j 3 -g 24 --skip-pws
+bt quick pasm-onboard -n "pws-only" -i "10.0.1.6" -w 3 --skip-pra
+```
+
+### PASM Offboard
+Remove from both products.
+
+```bash
+bt quick pasm-offboard -n "my-server"
+bt quick pasm-offboard -n "web-01" --force
+```
+
+## Environment Reference IDs
+
+| Resource | ID | Notes |
+|----------|-----|-------|
+| PWS Workgroup (AWS) | 3 | AWS_Account Workgroup |
+| PWS Workgroup (Datacenter) | 2 | Datacenter_West |
+| PWS Functional Account | 7 | pws-functional SSH key |
+| PWS Platform Linux | 2 | |
+| PWS Platform Windows | 1 | |
+| PRA Jumpoint (AWS) | 3 | AWS Account |
+| PRA Jumpoint (Datacenter) | 2 | Data Center 01 |
+| PRA Vault Account (ec2-admin) | 31 | SSH CA for EC2 |
+| Entitle PRA Integration | bb2a3c79-02a9-45d9-be7f-f209d97cb1d7 | |
+| Entitle Customer Access | 22f4960f-b2ee-435f-9fa2-b82baeca06b2 | Virtual integration |
+
+## Product-Specific Skills
+
+Use `/pws`, `/pra`, `/entitle`, `/epmw` for product-specific commands.

bt_cli/data/skills/entitle/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: entitle
+description: Entitle commands for JIT access, bundles, workflows, and permissions. Use when working with access requests, approval workflows, or managing user entitlements.
+---
+
+# Entitle Commands (`bt entitle`)
+
+## IMPORTANT: Destructive Operations
+
+**ALWAYS confirm with the user before:**
+- `bt entitle resources delete` - Deletes resource from integration
+- `bt entitle bundles delete` - Deletes access bundle
+- `bt entitle permissions revoke` - Revokes active permission
+
+List affected resources first, then ask for explicit confirmation.
+
+## Integrations & Resources
+
+```bash
+# List integrations (connected apps)
+bt entitle integrations list
+bt entitle integrations get <integration_id>
+
+# List resources in an integration
+bt entitle resources list --integration <integration_id>
+bt entitle resources get <resource_id>
+
+# Virtual integration resources
+bt entitle resources create-virtual \
+    --name "Customer-05 (Bing7)" \
+    --integration 22f4960f-b2ee-435f-9fa2-b82baeca06b2 \
+    --source-role-id <role_id> \
+    --role-name "Start Session"
+bt entitle resources delete <resource_id>
+```
+
+## Bundles
+
+Access bundles group multiple roles across integrations.
+
+```bash
+bt entitle bundles list
+bt entitle bundles get <bundle_id>
+bt entitle bundles create \
+    --name "Dev AWS Access" \
+    --description "Development AWS console access" \
+    --workflow <workflow_id> \
+    --role <role_id> \
+    --duration 3600
+bt entitle bundles delete <bundle_id>
+```
+
+## Workflows
+
+```bash
+bt entitle workflows list
+bt entitle workflows get <workflow_id>
+```
+
+**Available Workflows:**
+| Name | Type | Use Case |
+|------|------|----------|
+| Auto Approve | Automatic | Requests <= 12 hours |
+| Low sensitivity | Simple | Single approver |
+| Medium Sensitivity | Standard | Standard approval |
+| Production access | Multi-step | Duration-based tiers |
+
+## Users & Permissions
+
+```bash
+# Users
+bt entitle users list
+bt entitle users get <user_id>
+
+# Active permissions
+bt entitle permissions list
+bt entitle permissions list --user <user_id>
+bt entitle permissions revoke <permission_id>
+
+# Accounts
+bt entitle accounts list --integration <integration_id>
+```
+
+## Roles & Policies
+
+```bash
+bt entitle roles list
+bt entitle roles list --resource <resource_id>
+bt entitle roles get <role_id>
+
+bt entitle policies list
+bt entitle policies get <policy_id>
+```
+
+## Common Workflows
+
+### Add PRA Jump Group to Entitle
+
+**Important:** PRA integration sync is **asynchronous** (runs hourly). After creating a new PRA jump group, either:
+- Wait up to 1 hour for auto-sync
+- Or manually trigger sync in Entitle UI: Integrations → PRA → Sync Now
+
+```bash
+# 1. Trigger PRA sync in Entitle UI (or wait for hourly sync)
+
+# 2. Find the new PRA resource
+bt entitle resources list --integration bb2a3c79-02a9-45d9-be7f-f209d97cb1d7
+
+# 3. Get "Start Sessions Only" role ID
+bt entitle roles list --resource <pra_resource_id>
+
+# 4. Add to Customer Access virtual integration
+bt entitle resources create-virtual \
+    --name "Customer-05" \
+    --integration 22f4960f-b2ee-435f-9fa2-b82baeca06b2 \
+    --source-role-id <role_id> \
+    --role-name "Start Session"
+```
+
+### Check User Access
+
+```bash
+bt entitle permissions list --user "user@example.com" -o json
+```
+
+## Key IDs
+
+| Resource | ID |
+|----------|-----|
+| PRA Integration | bb2a3c79-02a9-45d9-be7f-f209d97cb1d7 |
+| Customer Access (Virtual) | 22f4960f-b2ee-435f-9fa2-b82baeca06b2 |
+| AWS SandBox | (check `bt entitle integrations list`) |
+
+## Integrations Available
+
+- Cloud10 (Virtual Application)
+- NexusDyn - Azure
+- Customer Access (Virtual)
+- Privileged Remote Access (PRA)
+- AWS - SandBox Account
+- Nexusdyn - Postgres ERP Database
+- NexusDyn - EntraID
+
+## Supported Applications (75+)
+
+**Cloud:** AWS, Azure, GCP, Oracle OCI
+**Identity:** Okta, Entra ID, OneLogin, JumpCloud
+**DevOps:** GitHub, GitLab, Jenkins, Terraform Cloud
+**Databases:** Postgres, MySQL, MSSQL, MongoDB, Snowflake
+**Kubernetes:** EKS, AKS, GKE, Rancher
+**BeyondTrust:** Password Safe, PRA, Remote Support
+
+## API Notes
+
+- Base path: `/public/v1`
+- Pagination: `page`/`perPage`
+- Response: `{"result": [...], "pagination": {...}}`
+- All IDs are UUIDs (strings)
+- Bearer token auth

bt_cli/data/skills/epmw/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: epmw
+description: EPM Windows commands for endpoint privilege management. Use when working with Windows computers, policies, admin access requests, or audit logs.
+---
+
+# EPM Windows Commands (`bt epmw`)
+
+## IMPORTANT: Destructive Operations
+
+**ALWAYS confirm with the user before:**
+- `bt epmw computers archive` - Archives computer from management
+- `bt epmw groups delete` - Deletes computer group
+- `bt epmw policies delete` - Deletes policy
+- `bt epmw quick stale --delete` - Deletes stale computers
+
+List affected resources first, then ask for explicit confirmation.
+
+## Quick Commands
+
+```bash
+# Find stale computers (not checked in recently)
+bt epmw quick stale                     # 24+ hours
+bt epmw quick stale --hours 48          # 48+ hours
+bt epmw quick stale -h 12 -g "Workstations"
+
+# Delete stale computers
+bt epmw quick stale --delete            # With confirmation
+bt epmw quick stale --delete --force    # Skip confirmation
+
+# Find disconnected computers
+bt epmw quick disconnected
+bt epmw quick disconnected -g "Servers"
+
+# Status summary by group
+bt epmw quick status
+bt epmw quick status -g "Datacenter"
+```
+
+## Computers
+
+```bash
+bt epmw computers list
+bt epmw computers list -o json
+bt epmw computers get <computer_id>
+bt epmw computers delete <computer_id>
+bt epmw computers archive <computer_id>
+bt epmw computers unarchive <computer_id>
+```
+
+## Groups
+
+```bash
+bt epmw groups list
+bt epmw groups get <group_id>
+bt epmw groups create --name "NewGroup" --description "Description"
+bt epmw groups update <group_id> --name "UpdatedName"
+bt epmw groups delete <group_id>
+bt epmw groups assign-policy <group_id> --policy <policy_id>
+bt epmw groups assign-computers <group_id> --computers <id1>,<id2>
+```
+
+## Policies
+
+```bash
+bt epmw policies list
+bt epmw policies get <policy_id>
+bt epmw policies groups <policy_id>      # Show assigned groups
+
+# Download policy XML (for template)
+bt epmw policies download <policy_id> > template.xml
+
+# Create policy from XML
+bt epmw policies create -n "My Policy" -f template.xml
+
+# Policy revisions
+bt epmw policies revisions list <policy_id>
+bt epmw policies revisions get <policy_id> <revision_id>
+bt epmw policies revisions upload <policy_id> -f policy.xml
+```
+
+## Admin Access Requests
+
+```bash
+bt epmw requests list
+bt epmw requests get <request_id>
+bt epmw requests create --computer <id> --duration 30 --reason "Maintenance"
+bt epmw requests approve <request_id>
+bt epmw requests deny <request_id> --reason "Not authorized"
+```
+
+## Users & Roles
+
+```bash
+bt epmw users list
+bt epmw users get <user_id>
+bt epmw users create --username "newuser" --email "user@example.com"
+bt epmw users enable <user_id>
+bt epmw users disable <user_id>
+bt epmw users assign-roles <user_id> --roles <role1>,<role2>
+
+bt epmw roles list
+bt epmw roles get <role_id>
+```
+
+## Audits
+
+```bash
+# Activity audits
+bt epmw audits activity list
+bt epmw audits activity get <audit_id>
+
+# Authorization requests
+bt epmw audits authorization list
+bt epmw audits authorization get <audit_id>
+
+# Request audits
+bt epmw audits requests list
+bt epmw audits requests get <audit_id>
+```
+
+## Key Groups
+
+| ID | Name | Computers |
+|----|------|-----------|
+| 042267ec-... | Servers - Datacenter1 | CorpMem01, CorpMem02 |
+| 1c8f6310-... | Workstations - Datacenter1 | CorpWS01, CorpWS02 |
+| 67ca23ad-... | Engineering | BenC-Skynet |
+
+## Key Computers
+
+| Host | Domain | Group | Status |
+|------|--------|-------|--------|
+| CorpMem01 | nexusdyn.corp | Servers | Connected |
+| CorpMem02 | nexusdyn.corp | Servers | Connected |
+| CorpWS01 | nexusdyn.corp | Workstations | Connected |
+| CorpWS02 | nexusdyn.corp | Workstations | Connected |
+
+## API Notes
+
+- Base path: `/management-api/v3`
+- Token endpoint: `/oauth/token`
+- Pagination: `pageNumber`/`pageSize`
+- Response: `{"data": [...], "totalCount": N}`
+- All IDs are UUIDs
+- Delete returns 405 - use archive instead