From 4084a770efdda1be50246fa355520198317f523f Mon Sep 17 00:00:00 2001
From: username-is-already-taken2 <digitalgaz@hotmail.com>
Date: Sun, 20 Nov 2016 19:28:44 +0000
Subject: [PATCH] Added documentation

Signed-off-by: username-is-already-taken2 <digitalgaz@hotmail.com>
---
 docs/resources/windows_task.md.erb | 103 +++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 docs/resources/windows_task.md.erb

diff --git a/docs/resources/windows_task.md.erb b/docs/resources/windows_task.md.erb
new file mode 100644
index 000000000..848a5ac57
--- /dev/null
+++ b/docs/resources/windows_task.md.erb
@@ -0,0 +1,103 @@
+---
+title: About the windows_task Resource
+---
+
+# windows_task
+
+Use the `windows_task` Inspec audit resource to test a scheduled tasks configuration on a Windows platform. 
+Microsoft and application vendors use scheduled tasks to perform a varity of system maintaince tasks but system administrators can schedule their own.
+
+## Syntax
+
+A `windows_task` resource block declares the name of the task (as its full path) and tests its configuration:
+
+    describe windows_task('task name uri' do
+      its('parameter') { should eq 'value' }
+      it { should be_enabled }
+    end
+
+where
+
+* `'parameter'` must be a valid parameter defined within this resource  ie `logon_mode`, `last_result`, `task_to_run`, `run_as_user` 
+* `'value'` will be used to compare the value gather from your chosen parameter
+* `'be_enabled'` is an example of a valid matcher that checks the state of a task, other examples are `exist` or `be_disabled` 
+
+## Matchers
+
+This InSpec audit resource has the following matchers:
+
+### be
+
+<%= partial "/shared/matcher_be" %>
+
+### cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+### eq
+
+<%= partial "/shared/matcher_eq" %>
+
+### include
+
+<%= partial "/shared/matcher_include" %>
+
+### match
+
+<%= partial "/shared/matcher_match" %>
+
+## Examples
+
+The following examples show how to use this InSpec resource.
+
+### Test's that a task is enabled
+```
+describe windows_task('\Microsoft\Windows\Time Synchronization\SynchronizeTime') do
+  it { should be_enabled }
+end
+```
+
+### Test's that a task is disabled
+```
+describe windows_task('\Microsoft\Windows\AppID\PolicyConverter') do
+  it { should be_disabled }
+end
+```
+
+### Test's the configuration parameters of a task
+```
+describe windows_task('\Microsoft\Windows\AppID\PolicyConverter') do
+  its('logon_mode') { should eq 'Interactive/Background' }
+  its('last_result') { should eq '1' }
+  its('task_to_run') { should cmp '%Windir%\system32\appidpolicyconverter.exe' }
+  its('run_as_user') { should eq 'LOCAL SERVICE' }
+end
+```
+
+### Test's that a task is defined
+```
+describe windows_task('\Microsoft\Windows\Defrag\ScheduledDefrag') do
+  it { should exist }
+end
+```
+
+## Gathering Tasknames
+Rather then use the GUI you can use the `schtasks.exe` to output a full list of tasks available on the system
+
+`schtasks /query /FO list`
+
+rather than use the `list` output you can use `CSV` if it is easier.
+
+Please make sure you use the full TaskName (include the prefix `\`) within your control
+
+```
+C:\>schtasks /query /FO list
+...
+Folder: \Microsoft\Windows\Diagnosis
+HostName:      XPS15
+TaskName:      \Microsoft\Windows\Diagnosis\Scheduled
+Next Run Time: N/A
+Status:        Ready
+Logon Mode:    Interactive/Background
+...
+```
\ No newline at end of file