The Heimdall Application Programming Interface (API) provides the following Representational State Transfer (REST) and Create, Read, Update, and Delete (CRUD) operations:

• Upload Evaluation (scans) from a Pipeline or Command Line (CMD)
• Retrieve Evaluation (scans) from a Pipeline or Command Line (CMD)
• Programmatic User API Key Generation
• Generate Group API Keys

Heimdall enables data exchange between a device and the server through a terminal utilizing the client URL (cURL) command line using Users or Groups API Keys.

API cURL format to upload (POST) an evaluation to Heimdall:

curl -F "data=@<Path to Evaluation File>" \
-F "filename=<Filename To Show in Heimdall>" \
-F "public=true/false" \
-F "evaluationTags=<tag-name>,<another-tag-name>..." \
-H "Authorization: Api-Key apikeygoeshere" "http://localhost:3000/evaluations"

NOTE: cURL flags

• The -F makes curl POST data using the Content-Type multipart/form-data
• The @ makes a file get attached in the post as a file upload
• The -H is used add the authorization to the regular request headers

API cURL format to upload (POST) multiple files at once (up to 100) to Heimdall:

curl -F "data=@<Path to first evaluation File>" \
-F "data=@<Path to second evaluation File>" ... \
-F "public=true/false" \
-F "evaluationTags=<tag-name>,<another-tag-name>..." \
-H "Authorization: Api-Key apikeygoeshere" "http://localhost:3000/evaluations"

top

The Heimdall API supports the capability of retrieving results information previously uploaded to the Heimdall server. Evaluations are retrieved for a single user or for a group. Two options are available:

• Retrieve evaluations (scan's) for provided user or group by ID
• Retrieve all evaluations (scans) for provided user or group.

To obtain the data from a specific scan and additional metadata from Heimdall Server accessible to a user or group, use the appropriate API key. If the key does not have permissions to access a particular scan (the scan is not affiliated with the user/group making the request), a 403 Forbidden status will be returned.

API cURL format for retrieving a specific evaluation ID:

curl -X GET \
  -H "Authorization: Api-Key apikeyhere" \
  "<heimdall url>:<port>/evaluations/<ID#>"  

API cURL example:

curl -X GET \
  -H "Authorization: Api-Key eyJhbGc...E-4QtA" \
  "localhost:3000/evaluations/1"  

{
    "id": "1",
    "filename": "test1",
    "data": // all data from the InSpec scan
    {
        "platform":
        {
        },
        "profiles":
        [
            {
            }
        ],
        "statistics":
        {
        },
        "version": "..."
    },
    "evaluationTags": // tag(s) assigned to scan
    [
        {
            "id": "1",
            "value": "tag1",
            "evaluationId": "1",
            "createdAt": "...",
            "updatedAt": "..."
        }
    ],
    "groups": // group(s) this scan belongs to
    [],
    "userId": "1",
    "groupId": null,
    "public": false,
    "createdAt": "...",
    "updatedAt": "...",
    "editable": true
}

top

Unlike Find by ID # which returns all data associated with a particular scan ID, the Find All returns the metadata of scans (within the provided query parameters - offset and limit) belonging to the provided user or group API key provided. The returned data is limited by URL query parameters (see table below for details)

API cURL format for retrieving all (see offset/limit) evaluations for a given user or group:

curl -X GET \
  -H "Authorization: Api-Key apikeyhere" \
  "<heimdall url>:<port>/evaluations?offset=0&limit=10&order\[\]=createdAt&order\[\]=DESC"  

NOTE: The URL query parameters are separated by the charact &

API cURL example:

curl -X GET \
  -H "Authorization: Api-Key eyJhbGc...E-4QtA" \
  "localhost:3000/evaluations?offset=0&limit=10&order\[\]=createdAt&order\[\]=DESC"  

{
    "evaluations": // this particular user has 2 scans stored
    [
        {
            "id": "2",
            "filename": "test2",
            "evaluationTags":
            [
                {
                    "id": "2",
                    "value": "tag2",
                    "evaluationId": "2",
                    "createdAt": "...",
                    "updatedAt": "..."
                }
            ],
            "groups":
            [],
            "userId": "1",
            "groupId": null,
            "public": false,
            "createdAt": "...",
            "updatedAt": "...",
            "editable": true
        },
        {
            "id": "1",
            "filename": "test1",
            "evaluationTags":
            [
                {
                    "id": "1",
                    "value": "tag1",
                    "evaluationId": "1",
                    "createdAt": "...",
                    "updatedAt": "..."
                }
            ],
            "groups":
            [],
            "userId": "1",
            "groupId": null,
            "public": false,
            "createdAt": "...",
            "updatedAt": "...",
            "editable": true
        }
    ],
    "totalCount": 2
}

Filtering can be used on this API endpoint to restrict return values. Filtering can be applied to these fields: file, group, and/or tag name The additional query parameters for filtering are:

API cURL example filtering on scans containing filename rhel_8 or group name myGroup or tag name rhel8:

curl -X GET \
  -H "Authorization: Api-Key eyJhbGc...E-4QtA" \
  "localhost:3000/evaluations?offset=0&limit=10&order[]=createdAt&order[]=DESC&useClause=true&operator=OR&searchFields[]=(rhel_8)&searchFields[]=(myGroup)&searchFields[]=(rhel8)"

top

In order to generate an API key for a user programmatically, you must create a login session for either the admin account or the account of the user for which you wish to create an API key.

curl '<your-heimdall-instance>:<PORT>/authn/login' \
  -H 'Content-Type: application/json' \
  --data-raw '{"email":"<email>","password":"<password>"}'

{
	"userID": "1",
	"accessToken": "eyJhbGc...rqA3Zo"
}

NOTE: Use the returned accessToken for the -H 'Authorization: Bearer <accessToken>'

Issue an API key utilizing user identification (userID), the one returned by the login API call use:

curl 'http://localhost:8080/apikeys' \
  -H 'Authorization: Bearer eyJhbGc...rqA3Zo' \
  -H 'Content-Type: application/json' \
  --data-raw '{"userId":"<User ID>","currentPassword":"<Password>"}' \
  --compressed

Issue an API key utilizing the user email used for the login API call

curl 'http://localhost:8080/apikeys' \
  -H 'Authorization: Bearer eyJhbGc...rqA3Zo' \
  -H 'Content-Type: application/json' \
  --data-raw '{"userEmail":"<User Email>","currentPassword":"<Password>"}' \
  --compressed

{
	"id": "3", // This is the ID of the API key
	"name": null,
	"apiKey": "eyJhbGciOi...kPrGBVDOU"
}

top

Heimdall provides the ability for groups to have API key(s) that can be used to communicate with the application via the CLI.

To add an API key to a group, select "My Groups" from the user menu:

• Add an API Key to the group
• Regenerate an new API Key (if the old one is lost or compromised)
• Delete an API Key

NOTE: To create a new API Key users must provide their password

top