From ae7ca8cb6711ce1533234aceacb4c1900718ea3a Mon Sep 17 00:00:00 2001 From: Clinton Wolfe Date: Thu, 9 May 2019 15:01:57 -0400 Subject: [PATCH 1/4] Update README Signed-off-by: Clinton Wolfe --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 42 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 855f806..f087b32 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This plugin allows applications that rely on Train to communicate with the WinRM API. For example, you could use this to audit Windows Server 2016 machines. -TODO - details about underlying library +This plugin relies on the `winrm` and `winrm-fs` gems for implementation. Train itself has no CLI, nor a sophisticated test harness. Chef InSpec does have such facilities, so installing Train plugins will require a Chef InSpec installation. You do not need to use or understand Chef InSpec. @@ -10,6 +10,12 @@ Train plugins may be developed without a Chef InSpec installation. ## To Install this as a User +### ChefDK Installation + +After June 2019, this plugin will be distributed with ChefDK; you do not need to install it separately. + +### Manual Installation + Train plugins are distributed as gems. You may choose to manage the gem yourself, but if you are an Chef InSpec user, Chef InSpec can handle it for you. You will need Chef InSpec v2.3 or later. @@ -20,15 +26,47 @@ Simply run: $ inspec plugin install train-winrm ``` -You can then run: +You can then run, using Chef InSpec as an example: + +``` +you@home $ inspec some-profile winrm://someuser@somehost --password somepassword +``` +From Ruby code, you may use this plugin as follows: ``` -TODO - example +require 'train' +transport = Train.create('winrm', + host: '1.2.3.4', user: 'Administrator', password: '...', ssl: true, self_signed: true) +conn = transport.connection ``` ## Target Options for Train-WinRM -TODO +### host + +Required `String`. The hostname or IP address to connect to. + +#### port + +Optional `Integer`, default 5985 (plain) or 5896 (SSL). The port number to which the connection should be made. + +### user + +Optional `String`, username to connect as. Default 'Administrator'. + +### password + +Optional `String`, password to use to connect. None sent if not provided. + +### ssl + +Optional `Boolean`, defaults to `false`. Whether to use SSL to encrypt communications. + +Several other options exist; run: + +``` +puts Train.options('winrm') +``` ## Reporting Issues From 599c5d9b9677e781dd2941a9d366eda52cc622c7 Mon Sep 17 00:00:00 2001 From: Clinton Wolfe Date: Thu, 9 May 2019 15:11:59 -0400 Subject: [PATCH 2/4] Add testing info Signed-off-by: Clinton Wolfe --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f087b32..39f4aed 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,12 @@ If you wish to contribute to this plugin, please use the usual fork-branch-push- [Plugin Development](https://github.com/inspec/train/blob/master/docs/dev/plugins.md) is documented on the `train` project on GitHub. +### Unit tests + +Run `bundle exec rake test:unit` to run the unit tests. + ### Testing changes against a Windows Machine -TODO \ No newline at end of file +Install Vagrant and VirtualBox. Check the Vagrantfile to verify it references a Windows 2016 evaluation VagrantBox to which you have access. + +Then run `bundle exec rake test:integration` . There are sub-tasks you can use to run only the integration tests; see `rake -aT`. From efcbc48237877026d3a3f747ba15a3bfa8fb98aa Mon Sep 17 00:00:00 2001 From: Clinton Wolfe Date: Fri, 10 May 2019 18:26:57 -0400 Subject: [PATCH 3/4] Fix changelog Signed-off-by: Clinton Wolfe --- CHANGELOG.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b192ce2..0ece05a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,2 +1,8 @@ - \ No newline at end of file + + + + + + + From 427f32a2a076caef56a931d631c6380cce3fd25b Mon Sep 17 00:00:00 2001 From: Clinton Wolfe Date: Fri, 10 May 2019 18:27:10 -0400 Subject: [PATCH 4/4] README feedback Signed-off-by: Clinton Wolfe --- README.md | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 39f4aed..aafcda4 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # train-winrm - Train Plugin for connecting to Windows via Remote Management +* **Project State: Active** +* **Issues Response SLA: 3 business days** +* **Pull Request Response SLA: 3 business days** + This plugin allows applications that rely on Train to communicate with the WinRM API. For example, you could use this to audit Windows Server 2016 machines. This plugin relies on the `winrm` and `winrm-fs` gems for implementation. @@ -14,7 +18,7 @@ Train plugins may be developed without a Chef InSpec installation. After June 2019, this plugin will be distributed with ChefDK; you do not need to install it separately. -### Manual Installation +### Manual Installation using `inspec plugin install` Train plugins are distributed as gems. You may choose to manage the gem yourself, but if you are an Chef InSpec user, Chef InSpec can handle it for you. @@ -35,8 +39,14 @@ you@home $ inspec some-profile winrm://someuser@somehost --password somepassword From Ruby code, you may use this plugin as follows: ``` require 'train' -transport = Train.create('winrm', - host: '1.2.3.4', user: 'Administrator', password: '...', ssl: true, self_signed: true) +transport = Train.create( + 'winrm', + host: '1.2.3.4', + user: 'Administrator', + password: '...', + ssl: true, + self_signed: true +) conn = transport.connection ``` @@ -44,7 +54,7 @@ conn = transport.connection ### host -Required `String`. The hostname or IP address to connect to. +Required `String`. The hostname or IP address used for connection. #### port @@ -52,17 +62,17 @@ Optional `Integer`, default 5985 (plain) or 5896 (SSL). The port number to which ### user -Optional `String`, username to connect as. Default 'Administrator'. +Optional `String`, username used for sign in. Default `Administrator`. ### password -Optional `String`, password to use to connect. None sent if not provided. +Optional `String`, password used for sign in. None sent if not provided. ### ssl -Optional `Boolean`, defaults to `false`. Whether to use SSL to encrypt communications. +Optional `Boolean`. Defaults to `false`. Determines whether to use SSL to encrypt communications. -Several other options exist; run: +Several other options exist. To see these options, run: ``` puts Train.options('winrm') @@ -90,6 +100,6 @@ Run `bundle exec rake test:unit` to run the unit tests. ### Testing changes against a Windows Machine -Install Vagrant and VirtualBox. Check the Vagrantfile to verify it references a Windows 2016 evaluation VagrantBox to which you have access. +Install Vagrant and VirtualBox. Check the Vagrantfile to verify that it references a Windows 2016 evaluation VagrantBox to which you have access. -Then run `bundle exec rake test:integration` . There are sub-tasks you can use to run only the integration tests; see `rake -aT`. +Then, run `bundle exec rake test:integration`. There are sub-tasks you can use to run only the integration tests; to see a list of all tasks, run `rake -aT`.