Addressing review comments, adding documentation

8 files changed, 71 insertions, 4 deletions

diff --git a/.kitchen.yml b/.kitchen.yml
index c9be1b56e7..ed49eb3e57 100644
--- a/.kitchen.yml
+++ b/.kitchen.yml
@@ -6,8 +6,6 @@ driver:
     memory: 4096
   synced_folders:
     - ['.', '/home/vagrant/chef']
-    - ['../ohai', '/home/vagrant/ohai']
-    - ['../triager', '/home/vagrant/triager']
 
 provisioner:
   name: chef_zero
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f93aa4c453..2ff00ab99e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,6 +24,7 @@
 * Update Chef to use RSpec 3.
 * Cleaned up script and execute provider + specs
 * Added deprecation warnings around the use of command attribute in script resources
+* Audit mode feature added - see the RELEASE_NOTES for details
 
 ## 12.0.3
 * [**Phil Dibowitz**](https://github.com/jaymzh):
diff --git a/DOC_CHANGES.md b/DOC_CHANGES.md
index 15f88abdca..9a6c78a524 100644
--- a/DOC_CHANGES.md
+++ b/DOC_CHANGES.md
@@ -6,6 +6,15 @@ Example Doc Change:
 Description of the required change.
 -->
 
+### Experimental Audit Mode Feature
+
+There is a new command_line flag provided for `chef-client`: `--audit-mode`.  This accepts 1 of 3 arguments:
+
+* disabled (default) - Audits are disabled and the phase is skipped.  This is the default while Audit mode is an
+experimental feature.
+* enabled - Audits are enabled and will be performed after the converge phase.
+* audit_only - Audits are enabled and convergence is disabled.  Only audits will be performed.
+
 ### Chef Why Run Mode Ignores Audit Phase
 
 Because most users enable `why_run` mode to determine what resources convergence will update on their system, the audit
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 630aa737df..0c73b7f7c8 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -1,7 +1,59 @@
-# Chef Client Release Notes 12.2.0:
+# Chef Client Release Notes 12.1.0:
 
 # Internal API Changes in this Release
 
+## Experimental Audit Mode Feature
+
+This is a new feature intended to provide _infrastructure audits_.  Chef already allows you to configure your infrastructure
+with code, but there are some use cases that are not covered by resource convergence.  What if you want to check that
+the application Chef just installed is functioning correctly?  If it provides a status page an audit can check this
+and validate that the application has database connectivity.
+
+Audits are performed by leveraging [Serverspec](http://serverspec.org/) and [RSpec](https://relishapp.com/rspec) on the
+node.  As such the syntax is very similar to a normal RSpec spec.
+
+### Syntax
+
+```ruby
+controls "Database Audit" do
+
+  control "postgres package" do
+    it "should not be installed" do
+      expect(package("postgresql")).to_not be_installed
+    end
+  end
+
+  let(:p) { port(111) }
+  control p do
+    it "has nothing listening" do
+      expect(p).to_not be_listening
+    end
+  end
+
+end
+```
+
+Using the example above I will break down the components of an Audit:
+
+* `controls` - This named block contains all the audits to be performed during the audit phase.  During Chef convergence
+ the audits will be collected and ran in a separate phase at the end of the Chef run.  Any `controls` block defined in
+ a recipe that is ran on the node will be performed.
+* `control` - This keyword describes a section of audits to perform.  The name here should either be a string describing
+the system under test, or a [Serverspec resource](http://serverspec.org/resource_types.html).
+* `it` - Inside this block you can use [RSpec expectations](https://relishapp.com/rspec/rspec-expectations/docs) to
+write the audits.  You can use the Serverspec resources here or regular ruby code.  Any raised errors will fail the
+audit.
+
+### Output and error handling
+
+Output from the audit run will appear in your `Chef::Config[:log_location]`.  If an audit fails then Chef will raise
+an error and exit with a non-zero status.
+
+### Further reading
+
+More information about the audit mode can be found in its
+[RFC](https://github.com/opscode/chef-rfc/blob/master/rfc035-audit-mode.md)
+
 # End-User Changes
 
 ## OpenBSD Package provider was added
diff --git a/chef.gemspec b/chef.gemspec
index 43fb3d16fe..52babdc5a1 100644
--- a/chef.gemspec
+++ b/chef.gemspec
@@ -35,6 +35,7 @@ Gem::Specification.new do |s|
 
   s.add_dependency 'plist', '~> 3.1.0'
 
+  # Audit mode requires these, so they are non-developmental dependencies now
   %w(rspec-core rspec-expectations rspec-mocks).each { |gem| s.add_dependency gem, "~> 3.1" }
   s.add_dependency "rspec_junit_formatter", "~> 0.2.0"
   s.add_dependency "serverspec", "~> 2.7"
diff --git a/lib/chef/event_dispatch/base.rb b/lib/chef/event_dispatch/base.rb
index 695e31cf2e..25dd9fd1b2 100644
--- a/lib/chef/event_dispatch/base.rb
+++ b/lib/chef/event_dispatch/base.rb
@@ -229,6 +229,11 @@ class Chef
       def converge_failed(exception)
       end
 
+      ##################################
+      # Audit Mode Events
+      # This phase is currently experimental and these event APIs are subject to change
+      ##################################
+
       # Called before audit phase starts
       def audit_phase_start(run_status)
       end
diff --git a/spec/integration/solo/solo_spec.rb b/spec/integration/solo/solo_spec.rb
index 9500e7a1ca..cc9ba1abb2 100644
--- a/spec/integration/solo/solo_spec.rb
+++ b/spec/integration/solo/solo_spec.rb
@@ -92,7 +92,7 @@ EOM
       # We have a timeout protection here so that if due to some bug
       # run_lock gets stuck we can discover it.
       expect {
-        Timeout.timeout(1200) do
+        Timeout.timeout(120) do
           chef_dir = File.join(File.dirname(__FILE__), "..", "..", "..")
 
           # Instantiate the first chef-solo run
diff --git a/spec/support/audit_helper.rb b/spec/support/audit_helper.rb
index 5744f779fc..70e36f1ad2 100644
--- a/spec/support/audit_helper.rb
+++ b/spec/support/audit_helper.rb
@@ -7,6 +7,7 @@
 # end
 
 # rspec-core did not include a license on Github
+# TODO when this API is exposed publicly from rspec-core, get rid of this copy pasta
 
 # Adding these as writers is necessary, otherwise we cannot set the new configuration.
 # Only want to do this in the specs.