Heimdall API Documentation

Heimdall CRUD Capabilities

Heimdall provides the following capabilities via CRUD operations:

• Upload scans from a pipeline or command line
• Programmatic API Key Generation
• Associate API keys to users and groups

How to Generate API Keys for Groups

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 via Users or Groups API Keys.

To use API Keys, 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

Create an API key using the Heimdall frontend (within the edit user profile modal) and upload an evaluation with the following command

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 the flags formats

Flags	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

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

NOTES:

• 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 will return a live JWT token in response

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

The access token can then be used to issue an API key for a user

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

or

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 to be used with the API to communicate with the application via the CLI.

To add a 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

top