mirror of
https://github.com/inspec/inspec
synced 2025-02-17 06:28:40 +00:00
Kg/file (#2529)
* Refactors file docs Signed-off-by: kagarmoe <kgarmoe@chef.io> * Fixes terminal punctuation Signed-off-by: kagarmoe <kgarmoe@chef.io> * Adds deprecations and differentiates OS Signed-off-by: kagarmoe <kgarmoe@chef.io>
This commit is contained in:
Kimberly Garmoe
Christoph Hartmann
parent
f5acd5d34e
commit
ecf6900e9f
1 changed files with 138 additions and 133 deletions
|
|
@ -10,24 +10,156 @@ Use the `file` InSpec audit resource to test all system file types, including fi
|
|||
|
||||
## Syntax
|
||||
|
||||
A `file` resource block declares the location of the file type to be tested, what type that file should be (if required), and then one (or more) matchers:
|
||||
A `file` resource block declares the location of the file type to be tested, the expected file type (if required), and one (or more) resource properties.
|
||||
|
||||
describe file('path') do
|
||||
it { should MATCHER 'value' }
|
||||
it { should PROPERTY 'value' }
|
||||
end
|
||||
|
||||
where
|
||||
|
||||
* `('path')` is the name of the file and/or the path to the file
|
||||
* `MATCHER` is a valid matcher for this resource
|
||||
* `'value'` is the value to be tested
|
||||
* `('path')` is the name of the file and/or the path to the file.
|
||||
* `PROPERTY` is a valid resource property for this resource'
|
||||
* `'value'` is the value to be tested.
|
||||
|
||||
<br>
|
||||
|
||||
## Examples
|
||||
## Supported Resource Properties
|
||||
|
||||
### General Resource Properties
|
||||
|
||||
content, size, basename, path, owner, group, type
|
||||
|
||||
### Unix/Linux Resource Properties
|
||||
|
||||
symlink, mode, link_path, mtime, size, selinux\_label, md5sum, sha256sum, path, source, source\_path, uid, gid
|
||||
|
||||
### Windows Resource Properties
|
||||
|
||||
file\_version, product\_version
|
||||
|
||||
## Resource Property Examples
|
||||
|
||||
### content
|
||||
|
||||
The `content` property tests if contents in the file match the value specified in a regular expression. The values of the `content` property are arbitrary and depend on the file type being tested and also the type of information that is expected to be in that file:
|
||||
|
||||
its('content') { should match REGEX }
|
||||
|
||||
The following complete example tests the `pg_hba.conf` file in PostgreSQL for MD5 requirements. The tests look at all `host` and `local` settings in that file, and then compare the MD5 checksums against the values in the test:
|
||||
|
||||
describe file(hba_config_file) do
|
||||
its('content') { should match(%r{local\s.*?all\s.*?all\s.*?md5}) }
|
||||
its('content') { should match(%r{host\s.*?all\s.*?all\s.*?127.0.0.1\/32\s.*?md5}) }
|
||||
its('content') { should match(%r{host\s.*?all\s.*?all\s.*?::1\/128\s.*?md5})
|
||||
end
|
||||
|
||||
### file_version
|
||||
|
||||
The `file_version` property tests if a Windows file's version matches the specified value. The difference between a file's "file version" and "product version" is that the file version is the version number of the file itself, whereas the product version is the version number associated with the application from which that file originates:
|
||||
|
||||
its('file_version') { should eq '1.2.3' }
|
||||
|
||||
### group
|
||||
|
||||
The `group` property tests if the group to which a file belongs matches the specified value.
|
||||
|
||||
its('group') { should eq 'admins' }
|
||||
|
||||
The following examples show how to use this InSpec audit resource.
|
||||
|
||||
### link_path
|
||||
|
||||
The `link_path` property tests if the file exists at the specified path. If the file is a symlink,
|
||||
InSpec will resolve the symlink and return the ultimate linked file.
|
||||
|
||||
its('link_path') { should eq '/some/path/to/file' }
|
||||
|
||||
### md5sum
|
||||
|
||||
The `md5sum` property tests if the MD5 checksum for a file matches the specified value.
|
||||
|
||||
its('md5sum') { should eq '3329x3hf9130gjs9jlasf2305mx91s4j' }
|
||||
|
||||
### mode
|
||||
|
||||
The `mode` property tests if the mode assigned to the file matches the specified value.
|
||||
|
||||
its('mode') { should cmp '0644' }
|
||||
|
||||
### mtime
|
||||
|
||||
The `mtime` property tests if the file modification time for the file matches the specified value. The mtime, where supported, is returned as the number of seconds since the epoch.
|
||||
|
||||
describe file('/') do
|
||||
its('mtime') { should <= Time.now.to_i }
|
||||
its('mtime') { should >= Time.now.to_i - 1000 }
|
||||
end
|
||||
|
||||
### owner
|
||||
|
||||
The `owner` property tests if the owner of the file matches the specified value.
|
||||
|
||||
its('owner') { should eq 'root' }
|
||||
|
||||
### product_version
|
||||
|
||||
The `product_version` property tests if a Windows file's product version matches the specified value. The difference between a file's "file version" and "product version" is that the file version is the version number of the file itself, whereas the product version is the version number associated with the application from which that file originates.
|
||||
|
||||
its('product_version') { should eq 2.3.4 }
|
||||
|
||||
### selinux_label
|
||||
|
||||
The `selinux_label` property tests if the SELinux label for a file matches the specified value.
|
||||
|
||||
its('selinux_label') { should eq 'system_u:system_r:httpd_t:s0' }
|
||||
|
||||
### sha256sum
|
||||
|
||||
The `sha256sum` property tests if the SHA-256 checksum for a file matches the specified value.
|
||||
|
||||
its('sha256sum') { should eq 'b837ch38lh19bb8eaopl8jvxwd2e4g58jn9lkho1w3ed9jbkeicalplaad9k0pjn' }
|
||||
|
||||
### size
|
||||
|
||||
The `size` property tests if a file's size matches, is greater than, or is less than the specified value. For example, equal:
|
||||
|
||||
its('size') { should eq 32375 }
|
||||
|
||||
Greater than:
|
||||
|
||||
its('size') { should > 64 }
|
||||
|
||||
Less than:
|
||||
|
||||
its('size') { should < 10240 }
|
||||
|
||||
### type
|
||||
|
||||
The `type` property tests for the file type. The available types are:
|
||||
|
||||
* `file`: the object is a file
|
||||
* `directory`: the object is a directory
|
||||
* `link`: the object is a symbolic link
|
||||
* `pipe`: the object is a named pipe
|
||||
* `socket`: the object is a socket
|
||||
* `character_device`: the object is a character device
|
||||
* `block_device`: the object is a block device
|
||||
* `door`: the object is a door device
|
||||
|
||||
The `type` method usually returns the type as a Ruby "symbol". We recommend using the `cmp` matcher to match
|
||||
either by symbol or string.
|
||||
|
||||
For example:
|
||||
|
||||
its('type') { should eq :file }
|
||||
its('type') { should cmp 'file' }
|
||||
|
||||
or:
|
||||
|
||||
its('type') { should eq :socket }
|
||||
its('type') { should cmp 'socket' }
|
||||
|
||||
### Test the contents of a file for MD5 requirements
|
||||
|
||||
describe file(hba_config_file) do
|
||||
|
|
@ -128,11 +260,6 @@ The following examples show how to use this InSpec audit resource.
|
|||
its('size') { should be 0 }
|
||||
end
|
||||
|
||||
### Test that a file is not mounted
|
||||
|
||||
describe file('/proc/cpuinfo') do
|
||||
it { should_not be_mounted }
|
||||
end
|
||||
|
||||
### Test an MD5 checksum
|
||||
|
||||
|
|
@ -278,11 +405,6 @@ The `be_linked_to` matcher tests if the file is linked to the named target:
|
|||
|
||||
it { should be_linked_to '/etc/target-file' }
|
||||
|
||||
### be_mounted
|
||||
|
||||
The `be_mounted` matcher tests if the file is accessible from the file system:
|
||||
|
||||
it { should be_mounted }
|
||||
|
||||
### be\_owned\_by
|
||||
|
||||
|
|
@ -376,132 +498,15 @@ a user:
|
|||
|
||||
it { should be_writable.by_user('user') }
|
||||
|
||||
### content
|
||||
|
||||
The `content` matcher tests if contents in the file match the value specified in a regular expression. The values of the `content` matcher are arbitrary and depend on the file type being tested and also the type of information that is expected to be in that file:
|
||||
|
||||
its('content') { should match REGEX }
|
||||
|
||||
The following complete example tests the `pg_hba.conf` file in PostgreSQL for MD5 requirements. The tests look at all `host` and `local` settings in that file, and then compare the MD5 checksums against the values in the test:
|
||||
|
||||
describe file(hba_config_file) do
|
||||
its('content') { should match(%r{local\s.*?all\s.*?all\s.*?md5}) }
|
||||
its('content') { should match(%r{host\s.*?all\s.*?all\s.*?127.0.0.1\/32\s.*?md5}) }
|
||||
its('content') { should match(%r{host\s.*?all\s.*?all\s.*?::1\/128\s.*?md5})
|
||||
end
|
||||
|
||||
### exist
|
||||
|
||||
The `exist` matcher tests if the named file exists:
|
||||
|
||||
it { should exist }
|
||||
|
||||
### file_version
|
||||
|
||||
The `file_version` matcher tests if the file's version matches the specified value. The difference between a file's "file version" and "product version" is that the file version is the version number of the file itself, whereas the product version is the version number associated with the application from which that file originates:
|
||||
|
||||
its('file_version') { should eq '1.2.3' }
|
||||
|
||||
### group
|
||||
|
||||
The `group` matcher tests if the group to which a file belongs matches the specified value:
|
||||
|
||||
its('group') { should eq 'admins' }
|
||||
|
||||
### have_mode
|
||||
|
||||
The `have_mode` matcher tests if a file has a mode assigned to it:
|
||||
|
||||
it { should have_mode }
|
||||
|
||||
### link_path
|
||||
|
||||
The `link_path` matcher tests if the file exists at the specified path. If the file is a symlink,
|
||||
InSpec will resolve the symlink and return the ultimate linked file:
|
||||
|
||||
its('link_path') { should eq '/some/path/to/file' }
|
||||
|
||||
### md5sum
|
||||
|
||||
The `md5sum` matcher tests if the MD5 checksum for a file matches the specified value:
|
||||
|
||||
its('md5sum') { should eq '3329x3hf9130gjs9jlasf2305mx91s4j' }
|
||||
|
||||
### mode
|
||||
|
||||
The `mode` matcher tests if the mode assigned to the file matches the specified value:
|
||||
|
||||
its('mode') { should cmp '0644' }
|
||||
|
||||
### mtime
|
||||
|
||||
The `mtime` matcher tests if the file modification time for the file matches the specified value. The mtime, where supported, is returned as the number of seconds since the epoch.
|
||||
|
||||
describe file('/') do
|
||||
its('mtime') { should <= Time.now.to_i }
|
||||
its('mtime') { should >= Time.now.to_i - 1000 }
|
||||
end
|
||||
|
||||
### owner
|
||||
|
||||
The `owner` matcher tests if the owner of the file matches the specified value:
|
||||
|
||||
its('owner') { should eq 'root' }
|
||||
|
||||
### product_version
|
||||
|
||||
The `product_version` matcher tests if the file's product version matches the specified value. The difference between a file's "file version" and "product version" is that the file version is the version number of the file itself, whereas the product version is the version number associated with the application from which that file originates:
|
||||
|
||||
its('product_version') { should eq 2.3.4 }
|
||||
|
||||
### selinux_label
|
||||
|
||||
The `selinux_label` matcher tests if the SELinux label for a file matches the specified value:
|
||||
|
||||
its('selinux_label') { should eq 'system_u:system_r:httpd_t:s0' }
|
||||
|
||||
### sha256sum
|
||||
|
||||
The `sha256sum` matcher tests if the SHA-256 checksum for a file matches the specified value:
|
||||
|
||||
its('sha256sum') { should eq 'b837ch38lh19bb8eaopl8jvxwd2e4g58jn9lkho1w3ed9jbkeicalplaad9k0pjn' }
|
||||
|
||||
### size
|
||||
|
||||
The `size` matcher tests if a file's size matches, is greater than, or is less than the specified value. For example, equal:
|
||||
|
||||
its('size') { should eq 32375 }
|
||||
|
||||
Greater than:
|
||||
|
||||
its('size') { should > 64 }
|
||||
|
||||
Less than:
|
||||
|
||||
its('size') { should < 10240 }
|
||||
|
||||
### type
|
||||
|
||||
The `type` matcher tests for the file type. The available types are:
|
||||
|
||||
* `file`: the object is a file
|
||||
* `directory`: the object is a directory
|
||||
* `link`: the object is a symbolic link
|
||||
* `pipe`: the object is a named pipe
|
||||
* `socket`: the object is a socket
|
||||
* `character_device`: the object is a character device
|
||||
* `block_device`: the object is a block device
|
||||
* `door`: the object is a door device
|
||||
|
||||
The `type` method usually returns the type as a Ruby "symbol". We recommend using the `cmp` matcher to match
|
||||
either by symbol or string.
|
||||
|
||||
For example:
|
||||
|
||||
its('type') { should eq :file }
|
||||
its('type') { should cmp 'file' }
|
||||
|
||||
or:
|
||||
|
||||
its('type') { should eq :socket }
|
||||
its('type') { should cmp 'socket' }
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue