Heimdall API Documentation

Heimdall API Capabilities

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

Important

• To use any available CRUD capabilities provided by Heimdall, the environment variable API_KEY_SECRET must be set (see Environment Variable Configurations).
  
• To create a secret to be used with the API_KEY_SECRET run: openssl rand -hex 33 then assign the value to the variable in the .env configuration file:
  • API_KEY_SECRET=91f82f...082fee

Upload evaluations scans via cURL

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.

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: Flag formats and description

Flag	Description
-F "data=@ ..."	File(s) to be uploaded
-F "filename= ..."	File(s) display name
-H "Authorization: Api-Key ..."	API Key value

To upload multiple files at once (up to 100) use

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

Retrieve Evaluations from Heimdall

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 (scans) by ID
• Retrieve all evaluations (scans) for provided user or group.

Find by ID

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.

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

Flag/Parameters	Description
-X GET	Explicity specify HTTP GET
-H "Authorization: Api-Key ..."	API Key value
<heimdall url>	The URL that Heimdal Server is deployed
<port>	The port Heimdall Server is listening on
<ID#>	The unqiue ID number of the evaluation to retrieve

Example of a GET call

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

Returns

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

top

Find All

Unlike Find by ID # which returns all data associated with a particular scan, Find All returns the metadata of all results files from what is available to the API key. Use the appropriate API key of the user or group to make the request.

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

Flag	Description
-X GET	Explicity specify HTTP GET
-H "Authorization: Api-Key ..."	API Key value
<heimdall url>	The URL that Heimdal Server is deployed
<port>	The port Heimdall Server is listening on

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

Returns

{
    "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
}

top

Programmatic API Key Generation

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.

Login via API

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

Tip

• If you are running Heimdall via a local Docker deployment, you may not need a PORT, given that it is likely running on standard 443 or 80.
  
• Add -k to ignore SSL certificate validation. This is unsafe. Do not use in production.
  
• If your login is handled through a third party authentication service, you must complete the third party login flow programmatically or insert a user record into the database containing the email address of the user for which you wish to create the API key
  

The server returns a live JWT access token in response

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

The access token is used to issue an API key

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

The server will respond with the newly generated API key

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

top

How to Generate API Keys for Groups

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:

Select the "Edit" pencil icon to open the "Update Groups" dialog window:

On the "Update Groups" dialog window, click on "Manage API KEYS" link to open the "Group API Keys" dialog window:

The "Group API Keys" dialog window allows the user to do the following:

• 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

Once the Add API Key is clicked a new API Key is generated. Provide a name for the key, copy and store the key value.

top