Tutorial 2: Upload the trace

In this section, we will upload a trace and add it to the project we have selected.

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 API, which can then be used in an authenticated POST request directly to the AWS S3 API.

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

mutation {
  generateTraceUploadPost(input: {}) {
    url
    formData
    method
  }
}

Example response:

{
  "data": {
    "generateTraceUploadPost": {
      "url": "<object_storage_url>",
      "formData": "{\"key\": \"<key>\", \"policy\": \"<policy>\", \"x-amz-signature\": \"<signature>\", \"x-amz-date\": \"<date>\", \"x-amz-algorithm\": \"<algorithm>\", \"x-amz-credential\": \"<credential>\", \"success_action_status\": 201, \"acl\": \"private\"}",
      "method": "POST"
    }
  }
}

Make a note of the returned values to use in the next step. If the CAP instance is using the PUT method to upload traces (as indicated by the method field), refer to Appendix: PUT upload.

Upload the trace directly to S3

Use the following command to upload a trace using the AWS S3 API (example with curl):

curl \
    --request POST \
    --form key=<key> \
    --form acl=private \
    --form policy=<policy> \
    --form x-amz-signature=<signature> \
    --form x-amz-credential=<credentials> \
    --form x-amz-date=<current date> \
    --form x-amz-algorithm=<"AWS4-HMAC-SHA256" \
    --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 the [official documentation][s3_post_api].

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:

mutation {
  createTrace(
    input: {
      projectId: "<project_id>",
      name: "<name>",
      fileName: "<fileName>",
      key: "<key>",
      size: <size>
    }
  ) {
    trace {
      id
    }
  }
}

In the above query:

• <project_id> is the ID of the project retrieved in the previous part.
• <name> is an optional name of your choice, provided no other trace with that name exists in the project. Defaults to <fileName> if not provided.
• <fileName> is the optional name of the trace file. Defaults to the current timestamp if not provided. Ignored if name is provided.
• <key> must be the same value for key that you used to upload the trace in the previous query.
• <size> must be the size of trace_name.cst.gz in bytes.

Response:

{
  "data": {
    "createTrace": {
      "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 query:

query {
  node(id: "<trace_id>") {
    __typename

    ... on TraceFailed {
      reason
    }
  }
}

In the query above, <trace_id> should be replaced by the ID you obtained in the previous section.

If the trace has been processed, this will return the following response:

{
  "data": {
    "__typename": "TraceDone"
  }
}

If the trace is still being processed, the typename will be TracePending instead. You will have to wait and try the query again until it is TraceDone.

If trace processing failed, you will get the following response:

{
  "data": {
    "__typename": "TraceFailed",
    "reason": "<reason_for_the_failure>"
  }
}

Appendix: PUT upload

In certain environments, the CAP server will be configured to use the PUT method to upload traces. The API call to generateTraceUploadPost will return something like this:

{
  "data": {
    "generateTraceUploadPost": {
      "url": "<object_storage_url>/uploads/1234?X-Amz-...",
      "formData": "",
      "method": "PUT"
    }
  }
}

Take note of the URL that is returned.

To upload the file to the storage backend, use the following cURL command:

curl \
    --request PUT \
    --data-binary=@<path to trace_name.cst.gz> \
    <url>