Technical Overview

Config Requirements

Your application’s user interface MUST let the end-user specify their own API Token and the URI endpoint to upload to.

CloudShark URI

The CloudShark URI should be the full URL including protocol of the API endpoint. For CloudShark Personal accounts this will be:

https://www.cloudshark.org

CloudShark Enterprise customers will require setting a private domain to use instead.

This URI MUST be configurable, and support both public and private instances.

Additionally, we strongly recommend using only secure HTTPS uploads to a FQDN with a matching valid certificate.

API Token

The user MUST also be able to specify the API Token that has been created on that host. API Tokens are 32-characters and only contain case-insensitive hexadecimal 0-9a-f.

The username and password of the user account SHOULD NOT be required by your application.

Performing Uploads

In order to upload a PCAP to CloudShark, your application should perform an HTTP POST or PUT with the contents of a completed capture file a URL matching the following pattern:

https://\[host\]/api/v1/\[api-token\]/upload

The host and api-token fields should be provided by the end user.

HTTP POST vs. PUT

When using the POST method, the contents of the file MUST be encoded as multipart/form-data and provided as the file URL parameter.

If using the PUT method, the file MUST be sent as binary data as the body of the HTTP request.

Response

The CloudShark server will respond to successful uploads with an HTTP 200 response containing the newly created Capture as a JSON encoded string:

{ "filename":"traffic-2011-08-16-104829.cap", "id":"f27d1494400c" }

Your application can then provide a link to the CloudShark “session” for this upload:

https://\[host\]/captures/\[capture.id\]

We recommend directing users to only this URL as a starting point for their analysis.

Handling Errors

If an API request fails for any reason, CloudShark will return a non-200 HTTP response code. The response object will also contain a text description of the error in the exceptions field.

{ "status":404, "exceptions":\["API Token is missing or invalid"\] }

Your application SHOULD inspect the status field, as well as any exceptions given for why the upload failed. Common errors include trying to upload with an invalid API Token, or uploading a file that is larger than allowed.

CloudShark returns useful human-readable messages for all error conditions. These may be passed onto the user or displayed in your interface if desired.

If your application does not get an HTTP 200 status code back, or if the text response is not parsable as JSON, you MUST assume the upload failed and return an error code to the user.

Usage Statistics

If you’d like to see usage-statistics for your application, make sure you set the HTTP User-Agent header on requests to something unique to your application. This could include a version number as well.

User-Agent: my-plugin/v1.2.5

Product

Search Results