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

{bt_cli-0.4.67 → 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.67**
+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.67 → bt_cli-0.4.69}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bt-cli
-Version: 0.4.67
+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.67 → bt_cli-0.4.69}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bt-cli"
-version = "0.4.67"
+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.67 → bt_cli-0.4.69}/src/bt_cli/__init__.py

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

{bt_cli-0.4.67 → bt_cli-0.4.69}/src/bt_cli/data/skills/pws/SKILL.md

@@ -189,6 +189,11 @@ bt pws sessions list --active        # only live sessions (started, not ended)
 bt pws sessions list --all -o json   # full history
 bt pws sessions get <session_id>
 
+# "The session from today" — date filters match on StartTime (client-side)
+bt pws sessions list --today
+bt pws sessions list --on 2026-07-02
+bt pws sessions list --since 2026-06-01 --until 2026-06-30   # a range (e.g. "this week")
+
 # Suspend = lock (user disconnected, session can be resumed)
 bt pws sessions suspend <session_id>
 
@@ -241,6 +246,27 @@ 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.
 
+### "What happened in this session?" — summarize efficiently
+
+`replay` only *downloads* frames. To turn a session into a **timeline summary of
+what the user did**, don't read every frame — use the analysis pipeline:
+
+```bash
+bt pws sessions replay <session_id>       # 1. download the frames
+bt pws sessions analyze <session_id>      # 2. pick keyframes + anchor keystrokes + estimate cost
+```
+
+`analyze` is deterministic prep (no LLM): it selects the handful of frames worth
+reading — screen-change frames **plus** the frames that render what the user
+typed (keystroke-anchored, tagged `after-typing` with the `typed` text) — pulls
+the transcript, and prints a token/USD cost estimate. Then **invoke the
+`/session-analysis` skill**, which tells you (the agent) to read only those
+keyframes (after-typing first) and produce a timeline + auditor highlights (EPM
+elevation prompts, privileged tools, service/account changes) + a secrets-exposure
+note. For **SSH**, skip frames entirely — `analyze` points you at the transcript,
+which is the full input+output and far cheaper. This is the intended path for
+"show me / summarize the session from today".
+
 **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.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.67 → bt_cli-0.4.69}/src/bt_cli/pws/commands/sessions.py

@@ -5,7 +5,7 @@ import json
 import shutil
 import subprocess
 import time
-from datetime import datetime, timezone
+from datetime import date, datetime, timezone
 from pathlib import Path
 
 import httpx
@@ -35,6 +35,41 @@ SESSION_STATUS = {
 }
 
 
+def _norm_date(value: str) -> str:
+    """Validate a YYYY-MM-DD (or ISO) date arg and return its date portion."""
+    try:
+        datetime.strptime(value.strip()[:10], "%Y-%m-%d")
+    except (ValueError, AttributeError):
+        print_error(f"Invalid date '{value}'. Use YYYY-MM-DD.")
+        raise typer.Exit(2)
+    return value.strip()[:10]
+
+
+def _resolve_date_window(today: bool, on: str, since: str, until: str) -> tuple:
+    """Collapse the date flags into an inclusive (lo, hi) date window (YYYY-MM-DD
+    strings, either may be None). --today/--on pin both ends to one day."""
+    if today:
+        d = date.today().isoformat()
+        return d, d
+    if on:
+        d = _norm_date(on)
+        return d, d
+    return (_norm_date(since) if since else None, _norm_date(until) if until else None)
+
+
+def _started_in_window(s: dict, lo: str, hi: str) -> bool:
+    """True if the session's StartTime date falls within [lo, hi] (ISO date
+    strings sort lexicographically, so string compare on the date is correct)."""
+    d = (s.get("StartTime") or "")[:10]
+    if not d:
+        return False
+    if lo and d < lo:
+        return False
+    if hi and d > hi:
+        return False
+    return True
+
+
 def is_active(s: dict) -> bool:
     """A session is live (suspend/terminate-able) when Status == 1.
 
@@ -99,6 +134,10 @@ def list_sessions(
     system: int = typer.Option(None, "--system", help="Filter by managed system ID"),
     active: bool = typer.Option(False, "--active", help="Show only active (started, not ended) sessions"),
     status: str = typer.Option(None, "--status", "-s", help="Filter by raw numeric status code"),
+    today: bool = typer.Option(False, "--today", help="Only sessions that started today"),
+    on: str = typer.Option(None, "--on", help="Only sessions that started on this date (YYYY-MM-DD)"),
+    since: str = typer.Option(None, "--since", help="Only sessions on/after this date (YYYY-MM-DD)"),
+    until: str = typer.Option(None, "--until", help="Only sessions on/before this date (YYYY-MM-DD)"),
     limit: int = typer.Option(25, "--limit", "-l", help="Max rows to show (most recent first)"),
     fetch_all: bool = typer.Option(False, "--all", help="Show all sessions (the endpoint returns full history)"),
     output: str = typer.Option("table", "--output", "-o", help="Output format: table or json"),
@@ -110,11 +149,17 @@ def list_sessions(
     suspend/terminate), or --all to see everything. Output is newest-first and
     capped at --limit by default.
 
+    Date filters (--today/--on/--since/--until) match on StartTime's date and are
+    applied client-side (the endpoint returns the full history every call).
+
     Examples:
         bt pws sessions list --active
+        bt pws sessions list --today
+        bt pws sessions list --since 2026-06-01 --until 2026-06-30
         bt pws sessions list --system 13
         bt pws sessions list --all -o json
     """
+    lo, hi = _resolve_date_window(today, on, since, until)
     try:
         with get_client() as client:
             client.authenticate()
@@ -122,6 +167,8 @@ def list_sessions(
 
         if active:
             sessions = [s for s in sessions if is_active(s)]
+        if lo or hi:
+            sessions = [s for s in sessions if _started_in_window(s, lo, hi)]
 
         total = len(sessions)
         shown = sessions if fetch_all else sessions[:limit]
@@ -715,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)"),
@@ -758,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", "")}
@@ -807,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),
@@ -826,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.67/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.