CloudShark includes an API which provides an easy way to programmatically upload captures to your CloudShark appliance directly from third party tools and scripts. This API is intended for advanced users and developers interested in integrating CloudShark into their existing network infrastructure.
If you are just getting started with the CloudShark appliance, we recommend reviewing the Quick Start Guide first. It includes information on the installation and initial setup of your new CloudShark appliance.
All access to the API is based on and controlled by API tokens that can be managed by members of the CloudShark Admin group, or by all users if enabled in the settings.
Administrator should visit the API Tokens link in the Administration menu at the top of your screen.
Regular users will see a new API Tokens link from their Preferences menu at the top of the screen and a new dialog listing their current tokens.
An API token is a 32-character string that represents a set of options that define how access is handled. Think of them as a username/password and protect them as such. When a token is used to access CloudShark, it has the same permissions as would a user logging in with the same credentials.
API tokens are very similar to Auto-Imports in that they define the user, group, and permissions that will be associated with a capture file. A default set of tags can also be applied to API token uploads. There is no limit on the number of API tokens that can be created.
Here you can see an example API token being configured. It’s for our new script that imports capture files and stores the link to CloudShark in our bug-tracking system.
Because “billy” is the head of the QA team, he’s in control of all the capture files. We set him as the owner when setting up the token, and every capture file that is uploaded using this token gets assigned to him.
However, we also want any member of the staff group to be able to look at these captures as well. We set the group field accordingly.
When we press Create, we get back a 32-character token that can now be used in our scripts.
API tokens can be configured with or without user authentication. Authenticated tokens require users to log in to the CloudShark appliance before they can be used. Non-authenticated tokens can be used at any time without requiring authentication.
As we described above, anybody with access to the 32-character token essentially has access to the CloudShark appliance as that person. They can upload captures with it. For this reason, it is best that non-authenticated tokens like this one are used in scripts or other closed-source tools so that the end-user doesn’t see them.
In situations where the token can’t be hidden from view, authenticated tokens are useful for controlling access to the CloudShark appliance. For example, with the open API method, API tokens are visible as part of the URL. Requiring authentication in this case ensures that the tokens cannot be used by unauthorized individuals for uploading files to the CloudShark appliance.
Administrators can allow users to define their own API Tokens if it makes sense for their environment. If you have a lot of users, or users are doing a lot of API dependent things, it may be easier to give them the ability to manage their own tokens.
As an Admin user, on the Settings page, you will see a new option to enable user-defined API Tokens.
This setting is OFF by default and was added in CloudShark 2.3. Click the check-box to enable it for all users logged into CloudShark.