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

RSS

audit (43) Versions 0.10.0

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

Berkshelf/Librarian
Policyfile
Knife
cookbook 'audit', '= 0.10.0'
cookbook 'audit', '= 0.10.0', :supermarket
knife cookbook site install audit
knife cookbook site download audit
README
Dependencies
Changelog
Quality

audit cookbook

Cookbook Version Build Status

Requirements

Chef

  • Chef Client >=12.5.1

The audit cookbook allows you to run Chef Compliance profiles as part of a Chef Client run. It downloads configured profiles from Chef Compliance and reports audit runs to Chef Compliance.

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

You can see all publicly available InSpec versions here

Overview

The audit support two 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

The second scenario support a direct connection with Chef Compliance and support chef-solo mode as well.

 ┌──────────────────────┐                                ┌──────────────────────┐
 │     Chef Client      │                                │   Chef Compliance    │
 │                      │                                │                      │
 │ ┌──────────────────┐ │                                │                      │
 │ │                  │◀┼────────────────────────────────│  Profiles            │
 │ │  audit cookbook  │ │                                │                      │
 │ │                  │─┼───────────────────────────────▶│  Reports             │
 │ └──────────────────┘ │                                │                      │
 │                      │                                │                      │
 └──────────────────────┘                                └──────────────────────┘
  audit = {
    "inspec_version" => "0.22.1",
  }

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 the existing workflow.

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.

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, to run the base/ssh and base/linux profiles, you can define the attribute in a JSON-based role or environment file like this:

audit = {
  "inspec_version" => "0.22.1",
  "profiles" => {
    # org / profile name from Chef Compliance
    'base/linux' => true,
    # supermarket url
    'brewinc/ssh-hardening' => {
      # location where inspec will fetch the profile from
      'source' => 'supermarket://hardening/ssh-hardening',
      'key' => 'value',
    },
    # local Windows path
    'brewinc/win2012_audit' => {
      # filesystem path
      'source' => 'E:/profiles/win2012_audit',
    },
    # github url
    'brewinc/tmp_compliance_profile' => {
      'source' => 'https://github.com/nathenharvey/tmp_compliance_profile',
    },
    # disable profile
    'brewinc/tmp_compliance_profile-master' => {
      'source' => '/tmp/tmp_compliance_profile-master',
      'disabled' => true,
    },
  },
}

Direct reporting to Chef Compliance

If you want the audit cookbook directly report to Chef Compliance, set the server and the token attribute.

If those attributes are missing, the audit cookbook expects the Chef Server integration to be available.

audit: {
  server: 'https://compliance-fqdn/api/',
  token: 'eyJ........................YQ',
  profiles: {
    'base/windows'    => true,
  },
}

It is also possible to use a refresh_token instead of an access token:

audit: {
  server: 'https://compliance-fqdn/api/',
  refresh_token: '5/4T...g==',
  profiles: {
    'base/windows'    => true,
  },
}

How does it relate to 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

How to migrate 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 use the interval recipe instead of the default recipe in your runlist, and set the following attributes:

default['audit']['interval']['enabled'] = false
default['audit']['interval']['time'] = 1440

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": {
      "base/ssh": true,
      "base/linux": true
    },
    "interval": {
      "enabled": "true",
      "time": 1440
    }
  }

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.

Dependent cookbooks

This cookbook has no specified dependencies.

Contingent cookbooks

There are no cookbooks that are contingent upon this one.

Change Log

v0.9.1 (2016-05-26)

Full Changelog

Implemented enhancements:

  • Report to Chef Compliance directly #45
  • test-kitchen example for Chef Compliance direct reporting #57 (chris-rock)

Fixed bugs:

Closed issues:

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

v0.9.0 (2016-05-25)

Full Changelog

Fixed bugs:

  • Scan reports showing up as "Skipped" in the Compliance server UI #46

Closed issues:

  • Provide support for additional profile hosting sources #49

Merged pull requests:

v0.8.0 (2016-05-18)

Full Changelog

Fixed bugs:

  • Compliance results no longer reports back to Chef Compliance with latest version of inspec #41
  • Inspec 0.22.1 for Chef Compliance 1.2.3 #44 (chris-rock)

Merged pull requests:

  • Update readme and bump patch version #43 (alexpop)

v0.7.0 (2016-05-13)

Full Changelog

Fixed bugs:

  • Support chef-client < 12.5.1 #30

Closed issues:

  • Undefined method 'path' for nil:NilClass #39
  • 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

Fixed bugs:

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

v0.5.0 (2016-04-25)

Full Changelog

Implemented enhancements:

  • 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

Implemented enhancements:

  • work with token and direct compliance server API #20 (srenatus)

Merged pull requests:

v0.4.3 (2016-04-20)

Full Changelog

Fixed bugs:

  • chef-compliance profiles changes require a new ver of inspec #28 (alexpop)

Merged pull requests:

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)

Implemented enhancements:

  • add default recipe that reads profiles from attributes #1
  • prepare test-kitchen tests #10 (chris-rock)
  • Update readme and add license information #6 (chris-rock)

Closed issues:

  • Do not crash default recipe, if node['audit'] is not defined #4

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)
  • offer native inspec-style syntax as an alternative #9 (arlimus)
  • lint files and activate travis testing #7 (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

Foodcritic Metric
            

0.10.0 passed this metric