inspec 1.17.0 → 1.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2c165a6b8a6e0ec2ed55a4038e82a3bac56ab80b
-  data.tar.gz: 1a806307865e65cbd266caf0a8f3d0abe2b58257
+  metadata.gz: 9379e53ddea254aaf25d826f7f0c6ca5dc8a0f8f
+  data.tar.gz: 34abc2d25c9ad4531c8f972f929f2f9c52b153fa
 SHA512:
-  metadata.gz: 6b0ed9d55cc66ed12aaa28a51560cd3238970f215d764c56c96a75b329a41d9a05edc6bb2bece49a353b99b011b3168c76067599309d632f7d51b558a8033baa
-  data.tar.gz: 991eb89677b038a066fac3162685db305f807d1dc67cef40742ec8d778cef8ab6c2cce3c94411c9c6265c46744be37d5b2d09b9edfaf2ecec939fa4885c742c6
+  metadata.gz: e79a10bb506d7b6b2f062800a8f70e27456c18dd6c056b5da0c613196ad19b577d00d8836486314fd2773e21740e9507e0479d6b49ea66fabd1e55004ce227b8
+  data.tar.gz: ba859c6e85d244fabb94e3ecb6ec8b9eb83e5de1951c4b0c5c2e04fc06aeddf3fcd4c1b4ed0501a4b02365f181e63456644689f3cf08eca0803cf958065ace20

data/CHANGELOG.md

@@ -1,24 +1,65 @@
 # Change Log
 
-## [1.17.0](https://github.com/chef/inspec/tree/v1.17.0) (2017-03-21)
+## [v1.18.0](https://github.com/chef/inspec/tree/v1.18.0) (2017-03-30)
+[Full Changelog](https://github.com/chef/inspec/compare/v1.17.0...v1.18.0)
+
+**Implemented enhancements:**
+
+- Requesting x509\_certificate and x509\_private\_key [\#1459](https://github.com/chef/inspec/issues/1459)
+- generate profile CLI command [\#410](https://github.com/chef/inspec/issues/410)
+
+**Fixed bugs:**
+
+- YAML file extensions support only \(.yml\) [\#1569](https://github.com/chef/inspec/issues/1569)
+- yum.repo with should\_not exist fails with NoMethodError: undefined method `\[\]' for nil:NilClass [\#1553](https://github.com/chef/inspec/issues/1553)
+
+**Closed issues:**
+
+- port should be\_listening busted in 1.17.0? [\#1602](https://github.com/chef/inspec/issues/1602)
+- inspec fails to install on centos 7 [\#1597](https://github.com/chef/inspec/issues/1597)
+- inspec outputs full hash when testing ini style file option with \[header\] [\#1541](https://github.com/chef/inspec/issues/1541)
+- Add JSON Schema validation [\#884](https://github.com/chef/inspec/issues/884)
+
+**Merged pull requests:**
+
+- Fix port resource for invalid IP address in netstat output [\#1603](https://github.com/chef/inspec/pull/1603) ([adamleff](https://github.com/adamleff))
+- Remove errant puts in inspec habitat CLI command [\#1601](https://github.com/chef/inspec/pull/1601) ([adamleff](https://github.com/adamleff))
+- Add docs for habitat CLI commands [\#1600](https://github.com/chef/inspec/pull/1600) ([adamleff](https://github.com/adamleff))
+- Require Ruby 2.1 [\#1599](https://github.com/chef/inspec/pull/1599) ([adamleff](https://github.com/adamleff))
+- Extend `gem` to take an optional `gem\_binary` [\#1596](https://github.com/chef/inspec/pull/1596) ([nvwls](https://github.com/nvwls))
+- Feature/fix ability to pass in supermarket url [\#1595](https://github.com/chef/inspec/pull/1595) ([rylarson](https://github.com/rylarson))
+- Support vendored profiles in Habitat-packaged profiles [\#1594](https://github.com/chef/inspec/pull/1594) ([adamleff](https://github.com/adamleff))
+- Yum resource fix for non-existent repos and repo info [\#1593](https://github.com/chef/inspec/pull/1593) ([adamleff](https://github.com/adamleff))
+- Fixing www/docs rake tasks [\#1591](https://github.com/chef/inspec/pull/1591) ([adamleff](https://github.com/adamleff))
+- add tag object [\#1590](https://github.com/chef/inspec/pull/1590) ([chris-rock](https://github.com/chris-rock))
+- Support YAML attributes files ending in .yaml [\#1589](https://github.com/chef/inspec/pull/1589) ([mr-exz](https://github.com/mr-exz))
+- Fix Habitat plan for nokogiri support [\#1587](https://github.com/chef/inspec/pull/1587) ([adamleff](https://github.com/adamleff))
+- x509\_certificate and key\_rsa resource [\#1567](https://github.com/chef/inspec/pull/1567) ([chris-rock](https://github.com/chris-rock))
+- implement JSON schema for `inspec exec` json outputs [\#1564](https://github.com/chef/inspec/pull/1564) ([arlimus](https://github.com/arlimus))
+- Provide a method-based accessor for SimpleConfig hashes [\#1544](https://github.com/chef/inspec/pull/1544) ([adamleff](https://github.com/adamleff))
+
+## [v1.17.0](https://github.com/chef/inspec/tree/v1.17.0) (2017-03-21)
 [Full Changelog](https://github.com/chef/inspec/compare/v1.16.1...v1.17.0)
 
 **Implemented enhancements:**
 
+- Calendar for Line Chart [\#1558](https://github.com/chef/inspec/issues/1558)
 - Need better error message for improper inspec.yml formatting [\#1549](https://github.com/chef/inspec/issues/1549)
 
 **Fixed bugs:**
 
 - cannot load such file -- nokogiri [\#1562](https://github.com/chef/inspec/issues/1562)
 - Failure to parse tcp6 URI [\#1521](https://github.com/chef/inspec/issues/1521)
-- json resource array index access not working [\#1560](https://github.com/chef/inspec/issues/1560)
 
 **Closed issues:**
 
+- json resource array index access not working [\#1560](https://github.com/chef/inspec/issues/1560)
 - Crontab regex matching [\#1526](https://github.com/chef/inspec/issues/1526)
 
 **Merged pull requests:**
 
+- Move simulator gems to www [\#1585](https://github.com/chef/inspec/pull/1585) ([adamleff](https://github.com/adamleff))
+- release 1.17.0 [\#1583](https://github.com/chef/inspec/pull/1583) ([adamleff](https://github.com/adamleff))
 - Fix omnibus configuration [\#1579](https://github.com/chef/inspec/pull/1579) ([adamleff](https://github.com/adamleff))
 - moving the nokogiri reference into the gemspec file [\#1576](https://github.com/chef/inspec/pull/1576) ([jkerry](https://github.com/jkerry))
 - Hide Event Feature on Homepage [\#1563](https://github.com/chef/inspec/pull/1563) ([hannah-radish](https://github.com/hannah-radish))

data/Gemfile

@@ -19,6 +19,7 @@ group :test do
   gem 'mocha', '~> 1.1'
   gem 'ruby-progressbar', '~> 1.8'
   gem 'webmock', '~> 2.3.2'
+  gem 'jsonschema', '~> 2.0.2'
 end
 
 group :integration do

data/Rakefile

@@ -7,7 +7,6 @@ require 'rake/testtask'
 require 'rubocop/rake_task'
 require_relative 'tasks/docs'
 require_relative 'tasks/maintainers'
-require_relative 'tasks/www'
 
 # Rubocop
 desc 'Run Rubocop lint checks'
@@ -186,3 +185,20 @@ task :release_habitat do
     puts "--> #{cmd}"
     sh('sh', '-c', cmd)
 end
+
+desc 'Release the website [deprecated]'
+task :www do
+  puts 'The Rake tasks for releasing the website are now in the www/ directory.'
+  puts 'Run `cd www` and then `rake --tasks` for a list of the www-related tasks available.'
+  exit(1)
+end
+
+namespace :www do
+  desc 'Release the website [deprecated]'
+  task :release do
+    puts 'The Rake tasks for releasing the website are now in the www/ directory.'
+    puts 'Run `cd www` and then `rake --tasks` for a list of the www-related tasks available.'
+    exit(1)
+  end
+end
+

data/docs/habitat.md

@@ -0,0 +1,192 @@
+---
+title: InSpec Integration with Habitat
+---
+
+# Habitat Integration
+
+InSpec provides an easy method to create an executable Habitat package for an InSpec profile. When run via the Habitat Supervisor, the package will run InSpec with your profile and write out its findings to a JSON file. This provides the ability to ship your compliance controls alongside your Habitat-packaged application and continuously run InSpec, providing you *Continuous Compliance.*
+
+## What is Habitat?
+
+Habitat by Chef is our new Application Automation tool that aims to make it easy, safe, and fast to build, deploy, and manage applications. From build dependencies, runtime dependencies, dynamic configuration, and service discovery (just to name a few), Habitat packages the automation with the application instead of relying on an underlying platform.
+
+To learn more about Habitat and try our demos and tutorials, visit [https://www.habitat.sh](https://www.habitat.sh).
+
+## Using the Habitat Integration
+
+After creating a Habitat package for an InSpec profile (see CLI commands below) and uploading the package to a Habitat Depot or manually distributing to a host, start the Habitat Supervisor with your package:
+
+```bash
+hab start adamleff/inspec-profile-frontend1
+```
+
+The Habitat Supervisor will install InSpec and execute your profile in a loop. By default, the loop runs every 300 seconds but can be changed via the `sleep_time` configuration value:
+
+```bash
+HAB_INSPEC_PROFILE_FRONTEND1="sleep_time = 60" hab start adamleff/inspec-profile-frontend1
+```
+
+The Habitat Supervisor will display output like this:
+
+```
+hab start adamleff/inspec-profile-frontend1
+∵ Missing package for core/hab-sup/0.17.0
+» Installing core/hab-sup/0.17.0
+↓ Downloading core/hab-sup/0.17.0/20170214235450
+    1.68 MB / 1.68 MB - [=========================================================================] 100.00 % 7.43 MB/s
+
+... more Habitat output here ...
+
+hab-sup(MN): Starting adamleff/inspec-profile-frontend1/0.1.0/20170328173005
+hab-sup(CS): adamleff/inspec-profile-frontend1/0.1.0/20170328173005 is not installed
+↓ Downloading adamleff-20160617201047 public origin key
+    79 B / 79 B | [===============================================================================] 100.00 % 2.64 MB/s
+☑ Cached adamleff-20160617201047 public origin key
+↓ Downloading chef/inspec/1.17.0/20170321214949
+    16.93 MB / 16.93 MB / [======================================================================] 100.00 % 10.49 MB/s
+
+... more Habitat output here ...
+
+★ Install of adamleff/inspec-profile-frontend1/0.1.0/20170328173005 complete with 9 new packages installed.
+hab-sup(MR): Butterfly Member ID d9bd761e18c144469d755b1b97406eb2
+hab-sup(MR): Starting butterfly on 0.0.0.0:9638
+hab-sup(MR): Starting http-gateway on 0.0.0.0:9631
+inspec-profile-frontend1.default(SR): Initializing
+inspec-profile-frontend1.default(SV): Starting process as user=hab, group=hab
+inspec-profile-frontend1.default(O): Executing InSpec for adamleff/inspec-profile-frontend1
+inspec-profile-frontend1.default(O): InSpec run completed successfully.
+inspec-profile-frontend1.default(O): sleeping for 300 seconds
+```
+
+The above sample output shows the supervisor starting, downloading the necessary dependencies for the supervisor and the InSpec profile, and then shows the supervisor running InSpec successfully.
+
+InSpec will write a JSON file in the `${svc_var_path}/inspec_results` directory containing the results of the last InSpec run. For example, for the `adamleff/inspec-profile-frontend1` package, the InSpec results will be at:
+
+```
+/hab/svc/inspec-profile-frontend1/var/inspec_results/inspec-profile-frontend1.json
+```
+
+## InSpec Habitat CLI Commands
+
+### inspec habitat profile create
+
+Create a Habitat package for an InSpec profile. InSpec will validate the profile, fetch and vendor any dependencies (if necessary), and build the Habitat package with a dependency on the latest InSpec. The resulting package will be saved to the current working directory.
+
+The package file will be named:
+
+```
+HABITAT_ORIGIN-inspec-profile-PROFILE_NAME-PROFILE_VERSION-BUILD_ID-x86_64-linux.hart
+```
+
+For example:
+
+```
+adamleff-inspec-profile-frontend1-0.1.0-20170328173005-x86_64-linux.hart
+```
+
+#### Syntax
+
+```bash
+inspec habitat profile create PROFILE_DIRECTORY
+```
+
+Example:
+
+```bash
+inspec habitat profile create ~/profiles/frontend1
+```
+
+### inspec habitat profile create
+
+Create a Habitat package for an InSpec profile. InSpec will validate the profile, fetch and vendor any dependencies (if necessary), and build the Habitat package with a dependency on the latest InSpec. The resulting package will be saved to the current working directory.
+
+The package can then be manually uploaded to a Habitat Depot or manually distributed to a host and installed via `hab pkg install`.
+
+The package file will be named:
+
+```
+HABITAT_ORIGIN-inspec-profile-PROFILE_NAME-PROFILE_VERSION-BUILD_ID-x86_64-linux.hart
+```
+
+For example:
+
+```
+adamleff-inspec-profile-frontend1-0.1.0-20170328173005-x86_64-linux.hart
+```
+
+#### Syntax
+
+```bash
+inspec habitat profile create PROFILE_DIRECTORY
+```
+
+#### Example
+
+```bash
+inspec habitat profile create ~/profiles/frontend1
+```
+
+#### Example Output
+
+```
+$ habitat profile create ~/profiles/frontend1
+[2017-03-28T13:29:32-04:00] INFO: Creating a Habitat artifact for profile: /Users/aleff/profiles/frontend1
+[2017-03-28T13:29:32-04:00] INFO: Checking to see if Habitat is installed...
+[2017-03-28T13:29:32-04:00] INFO: Copying profile contents to the work directory...
+[2017-03-28T13:29:32-04:00] INFO: Generating Habitat plan at /var/folders/v5/z54gb76j2rs3wrn65hmtyf1r0000gp/T/inspec-habitat-exporter20170328-4932-kg2ltd/habitat/plan.sh...
+[2017-03-28T13:29:32-04:00] INFO: Generating a Habitat run hook at /var/folders/v5/z54gb76j2rs3wrn65hmtyf1r0000gp/T/inspec-habitat-exporter20170328-4932-kg2ltd/habitat/hooks/run...
+[2017-03-28T13:29:32-04:00] INFO: Generating Habitat's default.toml configuration...
+[2017-03-28T13:29:32-04:00] INFO: Building our Habitat artifact...
+   hab-studio: Destroying Studio at /hab/studios/src (default)
+   hab-studio: Creating Studio at /hab/studios/src (default)
+   hab-studio: Importing adamleff secret origin key
+» Importing origin key from standard input
+★ Imported secret origin key adamleff-20160617201047.
+» Installing core/hab-backline
+↓ Downloading core/hab-backline/0.19.0/20170311034116
+    2.17 KB / 2.17 KB / [=========================================================================] 100.00 % 4.33 MB/s
+
+... more Habitat output here...
+
+[2017-03-28T13:30:18-04:00] INFO: Copying artifact to /Users/aleff...
+```
+
+### inspec habitat profile upload
+
+Create and then upload a Habitat package for an InSpec profile. Like the `inspec habitat profile create` command, InSpec will validate the profile, fetch and vendor any dependencies (if necessary), and build the Habitat package with a dependency on the latest InSpec. However, instead of saving the package locally to the workstation, InSpec will upload it to the depot defined in the `HAB_DEPOT` environment variable. If `HAB_DEPOT` is not defined, the package will be uploaded to the public Habitat depot at [https://app.habitat.sh](https://app.habitat.sh).
+
+#### Syntax
+
+```bash
+inspec habitat profile upload PROFILE_DIRECTORY
+```
+
+#### Example
+
+```bash
+inspec habitat profile upload ~/profiles/frontend1
+```
+
+#### Example Output
+```
+[2017-03-28T13:29:32-04:00] INFO: Creating a Habitat artifact for profile: /Users/aleff/profiles/frontend1
+[2017-03-28T13:29:32-04:00] INFO: Checking to see if Habitat is installed...
+[2017-03-28T13:29:32-04:00] INFO: Copying profile contents to the work directory...
+[2017-03-28T13:29:32-04:00] INFO: Generating Habitat plan at /var/folders/v5/z54gb76j2rs3wrn65hmtyf1r0000gp/T/inspec-habitat-exporter20170328-4932-kg2ltd/habitat/plan.sh...
+[2017-03-28T13:29:32-04:00] INFO: Generating a Habitat run hook at /var/folders/v5/z54gb76j2rs3wrn65hmtyf1r0000gp/T/inspec-habitat-exporter20170328-4932-kg2ltd/habitat/hooks/run...
+[2017-03-28T13:29:32-04:00] INFO: Generating Habitat's default.toml configuration...
+[2017-03-28T13:29:32-04:00] INFO: Building our Habitat artifact...
+   hab-studio: Destroying Studio at /hab/studios/src (default)
+   hab-studio: Creating Studio at /hab/studios/src (default)
+   hab-studio: Importing adamleff secret origin key
+» Importing origin key from standard input
+★ Imported secret origin key adamleff-20160617201047.
+» Installing core/hab-backline
+↓ Downloading core/hab-backline/0.19.0/20170311034116
+    2.17 KB / 2.17 KB / [=========================================================================] 100.00 % 4.33 MB/s
+
+... more Habitat output here...
+
+[2017-03-28T13:30:18-04:00] INFO: Uploading the Habitat artifact to our Depot...
+[2017-03-28T13:30:23-04:00] INFO: Upload complete!
+```

data/docs/resources/gem.md.erb

@@ -10,13 +10,14 @@ Use the `gem` InSpec audit resource to test if a global Gem package is installed
 
 A `gem` resource block declares a package and (optionally) a package version:
 
-    describe gem('gem_package_name') do
+    describe gem('gem_package_name', 'gem_binary') do
       it { should be_installed }
     end
 
 where
 
 * `('gem_package_name')` must specify a Gem package, such as `'rubocop'`
+* `('gem_binary')` can specify the path to a non-default gem binary, defaults to `'gem'`
 * `be_installed` is a valid matcher for this resource
 
 ## Matchers
@@ -71,3 +72,21 @@ The following examples show how to use this InSpec audit resource.
     describe gem('rubocop') do
       it { should_not be_installed }
     end
+
+### Verify that a gem package is installed in an omnibus environment
+
+    describe gem('pry', '/opt/ruby-2.3.1/embedded/bin/gem') do
+      it { should be_installed }
+    end
+
+### Verify that a gem package is installed in a chef omnibus environment
+
+    describe gem('chef-sugar', :chef) do
+      it { should be_installed }
+    end
+
+### Verify that a gem package is installed in a chef-server omnibus environment
+
+    describe gem('knife-backup', :chef_server) do
+      it { should be_installed }
+    end

data/docs/resources/key_rsa.md

@@ -0,0 +1,70 @@
+---
+title: The key_rsa Resource
+---
+
+# key_rsa
+
+Use the `key_rsa` InSpec audit resource to test RSA public/private keypairs.
+
+This resource is mainly useful when used in conjunction with the x509_certificate resource but it can also be used for checking SSH keys.
+
+
+## Syntax
+
+An `key_rsa` resource block declares a `key file` to be tested.
+
+    describe key_rsa('mycertificate.key') do
+      it { should be_private }
+      it { should be_public }
+      its('public_key') { should match "-----BEGIN PUBLIC KEY-----\n3597459df9f3982" }
+      its('key_length') { should eq 2048 }
+    end
+
+You can use an optional passphrase with `key_rsa`
+
+    describe key_rsa('mycertificate.key', 'passphrase') do
+      it { should be_private }
+    end
+
+## Supported Properties
+
+### public?
+
+To verify if a key is public use the following:
+
+    describe key_rsa('/etc/pki/www.mywebsite.com.key') do
+      it { should be_public }
+    end
+
+### public_key (String)
+
+The `public_key` property returns the public part of the RSA key pair
+
+    describe key_rsa('/etc/pki/www.mywebsite.com.key') do
+      its('public_key') { should match "-----BEGIN PUBLIC KEY-----\n3597459df9f3982......" }
+    end
+
+### private?
+
+This property verifies that the key includes a private key:
+
+    describe key_rsa('/etc/pki/www.mywebsite.com.key') do
+      it { should be_private }
+    end
+
+
+### private_key (String)
+
+The `private_key` property returns the private key or the RSA key pair.
+
+    describe key_rsa('/etc/pki/www.mywebsite.com.key') do
+      its('private_key') { should match "-----BEGIN RSA PRIVATE KEY-----\nMIIJJwIBAAK......" }
+    end
+
+### key_length
+
+The `key_length` property allows testing the number of bits in the key pair.
+
+    describe key_rsa('/etc/pki/www.mywebsite.com.key') do
+      its('key_length') { should eq 2048 }
+    end

data/docs/resources/x509_certificate.md

@@ -0,0 +1,146 @@
+---
+title: The x509_certificate Resource
+---
+
+# x509_certificate
+
+Use the `x509_certificate` InSpec audit resource to test the fields and validity of an x.509 certificate.
+
+X.509 certificates use public/private key pairs to sign and encrypt documents
+or communications over a network. They may also be used for authentication.
+
+Examples include SSL certificates, S/MIME certificates and VPN authentication
+certificates.
+
+## Syntax
+
+An `x509_certificate` resource block declares a certificate `key file` to be tested.
+
+    describe x509_certificate('mycertificate.pem') do
+      its('validity_in_days') { should be > 30 }
+    end
+
+## Supported Properties
+
+### subject.XX
+
+`subject` property makes it easier to access individual subject elements.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('subject.CN') { should eq "www.mywebsite.com" }
+    end
+
+### subject_dn (String)
+
+The `subject_dn` string returns the distinguished name of the subject field. It contains several fields separated by forward slashes. The field identifiers are the same ones used by OpenSSL to generate CSR's and certs. Use `subject.XX` instead to access the parsed version.
+
+e.g. `/C=US/L=Seattle/O=Chef Software Inc/OU=Chefs/CN=Richard Nixon`
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('subject_dn') { should match "CN=www.mywebsite.com" }
+    end
+
+### issuer.XX
+
+`issuer` makes it easier to access individual issuer elements.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('issuer.CN') { should eq "Acme Trust CA" }
+    end
+
+### issuer_dn (String)
+
+The `issuer_dn` is the distinguished name from a CA (certificate authority) during the
+certificate signing process. It describes which authority is guaranteeing the
+identity of our certificate.
+
+e.g. `/C=US/L=Seattle/CN=Acme Trust CA/emailAddress=support@acmetrust.org`
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('issuer_cn') { should match "CN=Acme Trust CA" }
+    end
+
+### public_key (String)
+
+The `public_key` property returns a base64 encoded public key in PEM format.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('public_key') { should match "-----BEGIN PUBLIC KEY-----\nblah blah blah..." }
+    end
+
+### key_length (Integer)
+
+The `key_length` property calculates the number of bits in the public key.
+More bits increase security, but at the cost of speed and in extreme cases, compatibility.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('key_length') { should be 2048 }
+    end
+
+### signature_algorithm (String)
+
+The `signature_algorithm` property describes which hash function was used by the CA to
+sign the certificate.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('signature_algorithm') { should be 'sha256WithRSAEncryption' }
+    end
+
+
+### validity_in_days (Float)
+
+The `validity_in_days` property can be used to check that certificates are not in
+danger of expiring soon.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('validity_in_days') { should be > 30 }
+    end
+
+### not_before and not_after (Time)
+
+The `not_before` and `not_after` properties expose the start and end dates of certificate
+validity. They are exposed as ruby Time class so that date arithmetic can be easily performed.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('not_before') { should be <= Time.utc.now }
+      its('not_after')  { should be >= Time.utc.now }
+    end
+
+### serial (Integer)
+
+The `serial` property exposes the serial number of the certificate. The serial number is set by the CA during the signing process and should be unique within that CA.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('serial') { should eq 9623283588743302433 }
+    end
+
+### version (Integer)
+
+The `version` property exposes the certificate version.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('version') { should eq 2 }
+    end
+
+### extensions (Hash)
+
+The `extensions` hash property is mainly used to determine what the certificate can be used for.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      # Check what extension categories we have
+      its('extensions') { should include 'keyUsage' }
+      its('extensions') { should include 'extendedKeyUsage' }
+      its('extensions') { should include 'subjectAltName' }
+
+      # Check examples of basic 'keyUsage'
+      its('extensions.keyUsage') { should include 'Digital Signature' }
+      its('extensions.keyUsage') { should include 'Non Repudiation' }
+      its('extensions.keyUsage') { should include 'Data Encipherment' }
+
+      # Check examples of newer 'extendedKeyUsage'
+      its('extensions.extendedKeyUsage') { should include 'TLS Web Server Authentication' }
+      its('extensions.extendedKeyUsage') { should include 'Code Signing' }
+
+      # Check examples of 'subjectAltName'
+      its('extensions.subjectAltName') { should include 'email:support@chef.io' }
+    end