ExecuteCommand (V7.4 and later)

Description

An alternate method for connecting to a remote host using SSH, if an interactive shell session is not required.

This method runs a remote command (the equivalent of using an ssh client to execute: ssh -l user host command
Typically, the command is executed by the remote SSHD server using the service account's configured login environment, but the exact behaviour will depend on the remote SSHD server. No assumptions are made as to the expected behaviour of the command being executed on the remote asset.
It is up to the script writer to check the expected exitStatus, stdout and stderr reported by the remote asset. Note that some commands write successful output to stderr rather than stdout, e.g. the passwd command on Linux.

The SSHD server does not allocate a pseudo-terminal in this context, so this component can only be used to execute a command that does not prompt for user input during execution. However, input data can be passed in to the remote command in the Stdin property, in which case it is made available to the remote command as soon as it starts to execute.

To use this component, you must first create a Connect component with RequestTerminal = false. Note: Send and Receive cannot be used on this connection. If the command runs to completion on the remote host, then the exitStatus, stdout and stderr will be made available in the buffers configured.

An exception is thrown in the following circumstances

• the SSH connection is terminated for any reason
• an error thrown by the remote Sshd server (the exitstatus and output are not available in this case, as the command may not have completed)
• a timeout occurs before the command completes.

Note: This method is only supported for SSH connections.

Compatibility

This version of the command was introduced in Safeguard v7.4

Parameters

Parameter Name	Description	Type	Resolved Type	Required
ConnectionObjectName	The name of a connection object variable that has been created using the Connect component with RequestTerminal=false	String	String	Yes
Timeout	Optional Timeout. If not specified, the connection timeout will be used	Value	Integer	No
Command	The full path of the command to run, and any command line arguments to use. This can be a hardcoded string, or can contain expressions or variables that will be resolved, e.g. _ /bin/grep %AccountUserName% /etc/shadow_	Value	String	Yes
Stdin	An optional list of string arguments to write to stdin when the command executes. Each element in the list can be a hardcoded string, or can contain expressions or variables. Each item in the list will be written to stdin, followed by a newline.	Value	String Array	No
ExitStatusBufferName	The name of a buffer that will contain the exit status (integer value) produced by the command	Value	integer	No
BufferName	The name of the variable to contain the output produced by the command	Value	String	Yes
StderrBufferName	The name of the variable to contain the output produced by the command	Value	String	Yes
CommandContainsSecret	If true, the command contains sensitive information and should not be logged in the comms log	Value	Boolean	No
InputContainsSecret	If true, the stdin contains sensitive information and should not be logged in the comms log	Value	Boolean	No
OutputContainsSecret	If true, the output from the command may contain sensitive information and should not be logged in the commas log	Value	Boolean	No
SuppressExceptions	If true, do not throw an exception if the executing command returns stderr data	Value	Boolean	No (default false)

Examples

Example
Connect to the remote host, and run the passwd command to change the password for an account. In this case sudo requires a password for the service account, so the script must allow for this; it runs sudo with the -S argument, and passes the service account password as the first stdin argument.

{
    "Try": {
        "Do": [
            {   
                “Connect” : {
                   “ConnectionObjectName” : ”Global:ConnectSsh”,
                   “Address” : ”%Address%”,
                   “Port” : ”%Port%”,
                   “Login” : ”%FuncUserName%”,
                   “Password” : ”%FuncPassword%”,
                   “RequestTerminal” : false,
                   "Timeout": "%Timeout%",
                }
            },

            {       
                "ExecuteCommand": {    
                    "ConnectionObjectName": "Global:ConnectSsh",
                    "Command" : "%DelegationPrefix::$% -S /usr/bin/passwd %{ AccountUserName }%",
                    "Stdin" : [ “%{ FuncPassword }%”, "%{ NewPassword }%", "%{ NewPassword }%" ],
                    "BufferName" : "OutputBuffer",
                    "StderrBufferName" : "ErrBuf",
                    "ExitStatusBufferName" : "rc",
                    "CommandContainsSecret" : false,
                    “OutputContainsSecret" : false,
                   "InputContainsSecret" : true
                }
            },
            {
               “Condition” : {
                  “If”      : “ rc == 0 “,  “Then”  : {  …..success…  },
                  “Else” : {   ….failure … }
              }
            }
        ],
        "Catch": [
                { "Throw": { "Value": "Failed to run command : %Exception%" } }
           ]
      }
 }