Integrate Chef Compliance w/Chef Server

[edit on GitHub]

_images/chef_automate_full.png

Integrate Chef Compliance with the Chef server to allow:

  • Users of Chef Compliance to log in using their Chef server credentials
  • Nodes under management by Chef to download Chef Compliance profiles, run them on nodes, and then send the results back to Chef Compliance

Note

This feature is included as part of the Chef Automate license agreement and is available via subscription.

Prerequisites

An integration between Chef Compliance and the Chef server requires:

  • Chef Compliance server, version 1.0 (or later), with a DNS-resolvable hostname
  • Chef server, version 12.4.1 (or later), configured as a standalone server
  • A time synchronization policy is in place, such as Network Time Protocol (NTP); authentication algorithms are sensitive to time drift
  • Chef Compliance and Chef server to allow bidirectional communication via port TCP/443; this enables single sign-on (SSO) and auditing use cases

Integration steps

To complete the integration between Chef Compliance and the Chef server, shell access to both Chef Compliance and the Chef server is required.

Prepare Chef Compliance

To prepare Chef Compliance for integration with the Chef server, do the following:

  1. From a command shell, run the following command:

    sudo -i
    chef-compliance-ctl connect chef-server
    

    When promoted, either confirm the default values (recommended) or provide custom values.

    The following shows sample output for a Chef Compliance server with a compliance.test hostname. SSL validation is not included because of the self-signed certificate used by the Chef Compliance server:

    Please confirm or provide values for:
     * Chef Server (OCID) APP-ID for Compliance [compliance_server]:
     * Name for Chef Server Authentication in Chef Compliance [Chef Server]:
     * Allow Self-signed SSL certificates [false]: true
     * Compliance Server URL [https://compliance.test]:
    
    Generating new shared secret for chef-gate...
      Successfully generated secret for chef-gate
    Please reconfigure Chef Compliance by running this command:
    chef-compliance-ctl reconfigure
    
    Please run the command delimited by --- on the Chef Server node as administrator:
    ---
    CHEF_APP_ID="compliance_server" AUTH_ID="Chef Server" COMPLIANCE_URL="https://compliance.test"\n
    INSECURE_SSL="true" CHEF_GATE_COMPLIANCE_SECRET="7fef11649f95d4de9e9334b103144f58e3e1fde12f49e\n
    5a70579143a7b48f7ebf25a0dab9c58b86460e392cb942a95b345bb" OIDC_CLIENT_ID="l0IL_ak15qZzkQtP_Orc5\n
    E0Gdka_3CYFVWHIjLKoh5o=@compliance.test" bash <( curl -k https://compliance.test/static/chef-gate.sh )
    ---
    

    The command may also be run in non-interactive mode:

    sudo -i
    chef-compliance-ctl connect chef-server --non-interactive true --chef-app-id 'compliance_server'\n
    --auth-id 'Chef Server' --insecure true --compliance-url 'https://compliance.test'
    
  2. Copy the command delimited by ---, and then run:

    sudo -i
    chef-compliance-ctl reconfigure
    

    This will create a file under /opt/chef-compliance/sv/core/env/CHEF_GATE_COMPLIANCE_SECRET

  3. Restart the Chef Compliance core service now:

    sudo -i
    chef-compliance-ctl restart core
    

Configure the Chef Server

To configure the Chef server for integration with Chef Compliance, do the following:

  1. From the Chef server shell, run the command delimited by --- from the previous section. For example:

    sudo -i
    CHEF_APP_ID="compliance_server" AUTH_ID="Chef Server" COMPLIANCE_URL="https://compliance.test"\n
    INSECURE_SSL="true" CHEF_GATE_COMPLIANCE_SECRET="7fef11649f95d4de9e9334b103144f58e3e1fde12f49e\n
    5a70579143a7b48f7ebf25a0dab9c58b86460e392cb942a95b345bb" OIDC_CLIENT_ID="l0IL_ak15qZzkQtP_Orc5\n
    E0Gdka_3CYFVWHIjLKoh5o=@compliance.test" bash <( curl -k https://compliance.test/static/chef-gate.sh )
    

    This will install a chef-gate service on the Chef server that enables the Chef server to act as an OpenID Connect (OIDC) resource server, plus enables the chef-client to request Chef Compliance profiles, and then report back to Chef Compliance the results of profile scans.

  2. When finished, a command will be printed at the end of the output similar to:

    chef-compliance-ctl auth add --client-id "50b3447fd3db4f59d0160611eb25703f348887b6760482df5\n
    bd3ae2303f93c2d" --client-secret "3880ed856a14fce2201459e93d667da8fcd22f8ebbc1ad94d8a0a1195\n
    9834b91" --id "Chef Server" --type ocid  --chef-url https://chef.compliance.test --insecure true
    

    Copy this line. It will be used in the next section.

Configure Chef Compliance

To configure Chef Compliance for integration with the Chef server, do the following:

  1. From the Chef Compliance shell, run the command that was printed at the end of the output while configuring the Chef server. For example:

    chef-compliance-ctl auth add --client-id "50b3447fd3db4f59d0160611eb25703f348887b6760482df5\n
    bd3ae2303f93c2d" --client-secret "3880ed856a14fce2201459e93d667da8fcd22f8ebbc1ad94d8a0a1195\n
    9834b91" --id "Chef Server" --type ocid  --chef-url https://chef.compliance.test --insecure true
    
  2. When finished, reconfigure Chef Compliance:

    sudo -i
    chef-compliance-ctl reconfigure
    

Test Integration

Go to the Chef Compliance web interface and click the Use a different provider link. The default provider is Compliance Server. Switch it to Chef Server, and then accept the authorization request. Only nodes under management by Chef that successfully run audit::default will show up in Chef Compliance.

Scan Managed Nodes

Once the integration is complete, the audit cookbook allows Chef Compliance profiles to be run as part of a chef-client run. Profiles are downloaded from Chef Compliance. Audit results are sent back to Chef Compliance, which uses the Chef server as a proxy.

The audit cookbook must be uploaded to the Chef server, and then added to one (or more) recipes before the chef-client can run profiles on a node.

Upload the audit Cookbook

The audit cookbook is available at the following locations:

Download it from one of those locations, and then upload it to the Chef server using the same workflow as any other cookbook.

Use the audit Cookbook

There are two ways to use the audit cookbook:

  • Use the custom resources in the audit cookbook directly in recipes
  • Add the audit::default recipe to the run-list

The default recipe requires a node['audit']['profiles'] attribute to be set. For example, defined as part of a JSON-based role or environment file:

"audit": {
  "profiles": [
    {
      "name": "ssh",
      "compliance": "base/ssh"
    },
    {
      "name": "linux",
      "compliance": "base/linux"
    }
  ],
  "reporter": "chef-server"
}

Note

The audit cookbook requires a time synchronization policy to be in place, such as Network Time Protocol (NTP).

The example above is using audit cookbook version 2.0. Further information is available at Reporting to Chef Compliance via Chef Server. For more configuration examples supported audit cookbook 4.0.0 and later, see setting up visibility on Chef automate and supported audit cookbook configurations. For more information and examples on how to use the audit cookbook, see the audit project repo in GitHub.

Run the chef-client

After the audit cookbook is uploaded to the Chef server and it has been added to recipes and/or the run-list, the chef-client run will do the following:

  • Download the targeted profiles from Chef Compliance, and then run them locally on the node via InSpec.
  • Log a summary of the audit execution.
  • Submit the full report back to the Chef Compliance server. These reports are saved in a Chef Compliance Organization that has the same name as the Organization to which the node belongs on the Chef server.