bt-cli 0.4.68__tar.gz → 0.4.69__tar.gz

{bt_cli-0.4.68 → bt_cli-0.4.69}/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.68**
+BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, EPM Linux, and the BeyondTrust Secrets API. **Version: 0.4.69**
 
 ## Setup
 

{bt_cli-0.4.68 → bt_cli-0.4.69}/PKG-INFO

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

{bt_cli-0.4.68 → bt_cli-0.4.69}/pyproject.toml

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

{bt_cli-0.4.68 → bt_cli-0.4.69}/src/bt_cli/__init__.py

@@ -1,3 +1,3 @@
 """BeyondTrust Unified Admin CLI."""
 
-__version__ = "0.4.68"
+__version__ = "0.4.69"

bt_cli-0.4.69/src/bt_cli/data/skills/session-analysis/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: session-analysis
+description: Analyze a dumped Password Safe session (replay frames + keystrokes) into a timeline summary with a cost estimate. Use when the user points at a `session-<id>-replay` folder or asks to summarize/analyze a recorded RDP or SSH session.
+---
+
+# Session Analysis
+
+Turn a bt-cli session dump into a **timeline summary of what happened**, efficiently, with a **cost estimate**. Works for RDP (screen recording → frames) and SSH (keystroke transcript). This is interactive analysis — *you* (the model) read the frames/transcript; there is no LLM call inside the CLI.
+
+## The one rule: never read every frame
+
+An RDP session sampled at ~1 frame per 2s is dozens of near-identical frames. Reading them all wastes tokens. Let the CLI pick the frames worth reading — the ones where the screen changed **and** the ones that render what the user typed — and read only those, guided by the per-frame `typed`/`reason` tags.
+
+## Recipe
+
+### 1. Prep with the CLI (does the heavy lifting)
+
+```bash
+# If the user has a replay folder already:
+bt pws sessions analyze --dir <folder>
+# If they have the session id (reads ./session-<id>-replay):
+bt pws sessions analyze <id> --model opus   # or --model sonnet for a cheaper estimate
+```
+
+`analyze` writes `analysis.json` into the folder and prints:
+- **Who / what / when:** `user` (the initiator's real name + username, resolved from `UserID` via `/Users/{id}`), `user_email`, `account`@`system`, `start_time`. **Always name the human in the summary** — "UserID 219" is not an answer; "Amy Miller (amiller)" is.
+- **RDP:** the **keyframes** to read. Each is tagged with a **reason** — `screen-change` (the picture moved) and/or `after-typing` (it renders the result of something the user typed). `after-typing` frames also carry the exact `typed` text.
+- **SSH:** a pointer to the transcript (analyze it instead of frames).
+- **`typed_bursts`** — typed input grouped into phrases with recording-relative offsets (`@14.9s "powershell"`), already anchored to the keyframes above.
+- A **cost estimate**: `focused` (keyframes only) vs `all frames`.
+
+If the user only has a folder (no live API access), `analyze --dir` still works — user name, keystrokes, and anchoring need the session metadata (`StartTime`/`UserID`), so offline it falls back to `screen-change` keyframes only, with a note. Keyframes + cost are still computed.
+
+### 2. Combine both signals — transcript AND frames
+
+Don't treat this as either/or. The transcript gives you *verbatim text* the screen can't render cleanly; the frames give you *visual state* the transcript can't capture. Use each for what it's good at, and correlate them by timestamp (the CLI already did the correlation — `typed`/`typed_bursts` carry offsets, keystrokes carry `time`).
+
+- **Always pull the transcript** when there is one: `bt pws sessions transcript <id>`. It's cheap.
+  - **SSH:** the transcript *is* the analysis — full input+output (typed commands `»` + terminal stdout). Read it; frames are rarely worth opening.
+  - **RDP:** the transcript is sparse (typed keys / window titles, often empty) but still adds color frames miss — the exact command typed, a window title, a value entered in a field. Fold it into the narrative alongside the frames.
+- **Read the frames** (RDP): **read every keyframe the CLI listed — do not sub-sample them.** The CLI already culled the full recording down to the frames that matter; picking "6 of 37 to confirm the story" is how you miss events (a service restart, a dialog, a config change happen in the frames you skipped). If the full keyframe set is genuinely too expensive, raise `--threshold` and re-run so the *CLI* drops frames deliberately — never silently skip listed keyframes. Prioritize `after-typing` frames (the `typed` field tells you what to look for before you open the image), then read the `screen-change` frames for the mouse-driven actions keystrokes don't cover (menus, service start/stop, window closes).
+
+### 3. Anchoring is already done
+
+The CLI has correlated keystrokes → frames for you (via the recording `StartTime`): the `typed` field on each keyframe and the `typed_bursts` list *are* the timeline anchors. Just narrate them — "at ~0:14 typed `powershell`, frame at 16s shows PowerShell 7 open". If RDP keystroke capture was off (bursts empty), fall back to reading every screen-change frame and inferring actions from the pictures.
+
+### 4. Write the summary
+
+Produce:
+- **Who** — the initiating user by name (from `user`/`user_email`), the account@system, and the time window. Note if the initiator is an API/service credential (e.g. `cli-<name>`) vs an interactive login — that distinction matters for audit.
+- **Timeline table** — approximate time → event (app launched, window opened, command run, dialog shown, service changed, logoff).
+- **Highlights an auditor cares about** — EPM/Defendpoint elevation or justification prompts, privileged tools (`dsa.msc`, `services.msc`, PowerShell), AD/account/OU changes, service start/stop, file transfers.
+- **Security note** — explicitly state whether any credentials, passwords, tokens, or secret values were visible in the frames read.
+- **Coverage & cost** — say how many of the listed keyframes you actually read (ideally all of them) so the reader knows the summary isn't under-sampled, and report the estimate from `analysis.json`.
+
+## Efficiency notes
+
+- Two selection signals combine: PNG-size delta (`screen-change`, dependency-free) and keystroke anchoring (`after-typing`, when RDP keystroke capture is on). Anchoring is what makes the read *targeted* — it guarantees the frame that shows each typed action is included, even if its size barely moved.
+- **Blind spot — mouse-driven, low-pixel-change actions.** A subtle action done with the mouse (a service going Running→Stopped is a few pixels of text, no keystroke) can slip past *both* signals: no `after-typing` anchor, and too small a PNG delta to trip `screen-change`. This is the classic "we missed the service restart." Mitigations: (a) **read all listed keyframes** — the restart's modal progress dialog usually *is* a keyframe, you just have to open it; (b) if you suspect a missed event in a quiet stretch, re-run `analyze --threshold 1.5` (or `1.0`) to surface smaller deltas; (c) for forensic certainty, `bt pws sessions replay <id> --all-frames --no-dedup` captures every recorded change. Under-sampling is usually the agent skipping listed keyframes, not the CLI mis-selecting them.
+- If a session looks under-sampled (transitions missed), re-run `analyze --threshold 1.5` for more keyframes; over-sampled → raise it.
+- Frame token cost ≈ `(width × height) / 750` per image (1024×768 ≈ ~1,050 tokens). The CLI's estimate already accounts for this.
+- Pricing (per 1M tokens, for the estimate): Opus 4.8 $5/$25, Sonnet 4.6 $3/$15, Haiku 4.5 $1/$5. Use the `claude-api` skill for current numbers.
+
+## Scaling up (optional, not built)
+
+For summarizing **many** sessions unattended, this interactive recipe doesn't scale — that would be a `bt pws sessions summarize` command calling the Claude API (vision) with the same keyframe/transcript inputs and the Batch API for volume. Mention it if the user wants automation; today, analysis is interactive.
+
+## Related
+
+- `bt pws sessions replay <id>` — produce the frames (defaults to even coverage + dedup).
+- `bt pws sessions transcript <id>` — the keystroke transcript (SSH gold; RDP sparse).
+- `/pws` skill — Password Safe command reference.

{bt_cli-0.4.68 → bt_cli-0.4.69}/src/bt_cli/pws/commands/sessions.py

@@ -762,6 +762,17 @@ def _build_keyframes(
     return keyframes
 
 
+def _user_label(user: dict) -> str:
+    """Human label for a /Users record: 'First Last (username)' or best available."""
+    if not user:
+        return ""
+    full = " ".join(p for p in (user.get("FirstName"), user.get("LastName")) if p).strip()
+    handle = user.get("UserName") or user.get("EmailAddress") or ""
+    if full and handle:
+        return f"{full} ({handle})"
+    return full or handle or (f"UserID {user.get('UserID')}" if user.get("UserID") else "")
+
+
 @app.command("analyze")
 def session_analyze(
     session_id: int = typer.Argument(None, help="Session ID (defaults to reading ./session-<id>-replay)"),
@@ -805,18 +816,27 @@ def session_analyze(
     frames = idx.get("frames", [])
     sid = session_id or idx.get("session_id")
 
-    # Pull keystrokes + session meta (best-effort; folder may be analyzed offline)
+    # Pull keystrokes + session meta + the initiating user (best-effort; folder
+    # may be analyzed offline with no API access).
     keystrokes: list[dict] = []
     meta: dict = {}
+    user: dict = {}
     if sid:
         try:
             with get_client() as client:
                 client.authenticate()
                 meta = client.get_session(sid)
                 keystrokes = client.get_keystrokes(sid)
+                uid = meta.get("UserID")
+                if uid:
+                    try:
+                        user = client.get_user(uid)
+                    except Exception:
+                        pass  # name resolution is a nicety; don't fail the analysis
         except Exception as e:
             if output != "json":
                 print_warning(f"Could not pull keystrokes for session {sid} ({e}); continuing with frames only.")
+    user_label = _user_label(user)
 
     decoded_ks = [
         {"time": _fmt_marker(k.get("TimeMarker")), "type": _keystroke_type(k.get("Type")), "data": k.get("Data", "")}
@@ -854,6 +874,12 @@ def session_analyze(
     manifest = {
         "session_id": sid,
         "protocol": protocol,
+        "user_id": meta.get("UserID"),
+        "user": user_label,
+        "user_email": user.get("EmailAddress") if user else None,
+        "account": meta.get("ManagedAccountName"),
+        "system": meta.get("AssetName"),
+        "start_time": meta.get("StartTime"),
         "frame_dims": [w, h],
         "frame_count": len(frames),
         "keyframe_count": len(keyframes),
@@ -873,6 +899,9 @@ def session_analyze(
     acct = meta.get("ManagedAccountName", "?")
     sysn = meta.get("AssetName", "?")
     console.print(f"[bold]Session {sid}[/bold]  {protocol}  {acct}@{sysn}")
+    if user_label:
+        console.print(f"  [green]Initiated by[/green] {rich_escape(user_label)}"
+                      + (f"  [dim]· {meta.get('StartTime')}[/dim]" if meta.get("StartTime") else ""))
     console.print(f"  Frames: {len(frames)} ({w}x{h})   Keystroke events: {len(decoded_ks)}")
     if protocol.upper() == "SSH":
         console.print("  [green]SSH → analyze the transcript[/green] (cheap, full input+output):")

bt_cli-0.4.68/src/bt_cli/data/skills/session-analysis/SKILL.md

@@ -1,64 +0,0 @@
----
-name: session-analysis
-description: Analyze a dumped Password Safe session (replay frames + keystrokes) into a timeline summary with a cost estimate. Use when the user points at a `session-<id>-replay` folder or asks to summarize/analyze a recorded RDP or SSH session.
----
-
-# Session Analysis
-
-Turn a bt-cli session dump into a **timeline summary of what happened**, efficiently, with a **cost estimate**. Works for RDP (screen recording → frames) and SSH (keystroke transcript). This is interactive analysis — *you* (the model) read the frames/transcript; there is no LLM call inside the CLI.
-
-## The one rule: never read every frame
-
-An RDP session sampled at ~1 frame per 2s is dozens of near-identical frames. Reading them all wastes tokens. Let the CLI pick the frames worth reading — the ones where the screen changed **and** the ones that render what the user typed — and read only those, guided by the per-frame `typed`/`reason` tags.
-
-## Recipe
-
-### 1. Prep with the CLI (does the heavy lifting)
-
-```bash
-# If the user has a replay folder already:
-bt pws sessions analyze --dir <folder>
-# If they have the session id (reads ./session-<id>-replay):
-bt pws sessions analyze <id> --model opus   # or --model sonnet for a cheaper estimate
-```
-
-`analyze` writes `analysis.json` into the folder and prints:
-- **RDP:** the **keyframes** to read (a handful, not all). Each keyframe is tagged with a **reason** — `screen-change` (the picture moved) and/or `after-typing` (it renders the result of something the user typed). `after-typing` frames also carry the exact `typed` text.
-- **SSH:** a pointer to the transcript (analyze it instead of frames).
-- **`typed_bursts`** — typed input grouped into phrases with recording-relative offsets (`@14.9s "powershell"`), already anchored to the keyframes above.
-- A **cost estimate**: `focused` (keyframes only) vs `all frames`.
-
-If the user only has a folder (no live API access), `analyze --dir` still works — keystrokes need session metadata (`StartTime`) to anchor, so offline it falls back to `screen-change` keyframes only, with a note. Keyframes + cost are still computed.
-
-### 2. Read the right inputs — targeted, in `analysis.json` order
-
-- **RDP:** `Read` only the keyframe PNGs the CLI listed. **Prioritize the `after-typing` frames** — they're where a user action produced a visible result (a launched app, a command's output, an EPM prompt). For each, the `typed` field tells you what to look for *before* you open the image, so you read with intent instead of scanning. The `screen-change`-only frames fill in transitions the keystrokes don't cover (mouse-driven actions: menus, service restarts, window closes). If a keyframe implies something happened between it and the next, that's fine — the summary is event-level, not frame-level.
-- **SSH:** run `bt pws sessions transcript <id>` and read that — it's the full input+output, far richer and cheaper than frames. Frames are rarely worth reading for SSH.
-
-### 3. Anchoring is already done
-
-The CLI has correlated keystrokes → frames for you (via the recording `StartTime`): the `typed` field on each keyframe and the `typed_bursts` list *are* the timeline anchors. Just narrate them — "at ~0:14 typed `powershell`, frame at 16s shows PowerShell 7 open". If RDP keystroke capture was off (bursts empty), fall back to reading the screen-change frames and inferring actions from the pictures alone.
-
-### 4. Write the summary
-
-Produce:
-- **Timeline table** — approximate time → event (app launched, window opened, command run, dialog shown, service changed, logoff).
-- **Highlights an auditor cares about** — EPM/Defendpoint elevation or justification prompts, privileged tools (`dsa.msc`, `services.msc`, PowerShell), AD/account/OU changes, service start/stop, file transfers.
-- **Security note** — explicitly state whether any credentials, passwords, tokens, or secret values were visible in the frames read.
-- **Cost** — report the estimate from `analysis.json` (and, if you want, the actual: images read × ~`(w*h)/750` tokens + output).
-
-## Efficiency notes
-
-- Two selection signals combine: PNG-size delta (`screen-change`, dependency-free) and keystroke anchoring (`after-typing`, when RDP keystroke capture is on). Anchoring is what makes the read *targeted* — it guarantees the frame that shows each typed action is included, even if its size barely moved. If a session looks under-sampled (transitions missed), re-run `analyze --threshold 1.5` for more keyframes; over-sampled → raise it.
-- Frame token cost ≈ `(width × height) / 750` per image (1024×768 ≈ ~1,050 tokens). The CLI's estimate already accounts for this.
-- Pricing (per 1M tokens, for the estimate): Opus 4.8 $5/$25, Sonnet 4.6 $3/$15, Haiku 4.5 $1/$5. Use the `claude-api` skill for current numbers.
-
-## Scaling up (optional, not built)
-
-For summarizing **many** sessions unattended, this interactive recipe doesn't scale — that would be a `bt pws sessions summarize` command calling the Claude API (vision) with the same keyframe/transcript inputs and the Batch API for volume. Mention it if the user wants automation; today, analysis is interactive.
-
-## Related
-
-- `bt pws sessions replay <id>` — produce the frames (defaults to even coverage + dedup).
-- `bt pws sessions transcript <id>` — the keystroke transcript (SSH gold; RDP sparse).
-- `/pws` skill — Password Safe command reference.