Overview

Ostorlab has migrated from a REST API to GraphQL API to perform all scannings tasks, from create scan, access scans progress to list vulnerabilities.

The migration is motivated by the increase in the complexity of maintaining a large and rapidly evolving API.

GraphQL offers the benefits of performance and removes the need for API versioning, which offers the Ostorlab team the capacity to extend its API without impacting its users.

The next section will describe how to use the API, how to play with and test it and finally provides some examples to common usages.

If you are not familiar with GraphQL, we recommend this tutorial to get familiar with the technology and syntax. We promise you, once you get familiar with it, you will wish all the API will start using GraphQL.

Access

Sandbox

You can use the GraphiQL web application to experiment with the API. GrapiQL is accessible at /apis/graphql. The API is accessible to authenticated users only. Make sure you are authenticated at /portal/login/.

API access from scripts

A typical usage of the API is for building automation around deployment pipelines or automate the creation and monitoring of a large number of scans. Ostorlab offers a token based authentication. The token can be retrieved from /apis/token/ by submitting the username and password. A token linked to the user will be created. The token is then set in an Authorization header with the value Token {value} to authenticate subsequent requests to /apis/graphql_token.

import requests
import json


query = '''
query {
   allScans {
     email
     id
     title
 }
}
'''

# Retrieve authentication token.
request = requests.post(url='https://ostorlab.co/apis/token/',
                       json={"username":"user1","password":"pass1"})
json_data = json.loads(request.text)
if "token" in json_data:
   token = json_data["token"]
   # Set token in Authorization header.
   headers = {"Authorization": f"Token {token}"}
   # Post query request.
   request = requests.post(url='https://ostorlab.co/apis/graphql_token/',
                           json={"query": query},
                           headers=headers)
   print(request.json())

API Reference

Ostorlab maintains a self documenting scheme, see documentation explorer at the top right corner in the GrapiQL menu. See also the example section for common queries.

Examples

List Scans

To list all the scans owned by the organisation of the current user:

query {
  allScans {
    id
    title
    progress
  }
}

Scan Details

To retrieve the details of a single scan using its id:

query {
  scan(id: 26095) {
    id
    title
    scanType
    createdTime
    riskRating
  }
}

Vulnerabilities Details

To retrieve the list and details of vulnerabilities of a scan:

query {
  scan(id: 26095) {
    vulnerabilities {
      detail {
        title
        description
        recommendation
        cvssV3Vector
      }
      customRiskRating
    }
  }
}

Scan Progress

To determine scan current progress stage (scheduled, scanning or done):

query {
  allScans {
    id
    title
    progress
  }
}

Create New Scan

GraphQL do not support binary format. To submit a scan, files needs to be base64 encoded to be submitted. To create a scan, make sure all these fields are submitted:

An example using Python

import base64
import requests
import json

with open('myapk.apk', 'br') as application:
   lines = application.read()
   lines_b64 = base64.b64encode(lines)

   # The GraphQL query (with a few additional bits included) itself defined as a multi-line string.

   query = '''
   mutation newScan {
     createScan(input: {
       title: "test",
       scanType: "android",
       b64Application: "%s",
       public: false,
     })
     {
       scan {
         email
         id
         title
       }
     }
   }
   ''' % lines_b64

   request = requests.post(url='https://ostorlab.co/apis/token/',
                           json={"username":"user1","password":"pass1"})
   json_data = json.loads(request.text)
   if "token" in json_data:
       token = json_data["token"]
       headers = {"Authorization": f"Token {token}"}
       request = requests.post(url='https://ostorlab.co/apis/graphql_token/',
                               json={"query": query},
                               headers=headers)
       print(request.json())