Project: Chef InSpec (Provisioning / Security & Compliance)
File: ssl.md

+++ title = "ssl resource" draft = false gh_repo = "inspec" platform = "os" [menu] [menu.inspec] title = "ssl" identifier = "inspec/resources/os/ssl.md ssl resource" parent = "inspec/resources/os" +++ Use the `ssl` Chef InSpec audit resource to test SSL settings for the named port. {{< readfile file="content/inspec/reusable/md/inspec_installation.md" >}} This resource first became available in v1.0.0 of InSpec. 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` The `ciphers` property tests the named cipher: its('ciphers') { should_not eq '/rc4/i' } or: describe ssl(port: 443).ciphers(/rc4/i) do it { shouldnot beenabled } end The `protocols` property tests what protocol versions (SSLv3, TLSv1.1, etc) are enabled: its('protocols') { should eq 'ssl2' } or: describe ssl(port: 443).protocols('ssl2') do it { shouldnot beenabled } end The following examples show how to use this Chef InSpec audit resource. The following shows how to use the `ssl` Chef 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-baseline` 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(procdesc) { should beenabled } 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(procdesc) { shouldnot be_enabled } it { shouldnot beenabled } end end end There are two ways to run the `ssl-baseline` example profile to test SSL via the `ssl` resource. Clone the profile: $ git clone https://github.com/dev-sec/ssl-baseline and then run: $ inspec exec ssl-baseline Or execute the profile directly via URL: $ inspec exec https://github.com/dev-sec/ssl-baseline {{< readfile file="content/inspec/reusable/md/inspecmatcherslink.md" >}} This resource has the following special matchers. The `be_enabled` matcher tests if SSL is enabled: it { should be_enabled } The `ciphers` matcher tests the named cipher: its('ciphers') { should_not eq '/rc4/i' } or: describe ssl(port: 443).ciphers(/rc4/i) do it { shouldnot beenabled } end 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 { shouldnot beenabled } end Supported protocols: `ssl2` `ssl3` `tls1.0` `tls1.1` `tls1.2` `tls1.3`