Integrations

Getting Started

Authorize and connect tools with Contrast to streamline your workflows, go to the User menu > Organization Settings > Integrations tab. Contrast offers integrations with the following notification and bugtracker services.

Bugtrackers:

  • JIRA
  • Visual Studio Team Services/Team Foundation Services (VSTS/TFS)
  • Bugzilla
  • Agile Central
  • Serena Business Manager

Notifications:

  • Slack
  • HipChat
  • VictorOps
  • Generic Webhook

Notes:

  • Notification settings in your organization affects which messages you receive from your existing integrations. Read the article on Notifications for more information.
  • If EOP customers set up a proxy in the Contrast application, Contrast will filter all integration traffic through that proxy.

Introduction to Bugtrackers

Streamline the remediation process for vulnerabilities by sending details directly from Contrast to a configured bugtracker. Contrast supports integrations with services including Atlassian JIRA, Microsoft Visual Studio Team Services/Team Foundation Services (VSTS/TFS), Mozilla Bugzilla and Serena Business Manager.

Note: You must configure a bugtracker integration in your organization before sending vulnerabilities to it.

Export findings

Vulnerabilities

You can send vulnerabilities to a bugtracker from the Send Vulnerability (paper plane) icon located on the Vulnerabilities page, or from the Vulnerabilities tab of an Application Overview page. In the dialog that follows, choose which information should be included when exporting the findings.

For more information, go to the Manage Vulnerabilities article.

Library details

You can send the details of vulnerable libraries to a bugtracker from the Libraries page, and application's Libraries tab or a library's overview page. For more information, go to the Manage Libraries article.

Integrate with unsupported systems

If you need to integrate your data from Contrast with an unsupported system, you can use one of the following options.

  • The Contrast REST API: Read the complete REST API documentation.
  • CSV spreadsheet: Export findings to a Comma-Separated Values (CSV)-formatted spreadsheet, and import them into the bugtracker of your choice.
  • XML spreadsheet: Export findings for individual or groups of vulnerabilities to an Extensible Markup Language(XML)-formatted spreadsheet, and import them into a bugtracker of your choice.

JIRA Integration

Integrate Jira with Contrast to automatically generate tickets, synchronize comments and push notifications for your applications.

Prerequisites

  • Jira account credentials (username and password)
  • Permission to create issues in the target project
  • A running Jira instance accessible via HTTP to the Contrast UI
  • A project to associate the application instrumented by Contrast

Add a Configuration

In the Integrations page, click Connect in the Jira row. In the Connect with Jira form, add the name for the bugtracker entry, the username and password for the account connected to Jira in the appropriate fields. The Jira URL must be accessible from the Contrast UI instance being configured.

Note: Contrast saves the username, password and Jira URL entered in your configuration as a set of credentials. See the Credential Sets section for more details.

Once you complete the fields, click Test connection. This process may take a few moments depending on the number of your Jira projects. The test verifies that Contrast can reach the Jira instance and that the specified user is able to log in.

Once connected, select the applications that you want to be available to this integration, and customize the values for the Project, Assignee and Default Issue Type fields. You can also customize the Default Priority levels for vulnerability severity and values for Additional JIRA fields, such as environment or labels.

Note: If you change the Project or Issue type, required and additional fields are updated. However, the UI keeps the selected values that apply to the new configuration.

Two-way integration

Use two-way integration to automatically update the status of a linked vulnerability when you close or reopen an issue in Jira.

In the Jira configuration page, check the box to Enable two-way integration. This generates a URL that appears below the checkbox, which your Jira administrator must use to register a webhook in JIRA. Clicking the link opens a new tab that takes you to instructions for registering webhooks. In the webhook configuration, place a check for the updated event type under Issue column for Issue related events.

Note: When you delete a configuration with two-way integration enabled, you must delete the webhook configuration from your Jira administrator console to completely remove the integration.

In the fields below, use the dropdown menu to set a vulnerability status based on a JIRA ticket status and resolution pairing. The table below shows the default vulnerability status options in bold.

Ticket Status Ticket Resolution Vulnerability Status Options
OPEN N/A Confirmed
Suspicious
Reported
IN PROGRESS N/A Confirmed
Suspicious
Not a Problem
Remediated
Reported
Fixed
RESOLVED Fixed
Won't Fix
Duplicate
Incomplete
Cannot Reproduce
Done
Won't Do
Not a Problem
Remediated
Fixed
REOPENED N/A Confirmed
Suspicious
Reported
CLOSED Fixed
Won't Fix
Duplicate
Incomplete
Cannot Reproduce
Done
Won't Do
Not a Problem
Remediated
Fixed
BLOCKED N/A Confirmed
Suspicious
Not a Problem
Remediated
Reported
Fixed
NEEDS CLARIFICATION N/A Confirmed
Suspicious
Not a Problem
Remediated
Reported
Fixed
READY TO DEPLOY Fixed
Won't Fix
Duplicate
Incomplete
Cannot Reproduce
Done
Won't Do
Not a Problem
Remediated
Fixed

Note: If you choose Not a Problem, Contrast requires you to enter a Reason in the dropdown menu. The default selection in the dropdown menu is Other.

Once the two-way integration is saved, Contrast will automatically generate comments in the vulnerability's Discussion page when the status of a ticket is updated. Each comment includes the name of the bugtracker and a link to the ticket.

Multiple vulnerabilities

For multiple vulnerabilities sent to Jira in bulk as a single issue, the Jira ticket status applies to all vulnerabilities associated with that ticket. For multiple tickets tied to a single vulnerability, the vulnerability can only be closed when all the tickets are closed.

Automatically create tickets

Automatically create tickets in Jira for newly discovered vulnerabilities by checking the designated box in the configuration form. In the multiselect field that appears, choose the Rule(s) and/or Severity level(s) of the vulnerabilities for which you want to generate tickets. The default selections are Critical and High.

Note: This selection doesn't generate tickets retroactively.

Credentials

Contrast saves the latest set of credentials that you enter in your Jira configurations to help you set up new connections even faster. The username, password and Jira URL values that you enter in your first configuration become the default credentials for your following configurations. In subsequent configurations, Contrast will auto-populate the fields with the default credentials, but allow you to modify the values as needed. You can also manage your saved sets of credentials to simultaneously update all of the affected configurations.

Manage credentials

To create or edit a configuration with credentials that are different than your default set, select the Manage credentials link. In the URL field, use the dropdown menu to choose a set of saved credentials; or, manually update the values in the URL, Username and Password fields. Once you've updated the fields, click the button to Test Connection.

Click the button to Save your changes. If you're using new credentials, you must choose to override the existing set of credentials under the given name, or save the new values as a new credential set under a different name.

You can also select the Manage Credentials link in the Jira Integrations row to modify your existing sets of information. In the configuration form, use the dropdown menu to select a set of saved credentials, and then modify the values in the given fields. Click the link to Rename the set of credentials, if needed.

Note: Any updates to a set of credentials will affect all configurations using that set.

Click the button to Test Connection; once Contrast verifies the connection, click the button to Save your changes.

Visual Studio Team Services Integration

Integrating Visual Studio Team Services (VSTS) or Team Foundation Server (TFS) with Contrast allows you to automatically generate tickets, synchronize comments and push notifications for your applications.

Prerequisites

  • VSTS or TFS account credentials (username and personal access token)
  • An access token with "Work items (read and write)" scope (minimum requirement)
  • A running VSTS or TFS instance accessible via HTTP(s) to Contrast
  • A project which to associate the application instrumented by Contrast

Setup

In the Integrations page, click Connect in the VSTS row. This takes you to the Connect with Visual Studio page, where you must complete the following fields.

  • Name: The name for the bugtracker entry; displayed when sending findings to bugtrackers.
  • Personal Access Token: The token associated with your user to authenticate to your host.
  • Host: The VSTS or TFS URL; must be accessible from the Contrast interface instance being configured.

Once you complete the fields, click Test connection. This process may take a few minutes, depending on the number of your VSTS or TFS projects. The test verifies that Contrast can reach the VSTS or TFS instance and that the specified user can log in.

Once a connection is made, select the applications that you want to be available to this bugtracker. Customize the values for the Project, Assignee and Default Work Issue Type fields as well as the Default Severity or Priority levels depending on the work issue type.

Note: Contrast uses API v.2 to support VSTS and TFS 2015/2017.

Two-way integration

Use two-way integration to automatically update the status of a linked vulnerability when you close or reopen an issue in VSTS or TFS.

In the configuration page, begin setup by checking the box to Enable two-way integration. In the Vulnerability Status fields that appear, use the dropdown menus to set a vulnerability status based on each VSTS/TFS ticket state. If you choose Not a Problem as a ticket state, Contrast requires you to choose a Reason in the dropdown menu, as it does in the Vulnerability grid; the default selection is "Other".

Note: After you fill in the the Work Item Type and the Project fields in the configuration page, as outlined in the previous section, Contrast does an API call that returns a list of your VSTS/TFS ticket states. The Vulnerability Status dropdown menus are populated accordingly. For more information about VSTS and TFS work item types and ticket states, read Microsoft's documentation.

Once the two-way integration is saved, Contrast will automatically generate comments in the Discussion tab on each vulnerability page when the state of a ticket is updated. Each comment includes the name of the bugtracker and a link to the ticket.

Multiple vulnerabilities

For multiple vulnerabilities sent to VSTS or TFS in bulk as a single issue, the ticket state applies to all vulnerabilities associated with that ticket. For multiple tickets tied to a single vulnerability, the vulnerability can only be updated when all the tickets are updated as well.

Example: If you change a ticket state from "New" to "Active", Contrast updates the vulnerability status only if all the tickets related to that vulnerability are in "Active" state.

Automatically create tickets

Automatically create tickets for newly discovered vulnerabilities by checking the designated box in the configuration form. In the multiselect field that appears, choose the Rule(s) and/or Severity level(s) of the vulnerabilities for which you want to generate tickets. The default selections are "Critical" and "High".

Note: This selection doesn't generate tickets retroactively.

Bugzilla Integration

Prerequisites

  • Bugzilla account credentials (username and password)
  • A running Bugzilla application instance accessible via HTTP to Contrast
  • A product, component and version to associate the application instrumented by Contrast

Setting up the Bugzilla Integration

  1. Log in to Contrast as an Organization Administrator
  2. From the user dropdown menu, select Organization Settings
  3. Select the Integrations tab in the left navigation
  4. Click Connect in the Bugzilla row

Option Description
Name A name for the bugtracker entry. It will be displayed when sending findings to bugtrackers.
Username The username for the account connected with Bugzilla
Password The password for the username specified
Host The URL of the Bugzilla instance
Application The application you would like to map to a Bugzilla product/component
Product The product in Bugzilla to map to the application
Component The component in Bugzilla to map to the application
Version The version in Bugzilla to map to the application
Priority The priority to use when exporting findings to Bugzilla

Once you have configured the Bugzilla integration properties, you can verify communication via the Test button. This ensures that Contrast can communicate and authenticate with the Bugzilla instance as well as verify the existence of the specified Product, Component and Version.

Agile Central Integration

Integrate Agile Central with Contrast to automatically track vulnerabilities in your applications.

Prerequisites

  • Agile Central account URL
  • Permission to create issues in the target project
  • A running Agile Central instance accessible via HTTP to the Contrast UI
  • A project to associate the application instrumented by Contrast

Add a Configuration

To connect your Contrast organization with Agile Central, complete the following steps.

  • Go to the user menu > Organization Settings > Integrations page, and click Connect in the Agile Central row.
  • In the Connect with Agile Central form, add the name for the bugtracker entry, as well as the URL and API Key in the given fields. The Agile Central URL must be accessible from the Contrast UI instance being configured.

Notes:

  • To find your Agile Central API key, log in to the Agile Central Application manager, and go to the API Keys tab.
  • Contrast saves the username, password and Agile Central URL entered in your configuration as a set of credentials. See the Credential Sets section for more details.
  • Once you complete the fields, click the button to Test connection. The test verifies that Contrast can reach the Agile Central instance and that the specified user can log in.

  • Once connected, select the Applications that you want to be available to this integration.
  • Choose a Project Name and Owner from the dropdown menus.
  • In the Default Priority section, use the dropdown menus to choose a priority level for each vulnerability severity.
  • Choose the Environment for which you want to generate tickets.
  • Choose a Defect State.
  • Add a name that the tickets are Submitted By.

Note: While none of these configuration fields are required, Agile Central may populate tickets with their own default values for any fields you leave blank.

To add another integration once you're connected in Contrast, click the Add Configuration link in Agile Central row.

Automatically create tickets

To automatically create tickets for newly discovered vulnerabilities, check the designated box in the configuration form. In the multiselect field that appears, choose the Rule(s) and/or Severity level(s) of the vulnerabilities for which you want to generate tickets.

Note: This selection doesn't generate tickets retroactively.

Edit Configurations

To see existing configurations, click the Show Configurations link in Agile Central row. Click on a configuration name to go to the Agile Central Connection form, and edit the field values. You can also delete your configuration by clicking the trashcan icon.

Credentials

Contrast saves the latest set of credentials that you enter in your Agile Central configurations to help you set up new connections even faster. The API key and URL values that you enter in your first configuration become the default credentials for your following configurations. In subsequent configurations, Contrast will auto-populate the fields with the default credentials, but allow you to modify the values as needed. You can also manage your saved sets of credentials to simultaneously update all of the affected configurations.

Manage credentials

To create or edit a configuration with credentials that are different than your default set, select the Manage credentials link.

  • In the URL field, use the dropdown menu to choose a set of saved credentials; or, manually update the values in the URL, Username and Password fields.
  • Once you've updated the fields, click the button to Test Connection.

  • Click the button to Save your changes.
  • If you're using new credentials, you must choose to override the existing set of credentials under the given name, or save the new values as a new credential set under a different name.

You can also select the Manage Credentials link in the Agile Central Integrations row to modify your existing sets of information.

  • In the configuration form, use the dropdown menu to select a set of saved credentials, and then modify the values in the given fields.
  • Click the link to Rename the set of credentials, if needed.

Note: Any updates to a set of credentials will affect all configurations using that set.

  • Click the button to Test Connection.
  • Once Contrast verifies the connection, click the button to Save your changes.

GitHub Integration

Set up an integration to automatically send issues to GitHub when Contrast finds them in your applications.

Prerequisites

  • GitHub account credentials (username and password)
  • Access to a GitHub organization and repository for the application
  • Write permission (push access) to the repository
    (This is required to set labels, milestones and assignees in the configuration form. See the Setup section for more information.)
  • A running GitHub instance accessible via HTTP to the Contrast UI

Setup

In the Integrations page, click Connect in the row for GitHub.

In the Connect with GitHub form, add the name for the bugtracker entry, the username for the account connected to GitHub and the password for the specified username in the appropriate fields. The GitHub URL must be accessible from the Contrast UI instance being configured.

Once you complete the fields, click Test connection. This process may take a few moments depending on the number of your GitHub organizations and repositories. The test verifies that the GitHub instance can be reached by Contrast and that the specified user is able to log in.

Once a connection is made, select the Applications that you want to be available to this bugtracker, and select the values for the GitHub Organization and Repository fields using the dropdown menus. You also have the option to add Labels, Assignees and a Milestone for GitHub issues using the given fields.

Note: If you change the GitHub Organization or Repository values, you must re-enter the values for optional fields.

Automatically create tickets

Automatically create issues in GitHub for newly discovered vulnerabilities by checking the box at the bottom of the configuration form. In the multiselect field that appears, choose the rule(s) and/or severity level(s) of the vulnerabilities for which you want to generate tickets. The default selections are "Critical" and "High".

Note: This selection doesn't generate issues retroactively.

Multiple vulnerabilities

For multiple vulnerabilities sent in bulk to GitHub as a single issue, the GitHub ticket status applies to all vulnerabilities associated with that ticket. For multiple issues tied to a single vulnerability, the vulnerability can only be closed when all the tickets are closed.

Serena Business Manager Integration

Prerequisites

  • Serena (SBM) account credentials (username and password)
  • A running SBM instance accessible via HTTP to Contrast
  • A project to associate the application instrumented by Contrast

Setting up the SBM Integration

  1. Log in to the Contrast with an Organization Administrator account
  2. From the user dropdown menu, select Organization Settings
  3. Select the Integrations tab in the left navigation
  4. Click Connect in the Serena Business Management row

Option Description
Name A name for the bugtracker entry. It will be displayed when sending findings to bugtrackers.
Username The username for the account connected to the SBM instance
Password The password for the username specified
Host The URL to the SBM instance
Application The application you would like to map to an SBM instance
Project ID The SBM Project ID to associate with this application

Once you have configured the Serena integration properties, you can verify communication via the Test button. This will ensure that Contrast can communicate and authenticate with the Serena instance as well as verify the existence of the specified Project.

Slack Integration

Contrast supports Slack integration! With this connection you can receive notifications from Contrast in your configured Slack instance using a format similar to in-app notifications.

Setup

To add, go to your team's Build settings in Slack:

  1. Add a new Incoming Webhooks custom integration
  2. Choose the appropriate channel to which to send messages
  3. Copy the Webhook URL

To connect in Contrast:

  1. Navigate to the Integrations tab under Organization Settings
  2. Click Connect within the Slack row
  3. Name the integration and paste the URL
  4. Select the application(s) for which you want to enable notifications
  5. Click Save

You are connected!

HipChat Integration

Contrast supports integration with HipChat! With this connection you can receive notifications from Contrast in your configured HipChat channel using a format similar to in-app notifications.

Setup

On the HipChat website, log in as a user with at least Send Notification and View Room scopes. Typically this is an admin user.

  1. Edit your profile and click API access
  2. Create a new token and add at least the Send Notification and View Room scope
  3. Copy the token created

To connect in Contrast:

  1. Navigate to the Integrations tab under Organization Settings
  2. Click Connect within the HipChat row
  3. Name the integration, paste the token into the token input field, and select the appropriate room from the dropdown
  4. Select the application(s) for which you want to enable notifications
  5. Click Save

You are connected!

VictorOps Integration

Set up an integration with with VictorOps incident management to receive attack notifications from Contrast.

Setup

In the Integrations page, click Connect in the VictorOps row. In the VictorOps Connection page, complete the following fields.

  • Name: The name for the integration entry, which is displayed in notifications from Contrast.
  • Message Type: Use the dropdown menu to choose the behavior of the alert. The default selection is "Critical". For more information about message types, see the VictorOps documentation on incident fields.
  • URL: You can generate the URL in VictorOps through a REST API endpoint. To get a URL or more information, see the VictorOps documentation on the REST endpoint.

Once you complete the fields, click Test connection. This process may take a few minutes, depending on the number of your VictorOps projects. The test verifies that Contrast can reach the VictorOps instance and that the specified user can log in.

Once a connection is made, click in the multiselect field to choose the Applications for which you want to send notifications. The default selection is "All Applications".

Generic Webhook Integration

Contrast supports generic webhook integration, which allows you to receive notifications on any URL that receives POST messages. The simple integration format includes an optional Payload field where you can include a title and message.

Setup

  • Retrieve the URL to which you want Contrast to send notifications.
  • Navigate to the User menu > Organization Settings > Integrations tab.
  • In the row for Generic Webhook, click the button to Connect.
  • Name the webhook, and paste the URL in the designated field.
  • Select the application(s) that you want to filter.
  • If you want to complete the Payload field, enter the title and message. Sample code:
{
    'title':   'Contrast Security Notification',
    'message': 'Test User commented on a Insecure JSP Placement vulnerability in WebGoat. \"Fixed in CVE-2015\"'
}

You can also add placeholders in the payload so that Contrast changes the text for different notifications - a new application, server, vulnerability, etc. Sample code for VictorOps integration:

{ 
    "message_type":"INFO", 
    "entity_id":"$Title", 
    "entity_display_name":"$Title", 
    "state_message":"$Message" 
}
  • Click Save.

You are connected!