Getting Started with the Chef Compliance API

chef_compliance_api.md

Getting Started with the Chef Compliance API

Demo how to setup accessing the Chef Compliance server's api and some of the useful things you can do with it.

Access tokens

In order to make requests against the Chef Compliance's API you need to have a token to authenticate. There are two types of token:

1. Refresh Tokens - A long-lived token that can be used to initially identify with the service, in exchange for an access token
2. Access Tokens - A short-lived (12 hours) and used for every request against the API.

Obtaining Tokens

There are a couple of ways to get refresh tokens and access tokens which are explained on the doc.chef.io

Setting up environment variables

Once you have your access token setup the following environment variables:

$ export API_URL="https:<FQDN_COMPLIANCE_SERVER>/api"
$ export API_TOKEN="<PASTE API YOUR TOKEN HERE>"
$ export AUTH="Authorization: Bearer $API_TOKEN"

A note about self-signed SSL certificates...the examples below assume you are using self-signed certificates and so all curl commands have the --insecure or -k flag appended

GET a list of all users on the Chef Compliance server

$ curl -X GET "$API_URL/users" -H "Authorization: Bearer $API_TOKEN" --insecure
[{"login":"admin","name":"admin","id":"ffb5e315-2d72-4912-70e1-b212ea1b5864"}]

GET a list of all nodes on the Chef Compliance server

$ curl -X GET "$API_URL/owners/admin/envs/default/nodes" -H "$AUTH" --insecure

[
  {
    "environment":"bf4c1601-4dde-4651-4460-55df2af39a77",
    "owner":"ffb5e315-2d72-4912-70e1-b212ea1b5864",
    "name":"Active Directory",
    "hostname":"windows3.local",
    "loginMethod":"winrm",
    "loginUser":"Administrator",
    "loginKey":"",
    "loginPort":0,
    "disableSudo":false,"sudoOptions":"",
    "lastScan":"0001-01-01T00:00:00Z",
    "lastScanID":"",
    "arch":"",
    "family":"",
    "release":"",
    "complianceStatus":-1,
    "patchlevelStatus":-1,
    "unknownStatus":1,
    "id":"41d78879-ed83-461c-6527-cdbe29e61c4f"
  }
]

Get a list of all Environments

$ curl -X GET "$API_URL/owners/admin/envs" -H "$AUTH" --insecure
[
  {
    "owner": "ffb5e315-2d72-4912-70e1-b212ea1b5864",
    "name": "default",
    "lastScan": "0001-01-01T00:00:00Z",
    "complianceStatus": 0,
    "patchlevelStatus": 0,
    "unknownStatus": 0,
    "id": "bf4c1601-4dde-4651-4460-55df2af39a77"
  }
]

Adding Nodes to Chef Compliance

It can be really useful to add nodes to Chef Compliance via the api in bulk. The following example uses a json file of nodes and passes the it to the Compliance api with curl.

nodes.json

[
  {
    "hostname": "linux4.local",
    "name": "Nagios Server",
    "environment": "bf4c1601-4dde-4651-4460-55df2af39a77",
    "loginUser": "root",
    "loginMethod": "sshKey",
    "loginKey": "263aa360-2e01-453f-5034-b7c4d91c2ca0" 
   },
   {
     "hostname": "windows3.local",
     "name": "Active Directory",
     "environment": "bf4c1601-4dde-4651-4460-55df2af39a77",
     "loginUser": "Administrator",
     "loginMethod": "winrm",
     "loginPassword": "$uper$ecur3"
    },
    {
      "hostname": "linux5.local",
      "name": "Webserver",
      "environment": "bf4c1601-4dde-4651-4460-55df2af39a77",
      "loginUser": "root",
      "loginMethod": "ssh"
     }
 ]

A couple of items of note...the environment corresponds to the environment id, loginMethod can be ssh for logging in with ssh passwords, sshKey for logging in with ssh keys for which the loginKey id can be provided, and loginPassword can be supplied to add a password for the account you are using to connect to nodes with Chef Compliance.

Add the nodes with curl

$ curl -X POST "$API_URL/owners/admin/nodes" -H "Content-Type: application/json" -H "$AUTH" -d @nodes.json --insecure
[
  "5e508e8e-7da7-4696-7483-b6510e332178",
  "e86a8d2b-76f8-46d1-4a6c-078ac7c27f00",
  "6bb60524-50af-45f1-65d4-22e82673bb3e"
]