Integration Guide

View, share, and analyze your application's PCAP data in CloudShark

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!

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.


Get started for free in under 2 minutes...

Step 1. Create a CloudShark account

This is the easiest part! Visit CloudShark.org and sign up with your email address to create an account. We'll send you a confirmation code to let you pick a password and log in.

Step 2. Get an API Token

You can find your API token 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.

When it comes time to release your integration, your customers will provide their own API Token so that uploads go to their account.

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. Show & 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-Premise

CloudShark Enterprise is preferred by our more security conscious customers. They deploy their own on-premise CloudShark Appliance 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, the SaaS model of CloudShark is more appealing. Your end-users have the choice of signing up for either a CloudShark Personal or CloudShark Business subscription plan. These plans are detailed on our website.

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 the hosted CloudShark service 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 should 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 Hosted accounts this will be https://www.cloudshark.org however, CloudShark Enterprise customers may have a private domain they want to use instead.

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 CloudShark 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.org/api.

About Us

CloudShark is made by QA Cafe, a technology company based in Portsmouth, NH. Our passion for packet captures has grown out of our other product CDRouter.

Get in touch via our Contact us page or by following us on your favorite service: