Short Commands
Short Commands simplify API workflows by reducing command-line input and chaining successive calls in a single command, instead of calling each endpoint directly.
Short command parameters are ordered, not named; they do not need to be prefixed with the parameter name and need only be in the correct order. For example, the syntax for the command RetrievePassword is:
psrun2 -i $host $key $user RetrievePassword $MANAGEDSYSTEM $MANAGEDACCOUNT $REASON
RetrievePassword (alias: RetrievePasswordByName)
APIs: GET ManagedAccounts, POST Requests, GET Credentials, PUT Requests/{id}/Checkin
Or: POST ISARequests (for ISA-based access)
Finds an account by name (if necessary), creates a request, then retrieves a password. After printing the password, the request is released (see DoNotRelease parameter).
Parameters
- SystemName: The managed system name. Use DatabaseName\InstanceName for databases.
- AccountName: The managed account name. Can use IDs instead of names (but do not mix both).
- Reason: The reason to retrieve a password.
- DurationMinutes (optional): The request duration (in minutes). Default request duration is 10 minutes.
- Type (optional, default: password): The type of credentials to retrieve (password, dsskey).
- DoNotRelease (optional): Do not release created request. Allowed values are DoNotRelease or -p.
psrun2 $(cat conn) RetrievePassword SystemName AccountName "your reason"
psrun2 $(cat conn) RetrievePassword 1 2 "your reason"
psrun2 $(cat conn) RetrievePassword 1 2 "your reason" 25 password DoNotRelease
psrun2 $(cat conn) RetrievePassword 1 2 "your reason" 25 -p
RetrievePassword is affected by the number of approvers. This command works only with Auto Approve enabled in the Access Policy.
ListAssets
API: GET Workgroups/{workgroupID}/Assets or Workgroups/{workgroupName}/Assets
Parameters
- Workgroup: ID or name of the workgroup.
- Limit (optional): Number of records to return.
- Offset (optional): Number of records to skip before returning <limit> records (works only with limit).
psrun2 $(cat conn) ListAssets 1
psrun2 $(cat conn) ListAssets PasswordSafe
psrun2 $(cat conn) ListAssetts PasswordSafe 2 2
ListWorkgroups
API: GET Workgroups
psrun2 $(cat conn) ListWorkgroups
ListSystems
API: GET ManagedSystems or GET ManagedSystems/{id}
Parameters
- id (optional): ID of the managed system.
psrun2 $(cat conn) ListSystems
psrun2 $(cat conn) ListSystems 123
ListAccounts
API: GET ManagedAccounts?systemName={system}&accountName={account}&workgroupName={workgroup}
Parameters
- SystemName (optional): Managed system name (must be used with AccountName).
- AccountName (optional): Managed account name (must be used with SystemName).
- WorkgroupName (optional): Workgroup name.
- Type (optional): Type of managed accounts to return.
- System: Returns local accounts.
- Domainlinked: Returns domain accounts linked to systems.
- Database: Returns database accounts.
- Cloud: Returns cloud system accounts.
- Application: Returns application accounts.
psrun2 -separator "," -filter "SystemId,SystemName,AccountId,AccountName" $(cat conn) ListAccounts TestSystemName TestAccountName "BeyondTrust Workgroup"
psrun2 $(cat conn) ListAccounts
psrun2 $(cat conn) ListAccounts database
ListAliases
API: GET Aliases or GET Aliases/{name}
Parameters
Name: Name of the managed account alias.
psrun2 $(cat conn) ListAliases
psrun2 $(cat conn) ListAliases AliasName
ListGroups
API: GET UserGroups or GET <base>/UserGroups/{id} or GET <base>/UserGroups/{name}
Parameters
Group (optional): ID or name of the user group.
psrun2 $(cat conn) ListGroups
psrun2 $(cat conn) ListGroups 1
psrun2 $(cat conn) ListGroups Administrators
ListGroupMembership
API: GET UserGroups/{userGroupId}/Users
Parameters
UserGroupId: User group ID.
psrun2 $(cat conn) ListGroupMembership 1
ListRequest
API: GET Requests
Parameters
- Status (optional, default: all): The status of requests to return (all, active, pending).
- Queue (optional, default: req): The type of request queue to return (req, app).
psrun2 $(cat conn) ListRequests active
psrun2 $(cat conn) ListRequests all req
ListRoles
API: GET Roles
psrun2 $(cat conn) ListRoles
ListSmartRules
API: GET SmartRules
Parameters
- Type (optional, default: all): The type of Smart Rules to return (all, ManagedAccount, Asset, Vulnerabilities)
psrun2 $(cat conn) ListSmartRules
psrun2 $(cat conn) ListSmartRules Asset
Request
API: POST Requests
Parameters
- AccessType (optional, default: View): The type of access requested (View, RDP, SSH).
- SystemId: ID of the managed system to request.
- AccountId: ID of the managed account to request.
- DurationMinutes: The request duration (in minutes).
- Reason (optional): The reason for the request.
- AccessPolicyScheduleID (optional): The schedule ID of an access policy to use for the request. If omitted, automatically selects the best schedule.
- ConflictOption (optional, default: renew): The conflict resolution option to use if an existing request is found for the same user, system, and account (reuse, renew). If omitted and a conflicting request is found, returns a 409 error.
- Reuse: Return an existing, approved request ID for the same user/system/account/access type (if one exists). If the request does not already exist, create a new request using the request body details.
- Renew: Cancel any existing approved requests for the same user/ system/account and create a new request using the request body details.
psrun2 $(cat conn) Request 1 1 120 "Request reason"
ISARequests
API: POST ISARequests
Parameters
- Type (optional, default: password): the type of credentials to retrieve (password, dsskey).
- SystemID (required): ID of the managed system to request.
- AccountID (required): ID of the managed account to request.
- DurationMinutes (optional): The request duration (in minutes).
- Reason (optional): The reason for the request.
psrun2 $(cat conn) ISARequests 1 1 15 "Reason"
psrun2 $(cat conn) ISARequests 1 1
Retrieve
API: GET Credentials/{requestId}
Parameters
- RequestId: ID of the request.
- Type (optional, default value: password): the type of credentials to retrieve (password, dsskey).
psrun2 $(cat conn) Retrieve 12 dsskey
Release
API: PUT Requests/{requestId}/Checkin
Parameters
- ID: ID of the request to release.
- Reason (optional): A reason or comment why the request is being released.
psrun2 $(cat conn) Release 123 "reason for release"
ImportFile
API: POST Imports (Base64FileContents option)
Parameters
- WorkgroupName: Name of the workgroup
- ImportType (case-sensitive, default: PASSWORDSAFE) Type of import being queued:
- PASSWORDSAFE: Password Safe import file. Expected file extension: .xml
- RETINARTD: Retina© RTD import file. Expected file extension: .rtdSupport for the following file types has been deprecated and will be removed from the product in a future version.
- NESSUS: Nessus© import file. Expected file extension: .csv
- NESSUSSECCEN: NessusSecurityCenter© import file. Expected file extension: .csv
- NEXPOSE: Nexpose© import file. Expected file extension: .csv or .xml
- QUALYSGUARD: QualysGuard© import file. Expected file extension: .csv or .xml
- METASPLOIT: METASPLOIT© import file. Expected file extension: .xml
- TRIPWIRE: Tripwire© import file. Expected file extension: .csv
- MCAFEEVM: McAfee Vulnerability Management© import file. Expected file extension: .csv
- FileName: Name of the file to be imported
- Filter (optional, case-sensitive, default: All Assets): Asset selection filter
- All Assets: No filter, import all
- Single IPv4 address (example, 10.0.0.1)
- IPv4 range (example, 10.0.0.1 - 10.0.0.5)
- CIDR (example, 10.0.0.0 / 24)
psrun2 $(cat conn) ImportFile "PasswordSafe" PASSWORDSAFE data.xml
ForceReset
API: GET ManagedAccounts?systemName={system}&accountName={account}, PUT ManagedAccounts/{accountId}/Credentials
ForceReset updates a managed account password, public and private key. This command can also be used without parameters, with a password parameter (optionally with UpdateSystem), or with all parameters.
Parameters
- SystemName: Managed system name.
- AccountName: Managed account name.
- Password: New password, use empty quotes to auto-generate a value.
- UpdateSystem (optional, default 1): Whether to update the credentials on the referenced system.
- PublicKey: The new public key to set on the host (could be a value or a name of the file).
- PrivateKey: The private key to set (provide passphrase if encrypted, could be a value or a name of the file).
- Passphrase (optional): The passphrase to use for an encrypted private key.
psrun2 $(cat conn) ForceReset SystemName AccountName
psrun2 $(cat conn) ForceReset SystemName AccountName Password
psrun2 $(cat conn) ForceReset SystemName AccountName Password 0
psrun2 $(cat conn) ForceReset SystemName AccountName Password 1 "publicFile" "privateFile"