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: .rtd
      Support 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.
Generates random password (and keys, depending on account configuration):
psrun2 $(cat conn) ForceReset SystemName AccountName
Updates password on system and in BeyondInsight:
psrun2 $(cat conn) ForceReset SystemName AccountName Password
Updates password in BeyondInsight but does not try to change password on system:
psrun2 $(cat conn) ForceReset SystemName AccountName Password 0
Updates password and keys on system and in BeyondInsight:
psrun2 $(cat conn) ForceReset SystemName AccountName Password 1 "publicFile" "privateFile"