winrm

func (*ArkWinRMConnection) Connect ¶

func (c *ArkWinRMConnection) Connect(connectionDetails *connectionsmodels.ArkConnectionDetails) error

Connect establishes a WinRM connection using the provided connection details.

Establishes a secure WinRM HTTPS connection to the target Windows machine using the provided connection details. The method handles certificate validation, retry logic, and creates both the WinRM client and shell required for command execution.

If the connection is already established, this method returns immediately without error. The method uses the default HTTPS port (5986) if no port is specified in the connection details.

Parameters:

• connectionDetails: Connection configuration including address, port, credentials, retry settings, and optional certificate settings

Returns an error if the connection cannot be established, including cases where credentials are missing, certificate files cannot be read, or the WinRM client/shell creation fails.

The method supports automatic retry with configurable retry count and tick period. Connection failures are detected and retried up to the specified limit.

Example:

details := &connectionsmodels.ArkConnectionDetails{
	Address: "windows-server.example.com",
	Port:    5986,
	Credentials: &connectionsmodels.ArkConnectionCredentials{
		User:     "administrator",
		Password: "password",
	},
	ConnectionRetries: 3,
	RetryTickPeriod:   5,
}
err := conn.Connect(details)
if err != nil {
	// handle connection error
}

func (*ArkWinRMConnection) Disconnect ¶

func (c *ArkWinRMConnection) Disconnect() error

Disconnect closes the WinRM connection.

Closes the active WinRM shell and cleans up the connection resources. If the connection is not currently established, this method returns immediately without error.

The method attempts to close the WinRM shell gracefully. If the shell closure fails, a warning is logged but the method continues to clean up the connection state.

After successful completion, the connection state is reset to disconnected and not suspended.

Returns an error only in exceptional circumstances. Shell closure errors are logged as warnings but do not cause the method to fail.

Example:

err := conn.Disconnect()
if err != nil {
	// handle disconnect error (rare)
}

func (*ArkWinRMConnection) IsConnected ¶

func (c *ArkWinRMConnection) IsConnected() bool

IsConnected checks if the WinRM connection is established.

Returns the current connection state indicating whether a WinRM connection has been successfully established and is ready for use. This does not check the network connectivity, only the internal connection state.

Returns true if the connection is established, false otherwise.

Example:

if !conn.IsConnected() {
	err := conn.Connect(connectionDetails)
	if err != nil {
		// handle connection error
	}
}

func (*ArkWinRMConnection) IsSuspended ¶

func (c *ArkWinRMConnection) IsSuspended() bool

IsSuspended checks if the WinRM connection is suspended.

Returns the current suspension state of the connection. When suspended, the connection will refuse to execute commands even if the underlying WinRM connection is still active.

Returns true if the connection is currently suspended, false otherwise.

Example:

if conn.IsSuspended() {
	// Connection is suspended, restore before running commands
	conn.RestoreConnection()
}

func (*ArkWinRMConnection) RestoreConnection ¶

func (c *ArkWinRMConnection) RestoreConnection() error

RestoreConnection restores the WinRM connection.

Restores a previously suspended connection, allowing command execution to resume. This method clears the suspended state without affecting the underlying WinRM connection.

Returns nil as this operation always succeeds.

Example:

err := conn.RestoreConnection()
// Commands can now be executed again

func (*ArkWinRMConnection) RunCommand ¶

func (c *ArkWinRMConnection) RunCommand(command *connectionsmodels.ArkConnectionCommand) (*connectionsmodels.ArkConnectionResult, error)

RunCommand executes a command on the remote machine using WinRM.

Executes the specified command on the remote Windows machine through the established WinRM connection. The method handles both small and large commands automatically, using different execution strategies based on command size.

For commands smaller than maxSingleCommandSize (2000 bytes), the command is executed directly using PowerShell's encoded command feature with UTF-16 encoding. For larger commands, the method splits the command into chunks, writes them to a temporary PowerShell script file on the remote machine, executes the file, and cleans up afterward.

The method can be forced to use the file-based approach for any command by setting ExtraCommandData["force_command_split"] to true.

Parameters:

• command: The command configuration including the command string, expected return code, and optional extra data for execution control

Returns the command execution result containing stdout, stderr, and return code, or an error if the command cannot be executed or returns an unexpected return code.

The method validates that the connection is active and not suspended before execution. Commands that return a different exit code than expected will result in an error.

Example:

cmd := &connectionsmodels.ArkConnectionCommand{
	Command:    "Get-Process | Where-Object {$_.ProcessName -eq 'notepad'}",
	ExpectedRC: 0,
}
result, err := conn.RunCommand(cmd)
if err != nil {
	// handle execution error
}
fmt.Printf("Output: %s\n", result.Stdout)

For large commands:

cmd := &connectionsmodels.ArkConnectionCommand{
	Command:    veryLargeScript,
	ExpectedRC: 0,
	ExtraCommandData: map[string]interface{}{
		"force_command_split": true,
	},
}
result, err := conn.RunCommand(cmd)

func (*ArkWinRMConnection) SuspendConnection ¶

func (c *ArkWinRMConnection) SuspendConnection() error

SuspendConnection suspends the WinRM connection.

Marks the connection as suspended without actually closing the underlying WinRM connection. When suspended, the connection will refuse to execute commands until it is restored using RestoreConnection.

This is useful for temporarily disabling command execution while keeping the underlying network connection alive.

Returns nil as this operation always succeeds.

Example:

err := conn.SuspendConnection()
// Commands will now fail until RestoreConnection is called