Access the SDKs

Java SDK Tutorial

Getting Started

The Contrast Java SDK requires the following:

  • JDK 7 / 8
  • TeamServer account

There are a few ways to make use of the Contrast Java SDK. If you are using a Maven or Gradle-based project, the easiest way to begin using the SDK is to add it as a dependency to your pom.xml or build.gradle file, respectively.

Maven Example

<dependencies>
    <dependency>
        <groupId>com.contrastsecurity</groupId>
        <artifactId>contrast-sdk-java</artifactId>
        <version>2.1.0</version>
    </dependency>
</dependencies>

Gradle Example

repositories {
    mavenCentral()
}

dependencies {
    compile group: "com.contrastsecurity", name: "contrast-sdk-java", version:"2.1.0"
}

If you are not using one of the above build tools you can still make use of the Contrast Java SDK by cloning the repository from GitHub and creating the jar. To clone the repository and generate the jar use the following command:

git clone https://github.com/Contrast-Security-OSS/contrast-sdk-java.git
cd /contrast-sdk-java
mvn install

The jar can then be located within the target directory and configured within your own project.

Common Tasks Within Plugins

The first thing you are likely to do when creating the plugin is to create an instance of the Contrast SDK. The SDK has two constructors which require a username, apiKey, serviceKey, and (optionally) an apiUrl. Your username, apiKey and serviceKey can be found within your instance of TeamServer.

String username = "contrast_username";
String apiKey = "123456789-1234-1234-123456";
String serviceKey = "123456789-1234-1234-123456";
ContrastSDK contrastSDK = new ContrastSDK(username, apiKey, serviceKey);

In order to make use of a variety of functions you will also need your organization UUID. This is found within TeamServer by clicking your username in the upper right corner of the screen and selecting Organization Settings in the dropdown. Your UUID can be found on the right side of the General Information header bar.

If you would like to retrieve a collection of your applications, the following code snippet makes use of the ContrastSDK in order to do so:

String orgUuid = "12345678-1234-1234-1234-123456789ABC";
try {
    Applications applications = contrastSDK.getApplications(orgUuid);
        for (Application application : applications.getApplications()) {
            System.out.println("App name: "  + application.getName());
            System.out.println("App id: " + application.getId());
        }
    }catch (IOException e) {
        System.out.println("Unable to retrieve the applications.");
    } catch (UnauthorizedException e) {
        System.out.println("Unable to connect to TeamServer.");
    }
}

A similar pattern can be used to retrieve the servers associated with your organization. When calling the getServers method of the ContrastSDK class, you need to pass along a ServerFilterForm object. In the example below, the object has not been given any specific filters so it will retrieve all servers associated with your organization.

String orgUuid = "12345678-1234-1234-1234-123456789ABC";
try {
    Server servers = contrastSDK.getServers(orgUuid, new ServerFilterForm());
    for(Server server : servers.getServers()){
        System.out.println("Server status: " + server.getStatus());
        System.out.println("Server name: " + server.getName());
    }
} catch (IOException e) {
    System.out.println("Unable to retrieve the servers");
} catch (UnauthorizedException e) {
    System.out.println("Unable to connect to TeamServer");
}

The ContrastSDK can also retrieve a list of your organizations and a variety of their properties, including the UUID.

try {
      Organizations orgs =  contrastSDK.getProfileOrganizations();
      for(Organization org : orgs.getOrganizations()){
        System.out.println("Org name: " + org.getName());
        System.out.println("Org UUID :" + org.getOrgUuid());
      }
} catch (IOException e) {
    System.out.println("Unable to retrieve the organizations.");
} catch (UnauthorizedException e) {
    System.out.println("Unable to connect to TeamServer");
}

Oftentimes you will be a member of only one organization. In order to easily get a reference to that object as opposed to iterating over the collection of organizations, you can use the following snippet:

Organization myOrg = contrastSDK.getProfileDefaultOrganizations().getOrganization();

One of the most valuable features of the SDK is the ability to gather a list of vulnerabilities from a given application. The following code will gather all Medium, High, or Critical severity vulnerabilities that have been found for an application:

String appId = "12345678912312313123";
String serverId = "1234";
String orgUuid = "12345678-1234-1234-1234-123456789ABC";
FilterForm form = new FilterForm();
form.setSeverities(Arrays.asList("Medium", "High", "Critical"));
Traces traces = null;

try {
    traces = contrastSDK.getTracesWithFilter(orgUuid, appId, "servers", serverId, form);
} catch (IOException e) {
    System.out.println("Unable to retrieve the traces.");
} catch (UnauthorizedException e) {
    System.out.println("Unable to connect to TeamServer.");
}

if (traces != null && traces.getCount() > 0) {
    for (Trace trace : traces.getTraces()) {
        System.out.println("Rule: " + trace.getRule());
        System.out.println("Severity: " + trace.getSeverity());
    }
}

Writing Tests

The type of plugin you are building will have a lot of impact on the type of tests you will write. One key point you will probably want to cover is ensuring that invalid configuration data fails. The Contrast Gradle plugin generates an extension for use in the build.gradle file. One such test would be ensuring that the appropriate extension is generated and is an instance of the appropriate class. If you are creating any specific tasks or goals depending on your build tool, you should check that the appropriate tasks are actually being added to the build process. If you are developing for Gradle, it is important to be aware of task naming collisions that may occur if you choose a more generic name as opposed to a domain-specific task naming convention.

Python SDK Tutorial

Install

The Contrast Python module is available to install via pip.

pip install contrast-security

Sample usage

The SDK offers a majority of our public APIs through an instance of the ContrastSDK object.

Note: The Contrast URL is optional and defaults to https://app.contrastsecurity.com.

from contrast_security.contrast_sdk import ContrastSdk
contrast_sdk = ContrastSdk('username','api_key','service_key','teamserver_url')

An example of getting an application:

org_uuid='organization_uuid'
contrast_sdk.get_application(org_uuid, 'an_app_id')

In some cases, you may want to filter applications, servers, traces or libraries. Any endpoint that involves filtering can use the appropriate filter object.

These methods are easily identifiable on the ContrastSDK object by looking at any methods that include the phrase filter.

from contrast_security.filters.library_filter import LibraryFilter
library_filter = LibraryFilter()
library_filter.apps = ['app_id_1','app_id_2']
library_filter.expand = ['vulns','apps']
contrast_sdk.filter_libraries(my_org_uuid, library_filter)

You can easily use the responses as a Python dictionary by using the .json() method of the response:

librariesResponse = contrast_sdk.filter_libraries(org_uuid, library_filter).json()

for index, lib in enumerate(librariesResponse['libraries']):
    print(lib['name'], lib['grade'])

Developing

Use pip to install the projects dependencies:

pip install -r requirements.txt

To run the tests, create a file in the /tests directory called test-config.json with local Contrast information. An example test configuration can be seen in tests/test-config.json.example.

Note: The URL validation doesn't accept localhost as a Contrast URL. If you're running Contrast locally, use http://127.0.0.1:19080 as your teamserver_url.

Then run tests with nosetests.