bt-cli 0.4.61__tar.gz → 0.4.64__tar.gz

{bt_cli-0.4.61 → bt_cli-0.4.64}/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.61**
+BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, EPM Linux, and the BeyondTrust Secrets API. **Version: 0.4.64**
 
 ## Setup
 
@@ -87,6 +87,8 @@ PASSWORD=$(bt pws quick checkout -s server -a admin --raw)
 - **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).
 - **PWS SSH/RDP session establishment = `POST /Requests/{id}/Sessions`** (`{"SessionType":"SSH"|"RDP"}`), NOT `POST /Sessions` (collection is GET-only → 405). Create the request with matching `AccessType` first. **SSH** returns a ready `Command` (`ssh -p 4422 <ticket>@<proxyhost>`) + `Link`; **RDP** returns `Host`/`Port`/`Ticket` only — the `.rdp` is built client-side (`full address` = proxy `Host:Port`, `username` = `Ticket`); there's no server-side launch file (`/Sessions/RDPFile` is audit-playback → 403). Ticket is the proxy username; password is proxy-injected. `bt pws quick checkout --access-type ssh|rdp` and `bt pws quick ssh`/`quick rdp` (with `--launch`); session commands do **not** auto-checkin.
+- **PWS session keystroke transcript = `GET /Sessions/{id}/Keystrokes`** → events `{KeystrokeID, TimeMarker (epoch ms), Type, Data}`. **Type 1 = user input** (typed keys; special keys as glyphs `⌫`/`→`/`↑`), **Type 2 = terminal output** (SSH stdout). SSH captures a full input+output transcript; **RDP is sparse** (typed keys / window events only, off by default → often empty). Surfaced as `bt pws sessions transcript <id>` (default = time-ordered readable transcript; `--input-only`; text/json/csv). Text trail, not the visual recording. (There is **no** `bt pws sessions export` — session *metadata* evidence is `bt pws audit export`.)
+- **PWS session recording download = headless replay under `/pbsm/replay`** (there is **no** video-export API — `?video/?mp4/?webm` return JSON, not media). Flow: `GET /Sessions/{id}` for `Token`+`RecordKey`+`Protocol` → `POST /pbsm/replay` `{id:Token, record_key, protocol:"RDP"|"SSH", headless:true}` → `PUT /pbsm/replay/{rid}` `{offset:<ms>}` (seek) → `GET /pbsm/replay/{rid}?png=<scale>` (one PNG per offset) → `DELETE /pbsm/replay/{rid}`. **Warm-up:** the first `PUT` 404s (`"no such file or directory"`) until the renderer loads — retry ~0.5s. The seek response is state `{offset, next, eof, duration}`; **`next` = next recorded frame's offset**, enabling event-driven stepping. Surfaced as `bt pws sessions replay <id>` (event-driven default; `--fps`/`--interval` fixed sampling; `--from/--to`, `--scale`, `--max-frames`; `--mp4` stitches via ffmpeg, else prints the command + install hint). Always `DELETE`s the replay in `finally`.
 - 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
 - Windows builds: Rich must be pinned to `<14.0.0` (Rich 14 has PyInstaller unicode issues)

{bt_cli-0.4.61 → bt_cli-0.4.64}/PKG-INFO

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

{bt_cli-0.4.61 → bt_cli-0.4.64}/pyproject.toml

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

{bt_cli-0.4.61 → bt_cli-0.4.64}/src/bt_cli/__init__.py

@@ -1,3 +1,3 @@
 """BeyondTrust Unified Admin CLI."""
 
-__version__ = "0.4.61"
+__version__ = "0.4.64"

{bt_cli-0.4.61 → bt_cli-0.4.64}/src/bt_cli/data/skills/pws/SKILL.md

@@ -195,8 +195,43 @@ bt pws sessions suspend <session_id>
 # Terminate = end permanently (cannot be resumed) - prompts unless --force
 bt pws sessions terminate <session_id>
 bt pws sessions terminate <session_id> --force
+
+# Transcript = recorded keystrokes for a session (SSH input+output, RDP sparse)
+bt pws sessions transcript <session_id>                 # readable transcript (default)
+bt pws sessions transcript <session_id> --input-only    # just the commands typed
+bt pws sessions transcript <session_id> -o json | jq
+bt pws sessions transcript <session_id> --file s.txt
+bt pws sessions transcript <session_id> --file s.csv --format csv
+```
+
+`transcript` pulls `GET /Sessions/{id}/Keystrokes`: events `{KeystrokeID,
+TimeMarker (epoch ms), Type, Data}` where **Type 1 = user input** (typed keys,
+special keys as glyphs like `⌫`/`→`) and **Type 2 = terminal output** (SSH
+stdout). The default view reconstructs a time-ordered transcript (input marked
+`»`, output verbatim). SSH sessions capture a full transcript; **RDP capture is
+sparse** (typed keys / window events only, and only when keystroke logging is
+enabled - many RDP sessions have none). This is the text trail, not the visual
+recording. For session *metadata* evidence, use `bt pws audit export`.
+
+```bash
+# Download the VISUAL recording as PNG frames (RDP screen / SSH terminal)
+bt pws sessions replay <session_id>                    # event-driven frames + index.json
+bt pws sessions replay <session_id> --mp4              # also stitch an MP4 (needs ffmpeg)
+bt pws sessions replay <session_id> --fps 1 --to 120   # 1 fps for the first 2 minutes
+bt pws sessions replay <session_id> --out ./review --scale 1 --max-frames 500
 ```
 
+`replay` drives the headless renderer at `/pbsm/replay` (there is **no**
+video-export API): create replay → seek by offset → pull one PNG per frame →
+delete. By default it steps **event-driven** (following the replay state's
+`next`/`eof` fields, one frame per recorded change); `--fps`/`--interval` force
+fixed-rate sampling. **It's one network round-trip per frame, so long sessions
+are slow** - bound them with `--fps`, `--from/--to`, or `--max-frames` (default
+3600). `--mp4` stitches with ffmpeg (H.264); if ffmpeg is missing it prints the
+exact command + install instructions and leaves the frames. Works for RDP
+(screen) and SSH (rendered terminal). Gotcha: the renderer needs ~0.5s warm-up
+(first seek 404s), handled automatically.
+
 **Gotchas:**
 - `/Sessions` returns session **history**, not just active sessions, and **ignores `limit`/`offset`** (returns the full set every call - the client does a single GET, the CLI caps display client-side). Use `--active` for the live ones.
 - `Status` codes confirmed live: **0 = Not started, 1 = Active, 2 = Completed, 5 = Locked, 7 = Terminated** (3/9 are other terminal states). `--active` filters on Status == 1.

{bt_cli-0.4.61 → bt_cli-0.4.64}/src/bt_cli/pws/client/passwordsafe.py

@@ -594,6 +594,66 @@ class PasswordSafeMixin:
         """
         return self.get(f"/Sessions/{session_id}")
 
+    def get_keystrokes(self: "PasswordSafeClient", session_id: int) -> list[dict[str, Any]]:
+        """Get recorded keystrokes for a session.
+
+        GET /Sessions/{id}/Keystrokes. Each event is
+        {KeystrokeID, SessionID, TimeMarker (epoch ms), Type, Data}. Type 1 =
+        user input (typed keys), Type 2 = terminal output (SSH). SSH sessions
+        capture a full transcript; RDP capture is sparse (often empty).
+
+        Returns:
+            List of keystroke events (empty list if none recorded).
+        """
+        result = self.get(f"/Sessions/{session_id}/Keystrokes")
+        if isinstance(result, list):
+            return result
+        if isinstance(result, dict) and "Data" in result:
+            return result["Data"]
+        return []
+
+    # --- Session replay (headless renderer under /pbsm/replay) ---
+    # There is no video-export endpoint: you create a replay, seek by offset,
+    # and pull one PNG per offset, then stitch client-side. The seek response
+    # carries {offset, next, eof, duration} - `next` is the next recorded
+    # frame's offset (ms), enabling event-driven stepping.
+
+    def create_replay(
+        self: "PasswordSafeClient", token: str, record_key: str, protocol: str
+    ) -> dict[str, Any]:
+        """Create a headless replay session. Returns dict with `id` (replayId)."""
+        return self.post(
+            "/pbsm/replay",
+            json={"id": token, "record_key": record_key, "protocol": protocol, "headless": True},
+        )
+
+    def seek_replay(self: "PasswordSafeClient", replay_id: str, offset_ms: int) -> dict[str, Any]:
+        """Seek the replay to offset (ms from start). Returns replay state.
+
+        Note: immediately after create the renderer isn't ready and this 404s
+        ("no such file or directory") - callers should retry with a short delay.
+        """
+        return self.put(f"/pbsm/replay/{replay_id}", json={"offset": offset_ms})
+
+    def get_replay_frame(self: "PasswordSafeClient", replay_id: str, scale: int = 1) -> bytes:
+        """Fetch the PNG frame at the current offset. Returns raw PNG bytes.
+
+        Uses the underlying client directly so binary content isn't coerced to
+        text. If the server returns non-PNG (e.g. state JSON when not ready),
+        the raw bytes are returned as-is for the caller to validate.
+        """
+        client = self._ensure_client()
+        headers = self._get_auth_headers()
+        response = client.request(
+            "GET", f"/pbsm/replay/{replay_id}", params={"png": scale}, headers=headers
+        )
+        response.raise_for_status()
+        return response.content
+
+    def delete_replay(self: "PasswordSafeClient", replay_id: str) -> dict[str, Any]:
+        """Terminate a replay session (always call this to free the renderer)."""
+        return self.delete(f"/pbsm/replay/{replay_id}")
+
     def lock_session(self: "PasswordSafeClient", session_id: int) -> dict[str, Any]:
         """Lock an active session.