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

{bt_cli-0.4.38 → bt_cli-0.4.39}/.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 → bt_cli-0.4.39}/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.39**
 
 ## Setup
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bt-cli
-Version: 0.4.38
+Version: 0.4.39
 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.39}/pyproject.toml

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

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

{bt_cli-0.4.38 → bt_cli-0.4.39}/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.39**
 
 ## Setup
 

{bt_cli-0.4.38 → bt_cli-0.4.39}/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)