bt-cli 0.4.41__tar.gz → 0.4.42__tar.gz

{bt_cli-0.4.41 → bt_cli-0.4.42}/PKG-INFO

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

bt_cli-0.4.42/epml-clients-server-side-filters-plan.md

@@ -0,0 +1,206 @@
+# Plan: Server-side filters + pagination on `bt epml clients list`
+
+## Goal
+
+Today `bt epml clients list` fetches the **entire** license-client inventory in one shot and filters client-side. The EPMLC API at `GET /api/epml/license/clients` supports server-side pagination, sorting, date-windowing, and pattern matching (per the [reference](https://docs.beyondtrust.com/epm-l/reference/epmlgetlicenseclients)). We don't expose any of that. On a tenant with thousands of clients it's slow and unnecessarily heavy.
+
+This plan adds the missing flags, keeps current behavior working, and tightens the listing for large tenants.
+
+## Current vs server
+
+| Server query param | Type | Today's CLI | Notes |
+|---|---|---|---|
+| `limit` | int | ❌ missing | server-side page size |
+| `offset` | int | ❌ missing | server-side page offset |
+| `older` | int (epoch) | ❌ missing | last-updated **before** |
+| `newer` | int (epoch) | ❌ missing | last-updated **since** |
+| `order` | enum (`uuid`/`fqdn`/`addr`/`lastupdated`/`retired`) | ❌ missing | sort field |
+| `direction` | enum (`asc`/`desc`) | ❌ missing | sort direction |
+| `fqdn` | string (wildcard) | ⚠️ client-side substring | server-side wildcard match |
+| `addr` | string (wildcard) | ❌ missing | server-side wildcard match |
+| `exclude_retired` | bool | ⚠️ client-side filter (`--include-retired` flips) | server-side equivalent |
+| `--component` | n/a | ✓ client-side only | NOT in server API; keep local |
+
+Source method: `EPMLClient.list_license_clients(host_id)` at `src/bt_cli/epml/client/base.py:237`.
+CLI command: `list_clients` at `src/bt_cli/epml/commands/clients.py:56`.
+
+## Proposed CLI surface
+
+```
+bt epml clients list [OPTIONS]
+
+  --host, -H              PMUL host id (uses host-scoped path)
+  --component, -c         License bucket filter (CLIENT-SIDE; server doesn't have this)
+                          {RBPClnts, PBULPolClnts, FIMClnts, SudoPolClnts}
+  --fqdn TEXT             FQDN wildcard (server-side; supports * and ?)
+  --addr TEXT             Address wildcard (server-side; supports * and ?)
+  --include-retired       Include retired clients (default: hidden via server's
+                          exclude_retired=true; flag flips it to false)
+  --since TEXT            Only clients updated since this time
+                          (accepts ISO-8601, "1h", "7d", or epoch)
+  --before TEXT           Only clients updated before this time (same formats)
+  --order [uuid|fqdn|addr|lastupdated|retired]
+                          Sort field (default: fqdn)
+  --direction [asc|desc]  Sort direction (default: asc)
+  --limit, -n INTEGER     Page size (default: 200; max: server-defined)
+  --all                   Iterate all pages until exhausted (overrides --limit
+                          for the per-call value but pages internally)
+  --output, -o            table | json
+```
+
+### Flag-naming notes
+
+- `--since` / `--before` are friendlier than `--newer` / `--older`. Accept ISO-8601, relative durations (`1h`, `7d`, `30m`), and raw epoch ints. Convert to epoch before the API call.
+- `--addr` mirrors the API param name verbatim (server already speaks wildcards there).
+- `--component` stays as a **client-side** filter with a warning in `--help` since the server doesn't support it.
+- Drop the current `--fqdn` substring behavior in favor of the server's wildcard matcher. If the user passes a plain string like `web-01`, transparently wrap in `*web-01*` so the substring UX is preserved. Document the auto-wrap behavior.
+- Default to `--exclude-retired=true` (matches today's UX where retired clients are hidden unless `--include-retired` is passed). Done via flipping the server param.
+
+## Implementation steps
+
+### 1. Extend `EPMLClient.list_license_clients`
+
+```python
+def list_license_clients(
+    self,
+    host_id: Optional[int] = None,
+    *,
+    limit: Optional[int] = None,
+    offset: Optional[int] = None,
+    older: Optional[int] = None,    # epoch
+    newer: Optional[int] = None,    # epoch
+    order: Optional[str] = None,    # uuid|fqdn|addr|lastupdated|retired
+    direction: Optional[str] = None,  # asc|desc
+    fqdn: Optional[str] = None,
+    addr: Optional[str] = None,
+    exclude_retired: Optional[bool] = None,
+) -> Dict[str, Any]:
+    """GET license clients with full server-side filter set."""
+    params: Dict[str, Any] = {}
+    for k, v in (
+        ("limit", limit), ("offset", offset),
+        ("older", older), ("newer", newer),
+        ("order", order), ("direction", direction),
+        ("fqdn", fqdn), ("addr", addr),
+        ("exclude_retired", exclude_retired),
+    ):
+        if v is not None:
+            params[k] = v
+    if host_id is not None:
+        return self.get(f"/api/pbul/{host_id}/licenseinfo/clients", params=params or None)
+    return self.get("/api/epml/license/clients", params=params or None)
+```
+
+Backwards-compatible: existing call sites pass no kwargs.
+
+### 2. Add a paginating helper for `--all`
+
+```python
+def iter_license_clients(
+    self,
+    page_size: int = 200,
+    **filters,
+) -> Iterator[Dict[str, Any]]:
+    """Yield every matching client across as many pages as needed."""
+    offset = 0
+    while True:
+        page = self.list_license_clients(limit=page_size, offset=offset, **filters)
+        rows = (page.get("Data") or page.get("data") or []) if isinstance(page, dict) else []
+        if not rows:
+            return
+        yield from rows
+        if len(rows) < page_size:
+            return
+        offset += page_size
+```
+
+### 3. Update the CLI command
+
+In `src/bt_cli/epml/commands/clients.py`:
+- Add the new typer options.
+- Parse `--since`/`--before` to epoch using a small helper (accept `1h`/`7d`/`30m` patterns + ISO-8601 + raw integer).
+- Auto-wrap plain `--fqdn` values in `*` if no glob char present (preserves substring UX).
+- Branch on `--all`: paginate via `iter_license_clients`, otherwise single page.
+- Keep `--component` as a post-filter (server doesn't support it). Document this in the option help text.
+
+### 4. Time-spec parser
+
+Small new helper in `core/timeparse.py` (or co-located if there's no shared util module):
+
+```python
+def parse_time_to_epoch(s: str) -> int:
+    """Accept '1h', '7d', '30m', ISO-8601, or raw epoch int. Return UTC epoch."""
+    ...
+```
+
+Used by both `--since` and `--before`. Tests cover each input form.
+
+### 5. Output formatting
+
+No change needed — `_flatten_user`-style helpers already handle the row shape. Only thing to verify: when paginating with `--all`, table rendering streams or buffers? For now buffer (dataset typically <10k rows; rich.Table handles fine). Document the trade-off.
+
+### 6. Tests
+
+In `tests/epml/test_clients.py` (or wherever the existing client tests live):
+
+- `test_list_license_clients_passes_server_params` — respx-mock, assert query string carries all the params we set
+- `test_list_license_clients_no_params_unchanged` — backwards compat: no kwargs → no `params` arg → same URL as today
+- `test_iter_license_clients_paginates` — three pages of 200 + a partial; verify offset progression and termination
+- `test_iter_license_clients_terminates_on_short_page`
+- `test_clients_list_command_auto_wraps_fqdn_substring` — `--fqdn web-01` becomes `*web-01*`; `--fqdn '*web*'` is passed through
+- `test_clients_list_command_since_relative` — `--since 1h` parses correctly
+- `test_clients_list_command_since_iso` — ISO-8601 form
+- `test_clients_list_component_is_post_filter` — server returns 100 rows; `--component RBPClnts` filters client-side
+- `test_parse_time_to_epoch_accepts_*` — unit tests for the helper
+
+### 7. Skill + docs
+
+Update `src/bt_cli/data/skills/epml/SKILL.md`:
+- The "License clients" section already exists. Replace with the new flag set.
+- Add a one-liner about `--all` and the auto-wrap fqdn behavior.
+
+Update `src/bt_cli/data/CLAUDE.md` if it has a clients line.
+
+Update `btcli/CLAUDE.md`'s API quirks table — add a note that EPML clients endpoint supports server-side pagination and sorting.
+
+## Backwards compatibility
+
+- `--component`, `--fqdn`, `--include-retired`, `--host`, `--output` all keep their current meaning.
+- `--fqdn`'s substring semantics preserved via the auto-wrap.
+- Default sort changes from "whatever the server returned" to `fqdn asc` — small cosmetic change; document it.
+
+## Edge cases
+
+- **Empty Data array on a non-zero `Total`** — server bug or a filter that removed everything; treat as "end of pages" in `iter_license_clients`.
+- **Server caps `limit`** — if the server returns fewer rows than asked, that's normal pagination, not necessarily end-of-data. The "fewer than page_size → done" heuristic is good enough today but could need revisiting.
+- **`--all` with `--limit`** — `--limit` becomes the per-call page size; `--all` toggles iteration. Document.
+- **Wildcard escape** — server interprets `*` and `?`. If a user has a literal `*` in an fqdn (unlikely but possible), no escape syntax exists. Note in help text.
+
+## Verification
+
+```bash
+# Single page, default
+bt epml clients list
+
+# Server-side fqdn wildcard
+bt epml clients list --fqdn 'web-*'
+
+# Server-side address wildcard
+bt epml clients list --addr '10.0.0.*'
+
+# Recent activity
+bt epml clients list --since 1h
+bt epml clients list --since 2026-05-01T00:00:00Z
+
+# Sorted
+bt epml clients list --order lastupdated --direction desc --limit 20
+
+# Full sweep
+bt epml clients list --all -o json | jq '.Data | length'
+```
+
+## Out of scope
+
+- `bt epml clients retire` flag additions (separate endpoint; can mirror later if needed).
+- Changing the `host-scoped` URL behavior (`/api/pbul/{hostid}/licenseinfo/clients`) — current logic keeps it.
+- Streaming output for `--all` (buffer for now).

bt_cli-0.4.42/pf-implementation-plan.md

@@ -0,0 +1,187 @@
+# Plan: Add Pathfinder (PF) Product to BeyondTrust CLI
+
+## Context
+
+The BeyondTrust CLI (`bt-cli`) currently supports 4 products: PWS, PRA, Entitle, and EPMW. The Pathfinder platform (internally "Nomine Authentication API") handles identity management — users, machine-to-machine auth, SAML providers, site/product access control, tokens, and auditing. Its OpenAPI spec lives at `/projects/reference/apidoc/pf/swagger.yaml` (67+ endpoints, 80+ schemas). This plan adds full PF support following the established patterns.
+
+## Command Tree: `bt pf`
+
+```
+bt pf
+  auth test|status
+  users list|get|me|access|my-access|update|delete|bulk-delete|invite|cancel-invite
+  machines list|get|create|delete|activate
+  auditing list
+  saml list|create|import|update|delete
+  product-access list|org|org-defaults|grant|revoke|grant-org|revoke-org
+  site-access list|org|grant|revoke|grant-org|revoke-org
+  tokens list|create|delete
+  mcp-tokens list|create|delete
+  mfa enable|disable|disable-user|count
+```
+
+## Implementation Phases
+
+### Phase 1: Foundation (core infra + auth test)
+
+**1a. Add `MachineAuth` strategy** — `src/bt_cli/core/auth.py`
+- New class: `MachineAuth(AuthStrategy)` with `machine_id`, `machine_secret`
+- `authenticate()`: POST `/bt.identity/Machine/AccessToken` with JSON `{machineId, machineSecret}`
+- Returns `{access_token, token_type, expires_in}` → sets Bearer token
+- No sign_out needed (JWT is stateless)
+
+**1b. Add `PFConfig`** — `src/bt_cli/core/config.py`
+- Dataclass: `PFConfig(ProductConfig)` with `machine_id: str`, `machine_secret: str`
+- `load_pf_config()` function — env vars: `BT_PF_API_URL`, `BT_PF_MACHINE_ID`, `BT_PF_MACHINE_SECRET`, `BT_PF_VERIFY_SSL`, `BT_PF_TIMEOUT`
+- Add `"pf": load_pf_config` to `load_config()` dispatcher
+
+**1c. Update config_file.py** — `src/bt_cli/core/config_file.py`
+- Add `"pf"` entry to `PRODUCTS` dict (fields: api_url, machine_id, machine_secret, verify_ssl, timeout)
+
+**1d. Create module structure:**
+- `src/bt_cli/pf/__init__.py`
+- `src/bt_cli/pf/client/__init__.py` — exports `PFClient, get_client`
+- `src/bt_cli/pf/client/base.py` — client with context manager, token caching, HTTP methods
+- `src/bt_cli/pf/commands/__init__.py` — registers all sub-typer apps
+- `src/bt_cli/pf/commands/auth.py` — `test` (call list_users limit=1) and `status`
+- `src/bt_cli/pf/models/__init__.py`
+- `src/bt_cli/pf/models/common.py` — `CommandResponse` base model
+
+**1e. Register in CLI** — `src/bt_cli/cli.py`
+- Add `_get_pf_app()` lazy loader (after line 83)
+- Add `app.add_typer()` registration (after line 124)
+- Update help text in `main_callback` docstring to include Pathfinder
+
+**Verify:** `bt pf auth test` connects and authenticates.
+
+### Phase 2: Core Resources (users, machines, auditing)
+
+**2a. Models:**
+- `models/user.py` — `NomineUser` (id, email, firstName, lastName, active, mfaEnabled)
+- `models/machine.py` — `Machine` (id, activationToken, active, tenantId, organizationId, timestamps)
+- `models/audit.py` — `AuditRecord` (id, userId, organizationId, auditTimeUtc, description, metadata)
+
+**2b. Client methods** in `pf/client/base.py`:
+- Users: `list_users()`, `get_user_info()`, `get_user_access()`, `get_my_access()`, `update_user()`, `delete_user()`, `bulk_delete_users()`, `invite_user()`, `cancel_invitation()`
+- Machines: `list_machines()`, `get_machine()`, `create_machine()`, `delete_machine()`, `activate_machine()`
+- Auditing: `list_audit_records()`
+
+**2c. Commands:**
+- `commands/users.py` — 10 subcommands
+- `commands/machines.py` — 5 subcommands
+- `commands/auditing.py` — 1 subcommand (list with date/email/description filters)
+
+**API quirks:**
+- `GET /api/Users` returns plain array (no pagination wrapper)
+- `GET /api/Machine` returns only UUIDs in `machines[]`, need `GET /api/Machine/{id}` for details
+- Machine create returns `activationToken` (30min TTL) → `activate` exchanges code for `machineSecret`
+
+### Phase 3: Access Management (product-access, site-access, saml)
+
+**3a. Models:**
+- `models/access.py` — `ProductAccessRule`, `SiteAccessRule`
+- `models/saml_provider.py` — `SamlProvider`
+
+**3b. Client methods:**
+- Product access: `list_product_access()`, `list_org_product_access()`, `get_org_defaults()`, `grant_product_access()`, `revoke_product_access()`, `grant_org_product_access()`, `revoke_org_product_access()`
+- Site access: `list_site_access()`, `list_org_site_access()`, `grant_site_access()`, `revoke_site_access()`, `grant_org_site_access()`, `revoke_org_site_access()`
+- SAML: `list_saml_providers()`, `create_saml_provider()`, `import_saml_provider()`, `update_saml_provider()`, `delete_saml_provider()`
+
+**3c. Commands:**
+- `commands/product_access.py` — 7 subcommands
+- `commands/site_access.py` — 6 subcommands
+- `commands/saml.py` — 5 subcommands (import reads XML file from disk)
+
+### Phase 4: Tokens & MFA
+
+**4a. Models:**
+- `models/token.py` — `UserPersonalAccessToken`, `UserMcpAccessToken`
+
+**4b. Commands:**
+- `commands/tokens.py` — list, create (--expiration-days), delete
+- `commands/mcp_tokens.py` — list, create (--expiration-days), delete
+- `commands/mfa.py` — enable (--token-code), disable, disable-user, count
+
+### Phase 5: CLI Integration
+
+Update `src/bt_cli/cli.py`:
+- Add `_test_pf_connection()` → call `get_user_info()` for whoami
+- Add PF to `whoami` command results
+- Add PF section to `tree_command` + add `"pf"` to valid product list
+- Add all PF commands to `_get_all_commands()`
+- Update `skills` command help text
+
+### Phase 6: Tests
+
+**6a. Fixtures** — `tests/conftest.py`: add `mock_pf_config`, `pf_env_vars`
+**6b. Mock responses** — `tests/fixtures/responses.py`: add `PF_*` constants
+**6c. Test files:**
+- `tests/pf/__init__.py`
+- `tests/pf/test_client.py` — client unit tests with `@respx.mock`
+- `tests/pf/test_commands.py` — CLI command tests with patched config/client
+
+### Phase 7: Skill File
+
+- `src/bt_cli/data/skills/pf/SKILL.md` — command reference, destructive ops warnings, workflow examples, API quirks
+- Update `btcli/CLAUDE.md` and `src/bt_cli/data/CLAUDE.md` to include PF
+
+## Files to Create (27 files)
+
+| File | Purpose |
+|------|---------|
+| `src/bt_cli/pf/__init__.py` | Package marker |
+| `src/bt_cli/pf/client/__init__.py` | Export PFClient, get_client |
+| `src/bt_cli/pf/client/base.py` | HTTP client with Machine auth token caching |
+| `src/bt_cli/pf/commands/__init__.py` | Register all command sub-apps |
+| `src/bt_cli/pf/commands/auth.py` | test, status |
+| `src/bt_cli/pf/commands/users.py` | User management (10 commands) |
+| `src/bt_cli/pf/commands/machines.py` | Machine registration (5 commands) |
+| `src/bt_cli/pf/commands/auditing.py` | Audit log listing |
+| `src/bt_cli/pf/commands/saml.py` | SAML provider CRUD + import |
+| `src/bt_cli/pf/commands/product_access.py` | Product access rules (7 commands) |
+| `src/bt_cli/pf/commands/site_access.py` | Site access rules (6 commands) |
+| `src/bt_cli/pf/commands/tokens.py` | Personal access tokens |
+| `src/bt_cli/pf/commands/mcp_tokens.py` | MCP access tokens |
+| `src/bt_cli/pf/commands/mfa.py` | MFA management |
+| `src/bt_cli/pf/models/__init__.py` | Package marker |
+| `src/bt_cli/pf/models/common.py` | CommandResponse base |
+| `src/bt_cli/pf/models/user.py` | NomineUser |
+| `src/bt_cli/pf/models/machine.py` | Machine |
+| `src/bt_cli/pf/models/audit.py` | AuditRecord |
+| `src/bt_cli/pf/models/saml_provider.py` | SamlProvider |
+| `src/bt_cli/pf/models/access.py` | ProductAccessRule, SiteAccessRule |
+| `src/bt_cli/pf/models/token.py` | PAT, MCP token models |
+| `tests/pf/__init__.py` | Test package |
+| `tests/pf/test_client.py` | Client unit tests |
+| `tests/pf/test_commands.py` | CLI command tests |
+| `src/bt_cli/data/skills/pf/SKILL.md` | Claude Code skill |
+
+## Files to Modify (7 files)
+
+| File | Change |
+|------|--------|
+| `src/bt_cli/core/auth.py` | Add `MachineAuth` class (~30 lines) |
+| `src/bt_cli/core/config.py` | Add `PFConfig` dataclass + `load_pf_config()` (~40 lines) |
+| `src/bt_cli/core/config_file.py` | Add `"pf"` to PRODUCTS dict (~15 lines) |
+| `src/bt_cli/cli.py` | Lazy loader, registration, whoami, tree, find, help text |
+| `tests/conftest.py` | Add `mock_pf_config`, `pf_env_vars` fixtures |
+| `tests/fixtures/responses.py` | Add `PF_*` mock response constants |
+| `btcli/CLAUDE.md` + `src/bt_cli/data/CLAUDE.md` | Add PF to docs |
+
+## Key Design Decisions
+
+1. **Auth: New `MachineAuth` strategy** — PF uses `machineId`+`machineSecret` → JWT, not standard OAuth form-encoded flow. Clean separation.
+2. **No path prefix** — PF endpoints are at `/api/*` and `/bt.identity/*` directly off base URL (unlike PWS `/api/public/v3` or Entitle `/public/v1`).
+3. **Pagination** — PF uses `page`/`pageSize` but some endpoints (GET /api/Users) return plain arrays. Client handles both.
+4. **Skip browser/internal endpoints** — `/bt.identity/Authentication/*`, `/api/noauth/*`, `/api/Support/*`, `/Test/*` are not CLI-appropriate.
+5. **Env var prefix: `BT_PF_`** — Consistent with `BT_PWS_`, `BT_PRA_`, etc.
+
+## Verification
+
+1. `bt pf auth test` — connects with machine credentials
+2. `bt pf users list` / `bt pf users me` — reads user data
+3. `bt pf machines list` — lists registered machines
+4. `bt tree pf` — shows full command tree
+5. `bt whoami` — includes PF status
+6. `pytest tests/pf/ -v` — all unit tests pass
+7. `bt find saml` — finds PF SAML commands

{bt_cli-0.4.41 → bt_cli-0.4.42}/pyproject.toml

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