com.contrastsecurity.sdk

Class ContrastSDK

java.lang.Object

com.contrastsecurity.sdk.ContrastSDK

public class ContrastSDK
extends java.lang.Object

Entry point for using the Contrast REST API. Make an instance of this class and call methods. Easy!

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_CONNECTION_TIMEOUT Default connection timeout.
static int	DEFAULT_READ_TIMEOUT Default read timeout.

Constructor Summary

Constructors

Constructor and Description
ContrastSDK()
ContrastSDK(java.lang.String user, java.lang.String serviceKey, java.lang.String apiKey) Create a ContrastSDK object to use the Contrast V3 API
ContrastSDK(java.lang.String user, java.lang.String serviceKey, java.lang.String apiKey, java.lang.String restApiURL) Create a ContrastSDK object to use the Contrast V3 API
ContrastSDK(java.lang.String user, java.lang.String serviceKey, java.lang.String apiKey, java.lang.String restApiURL, java.net.Proxy proxy) Create a ContrastSDK object to use the Contrast V3 API through a Proxy.

Method Summary

Modifier and Type	Method and Description
Application	createApplication(java.lang.String organizationId, ApplicationCreateRequest request) Creates an application without a server that is meant to be instrumented later.
void	generateAttestationReport(java.lang.String organizationId, java.lang.String appId, AttestationCreateRequest request) Generate an attestation report for the application whose ID is passed in.
byte[]	getAgent(AgentType type, java.lang.String organizationId) Download a contrast.jar agent associated with this account.
byte[]	getAgent(AgentType type, java.lang.String organizationId, java.lang.String profileName) Download a contrast.jar agent associated with this account.
Applications	getApplication(java.lang.String organizationId, java.lang.String appId) Get summary information about a single app without expandValues.
Applications	getApplication(java.lang.String organizationId, java.lang.String appId, java.util.EnumSet<FilterForm.ApplicationExpandValues> expandValues) Get summary information about a single app.
Application	getApplicationByNameAndLanguage(java.lang.String orgId, java.lang.String appName, AgentType language) Gets a single application based on the org, name, and language
Applications	getApplications(java.lang.String organizationId) Get the list of applications being monitored by Contrast.
Applications	getApplicationsNames(java.lang.String organizationId)
AssessLicenseOverview	getAssessLicensing(java.lang.String organizationId) Get all Assess Licensing for an Organizations.
Coverage	getCoverage(java.lang.String organizationId, java.lang.String appId) Return coverage data about the monitored Contrast application.
Libraries	getLibraries(java.lang.String organizationId, java.lang.String appId)
Libraries	getLibraries(java.lang.String organizationId, java.lang.String appId, java.util.EnumSet<FilterForm.LibrariesExpandValues> expandValues) Return the libraries of the monitored Contrast application.
LibraryScores	getLibraryScores(java.lang.String organizationId) Return the library Scores for an Organization.
LibraryStats	getLibraryStats(java.lang.String organizationId) Return the library Stats for an Organization.
Applications	getLicensedApplications(java.lang.String organizationId) Get the list of licensed applications being monitored by Contrast.
TraceNotesResponse	getNotes(java.lang.String organizationId, java.lang.String appId, java.lang.String traceId, TraceFilterForm form) Get the notes (discussion) for the vulnerability ID in the application whose ID is passed in.
Users	getOrganizationUsers(java.lang.String organizationId) Get all users for an organization.
Organizations	getProfileDefaultOrganizations() Get the default organization for the user profile.
Organizations	getProfileOrganizations() Get all organizations for the user profile.
Rules	getRules(java.lang.String organizationId) Get the rules for an organization
Servers	getServers(java.lang.String organizationId, ServerFilterForm filterForm) Return the servers of the monitored Contrast application.
Servers	getServersWithFilter(java.lang.String organizationId, ServerFilterForm filterForm) Return the servers of the monitored Contrast application.
MetadataFilterResponse	getSessionMetadataForApplication(java.lang.String organizationId, java.lang.String appId, TraceFilterForm form) Get the available session metadata values in the application whose ID is passed in.
Traces	getTraceFilterByRule(java.lang.String organizationId, java.lang.String appId, java.util.List<java.lang.String> ruleNames) Deprecated.
TraceListing	getTraceFilters(java.lang.String organizationId, java.lang.String appId) Get the filters for the traces in the application.
Traces	getTraces(java.lang.String organizationId, java.lang.String appId, TraceFilterForm form) Get the vulnerabilities in the application whose ID is passed in.
Traces	getTracesInOrg(java.lang.String organizationId, TraceFilterForm form) Get the vulnerabilities in the organization whose ID is passed in.
Traces	getTracesWithFilter(java.lang.String organizationId, java.lang.String appId, TraceFilterType traceFilterType, TraceFilterKeycode keycode, TraceFilterForm form) Get the vulnerabilities in the application whose ID is passed in with a filter.
TagsResponse	getVulnTagsByApplication(java.lang.String organizationId, java.lang.String appId) Get the available vulnerability tags in the application whose ID is passed in.
VulnerabilityTrend	getYearlyNewVulnTrend(java.lang.String organizationId) Get all Vulnerability Trend for an Organizations.
VulnerabilityTrend	getYearlyVulnTrend(java.lang.String organizationId) Get all Vulnerability Trend for an Organizations.
java.net.HttpURLConnection	makeConnection(java.lang.String url, java.lang.String method)
java.io.InputStream	makeRequest(HttpMethod method, java.lang.String path)
void	setConnectionTimeout(int timeout) Sets a custom connection timeout for all SDK requests.
void	setReadTimeout(int timeout) Set a custom read timeout for all SDK requests.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_CONNECTION_TIMEOUT

public static final int DEFAULT_CONNECTION_TIMEOUT

Default connection timeout. If connection timeout its set to this value, custom timeout will be ignored and requests will take the default value that its usually assigned to them.

See Also:

Constant Field Values

DEFAULT_READ_TIMEOUT

public static final int DEFAULT_READ_TIMEOUT

Default read timeout. If read timeout its set to this value, custom timeout will be ignored and requests will take default value that its usually assigned to them.

See Also:

Constant Field Values

Constructor Detail

ContrastSDK

public ContrastSDK()

ContrastSDK

public ContrastSDK(java.lang.String user,
                   java.lang.String serviceKey,
                   java.lang.String apiKey,
                   java.lang.String restApiURL)
            throws java.lang.IllegalArgumentException

Create a ContrastSDK object to use the Contrast V3 API

Parameters:

user - Username (e.g., joe@acme.com)

serviceKey - User service key

apiKey - API Key

restApiURL - the base Contrast API URL

Throws:

java.lang.IllegalArgumentException - if the API URL is malformed

ContrastSDK

public ContrastSDK(java.lang.String user,
                   java.lang.String serviceKey,
                   java.lang.String apiKey,
                   java.lang.String restApiURL,
                   java.net.Proxy proxy)
            throws java.lang.IllegalArgumentException

Create a ContrastSDK object to use the Contrast V3 API through a Proxy.

Parameters:

user - Username (e.g., joe@acme.com)

serviceKey - User service key

apiKey - API Key

restApiURL - the base Contrast API URL

proxy - Proxy to use

Throws:

java.lang.IllegalArgumentException - if the API URL is malformed

ContrastSDK

public ContrastSDK(java.lang.String user,
                   java.lang.String serviceKey,
                   java.lang.String apiKey)

Create a ContrastSDK object to use the Contrast V3 API

This will use the default api url which is https://app.contrastsecurity.com/Contrast/api

Parameters:

user - Username (e.g., joe@acme.com)

serviceKey - User service key

apiKey - API Key

Method Detail

getAssessLicensing

public AssessLicenseOverview getAssessLicensing(java.lang.String organizationId)
                                         throws java.io.IOException,
                                                UnauthorizedException

Get all Assess Licensing for an Organizations.

Parameters:

organizationId - the ID of the organization

Returns:

AssessLicenseOverview with Assess Licensing for an Oeg.

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getYearlyVulnTrend

public VulnerabilityTrend getYearlyVulnTrend(java.lang.String organizationId)
                                      throws java.io.IOException,
                                             UnauthorizedException

Get all Vulnerability Trend for an Organizations.

Parameters:

organizationId - the ID of the organization

Returns:

VulnerabilityTrend with the yearly Vulnerability Trend for an Oeg.

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getYearlyNewVulnTrend

public VulnerabilityTrend getYearlyNewVulnTrend(java.lang.String organizationId)
                                         throws java.io.IOException,
                                                UnauthorizedException

Get all Vulnerability Trend for an Organizations.

Parameters:

organizationId - the ID of the organization

Returns:

VulnerabilityTrend with the yearly Vulnerability Trend for an Oeg.

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getProfileOrganizations

public Organizations getProfileOrganizations()
                                      throws java.io.IOException,
                                             UnauthorizedException

Get all organizations for the user profile.

Returns:

Organization objects with a list of disabled and valid organizations for the user.

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getOrganizationUsers

public Users getOrganizationUsers(java.lang.String organizationId)
                           throws java.io.IOException,
                                  UnauthorizedException

Get all users for an organization.

Parameters:

organizationId - the ID of the organization

Returns:

A List of User Objects.

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getProfileDefaultOrganizations

public Organizations getProfileDefaultOrganizations()
                                             throws java.io.IOException,
                                                    UnauthorizedException

Get the default organization for the user profile.

Returns:

Organization object with the default Organizaiton.

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

createApplication

public Application createApplication(java.lang.String organizationId,
                                     ApplicationCreateRequest request)
                              throws java.io.IOException,
                                     UnauthorizedException,
                                     ApplicationCreateException

Creates an application without a server that is meant to be instrumented later.

Parameters:

organizationId -

request -

Returns:

Throws:

java.io.IOException

UnauthorizedException

ApplicationCreateException

getApplicationByNameAndLanguage

public Application getApplicationByNameAndLanguage(java.lang.String orgId,
                                                   java.lang.String appName,
                                                   AgentType language)
                                            throws java.io.IOException,
                                                   UnauthorizedException

Gets a single application based on the org, name, and language

Parameters:

orgId - ID of the organization

appName - Application name when the application was first created

language - Language of the application

Returns:

the Application found, returns null if the application is not found

Throws:

java.io.IOException

UnauthorizedException

getApplication

public Applications getApplication(java.lang.String organizationId,
                                   java.lang.String appId)
                            throws java.io.IOException,
                                   UnauthorizedException

Get summary information about a single app without expandValues.

Parameters:

organizationId - the ID of the organization

appId - the ID of the application

Returns:

Applications object that contains one Application; wrapper

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getApplication

public Applications getApplication(java.lang.String organizationId,
                                   java.lang.String appId,
                                   java.util.EnumSet<FilterForm.ApplicationExpandValues> expandValues)
                            throws java.io.IOException,
                                   UnauthorizedException

Get summary information about a single app.

Parameters:

organizationId - the ID of the organization

appId - the ID of the application

expandValues - Expand values to filter on

Returns:

Applications object that contains one Application; wrapper

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getApplications

public Applications getApplications(java.lang.String organizationId)
                             throws UnauthorizedException,
                                    java.io.IOException

Get the list of applications being monitored by Contrast.

Parameters:

organizationId - the ID of the organization

Returns:

Applications object that contains the list of Application's

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getLicensedApplications

public Applications getLicensedApplications(java.lang.String organizationId)
                                     throws UnauthorizedException,
                                            java.io.IOException

Get the list of licensed applications being monitored by Contrast.

Parameters:

organizationId - the ID of the organization

Returns:

Applications object that contains the list of Application's

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getApplicationsNames

public Applications getApplicationsNames(java.lang.String organizationId)
                                  throws UnauthorizedException,
                                         java.io.IOException

Throws:

UnauthorizedException

java.io.IOException

getCoverage

public Coverage getCoverage(java.lang.String organizationId,
                            java.lang.String appId)
                     throws java.io.IOException,
                            UnauthorizedException

Return coverage data about the monitored Contrast application.

Parameters:

organizationId - the ID of the organization

appId - the ID of the application

Returns:

Coverage object for the given app

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getLibraries

public Libraries getLibraries(java.lang.String organizationId,
                              java.lang.String appId)
                       throws java.io.IOException,
                              UnauthorizedException

Throws:

java.io.IOException

UnauthorizedException

getLibraries

public Libraries getLibraries(java.lang.String organizationId,
                              java.lang.String appId,
                              java.util.EnumSet<FilterForm.LibrariesExpandValues> expandValues)
                       throws java.io.IOException,
                              UnauthorizedException

Return the libraries of the monitored Contrast application.

Parameters:

organizationId - the ID of the organization

appId - the ID of the application

expandValues - Query params to add more info to response

Returns:

Libraries object that contains the list of Library objects

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getLibraryScores

public LibraryScores getLibraryScores(java.lang.String organizationId)
                               throws java.io.IOException,
                                      UnauthorizedException

Return the library Scores for an Organization.

Parameters:

organizationId - the ID of the organization

Returns:

LibraryScores object that contains the Library scores for an Org

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getLibraryStats

public LibraryStats getLibraryStats(java.lang.String organizationId)
                             throws java.io.IOException,
                                    UnauthorizedException

Return the library Stats for an Organization.

Parameters:

organizationId - the ID of the organization

Returns:

LibraryScores object that contains the Library stats for an Org

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getServers

public Servers getServers(java.lang.String organizationId,
                          ServerFilterForm filterForm)
                   throws java.io.IOException,
                          UnauthorizedException

Return the servers of the monitored Contrast application.

Parameters:

organizationId - the ID of the organization

filterForm - FilterForm query parameters

Returns:

Servers object that contains the list of Library objects

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getServersWithFilter

public Servers getServersWithFilter(java.lang.String organizationId,
                                    ServerFilterForm filterForm)
                             throws java.io.IOException,
                                    UnauthorizedException

Return the servers of the monitored Contrast application.

Parameters:

organizationId - the ID of the organization

filterForm - FilterForm query parameters

Returns:

Servers object that contains the list of Library objects

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getTraces

public Traces getTraces(java.lang.String organizationId,
                        java.lang.String appId,
                        TraceFilterForm form)
                 throws java.io.IOException,
                        UnauthorizedException

Get the vulnerabilities in the application whose ID is passed in.

Parameters:

organizationId - the ID of the organization

appId - the ID of the application

form - FilterForm query parameters

Returns:

Traces object that contains the list of Trace's

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getNotes

public TraceNotesResponse getNotes(java.lang.String organizationId,
                                   java.lang.String appId,
                                   java.lang.String traceId,
                                   TraceFilterForm form)
                            throws java.io.IOException,
                                   UnauthorizedException

Get the notes (discussion) for the vulnerability ID in the application whose ID is passed in.

Parameters:

organizationId - the ID of the organization

appId - the ID of the application

traceId - the ID of the vulnerability

form - FilterForm query parameters

Returns:

Traces object that contains the list of Trace's

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getVulnTagsByApplication

public TagsResponse getVulnTagsByApplication(java.lang.String organizationId,
                                             java.lang.String appId)
                                      throws java.io.IOException,
                                             UnauthorizedException

Get the available vulnerability tags in the application whose ID is passed in.

Parameters:

organizationId - the ID of the organization

appId - the ID of the application

Returns:

TagsResponse object that contains the list of Tags

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getSessionMetadataForApplication

public MetadataFilterResponse getSessionMetadataForApplication(java.lang.String organizationId,
                                                               java.lang.String appId,
                                                               TraceFilterForm form)
                                                        throws java.io.IOException,
                                                               UnauthorizedException

Get the available session metadata values in the application whose ID is passed in.

Parameters:

organizationId - the ID of the organization

appId - the ID of the application

form - FilterForm query parameters

Returns:

Traces object that contains the list of Trace's

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

generateAttestationReport

public void generateAttestationReport(java.lang.String organizationId,
                                      java.lang.String appId,
                                      AttestationCreateRequest request)
                               throws java.io.IOException,
                                      UnauthorizedException,
                                      ApplicationCreateException

Generate an attestation report for the application whose ID is passed in.

Parameters:

organizationId - the ID of the organization

appId - the ID of the application

request -

Throws:

java.io.IOException

UnauthorizedException

ApplicationCreateException

getTracesInOrg

public Traces getTracesInOrg(java.lang.String organizationId,
                             TraceFilterForm form)
                      throws java.io.IOException,
                             UnauthorizedException

Get the vulnerabilities in the organization whose ID is passed in.

Parameters:

organizationId - the ID of the organization

form - FilterForm query parameters

Returns:

Traces object that contains the list of Trace's

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getTraceFilters

public TraceListing getTraceFilters(java.lang.String organizationId,
                                    java.lang.String appId)
                             throws java.io.IOException,
                                    UnauthorizedException

Get the filters for the traces in the application.

Parameters:

organizationId - the ID of the organization

appId - the ID of the application

Returns:

TraceListing object that contains the trace filters for the application

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getTracesWithFilter

public Traces getTracesWithFilter(java.lang.String organizationId,
                                  java.lang.String appId,
                                  TraceFilterType traceFilterType,
                                  TraceFilterKeycode keycode,
                                  TraceFilterForm form)
                           throws java.io.IOException,
                                  UnauthorizedException

Get the vulnerabilities in the application whose ID is passed in with a filter.

Parameters:

organizationId - the ID of the organization

appId - the ID of the application

traceFilterType - filter type

keycode - id or key to filter on

form - FilterForm query parameters

Returns:

Traces object that contains the list of Trace's

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getTraceFilterByRule

@Deprecated
public Traces getTraceFilterByRule(java.lang.String organizationId,
                                               java.lang.String appId,
                                               java.util.List<java.lang.String> ruleNames)
                                        throws java.io.IOException,
                                               UnauthorizedException

Deprecated.

Get the vulnerabilities in the application by the rule.

Parameters:

organizationId - the ID of the organization

appId - the ID of the application

ruleNames - FilterForm query parameters

Returns:

Traces object that contains the list of Trace's

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getRules

public Rules getRules(java.lang.String organizationId)
               throws java.io.IOException,
                      UnauthorizedException

Get the rules for an organization

Parameters:

organizationId - the ID of the organization

Returns:

Traces object that contains the list of Trace's

Throws:

UnauthorizedException - if the Contrast account failed to authorize

java.io.IOException - if there was a communication problem

getAgent

public byte[] getAgent(AgentType type,
                       java.lang.String organizationId,
                       java.lang.String profileName)
                throws java.io.IOException,
                       UnauthorizedException

Download a contrast.jar agent associated with this account. The user should save this byte array to a file named 'contrast.jar'. This signature takes a parameter which contains the name of the saved engine profile to download.

Parameters:

type - the type of agent you want to download; Java, Java 1.5, .NET, or Node

profileName - the name of the saved engine profile to download,

organizationId - the ID of the organization,

Returns:

a byte[] array of the contrast.jar file contents, which the user should convert to a new File

Throws:

java.io.IOException - if there was a communication problem

UnauthorizedException - if authentication fails

getAgent

public byte[] getAgent(AgentType type,
                       java.lang.String organizationId)
                throws java.io.IOException,
                       UnauthorizedException

Download a contrast.jar agent associated with this account. The user should save this byte array to a file named 'contrast.jar'. This signature takes a parameter which contains the name of the saved engine profile to download.

This uses 'default' as the profile name.

Parameters:

type - the type of agent you want to download; Java, Java 1.5, .NET, or Node

organizationId - the ID of the organization,

Returns:

a byte[] array of the contrast.jar file contents, which the user should convert to a new File

Throws:

java.io.IOException - if there was a communication problem

UnauthorizedException - if authentication fails

makeRequest

public java.io.InputStream makeRequest(HttpMethod method,
                                       java.lang.String path)
                                throws java.io.IOException,
                                       UnauthorizedException

Throws:

java.io.IOException

UnauthorizedException

makeConnection

public java.net.HttpURLConnection makeConnection(java.lang.String url,
                                                 java.lang.String method)
                                          throws java.io.IOException

Throws:

java.io.IOException

setConnectionTimeout

public void setConnectionTimeout(int timeout)

Sets a custom connection timeout for all SDK requests. This value must be set before a call to makeConnection is done.

Parameters:

timeout - Timeout value in milliseconds.

setReadTimeout

public void setReadTimeout(int timeout)

Set a custom read timeout for all SDK requests. This value must be set before calling makeConnection method in order to take effect.

Parameters:

timeout - TImeout value in milliseconds