2
0
Fork 0
mirror of https://github.com/inspec/inspec synced 2024-12-18 17:14:33 +00:00
inspec/docs/resources/powershell.md.erb
Franklin Webber a9726910ff Fixes resources in the docs
* Fixes the npm package example to state 'npm' vs 'gem'
* Fixes powershell resource to specify the resource instead of 'script'
* Updates the example to rename variable 'script'

While ruby would allow the local variable and the presence of the InSpec method at the same time I think that it is bad form. Other resource examples also use 'script'.

* Changes pip to show generic example

Other package like resources show a generic example in the default.

Signed-off-by: Franklin Webber <franklin@chef.io>
2016-11-19 17:57:03 -08:00

116 lines
2.5 KiB
Text

---
title: About the powershell Resource
---
# powershell
Use the `powershell` InSpec audit resource to test a Powershell script on the Windows platform.
## Syntax
A `powershell` resource block declares a Powershell script to be tested, and then compares the output of that command to the matcher in the test:
script = <<-EOH
# a PowerShell script
EOH
describe powershell(script) do
its('matcher') { should eq 'output' }
end
where
* `'script'` must specify a Powershell script to be run
* `'matcher'` is one of `exit_status`, `stderr`, or `stdout`
* `'output'` tests the output of the command run on the system versus the output value stated in the test
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### exit_status
The `exit_status` matcher tests the exit status for the command:
its('exit_status') { should eq 123 }
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### stderr
The `stderr` matcher tests results of the command as returned in standard error (stderr):
its('stderr') { should eq 'error' }
### stdout
The `stdout` matcher tests results of the command as returned in standard output (stdout):
its('stdout') { should eq '/^1$/' }
## Examples
The following examples show how to use this InSpec audit resource.
### Get all groups of Administrator user
script = <<-EOH
# find user
$user = Get-WmiObject Win32_UserAccount -filter "Name = 'Administrator'"
# get related groups
$groups = $user.GetRelated('Win32_Group') | Select-Object -Property Caption, Domain, Name, LocalAccount, SID, SIDType, Status
$groups | ConvertTo-Json
EOH
describe powershell(script) do
its('stdout') { should_not eq '' }
end
### Write-Output 'hello'
The following Powershell script:
script = <<-EOH
Write-Output 'hello'
EOH
can be tested in the following ways.
For a newline:
describe powershell(script) do
its('stdout') { should eq "hello\r\n" }
its('stderr') { should eq '' }
end
Removing whitespace `\r\n` from `stdout`:
describe powershell(script) do
its('strip') { should eq "hello" }
end
No newline:
describe powershell("'hello' | Write-Host -NoNewLine") do
its('stdout') { should eq 'hello' }
its('stderr') { should eq '' }
end