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

bt_cli-0.6.0/.claude/skills/pf/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: pf
+description: Pathfinder platform commands — whoami, site/product access, PAT/MCP token listing, machine registry, user invites and product/site access grants, workload identities (OIDC trust for CI/pods/apps) and Cedar IAM policies that grant access to Workload Credentials. Use when working with the Pathfinder portal API (Nomine), platform PATs, site IDs, user onboarding, machine identities, workload identities, or IAM/RBAC policies.
+---
+
+# Pathfinder Platform (`bt pf`)
+
+The Pathfinder platform API (internal name: **Nomine**) manages the BeyondTrust
+cloud portal layer: users, sites, product access, tokens, and machine
+identities, plus the auth service's **workload identities** and the **IAM
+policy service** (Cedar RBAC). `bt pf` talks to it through the public API
+gateway with PAT auth — the same pattern as `bt wlc` / `bt epml`.
+
+## Configuration
+
+```bash
+export BT_PF_API_URL=https://api.beyondtrust.io   # default
+export BT_PF_SITE_ID=<site-uuid>                  # required — the site the PAT was minted on
+export BT_PF_PAT=PAT_xxx                          # required (mint at app.beyondtrust.io → Manage Profile)
+```
+
+Site ID discovery: log into app.beyondtrust.io, choose your site, then browse
+to `https://app.beyondtrust.io/api/platform/currentSite`.
+
+**For `bt pf policies` and `bt pf wi`, point `pf` at the Administration site**:
+the **org id doubles as the Administration site id**, and the PAT must be
+minted there. The policy commands also need the **WLC site id** for Cedar's
+`@siteId` — taken from the `wlc` config (`BT_WLC_SITE_ID`), overridable with
+`--site`. Two sites, two PATs, because PATs are site-bound.
+
+## URL mapping (the thing everyone gets wrong)
+
+The Nomine swagger writes paths as `/api/auth/X`. On the gateway the product
+segment is `platform` and the `auth/` prefix stays:
+
+    spec /api/auth/UserInfo  →  https://api.beyondtrust.io/site/<site-id>/platform/auth/UserInfo
+
+**PATs are site-bound**: minted while a site is active in the portal, valid
+only for that site's `/site/<id>/...` paths. Any other site → `401 Access
+denied for this site`. A just-minted PAT can take ~1s to propagate
+(transient `401 Personal access token not found` — retry once).
+
+## Commands
+
+```bash
+bt pf auth test            # connectivity + PAT validity
+bt pf whoami               # UserInfo for the PAT owner
+bt pf access               # site + product access rules (also -o json)
+bt pf pats list            # PATs (values masked; --show-tokens to reveal)
+bt pf mcp-tokens list      # MCP tokens (same masking)
+bt pf machines list        # registered machine IDs
+bt pf machines get <uuid>  # one machine's record (secret hash never shown)
+bt pf wi list              # workload identities (alias of `bt pf workload-identities`)
+bt pf policies list        # Cedar IAM policies (deleted ones hidden; --all shows them)
+```
+
+## User onboarding & access assignment (`bt pf users`)
+
+```bash
+# Invite a user to the org (sends a real email; confirms unless --yes).
+# Default site = BT_PF_SITE_ID; -p grants products on that site at invite time.
+bt pf users invite -e new.user@corp.com --first-name New --last-name User \
+    -p pra -p epml
+
+bt pf users cancel-invite new.user@corp.com   # cancel a pending invite
+
+# Per-user product access on a site (product slugs are lowercase:
+# epmwm, pra, psc, rs, entitle, epml, insights, secrets)
+bt pf users grant  -u <user-uuid> -p epml          # default site
+bt pf users revoke -u <user-uuid> -p epml -s <site-uuid>
+
+# Site membership (optionally granting products in the same call)
+bt pf users add-to-site      -u <user-uuid> -s <site-uuid> -p pra -p psc
+bt pf users remove-from-site -u <user-uuid> -s <site-uuid>
+
+bt pf users delete <user-uuid> [...]   # bulk delete (org admin; confirms)
+bt pf users list                       # every page (admin-site PAT with 'admin' scope); --page N for one
+```
+
+**PAT matters (re-verified 2026-10-21):** the org-admin surface answers only a
+PAT minted on the **Administration site** (`BT_PF_SITE_ID` = the org id) that
+carries the **`admin`** scope. With that PAT, `auth/Users`, `auth/SAMLProviders`,
+`auth/Auditing` and `auth/{productaccess,siteaccess,access}/org` are all **200**.
+A product-site PAT still gets the empty-body 403 on every one of them, and that
+is what every PAT we had on 2026-06-11 got, which is why these commands looked
+permanently blocked. Every Administration-site command (`users`, `policies`, `wi`)
+shares one contract: an empty-body 403 (the wrong kind of PAT) exits **3** with a
+hint naming the fix; a 401, or a 403 with a body, exits 1.
+
+Writes work too, with the admin-scoped PAT (2026-10-21):
+- `bt pf users delete` removes the Pathfinder user record only, never the IdP
+  (Entra ID etc.) account.
+- `bt pf users invite -s <site> -p <slug>...` → `{inviteId, userId,
+  organizationId, email, isFederated}`. The user then lists as `status:
+  Invited`, `active: false`, with a **new** user id. A re-invited former SAML
+  user came back with `isFederated: false`.
+
+- `bt pf users add-to-site` / `remove-from-site` / `grant` / `revoke` all work
+  (live round trip on a test user, 2026-10-21, net zero). Order matters:
+  - **Site first:** a product grant on a site the user isn't a member of →
+    `404 "User does not have site access"`. Run `add-to-site` first.
+  - **Revoking a rule that doesn't exist** → `500 "Unable to remove product
+    access rule."` (exit 1), not a 404.
+- **Reading access back:** site membership is visible through `users list
+  --site-id <site>` (`auth/Users?siteId=`). Product rules aren't:
+  `auth/productaccess?userId=` is in the swagger but 404s on the gateway.
+- **A pending invite creates no site rule** until it's accepted, so an invitee
+  doesn't show in `users list --site-id` for the invited site.
+- `cancel-invite` removes the invitation, but the user record keeps
+  `status: Invited`, so the list can't tell a live invite from a cancelled one.
+  Re-inviting the same email **reuses that user id** and sends a fresh email.
+  After a full `delete`, the next invite gets a new id.
+- The org's *default* access rules (`auth/{site,product}access/org`) may grant
+  products to every user anyway. `invite` sends a
+real email. Note `invite`'s default site is `BT_PF_SITE_ID`, which for these
+commands is the Administration site, so pass `-s <product-site>` to grant
+products on a real site.
+
+`users list` pages for you: without paging params the server returns a bare
+array **capped at 200** (no total), and with `page`/`pageSize` it returns
+`{users, totalCount}`. The CLI asks for 1000 per page, walks pages to
+`totalCount`, de-duplicates by id, and warns if it comes up short.
+`--page N` fetches just that page.
+
+## Workload identities (`bt pf workload-identities`, alias `bt pf wi`)
+
+OIDC issuer trust configs for non-human callers (CI jobs, k8s pods, Azure
+apps). Administration site, admin PAT. An identity is granted **nothing**
+until a policy names it.
+
+| Command | Method & path |
+|---|---|
+| `list [--wlc] [--for-site S]` | `GET /site/{admin}/platform/auth/workload-identities` → `{issuers: [...], totalCount}` |
+| `get <id>` | `GET .../workload-identities/{id}` → `{issuer: {...}}` — CLI also lists the live policies naming it |
+| `create` | `POST .../workload-identities` → `{issuer}` |
+| `update <id>` | `PUT .../workload-identities/{id}` — full body, read-modify-write |
+| `delete <id>` | `DELETE .../workload-identities/{id}` (confirms; `--yes`) |
+
+Item keys (live): `conditions, description, expectedAud, identityId,
+idpCategory, issuerUrl, organizationId, registeredScopes, scopeLevel,
+serviceName, siteId, sites` (`sites[]` = `{siteId, registeredScopes,
+scopeLevel, expectedAud}`).
+
+```bash
+bt pf wi create -n k8s-wc-reader --issuer-url https://kubernetes.default.svc --idp-category Custom \
+    -c sub=system:serviceaccount:demo-app:wc-reader --scope secrets --dry-run
+bt pf wi create -n gh-deploy --issuer-url https://token.actions.githubusercontent.com \
+    --idp-category GitHubActions -c "sub=repo:owner/repo:*" -c ref=refs/heads/main
+bt pf wi update <id> --description "new"          # -c / --conditions-file REPLACE all conditions
+```
+
+Rules checked client-side (ported from the Terraform provider):
+`idpCategory` ∈ GitHubActions | AzureEntra | Custom; ≥ 1 registered scope
+(`secrets` = WLC, default; `psc`, `admin` also seen); condition values
+non-empty, ≤ 256 chars, at most one `*` and only at the end; GitHubActions
+keys ∈ {sub, repository, repository_owner, ref, job_workflow_ref,
+workflow_ref, environment, event_name, actor} and `sub` must start
+`repo:<owner>/<repo>`. Only `conditions`, `description`, `scopeLevel`,
+`registeredScopes` are updatable; the service lower-cases `serviceName` and
+`issuerUrl`.
+
+## IAM policies (`bt pf policies`) — Cedar RBAC for Workload Credentials
+
+| Command | Method & path (admin site) |
+|---|---|
+| `list [--all]` | `GET /site/{admin}/platform/iam/policies` → `{policies: [...]}`; DELETED / PENDING_UNBIND hidden unless `--all` |
+| `get <name>` | `GET .../iam/policies/{name}` |
+| `apply <name> -f p.cedar` / `--stdin` | `PUT .../iam/policies/{name}`, **`Content-Type: text/plain`**, raw Cedar — upsert |
+| `grant ...` | build Cedar from flags, show it, confirm (says REPLACE if the name is live), PUT, wait |
+| `render ...` | same flags, print Cedar (`--curl` for the curl). No write |
+| `validate -f p.cedar` | local checks only |
+| `delete <name>` | `DELETE .../iam/policies/{name}` — soft delete (then listed as DELETED) |
+| `wait <name>` | poll until ACTIVE / WAITING_FOR_RESOURCE (`--timeout`) |
+
+Policy object: `name, cedar, status, product, site, createdAt, updatedAt`
+(no id, no description). No pagination (query params ignored, 2026-10-21).
+
+Cedar the service accepts — one `permit`, `@siteId` = the site the grant
+applies to (the **WLC** site, not the admin site):
+
+```cedar
+@siteId("<wlc-site-uuid>")
+permit(
+  principal == Pathfinder::Workload::Id::"<identityId>",   // or User::Email / Group / Role
+  action in [WorkloadCredentials::Action::"ReadSecret", WorkloadCredentials::Action::"ListFolderContents"],
+  resource == WorkloadCredentials::Folder::"/btlab/app/demo" // or Secret / DynamicSecret / Integration, or `resource is WorkloadCredentials::Product`
+);
+```
+
+Not supported: `forbid`, `when`, `unless`, multiple statements, missing
+`@siteId`. Roles are written as actions (`WorkloadCredentials::Action::"Viewer"`,
+`Pathfinder::Action::"Admin"`). Full action catalog, role expansion and the
+folder cascade are in the `/wlc` skill.
+
+```bash
+# Viewer for k8s-wc-reader on a folder (cascades to everything below)
+bt pf policies grant --name k8s-wc-reader-demo-viewer --workload-name k8s-wc-reader \
+    --folder /btlab/app/demo --role-grant Viewer
+# ReadSecret on one secret
+bt pf policies grant --name k8s-db-pass --workload <id> --secret /btlab/app/demo/db-pass \
+    --action ReadSecret --action ReadSecretMetadata
+# Revoke
+bt pf policies delete k8s-db-pass
+```
+
+Gotchas (live-verified 2026-10-20/21):
+- The **docs' path `/platform/iam/policies` is wrong** — it is
+  `/site/{admin-site}/platform/iam/policies`.
+- The list **includes soft-deleted** policies — history, never grants.
+- **PUT is an upsert keyed by name** (unique per org). Reusing a name silently
+  replaces it; `grant`/`apply` say REPLACE and show the current Cedar. A
+  DELETED name is reusable.
+- **A wrong workload id still goes ACTIVE** (the service doesn't validate
+  principals) and grants nothing — `grant` warns.
+- **A missing path → WAITING_FOR_RESOURCE**, which binds when it's created.
+- Statuses: `RESOURCE_LOOKUP`, `PENDING_BIND` (settling) → `ACTIVE`;
+  `WAITING_FOR_RESOURCE`; `RESOURCE_LOOKUP_ERROR`, `NO_PRODUCT_ACCESS`
+  (failed); `PENDING_UNBIND` → `DELETED`.
+- Names: 1-100 chars, letters/digits/`-`/`_`, alnum at both ends (the
+  provider's server-mirrored rule — no dots).
+- A non-admin-site PAT on the policy API → `403 forbidden: caller cannot
+  perform this action`.
+
+## Groups and roles — known gap
+
+Policies can name `Pathfinder::Group::"name"` and `Pathfinder::Role::"name"`,
+but **group and role membership is not visible to PAT callers, so access
+through groups can't be resolved.** There is no groups/roles API in the Nomine
+swagger or the Terraform provider, and read-only probes on the Administration
+site (2026-10-21) found none: `platform/auth/{groups,Groups,roles,Roles,UserGroups}`
+and `platform/iam/{groups,Groups,roles}` → 404; `platform/auth/User/Groups` →
+405 (a route exists but not for GET; not probed further). The only membership
+data a PAT sees is the caller's own `groups` in `bt pf whoami`. `bt wlc access`
+reports group/role grants as "membership not resolved", and always notes that
+Admin-console role assignments can make effective access larger than policies show.
+
+## What works over PAT vs what doesn't (re-verified 2026-10-21)
+
+| Endpoint | Product-site PAT | Administration-site PAT (`admin` scope) |
+|----------|------------------|------------------------------------------|
+| `auth/UserInfo`, `auth/User/Access`, `auth/User/Token`, `auth/User/McpToken` | 200 | 200 |
+| `auth/Users`, `auth/SAMLProviders`, `auth/Auditing` | 403 (empty body) | **200** |
+| `auth/productaccess/org`, `auth/access/org`, `auth/siteaccess/org` | 403 (empty body) | **200** |
+| `auth/workload-identities`, `iam/policies` | 403 | **200** |
+| `auth/Machine`, `auth/Machine/{id}` | **200** | 403 |
+| `auth/productaccess` (collection GET) | 404 (not deployed) | n/a |
+| `auth/Users/delete` | 405 on GET; POST → 403 (2026-06-11) | **POST works** (deleted a test user, 2026-10-21) |
+| `auth/UserInvitation` | 405 on GET; POST → 403 (2026-06-11) | **POST works**: invited a user to a product site with products, 2026-10-21 |
+| `auth/UserInvitation/Cancel` | 405 on GET | **POST works** (2026-10-21); a second cancel → `404 "User invitation not found."` |
+| `auth/UserInvitation/Product` | 405 on GET | 405 on GET; POST not yet tested |
+| `auth/siteaccess/{s}/user/{u}` | 405 on GET | **POST and DELETE work** (2026-10-21) |
+| `auth/productaccess/{p}/site/{s}/user/{u}` | 405 on GET; grant POST → empty-body 403 (2026-06-11) | **POST and DELETE work** (2026-10-21) |
+| `auth/productaccess?userId=` (read a user's product rules, in the swagger) | 404 | 404: not deployed, so a user's product grants can't be read back |
+
+PAT `access` scopes are listed in `bt pf pats list`. The Administration-site PAT
+in use on 2026-10-21 carried `admin` plus every product slug. Note that machines
+work the other way round: they need a product-site PAT.
+
+## Machines
+
+Platform machine identities: non-user principals (machineId + machineSecret)
+used by agents/integrations to authenticate. `POST
+login.beyondtrust.io/bt.identity/Machine/AccessToken {machineId,
+machineSecret}` → 30-min JWT (machineEndpoints.* scopes only). Records carry
+an activation-token lifecycle (created/expiration) and `active` flag —
+an entry with `active: false` and a pending activation token was registered
+but never activated.
+
+## Not exposed via PAT (cookie-auth only, app.beyondtrust.io/api/auth/*)
+
+User listing, auditing, SAML providers and the org-default access-rule reads
+now work over an Administration-site PAT with the `admin` scope (see above).
+Still cookie-only as far as tested: PAT/MCP token creation and revocation, and
+invitation Accept. These need the `access` session cookie
+(browser JWT ~5min TTL, or the programmatic SignIn → /session/login flow —
+password-auth users only, not federated).
+
+Invite body shape (spec `InviteOrganizationUserInput`): `{email, firstName,
+lastName, siteMetaData: [{siteId, name, residency}], productMetaData:
+[{name, siteId, siteName}]}` — `bt pf users invite` builds this, defaulting
+the site to `BT_PF_SITE_ID` and omitting name/residency unless given.

bt_cli-0.6.0/.claude/skills/secrets/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: secrets
+description: Old name for Workload Credentials (WLC). `bt secrets` is a deprecated alias of `bt wlc` — use the /wlc skill.
+---
+
+# Secrets API → Workload Credentials (`bt wlc`)
+
+BeyondTrust renamed the Secrets API (Secrets Safe) to **Workload Credentials
+(WLC)**. In bt-cli 0.6.0 the commands moved to **`bt wlc`**; `bt secrets` is a
+deprecated alias with the same commands (it prints a one-line notice on
+stderr, so `-o json` output is unchanged).
+
+- Commands: `bt wlc folders|static|dynamic|leases|integrations|auth|tree|access`
+- Config: `BT_WLC_*` (falls back to `BT_SECRETS_*`), `wlc` profile section (falls back to `secrets`)
+- URL prefix: `/site/{id}/wlc` (`/site/{id}/secrets` still answers)
+- Access policies & workload identities: `bt pf policies`, `bt pf wi`
+
+**Use the `/wlc` skill** — it has everything that used to be here, plus the
+Cedar policy and effective-access material.