CloudShark

Integration Guide

Send your application's PCAP data to CloudShark to view, share, and analyze.

Add web-based PCAP analysis and management to your tool with a simple HTTP upload!


Take Advantage of the Benefits of CloudShark Integraton

Build it Quickly

CloudShark integration is fast and easy to add. All it takes is a simple HTTP upload. No incompatible binary libraries to compile, or external dependencies to keep track of.

Add Value to Your Tools

There's no cost to you, and your customers will immediatly benefit from additional analysis features and workflow improvements, saving them time and money. Let CloudShark enhance your offering!

Improve Your Demos

Don't let your product demo grind to a halt while you download a large PCAP for analysis. Stay in the browser and jump straight to the packets.

Joint Marketing

We love promoting tools to our customers that have CloudShark integration built-in, and we would love to talk to your cusomters about the benefits of adding CloudShark to their stack. Contact our marketing team to discuss options!

Check out our list of current integrators

If your tool is already exporting PCAP files to something like Wireshark,
adding CloudShark integration will be easy!


Key Integration Concepts

  • CloudShark operates on complete capture files. Before a CloudShark capture session can be created, the entire capture must be sent to CloudShark.

  • CloudShark does not initiate the upload of a capture file. The user interface or management system of your device or application must initiate the capture and upload to CloudShark.

  • Upload your PCAP files over HTTPS with either the POST or PUT method. CloudShark will return a "session" identifier in JSON that your application uses to build a URL.

  • Integrations should support users on our CloudShark Hosted platform as well as CloudShark Enterprise customers who are running their own on-premise version of CloudShark. Typically, all that needs to change is the URL of the API endpoint (so make it configurable!)

  • CloudShark loves metadata! If your PCAPs can be organized by tag, or need additional comments saved along side them, send that to CloudShark along with the upload.

Where can I get an API Token?

Whether you have a CS Personal account, or your own CS Enterprise server, you can generate API tokens that can be used by other tools to push data programatically.

Log into a user account, and choose "API Tokens" from the Preferences menu. If you are an Admin user of a CS Enterprise system, you can access the API tokens for each user through your "Appliance Setup" menu instead.

Get started for free in under 2 minutes...

Step 1. Create a CS Personal account

Click here and sign up for the 30-day free trial of one of our CS Personal SaaS accounts. You can explore the API and test things out against our servers.

If you already have access to an on-premises CS Enterprise server, log into your local server instead.

Step 2. Get an API Token

You can find your API tokens in the Preferences menu at the top of the page. This token will be used to develop your integreation, for testing, and when you're showing the CloudShark team a demo.

Tokens are tied to accounts, so when it comes time to release your integration, your customers will provide their own API Token so that uploads belong to them.

Step 3. Check out our tutorials and API documentation

Walk through a tutorial, read over the documentation, or just start hacking away! It's really easy to send PCAP files to CloudShark. How you build it is up to you.

Read more on our Support Site »

Step 4. Time for show and tell

We love seeing all the different tools that have PCAP data as a part of them, and we love to talk integration specifics with your engineers. When you have a working Proof-of-Concept for your integration, let us know! We'll set up a call for you to show us!

Deployment Scenarios

Hosted vs. On-Premises

CS Enterprise is preferred by our more security conscious customers. They deploy their own on-premises server that has internal connectivity only. Because it is often firewalled off from the rest of the Internet, any integration should work locally.

For smaller consumer-grade and individual applications, CS Personal SaaS is more appropriate.

CS Personal accounts are limited to a max-file-size of 150 MB.

Cloud-based management

If your product or application has a cloud-based management component you may consider transferring uploaded capture files through your infrastructure before sending it to a CloudShark endpoint.

We recommend using CS Personal for this kind of deployment so the end user does not need to configure inbound firewall rules allowing uploads from outside their network.


Technical Overview

Configuration 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 CS Personal accounts this will be https://www.cloudshark.org.

CS 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 integration 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 integration, make sure you set the HTTP User-Agent header on requests to something unique to your application or integration. This could include a version number as well.

User-Agent: my-plugin/v1.2.5

Contact us to find out how much your integration is being used!


Notes and Additional Considerations

  • The CloudShark API allows additional comments, tags, and a filename to be specified at the time the of upload. Your application's interface may wish to provide that functionality on a per-capture basis, or globally for all captures.

  • If your device does live packet-capture, or some kind of interactive capture, we recommend being able to limit the size/duration of that capture by specifying some termination criteria. “Stop after capturing X bytes” or “Stop after Y seconds” are common ways to implement termination criteria. Upon completion, the file is transmitted to CloudShark, and the resulting session URL is presented to the user, or stored for later use.

  • You may want to allow your user to specify a BPF filter to limit the traffic that is captured before sending it to CloudShark. This makes it very easy to isolate traffic from certain hosts, or certain kinds of flows (udp, tcp, port 80, etc) as well as limit the amount of traffic necessary to upload.

  • Your application can generate a capture file either in memory, temporary storage, or stream the file to CloudShark. The streaming approach requires starting a HTTP Request and writing an initial pcap header. Additional packets can be sent as part of the HTTP Request using chunked-encoding. CloudShark should receive a chunk of data at least every 60-seconds to avoid the server terminating the connection.

Full API documentation and examples are available at
https://support.cloudshark.io/api.