winrm

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 7, 2021 License: Apache-2.0 Imports: 22 Imported by: 1

README

WinRM for Go

Note: if you're looking for the winrm command-line tool, this has been splitted from this project and is available at winrm-cli

This is a Go library to execute remote commands on Windows machines through the use of WinRM/WinRS.

Note: this library doesn't support domain users (it doesn't support GSSAPI nor Kerberos). It's primary target is to execute remote commands on EC2 windows machines.

Build Status Coverage Status

Contact

Getting Started

WinRM is available on Windows Server 2008 and up. This project natively supports basic authentication for local accounts, see the steps in the next section on how to prepare the remote Windows machine for this scenario. The authentication model is pluggable, see below for an example on using Negotiate/NTLM authentication (e.g. for connecting to vanilla Azure VMs).

Note: This library only supports Golang 1.7+

Preparing the remote Windows machine for Basic authentication

This project supports only basic authentication for local accounts (domain users are not supported). The remote windows system must be prepared for winrm:

For a PowerShell script to do what is described below in one go, check Richard Downer's blog

On the remote host, a PowerShell prompt, using the Run as Administrator option and paste in the following lines:

	winrm quickconfig
	y
	winrm set winrm/config/service/Auth '@{Basic="true"}'
	winrm set winrm/config/service '@{AllowUnencrypted="true"}'
	winrm set winrm/config/winrs '@{MaxMemoryPerShellMB="1024"}'

N.B.: The Windows Firewall needs to be running to run this command. See Microsoft Knowledge Base article #2004640.

N.B.: Do not disable Negotiate authentication as the winrm command itself uses this for internal authentication, and you risk getting a system where winrm doesn't work anymore.

N.B.: The MaxMemoryPerShellMB option has no effects on some Windows 2008R2 systems because of a WinRM bug. Make sure to install the hotfix described Microsoft Knowledge Base article #2842230 if you need to run commands that uses more than 150MB of memory.

For more information on WinRM, please refer to the online documentation at Microsoft's DevCenter.

Building the winrm go and executable

You can build winrm from source:

git clone https://github.com/masterzen/winrm
cd winrm
make

Note: this winrm code doesn't depend anymore on Gokogiri which means it is now in pure Go.

Note: you need go 1.5+. Please check your installation with

go version

Command-line usage

For command-line usage check the winrm-cli project

Library Usage

Warning the API might be subject to change.

For the fast version (this doesn't allow to send input to the command) and it's using HTTP as the transport:

package main

import (
	"github.com/masterzen/winrm"
	"os"
)

endpoint := winrm.NewEndpoint(host, 5986, false, false, nil, nil, nil, 0)
client, err := winrm.NewClient(endpoint, "Administrator", "secret")
if err != nil {
	panic(err)
}
client.Run("ipconfig /all", os.Stdout, os.Stderr)

or

package main
import (
  "github.com/masterzen/winrm"
  "fmt"
  "os"
)

endpoint := winrm.NewEndpoint("localhost", 5985, false, false, nil, nil, nil, 0)
client, err := winrm.NewClient(endpoint,"Administrator", "secret")
if err != nil {
	panic(err)
}

_, err := client.RunWithInput("ipconfig", os.Stdout, os.Stderr, os.Stdin)
if err != nil {
	panic(err)
}

By passing a TransportDecorator in the Parameters struct it is possible to use different Transports (e.g. NTLM)

package main
import (
  "github.com/masterzen/winrm"
  "fmt"
  "os"
)

endpoint := winrm.NewEndpoint("localhost", 5985, false, false, nil, nil, nil, 0)

params := DefaultParameters
params.TransportDecorator = func() Transporter { return &ClientNTLM{} }

client, err := NewClientWithParameters(endpoint, "test", "test", params)
if err != nil {
	panic(err)
}

_, err := client.RunWithInput("ipconfig", os.Stdout, os.Stderr, os.Stdin)
if err != nil {
	panic(err)
}

By passing a Dial in the Parameters struct it is possible to use different dialer (e.g. tunnel through SSH)

package main
     
 import (
    "github.com/masterzen/winrm"
    "golang.org/x/crypto/ssh"
    "os"
 )
 
 func main() {
 
    sshClient, err := ssh.Dial("tcp","localhost:22", &ssh.ClientConfig{
        User:"ubuntu",
        Auth: []ssh.AuthMethod{ssh.Password("ubuntu")},
        HostKeyCallback: ssh.InsecureIgnoreHostKey(),
    })
 
    endpoint := winrm.NewEndpoint("other-host", 5985, false, false, nil, nil, nil, 0)
 
    params := winrm.DefaultParameters
    params.Dial = sshClient.Dial
 
    client, err := winrm.NewClientWithParameters(endpoint, "test", "test", params)
    if err != nil {
        panic(err)
    }
 
    _, err = client.RunWithInput("ipconfig", os.Stdout, os.Stderr, os.Stdin)
    if err != nil {
        panic(err)
    }
 }

For a more complex example, it is possible to call the various functions directly:

package main

import (
  "github.com/masterzen/winrm"
  "fmt"
  "bytes"
  "os"
)

stdin := bytes.NewBufferString("ipconfig /all")
endpoint := winrm.NewEndpoint("localhost", 5985, false, false,nil, nil, nil, 0)
client , err := winrm.NewClient(endpoint, "Administrator", "secret")
if err != nil {
	panic(err)
}
shell, err := client.CreateShell()
if err != nil {
  panic(err)
}
var cmd *winrm.Command
cmd, err = shell.Execute("cmd.exe")
if err != nil {
  panic(err)
}

go io.Copy(cmd.Stdin, stdin)
go io.Copy(os.Stdout, cmd.Stdout)
go io.Copy(os.Stderr, cmd.Stderr)

cmd.Wait()
shell.Close()

For using HTTPS authentication with x 509 cert without checking the CA

package main

import (
    "github.com/masterzen/winrm"
    "io/ioutil"
    "log"
    "os"
)

func main() {
    clientCert, err := ioutil.ReadFile("/home/example/winrm_client_cert.pem")
    if err != nil {
        log.Fatalf("failed to read client certificate: %q", err)
    }

    clientKey, err := ioutil.ReadFile("/home/example/winrm_client_key.pem")
    if err != nil {
        log.Fatalf("failed to read client key: %q", err)
    }

    winrm.DefaultParameters.TransportDecorator = func() winrm.Transporter {
        // winrm https module
        return &winrm.ClientAuthRequest{}
    }

    endpoint := winrm.NewEndpoint(
        "192.168.100.2", // host to connect to
        5986,            // winrm port
        true,            // use TLS
        true,            // Allow insecure connection
        nil,             // CA certificate
        clientCert,      // Client Certificate
        clientKey,       // Client Key
        0,               // Timeout
    )
    client, err := winrm.NewClient(endpoint, "Administrator", "")
    if err != nil {
        log.Fatalf("failed to create client: %q", err)
    }
    _, err = client.Run("whoami", os.Stdout, os.Stderr)
    if err != nil {
        log.Fatalf("failed to run command: %q", err)
    }
}

Developing on WinRM

If you wish to work on winrm itself, you'll first need Go installed (version 1.5+ is required). Make sure you have Go properly installed, including setting up your GOPATH.

For some additional dependencies, Go needs Mercurial and Bazaar to be installed. Winrm itself doesn't require these, but a dependency of a dependency does.

Next, clone this repository into $GOPATH/src/github.com/masterzen/winrm and then just type make.

You can run tests by typing make test.

If you make any changes to the code, run make format in order to automatically format the code according to Go standards.

When new dependencies are added to winrm you can use make updatedeps to get the latest and subsequently use make to compile.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var DefaultParameters = NewParameters("PT60S", "en-US", 153600)

DefaultParameters return constant config of type Parameters

Functions

func NewClientWithDial 

func NewClientWithDial(dial func(network, addr string) (net.Conn, error)) *clientRequest

NewClientWithDial NewClientWithDial

func NewClientWithProxyFunc 

func NewClientWithProxyFunc(proxyfunc func(req *http.Request) (*url.URL, error)) *clientRequest

NewClientWithProxyFunc NewClientWithProxyFunc

func NewDeleteShellRequest 

func NewDeleteShellRequest(uri, shellID string, params *Parameters) *soap.SoapMessage

NewDeleteShellRequest ...

func NewExecuteCommandRequest 

func NewExecuteCommandRequest(uri, shellID, command string, arguments []string, params *Parameters) *soap.SoapMessage

NewExecuteCommandRequest exec command on specific shellID

func NewGetOutputRequest 

func NewGetOutputRequest(uri, shellID, commandID, streams string, params *Parameters) *soap.SoapMessage

NewGetOutputRequest NewGetOutputRequest

func NewOpenShellRequest 

func NewOpenShellRequest(uri string, params *Parameters) *soap.SoapMessage

NewOpenShellRequest makes a new soap request

func NewSendInputRequest 

func NewSendInputRequest(uri, shellID, commandID string, input []byte, eof bool, params *Parameters) *soap.SoapMessage

NewSendInputRequest NewSendInputRequest

func NewSignalRequest 

func NewSignalRequest(uri string, shellID string, commandID string, params *Parameters) *soap.SoapMessage

NewSignalRequest NewSignalRequest

func ParseExecuteCommandResponse 

func ParseExecuteCommandResponse(response string) (string, error)

ParseExecuteCommandResponse ParseExecuteCommandResponse

func ParseOpenShellResponse 

func ParseOpenShellResponse(response string) (string, error)

ParseOpenShellResponse ParseOpenShellResponse

func ParseSlurpOutputErrResponse 

func ParseSlurpOutputErrResponse(response string, stdout, stderr io.Writer) (bool, int, error)

ParseSlurpOutputErrResponse ParseSlurpOutputErrResponse

func ParseSlurpOutputResponse 

func ParseSlurpOutputResponse(response string, stream io.Writer, streamType string) (bool, int, error)

ParseSlurpOutputResponse ParseSlurpOutputResponse

func Powershell 

func Powershell(psCmd string) string

Powershell wraps a PowerShell script and prepares it for execution by the winrm client

Types

type Client 

type Client struct {
	Parameters
	// contains filtered or unexported fields
}

Client struct

func NewClient 

func NewClient(endpoint *Endpoint, user, password string) (*Client, error)

NewClient will create a new remote client on url, connecting with user and password This function doesn't connect (connection happens only when CreateShell is called)

func NewClientWithParameters 

func NewClientWithParameters(endpoint *Endpoint, user, password string, params *Parameters) (*Client, error)

NewClientWithParameters will create a new remote client on url, connecting with user and password This function doesn't connect (connection happens only when CreateShell is called)

func (*Client) CreateShell 

func (c *Client) CreateShell() (*Shell, error)

CreateShell will create a WinRM Shell, which is the prealable for running commands.

func (*Client) NewShell 

func (c *Client) NewShell(id string) *Shell

NewShell will create a new WinRM Shell for the given shellID

func (*Client) Run 

func (c *Client) Run(command string, stdout io.Writer, stderr io.Writer) (int, error)

Run will run command on the the remote host, writing the process stdout and stderr to the given writers. Note with this method it isn't possible to inject stdin.

func (*Client) RunPSWithString 

func (c *Client) RunPSWithString(command string, stdin string) (string, string, int, error)

RunPSWithString will basically wrap your code to execute commands in powershell.exe. Default RunWithString runs commands in cmd.exe

func (Client) RunWithInput 

func (c Client) RunWithInput(command string, stdout, stderr io.Writer, stdin io.Reader) (int, error)

RunWithInput will run command on the the remote host, writing the process stdout and stderr to the given writers, and injecting the process stdin with the stdin reader. Warning stdin (not stdout/stderr) are bufferized, which means reading only one byte in stdin will send a winrm http packet to the remote host. If stdin is a pipe, it might be better for performance reasons to buffer it.

func (*Client) RunWithString 

func (c *Client) RunWithString(command string, stdin string) (string, string, int, error)

RunWithString will run command on the the remote host, returning the process stdout and stderr as strings, and using the input stdin string as the process input

type ClientAuthRequest 

type ClientAuthRequest struct {
	// contains filtered or unexported fields
}

ClientAuthRequest ClientAuthRequest

func NewClientAuthRequestWithDial 

func NewClientAuthRequestWithDial(dial func(network, addr string) (net.Conn, error)) *ClientAuthRequest

NewClientAuthRequestWithDial NewClientAuthRequestWithDial

func (ClientAuthRequest) Post 

func (c ClientAuthRequest) Post(client *Client, request *soap.SoapMessage) (string, error)

Post Post

func (*ClientAuthRequest) Transport 

func (c *ClientAuthRequest) Transport(endpoint *Endpoint) error

Transport Transport

type ClientNTLM 

type ClientNTLM struct {
	// contains filtered or unexported fields
}

ClientNTLM provides a transport via NTLMv2

func NewClientNTLMWithDial 

func NewClientNTLMWithDial(dial func(network, addr string) (net.Conn, error)) *ClientNTLM

NewClientNTLMWithDial NewClientNTLMWithDial

func NewClientNTLMWithProxyFunc 

func NewClientNTLMWithProxyFunc(proxyfunc func(req *http.Request) (*url.URL, error)) *ClientNTLM

NewClientNTLMWithProxyFunc NewClientNTLMWithProxyFunc

func (ClientNTLM) Post 

func (c ClientNTLM) Post(client *Client, request *soap.SoapMessage) (string, error)

Post make post to the winrm soap service (forwarded to clientRequest implementation)

func (*ClientNTLM) Transport 

func (c *ClientNTLM) Transport(endpoint *Endpoint) error

Transport creates the wrapped NTLM transport

type Command 

type Command struct {
	Stdin  *commandWriter
	Stdout *commandReader
	Stderr *commandReader
	// contains filtered or unexported fields
}

Command represents a given command running on a Shell. This structure allows to get access to the various stdout, stderr and stdin pipes.

func (*Command) Close 

func (c *Command) Close() error

Close will terminate the running command

func (*Command) ExitCode 

func (c *Command) ExitCode() int

ExitCode returns command exit code when it is finished. Before that the result is always 0.

func (*Command) Wait 

func (c *Command) Wait()

Wait function will block the current goroutine until the remote command terminates.

type Endpoint 

type Endpoint struct {
	// host name or ip address
	Host string
	// port to determine if it's http or https default
	// winrm ports (http:5985, https:5986).Versions
	// of winrm can be customized to listen on other ports
	Port int
	// set the flag true for https connections
	HTTPS bool
	// set the flag true for skipping ssl verifications
	Insecure bool
	// if set, used to verify the hostname on the returned certificate
	TLSServerName string
	// pointer pem certs, and key
	CACert []byte // cert auth to intdetify the server cert
	Key    []byte // public key for client auth connections
	Cert   []byte // cert for client auth connections
	// duration timeout for the underling tcp conn(http/https base protocol)
	// if the time exceeds the connection is cloded/timeouts
	Timeout time.Duration
}

Endpoint struct holds configurations for the server endpoint

func NewEndpoint 

func NewEndpoint(host string, port int, https bool, insecure bool, Cacert, cert, key []byte, timeout time.Duration) *Endpoint

NewEndpoint returns new pointer to struct Endpoint, with a default 60s response header timeout

type Parameters 

type Parameters struct {
	Timeout            string
	Locale             string
	EnvelopeSize       int
	TransportDecorator func() Transporter
	Dial               func(network, addr string) (net.Conn, error)
}

Parameters struct defines metadata information and http transport config

func NewParameters 

func NewParameters(timeout, locale string, envelopeSize int) *Parameters

NewParameters return new struct of type Parameters this struct makes the configuration for the request, size message, etc.

type Shell 

type Shell struct {
	// contains filtered or unexported fields
}

Shell is the local view of a WinRM Shell of a given Client

func (*Shell) Close 

func (s *Shell) Close() error

Close will terminate this shell. No commands can be issued once the shell is closed.

func (*Shell) Execute 

func (s *Shell) Execute(command string, arguments ...string) (*Command, error)

Execute command on the given Shell, returning either an error or a Command

type Transporter 

type Transporter interface {
	// init request baset on the transport configurations
	Post(*Client, *soap.SoapMessage) (string, error)
	Transport(*Endpoint) error
}

Transporter does different transporters and init a Post request based on them

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.