REST API tutorial

Learn how to interact with the diverse set of endpoints and harness the power of REST architecture in integrating with and extending the functionality of Security Compliance Management. This tutorial guides you through running an ad-hoc scan in Security Compliance Management using the API.

Before you begin:

Make sure that you have read the Authentication section and have a personal access token. You need the personal access token you created in Create and manage personal access tokens as a user. It is required for authentication.

You also need to have comply-operator or comply-admin permissions on the token to trigger an ad-hoc scan.

  1. Optional: Get the host's information. This step can be skipped if you do not want to run a scan on a particular host.
    Copy
    curl --request GET \
      --url https://<COMPLY-HOSTNAME>/api/public/v1/hosts \
      --header 'Authorization: Bearer <TOKEN>'

    This returns something similar to:

    Copy
    {
        "data": [
            {
                "id": 1,
                "name": "00.example.puppet.net",
                "environment": "development",
                "assessor_version": "4.41.0",
                "operating_system": {
                    "id": 9,
                    "name": "AlmaLinux 8"
                }
            },
            ...
            {
                "id": 10,
                "name": "09.example.puppet.net",
                "environment": "production",
                "assessor_version": "4.41.0",
                "operating_system": {
                    "id": 45,
                    "name": "Debian 12"
                }
            }
        ],
        "total": 100,
        "next": "/api/public/v1/hosts?offset=10&limit=10",
        "offset": 0,
        "limit": 10
    }

    From this you can extract the name of the hosts.

  2. Get the operating system information.
    Copy
    curl --request GET \
      --url 'https://<COMPLY_HOSTNAME>/api/public/v1/operating-systems' \
      --header 'Authorization: Bearer <TOKEN>'

    This returns something similar to:

    Copy
    [
        {
            "id": 8,
            "name": "CentOS 7",
            "compatible_benchmarks": [
                {
                    "id": 8,
                    "name": "4.0.0 CIS CentOS Linux 7"
                }
            ]
        },
      ...
        {
            "id": 3,
            "name": "macOS 13.0",
            "compatible_benchmarks": [
                {
                    "id": 3,
                    "name": "2.0.0 CIS Apple macOS 13.0 Ventura"
                }
            ]
        }
    ]

    From this you can extract the name of the operating system.

  3. Run the ad-hoc scan on nodes with specified hostnames, operating systems, and environment and node groups. Pass these as a filter object of the request body.
    Copy
    curl --request POST \
      --url https://<COMPLY_HOSTNAME>/api/public/v1/scan \
      --header 'Authorization: Bearer <TOKEN>' \
      --header 'Content-Type: application/json' \
      --data '{
        "scan-type": "desired",
        "filters": {
          "operating_systems": [
            "redhat 7",
            "redhat 8"
          ]
        }
      }'

    This triggers a scan on all Red Hat 7 and Red Hat 8 nodes in the Puppet Enterprise inventory.

  4. Optional: You can run a scan on particular hosts using the hostnames gathered from Step 1.
    Copy
    curl --request POST \
      --url https://<COMPLY_HOSTNAME>/api/public/v1/scan \
      --header 'Authorization: Bearer <TOKEN>' \
      --header 'Content-Type: application/json' \
      --data '{
        "scan-type": "desired",
        "filters": {
          "hostnames": [
            "00.example.puppet.net"
          ]
        }
      }'

    This triggers a scan on the 00.example.puppet.net host.