Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Audit docs improvements #115

Merged
merged 1 commit into from
Oct 24, 2016
Merged

Audit docs improvements #115

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 20 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ Using the `inspec_version` attribute, please use the following `InSpec` 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](https://rubygems.org/gems/inspec/versions)
Expand Down Expand Up @@ -96,15 +97,21 @@ knife cookbook upload audit -o ./chef-cookbooks

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

### Configure node

#### 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](https://docs.chef.io/integrate_compliance_chef_server.html).

#### 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:

```ruby
"audit" => {
"collector" => "chef-server",
"owner" => "prod-org",
"inspec_version" => "0.35.0",
"inspec_version" => "1.2.1",
"profiles" => {
# org / profile name from Chef Compliance
"base/linux" => true,
Expand Down Expand Up @@ -135,19 +142,22 @@ You can also configure in a policyfile like this:

```ruby
default['audit'] = {
'collector' => 'chef-server',
'profiles' => {
'base/linux' => true,
'base/ssh' => true
}
}
```


#### Direct reporting to Chef Compliance

If you want the audit cookbook to directly report to Chef Compliance, set the `collector`, `server` and the `refresh_token` attribute.
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`
Expand All @@ -156,7 +166,9 @@ If you want the audit cookbook to directly report to Chef Compliance, set the `c
"audit": {
"collector": "chef-compliance",
"server": "https://compliance-fqdn/api",
"owner": "my-comp-org",
"refresh_token": "5/4T...g==",
"insecure": false,
"profiles": {
"base/windows": true
}
Expand All @@ -169,6 +181,7 @@ Instead of a refresh token, it is also possible to use a `token` that expires in
"audit": {
"collector": "chef-compliance",
"server": "https://compliance-fqdn/api",
"owner": "my-comp-org",
"token": "eyJ........................YQ",
"profiles": {
"base/windows": true
Expand All @@ -179,8 +192,9 @@ Instead of a refresh token, it is also possible to use a `token` that expires in

#### Direct reporting to Chef Visibility

If you want the audit cookbook to directly report to Chef Visibility, set the `collector` attribute to 'chef-visibility'.
This method is sending the report to `data_collector.server_url`, defined in `client.rb`. It require `inspec` version `0.27.1` or greater.
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.

```ruby
"audit": {
Expand Down
3 changes: 2 additions & 1 deletion attributes/default.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,8 @@
# set this insecure attribute to true if the compliance server uses self-signed ssl certificates
default['audit']['insecure'] = nil

# owner needed for the 'chef-compliance' and 'chef-server' collectors
# Chef Compliance organization to post the report to. Defaults to Chef Server org if not defined
# needed for the 'chef-compliance' collector, optional for 'chef-server' collector
default['audit']['owner'] = nil

# raise exception if Compliance API endpoint is unreachable
Expand Down