inspec 2.3.10 → 2.3.23

data/docs/resources/shadow.md.erb

@@ -1,267 +0,0 @@
----
-title: About the shadow Resource
-platform: linux
----
-
-# shadow
-
-Use the `shadow` InSpec audit resource to test the contents of `/etc/shadow`, which contains password details that are readable only by the `root` user. `shadow` is a [plural resource](https://www.inspec.io/docs/reference/glossary/#plural_resource). Like all plural resources, it functions by performing searches across multiple entries in the shadow file.
-
-The format for `/etc/shadow` includes:
-
-* A username
-* The hashed password for that user
-* The last date a password was changed, as the number of days since Jan 1 1970
-* The minimum number of days a password must exist, before it may be changed
-* The maximum number of days after which a password must be changed
-* The number of days a user is warned about an expiring password
-* The number of days a user must be inactive before the user account is disabled
-* The date on which a user account was disabled, as the number of days since Jan 1 1970
-
-These entries are defined as a colon-delimited row in the file, one row per user:
-
-    dannos:Gb7crrO5CDF.:10063:0:99999:7:::
-
-The `shadow` resource understands this format, allows you to search on the fields, and exposes the selected users' properties.
-
-<br>
-
-## Availability
-
-### Installation
-
-This resource is distributed along with InSpec itself. You can use it automatically.
-
-### Version
-
-This resource first became available in v1.0.0 of InSpec.
-
-## Resource Parameters
-
-The `shadow` resource takes one optional parameter: the path to the shadow file. If omitted, `/etc/shadow` is assumed.
-
-    # Expect a file to exist at the default location and have 32 users
-    describe shadow do
-      its('count') { should eq 32 }
-    end
-
-    # Use a custom location
-    describe shadow('/etc/my-custom-place/shadow') do
-      its('count') { should eq 32 }
-    end
-
-## Examples
-
-A `shadow` resource block uses `where` to filter entries from the shadow file. If `where` is omitted, all entries are selected.
-
-    # Select all users. Among them, there should not be a user with the name 'forbidden_user'.
-    describe shadow do
-      its('users') { should_not include 'forbidden_user' }
-    end
-
-    # Ensure there is only one user named 'root' (Select all with name 'root', then count them).
-    describe shadow.where(user: 'root') do
-      its('count') { should eq 1 }
-    end
-
-Use `where` to match any of the supported [filter criteria](#filter_criteria). `where` has a method form for simple equality and a block form for more complex queries.
-
-    # Method form, simple
-    # Select just the root user (direct equality)
-    describe shadow.where(user: 'root') do
-      its ('count') { should eq 1 }
-    end
-
-    # Method form, with a regex
-    # Select all users whose names begin with smb
-    describe shadow.where(user: /^smb/) do
-      its ('count') { should eq 2 }
-    end
-
-    # Block form
-    # Select users whose passwords have expired
-    describe shadow.where { expiry_date > 0 } do
-      # This test directly asserts that there should be 0 such users
-      its('count') { should eq 0 }
-      # But if the count test fails, this test outputs the users that are causing the failure.
-      its('users') { should be_empty }
-    end
-
-<br>
-
-## Properties
-
-As a [plural resource](https://www.inspec.io/docs/reference/glossary/#plural_resource), all of `shadow`'s properties return lists (that is, Ruby Arrays). `include` and `be_empty` are two useful matchers when working with lists. You can also perform manipulation of the lists, such as calling `uniq`, `sort`, `count`, `first`, `last`, `min`, and `max`.
-
-### users
-
-A list of strings, representing the usernames matched by the filter.
-
-    describe shadow
-      its('users') { should include 'root' }
-    end
-
-### passwords
-
-A list of strings, representing the encrypted password strings for entries matched by the `where` filter. Each string may not be an encrypted password, but rather a `*` or similar which indicates that direct logins are not allowed. Different operating systems use different flags here (such as `*LK*` to indicate the account is locked).
-
-    # Use uniq to remove duplicates, then determine
-    # if the only password left on the list is '*'
-    describe shadow.where(user: /adm$/) do
-      its('passwords.uniq.first') { should cmp '*' }
-      its('passwords.uniq.count') { should eq 1 }
-    end
-
-### last\_changes
-
-A list of integers, indicating the number of days since Jan 1 1970 since the password for each matching entry was changed.
-
-    # Ensure all entries have changed their password in the last 90 days.  (Probably want a filter on that)
-    describe shadow do
-      its('last_changes.min') { should be < Date.today - 90 - Date.new(1970,1,1)   }
-    end
-
-### min\_days
-
-A list of integers reflecting the minimum number of days a password must exist, before it may be changed, for the users that matched the filter.
-
-    # min_days seems crazy today; make sure it is zero for everyone
-    describe shadow do
-      its('min_days.uniq') { should eq [0] }
-    end
-
-### max\_days
-
-A list of integers reflecting the maximum number of days after which the password must be changed for each user matching the filter.
-
-    # Make sure there is no policy allowing longer than 90 days
-    describe shadow do
-      its('max_days.max') { should be < 90 }
-    end
-
-### warn\_days
-
-A list of integers reflecting the number of days a user is warned about an expiring password for each user matching the filter.
-
-    # Ensure everyone gets the same 7-day policy
-    describe shadow do
-      its('warn_days.uniq.count') { should eq 1 }
-      its('warn_days.uniq.first') { should eq 7 }
-    end
-
-### inactive\_days
-
-A list of integers reflecting the number of days a user must be inactive before the user account is disabled for each user matching the filter.
-
-    # Ensure everyone except admins has an stale policy of no more than 14 days
-    describe shadow.where { user !~ /adm$/ } do
-      its('inactive_days.max') { should be <= 14 }
-    end
-
-### expiry\_dates
-
-A list of integers reflecting the number of days since Jan 1 1970 that a user account has been disabled, for each user matching the filter. Value is `nil` if the account has not expired.
-
-    # No one should have an expired account.
-    describe shadow do
-      its('expiry_dates.compact') { should be_empty }
-    end
-
-### count
-
-The `count` property tests the number of records that the filter matched.
-
-    # Should probably only have one root user
-    describe shadow.user('root') do
-      its('count') { should eq 1 }
-    end
-
-<br>
-
-## Filter Criteria
-
-You may use any of these filter criteria with the `where` function.  They are named after the columns in the shadow file. Each has a related list [property](#properties).
-
-### user
-
-The string username of a user.  Always present.  Not required to be unique.
-
-    # Expect all users whose name ends in adm to have a disabled password via the '*' flag
-    describe shadow.where(user: /adm$/) do
-      its('password.uniq') { should eq ['*'] }
-    end
-
-### password
-
-The encrypted password strings, or an account status string. Each string may not be an encrypted password, but rather a `*` or similar which indicates that direct logins are not allowed. Different operating systems use other flags here (such as `*LK*` to indicate the account is locked).
-
-    # Find 'locked' accounts and ensure 'nobody' is on the list
-    describe shadow.where(password: '*LK*') do
-      its('users') { should include 'nobody' }
-    end
-
-### last_change
-
-An integer reflecting the number of days since Jan 1 1970 since the user's password was changed.
-
-    # Find users who have not changed their password within 90 days
-    describe shadow.where { last_change > Date.today - 90 - Date.new(1970,1,1) } do
-      its('users') { should be_empty }
-    end
-
-### min_days
-
-An integer reflecting the minimum number of days a user is required to wait before
-changing their password again.
-
-    # Find users who have a nonzero wait time
-    describe shadow.where { min_days > 0 } do
-      its('users') { should be_empty }
-    end
-
-### max_days
-
-An integer reflecting the maximum number of days a user may go without changing their password.
-
-    # All users should have a 30-day policy
-    describe shadow.where { max_days != 30 } do
-      its('users') { should be_empty }
-    end
-
-### warn_days
-
-An integer reflecting the number of days before a password expiration that a user recieves an alert.
-
-    # All users should have a 7-day warning policy
-    describe shadow.where { warn_days != 7 } do
-      its('users') { should be_empty }
-    end
-
-### inactive_days
-
-An integer reflecting the number of days that must pass before a user who has not logged in will be disabled.
-
-    # Ensure everyone has a stale policy of no more than 14 days.
-    describe shadow.where { inactive_days.nil? || inactive_days > 14 } do
-      its('users') { should be_empty }
-    end
-
-### expiry_date
-
-An integer reflecting the number of days since Jan 1, 1970 on which the user was disabled. The `expiry_date` criterion is `nil` for enabled users.
-
-    # Ensure no one is disabled due to a old password
-    describe shadow.where { !expiry_date.nil? } do
-      its('users') { should be_empty }
-    end
-
-    # Ensure no one is disabled for more than 14 days
-    describe shadow.where { !expiry_date.nil? && expiry_date - Date.new(1970,1,1) > 14} do
-      its('users') { should be_empty }
-    end
-
-## Matchers
-
-This resource has no resource-specific matchers.
-
-For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).

data/docs/resources/ssh_config.md.erb

@@ -1,83 +0,0 @@
----
-title: About the ssh_config Resource
-platform: linux
----
-
-# ssh_config
-
-Use the `ssh_config` InSpec audit resource to test OpenSSH client configuration data located at `/etc/ssh/ssh_config` on Linux and Unix platforms.
-
-<br>
-
-## Availability
-
-### Installation
-
-This resource is distributed along with InSpec itself. You can use it automatically.
-
-### Version
-
-This resource first became available in v1.0.0 of InSpec.
-
-## Syntax
-
-An `ssh_config` resource block declares the client OpenSSH configuration data to be tested:
-
-    describe ssh_config('path') do
-      its('name') { should include('foo') }
-    end
-
-where
-
-* `name` is a configuration setting in `ssh_config`
-* `('path')` is the non-default `/path/to/ssh_config`
-* `{ should include('foo') }` tests the value of `name` as read from `ssh_config` versus the value declared in the test
-
-<br>
-
-## Examples
-
-The following examples show how to use this InSpec audit resource.
-
-### Test SSH configuration settings
-
-    describe ssh_config do
-      its('cipher') { should contain '3des' }
-      its('port') { should eq '22' }
-      its('hostname') { should include('example.com') }
-    end
-
-### Test which variables from the local environment are sent to the server
-
-    only_if do
-      command('sshd').exist? or command('ssh').exists?
-    end
-
-    describe ssh_config do
-      its('SendEnv') { should include('GORDON_CLIENT') }
-    end
-
-### Test SSH configuration
-
-    describe ssh_config do
-      its('Host') { should eq '*' }
-      its('Tunnel') { should eq nil }
-      its('SendEnv') { should eq 'LANG LC_*' }
-      its('HashKnownHosts') { should eq 'yes' }
-    end
-
-<br>
-
-## Matchers
-
-For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
-
-### name
-
-The `name` matcher tests the value of `name` as read from `ssh_config` versus the value declared in the test:
-
-    its('name') { should eq 'foo' }
-
-or:
-
-    its('name') { should include('bar') }

data/docs/resources/sshd_config.md.erb

@@ -1,93 +0,0 @@
----
-title: About the sshd_config Resource
-platform: linux
----
-
-# sshd_config
-
-Use the `sshd_config` InSpec audit resource to test configuration data for the OpenSSH daemon located at `/etc/ssh/sshd_config` on Linux and Unix platforms. sshd---the OpenSSH daemon---listens on dedicated ports, starts a daemon for each incoming connection, and then handles encryption, authentication, key exchanges, command execution, and data exchanges.
-
-<br>
-
-## Availability
-
-### Installation
-
-This resource is distributed along with InSpec itself. You can use it automatically.
-
-### Version
-
-This resource first became available in v1.0.0 of InSpec.
-
-## Syntax
-
-An `sshd_config` resource block declares the client OpenSSH configuration data to be tested:
-
-    describe sshd_config('path') do
-      its('name') { should include('foo') }
-    end
-
-where
-
-* `name` is a configuration setting in `sshd_config`
-* `('path')` is the non-default `/path/to/sshd_config`
-* `{ should include('foo') }` tests the value of `name` as read from `sshd_config` versus the value declared in the test
-
-<br>
-
-## Examples
-
-The following examples show how to use this InSpec audit resource.
-
-### Test which variables may be sent to the server
-
-    describe sshd_config do
-      its('AcceptEnv') { should include('GORDON_SERVER') }
-    end
-
-### Test for IPv6-only addresses
-
-    describe sshd_config do
-      its('AddressFamily') { should cmp 'inet6' }
-    end
-
-### Test the Protocol setting
-
-    describe sshd_config do
-      its('Protocol') { should cmp 2 }
-    end
-
-### Test for approved, strong ciphers
-
-    describe sshd_config do
-      its('Ciphers') { should cmp('chacha20-poly1305@openssh.com,aes256-ctr,aes192-ctr,aes128-ctr') }
-    end
-
-### Test SSH protocols
-
-    describe sshd_config do
-      its('Port') { should cmp  22 }
-      its('UsePAM') { should eq 'yes' }
-      its('ListenAddress') { should eq nil }
-      its('HostKey') { should eq [
-          '/etc/ssh/ssh_host_rsa_key',
-          '/etc/ssh/ssh_host_dsa_key',
-          '/etc/ssh/ssh_host_ecdsa_key',
-        ] }
-    end
-
-<br>
-
-## Matchers
-
-For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
-
-### name
-
-The `name` matcher tests the value of `name` as read from `sshd_config` versus the value declared in the test:
-
-    its('name') { should cmp 'foo' }
-
-or:
-
-    its('name') {should include('bar') }

data/docs/resources/ssl.md.erb

@@ -1,129 +0,0 @@
----
-title: About the ssl Resource
-platform: os
----
-
-# ssl
-
-Use the `ssl` InSpec audit resource to test SSL settings for the named port.
-
-<br>
-
-## Availability
-
-### Installation
-
-This resource is distributed along with InSpec itself. You can use it automatically.
-
-### Version
-
-This resource first became available in v1.0.0 of InSpec.
-
-## Syntax
-
-An `ssl` resource block declares an SSL port, and then other properties of the test like cipher and/or protocol:
-
-    describe ssl(port: #) do
-      it { should be_enabled }
-    end
-
-or:
-
-    describe ssl(port: #).filter('value') do
-      it { should be_enabled }
-    end
-
-where
-
-* `ssl(port: #)` is the port number, such as `ssl(port: 443)`
-* `filter` may take any of the following arguments: `ciphers`, `protocols`, and `handshake`
-
-<br>
-
-## Examples
-
-The following examples show how to use this InSpec audit resource.
-
-### Run the ssl-benchmark example profile
-
-The following shows how to use the `ssl` InSpec audit resource to find all TCP ports on the system, including IPv4 and IPv6. (This is a partial example based on the `ssl_text.rb` file in the `ssl-benchmark` profile on GitHub.)
-
-    ...
-
-    control 'tls1.2' do
-      title 'Run TLS 1.2 whenever SSL is active on a port'
-      impact 0.5
-
-      sslports.each do |socket|
-        proc_desc = "on node == #{command('hostname').stdout.strip} running #{socket.process.inspect} (#{socket.pid})"
-        describe ssl(port: socket.port).protocols('tls1.2') do
-          it(proc_desc) { should be_enabled }
-          it { should be_enabled }
-        end
-      end
-    end
-
-    ...
-
-    control 'rc4' do
-      title 'Disable RC4 ciphers from all exposed SSL/TLS ports and versions.'
-      impact 0.5
-
-      sslports.each do |socket|
-        proc_desc = "on node == #{command('hostname').stdout.strip} running #{socket.process.inspect} (#{socket.pid})"
-        describe ssl(port: socket.port).ciphers(/rc4/i) do
-          it(proc_desc) { should_not be_enabled }
-          it { should_not be_enabled }
-        end
-      end
-    end
-
-There are two ways to run the `ssl-benchmark` example profile to test SSL via the `ssl` resource.
-
-Clone the profile:
-
-    $ git clone https://github.com/dev-sec/ssl-benchmark
-
-and then run:
-
-    $ inspec exec ssl-benchmark
-
-Or execute the profile directly via URL:
-
-    $ inspec exec https://github.com/dev-sec/ssl-benchmark
-
-<br>
-
-## Matchers
-
-For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
-
-### be_enabled
-
-The `be_enabled` matcher tests if SSL is enabled:
-
-    it { should be_enabled }
-
-### ciphers
-
-The `ciphers` matcher tests the named cipher:
-
-    its('ciphers') { should_not eq '/rc4/i' }
-
-or:
-
-    describe ssl(port: 443).ciphers(/rc4/i) do
-      it { should_not be_enabled }
-    end
-
-### protocols
-
-The `protocols` matcher tests what protocol versions (SSLv3, TLSv1.1, etc) are enabled:
-
-    its('protocols') { should eq 'ssl2' }
-
-or:
-
-    describe ssl(port: 443).protocols('ssl2') do
-      it { should_not be_enabled }
-    end