# API

# Overview

Ostorlab provides a GraphQL API to perform all tasks, from create scan, access scans progress to list vulnerabilities.

GraphQL offers several benefits, like performance, reduced number of requests and removes the need for API versioning.

The next section will describe how to use the API, how to experiment and test it.

If you are not familiar with GraphQL, we recommend this tutorial to get familiar with the technology and syntax.

# Access

# Sandbox

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

# Scripts

A typical usage of the API is for 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 https://api.ostorlab.co/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 https://api.ostorlab.co/apis/graphql_token.

import requests
import json


query = '''
query {
  scans {
    scans {   
      id
      title
      progress
    }
  }
}
'''

# Retrieve authentication token.
request = requests.post(url='https://api.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://api.ostorlab.co/apis/graphql_token/',
                           json={"query": query},
                           headers=headers)
   print(request.json())

# 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 {
  scans {
    scans {   
      id
      title
      progress
    }
  }
}

# Scan Details

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

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

# Vulnerability Details

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

query {
  getScan(scanId: 26095) {
    vulnerabilities {
        vulnerabilities {
          detail {
            title
            description
            recommendation
            cvssV3Vector
          }
          customCvssV3BaseScore
        }
    }
  }
}

# Scan Progress

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

query {
  scans {
    scans{
      id
      packageName
      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:

mutation newMobileScan($title: String!, $assetType: String!, $application: Upload!, $plan: String!, $credentials: [CredentialInputType]) {
      createMobileScan(title: $title, assetType:$assetType, application: $application, plan: $plan, credentials: $credentials) {
        scan {
            id
        }
      }
    }

An example using Python:

import requests
import json

with open('app.apk', 'br') as application:
    query = '''mutation newMobileScan($title: String!, $assetType: String!, $application: Upload!, $plan: String!, $credentials: [CredentialInputType]) {
  createMobileScan(title: $title, assetType:$assetType, application: $application, plan: $plan, credentials: $credentials) {
    scan {
        id
    }
  }
}'''
    data = {
        'operations': json.dumps({'query': query,
                                  'variables': {'title': 'fake_title', 'assetType': 'android', 'application': None,
                                                'plan': 'free', 'credentials': []}}),
        '0': application,
        'map': json.dumps({
            '0': ['variables.application'],
        })
    }
    resp = requests.post('https://api.ostorlab.co/apis/graphql/', data=data, headers={"Authorization": f"Token {token}"})