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

{bt_cli-0.4.64 → bt_cli-0.4.65}/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.64**
+BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, EPM Linux, and the BeyondTrust Secrets API. **Version: 0.4.65**
 
 ## Setup
 
@@ -88,7 +88,7 @@ PASSWORD=$(bt pws quick checkout -s server -a admin --raw)
 - **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`.
+- **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>`. **Default = even coverage + dedup**: ~60 evenly-spaced frames across the whole session (`--frames N`) with consecutive-identical frames skipped (`--dedup`, sha1-based) — because event-driven over-samples RDP (it records many deltas as the screen paints, so `next`-stepping clusters at the login and burns the frame budget before covering the timeline). Modes are mutually exclusive: `--frames` (default) / `--fps` / `--interval` / `--all-frames` (event-driven forensic). Also `--from/--to`, `--scale`, `--max-frames`, `--no-dedup`; `--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.64 → bt_cli-0.4.65}/PKG-INFO

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

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

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

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

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

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

@@ -215,22 +215,31 @@ 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>                    # ~60 frames across the session, deduped
+bt pws sessions replay <session_id> --frames 30        # ~30 evenly-spaced frames
 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
+bt pws sessions replay <session_id> --all-frames --no-dedup   # every recorded frame, verbatim
+bt pws sessions replay <session_id> --mp4              # also stitch an MP4 (needs ffmpeg)
 ```
 
 `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.
+delete. **By default it captures ~60 evenly-spaced frames across the whole
+session and skips identical frames** (`--dedup`), so you see the full timeline
+rather than just the busy start. Sampling modes are mutually exclusive:
+
+- `--frames N` (default, N=60) — N frames spread evenly across the session
+- `--fps F` / `--interval MS` — fixed-rate sampling
+- `--all-frames` — event-driven, one frame per recorded change (forensic; can be
+  huge — RDP records many deltas while the screen paints, which is why this
+  isn't the default)
+
+**One network round-trip per frame**, so bound long captures with `--frames`,
+`--from/--to`, or `--max-frames` (default 3600). `--no-dedup` keeps every
+sampled frame. `--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.

{bt_cli-0.4.64 → bt_cli-0.4.65}/src/bt_cli/pws/commands/sessions.py

@@ -1,5 +1,6 @@
 """CLI commands for managing active Password Safe sessions."""
 
+import hashlib
 import json
 import shutil
 import subprocess
@@ -365,8 +366,11 @@ def _warmup_seek(client, replay_id: str, offset_ms: int, quiet: bool, attempts:
 def session_replay(
     session_id: int = typer.Argument(..., help="Session ID (from `sessions list`)"),
     out: str = typer.Option(None, "--out", help="Output directory (default: ./session-<id>-replay)"),
-    fps: float = typer.Option(None, "--fps", help="Fixed sampling rate (frames/sec). Default: event-driven (one frame per recorded change)"),
-    interval: int = typer.Option(None, "--interval", help="Fixed sampling interval in ms (alternative to --fps)"),
+    frames: int = typer.Option(None, "--frames", help="Target number of evenly-spaced frames across the session (default: 60)"),
+    fps: float = typer.Option(None, "--fps", help="Fixed sampling rate in frames/sec (alternative to --frames)"),
+    interval: int = typer.Option(None, "--interval", help="Fixed sampling interval in ms (alternative to --frames)"),
+    all_frames: bool = typer.Option(False, "--all-frames", help="Capture every recorded frame change (event-driven; forensic, can be very large)"),
+    dedup: bool = typer.Option(True, "--dedup/--no-dedup", help="Skip consecutive identical frames (on by default)"),
     scale: int = typer.Option(1, "--scale", help="PNG scale factor (1 = full size)"),
     start: float = typer.Option(0, "--from", help="Start offset in seconds"),
     end: float = typer.Option(None, "--to", help="End offset in seconds (default: end of session)"),
@@ -381,21 +385,34 @@ def session_replay(
     Password Safe has no video-export API, so this drives the headless replay
     renderer: it seeks through the recording and pulls one PNG per frame, then
     (with --mp4) stitches them with ffmpeg. Works for RDP (screen) and SSH
-    (rendered terminal). Note: one network round-trip per frame, so long
-    sessions take a while - use --fps/--interval, --from/--to, or --max-frames.
+    (rendered terminal).
+
+    By default it captures ~60 evenly-spaced frames across the whole session
+    (so you see the full timeline, not just the busy start) and skips identical
+    frames (--dedup). Use --frames/--fps/--interval to change the sampling rate,
+    or --all-frames for the forensic every-recorded-change mode (can be huge -
+    RDP records many deltas while the screen paints). One network round-trip per
+    frame, so bound long captures with --frames, --from/--to, or --max-frames.
 
     Examples:
-        bt pws sessions replay 1460                       # event-driven frames + index
-        bt pws sessions replay 1460 --mp4                 # also build an MP4
+        bt pws sessions replay 1460                       # ~60 frames across the session, deduped
+        bt pws sessions replay 1460 --frames 30           # ~30 evenly-spaced frames
         bt pws sessions replay 1460 --fps 1 --to 120      # 1 fps for the first 2 minutes
-        bt pws sessions replay 1460 --out ./review --mp4 --mp4-fps 8
+        bt pws sessions replay 1460 --all-frames --no-dedup   # every recorded frame, verbatim
+        bt pws sessions replay 1460 --mp4                 # also build an MP4
     """
     quiet = output == "json"
-    fixed_interval = None
-    if fps is not None and interval is not None:
-        print_error("Use --fps or --interval, not both.")
+    # Resolve sampling mode (mutually exclusive). Default = even-coverage frames.
+    n_modes = sum(x is not None for x in (frames, fps, interval)) + int(all_frames)
+    if n_modes > 1:
+        print_error("Choose one of --frames / --fps / --interval / --all-frames.")
         raise typer.Exit(2)
-    if fps is not None:
+
+    fixed_interval = None       # set for fps/interval; computed later for frames mode
+    frames_target = None        # set for even-coverage frames mode
+    if all_frames:
+        pass                    # event-driven: fixed_interval stays None
+    elif fps is not None:
         if fps <= 0:
             print_error("--fps must be positive.")
             raise typer.Exit(2)
@@ -405,6 +422,11 @@ def session_replay(
             print_error("--interval must be positive.")
             raise typer.Exit(2)
         fixed_interval = interval
+    else:
+        frames_target = frames if frames is not None else 60
+        if frames_target <= 0:
+            print_error("--frames must be positive.")
+            raise typer.Exit(2)
 
     out_dir = Path(out) if out else Path(f"session-{session_id}-replay")
     replay_id = None
@@ -435,7 +457,15 @@ def session_replay(
             total_ms = state.get("duration") or int(duration_s * 1000)
             end_ms = int(end * 1000) if end is not None else total_ms
 
+            # Even-coverage mode: spread the target frame count across the span
+            # (endpoints included), then capture like a fixed interval.
+            if frames_target is not None:
+                span = max(0, end_ms - start_ms)
+                fixed_interval = max(1, span // frames_target) if frames_target > 1 else span + 1
+
             frames: list[dict] = []
+            deduped = 0
+            last_hash = None
             offset = start_ms
             settle = settle_ms / 1000.0
             while True:
@@ -450,13 +480,19 @@ def session_replay(
                     if fixed_interval is None:
                         break
                 else:
-                    idx = len(frames)
-                    fname = f"frame_{idx:04d}.png"
-                    (out_dir / fname).write_bytes(png)
-                    frames.append({"file": fname, "offset_ms": offset})
+                    digest = hashlib.sha1(png).digest()
+                    if dedup and digest == last_hash:
+                        deduped += 1  # identical to the previous kept frame - skip
+                    else:
+                        last_hash = digest
+                        idx = len(frames)
+                        fname = f"frame_{idx:04d}.png"
+                        (out_dir / fname).write_bytes(png)
+                        frames.append({"file": fname, "offset_ms": offset})
                     if not quiet:
                         pct = min(100, int(offset / total_ms * 100)) if total_ms else 0
-                        console.print(f"\r[cyan]  {len(frames)} frames  {offset/1000:.1f}s  ({pct}%)[/cyan]", end="")
+                        dd = f"  (-{deduped} dup)" if deduped else ""
+                        console.print(f"\r[cyan]  {len(frames)} frames  {offset/1000:.1f}s  ({pct}%){dd}[/cyan]", end="")
 
                 # Advance
                 if fixed_interval is not None:
@@ -515,13 +551,15 @@ def session_replay(
                 "protocol": protocol,
                 "output_dir": str(out_dir.resolve()),
                 "frame_count": len(frames),
+                "deduped": deduped,
                 "mp4": str(mp4_path.resolve()) if mp4_path else None,
             }, default=str))
         else:
             if not frames:
                 console.print(f"[yellow]No frames captured for session {session_id}.[/yellow]")
             else:
-                console.print(f"[green]Captured {len(frames)} frame(s).[/green]")
+                dd = f" ({deduped} duplicate(s) skipped)" if deduped else ""
+                console.print(f"[green]Captured {len(frames)} frame(s).{dd}[/green]")
                 console.print(f"  Frames: [cyan]{out_dir.resolve()}[/cyan]")
                 if mp4_path:
                     console.print(f"  MP4:    [cyan]{mp4_path.resolve()}[/cyan]")

{bt_cli-0.4.64 → bt_cli-0.4.65}/tests/pws/test_commands.py

@@ -428,7 +428,7 @@ class TestPWSSessionsReplay:
 
     @respx.mock
     def test_replay_fixed_interval_captures_frames(self, runner, mock_pws_config, tmp_path):
-        """Fixed --interval captures a bounded set of frames + index.json."""
+        """Fixed --interval captures a bounded set of frames + index.json (dedup off)."""
         self._mock_replay({
             "SessionID": 1460, "Token": "tok", "RecordKey": "rk",
             "Protocol": 0, "Duration": 3, "AssetName": "win", "ManagedAccountName": "admin",
@@ -437,7 +437,7 @@ class TestPWSSessionsReplay:
         with patch("bt_cli.pws.client.base.load_pws_config", return_value=mock_pws_config):
             result = runner.invoke(app, [
                 "pws", "sessions", "replay", "1460",
-                "--interval", "1000", "--to", "3", "--settle", "0", "--out", str(out),
+                "--interval", "1000", "--to", "3", "--settle", "0", "--no-dedup", "--out", str(out),
             ])
 
         assert result.exit_code == 0, result.output
@@ -448,6 +448,46 @@ class TestPWSSessionsReplay:
         assert index["frame_count"] == 4
         assert index["protocol"] == "RDP"
 
+    @respx.mock
+    def test_replay_dedup_collapses_identical_frames(self, runner, mock_pws_config, tmp_path):
+        """Default dedup keeps only one of a run of identical frames."""
+        self._mock_replay({
+            "SessionID": 1460, "Token": "tok", "RecordKey": "rk",
+            "Protocol": 0, "Duration": 3, "AssetName": "win", "ManagedAccountName": "admin",
+        })
+        out = tmp_path / "r"
+        with patch("bt_cli.pws.client.base.load_pws_config", return_value=mock_pws_config):
+            result = runner.invoke(app, [
+                "pws", "sessions", "replay", "1460",
+                "--interval", "1000", "--to", "3", "--settle", "0", "--out", str(out), "-o", "json",
+            ])
+
+        assert result.exit_code == 0, result.output
+        summary = json.loads(result.output[result.output.index("{"):])
+        assert summary["frame_count"] == 1   # all 4 mock frames are identical
+        assert summary["deduped"] == 3
+
+    @respx.mock
+    def test_replay_frames_mode_even_coverage(self, runner, mock_pws_config, tmp_path):
+        """Default --frames spreads capture across the whole session span (3000ms per the mock state)."""
+        self._mock_replay({
+            "SessionID": 1460, "Token": "tok", "RecordKey": "rk",
+            "Protocol": 0, "Duration": 3, "AssetName": "win", "ManagedAccountName": "admin",
+        })
+        out = tmp_path / "r"
+        with patch("bt_cli.pws.client.base.load_pws_config", return_value=mock_pws_config):
+            result = runner.invoke(app, [
+                "pws", "sessions", "replay", "1460",
+                "--frames", "5", "--settle", "0", "--no-dedup", "--out", str(out),
+            ])
+
+        assert result.exit_code == 0, result.output
+        index = json.loads((out / "index.json").read_text())
+        offsets = [f["offset_ms"] for f in index["frames"]]
+        # frames spread across the 3000ms span, reaching near the end (not clustered at 0)
+        assert offsets[0] == 0
+        assert offsets[-1] >= 2400
+
     @respx.mock
     def test_replay_no_recording(self, runner, mock_pws_config):
         """A session without a recording (no Token/RecordKey) exits 1."""