bt-cli 0.4.38__tar.gz → 0.4.40__tar.gz

{bt_cli-0.4.38 → bt_cli-0.4.40}/.claude/skills/epml/SKILL.md

@@ -163,6 +163,54 @@ bt epml rbp policy revert
 bt epml rbp policy delete-all --yes-i-mean-it      # destructive, gated
 ```
 
+## Worked example: build a role from scratch
+
+End-to-end recipe for a "users in group X can run shells on all hosts at any time" role with I/O logging and a session banner. Mirrors the pattern of the tenant's existing roles (Postgres, Docker Admin, etc.).
+
+```bash
+# 1. Command group containing the commands the role allows
+bt epml rbp cmdgrps create --name "RootShells" --description "Root shells with arguments"
+# captures: id 35
+bt epml rbp cmdgrps commands add 35 --commands "bash *,sh *,ksh *,zsh *,csh *,bash,sh,ksh,zsh,csh"
+
+# 2. Role itself, all metadata in one shot
+bt epml rbp roles create \
+  --name "RootShells" \
+  --description "Root shell access — I/O logged" \
+  --comment    "Root shell access — I/O logged"  \
+  --tag        "RootAccess" \
+  --risk        9 \
+  --rpt         1 \
+  --action      A \
+  --iolog      '/iologs/%date%/%uniqueid%.iolog' \
+  --banner-text "Root Shell Access"
+# captures: id 126
+
+# 3. Wire up the four group assignments
+bt epml rbp roles cmdgrps   add 126 --ids 35              # cmdgrp: just IDs
+bt epml rbp roles hostgrps  add 126 --ids 1 --kind B      # All Hosts, both Submit and Run-as
+bt epml rbp roles usergrps  add 126 --ids 4 --kind S      # Administrators as Submit (who requests)
+bt epml rbp roles usergrps  add 126 --ids 3 --kind R      # 'root' as Run-as (whose identity)
+bt epml rbp roles tmdategrps add 126 --ids 1              # Any Time
+
+# 4. Verify
+bt epml rbp roles list -o json | python3 -c 'import json,sys;[print(json.dumps(r,indent=2)) for r in json.load(sys.stdin) if r["id"]==126]'
+bt epml rbp roles cmdgrps   list 126
+bt epml rbp roles hostgrps  list 126
+bt epml rbp roles usergrps  list 126
+bt epml rbp roles tmdategrps list 126
+bt epml rbp entitlement run -o json | grep RootShells     # rpt=1 makes it surface
+```
+
+The resulting banner displayed to users (server-substituted at session time):
+```
+############################################################
+ Policy:           Root Shell Access
+ Status:           %event%
+ Session Recorded: Yes
+############################################################
+```
+
 ## Test suites + transactions (the killer workflow)
 
 ```bash
@@ -211,7 +259,8 @@ bt epml quick tests-then-deploy --suite <suite_id>      # commits if pass; rollb
 - **Children share the parent's `id`** in GET responses — the listed `id` field is the cmdgrp/hostgrp/usergrp ID, not unique per child. The actual identifier is the `cmd`/`host`/`user` text.
 - **Role assignments take a single object per request, not an array**. The CLI loops under the hood; the wire body is e.g. `{"cmds": 35}`, `{"hosts": 1, "type": "S"}`, `{"users": 4, "type": "R"}`, `{"tmdates": 1}`.
 - **Hostgrp / usergrp assignments require a `type` field** (`S` = Submit / who requests, `R` = Run-as / whose identity the command runs under). Without `type` the request 400s with "RBP role type not in: [S,R]". CLI: `--kind S|R|B` on `roles hostgrps add` and `roles usergrps add`. `B` (default) creates both an S row and an R row for the same id — appropriate when the same group plays both roles. For "Admin requests, runs as root", do `--ids 4 --kind S` and `--ids 3 --kind R` separately.
-- **Roles need `rpt: 1`** to appear in `bt epml rbp entitlement run`. The role still functions for policy evaluation either way, but only `rpt=1` roles are surfaced in the report. Not yet exposed by the CLI — file-level edit via export/import is the workaround.
+- **Roles need `rpt: 1`** to appear in `bt epml rbp entitlement run`. The role still functions for policy evaluation either way, but only `rpt=1` roles are surfaced in the report. Set with `--rpt 1` on `roles create` / `roles update` (added in 0.4.38).
+- **Role update is upsert-on-id, not partial**: hitting POST `/roles` with `{id, ...}` *overwrites* the matching record — fields you omit get cleared. The CLI's `roles update` does read-modify-write (fetch the role, merge changes, post the whole record) so this feels partial. Role-child relations (rolecmds/roleusers/etc.) are filtered out of the merge so assignments survive an update. **If you hit the API directly via curl**, you must send the full record yourself.
 
 ## Known gaps (TODO)
 

{bt_cli-0.4.38/src/bt_cli/data → bt_cli-0.4.40}/CLAUDE.md

@@ -1,6 +1,6 @@
 # BT-CLI
 
-BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, and EPM Linux. **Version: 0.4.38**
+BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, and EPM Linux. **Version: 0.4.40**
 
 ## Setup
 
@@ -10,6 +10,15 @@ source .venv/bin/activate && source .env
 bt whoami   # Test all connections
 ```
 
+Each product reads its own `BT_<PRODUCT>_*` env vars. EPM Linux is the odd one out — it uses a Personal Access Token (PAT) against the BeyondTrust public API gateway:
+
+```bash
+export BT_EPML_API_URL=https://api.beyondtrust.io   # default
+export BT_EPML_SITE_ID=<site-uuid>                  # required
+export BT_EPML_PAT=PAT_xxx                          # required (mint at app.beyondtrust.io)
+export BT_EPML_DEFAULT_HOST=100                     # default PMUL host id (optional)
+```
+
 ## Skills Available
 
 Use these slash commands for detailed product guidance:
@@ -72,6 +81,9 @@ PASSWORD=$(bt pws quick checkout -s server -a admin --raw)
 - 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.
 - **EPML two authorizers**: spec claims `nomine-authorizer` (PAT) globally but the gateway has IAM-only routes (return 403 with AWS-flavored body). PAT cannot reach those. Documented per-op in `src/bt_cli/data/skills/epml/SKILL.md`. Where `/v6/pbul/rbp/...` exists alongside legacy `/pbul/{hostid}/rbp/...`, prefer legacy — v6 is mostly IAM-only.
+- **EPML body-shape gotchas**: role create needs `action ∈ {A,R}`; hostgrp/usergrp create needs `type ∈ {I,E}` (Internal=static / External=directory-resolved); role assignments need `--kind S|R|B` for hostgrps/usergrps (S=Submit user, R=Run-as user); collection deletes use `?id=N` query params (CLI loops); child collections (commands/hosts/users/tmdates) have **no per-item delete** — `clear` nukes all, use `replace` to keep some.
+- **EPML role update is upsert-on-id (overwrite, not partial)**: hitting `POST /roles` with `{id, ...}` clears any field you don't include. The CLI's `roles update` does read-modify-write so it feels partial; child relations are filtered out of the merge so assignments survive. Direct `curl` users must send the full record.
+- **EPML role banner format**: `bt epml rbp roles create --banner-text "Title"` builds a `############`-framed message using `%rbprole%`/`%event%` server substitutions, mirroring the appliance's existing roles. See the worked role example in the EPM-L SKILL.md.
 
 ## Functional vs Managed Accounts
 

{bt_cli-0.4.38 → bt_cli-0.4.40}/PKG-INFO

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

{bt_cli-0.4.38 → bt_cli-0.4.40}/pyproject.toml

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

{bt_cli-0.4.38 → bt_cli-0.4.40}/src/bt_cli/__init__.py

@@ -1,3 +1,3 @@
 """BeyondTrust Unified Admin CLI."""
 
-__version__ = "0.4.38"
+__version__ = "0.4.40"

{bt_cli-0.4.38 → bt_cli-0.4.40/src/bt_cli/data}/CLAUDE.md

@@ -1,6 +1,6 @@
 # BT-CLI
 
-BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, and EPM Linux. **Version: 0.4.38**
+BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, and EPM Linux. **Version: 0.4.40**
 
 ## Setup
 
@@ -10,6 +10,15 @@ source .venv/bin/activate && source .env
 bt whoami   # Test all connections
 ```
 
+Each product reads its own `BT_<PRODUCT>_*` env vars. EPM Linux is the odd one out — it uses a Personal Access Token (PAT) against the BeyondTrust public API gateway:
+
+```bash
+export BT_EPML_API_URL=https://api.beyondtrust.io   # default
+export BT_EPML_SITE_ID=<site-uuid>                  # required
+export BT_EPML_PAT=PAT_xxx                          # required (mint at app.beyondtrust.io)
+export BT_EPML_DEFAULT_HOST=100                     # default PMUL host id (optional)
+```
+
 ## Skills Available
 
 Use these slash commands for detailed product guidance:
@@ -72,6 +81,9 @@ PASSWORD=$(bt pws quick checkout -s server -a admin --raw)
 - 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.
 - **EPML two authorizers**: spec claims `nomine-authorizer` (PAT) globally but the gateway has IAM-only routes (return 403 with AWS-flavored body). PAT cannot reach those. Documented per-op in `src/bt_cli/data/skills/epml/SKILL.md`. Where `/v6/pbul/rbp/...` exists alongside legacy `/pbul/{hostid}/rbp/...`, prefer legacy — v6 is mostly IAM-only.
+- **EPML body-shape gotchas**: role create needs `action ∈ {A,R}`; hostgrp/usergrp create needs `type ∈ {I,E}` (Internal=static / External=directory-resolved); role assignments need `--kind S|R|B` for hostgrps/usergrps (S=Submit user, R=Run-as user); collection deletes use `?id=N` query params (CLI loops); child collections (commands/hosts/users/tmdates) have **no per-item delete** — `clear` nukes all, use `replace` to keep some.
+- **EPML role update is upsert-on-id (overwrite, not partial)**: hitting `POST /roles` with `{id, ...}` clears any field you don't include. The CLI's `roles update` does read-modify-write so it feels partial; child relations are filtered out of the merge so assignments survive. Direct `curl` users must send the full record.
+- **EPML role banner format**: `bt epml rbp roles create --banner-text "Title"` builds a `############`-framed message using `%rbprole%`/`%event%` server substitutions, mirroring the appliance's existing roles. See the worked role example in the EPM-L SKILL.md.
 
 ## Functional vs Managed Accounts
 

{bt_cli-0.4.38 → bt_cli-0.4.40}/src/bt_cli/data/skills/epml/SKILL.md

@@ -163,6 +163,54 @@ bt epml rbp policy revert
 bt epml rbp policy delete-all --yes-i-mean-it      # destructive, gated
 ```
 
+## Worked example: build a role from scratch
+
+End-to-end recipe for a "users in group X can run shells on all hosts at any time" role with I/O logging and a session banner. Mirrors the pattern of the tenant's existing roles (Postgres, Docker Admin, etc.).
+
+```bash
+# 1. Command group containing the commands the role allows
+bt epml rbp cmdgrps create --name "RootShells" --description "Root shells with arguments"
+# captures: id 35
+bt epml rbp cmdgrps commands add 35 --commands "bash *,sh *,ksh *,zsh *,csh *,bash,sh,ksh,zsh,csh"
+
+# 2. Role itself, all metadata in one shot
+bt epml rbp roles create \
+  --name "RootShells" \
+  --description "Root shell access — I/O logged" \
+  --comment    "Root shell access — I/O logged"  \
+  --tag        "RootAccess" \
+  --risk        9 \
+  --rpt         1 \
+  --action      A \
+  --iolog      '/iologs/%date%/%uniqueid%.iolog' \
+  --banner-text "Root Shell Access"
+# captures: id 126
+
+# 3. Wire up the four group assignments
+bt epml rbp roles cmdgrps   add 126 --ids 35              # cmdgrp: just IDs
+bt epml rbp roles hostgrps  add 126 --ids 1 --kind B      # All Hosts, both Submit and Run-as
+bt epml rbp roles usergrps  add 126 --ids 4 --kind S      # Administrators as Submit (who requests)
+bt epml rbp roles usergrps  add 126 --ids 3 --kind R      # 'root' as Run-as (whose identity)
+bt epml rbp roles tmdategrps add 126 --ids 1              # Any Time
+
+# 4. Verify
+bt epml rbp roles list -o json | python3 -c 'import json,sys;[print(json.dumps(r,indent=2)) for r in json.load(sys.stdin) if r["id"]==126]'
+bt epml rbp roles cmdgrps   list 126
+bt epml rbp roles hostgrps  list 126
+bt epml rbp roles usergrps  list 126
+bt epml rbp roles tmdategrps list 126
+bt epml rbp entitlement run -o json | grep RootShells     # rpt=1 makes it surface
+```
+
+The resulting banner displayed to users (server-substituted at session time):
+```
+############################################################
+ Policy:           Root Shell Access
+ Status:           %event%
+ Session Recorded: Yes
+############################################################
+```
+
 ## Test suites + transactions (the killer workflow)
 
 ```bash
@@ -211,7 +259,8 @@ bt epml quick tests-then-deploy --suite <suite_id>      # commits if pass; rollb
 - **Children share the parent's `id`** in GET responses — the listed `id` field is the cmdgrp/hostgrp/usergrp ID, not unique per child. The actual identifier is the `cmd`/`host`/`user` text.
 - **Role assignments take a single object per request, not an array**. The CLI loops under the hood; the wire body is e.g. `{"cmds": 35}`, `{"hosts": 1, "type": "S"}`, `{"users": 4, "type": "R"}`, `{"tmdates": 1}`.
 - **Hostgrp / usergrp assignments require a `type` field** (`S` = Submit / who requests, `R` = Run-as / whose identity the command runs under). Without `type` the request 400s with "RBP role type not in: [S,R]". CLI: `--kind S|R|B` on `roles hostgrps add` and `roles usergrps add`. `B` (default) creates both an S row and an R row for the same id — appropriate when the same group plays both roles. For "Admin requests, runs as root", do `--ids 4 --kind S` and `--ids 3 --kind R` separately.
-- **Roles need `rpt: 1`** to appear in `bt epml rbp entitlement run`. The role still functions for policy evaluation either way, but only `rpt=1` roles are surfaced in the report. Not yet exposed by the CLI — file-level edit via export/import is the workaround.
+- **Roles need `rpt: 1`** to appear in `bt epml rbp entitlement run`. The role still functions for policy evaluation either way, but only `rpt=1` roles are surfaced in the report. Set with `--rpt 1` on `roles create` / `roles update` (added in 0.4.38).
+- **Role update is upsert-on-id, not partial**: hitting POST `/roles` with `{id, ...}` *overwrites* the matching record — fields you omit get cleared. The CLI's `roles update` does read-modify-write (fetch the role, merge changes, post the whole record) so this feels partial. Role-child relations (rolecmds/roleusers/etc.) are filtered out of the merge so assignments survive an update. **If you hit the API directly via curl**, you must send the full record yourself.
 
 ## Known gaps (TODO)