WinRM (Windows Remote Management) Connector can be used to execute commands on remote Windows server machine using Microsoft implementation of WS-Management Protocol.

Features

  • Based on standardized Microsoft implementation of WS-Management protocol
  • Password based authentication mechanism
  • Both HTTP and HTTPS protocol support
  • Direct access to the command execution results from the remote server
  • The ability to set connector execution timeouts
  • Synchronous/Asynchronous execution of the connector
  • Both command line and powershell command execution ability.

Connector Configuration

 

Configuration parameters

ParameterDescriptionRequired
targetHost name or ip-address of the host server machine to connecttrue: config/request
usernameConnect with specified username, host server machine authenticationtrue: config/request
passwordConnect with specified password, host server machine authenticationtrue: config/request
shell

Shell execution is of two types - powershell(ps) and command linr(cmd)

ps: Commands will be executed on powershell command line

cmd: initiates a traditional cmd.exe shell via the WinRM protocol.Commands will be executed on Windows command line

true: config/request
commandCommand to be executed on the host server machinetrue: config/request
portPort to connect to the host server machine. Default port is 5985 for HTTP and 5986 for HTTPStrue: config/request
transport

The transport used governs the authentication method used and the encryption level used for the underlying HTTP communication with the target

true: config/request
operation_timeoutThe maximum amount of time to wait for a response from the endpoint. This defaults to 60 seconds. false: request
Note : Default HTTP Port: 5985 
           Default HTTPS Port: 5986
Example
{
  "target": "192.156.2.3",
  "username": "Administrator",
  "password": "example123",
  "transport": "plaintext/negotiate/ssl",
  "command": "hostname",
  "port": 5985,
  "shell":"cmd/ps",
  "operation_timeout":80
}
 

Actions

cmd:

Execute commands on Remote Windows command line.

ParameterDescriptionRequired
targetHost name or ip-address of the host server machine to connecttrue: config/request
usernameConnect with specified username, host server machine authenticationtrue: config/request
passwordConnect with specified password, host server machine authenticationtrue: config/request
shell

Shell execution is of two types - powershell(ps) and command linr(cmd)

ps: Commands will be executed on powershell command line

cmd: initiates a traditional cmd.exe shell via the WinRM protocol.Commands will be executed on Windows command line

true: config/request
commandCommand to be executed on the host server machinetrue: config/request
portPort to connect to the host server machine. Default port is 5985 for HTTP and 5986 for HTTPStrue: config/request
transport

The transport used governs the authentication method used and the encryption level used for the underlying HTTP communication with the target

true: config/request
operation timeoutExecution time for the command in milliseconds. Default timeout is 60000 millisecondsfalse: request

 

Example
connector_response=@call.connector("my-winrm-connector")
                        .set("target","192.156.2.3")
                        .set("username","Administrator")
                        .set("password","example123")
                        .set("transport","negotiate")
                        .set("command","dir")
                        .set("port", 5985)
                        .set("shell", "cmd")
                        .set("operation_timeout",80)
                        .set("timeout",60000)
                        .sync

#WinRM Connector Response Parameters
 
response_exitcode = connector_response.exitcode       # Exit status code
response_message = connector_response.message         # Execution status messages
response_body = connector_response.get('result')      # Response Body

 

ps: 

Execute commands on Remote Windows Powershell command line

ParameterDescriptionRequired
targetHost name or ip-address of the host server machine to connecttrue: config/request
usernameConnect with specified username, host server machine authenticationtrue: config/request
passwordConnect with specified password, host server machine authenticationtrue: config/request
shell

Shell execution is of two types - powershell(ps) and command linr(cmd)

ps: Commands will be executed on powershell command line

cmd: initiates a traditional cmd.exe shell via the WinRM protocol.Commands will be executed on Windows command line

true: config/request
commandCommand to be executed on the host server machinetrue: config/request
portPort to connect to the host server machine. Default port is 5985 for HTTP and 5986 for HTTPStrue: config/request
transport

The transport used governs the authentication method used and the encryption level used for the underlying HTTP communication with the target

true: config/request
timeoutExecution time for the command in milliseconds. Default timeout is 60000 millisecondsfalse: request
Example
connector_response=@call.connector("my-winrm-connector")
                        .set("target","192.156.2.3")
                        .set("username","Administrator")
                        .set("password","example123")
                        .set("transport","ssl")
                        .set("command","Get-ADuser 'john123'")
                        .set("shell", "ps")
                        .set("operation_timeout",80)
                        .set("no_ssl_peer_verification": true)
                        .set("timeout",60000)
                        .sync

#WinRM Connector Response Parameters

response_exitcode = connector_response.exitcode       # Exit status code
response_message = connector_response.message         # Execution status messages
response_body = connector_response.get('result')      # Response Body

Connector request error handling

This is how success or failures can be handled for the connector requests within your Flintbit. This would help to take appropriate action if something failed.

if response_exitcode == 0


@log.info("Success in executing WinRM Connector, where exitcode :: #{response_exitcode} | message :: #{response_message}")
# take action in case of success

 
else                                    

@log.error("Failure in executing WinRM Connector where, exitcode :: #{response_exitcode} | message :: #{response_message}")
@output.set('error', response_message)
## take action in case of failure

end
  • No labels