bt-cli 0.4.13__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,94 @@
+# BT-CLI
+
+BeyondTrust Platform CLI for Password Safe, Entitle, PRA, and EPM Windows.
+
+## Setup
+
+```bash
+# From project root
+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
+
+## Functional vs Managed Accounts
+
+**Functional accounts** (`bt pws functional`) - Service accounts used BY Password Safe to connect to systems for auto-management (password rotation, discovery). One functional account can manage many systems.
+
+**Managed accounts** (`bt pws accounts`) - User accounts ON systems that Password Safe manages (stores/rotates passwords for). These are what users check out.
+
+```bash
+# List functional accounts to find the right one for your platform
+bt pws functional list
+
+# List workgroups to find the right one
+bt pws workgroups list
+
+# Use functional account when onboarding a system
+bt pws quick onboard -n "server" -i "10.0.1.50" -w <WORKGROUP_ID> -f <FUNC_ACCT_ID> -e "sudo"
+```
+
+## 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,108 @@
+---
+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
+
+The CLI should be installed and configured. Test with:
+
+```bash
+bt whoami   # Verify all products are connected
+```
+
+## 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.
+
+**First, discover your environment IDs** (see "Discover Environment IDs" below).
+
+```bash
+# Linux SSH host (use IDs from your environment)
+bt quick pasm-onboard -n "my-server" -i "10.0.1.50" \
+    -w <workgroup_id> -j <jumpoint_id> -g <jump_group_id>
+
+# Full options
+bt quick pasm-onboard \
+    --name "web-01" \
+    --ip "10.0.1.100" \
+    --workgroup <workgroup_id> \
+    --jumpoint <jumpoint_id> \
+    --jump-group <jump_group_id> \
+    --functional-account <func_acct_id> \
+    --elevation "sudo" \
+    --pra-username "admin"
+
+# Windows RDP host
+bt quick pasm-onboard -n "win-srv" -i "10.0.2.10" \
+    -w <workgroup_id> -p <platform_id> -j <jumpoint_id> -g <jump_group_id> \
+    --jump-type rdp --port 3389
+
+# Skip one product
+bt quick pasm-onboard -n "pra-only" -i "10.0.1.5" -j <jumpoint_id> -g <jump_group_id> --skip-pws
+bt quick pasm-onboard -n "pws-only" -i "10.0.1.6" -w <workgroup_id> --skip-pra
+```
+
+### PASM Offboard
+Remove from both products.
+
+```bash
+bt quick pasm-offboard -n "my-server"
+bt quick pasm-offboard -n "web-01" --force
+```
+
+## Discover Environment IDs
+
+Use these commands to find the IDs for your environment:
+
+```bash
+# PWS resources
+bt pws workgroups list          # Find workgroup IDs
+bt pws functional list          # Find functional account IDs
+bt pws platforms list           # Find platform IDs
+
+# PRA resources
+bt pra jumpoint list            # Find jumpoint IDs
+bt pra jump-groups list         # Find jump group IDs
+bt pra vault groups list        # Find vault account group IDs
+
+# Entitle resources
+bt entitle integrations list    # Find integration IDs
+```
+
+## Product-Specific Skills
+
+Use `/pws`, `/pra`, `/entitle`, `/epmw` for product-specific commands.

bt_cli/data/skills/entitle/SKILL.md

@@ -0,0 +1,170 @@
+---
+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 (use integration ID from `bt entitle integrations list`)
+bt entitle resources create-virtual \
+    --name "Customer-05 (Bing7)" \
+    --integration <virtual_integration_id> \
+    --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. Find your PRA integration ID
+bt entitle integrations list | grep -i pra
+
+# 2. Trigger PRA sync in Entitle UI (or wait for hourly sync)
+
+# 3. Find the new PRA resource
+bt entitle resources list --integration <pra_integration_id>
+
+# 4. Get "Start Sessions Only" role ID
+bt entitle roles list --resource <pra_resource_id>
+
+# 5. Add to virtual integration (find ID with `bt entitle integrations list`)
+bt entitle resources create-virtual \
+    --name "Customer-05" \
+    --integration <virtual_integration_id> \
+    --source-role-id <role_id> \
+    --role-name "Start Session"
+```
+
+### Check User Access
+
+```bash
+bt entitle permissions list --user "user@example.com" -o json
+```
+
+## Discover IDs
+
+```bash
+# Find integration IDs
+bt entitle integrations list
+
+# Find workflow IDs
+bt entitle workflows list
+
+# Find resource IDs within an integration
+bt entitle resources list --integration <integration_id>
+
+# Find role IDs for a resource
+bt entitle roles list --resource <resource_id>
+```
+
+## 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