Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms

Select Status

RSS

audit (74) Versions 2.0.0

Allows for fetching and executing compliance profiles, and reporting their results

Policyfile
Berkshelf
Knife
cookbook 'audit', '= 2.0.0', :supermarket
cookbook 'audit', '= 2.0.0'
knife supermarket install audit
knife supermarket download audit
README
Dependencies
Changelog
Quality 100%

audit cookbook

Cookbook Version Build Status

The audit cookbook allows you to run InSpec profiles as part of a Chef Client run. It downloads configured profiles from various sources like Chef Compliance, Chef Supermarket or Git and reports audit runs to Chef Compliance or Chef Visibility.

Version 2.0 of the audit cookbook is based on an idea from Michael Hedgpeth. Under the hood it uses Chef handler instead of Chef resources now.

NOTE: The current readme refers to unreleased audit cookbook 2.0. Documentation for 1.x is available (here)[https://github.com/chef-cookbooks/audit/blob/v1.1.0/README.md]

Requirements

Chef

  • Chef Client >=12.5.1

Chef Compliance and InSpec

Using the inspec_version attribute, please use the following InSpec version based on your Chef Compliance version:

Chef Compliance version InSpec version Audit Cookbook version
Less or equal to 1.1.23 0.20.1 0.7.0
Greater than 1.1.23 Greater or equal to 0.22.1 0.8.0
Greater or equal to 1.6.8 Greater or equal to 1.2.0 1.0.2

You can see all publicly available InSpec versions here

Overview

The audit support three scenarios:

Chef Server Integration

The first scenario requires at least Chef Compliance 1.0 and the Chef Server extensions for Compliance. The architecture looks as following:

 ┌──────────────────────┐    ┌──────────────────────┐    ┌─────────────────────┐
 │     Chef Client      │    │     Chef Server      │    │   Chef Compliance   │
 │                      │    │                      │    │                     │
 │ ┌──────────────────┐ │    │                      │    │                     │
 │ │                  │◀┼────┼──────────────────────┼────│  Profiles           │
 │ │  audit cookbook  │ │    │                      │    │                     │
 │ │                  │─┼────┼──────────────────────┼───▶│  Reports            │
 │ └──────────────────┘ │    │                      │    │                     │
 │                      │    │                      │    │                     │
 └──────────────────────┘    └──────────────────────┘    └─────────────────────┘

Chef Compliance Integration

The second scenario supports a direct connection with Chef Compliance. It also supports chef-solo mode.

 ┌──────────────────────┐                                ┌─────────────────────┐
 │     Chef Client      │                                │   Chef Compliance   │
 │                      │                                │                     │
 │ ┌──────────────────┐ │                                │                     │
 │ │                  │◀┼────────────────────────────────│  Profiles           │
 │ │  audit cookbook  │ │                                │                     │
 │ │                  │─┼───────────────────────────────▶│  Reports            │
 │ └──────────────────┘ │                                │                     │
 │                      │                                │                     │
 └──────────────────────┘                                └─────────────────────┘

Chef Visibility Integration

The third scenario supports direct reporting to Chef Visibility. It also supports chef-solo mode.

 ┌──────────────────────┐                                ┌─────────────────────┐
 │     Chef Client      │     ┌───────────────────────┐  │   Chef Visibility   │
 │                      │  ┌──│ Profiles(Supermarket, │  │                     │
 │ ┌──────────────────┐ │  │  │ Github, local, etc)   │  │                     │
 │ │                  │◀┼──┘  └───────────────────────┘  │                     │
 │ │  audit cookbook  │ │                                │                     │
 │ │                  │─┼───────────────────────────────▶│  Reports            │
 │ └──────────────────┘ │                                │                     │
 │                      │                                │                     │
 └──────────────────────┘                                └─────────────────────┘

Usage

The audit cookbook needs to be configured for each node where the chef-client runs. The audit cookbook can be reused for all nodes, all node-specific configuration is done via Chef attributes.

Upload cookbook to Chef Server

The audit cookbook is available at Chef Supermarket. This allows you to reuse your existing workflow for managing cookbooks in your runlist.

If you want to upload the cookbook from git, use the following commands:

mkdir chef-cookbooks
cd chef-cookbooks
git clone https://github.com/chef-cookbooks/audit
cd ..
knife cookbook upload audit -o ./chef-cookbooks

Please ensure that chef-cookbooks is the parent directory of audit cookbook.

Reporting to Chef Compliance via Chef Server

If you want the audit cookbook to converge and retrieve compliance profiles through the Chef Server, set the collector and profiles attribute.

This requires your Chef Server to be integrated with the Chef Compliance server using this guide.

Configure node

Once the cookbook is available in Chef Server, you need to add the audit::default recipe to the run-list of each node. The profiles are selected via the node['audit']['profiles'] attribute. For example you can define the attributes in a role or environment file like this:

node.default['audit']['profiles'].push("path": "#{PROFILES_PATH}/mylinux-failure-success")

"audit" => {
  "collector" => "chef-server",
  "inspec_version" => "1.2.1",
  "profiles" => [
    # profile from Chef Compliance
    {
      "name": "linux",
      "compliance": "base/linux"
    },
    # profile from supermarket
    # note: If reporting to Compliance, the Supermarket profile needs to be uploaded to Chef Compliance first
    {
      "name": "ssh",
      "supermarket": "hardening/ssh-hardening"
    },
    # local Windows path
    {
      "name": "brewinc/win2012_audit",
      # filesystem path
      "path": "E:/profiles/win2012_audit"
    },
    # github
    {
      "name": "ssl",
      "git": "https://github.com/dev-sec/ssl-benchmark.git"
    },
    # url
    {
      "name": "ssh",
      "url": "https://github.com/dev-sec/tests-ssh-hardening/archive/master.zip"
    }
  ]
}

You can also configure in a policyfile like this:

default['audit'] = {
  'collector' => 'chef-server',
  'profiles' => [
    {
      "name": "linux",
      "compliance": "base/linux"
    },
    {
      "name": "ssh",
      "compliance": "base/ssh"
    }
  ]
}

Direct reporting to Chef Compliance

If you want the audit cookbook to directly report to Chef Compliance, set the collector, server, owner, refresh_token and profiles attributes.

  • collector - 'chef-compliance' to report to Chef Compliance
  • server - url of Chef Compliance server with /api
  • owner - Chef Compliance user or organization that will receive this scan report
  • refresh_token - refresh token for Chef Compliance API (https://github.com/chef/inspec/issues/690)
    • note: A UI logout revokes the refresh_token. Workaround by logging in once in a private browser session, grab the token and then close the browser without logging out
  • insecure - a true value will skip the SSL certificate verification when retrieving access token. Default value is false
"audit": {
  "collector": "chef-compliance",
  "server": "https://compliance-fqdn/api",
  "owner": "my-comp-org",
  "refresh_token": "5/4T...g==",
  "insecure": false,
  "profiles": [
    {
      "name": "windows",
      "compliance": "base/windows"
    }
  ]
}

Instead of a refresh token, it is also possible to use a token that expires in 12h after creation .

"audit": {
  "collector": "chef-compliance",
  "server": "https://compliance-fqdn/api",
  "owner": "my-comp-org",
  "token": "eyJ........................YQ",
  "profiles": [
    {
      "name": "windows",
      "compliance": "base/windows"
    }
  ]
}

Direct reporting to Chef Visibility

If you want the audit cookbook to directly report to Chef Visibility, set the collector attribute to 'chef-visibility'. Also specify where to retrieve the profiles from.

This method is sending the report using the data_collector.server_url and data_collector.token, defined in client.rb. It requires inspec version 0.27.1 or greater.

"audit": {
  "collector": "chef-visibility",
  "profiles": [
    {
      "name": "brewinc/tmp_compliance_profile",
      "url": "https://github.com/nathenharvey/tmp_compliance_profile"
    }
  ]
}

Profile Upload to Compliance Server

In order to support build cookbook mode, the compliance_profile resource has an upload action that allows uploading a compressed
inspec compliance profile to the Compliance Server.

Simply include the upload recipe in the run_list, with attribute overrides for the audit hash like so:

audit: {
  server: 'https://compliance-server.test/api'
  collector: 'chef-compliance',
  refresh_token: '21/XMEK3...',
  profiles: [
   {
      'name': 'admin/ssh2',
      'path': '/some/base_ssh.tar.gz'
    }
  ]
}

Write to file on disk

To write the report to a file on disk, simply set the collector to 'json-file' like so:

audit: {
  collector: 'json-file',
  profiles: [
   {
      'name': 'admin/ssh2',
      'path': '/some/base_ssh.tar.gz'
    }
  ]
}

Multiple reporters

To enable multiple reporters, simply define multiple reporters with all the necessary information
for each one. For example, to report to chef-compliance and write to json file on disk:

"audit": {
  "collector": [ "chef-compliance", "json-file" ]
  "server": "https://compliance-fqdn/api",
  "owner": "my-comp-org",
  "refresh_token": "5/4T...g==",
  "insecure": false,
  "profiles": [
    {
      "name": "windows",
      "compliance": "base/windows"
    }
  ]
}

Relationship with Chef Audit Mode

The following tables compares the Chef Client audit mode with this audit cookbook.

audit mode audit cookbook
Works with Chef Compliance No Yes
Execution Engine Serverspec InSpec
Execute InSpec Compliance Profiles No Yes
Execute tests embedded in Chef recipes Yes No

Eventually the audit cookbook will replace audit mode. The only drawback is that you will not be able to execute tests in Chef recipes, but since you will be running these tests in production, you will want to have a straightforward, consistent process by which you include these tests throughout your development lifecycle. Within Chef Compliance, this is a profile.

Migrating from audit mode to audit cookbook:

We will improve the migration and help to ease the process and to reuse existing audit mode test as much as possible. At this point of time, an existing audit-mode test like:

control_group 'Check SSH Port' do
  control 'SSH' do
    it 'should be listening on port 22' do
      expect(port(22)).to be_listening
    end
  end
end

can be re-written in InSpec as follows:

# rename `control_group` to `control` and use a unique identifier
control "blog-1" do
  title 'Check SSH Port'  # add the title from `control_group`
  # rename the old `control` to `describe`
  describe 'SSH' do
    it 'should be listening on port 22' do
      expect(port(22)).to be_listening
    end
  end
end

or even simplified to:

control "blog-1" do
  title 'SSH should be listening on port 22'
  describe port(22) do
    it { should be_listening }
  end
end

Interval Settings

If you have long running audit profiles that you don't wish to execute on every chef-client run,
you can enable an interval:

default['audit']['interval']['enabled'] = true
default['audit']['interval']['time'] = 1440 # once a day, the default value

The time attribute is in minutes.

You can enable the interval and set the interval time, along with your desired profiles,
in an environment or role like this:

  "audit": {
    "profiles": [
      {
        "name": "ssh",
        "compliance": "base/ssh"
      },
      {
        "name": "linux",
        "compliance": "base/linux"
      }
    ],
    "interval": {
      "enabled": true,
      "time": 1440
    }
  }

Alternate Source Location for inspec Gem

If you are not able or do not wish to pull the inspec gem from rubygems.org,
you may specify an alternate source using:

# URI to alternate gem source (e.g. http://gems.server.com or filesytem location)
# root of location must host the *specs.4.8.gz source index
default['audit']['inspec_gem_source'] = 'http://internal.gem.server.com/gems'

Please note that all dependencies to the inspec gem must also be hosted in this location.

Troubleshooting

Please refer to TROUBLESHOOTING.md.

Please let us know if you have any issues, we are happy to help.

License

Author: Stephan Renatus (srenatus@chef.io)
Author: Christoph Hartmann (chartmann@chef.io)
Copyright: Copyright (c) 2015 Chef Software Inc.
License: Apache License, Version 2.0

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Change Log

v2.0.0 (2016-11-04)

Full Changelog

Closed issues:

  • Cannot run profiles from Supermarket #139
  • version 2.0.0 reporting resources updated #138
  • inspec_version attribute specified twice #137
  • README.md "Upload cookbook to Chef Server" #136
  • Remove temporary report file #132
  • Add Chef Server authentication support #129
  • Add unit tests #128
  • JSON file reporter #126
  • Implement RFC: Harmonize profile location targets #118
  • Features missing from 2.0.0 #116
  • Implement reporting as InSpec plugin #111
  • Harmonize audit cookbook profile fetcher with InSpec fetchers #110
  • profile scan is reported every chef-client run even if compliance_profile resource wasn't executed #102
  • Timing issues during report aggregation #81
  • audit cookbook compliance run and report should not report converge #70
  • quiet should control whether converge is reported by Chef #65
  • Node information sent to Compliance after first audit run are not accurate #40
  • 403 Forbidden #21

Merged pull requests:

v1.1.0 (2016-10-18)

Full Changelog

Closed issues:

  • cookbook in master fails to converge #108
  • Interval setting is not working properly #101

Merged pull requests:

v1.0.2 (2016-10-12)

Full Changelog

Merged pull requests:

  • Fix bug when counting total failed controls in json format #106 (alexpop)

v1.0.1 (2016-10-06)

Full Changelog

Merged pull requests:

  • Use the new method to retrieve access tokens and fix total_failed bug #103 (alexpop)

v1.0.0 (2016-09-28)

Full Changelog

Closed issues:

  • Update to InSpec 1.0 #98
  • Some tests against windows machines will fail with winrm unitialized constant errors #94
  • Gzip error executing on windows host #93

Merged pull requests:

v0.14.4 (2016-09-06)

Full Changelog

Merged pull requests:

v0.14.3 (2016-08-25)

Full Changelog

Merged pull requests:

v0.14.2 (2016-08-16)

Full Changelog

Closed issues:

  • Changelog documentation Diff Link error #66
  • we not use inspec progress formatter #11

Merged pull requests:

v0.14.1 (2016-08-15)

Full Changelog

Merged pull requests:

  • ChefCompliance collector fix #75 (alexpop)
  • Update changelog generator task to be native rake task #74 (brentm5)

v0.14.0 (2016-08-12)

Full Changelog

Merged pull requests:

  • removing requirement for setting chef server url #73 (jeremymv2)
  • Add collector attribute and visibility reporting #72 (chris-rock)

v0.13.1 (2016-06-27)

Full Changelog

Merged pull requests:

v0.13.0 (2016-06-22)

Full Changelog

Closed issues:

  • audit cookbook should not report a converge #23

Merged pull requests:

  • Merged interval functionality into default.rb recipe, updated documentation, gave quiet default #64 (mhedgpeth)

v0.12.0 (2016-06-09)

Full Changelog

Merged pull requests:

v0.11.0 (2016-06-09)

Full Changelog

Merged pull requests:

v0.10.0 (2016-06-01)

Full Changelog

Merged pull requests:

v0.9.1 (2016-05-26)

Full Changelog

Closed issues:

  • Reports are not displayed in Chef Compliance #52
  • Cookbook issue with Windows path #48
  • Report to Chef Compliance directly #45

Merged pull requests:

v0.9.0 (2016-05-25)

Full Changelog

Closed issues:

  • Provide support for additional profile hosting sources #49
  • Scan reports showing up as "Skipped" in the Compliance server UI #46

Merged pull requests:

v0.8.0 (2016-05-18)

Full Changelog

Closed issues:

  • Compliance results no longer reports back to Chef Compliance with latest version of inspec #41

Merged pull requests:

v0.7.0 (2016-05-13)

Full Changelog

Closed issues:

  • Undefined method 'path' for nil:NilClass #39
  • Support chef-client < 12.5.1 #30
  • standalone Compliance report #12
  • we should use the latest inspec version by default #8

Merged pull requests:

v0.6.0 (2016-05-03)

Full Changelog

Merged pull requests:

  • fix: use_ssl value has changed error #37 (jeremymv2)
  • Add profile name validation and unit tests #36 (alexpop)
  • Adding an interval check, if you don't want to run every time #17 (spuranam)

v0.5.1 (2016-04-27)

Full Changelog

Merged pull requests:

  • Prevent null pointer when profile cannot be downloaded #35 (alexpop)

v0.5.0 (2016-04-25)

Full Changelog

Closed issues:

  • add option to fail chef run, if the audit failed #3

Merged pull requests:

  • Make inspec_version a cookbook attribute and default it to latest #33 (alexpop)
  • update bundler #32 (chris-rock)
  • update README.md with client version requirement #29 (jeremymv2)

v0.4.4 (2016-04-22)

Full Changelog

Merged pull requests:

v0.4.3 (2016-04-20)

Full Changelog

Merged pull requests:

  • chef-compliance profiles changes require a new ver of inspec #28 (alexpop)
  • Add our github templates #27 (tas50)
  • failing converge if any audits failed #25 (jeremymv2)
  • Misc updates #24 (tas50)
  • adding ability to handle offline compliance server #22 (jeremymv2)

v0.3.3 (2016-04-05)

Full Changelog

Merged pull requests:

  • Use move to avoid cross-device error #19 (alexpop)

v0.3.2 (2016-04-04)

Full Changelog

Merged pull requests:

  • Bump to 0.3.2, testing cookbook release #18 (alexpop)

v0.3.1 (2016-04-01)

Closed issues:

  • Do not crash default recipe, if node['audit'] is not defined #4
  • add default recipe that reads profiles from attributes #1

Merged pull requests:

  • Update readme and update version to test stove cookbook update #16 (alexpop)
  • Update github links and change to version 0.3.0 #15 (alexpop)
  • prepare test-kitchen tests #10 (chris-rock)
  • offer native inspec-style syntax as an alternative #9 (arlimus)
  • lint files and activate travis testing #7 (chris-rock)
  • Update readme and add license information #6 (chris-rock)
  • add default attributes file #5 (srenatus)
  • audit::default: read profiles from attributes, push report to chefserver #2 (srenatus)

* This Change Log was automatically generated by github_changelog_generator

Collaborator Number Metric
            

2.0.0 passed this metric

Foodcritic Metric
            

2.0.0 passed this metric