Protocols and methods
The protocol identifies the service that the user accesses. The method identifies the access operation. Each method has matching and behavior.
The command structure is:
bsh checkout <protocol> --method <method>
bsh checkin <protocol> --method <method>bsh probe lists the combinations available in the installed version. The tables below describe version 0.2.0. Transport settings apply in addition to the method settings.
Unix accounts and SSH keys
These methods support local and ssh transports. Remote administration requires BSH_TRANSPORT=ssh.
| Protocol | Method | Checkout | Default checkin |
|---|---|---|---|
ssh | ephemeral-key | Create the account if needed and install a generated SSH public key. Return its private key. | Remove bsh-managed keys for the user email and remove the sudo grant. Retain the account and home directory. |
ssh | existing-user-key | Install a generated SSH public key for an existing account. Return its private key. | Remove bsh-managed keys for the user email. Retain the account. |
ssh, telnet, netconf | ephemeral-password | Create an account with a generated password. | Lock the account and remove its sudo grant. |
SSH key cleanup matches the user email on the target account. If the same identity has overlapping checkouts on that account, checking in one removes keys from the others. Removing a key blocks new logins but does not close an existing direct SSH session.
| Variable | Applies to | Meaning |
|---|---|---|
BSH_HOME_ROOT | Unix methods | Parent of target home directories. Default home, producing /home/<username>. |
BSH_SSH_KEY_TYPE | Key methods | ed25519, the default, or rsa. |
BSH_SSH_RSA_BITS | Key methods | RSA key size. Default 4096, minimum 2048. |
BSH_SUDO | ephemeral-key, ephemeral-password | Grant passwordless sudo to the target account. Default false. |
BSH_SHELL | ephemeral-key, ephemeral-password | Login shell for a newly created account. |
BSH_GROUPS | ephemeral-password | Supplementary groups. |
BSH_PASSWORD_LENGTH | ephemeral-password | Generated password length. Default 32, minimum 16. |
BSH_DELETE_USER | ephemeral-key, ephemeral-password | Delete the account at checkin. Default false. |
BSH_REMOVE_HOME | ephemeral-key, ephemeral-password | Remove the home directory when BSH_DELETE_USER=true. Default false. |
The bsh Telnet and NETCONF password methods manage Unix accounts. They do not configure vendor network-device accounts. bsh does not support RESTCONF.
Windows local accounts
rdp ephemeral-user and winrm ephemeral-user use the WinRM transport. They create a local account with a generated password and add it to Remote Desktop Users or Remote Management Users, respectively.
Checkin disables the account by default. BSH_DELETE_USER=true deletes it. BSH_GROUPS adds further local groups. BSH_FULL_NAME sets the account’s display name. BSH_PASSWORD_LENGTH defaults to 32 and has a minimum of 16.
BSH_ACCOUNT_TTL sets account expiry. When absent, BSH_SESSION_DURATION supplies the expiry duration, with an eight-hour fallback for these methods. Target usernames default to a maximum of 20 characters.
Active Directory and LDAP
The following methods are available for ssh, rdp, and winrm protocols:
| Method | Transport | Required method settings | Checkin |
|---|---|---|---|
ad-group | winrm | BSH_GROUPS | Remove the specified group memberships. |
ad-enable-account | winrm | User identity | Disable the account. |
ad-rotate-password | winrm | BSH_SHARED_ACCOUNT | Rotate the shared account password again. |
directory-group | directory | BSH_GROUPS, directory search settings | Remove the specified group memberships. |
directory-rotate-password | directory | BSH_SHARED_ACCOUNT, directory search settings | Rotate the shared account password again. |
The ad-* methods run the ActiveDirectory PowerShell module on a domain-joined host. BSH_AD_SERVER selects a domain controller. BSH_AD_USER_ATTR selects lookup by userPrincipalName, the default, mail, or sAMAccountName. BSH_AD_UNLOCK defaults to true for ad-enable-account.
Directory methods require BSH_DIRECTORY_BASE_DN. BSH_DIRECTORY_USER_ATTR defaults to mail. BSH_DIRECTORY_GROUP_ATTR accepts member, the default, uniqueMember, or memberUid. Group DNs containing commas use semicolon-separated lists.
Group and account-enable methods return access details without generating a password. Password rotation requires an existing shared account and changes its password again at checkin. A rotation can invalidate credentials from another active checkout of the same account.
ssh ldap-passthrough changes no target credentials. In Bridge mode, Bridge forwards the user’s directory password. BSH_LDAP_AUTH_PASSTHROUGH remains enabled for both operations. When a shell transport is available, the method verifies that the account exists.
SQL databases
The protocols mysql, postgres, cockroachdb, mssql, and oracle use the database transport and support these methods:
| Method | Checkout | Checkin |
|---|---|---|
temp-user | Create a login with a generated password and apply the requested roles or grants. | Drop the login by default. |
role-grant | Grant roles or privileges to an existing account. Issue no password. | Remove the requested roles or privileges. |
rotate-password | Change an existing shared account’s password and return the new password. | Rotate the password again. |
BSH_ROLES names existing database roles. BSH_GRANTS specifies privileges such as SELECT, INSERT, or UPDATE, subject to the engine’s supported grant scope. role-grant requires at least one role or grant. BSH_TARGET_DATABASE supplies the database scope. Oracle uses BSH_ORACLE_SCHEMA for schema privileges.
BSH_DROP_USER defaults to true for temp-user. The role-grant and rotation methods reject account-deletion settings. rotate-password requires BSH_SHARED_ACCOUNT and does not grant roles or privileges.
BSH_PASSWORD_LENGTH defaults to 32, or 30 for Oracle. PostgreSQL and CockroachDB use BSH_SESSION_DURATION for login expiry, with a one-hour default. Other SQL engines still depend on checkin to revoke access.
NoSQL databases
redis, mongodb, and cassandra use the datastore transport. temp-user creates a principal and returns a generated password. Checkin deletes the principal by default, controlled by BSH_DROP_USER.
For temp-user, BSH_GRANTS has a store-specific format:
| Protocol | Grant format |
|---|---|
redis | Redis ACL rules. Required. |
mongodb | A role in the authentication database or role@database. Required. |
cassandra | An existing role or PERMISSION:keyspace. |
rotate-password requires BSH_SHARED_ACCOUNT. It returns a new password at checkout and rotates the password again at checkin. BSH_PASSWORD_LENGTH defaults to 32 for both methods.
VNC password rotation
vnc rotate-password uses a local or SSH transport to replace the VNC server password file. It rotates the password again at checkin.
BSH_VNC_USER is required and names the operating-system account that owns the password file. BSH_VNC_PASSWD_PATH defaults to /<home_root>/<vnc_user>/.vnc/passwd. The password has eight characters because of the VNC authentication format. The password belongs to the VNC server, so rotating it affects other connections that use the same password file.
Kubernetes tokens
k8s serviceaccount-token uses the Kubernetes transport. It creates a ServiceAccount, adds a role binding, and requests a token.
| Variable | Meaning |
|---|---|
BSH_KUBE_NAMESPACE | Namespace for the ServiceAccount. Defaults to the in-cluster namespace, or default. |
BSH_KUBE_ROLE | Existing Role in that namespace. Exactly one of this and BSH_KUBE_CLUSTER_ROLE is required. |
BSH_KUBE_CLUSTER_ROLE | Existing ClusterRole. |
BSH_KUBE_CLUSTER_ROLE_SCOPE | cluster, the default, creates a ClusterRoleBinding. namespace creates a RoleBinding in the selected namespace. |
BSH_KUBE_AUDIENCES | Token audiences. Defaults to the API server’s default audience. |
BSH_SESSION_DURATION | Requested token lifetime. Default 1h, minimum 10m, maximum 24h. The API server can shorten it. |
BSH_DELETE_SERVICEACCOUNT | Delete the ServiceAccount at checkin. Default true. |
Bridge Kubernetes exec additionally requires BSH_KUBE_POD. Namespace, container, command, and terminal controls are listed in the Bridge settings.
HTTP capture and Bridge role sessions
These methods do not provision accounts on a target.
| Protocol and method | Purpose | Required settings |
|---|---|---|
http capture-scope | Define the destinations allowed through a Bridge HTTP proxy session. | At least one of BSH_CAPTURE_HOSTS or BSH_CAPTURE_SUBDOMAINS. Values are bare hosts or domains. |
bridge admin-session | Open a Bridge administration session. | Bridge connection and identity settings. Audit scope parameters are rejected. |
bridge auditor-session | Open a Bridge audit session with restricted scope. | Bridge connection and identity settings, plus at least one audit scope list. |
In Bridge mode, HTTP checkin ends the registered checkout. There is no target
account to remove. The bridge protocol selects Bridge mode automatically.
bsh 0.2.0 reads BSH_TARGET_BEARER_TOKEN and sends it as target_password,
but omits target_host and target_port from the HTTP checkout. Bridge 3.0.2
requires both fields for bearer injection. Use the
API-based kubectl example for that case.
Auditor scope lists are BSH_AUDIT_USERS, BSH_AUDIT_PROTOCOLS, BSH_AUDIT_TARGETS, BSH_AUDIT_TARGET_USERNAMES, BSH_AUDIT_TRANSACTION_IDS, BSH_AUDIT_SESSION_IDS, and BSH_AUDIT_ARTIFACTS. A list narrows only its own dimension. An unset dimension is sent as *.
BSH_AUDIT_LIVE_VIEW permits live viewing and defaults to false. BSH_AUDIT_CONTROLS accepts lock, unlock, disconnect, or *. Any control also enables live viewing.