API Trace Analysis Tutorial

Aim

This tutorial will guide you through the process of uploading a trace file using the Cryptosense Analyzer REST API, triggering an analysis of the uploaded trace and viewing the results of the analysis.

The tutorial is divided into two stages:

  1. Uploading the trace to S3 and importing it using the Cryptosense Analyzer REST API
  2. Launching an analysis of the trace and viewing the results

Prerequisites

Before you begin, make sure that you have the following pieces of information available:

  • Your Cryptosense API Key:
    • This key can be found at the API page of the analyzer.
    • If you do not have API access enabled, then the link above will return a 404 error. To enable API access, please contact support.
  • Your target project ID
    • This can be found by navigating to the project in the analyzer GUI, and copying the ID from the URL bar.
  • Your target profile ID
    • This can be found by navigating to the profile in the analyzer GUI, and copying the ID from the URL bar.
  • Your target report name
    • This can be any string.
    • Duplicate names are not allowed in the same project.
  • A trace to upload
    • For instructions on generating a trace, please see our guide.
    • In the instructions below, the name of the trace is assumed to be trace_name.cst.gz.

As well as the information above, you will need a client to use to make the requests to the API. In this tutorial, we use the open-source curl client, which is available for most platforms.

Part 1: Uploading the trace

Retrieve S3 authenticated POST details from the API

Before uploading the trace file directly to AWS S3, it is necessary to generate a new set of authentication parameters using the Cryptosense Analyzer REST API, which can then be used in an authenticated POST request directly to the AWS S3 API.

Use the following command to request a set of authentication parameters:

curl \
    --request POST \
    --header 'API-KEY: <Cryptosense API Key>' \
    https://analyzer.cryptosense.com/api/v1/trace_s3_post

This will return a 201 response with the following format:

{
  "data": {
    "fields": {
      "AWSAccessKeyId": "<key_id>",
      "acl": "private",
      "key": "<key>",
      "policy": "<policy>",
      "signature": "<signature>",
      "success_action_status": 201
    },
    "url": "<object_storage_url>"
  }
}

Make a note of the returned values to use in the next step.

Upload the trace directly to S3

Use the following command to upload a trace using the AWS S3 API:

curl \
    --request POST \
    --form key=<key> \
    --form AWSAccessKeyId=<key_id> \
    --form acl=private \
    --form policy=<policy> \
    --form signature=<signature> \
    --form success_action_status=201 \
    --form Content-Type=<content_type> \
    --form file=@<path to trace_name.cst.gz> \
    <object_storage_url>

The Content-Type field must appear before the file field. Its value should be application/gzip for gzipped traces and empty otherwise. Note the presence of the @ character in the file field – this must be present for the upload to work correctly.

For more information on the AWS S3 API please refer to their documentation.

This will return a 201 response with the following format:

<?xml version="1.0" encoding="UTF-8"?>
<PostResponse>
  <Bucket>cryptosense-traces</Bucket>
  <Key>KEY</Key>
  <ETag>ETAG</ETag>
  <Location>LOCATION</Location>
</PostResponse>

Import the trace using the Cryptosense Analyzer REST API

Use the following command to import the uploaded trace with the following command:

curl \
    --request POST \
    --header 'API-KEY: <Cryptosense API Key>' \
    --form name=<trace_name.cst.gz> \
    --form key=<key> \
    --form size=<size> \
    https://analyzer.cryptosense.com/api/v1/projects/<Project ID>/traces

where <size> is the size of trace_name.cst.gz in bytes. This will return a 201 response with the following format:

{
  "data": {
    "trace_id": <Trace ID>
  }
}

Make a note of the trace ID, as it is needed for later steps in this process.

Verification: Check the uploaded trace has been successfully imported

Once the trace has been imported, check the status of the trace with the following command:

curl \
    --header 'API-KEY: <Cryptosense API Key>' \
    https://analyzer.cryptosense.com/api/v1/traces/<Trace ID>

This will return a 200 response with the following format:

{
  "data": {
    "name": <trace_name.cst.gz>,
    "size": <size>,
    "state": <state>
  }
}

Here <state> represents the state of the trace import, and will take one of the following values:

  • pending – Import has not yet begun
  • progress – Import is currently in progress
    • In this case, retry the request until the status changes
  • done – Import has succeeded, and the trace is ready for analysis
  • failed – Something went wrong with the import of the trace
    • To get more information on the failure, try looking at the trace using the web UI, or contact support

Part 2: Analyze the Uploaded Trace

Launch the analysis

Note: Traces are only available to be analysed once they have reached the done state.

To launch an analysis of the uploaded trace, use the following command:

curl \
    --request POST \
    --header 'API-KEY: <Cryptosense API Key>' \
    --form trace_id=<Trace ID> \
    --form profile_id=<Profile ID> \
    --form report_name=<Report name> \
    https://analyzer.cryptosense.com/api/v1/projects/<Project ID>/reports

This will return a 201 response of the form:

{
  "data": {
    "report_id": "<Report ID>"
  }
}

Check the state of the report

Once the analysis has been launched, check the status of the report using the following command:

curl \
    --header 'API-KEY: <Cryptosense API Key>' \
    https://analyzer.cryptosense.com/api/v1/reports/<Report ID>

This will return a 200 response with the following format:

{
  "data": {
    "state": "<state>",
    "result": <results>
  }
}

Here <state> represents the state of the analysis, and will take one of the following values:

  • pending – Analysis has not yet begun
  • progress – Analysis is currently in progress
    • In this case, retry the request until the status changes
  • done – Analysis has succeeded, and the results are available
  • failed – Something went wrong with the analysis
    • To get more information on the failure, try looking at the report using the web UI, or contact support

The result key is optional, and will only be present if the state is done. The value will be a JSON representation of the results of the analysis contained in the report.

Further Reading

For more information about the specific API endpoints that are used in this walkthrough, please see our reference documentation. This contains API reference for all endpoints available in the API, and also provides information on errors that may be encountered.

For general information about traces, please see our support pages. For instructions on how to generate a trace using our java agent, please see our HOWTO guide.

For information about how to interpret the results of an analysis, please see the support documentation for reports.

Try a Free 14-day Trial

Cryptosense Analyzer audits your applications and infrastructure to find vulnerabilities and understand your crypto landscape. Use it to optimise bug-fix resources and demonstrate compliance.