bt-cli 0.4.73__tar.gz → 0.5.0__tar.gz

{bt_cli-0.4.73/src/bt_cli/data → bt_cli-0.5.0/.claude}/skills/entitle/SKILL.md

@@ -5,6 +5,33 @@ description: Entitle commands for JIT access, bundles, workflows, and permission
 
 # Entitle Commands (`bt entitle`)
 
+## Two API tokens — read vs. write-on-behalf-of-user
+
+Entitle issues two distinct kinds of bearer token. The CLI uses both:
+
+| Token | Config field | Env var | Used for |
+|---|---|---|---|
+| **Org / admin** | `entitle.api_key` | `BT_ENTITLE_API_KEY` | All read-only commands (`list`, `get`) and admin writes (revoke, delete) |
+| **User-context** | `entitle.user_api_key` | `BT_ENTITLE_USER_API_KEY` | On-behalf-of-a-user writes — currently `bt entitle requests create` |
+
+The org/admin token **cannot** create access requests because requests are
+made *as* a person, not on behalf of the org. If only the admin token is
+configured, `bt entitle requests create` exits early with a panel explaining
+how to add a user token.
+
+```yaml
+# ~/.bt-cli/config.yaml
+profiles:
+  default:
+    entitle:
+      api_url: https://api.us.entitle.io
+      api_key: <ORG_TOKEN>           # broad read access
+      user_api_key: <USER_TOKEN>     # personal token, for `requests create`
+```
+
+The user token is generated from `app.entitle.io` → user profile → API tokens
+→ **Create user token** (different page from the org token).
+
 ## IMPORTANT: Destructive Operations
 
 **ALWAYS confirm with the user before:**
@@ -296,10 +323,146 @@ bt entitle roles list --resource <resource_id>
 **Kubernetes:** EKS, AKS, GKE, Rancher
 **BeyondTrust:** Password Safe, PRA, Remote Support
 
+## Newer command families
+
+Added in 0.5.0; the CLI now covers 75 of the API's 77 operations.
+
+```bash
+# Grant/revoke work items behind an access request (read + status only)
+bt entitle tasks list
+bt entitle tasks get <task-id>
+bt entitle tasks set-status <task-id> --status todo|inProgress|done
+bt entitle tasks archive <task-id>
+
+# Agent tokens — these are real credentials
+bt entitle agent-tokens list
+bt entitle agent-tokens create --name "collector" -o json   # token shown ONCE
+bt entitle agent-tokens update <id> --name "new name"
+bt entitle agent-tokens delete <id>
+
+# Outbound webhooks — two separate families
+bt entitle audit-webhooks    list | get | create | update | enable | delete
+bt entitle workflow-webhooks list | get | create | update | delete
+
+# Delegation: send someone's queue to someone else
+bt entitle request-forwards list | get | for-user <user-id> | create | delete
+bt entitle review-forwards  list | get | create | delete
+
+# Identity plumbing
+bt entitle directory-groups list --search "DYN-ROLE"
+bt entitle user-accounts list | create | delete
+bt entitle users pats <user-id>
+bt entitle permissions account <account-id>
+bt entitle chats channels --integration-type slack
+```
+
+Writes were added to the families that previously had reads only: `roles`,
+`policies`, `workflows`, `integrations` all gained create/update/delete, and
+`resources` and `bundles` gained `update`.
+
+## Update semantics: PUT merges, but lists inside it do not
+
+Live-verified per family. **Every family merges** — a field you leave out of the
+body keeps its current value, so no command does read-modify-write and a `curl`
+sending one field is safe.
+
+Two qualifications that matter more than the rule:
+
+- **A list you *do* send replaces that list wholesale.** `--role`, `--tag`,
+  `--group`, `--duration` set the whole collection; they never append. Passing
+  `-g` alone drops every other target.
+- **`workflows` merges at the top level but REPLACES its `rules` array.** A
+  two-rule workflow plus a PUT carrying one rule leaves **one rule**, and each
+  rule object must be complete (`400 "rules.0.inGroups must be an array"`).
+
+## Writes that return 200 and do nothing
+
+The most dangerous behaviour in this API. All live-verified — **verify a write
+with a follow-up GET**, because the response will not tell you:
+
+| Operation | Silently ignored |
+|---|---|
+| `POST /roles` | drops `prerequisitePermissions` (CLI issues a follow-up PUT) |
+| `PUT /roles/{id}` | ignores `name`, `resource`, `virtualizedRole` |
+| `PUT /integrations/{id}` | ignores `allowChangingAccountPermissions`, `allowCreatingAccounts`, `readonly` |
+| `PUT /policies/{id}` | a `sortOrder` past the last policy keeps the old value |
+| workflow webhooks | `approvalAlgorithmIds` is read-only |
+| both webhook families | `{"enabled": false}` on create *and* update |
+| integrations update | an unknown `--owner` (but create 404s on it) |
+
+**`POST` on both forwards families is an UPSERT keyed on the forwarder** — a
+second create for the same person returns the *same id* with the target
+replaced, 200, no 409. "Create a forward for Alice" therefore silently
+redirects her queue away from whoever it pointed at. Check with
+`request-forwards for-user <id>` first.
+
+**`POST /usersAccounts` is idempotent** on `(user, account)`: it returns the
+pre-existing row with its original `createdAt` rather than creating a duplicate.
+A script that deletes "the row it just created" will be deleting a real one.
+
+## Pagination: the envelope tells you
+
+`pagination` present in the response means the endpoint really pages. Absent
+means `page`/`perPage` are **silently ignored** and one GET returns everything —
+requesting page 2 hands back the same first row.
+
+| Ignores paging | Really pages |
+|---|---|
+| `/tasks`, `/applications`, `/auditLogsWebhooks`, `/workflowsWebhooks` | `/agentTokens`, `/directoryGroups`, `/usersAccounts`, both `*Forwards` |
+
+`perPage` caps at **100** and 400s above it. `--limit` means *maximum results*
+and bounds the fetch, so a small limit is cheap; it does not mean page size.
+
+## Secrets and redaction
+
+- **`agent-tokens create` returns a ~776-character token exactly once.** An
+  immediate GET returns only `id` and `name`. It is surfaced solely under
+  `-o json`, redacted in tables, with a stderr warning that it cannot be
+  retrieved again. Capture it at creation or delete and recreate.
+- **Webhook header values are redacted by header NAME, not per hook.**
+  `Authorization`, `X-Api-Key`, `api-key`, `X-Secret`, `Token` read back as
+  `***`; `Cookie` and arbitrary names come back verbatim. **A GET-edit-PUT
+  round trip would store the literal `***` over a real secret**, which is why
+  neither webhook family offers `--file` and update sends only your flags.
+
+## Tenant-shaped gotchas (not CLI bugs)
+
+- **A policy has no name or description** — the body is only
+  `inGroups`/`bundles`/`roles`/`sortOrder`, so policies are trackable by UUID
+  alone. `POST` also rejects an empty grant (`"Policy must grant at least 1
+  permission"`), so a policy can never be created inert: any create is a real
+  grant for as long as it lives.
+- **Webhooks cannot be created disabled** in either family, and `/disable`
+  404s. `DELETE` is the only off switch — which is why `audit-webhooks` has
+  `enable` and deliberately no `--disable` flag.
+- **Deleted webhook names stay reserved**: recreating a just-deleted name 400s
+  with "Resource already exists".
+- **`chats channels`** needs the *user* token (the org token 401s) and accepts
+  only `--integration-type slack`. It returns
+  `500 chatsService.missingScopes` until the tenant's Slack app is
+  re-authorized with `channels:read,groups:read,mpim:read,im:read`; the CLI
+  exits 3 with that message rather than a generic failure.
+- **`orgRoles` is unreachable** — `GET /orgRoles` and
+  `PUT /orgRoles/identities` are 401 on *both* tokens, the same org-level
+  gating Pathfinder has. These are the only two API operations the CLI does not
+  implement, and they stay unimplemented until the gateway opens up.
+- **Bundle create needs at least one role** (`"roles must contain at least 1
+  elements"`), and **role create** needs only `name` + `resource` +
+  `requestable` — the spec's required `prerequisitePermissions` is the field
+  the server discards. Virtual Application resources also need
+  `virtualizedRole`.
+- **Omitting either side of a `usersAccounts` body is a 500, not a 400.**
+
 ## API Notes
 
 - Base path: `/public/v1`
-- Pagination: `page`/`perPage`
-- Response: `{"result": [...], "pagination": {...}}`
+- Pagination: `page`/`perPage`, but only where the response carries a
+  `pagination` key — see the table above. `perPage` caps at 100.
+- Response: `{"result": [...]}`, with `pagination` alongside it on the
+  endpoints that really page. Single GETs wrap the object in `result` too;
+  `eligibleJitAccess` is the exception, returning `{roles, bundles, pagination}`.
 - All IDs are UUIDs (strings)
-- Bearer token auth
+- Bearer token auth; some routes need the *user* token, not the org one
+- Coverage: 75 of 77 operations. The two missing are the `orgRoles` pair,
+  blocked by org-level gating. `tests/entitle/test_coverage.py` fails if that
+  drifts.

{bt_cli-0.4.73/src/bt_cli/data → bt_cli-0.5.0/.claude}/skills/pra/SKILL.md

@@ -14,6 +14,9 @@ description: Privileged Remote Access commands for jump items, vault accounts, a
 - `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
+- `bt pra users delete` - Deletes a user (non-admins only)
+- `bt pra policies group delete` - Deletes a Group Policy
+- `bt pra policies group {jumpoints|members|jump-groups|vault-accounts|vault-account-groups|teams} remove` - Detaches a sub-resource from a Group Policy
 
 List affected resources first, then ask for explicit confirmation.
 

{bt_cli-0.4.73 → bt_cli-0.5.0}/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.73**
+BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, EPM Linux, and the BeyondTrust Secrets API. **Version: 0.5.0**
 
 ## Setup
 
@@ -42,7 +42,7 @@ Use these slash commands for detailed product guidance:
 | Cross-product | `bt quick` | `pasm-onboard`, `pasm-offboard`, `pasm-search` |
 | Password Safe | `bt pws` | `systems`, `accounts`, `credentials`, `sessions`, `secrets`, `audit`, `quick` |
 | PRA | `bt pra` | `jump-items`, `vault`, `jump-groups`, `quick` |
-| Entitle | `bt entitle` | `integrations`, `resources`, `bundles`, `permissions`, `jit`, `audit` |
+| Entitle | `bt entitle` | `integrations`, `resources`, `roles`, `bundles`, `workflows`, `policies`, `permissions`, `users`, `accounts`, `requests`, `tasks`, `jit`, `audit`, `agent-tokens`, `audit-webhooks`, `workflow-webhooks`, `request-forwards`, `review-forwards`, `directory-groups`, `user-accounts`, `chats` |
 | EPM Windows | `bt epmw` | `computers`, `groups`, `policies`, `requests`, `quick` |
 | EPM Linux | `bt epml` | `rbp` (cmdgrps/hostgrps/usergrps/tmdategrps/roles/policy/tests/tx), `settings`, `users`, `audit`, `siems`, `quick` |
 | Secrets API | `bt secrets` | `folders`, `static`, `dynamic` (incl. `generate`), `leases`, `integrations` |
@@ -71,7 +71,7 @@ PASSWORD=$(bt pws quick checkout -s server -a admin --raw)
 | Product | Pagination | Response Format |
 |---------|------------|-----------------|
 | PWS | `limit`/`offset` | `{"TotalCount": N, "Data": [...]}` |
-| Entitle | `page`/`perPage` | `{"result": [...], "pagination": {...}}` |
+| Entitle | `page`/`perPage` (**only where `pagination` is in the response**; max 100) | `{"result": [...]}`, `pagination` alongside it when the endpoint really pages |
 | PRA | `per_page`/`current_page` (1-indexed) | Array (pagination in headers) |
 | EPMW | `pageNumber`/`pageSize` | `{"data": [...], "totalCount": N}` |
 | EPML | varies — `take`/`skip` (audit, siems), `start`/`len` (iologs), plain arrays | mostly arrays; some `{total, data}` |
@@ -92,8 +92,9 @@ PASSWORD=$(bt pws quick checkout -s server -a admin --raw)
 - **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. **`bt pws sessions analyze <id>` (or `--dir`)** preps a replay dump for LLM analysis without calling an LLM: reads `index.json`, selects **keyframes** (RDP frames whose PNG byte-size changed ≥`--threshold`%, dependency-free — no Pillow, UNION the frame that renders each **typed keystroke burst**, anchored via the recording `StartTime` → each keyframe tagged `screen-change`/`after-typing` with the `typed` text, so the model reads targeted spots not every frame), and prints a token/USD **cost estimate** (`--model opus|sonnet|haiku`) for focused (keyframes) vs all-frames; writes `analysis.json`. SSH → recommends the transcript over frames. Consumed by the `/session-analysis` skill (interactive; the model reads only the keyframes). 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
+- **Entitle `--limit` means *maximum results*, not page size** (fixed 0.5.0): it bounds the fetch, so a small limit is cheap. It used to be forwarded as `perPage` while `paginate()` walked every page anyway, which made a small `--limit` *more* work — `--limit 2` over `/usersAccounts` was ~978 requests. `users list --all` is uncapped; without it you get one page.
 - **Entitle tokens are region-bound**: a token minted in one region 401s `"The token received doesn't exist"` on the others. Servers: `api.entitle.io`, `api.us.entitle.io`, `api.ca.entitle.io` — set `BT_ENTITLE_API_URL`/`entitle.api_url` to the tenant's region (that misleading 401 also = wrong-region config, not just a dead token). **No `GET /users/{id}`** — `users get` resolves via `list_users(search=...)`.
+- **Entitle write semantics** (all live-verified, 0.5.0; full detail in the entitle SKILL.md): **PUT merges** in every family — omitted fields survive, so no command does read-modify-write — but **a list you do send replaces that list**, and **`workflows` replaces its whole `rules` array**. Beware the **silent 200-OK no-ops**: `POST /roles` discards `prerequisitePermissions`, `PUT /roles` ignores `name`/`resource`/`virtualizedRole`, `PUT /integrations` ignores its three create-only booleans, and neither webhook family accepts `{"enabled": false}` (**DELETE is the only off switch**). **`POST` on both forwards families is an upsert keyed on the forwarder** — creating one silently retargets any existing forward for that person; **`POST /usersAccounts` is idempotent** and returns the pre-existing row, so never delete "the row you just created" without checking its id against a baseline. **Webhook header values are redacted by header NAME** (`Authorization`/`X-Api-Key`/`Token` → `***`; `Cookie` verbatim), so a GET-edit-PUT round trip would write `***` over a real secret — hence no `--file` on webhooks. **`agent-tokens create` returns a one-shot ~776-char token** (`-o json` only). **`orgRoles` (2 ops) is 401 on both tokens** and is the only gap left; `tests/entitle/test_coverage.py` guards 75/77.
 - **Entitle `jit` / `audit`** (spec-derived, live-verified): `bt entitle jit list` wraps `GET /eligibleJitAccess` — with an org token `--user` is **required** (else 400), and the response is `{roles,bundles,pagination}` not the `result` envelope. `bt entitle audit search` wraps `POST /auditLogs/search` (Experimental) — **date window must be < 24h** (server 400s on ≥24h; CLI enforces client-side, default `--hours 24`), no pagination (returns all rows in range), each row's context is one of `integration`/`idp`/`ticket`/`user`. Full spec at `/projects/reference/entitle-api-reference.openapi.json`.
 - Windows builds: Rich must be pinned to `<14.0.0` (Rich 14 has PyInstaller unicode issues)
 - **EPML URL transform**: spec paths start with `/api/...` but real URL is `https://api.beyondtrust.io/site/<site-id>/epm/linux/<spec-path-minus-/api/>`. Encapsulated in client `_build_url` — never bypass it.

{bt_cli-0.4.73 → bt_cli-0.5.0}/PKG-INFO

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

bt_cli-0.5.0/entitle-gaps-implementation-plan.md

@@ -0,0 +1,378 @@
+# Plan: Close the Entitle API coverage gap in `bt entitle`
+
+## Context
+
+`bt entitle` implements **26 of the 77 operations** in the Entitle public API
+spec (`/projects/reference/entitle-api-reference.openapi.json`, 43 paths). This
+plan covers the **51 missing operations**.
+
+Measured 2026-09-03 by walking the live Typer tree (`core/command_tree.py`) and
+diffing call sites in `entitle/client/base.py` against the spec:
+
+| | count |
+|---|---|
+| Spec paths | 43 |
+| Spec operations | 77 |
+| Covered by the client | 26 |
+| **Missing** | **51** |
+| Existing `bt entitle` leaf commands | 27 |
+
+> **Correction (Phase 6):** the stale "43 paths vs CLI's 19" line is in the
+> project *memory* file, not CLAUDE.md — this plan named the wrong file in
+> Phase 0. Both are now updated. Count *operations*, not paths: a path with 5
+> methods is 5 units of work.
+
+Two families are missing entirely (no read, no write): `tasks`, `agentTokens`,
+`auditLogsWebhooks`, `workflowsWebhooks`, `accessRequestForwards`,
+`accessReviewForwards`, `usersAccounts`, `orgRoles`, `directoryGroups`,
+`chats/channels`. Four families have reads but no writes: `roles`, `policies`,
+`workflows`, `integrations`.
+
+### Prerequisites before any live phase
+
+1. **API keys.** Both tokens live in the Ninth Floor Vault:
+   `nfv get pws-prod-cli-workload` → `ENT-URL`, `ENT-KEY` (org/admin),
+   `ENT-USER-KEY` (user-context). Load them at runtime rather than writing them
+   to a `.env` — see `scratchpad/entitle-env.sh`.
+2. **Region: US.** `ENT-URL` is `https://api.us.entitle.io`. Entitle tokens are
+   region-bound — a token minted in one region returns
+   `401 "The token received doesn't exist"` on the others. **That 401 is also
+   the symptom of a wrong-region config, not just a dead token** — do not chase
+   it as an auth bug.
+3. **Two-token model.** `EntitleClient(config, use_user_token=...)` selects
+   between the org/admin token (`api_key`) and the user-context token
+   (`user_api_key`). Every new command must make a deliberate choice; see
+   Design decision 4.
+
+### Live reconnaissance (run 2026-09-03, both tokens, US tenant)
+
+Auth confirmed on both tokens (76 applications). Every missing read endpoint was
+probed. Three findings change this plan:
+
+**A. `pagination` in the envelope is the reliable signal for whether an endpoint
+actually paginates.** Where it is absent, `page`/`perPage` are silently ignored
+and a single GET returns the whole collection — verified by requesting
+`page=2&perPage=1` and getting back the same first row.
+
+| endpoint | envelope | pages? |
+|---|---|---|
+| `/tasks` | `{result}` | **no — ignores paging** |
+| `/auditLogsWebhooks` | `{result}` | **no — ignores paging** |
+| `/workflowsWebhooks` | `{result}` | **no — ignores paging** |
+| `/agentTokens` | `{pagination, result}` | yes |
+| `/directoryGroups` | `{pagination, result}` | yes |
+| `/usersAccounts` | `{pagination, result}` | yes |
+| `/accessRequestForwards` | `{pagination, result}` | yes |
+| `/accessReviewForwards` | `{pagination, result}` | yes |
+
+The three non-paginating endpoints are the `/Sessions` pattern from Password
+Safe. `paginate()` happens to terminate on them (`totalPages` defaults to 1), so
+this is not a hang — but calling it implies a pagination that does not exist.
+Use a single `get()` and cap display client-side, as `list_sessions` does.
+
+**B. `/orgRoles` is unreachable — 401 on *both* tokens** (`request.unauthorized`).
+`GET /orgRoles/identities` 404s, consistent with it being PUT-only. This is the
+same org-level gating seen in Pathfinder. **Both orgRoles operations are struck
+from the plan** and move to a documented-blocked list; `PUT
+/orgRoles/identities` cannot be verified, so it must not ship blind. That
+removes the riskiest operation in the original draft.
+
+**C. `/chats/channels` is user-token-only and needs `integrationType`.** The
+admin token always returns `401 "User must be logged in to use this action"`.
+With the user token, the parameter is mandatory and the enum has exactly one
+member — the server says so itself:
+`"integrationType must be one of the following values: slack"`. On this tenant
+the call then returns `500 chatsService.missingScopes`, i.e. the Slack
+integration lacks scopes. Ship the command with `--integration-type slack` as
+the only accepted value, and surface `missingScopes` as an actionable message
+rather than a generic 500.
+
+**D. `PUT` is a MERGE, not a full replace** (probed on a throwaway bundle,
+created and deleted in the same run). Sending only `{name, description}` left
+`category`, `tags`, `allowedDurations` and `roles` untouched. So **no
+read-modify-write is needed** — the EPM-L upsert-on-id trap does not apply here.
+A field that *is* sent replaces that field wholesale, so list-valued flags set
+the list rather than appending. Re-probe per family before relying on this in
+Phase 3; it is verified for `bundles` only.
+
+**E. Every `DELETE` in the client was broken.** `_get_headers()` set
+`Content-Type: application/json` on all requests including bodyless ones, and
+the server answers `400 "Body cannot be empty when content-type is set to
+'application/json'"`. That silently broke all three shipped delete paths —
+`bundles delete`, `resources delete`, `permissions revoke`. Fixed in Phase 0;
+the header is now sent only when there is a body.
+
+**F. Two body/query constraints the spec does not state.** `perPage` caps at
+**100** (larger 400s), now clamped in `paginate()`. And bundle create requires
+**at least one role** — `"roles must contain at least 1 elements"` — so
+`bundles create` without `--role` could never have succeeded; it now fails
+client-side with a message naming the fix.
+
+**G. Every family MERGES on PUT — with one important exception.** Probed
+per family on throwaway objects (Phase 3): bundles, roles, policies, resources
+and integrations all keep fields omitted from the body, so no `update` needs
+read-modify-write. **Workflows merges at the top level but replaces the `rules`
+array wholesale** — a 2-rule workflow plus a PUT carrying one rule leaves one
+rule, and a rule object must be complete (`400 "rules.0.inGroups must be an
+array"`). In every family a list you *do* pass is replaced, not appended.
+
+**H. Silent 200-OK no-ops are the real hazard here.** Several writes report
+success and do nothing: `POST /roles` drops `prerequisitePermissions`
+(so `roles create` follows up with a PUT); `PUT /roles` ignores
+`name`/`resource`/`virtualizedRole`; `PUT /integrations` accepts and ignores
+the three create-only fields (`allowChangingAccountPermissions`,
+`allowCreatingAccounts`, `readonly`); an unknown `--owner` is a no-op on
+integration update but 404s on create; and `PUT` with a raised `sortOrder`
+past the last policy silently keeps the old value. A `curl` user would believe
+all of these landed. Verify writes with a follow-up GET.
+
+**I. Spec inaccuracies found live.** `POST /roles` needs only
+`name` + `resource` + `requestable` (the spec's `prerequisitePermissions` is
+the field the server discards). Workflow approver types include **`Webhook`**
+and **`TeamsChannel`**, both absent from the published spec; the notified-type
+enum is that list minus `Automatic`. Integration create does not enforce the
+spec's `maintainers`/`prerequisitePermissions`/`agentToken`.
+
+**J. Policies cannot be created inert.** A policy has no `name` or
+`description` at all — the body is only `inGroups`/`bundles`/`roles`/
+`sortOrder`, so it is trackable by UUID alone — and `POST` rejects an empty
+grant with `400 "Policy must grant at least 1 permission"`. Any policy create
+is therefore a real grant for as long as it lives; do it only against a
+Virtual Application, which provisions nothing downstream.
+
+**K. Two writes silently overwrite or ignore, in ways the response hides.**
+`POST` on both forwards families is an **upsert keyed on the forwarder** — a
+second create for the same person returns the same id with the target replaced,
+200, no 409. A naive "create a forward for Alice" therefore silently
+redirects her queue away from whoever it pointed at. `POST /usersAccounts`, by
+contrast, is **idempotent** on `(user, account)`: it returns the pre-existing
+row with its original `createdAt` rather than creating a duplicate — so a
+caller that deletes "the row it just made" would be deleting a real one.
+
+**L. Webhooks cannot be created disabled, in either family.**
+`{"enabled": false}` is accepted with 200 and silently discarded on create and
+on `PUT`; `/disable` 404s. **DELETE is the only off switch.** The audit family
+therefore exposes `enable` with no `--disable`, because a `--disable` flag
+could only lie.
+
+**M. Header redaction is by header NAME, not per hook, and it breaks
+round-tripping.** `Authorization`, `X-Api-Key`, `api-key`, `X-Secret` and
+`Token` read back as `***`; `Cookie` and arbitrary names come back verbatim.
+Re-PUTting a body obtained from GET would therefore **store the literal `***`
+over a real secret**, so neither webhook family offers `--file`, and update
+sends only the flags given.
+
+**N. `POST /agentTokens` returns a one-shot ~776-char credential** in
+`{result:{id,name,token}}`; an immediate GET returns only `id`+`name`. It is
+surfaced solely under `-o json`, redacted in tables, with an stderr warning
+that it is unrecoverable. The spec documents this response bare, but it is
+enveloped live.
+
+**Revised scope: 49 implementable, 2 blocked.**
+
+---
+
+## Command tree (additions)
+
+```
+bt entitle
+├── tasks                  list | get | set-status | archive
+├── agent-tokens           list | get | create | update | delete
+├── audit-webhooks         list | get | create | update | delete | enable
+├── workflow-webhooks      list | get | create | update | delete
+├── request-forwards       list | get | get-for-user | create | delete
+├── review-forwards        list | get | create | delete
+├── user-accounts          list | create | delete
+├── directory-groups       list
+├── chats                  channels        (user token; --integration-type slack)
+├── users                  + pats
+├── permissions            + account
+├── roles                  + create | update | delete
+├── policies               + create | update | delete
+├── workflows              + create | update | delete
+├── integrations           + create | update | delete
+├── resources              + update
+└── bundles                + update        ← client method already exists
+```
+
+`bundles update` is not one of the 51: `EntitleClient.update_bundle()` already
+exists at `client/base.py:359` with no command exposing it. Free win, Phase 0.
+
+---
+
+## Implementation phases
+
+Ordered read-before-write so the models and table columns are already proven by
+the time a phase starts mutating a live tenant.
+
+### Phase 0 — Orphan + scaffolding (DONE)
+
+- Expose `bt entitle bundles update` over the existing `update_bundle()`.
+- Fix the `Content-Type` bug breaking every DELETE (finding E).
+- Clamp `perPage` to 100 and validate bundle-create roles (finding F).
+- Add `tests/entitle/test_coverage.py`: a **static guard** that parses the spec
+  and asserts every operation is either implemented or listed in an explicit
+  `KNOWN_UNIMPLEMENTED` set. This is the same class of fix as the derived
+  command tree in 0.4.73 — it makes the gap impossible to re-open silently, and
+  each later phase shrinks the allowlist.
+- Replace the placeholder block at `tests/entitle/test_commands.py:526`.
+
+### Phase 1 — Read-only, new families (11 ops) — DONE
+
+| Ops | Commands |
+|---|---|
+| `GET /tasks`, `GET /tasks/{id}` | `tasks list`, `tasks get` |
+| `GET /agentTokens`, `GET /agentTokens/{id}` | `agent-tokens list/get` |
+| `GET /directoryGroups` | `directory-groups list` |
+| `GET /chats/channels` | `chats channels` |
+| `GET /usersAccounts` | `user-accounts list` |
+| `GET /users/{id}/personalAccessTokens` | `users pats` |
+| `GET /permissions/{accountId}` | `permissions account` |
+| `GET /auditLogsWebhooks`, `GET /workflowsWebhooks` | `*-webhooks list` |
+
+Envelopes are already captured in finding A above — use that table rather than
+re-deriving it. `tasks`, `audit-webhooks`, and `workflow-webhooks` take a single
+`get()`, not `paginate()`. `chats channels` takes the **user** token.
+
+### Phase 2 — Read-only, single-item gets + forwards (7 ops) — DONE
+
+`GET` on `{id}` for `auditLogsWebhooks`, `workflowsWebhooks`,
+`accessRequestForwards`, `accessReviewForwards`, plus
+`GET /accessRequestForwards/user/{forwardUserId}`.
+
+Split from Phase 1 only so Phase 1 can ship while list-shape questions on the
+forwards families are still open.
+
+### Phase 3 — Complete the half-done families (15 ops) — DONE
+
+Writes on families that already have reads. Highest user-visible value: these
+groups currently look broken (`bt entitle roles list` works, `roles create`
+doesn't exist).
+
+- `roles` create / update / delete
+- `policies` create / update / delete
+- `workflows` create / update / delete
+- `integrations` create / update / delete
+- `resources` update
+
+**Live verify (create → update → delete on objects the agent itself made).**
+Record for each: required vs optional body fields, whether `PUT` is a full
+replace or a merge, and the 4xx body shape on validation failure.
+
+> **`PUT` merges — verified for `bundles` (finding D), not yet for the others.**
+> Probe each family the same way before writing its `update`: create a throwaway
+> object, `PUT` a partial body, and check whether the omitted fields survive. If
+> any family turns out to replace instead, that one needs read-modify-write and
+> a warning in the skill file for direct-`curl` users.
+
+### Phase 4 — Webhooks + agent tokens, write paths (10 ops) — DONE
+
+- `auditLogsWebhooks` create / update / delete / **enable** (`PUT {id}/enable`)
+- `workflowsWebhooks` create / update / delete
+- `agentTokens` create / update / delete
+
+**Handle the secret.** `POST /agentTokens` almost certainly returns a token value
+exactly once. It must go to stdout as data under `-o json`, never to a log or a
+status banner, and the table view should make the show-once behavior explicit.
+
+**Webhook targets are outbound, and an enabled one receives real data.**
+Creating an audit-log webhook on a live tenant means real audit events start
+being POSTed to whatever URL it names. **Do not use a request-bin or
+webhook.site style capture service** — that exfiltrates the tenant's audit
+trail to a third party, which is worse than the bug being tested for. Point it
+at `https://example.com/...` (IANA-reserved, nothing listening, nothing
+recorded), leave it disabled wherever the test allows, and delete every webhook
+created during verification.
+
+### Phase 5 — Forwards + user accounts (6 ops) — DONE
+
+- `accessRequestForwards` create / delete
+- `accessReviewForwards` create / delete
+- `usersAccounts` create / delete
+
+`orgRoles` is **excluded** — see finding B. Do not implement `org-roles list` or
+`set-identities` until the tenant's org-level gating is lifted; an unverifiable
+org-wide identity write is not worth shipping blind.
+
+### Phase 6 — Tests, skill, docs — DONE
+
+- Drain `KNOWN_UNIMPLEMENTED` in the Phase 0 guard to empty.
+- Update `src/bt_cli/data/skills/entitle/SKILL.md` with every new command plus
+  the envelope/body-shape findings from the live runs.
+- Fix the stale "43 paths vs CLI's 19" line — it lives in the project memory
+  file, not `CLAUDE.md` — and add any gotcha worth a permanent warning
+  (region-binding is already there).
+- **Do not touch `bt tree` / `bt find`** — they derive from the live Typer app.
+  New commands appear automatically; help text comes from the docstring's first
+  line, so **every new command needs a docstring** (see the 29 blank-help
+  commands found in the same audit that produced this plan).
+
+---
+
+## Files
+
+**Create** (`src/bt_cli/entitle/`):
+
+```
+commands/tasks.py              commands/agent_tokens.py
+commands/webhooks.py           commands/forwards.py
+commands/user_accounts.py      commands/directory_groups.py
+commands/chats.py
+models/task.py                 models/agent_token.py
+models/webhook.py              models/forward.py
+tests/entitle/test_coverage.py
+```
+
+**Modify:**
+
+```
+client/base.py                    +49 methods
+commands/__init__.py              register new sub-apps
+commands/{roles,policies,workflows,integrations,resources,bundles}.py
+commands/{users,permissions}.py   add pats / account
+src/bt_cli/data/skills/entitle/SKILL.md
+CLAUDE.md
+```
+
+---
+
+## Key design decisions
+
+1. **Group naming: kebab-case, mirroring the resource.** `agent-tokens`, not
+   `agenttokens` or `tokens`. Two webhook families stay separate
+   (`audit-webhooks`, `workflow-webhooks`) rather than a merged `webhooks
+   --type` — they are different endpoints with different bodies, and only the
+   audit one has `enable`.
+2. **`tasks` mutations get verbs, not `update`.** `PUT /tasks/{id}` only sets
+   status and `DELETE` archives rather than deletes. `tasks set-status` and
+   `tasks archive` say what actually happens; `tasks delete` would lie.
+3. **Pagination is chosen per endpoint from the finding-A table, not assumed.**
+   Endpoints whose envelope carries `pagination` go through `paginate()`; the
+   three that lack it take a single `get()` with client-side capping. Add a
+   comment at each single-`get()` call site saying why, so nobody "fixes" it
+   into a paginate later. If a new endpoint returns an envelope the four
+   existing branches don't handle, extend `paginate()` — never special-case at
+   the call site.
+4. **Token choice is explicit per command.** Default to the org token; use the
+   user token only where the API demands on-behalf-of semantics (as
+   `requests create` does). Where an org token 400s, surface the same
+   actionable error `jit list` gives, not a raw 400.
+5. **`-o json` purity is non-negotiable.** All banners, warnings, and
+   confirmations to stderr via `print_success`/`print_warning`/`err_console`,
+   and `typer.confirm(..., err=True)`. Enforced by
+   `tests/core/test_json_stdout_purity.py`.
+6. **Destructive commands require confirmation.** Every `delete`, `archive`,
+   `revoke`, and `set-identities` prompts unless `--yes`. Prompt goes to stderr.
+
+---
+
+## Verification
+
+Per phase: unit tests green, `tests/core/test_json_stdout_purity.py` green,
+`tests/core/test_command_tree.py` green, the Phase 0 coverage guard shrunk by
+exactly the phase's operation count, and a live run of every new command against
+the tenant with the response shape recorded in the skill file.
+
+Full-live-verify hygiene: every object an agent creates is deleted in the same
+phase. Nothing is created against a name that could collide with real tenant
+data — prefix all test objects `btcli-verify-<phase>-<uuid>`.

{bt_cli-0.4.73 → bt_cli-0.5.0}/pyproject.toml

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