gowindows

Overview

gowindows is a Go library designed for remotely configuring and managing Windows-based systems.

Leveraging WinRM and SSH connections, gowindows provides a comprehensive set of functions to execute PowerShell commands, making it easy to automate tasks, manage users, groups, and more on remote Windows servers.

This library is especially useful when combined with tools like Terraform, enabling seamless integration into infrastructure as code workflows for Windows environments.

Usage

Single Client with an SSH Connection

package main

import (
    "context"
    "fmt"

    "github.com/d-strobel/gowindows/connection/ssh"
    "github.com/d-strobel/gowindows/windows/local/accounts"
)

func main() {
    sshConfig := &ssh.Config{
        Host:     "winsrv",
        Username: "vagrant",
        Password: "vagrant",
    }

    // Create a new connection.
    conn, err := ssh.NewConnection(sshConfig)
    if err != nil {
        panic(err)
    }

    // Create a client for the local accounts package.
    c := accounts.NewClient(conn)
    defer c.Connection.Close()

    // Run the GroupRead function to retrieve a local Windows group.
    group, err := c.GroupRead(context.Background(), accounts.GroupReadParams{Name: "Users"})
    if err != nil {
        panic(err)
    }

    // Print the user group.
    fmt.Printf("User group: %+v", group)
}

Multi Client with a WinRM Connection

package main

import (
    "context"
    "fmt"

    "github.com/d-strobel/gowindows"
    "github.com/d-strobel/gowindows/connection/winrm"
    "github.com/d-strobel/gowindows/windows/local/accounts"
)

func main() {
    winrmConfig := &winrm.Config{
        Host:     "winsrv",
        Username: "vagrant",
        Password: "vagrant",
    }

    // Create a new connection.
    conn, err := winrm.NewConnection(winrmConfig)
    if err != nil {
        panic(err)
    }

    // Create client for all subpackages.
    c := gowindows.NewClient(conn)
    defer c.Close()

    // Run the GroupRead function to retrieve a local Windows group.
    group, err := c.LocalAccounts.GroupRead(context.Background(), accounts.GroupReadParams{Name: "Users"})
    if err != nil {
        panic(err)
    }

    // Print the user group.
    fmt.Printf("User group: %+v", group)
}

Development

Pre-commit

To ensure smooth execution in the pipeline and eliminate potential linting errors, it's highly advisable to integrate pre-commit hooks. These hooks can be effortlessly installed to streamline the process and maintain code quality standards.

You can find more details about pre-commit hooks on their official website: pre-commit.

Conventional Commits

gowindows follows the conventional commit guidelines. For more information, see conventionalcommits.org.

Testing

Unit tests

Run unit tests:

make test

Acceptance test

Prerequisites:

• Hashicorp Vagrant
• Oracle VirtualBox

Boot the Vagrant machines:

make vagrant-up

Run acceptance tests:

make testacc

Destroy the Vagrant machines:

make vagrant-down

Third-Party libraries

• For the WinRM connection part, I rely on the library masterzen/winrm.

Inspirations

• hashicorp - terraform-provider-ad:
  Hashicorp made a great start with the terraform-provider-ad. Currently, it seems that the provider is not actively maintained.
  Beyond that, my goal is to split the terraform-provider into a library and a provider and extend its functionality with non Active-Directory systems.

License

This project is licensed under the Mozilla Public License Version 2.0.