About the Contrast API

Contrast has a few API versions:

  • Engine APIs (v1)
  • Application APIs (v2)
  • HATEOS-compliant REST API (v3) Recommended

Note: We haven't officially deprecated v1 or v2, but strongly recommend using v3.

Overview

The Contrast plugin allows you to collect nearly all the same information that is accessible through the Contrast UI. You can get vulnerability data, application, server and library information, download agents and much more.

The API is available to both SaaS and Enterprise On-Premises users. The endpoint for SaaS users is the same for everyone, while for On-Premise users it will depend on where the TeamServer application is installed on the client's network.

Our goal is to make sure Contrast offers data to allow complete integration into your existing Continuous Integration (CI), SIEM software, or other business intelligence dashboards. We're always adding more endpoints, but if you'd like to see something added to the API, file a ticket and let's talk about it!

Note: The set of APIs is subject to change at any time, uses different keys, and in general is more about writing data to your Contrast account.

Open API Documentation

All of Contrast's public API endpoints can be viewed online. We’ve provided open API documentation that provides resources in understanding how to use the endpoints and help you along with authenticating, navigating, collecting data and taking actions on TeamServer programmatically. This guidance is built continuously and stays current with our latest SaaS release. The same documentation can also be found embedded in the Contrast UI for both SaaS and EOP customers. Simply authenticate with an administrator account in Contrast, select Settings, then select API.

Using the Documentation

Endpoints and the related objects used by the endpoints are listed under “API” and “Objects”. “Flow” provides a list of sample use cases and the information of their sequence of endpoints that need be called to accomplish them.

The documentation also includes a playground to test your endpoint interactions. This is a handy tool to quickly learn how to use the endpoints through experience. The documentation is comprehensive, as it includes endpoints for v1, v2 and v3 API endpoints.

Engine API

Data Objects

Profile

Profile represents the configuration used by an Agent to report to either the SaaS or your local instance of TeamServer.

Fields

Field Type Description
name string The name of the profile
log-level string The lowest level of events to log
log-file string The path of the file to which to save the logs
use-proxy boolean Indicates whether or not the agent will need a proxy to communicate with the TeamServer
proxy-host string The host name of the proxy through which the agent needs to communicate in order to reach the TeamServer
proxy-port int The port number of the proxy through which the agent needs to communicate in order to reach the TeamServer
proxy-auth string The type of authentication used by the proxy through which the agent needs to communicate in order to reach the TeamServer
proxy-user string The user name to be given to the proxy through which the agent needs to communicate in order to reach the TeamServer
proxy-password string The encoded password to be give to the proxy through which the agent needs to communicate in order to reach the TeamServer
sampling-baseline int How many times a URL needs to be analyzed before it is considered sampled by the agent
sampling-window int How many seconds a sample of a URL is considered valid by the agent
sampling-frequency int The frequency with which sampled URLs will be reanalyzed by the agent
* stacktrace-capture-mode string The capture mode of stack traces - All, Some, or None
override-teamserver-url boolean Whether or not the agent should override the default TeamServer URL and use the one included in this profile
teamserver-url string The URL the agent will use in order to reach the TeamServer
engine-type string The engine-type indicates the type of language for which the Agent was designed. It MUST be JAVA, DOTNET_x86, or DOTNET_x64 and MUST BE INCLUDED

Note: A stacktrace-capture-mode of Some indicates that traces are only saved for the first and last events of a Trace

API Operations

Retrieve Profiles

Retrieve Profiles retrieves a list of user Profiles.

Resource URI:

GET https://app.contrastsecurity.com/Contrast/api/engine/profiles

Request: Static URL that doesn't have any custom parameters.

Sample request:

curl -HAccept:application/json -HAPI-Key:test -HAuthorization:dGVzdF91c2VyOnRlc3Q= https://app.contrastsecurity.com/Contrast/api/engine/profiles

Response: Returns a collection of Profile objects.

Sample response:

[ {
    "name" : "NEW PROFILE",
    "id" : {
     "rel" : "self",
     "href" : "https://app.contrastsecurity.com/Contrast/api/engine/profiles/NEW%20PROFILE",
     "method" : "GET"
     },
     "link" : [ {
         "rel" : "download",
         "href" : "https://app.contrastsecurity.com/Contrast/api/engine/NEW%20PROFILE",
         "method" : "GET"
    }, {
        "rel" : "self",
        "href" : "https://app.contrastsecurity.com/Contrast/api/engine/profiles/NEW%20PROFILE",
        "method" : "GET"
    }, {
        "rel" : "update",
        "href" : "https://app.contrastsecurity.com/Contrast/api/engine/profiles/NEW%20PROFILE",
        "method" : "PUT"
    } ],
    "sampling-baseline" : 5,
    "sampling-window" : 180,
     "sampling-frequency" : 10,
     "log-level" : "fatal",
     "log-file" : "/log/file/path",
     "proxy-host" : "localhost",
     "proxy-auth" : "Basic",
     "proxy-user" : "user_name",
     "proxy-pass" : "wdYYyn3+5QkUV264KmSv9w==",
     "proxy-port" : 8080,
     "stacktrace-capture-mode" : "ALL",
     "use-proxy" : true,
     "override-teamserver-url" : false,
     "engine-type" : "JAVA"
    }, {
     "name" : "default",
     "id" : {
         "rel" : "self",
         "href" : "https://app.contrastsecurity.com/Contrast/api/engine/profiles/default",
         "method" : "GET"
     },
     "link" : [ {
         "rel" : "download",
         "href" : "https://app.contrastsecurity.com/Contrast/api/engine/default",
         "method" : "GET"
     }, {
         "rel" : "self",
         "href" : "https://app.contrastsecurity.com/Contrast/api/engine/profiles/default",
         "method" : "GET"
     }, {
         "rel" : "update",
         "href" : "https://app.contrastsecurity.com/Contrast/api/engine/profiles/default",
          "method" : "PUT"
     } ],
     "sampling-baseline" : 5,
     "sampling-window" : 180,
     "sampling-frequency" : 10,
     "stacktrace-capture-mode" : "ALL",
     "use-proxy" : false,
     "override-teamserver-url" : false,
     "engine-type" : "JAVA"
} ]

Send Profiles

Send Profiles sends a Profile created by the user.

Resource URI:

POST https://app.contrastsecurity.com/Contrast/api/engine/profiles

Request: Static URL that doesn't have any custom parameters.

Sample request:

curl -HAccept:application/json -HAPI-Key:test -HAuthorization:dGVzdF91c2VyOnRlc3Q= https://app.contrastsecurity.com/Contrast/api/engine/profiles --data "{"name":"REST PROFILE","sampling-baseline":5,"sampling-window":180,"sampling-frequency":10,"log-level":"","log-file":"","proxy-host":"","proxy-auth":"","proxy-user":"","proxy-pass":"","proxy-port":"","teamserver-url":"","stacktrace-capture-mode":"ALL","use-proxy":false,"override-teamserver-url":false,"engine-type":"JAVA"}"

Response: Returns the sent Profile object.

Sample response:

{
    "name" : "REST PROFILE",
    "id" : {
    "rel" : "self",
    "href" : "https://app.contrastsecurity.com/Contrast/api/engine/profiles/REST%20PROFILE",
     "method" : "GET"
     },
     "link" : [ {
         "rel" : "download",
         "href" : "https://app.contrastsecurity.com/Contrast/api/engine/REST%20PROFILE",
         "method" : "GET"
     }, {
         "rel" : "self",
         "href" : "https://app.contrastsecurity.com/Contrast/api/engine/profiles/REST%20PROFILE",
         "method" : "GET"
     }, {
         "rel" : "update",
         "href" : "https://app.contrastsecurity.com/Contrast/api/engine/profiles/REST%20PROFILE",
         "method" : "PUT"
     } ],
     "sampling-baseline" : 5,
     "sampling-window" : 180,
     "sampling-frequency" : 10,
     "log-level" : "",
     "log-file" : "",
     "proxy-host" : "",
     "stacktrace-capture-mode" : "ALL",
     "use-proxy" : false,
     "override-teamserver-url" : false,
     "engine-type" : "JAVA"
}

Retrieve Specific Profile

Get a Profile based on the name provided by the user.

Resource URI:

GET https://app.contrastsecurity.com/Contrast/api/engine/profiles/{profile-name}

Request:

Parameter Type Required Description
profile-name string true The name of the profile you wish to retrieve

Sample request:

curl -HAccept:application/json -HAPI-Key:test -HAuthorization:dGVzdF91c2VyOnRlc3Q= https://app.contrastsecurity.com/Contrast/api/engine/profiles/NEW%20PROFILE

Response: Returns the selected Profile object.

Sample response:

{
    "name" : "NEW PROFILE",
    "id" : {
     "rel" : "self",
     "href" : "https://app.contrastsecurity.com/Contrast/api/engine/profiles/NEW%20PROFILE",
     "method" : "GET"
     },
     "link" : [ {
         "rel" : "download",
         "href" : "https://app.contrastsecurity.com/Contrast/api/engine/NEW%20PROFILE",
         "method" : "GET"
     }, {
         "rel" : "self",
         "href" : "https://app.contrastsecurity.com/Contrast/api/engine/profiles/NEW%20PROFILE",
         "method" : "GET"
     }, {
         "rel" : "update",
         "href" : "https://app.contrastsecurity.com/Contrast/api/engine/profiles/NEW%20PROFILE",
         "method" : "PUT"
     } ],
     "sampling-baseline" : 5,
     "sampling-window" : 180,
     "sampling-frequency" : 10,
     "stacktrace-capture-mode" : "ALL",
     "use-proxy" : false,
     "override-teamserver-url" : false,
     "engine-type" : "JAVA"
}

Update Profile

Update a Profile with changes made by the user.

Resource URI:

PUT https://app.contrastsecurity.com/Contrast/api/engine/profiles/{profile-name}

Request:

Parameter Type Required Description
profile-name string true The name of the profile you wish to update

Sample Request:

curl -HAccept:application/json -HAPI-Key:test -HAuthorization:dGVzdF91c2VyOnRlc3Q= https://app.contrastsecurity.com/Contrast/api/engine/profiles/UPDATE%20PROFILE
--data "{"name":"UPDATE PROFILE","sampling-baseline":5,"sampling-window":180,"sampling-frequency":10,"log-level":"","log-file":"","proxy-host":"","proxy-auth":"","proxy-user":"","proxy-pass":"","proxy-port":"","teamserver-url":"","stacktrace-capture-mode":"ALL","use-proxy":false,"override-teamserver-url":false,"engine-type":"JAVA"}"

Response: Returns the updated Profile object.

Sample response:

{
    "name" : "UPDATE PROFILE",
    "id" : {
     "rel" : "self",
     "href" : "http://localhost:19080/Contrast/api/engine/profiles/NEW%20PROFILE",
     "method" : "GET"
     },
     "link" : [ {
         "rel" : "download",
         "href" : "http://localhost:19080/Contrast/api/engine/NEW%20PROFILE",
         "method" : "GET"
     }, {
         "rel" : "self",
         "href" : "http://localhost:19080/Contrast/api/engine/profiles/NEW%20PROFILE",
         "method" : "GET"
     }, {
         "rel" : "update",
         "href" : "http://localhost:19080/Contrast/api/engine/profiles/NEW%20PROFILE",
         "method" : "PUT"
     } ],
     "sampling-baseline" : 5,
     "sampling-window" : 180,
     "sampling-frequency" : 10,
     "log-level" : "",
     "log-file" : "",
     "proxy-host" : "",
     "stacktrace-capture-mode" : "ALL",
     "use-proxy" : false,
     "override-teamserver-url" : false,
     "engine-type" : "JAVA"
}

Delete Profile

Delete a Profile with the given name.

Resource URI:

DELETE https://app.contrastsecurity.com/Contrast/api/engine/profiles/{profile-name}

Request:

Parameter Type Required Description
profile-name string true The name of the profile you wish to delete

Sample Request:

curl -HAccept:application/json -HAPI-Key:test -HAuthorization:dGVzdF91c2VyOnRlc3Q= https://app.contrastsecurity.com/Contrast/api/engine/profiles/NEW%20PROFILE
--data "{"name":"UPDATE PROFILE","sampling-baseline":5,"sampling-window":180,"sampling-frequency":10,"log-level":"","log-file":"","proxy-host":"","proxy-auth":"","proxy-user":"","proxy-pass":"","proxy-port":"","teamserver-url":"","stacktrace-capture-mode":"ALL","use-proxy":false,"override-teamserver-url":false,"engine-type":"JAVA"}"

Response: Returns 200 if the Profile was successfully deleted.

Retrieve Agent

Get an Agent for the given platform: java or dotnet.

Resource URI:

GET https://app.contrastsecurity.com/Contrast/api/engine/{profile}/{platform}

Request:

Parameter Type Required Description
jvm string false The jvm level on which your application runs (Java only)

Sample request:

curl -HAccept:application/json -HAPI-Key:test -HAuthorization:dGVzdF91c2VyOnRlc3Q= https://app.contrastsecurity.com/Contrast/api/engine/default/java?jvm=1.6

Response: Returns an Agent with which to monitor your Application.

Sample response: Contrast.jar

More Information

Servers API

Data Objects

Server

A server object representing a single web server monitored by the Contrast agent.

Fields

Field Type Description
server-id long The unique identifier for the server
last-startup-message-received date The date the last *Startup Message was reported by the Agent on the Server
last-activity date The date the last **AppActivity Message was reported by the Agent on the server
last-trace-received date The date the last Trace was reported by the Agent on the server
hostname string The name of the host machine on which the server is running
server-path string The path to the server on the host machine
server-type string Indicates the type of server
enabled boolean Indicates whether or not the Agent on the server is currently active
engine-version string The version of the Agent currently running on the server, in the form Major.Minor.Patch

A startup message is sent by the Agent when the server first starts to tell TeamServer that it is still available and to determine what, if any, applications should be monitored

An AppActivity message indicates some type of action was performed on the application. These types of messages provide updates to Coverage, Architecture and Library information.

HATEOAS Links

Relevance Description
application The application to which the coverage belongs

API Operations

Retrieve Servers

Retrieves a list of the Servers to which the user has access.

Resource URI:

GET https://app.contrastsecurity.com/Contrast/api/servers

Request: Static URL that doesn't have any custom parameters.

Sample request:

curl -HAccept:application/json -HAPI-Key:test -HAuthorization:dGVzdF91c2VyOnRlc3Q= https://app.contrastsecurity.com/Contrast/api/servers

Response: Returns a collection of Server objects.

Sample response:

[ {
    "hostname" : "DELALTE6520-HM",
     "enabled" : true,
     "applications" : null,
     "id" : null,
     "link" : [ ],
     "server-id" : 1,
     "last-startup-message-received" : 1389619832000,
     "last-trace-received" : 1389619927000,
     "last-activity" : 1389624222000,
     "server-path" : "c:\\Tools\\apache-tomcat2-7.0.40\\bin\\",
    "server-type" : "tomcat7",
     "engine-version" : "2.4.8"
    }, {
     "hostname" : "DELALTE6520-HM",
     "enabled" : true,
     "applications" : null,
     "id" : null,
     "link" : [ ],
     "server-id" : 2,
     "last-startup-message-received" : 1389622545000,
     "last-trace-received" : 1389622712000,
     "last-activity" : 1389624352000,
     "server-path" : "c:\\windows\\system32\\inetsrv\\w3wp.exe",
     "server-type" : "iis7",
     "engine-version" : "-"
} ]

Get Specific Server

Retrieve the given Server.

Resource URI:

GET https://app.contrastsecurity.com/Contrast/api/servers/{server-id}

Request:

Parameter Type Required Description
server-id long true The ID of the server for which you want information

Sample request:

curl -HAccept:application/json -HAPI-Key:test -HAuthorization:dGVzdF91c2VyOnRlc3Q= https://app.contrastsecurity.com/Contrast/api/servers/1

Response: Returns a Server object.

Sample response:

{
    "hostname" : "DELALTE6520-HM",
     "enabled" : true,
     "applications" : null,
     "id" : null,
     "link" : [ ],
     "server-id" : 1,
     "last-startup-message-received" : 1389619832000,
     "last-trace-received" : 1389619927000,
     "last-activity" : 1389624222000,
     "server-path" : "c:\\Tools\\apache-tomcat2-7.0.40\\bin\\",
     "server-type" : "tomcat7",
     "engine-version" : "2.4.8"
}

More Information

Glossary