bt-cli 0.4.58__tar.gz → 0.4.59__tar.gz

{bt_cli-0.4.58 → bt_cli-0.4.59}/CLAUDE.md

@@ -1,6 +1,6 @@
 # BT-CLI
 
-BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, EPM Linux, and the BeyondTrust Secrets API. **Version: 0.4.58**
+BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, EPM Linux, and the BeyondTrust Secrets API. **Version: 0.4.59**
 
 ## Setup
 
@@ -81,6 +81,10 @@ PASSWORD=$(bt pws quick checkout -s server -a admin --raw)
 - PRA K8s tunnels: Require Linux jumpoint
 - PWS assets: Must create via workgroup endpoint
 - ECM integration: PWS system name must match PRA jump item name
+- **PRA `-o json` is pure JSON on stdout** — all human status/error banners go to **stderr** (`core/output.py` `err_console`), so `... -o json | jq` is safe. API 4xx `errors` objects are surfaced field-by-field, not collapsed to "Validation Failed".
+- **PRA tunnel create gates fields by `tunnel_type`**: tcp→`--ports`, mssql→`--username`/`--database`, k8s→`--url`/`--ca-cert`. **psql/mysql are created BARE** — the public Config API has no write path for their username/database (POST rejects, PATCH no-ops, PUT 405s) though GET shows them; CLI warns + ignores those flags. Set in `/login` UI.
+- **PRA `export jump-items` defaults to a REAL export** (all types: shell/rdp/vnc/web/tunnel, full type-specific columns) that round-trips through `import jump-items`; `--sample` gives the blank template. `bt pra jump-items web create` exists.
+- **PRA vault `associate -t protocol_tunnel` is MSSQL-only** (live-verified): server rejects psql/mysql/tcp/k8s with "Only SQL Server Tunnels are allowed" — use tag/criteria association for those. **TCP `--ports` needs listen;destination *pairs*** (even count; odd → 400 "number of parameters is invalid"). Jumpoint listing is `bt pra jumpoints list` (plural).
 - **PWS `/Sessions` ignores `limit`/`offset`** and returns the full session *history* every call — never `paginate()` it (infinite loop); `list_sessions` does a single GET and `bt pws sessions list` caps display client-side. `Status` codes (live-confirmed): 0=Not started, 1=Active, 2=Completed, 5=Locked, 7=Terminated; `--active`=Status 1. Active sessions have `EndTime`==`StartTime` (placeholder, not null) — identify live sessions by Status, not timestamps. **`terminate` = `POST /Sessions/{id}/Terminate`** (symmetric w/ `/Lock`); `/Sessions/{id}` is GET/PUT only (DELETE → 405).
 - Entitle permissions: Use server-side filters (`--resource`, `--user`, `--integration`) - dataset can be 20k+ records
 - Entitle users: Use `--all` flag only when needed - default fetches first page only

{bt_cli-0.4.58 → bt_cli-0.4.59}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bt-cli
-Version: 0.4.58
+Version: 0.4.59
 Summary: BeyondTrust Platform CLI (unofficial) - Password Safe, Entitle, PRA, EPM
 Author-email: Dave Grendysz <dgrendysz@beyondtrust.com>
 License: MIT

{bt_cli-0.4.58 → bt_cli-0.4.59}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bt-cli"
-version = "0.4.58"
+version = "0.4.59"
 description = "BeyondTrust Platform CLI (unofficial) - Password Safe, Entitle, PRA, EPM"
 readme = "README.md"
 requires-python = ">=3.9"

{bt_cli-0.4.58 → bt_cli-0.4.59}/src/bt_cli/__init__.py

@@ -1,3 +1,3 @@
 """BeyondTrust Unified Admin CLI."""
 
-__version__ = "0.4.58"
+__version__ = "0.4.59"

{bt_cli-0.4.58 → bt_cli-0.4.59}/src/bt_cli/core/errors.py

@@ -121,6 +121,44 @@ HTTP_STATUS_MESSAGES = {
 }
 
 
+def _format_field_errors(response: dict) -> Optional[str]:
+    """Flatten an API's field-level validation errors into one readable string.
+
+    Looks for the common ``errors`` / ``field_errors`` / ``validationErrors``
+    containers, which map a field name to either a message string or a list of
+    message strings. Returns e.g. ``"username: only allowed when tunnel_type is
+    mssql; database: only allowed when tunnel_type is mssql"`` or None if no
+    field errors are present.
+
+    Args:
+        response: The (already sanitized) parsed JSON response body
+
+    Returns:
+        A flattened "field: message" string, or None
+    """
+    for key in ("errors", "field_errors", "fieldErrors", "validationErrors"):
+        container = response.get(key)
+        if not container:
+            continue
+
+        parts: list[str] = []
+        if isinstance(container, dict):
+            for field, messages in container.items():
+                if isinstance(messages, (list, tuple)):
+                    joined = ", ".join(str(m) for m in messages)
+                else:
+                    joined = str(messages)
+                parts.append(f"{field}: {joined}" if field else joined)
+        elif isinstance(container, (list, tuple)):
+            parts.extend(str(m) for m in container)
+        else:
+            parts.append(str(container))
+
+        if parts:
+            return "; ".join(parts)
+    return None
+
+
 def get_http_error_message(error: httpx.HTTPStatusError) -> str:
     """Map HTTP status error to user-friendly message.
 
@@ -161,6 +199,17 @@ def get_http_error_message(error: httpx.HTTPStatusError) -> str:
                 detail = err.get("message")
             elif isinstance(err, str):
                 detail = err
+
+        # Append field-level validation details. Many APIs (e.g. PRA Config
+        # API) return a generic top-level "Validation Failed" message plus an
+        # "errors" object keyed by field name, e.g.:
+        #   {"message": "Validation Failed",
+        #    "errors": {"username": ["only allowed when tunnel_type is mssql"]}}
+        # Surfacing those field messages is what lets a user self-diagnose.
+        if isinstance(sanitized_response, dict):
+            field_errors = _format_field_errors(sanitized_response)
+            if field_errors:
+                detail = f"{detail} ({field_errors})" if detail else field_errors
     except Exception:
         # Response may not be JSON
         pass

{bt_cli-0.4.58 → bt_cli-0.4.59}/src/bt_cli/core/output.py

@@ -19,12 +19,21 @@ class OutputFormat(str, Enum):
     JSON = "json"
 
 
-# Shared console instance
+# Shared console instances.
+#
+# `console` is for machine-consumable output (JSON, tables, raw values) and
+# writes to stdout. `err_console` is for human-facing status/diagnostics
+# (success/error/warning/info banners) and writes to stderr.
+#
+# Keeping these separate is what lets `-o json` produce *pure* JSON on stdout:
+# a "Created X (ID: N)" status line goes to stderr, so `... -o json | jq` and
+# `json.load(stdin)` see only the JSON document.
 console = Console()
+err_console = Console(stderr=True)
 
 
 def print_json(data: Any) -> None:
-    """Print data as formatted JSON.
+    """Print data as formatted JSON to stdout.
 
     Args:
         data: Any JSON-serializable data
@@ -137,39 +146,42 @@ def _format_value(value: Any) -> str:
 
 
 def print_success(message: str) -> None:
-    """Print a success message.
+    """Print a success message to stderr.
+
+    Status/diagnostic output goes to stderr so it never pollutes stdout data
+    (e.g. ``-o json`` output that may be piped into a parser).
 
     Args:
         message: Message to display
     """
-    console.print(f"[green]{escape(message)}[/green]")
+    err_console.print(f"[green]{escape(message)}[/green]")
 
 
 def print_error(message: str) -> None:
-    """Print an error message.
+    """Print an error message to stderr.
 
     Args:
         message: Error message to display
     """
-    console.print(f"[red]Error:[/red] {escape(message)}")
+    err_console.print(f"[red]Error:[/red] {escape(message)}")
 
 
 def print_warning(message: str) -> None:
-    """Print a warning message.
+    """Print a warning message to stderr.
 
     Args:
         message: Warning message to display
     """
-    console.print(f"[yellow]Warning:[/yellow] {escape(message)}")
+    err_console.print(f"[yellow]Warning:[/yellow] {escape(message)}")
 
 
 def print_info(message: str) -> None:
-    """Print an info message.
+    """Print an info message to stderr.
 
     Args:
         message: Info message to display
     """
-    console.print(f"[blue]{escape(message)}[/blue]")
+    err_console.print(f"[blue]{escape(message)}[/blue]")
 
 
 def confirm_action(message: str, default: bool = False) -> bool:
@@ -203,4 +215,4 @@ def print_api_error(error: Exception, operation: str) -> None:
         operation: Description of the operation that failed (e.g., "list systems")
     """
     message = handle_api_error(error, operation)
-    console.print(f"[red]Error:[/red] {escape(message)}")
+    err_console.print(f"[red]Error:[/red] {escape(message)}")

bt_cli-0.4.59/src/bt_cli/data/skills/pra/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: pra
+description: Privileged Remote Access commands for jump items, vault accounts, and remote sessions. Use when working with PRA shell jumps, RDP, protocol tunnels, or SSH CA authentication.
+---
+
+# PRA Commands (`bt pra`)
+
+## IMPORTANT: Destructive Operations
+
+**ALWAYS confirm with the user before:**
+- `bt pra jump-items shell delete` - Deletes shell jump item
+- `bt pra jump-items rdp delete` - Deletes RDP jump item
+- `bt pra jump-items web delete` - Deletes web jump item
+- `bt pra jump-items tunnel delete` - Deletes protocol tunnel
+- `bt pra jump-groups delete` - Deletes jump group
+- `bt pra vault accounts delete` - Deletes vault account
+
+List affected resources first, then ask for explicit confirmation.
+
+## Quick Commands
+
+```bash
+# Vault credential checkout
+bt pra quick vault                      # Interactive - shows accounts, prompts
+bt pra quick vault -n "server-admin"
+bt pra quick vault -n postgres --raw
+
+# Search jump items and vault
+bt pra quick search axion
+bt pra quick search admin -o json
+```
+
+## Jump Items
+
+### Shell Jump (SSH/Telnet)
+
+```bash
+bt pra jump-items shell list
+bt pra jump-items shell get <jump_item_id>
+bt pra jump-items shell create \
+    --name "web-server-01" \
+    --hostname "10.0.1.50" \
+    --jumpoint <jumpoint_id> \
+    --jump-group <jump_group_id> \
+    --protocol ssh \
+    --port 22 \
+    --username "admin"
+bt pra jump-items shell delete <jump_item_id>
+```
+
+### RDP Jump
+
+```bash
+bt pra jump-items rdp list
+bt pra jump-items rdp get <jump_item_id>
+bt pra jump-items rdp create \
+    --name "win-server-01" \
+    --hostname "10.0.2.10" \
+    --jumpoint <jumpoint_id> \
+    --jump-group <jump_group_id> \
+    --port 3389
+```
+
+### Web Jump
+
+```bash
+bt pra jump-items web list
+bt pra jump-items web get <jump_item_id>
+bt pra jump-items web create \
+    --name "Grafana" \
+    --url "https://grafana.example.com" \
+    --jumpoint <jumpoint_id> \
+    --jump-group <jump_group_id> \
+    --username-format "{username}" \
+    --authentication-timeout 30
+    # --no-verify-certificate to skip TLS verification
+```
+
+### Protocol Tunnels (TCP/MSSQL/PostgreSQL/MySQL/K8s)
+
+```bash
+bt pra jump-items tunnel list
+
+# TCP — port pairs via --ports
+bt pra jump-items tunnel create -n tcp-jump -h 10.0.0.1 -j <jp> -g <jg> \
+    --type tcp --ports "22;24;26;28"
+
+# MSSQL — username/database are settable
+bt pra jump-items tunnel create -n sql -h 10.0.0.3 -j <jp> -g <jg> \
+    --type mssql --username sa --database demo
+
+# PostgreSQL / MySQL — created BARE (see limitation below)
+bt pra jump-items tunnel create -n pg -h 10.0.0.2 -j <jp> -g <jg> --type psql
+
+# K8s — requires Linux jumpoint
+bt pra jump-items tunnel create -n production-k8s -h k8s-api.example.com \
+    -j <jp> -g <jg> --type k8s \
+    --url "https://k8s-api.example.com:6443" --ca-cert "$(cat /path/to/ca.crt)"
+```
+
+**Per-type field gating (CLI sends only what the endpoint accepts):**
+
+| tunnel_type | type-specific fields |
+|-------------|----------------------|
+| tcp         | `--ports` (tunnel_definitions — **listen;destination pairs**, even count: `"5432;5432"` or `"22;24;26;28"`; an odd count 400s) |
+| mssql       | `--username`, `--database` |
+| psql/mysql  | none — created bare |
+| k8s         | `--url`, `--ca-cert` |
+
+**psql/mysql limitation:** the public Config API has no working write path for a
+PostgreSQL/MySQL tunnel's username/database (POST rejects them, PATCH no-ops, PUT
+405s) — even though they appear populated on GET. The CLI ignores
+`--username`/`--database` for those types (with a warning) and creates the tunnel
+bare. Set the user/db afterward in the `/login` web UI.
+
+## Jump Groups
+
+```bash
+bt pra jump-groups list
+bt pra jump-groups get <group_id>
+bt pra jump-groups create \
+    --name "Customer-05" \
+    --code-name customer05 \
+    --comments "New customer environment"
+bt pra jump-groups delete <group_id>
+```
+
+## Vault Accounts
+
+```bash
+bt pra vault accounts list
+bt pra vault accounts get <account_id>
+bt pra vault accounts checkout <account_id>
+bt pra vault accounts checkin <account_id>
+bt pra vault accounts rotate <account_id>
+
+# SSH CA - get public key for provisioning
+bt pra vault accounts get-public-key <ssh_ca_account_id>
+
+# Associate a vault account with a jump item (credential injection)
+bt pra vault accounts associate <account_id> -j <jump_item_id> -t shell_jump
+# --type: shell_jump | remote_rdp | remote_vnc | web_jump | protocol_tunnel
+```
+
+Direct per-item association works for shells, RDP, VNC and web jumps. For
+protocol tunnels, `-t protocol_tunnel` is accepted **only for MSSQL (SQL Server)
+tunnels** — the server rejects psql/mysql/tcp/k8s with *"Only SQL Server Tunnels
+are allowed."* (live-verified). For those, wire the credential via tag/criteria
+association on the vault account instead.
+
+## SSH CA Authentication
+
+PRA supports SSH CA for ephemeral access - no static keys on hosts.
+
+```bash
+# Find SSH CA vault accounts
+bt pra vault accounts list | grep -i ssh
+
+# Get CA public key (ready for authorized_keys)
+bt pra vault accounts get-public-key <ssh_ca_account_id>
+# Output: cert-authority ssh-rsa AAAAB3NzaC1yc2E...
+
+# Provision EC2 with SSH CA
+PRA_CA_KEY=$(bt pra vault accounts get-public-key <ssh_ca_account_id>)
+# Embed in user-data script for EC2
+```
+
+## CSV Import/Export
+
+`export jump-items` dumps your **actual** jump items of every type (shell, rdp,
+vnc, web, tunnel) with all type-specific columns, so the file round-trips back
+through `import jump-items` as a faithful copy. Pass `--sample` for a blank
+one-row-per-type template instead.
+
+```bash
+bt pra export jump-items --file jump-items.csv            # real export (all types)
+bt pra export jump-items --file template.csv --sample     # blank template
+bt pra import jump-items --file jump-items.csv --dry-run
+bt pra import jump-items --file jump-items.csv
+# Override jumpoint/jump-group for every row:
+bt pra import jump-items --file jump-items.csv --jumpoint 3 --jump-group 24
+```
+
+CSV columns (superset; blanks where N/A): `type, name, hostname, jumpoint_id,
+jump_group_id, username, port, protocol, domain, tag, comments, url,
+tunnel_type, tunnel_definitions, database, verify_certificate, username_format,
+authentication_timeout, ca_certificates`. `type` ∈ {shell, rdp, vnc, web, tunnel}.
+
+## Discover IDs
+
+```bash
+# Find jumpoint IDs
+bt pra jumpoints list
+
+# Find jump group IDs
+bt pra jump-groups list
+
+# Find vault account IDs
+bt pra vault accounts list
+
+# Find vault account group IDs
+bt pra vault groups list
+```
+
+## API Notes
+
+- Base path: `/api/config/v1`
+- Pagination: `per_page`/`current_page` (1-indexed)
+- Response: Array directly (pagination in headers)
+- Jump item types have separate endpoints
+- K8s tunnels require Linux jumpoint
+- **`-o json` is pure JSON on stdout** — status banners ("Created ... (ID: N)")
+  go to **stderr**, so `... -o json | jq` and `json.load(stdin)` are safe.
+- **API validation detail is surfaced**: a 4xx with an `errors` object
+  (e.g. `{"username": ["only allowed when tunnel_type is 'mssql'"]}`) is shown
+  field-by-field in the CLI error, not collapsed to "Validation Failed".

{bt_cli-0.4.58 → bt_cli-0.4.59}/src/bt_cli/pra/client/base.py

@@ -457,6 +457,38 @@ class PRAClient:
             params["hostname"] = hostname
         return self.get_paginated("/jump-item/remote-vnc", params)
 
+    def create_vnc_jump(
+        self,
+        name: str,
+        hostname: str,
+        jumpoint_id: int,
+        jump_group_id: int,
+        port: int = 5900,
+        tag: Optional[str] = None,
+        comments: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Create a Remote VNC Jump item."""
+        data = {
+            "name": name,
+            "hostname": hostname,
+            "jumpoint_id": jumpoint_id,
+            "jump_group_id": jump_group_id,
+            "port": port,
+        }
+        if tag:
+            data["tag"] = tag
+        if comments:
+            data["comments"] = comments
+        return self.post("/jump-item/remote-vnc", json=data)
+
+    def get_vnc_jump(self, item_id: int) -> Dict[str, Any]:
+        """Get a Remote VNC Jump item."""
+        return self.get(f"/jump-item/remote-vnc/{item_id}")
+
+    def delete_vnc_jump(self, item_id: int) -> None:
+        """Delete a Remote VNC Jump item."""
+        self.delete(f"/jump-item/remote-vnc/{item_id}")
+
     def list_web_jumps(
         self,
         jump_group_id: Optional[int] = None,
@@ -473,6 +505,52 @@ class PRAClient:
             params["name"] = name
         return self.get_paginated("/jump-item/web-jump", params)
 
+    def create_web_jump(
+        self,
+        name: str,
+        url: str,
+        jumpoint_id: int,
+        jump_group_id: int,
+        username_format: Optional[str] = None,
+        verify_certificate: bool = True,
+        authentication_timeout: Optional[int] = None,
+        jump_group_type: Optional[str] = None,
+        tag: Optional[str] = None,
+        comments: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Create a Web Jump item.
+
+        Args:
+            name: Jump item name
+            url: Target URL (https://...)
+            jumpoint_id: Jumpoint ID
+            jump_group_id: Jump Group ID
+            username_format: How the username field is matched on the page
+            verify_certificate: Verify the site's TLS certificate (default True)
+            authentication_timeout: Seconds before auth times out
+            jump_group_type: 'shared' or 'personal' (defaults server-side)
+            tag: Optional tag
+            comments: Optional comments
+        """
+        data = {
+            "name": name,
+            "url": url,
+            "jumpoint_id": jumpoint_id,
+            "jump_group_id": jump_group_id,
+            "verify_certificate": verify_certificate,
+        }
+        if username_format:
+            data["username_format"] = username_format
+        if authentication_timeout is not None:
+            data["authentication_timeout"] = authentication_timeout
+        if jump_group_type:
+            data["jump_group_type"] = jump_group_type
+        if tag:
+            data["tag"] = tag
+        if comments:
+            data["comments"] = comments
+        return self.post("/jump-item/web-jump", json=data)
+
     def get_web_jump(self, item_id: int) -> Dict[str, Any]:
         """Get a Web Jump item."""
         return self.get(f"/jump-item/web-jump/{item_id}")
@@ -532,6 +610,27 @@ class PRAClient:
     ) -> Dict[str, Any]:
         """Create a Protocol Tunnel Jump item.
 
+        The Config API's ``protocol-tunnel-jump`` POST endpoint rejects
+        type-specific fields that don't belong to the chosen ``tunnel_type``
+        (it 400s with e.g. "This field is only allowed when tunnel_type is
+        'mssql'"). We therefore only include each field for the type that
+        actually accepts it:
+
+        =============  ===========================================
+        tunnel_type    type-specific fields sent
+        =============  ===========================================
+        tcp            tunnel_definitions
+        mssql          username, database
+        psql / mysql   (none — see note below)
+        k8s            url, ca_certificates
+        =============  ===========================================
+
+        Note: psql/mysql tunnels have ``username``/``database`` in their GET
+        representation, but the public API has no working write path for them
+        (POST rejects them, PATCH no-ops, PUT 405s). A psql/mysql tunnel is
+        therefore created "bare"; any username/database passed here is ignored
+        for those types and the caller is expected to warn the user.
+
         Args:
             name: Jump item name
             hostname: Target hostname (auto-set for k8s from url)
@@ -539,8 +638,8 @@ class PRAClient:
             jump_group_id: Jump Group ID
             tunnel_type: 'tcp', 'mssql', 'psql', 'mysql', or 'k8s'
             tunnel_definitions: Port pairs for TCP (e.g., "22;24;26;28")
-            username: Database username (for mssql, psql, mysql)
-            database: Database name (for mssql, psql, mysql)
+            username: Database username (mssql only)
+            database: Database name (mssql only)
             url: K8s API URL (required for k8s)
             ca_certificates: K8s CA cert (required for k8s)
             tag: Optional tag
@@ -553,16 +652,22 @@ class PRAClient:
             "jump_group_id": jump_group_id,
             "tunnel_type": tunnel_type,
         }
-        if tunnel_definitions:
-            data["tunnel_definitions"] = tunnel_definitions
-        if username:
-            data["username"] = username
-        if database:
-            data["database"] = database
-        if url:
-            data["url"] = url
-        if ca_certificates:
-            data["ca_certificates"] = ca_certificates
+        # Only send fields the endpoint allows for this tunnel_type.
+        if tunnel_type == "tcp":
+            if tunnel_definitions:
+                data["tunnel_definitions"] = tunnel_definitions
+        elif tunnel_type == "mssql":
+            if username:
+                data["username"] = username
+            if database:
+                data["database"] = database
+        elif tunnel_type == "k8s":
+            if url:
+                data["url"] = url
+            if ca_certificates:
+                data["ca_certificates"] = ca_certificates
+        # psql / mysql: no type-specific fields are writable; create bare.
+
         if tag:
             data["tag"] = tag
         if comments: