inspec/docs/resources/processes.md.erb
Adam Leff 939ee5ecfc processes resource: support busybox ps (#2222)
This change enhances the processes resource to support the busybox
ps command which is common on Alpine, for example. The way we
map ps fields to the structs needed by FilterTable have also been
refactored to be more flexible so we can support multiple formats
in the future.

Also, the processes resource now allows the grep argument to be optional
thus allowing a user to query all resources without passing in a
match-all regex.

Signed-off-by: Adam Leff <adam@leff.co>
2017-10-06 19:32:39 +02:00

107 lines
3.2 KiB
Text

---
title: About the processes Resource
---
# processes
Use the `processes` InSpec audit resource to test properties for programs that are running on the system.
<br>
## Syntax
A `processes` resource block declares the name of the process to be tested, and then declares one (or more) property/value pairs:
describe processes('process_name') do
its('property_name') { should eq ['property_value'] }
end
where
* `processes('process_name')` specifies the name of a process to check. If this is a string, it will be converted to a Regexp. For more specificity, pass a Regexp directly. If left blank, all processes will be returned.
* `property_name` may be used to test user (`its('users')`) and state properties (`its('states')`)
<br>
## Examples
The following examples show how to use this InSpec audit resource.
### Test if the list length for the mysqld process is 1
describe processes('mysqld') do
its('list.length') { should eq 1 }
end
### Test if the process is owned by a specifc user
describe processes('init') do
its('users') { should eq ['root'] }
end
describe processes('winlogon') do
its('users') { should cmp "NT AUTHORITY\\SYSTEM" }
end
### Test if a high-priority process is running
describe processes('linux_process') do
its('states') { should eq ['R<'] }
end
describe processes('windows_process') do
its('labels') { should cmp "High" }
end
### Test if a process exists on the system
describe processes('some_process') do
it { should exist }
end
### Test for a process using a specific Regexp
If the process name is too common for a string to uniquely find it,
you may use a regexp. Inclusion of whitespace characters may be
needed.
describe processes(Regexp.new("/usr/local/bin/swap -d")) do
its('list.length') { should eq 1 }
end
### Notes for auditing Windows systems
Sometimes with system properties there isn't a direct comparison between different operating systems.
Most of the `property_name`'s do align between the different OS's.
There are however some exception's, for example, within linux `states` offers multiple properties.
Windows doesn't have direct comparison that is a single property so instead `states` is mapped to the property of `Responding`, This is a boolean true/false flag to help determine if the process is hung.
Below is a mapping table to help you understand what property the unix field maps to the windows `Get-Process` Property
| *unix ps field* | *windows PowerShell Property* |
|:---------------:|:-----------------------------:|
|labels |PriorityClass|
|pids |Id|
|cpus |CPU|
|mem |PM|
|vsz |VirtualMemorySize|
|rss |NPM|
|tty |SessionId|
|states |Responding|
|start |StartTime|
|time |TotalProcessorTime|
|users |UserName|
|commands |Path|
## Matchers
This InSpec audit resource has the following matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### property_name
The `property_name` matcher tests the named property for the specified value:
its('property_name') { should eq ['property_value'] }