How to use the Crashtest Security API

Setup and usage of the public API to automate creating projects and scans.

TL;DR

Why should I use the API?

The API grants access to multiple features of the Crashtest Security Suite without human interaction, like clicking through the interface. Systems which need to update data dynamically are able to setup projects and start scans. 

What do I need, in order to use the API?

In order to get started using the API, an API Key is required. Every key is unique for a single user and allows the user to interact with his/her stored data in the Crashtest Security Suite.

An API Key can be requested by sending an email at support@crashtest-security.com

Once the key has been assigned, it must be attached to every request, which is send to the API. 

Where do I have to attach the API Key?

There are multiple ways of attaching the key. It can either be attached to the URL as a parameter or used as a header field within the request. Both versions allow the "api_key" attribute to be either fully lower or upper case.

As a parameter in the URL:

  • api.crashtest.cloud/something?API_KEY=my_secret_key
  • api.crashtest.cloud/something?api_key=my_secret_key

As a header attribute:

  • API_KEY: my_secret_key
  • api_key: my_secret_key

What can I do using the API?

The API is based on the Rest API format and allows sending GET, POST and DELETE requests. All available operations with a detailed specification can be found here. As the API Key is assigned to the user itself, it can be used to modify all teams, which the user is a member of.

Note: The same restrictions and permissions the user normally has, are also applied for the API.

For most requests, it is necessary to have some IDs in advance. An ID is a unique identifier that clarifies, which team, which project, ... should be updated.

Team ID

The team ID can be retrieved from the Local Storage of the Browser or by requesting the information at support@crashtest-security.com

The Local Storage can be found by opening the developer tools of the browser. 

  1. Click on the "Application" tab
  2. Select the local storage for "https://crashtest.cloud"
  3. Check the "user" entry for the "active_team_id"

When switching between different teams, this value will update and represent the newly selected team.

Project ID

There are two ways of retrieving the ID of a project.

  1. If the project is created using the API, the response of the "create API" call contains the ID of the project.

    Project ID via API Response
  2. The project ID can be found by clicking in the User Interface on a single project. Afterwards the URL in the browser shows a URL like: https://crashtest.cloud/projects/123
    The "123" at the end is in this case the ID of the specific project.

Scan ID

When starting a scan using the API, the response of the call contains the ID of the scan:

Scan ID via API Response

If the API call to start a new scan is used, while another scan for the same project is already running, the API call returns the ID of the running scan.

Running Scan ID via API Response

Operations

Currently the API offers the following operations:

  • Projects
    • Create a new project
    • Delete a project
  • Scans
    • Start a new scan for a project
    • Stop a running Scan
    • Retrieve the status of a scan
    • Retrieve the finding for a scan (PDF, XML, JSON)