2.7.0
Plugins Guide

Code Dx Plugins

There are a number of plugins available to make it easier to bring the power of Code Dx to other software development tools, including IDE's, Continuous Integraton Systems, and open source Application Security Testing tools. This guide includes instructions for installing and using these plugins.

Jenkins

The Code Dx Jenkins plugin integrates the Jenkins continuous integration platform with your Code Dx server. It allows you to push build results to your Code Dx server as part of the build process.

A Code Dx project and an API key are required. The API key must have the create role for the project.

This section of the Plugins guide explains how to install and use the Jenkins plugin. For more information you may visit the Official Code Dx Jenkins Wiki Page or our GitHub Repository. This plugin is open source and we welcome community involvement.

Installation

The Code Dx Jenkins plugin is available for installation through the Jenkins plugin management page. You must be running Jenkins version 1.642.2 or later.

Job Configuration

The first thing you should do is configure your Jenkins Job to publish to Code Dx.

This is accomplished on the configuration page by going to Post-build Actions (toward the bottom) and selecting the Publish to Code Dx option from the Add post-build action button.

You can use the new action to setup different options related to Code Dx.

Publishing

The Server URL, Server API Key, and Code Dx Project fields are required for publishing. Ask your Code Dx administrator to generate the server API key that has the create role for the project it needs to interact with.

Once the Server URL and Server API Key fields are populated, the Code Dx Project dropdown will automatically list the projects available to the Server API key. It is highly recommended that you specify an HTTPS URL, since using HTTP is insecure. If you receive a warning regarding an invalid certificate, refer to the section on self-signed certificates.

The Source and Binary Files field allows you to identify the files in the job workspace for Code Dx to analyze. The format of this field is a comma-separated list of Ant glob file location patterns. You can populate this list by specifying the files (relative to the workspace) that will be sent to Code Dx. By default, this field is set to ** (all files).

Code Dx Enterprise supports importing the results of more then 40 commercial and open source analysis tools, in addition to generic listing formats. This feature is supported in the Jenkins plugin via the Tool Output Files field, where you specify a comma-separated list of paths and filenames of each output file.

Code Dx Enterprise users have access to the "First Seen" and "Last Modified" filters on Code Dx's Findings page. Each analysis in those filters can have an Analysis Name, which is directly related to the Analysis Name field in Jenkins. The Analysis Name field lets you set a "name" for each Code Dx analysis published from Jenkins. You can use build/environment variables to construct a different name for each analysis. For example, Build #${BUILD_NUMBER} creates the analysis name "Build #26" for the 26th build of the project. You can construct links using a syntax similar to markdown, i.e., [link text](link url). This also works with build variables: Build [#${BUILD_NUMBER}]($BUILD_URL). Some Jenkins plugins, like the Git plugin, provide "macros" which allow for some additional customization. In this example, the analysis name will be set to the first eight characters of the git commit hash: ${GIT_REVISION, length=8}. For more information about "macros", see the Token Macro Plugin Wiki. Note: the analysis name feature is only supported by Code Dx versions 2.4.0 and up. If the server you plan to publish to is older than version 2.4.0, the analysis name will be ignored.

In the Advanced Options section, which is located at the bottom, you may specify source and/or binary locations to exclude from the analysis.

Clicking the Advanced... button will allow you to enter the files you would like to exclude from the build. These files are also Ant glob patterns.

Handling a Self-Signed Certificate

If the server hosting Code Dx is using a self-signed certificate, you'll receive a warning:

Clicking the Advanced button will allow you to populate the Self-Signed Certificate Fingerprint field with the SHA1 fingerprint of the self-signed certificate used by the server. Contact your Code Dx administrator for the correct value. Or you can navigate to your installation of Code Dx in a browser, and obtain the fingerprint by following the instructions for your particular browser:

Once you have the correct fingerprint, populating the Self-Signed Certificate Fingerprint field will allow you to proceed.

Waiting for Analysis Results

When performing an analysis, the Jenkins Code Dx publisher will zip up the specified workspace files and send them to the Code Dx server. By default, Jenkins will not wait for the results of the analysis.

In some cases you will want to wait for the analysis to complete so you may consider the Jenkins job a success or failure. To take this even further, a team may also want the resulting Code Dx analysis data to influence the state of the build. Additionally, you may want to see a summary of the Code Dx build and analysis results within Jenkins, including the resulting Code Dx tables and graphs. This is all possible by selecting the Wait for Analysis Results checkbox.

Upon enabling this option, a new set of fields will be shown on the configuration page. These fields are categorized into three sections: Build Failure Conditions, Build Unstable Conditions, and Graph Options.

Build Failure Conditions

The Build Failure Conditions section allows you to configure the requirements upon which the build will be considered a failure. It is important to note that not all findings will be included in this check. By default, only findings with a status of Assigned, Escalated, and Unresolved will be considered. To only check findings created during the current build, you can select the Only Consider New Findings checkbox.

The severity dropdown specifies the range of severities that will cause the build to fail. That is, the build will be considered a failure if one or more findings are detected with the selected severity range.

Build Unstable Conditions

The Build Unstable Conditions section is identical to the previous section, but configures the requirements upon which the build will be considered unstable. The severity dropdown has the same options as the Build Failure Conditions section.

Graph Options

The Code Dx Jenkins plugin will show some helpful graphs on the Job and Build pages when the Wait for Analysis Results option is enabled. The number of datapoints in these graphs is configurable using the Number of Builds in Graph field. To show an unlimited number of datapoints, set this field to a value less than 2.

Analysis Results

If the Code Dx Jenkins plugin is configured to wait for analysis results before allowing the build to complete, it will also show tables and charts on the Job and Build pages.

Finding Tables

The Job and Build pages will display tables that provide a summary of the findings.

These tables show the number of findings for each severity and status. A delta between the current build and previous build will also be shown, if applicable.

Under the tables there is a link to view the latest results within the Code Dx application.

Finding Graphs

The Job page will show graphs of the findings according to severity and status.

Eclipse

The Code Dx Eclipse plugin streamlines the use of Code Dx within the Eclipse IDE. Developers can push out new builds for Code Dx analyses and the results can be viewed from within the IDE.

A Code Dx project is required. To allow users access to the project, they must be assigned to the project where the user roles are consistent with those within Code Dx.

This section of the guide explains how to install and use the Eclipse plugin. For more information you may visit The Official Eclipse Marketplace Page.

This plugin supports the following Eclipse versions:

Installation

The Eclipse plugin is installed through the usual plugin installation method. Navigate to Help -> Install New Software. Then click the Add button to add a new update site.

Enter Code Dx for Name. Enter http://codedx.com/eclipse-plugin/ for Location.

Then click OK.

Select the Code Dx plugin and continue with the wizard in order to complete the plugin installation process.

Configuration

To configure the Eclipse plugin, you can either navigate to Window -> Preferences and select Code Dx, or you can navigate to Code Dx -> Configure. Both methods will result in the same preferences section being shown.

There are three configuration options available: Server, Username, and Password. Enter the URL of the Code Dx server in the Server field. Enter your Code Dx log in credentials in the Username and Password fields. Verify the Code Dx plugin is able to communicate with the Code Dx server by clicking the Test Connection button. A message will appear indicating a successful connection or explaining why the connection failed.

Views

The Eclipse plugin provides two main views: the Code Dx Findings View and the Code Dx Finding Details View. Both of these are available by navigating to Window -> Show View -> Other.

The views will be located under the Code Dx folder.

Findings View

This view displays all of the findings from the selected project. There are three sections: the findings table, the summary area, and a toolbar.

The table has columns for many of the finding properties such as:

The table can be sorted by any of these columns except the Tool column. Right-clicking on a row provides a context menu for performing actions on the selected finding.

The summary area is located above the table. It provides the project name, the total number of findings, and the number of findings for each severity category.

The toolbar buttons include (from left to right) the ability to switch Code Dx projects, show details of a finding, show remote source code residing on the Code Dx server, filter findings by user and/or status, change status, synchronize the Eclipse Package Explorer view with the table contents, and refresh the table.

Switching Code Dx Projects

The table of findings can easily be changed to show the results of different Code Dx projects. This is done using the following toolbar button:

A dialog is displayed after you click the Select a Project button. Note that only the projects accessible to your user credentials (provided during configuration) will be shown in this dialog.

Showing Source Code for a Finding

You can view and edit the local source code for a finding by double-clicking on it, or by right-clicking on the selected finding and choosing Show Finding in the context menu. The editor view will open with the associated source code. If there is a line number for the finding, the editor will automatically scroll to that location.

Showing Finding Details

The details of a finding can be viewed by selecting a row in the table and either using the toolbar button or the context menu of the row.

Showing Remote Source

It is sometimes useful to see the current version of a source file on the Code Dx server. For example, if the code local to eclipse is different from the remote code. This can be done by selecting a row in the table and either using the toolbar button or the context menu of the row.

The file will be downloaded from the Code Dx server and displayed in a read-only editor.

The title of the editor will be marked with a [Code Dx] label before the filename so that it can be distinguished from local source.

Filtering Findings

The table can be filtered to show only the findings that are assigned to you (left button) and to hide findings that have a status of Ignored, False Positive,Fixed, Gone and Mitigated (right button).

Changing the Status of Findings

You can change the status of a single finding or a group of findings. First select the finding(s) then use either the Change Status dropdown located on the toolbar or the Status option in the context menu.

Sync and Refresh

The Sync button is situated to the immediate right of the Change Status dropdown and is used in conjunction with the Package Explorer view and editors. With the button enabled, just click a file in the Package Explorer and the table will display only those findings associated with the selected file. Selecting an editor window of an open file will do the same.

The Refresh button is located to the right of the Sync button. It is used to refresh the table with the findings on the Code Dx server.

Finding Details View

The Finding Details view shows a minimal version of the Finding Details page in the Code Dx application. If you have the update role for a project, you can change the status of a finding in that project and post to its activity stream.

The toolbar contains a Sync button. When enabled, selections in the Findings table will automatically update the information in the Finding Details view.

Markers

The Code Dx Eclipse plugin automatically adds source code markers to help you determine the location of the findings within the code.

There are markers in both the left and right gutters. The markers in the left gutter use the Code Dx severity icons to show the highest level severity on the given line. The markers in the right gutter show the findings throughout the entire file.

The context menu on the marker will show a submenu for each finding on the given line.

Running an Analysis

If you have the create role on a Code Dx project, you have the ability to perform Code Dx analyses on that project from within the Eclipse IDE. Just select the Run Analysis option from the Code Dx menu.

When the dialog is displayed, select the Code Dx project from the dropdown, the Eclipse projects from the list, and click Run.

An Eclipse job is created and the progress is displayed in the bottom right corner of the IDE. The Findings table will automatically be updated upon completion of the analysis.

Visual Studio

The Code Dx Visual Studio (VS) extension is a plugin for the Visual Studio IDE. It streamlines the use of Code Dx for developers by allowing them to push out new builds for analysis and view analysis results from within the IDE.

A Code Dx project is required. To allow users access to the project, they must be assigned to the project where the user roles are consistent with those within Code Dx.

This section of the guide explains how to install and use the VS extension. You may download the installer from the Official Marketplace Page.

This extension supports VS 2012 or greater.

Please contact us at support@codedx.com if you're using an older VS version.

Installation

Installation of the VS extension is done by double-clicking the installer.

Configuration

To configure the Visual Studio plugin you can either navigate to Tools -> Options and select Code Dx, or you can navigate to Code Dx -> Configure. Both methods will result in the same options section being shown.

There are four configuration options available: URL, Username, Password, and Response Timeout. Enter the URL of the Code Dx server in the URL field and your Code Dx log in credentials in the Username and Password fields. The default value for Response Timeout is 120 seconds, but you can customize the timeout period for your server.

Verify the Code Dx plugin is able to communicate with the Code Dx server by clicking the Test Connection button. A message will appear indicating a successful connection or explaining why the connection failed.

Attaching a Code Dx Project

In order to view findings and push out builds to be analyzed, you must first open your solution file. Second, attach a Code Dx project by either using the Code Dx menu or by right-clicking your VS project in Solution Explorer. The setting will be remembered the next time the solution is opened. The project can be detached at any time using the same method.

A dialog will be displayed to select the desired Code Dx project.

Viewing Findings

Once the solution has been attached to a Code Dx project, a table of the latest findings is displayed. This is accessible by navigating to Code Dx -> Show Findings.

A window opens that is comprised of the findings table, the summary area, and a toolbar.

The table has columns for many of the finding properties such as:

The table can be sorted by any of these columns except the Tool column. Right-clicking on a row provides a context menu for performing actions on the selected finding.

The summary area is located above the table. It provides the project name, the total number of findings, and the number of findings for each severity category.

The toolbar buttons include (from left to right) the ability to show finding details, show remote source code that resides on the Code Dx server, filter findings by user and/or status, change status, and refresh the table.

Showing the Source Code for a Finding

You can view and edit the local source code for a finding by double-clicking it, or by right-clicking on the selected finding and choosing Show Finding in the context menu. The editor will open with the associated source code. If there is a line number for the finding, the editor will automatically scroll to that location.

Showing Finding Details

The details of a finding can be viewed by selecting a row in the table and either using the toolbar button or the context menu of the row.

Showing Remote Source

It is sometimes useful to see the current version of a source file on the Code Dx server. For example, if the code local to Visual Studio is different than the remote code. To do this, select a row in the table then choose Show Remote Source from either the toolbar button or the context menu of the row.

The file will be downloaded from the Code Dx server and displayed in a read-only editor.

The title of the editor will be marked with a [Code Dx] label before the filename so that it can be distinguished from local source.

Filtering Findings

The table can be filtered to show only the findings that are assigned to you (left button) and to hide findings that have a status of Ignored, False Positive, Gone, Fixed and Mitigated (right button).

Changing the Status of Findings

The status of a single finding or a group of findings can be changed by selecting the desired finding(s) in the table and choosing the status via the toolbar drop-down or the context menu.

Refreshing the Findings Table

Click the Refresh button to update the table with the findings on the Code Dx server.

Viewing Finding Details

This window displays the details about a finding.

It shows a minimal version of the Finding Details page from the Code Dx application. If you have the update role for its respective Code Dx project, you can change the status of a finding, or post to the activity stream.

The toolbar for the Finding Details contains a Sync button, which is located in the upper right corner. When enabled, the details window will automatically contain information about the selected finding.

Markers

The Code Dx VS extension automatically adds source code markers to help you determine the location of the findings within your code.

There are markers in both the left and right gutters. The markers in the left gutter use the Code Dx severity icons to show the highest level severity on the given line. The markers in the right gutter show the findings throughout the entire file.

The right-click context menu on the marker will show a sub-menu for each finding on the given line.

Running an Analysis

If you have the create role, you have the ability to perform Code Dx analyses from within the VS IDE. Just select the Run Analysis option from the Code Dx menu or right-click on the solution in the Solution Explorer

You can include or exclude VS projects for the solution by right-clicking on the VS project and selecting Include in Code Dx Analysis or Exclude in Code Dx Analysis, respectively.

The solution will be zipped and sent to the Code Dx server for analysis except for the project(s) you excluded.

The analysis progress is shown on the bottom status bar of the IDE.

The findings table will automatically update upon completion of the analysis.

IntelliJ

The Code Dx IntelliJ plugin streamlines the use of Code Dx within the IntelliJ IDE. Developers can push out new builds for Code Dx analyses and the results can be viewed from within the IDE.

A Code Dx project is required. To allow users access to the project, they must be assigned to the project where the user roles are consistent with those within Code Dx.

This section of the guide explains how to install and use the IntelliJ plugin. For more information you may visit the Official IntelliJ Plugin Page.

This plugin supports IntelliJ version 2017.2 or greater.

Installation

The IntelliJ plugin is installed through the plugin repository within the IDE. Navigate to IntelliJ's settings by pressing Ctrl + Alt + S while in the IDE. Click Plugins in the side bar, and then the Browse Repositories... button.

Enter Code Dx into the search bar. Click on the Code Dx plugin and press Install.

Wait for the plugin to download and press Restart IntelliJ IDEA.

The plugin will now be available upon restart.

Configuration

To configure the IntelliJ plugin, you can either navigate to Settings (Ctrl + Alt + S) -> Code Dx, or you can navigate to Code Dx -> Configure from the menu bar. Both methods will result in the same preferences section being shown.

There are four configuration options available: URL, Username, Password and Response Timeout. Enter the URL of the Code Dx server in the URL field. Enter your Code Dx log in credentials in the Username and Password fields. The default value for Response Timeout is 120 seconds, but you can customize the timeout period for your server.

Verify the Code Dx plugin is able to communicate with the Code Dx server by clicking the Test Connection button. A message will appear indicating a successful connection or explaining why the connection failed.

Tool Window

The IntelliJ plugin provides a tool window with two tabs: the Code Dx Findings Table and the Code Dx Finding Details. To show the tool window, navigate to View -> Tool Windows -> Code Dx Findings.

Alternatively, click on Code Dx from the menu bar and then Show Findings.

Findings Table Tab

This tab displays all of the findings from the selected project. There are three sections: the findings table, the summary area, and a toolbar.

The table has columns for many of the finding properties such as:

The table can be sorted by any of these columns except the Tool column. Right-clicking on a row provides a context menu for performing actions on the selected finding.

The summary area is located above the table. It provides the project name, the total number of findings, and the number of findings for each severity category.

The toolbar buttons include (from left to right) the ability to switch Code Dx projects, show details of a finding, show remote source code residing on the Code Dx server, filter findings by user and/or status, change status, and refresh the table.

Switching Code Dx Projects

The table of findings can easily be changed to show the results of different Code Dx projects. This is done using the following toolbar button:

A dialog is displayed after you click the Select a Project button. Note that only the projects accessible to your user credentials (provided during configuration) will be shown in this dialog.

Showing Source Code for a Finding

You can view and edit the local source code for a finding by double-clicking on it, or by right-clicking on the selected finding and choosing Show Finding in the context menu. The editor view will open with the associated source code. If there is a line number for the finding, the editor will automatically scroll to that location.

Showing Finding Details

The details of a finding can be viewed by selecting a row in the table and either using the toolbar button or the context menu of the row.

Showing Remote Source

It is sometimes useful to see the current version of a source file on the Code Dx server. For example, if the code local to IntelliJ is different from the remote code. This can be done by selecting a row in the table and either using the toolbar button or the context menu of the row.

The file will be downloaded from the Code Dx server and displayed in a read-only editor.

The title of the editor will be marked with a [Code Dx] label before the filename so that it can be distinguished from local source.

Filtering Findings

The table can be filtered to show only the findings that are assigned to you (left button) and to hide findings that have a status of Ignored, False Positive,Fixed, Gone and Mitigated (right button).

Changing the Status of Findings

You can change the status of a single finding or a group of findings. First select the finding(s) then use either the Change Status dropdown located on the toolbar or the Status option in the context menu.

Refresh

The Refresh button is located to the right of the Change Status drop down. It is used to refresh the table with the findings on the Code Dx server, and reload the Code Dx line markers in opened files.

Finding Details Tab

To navigate to the Details tab, click Details at the top of the Code Dx tool window.

The Finding Details tab shows a minimal version of the Finding Details page in the Code Dx application. If you have the update role for a project, you can change the status of a finding in that project and post to its activity stream.

The toolbar tab contains a Sync button. When enabled, selections in the Findings table will automatically update the information in the Finding Details tab.

Markers

The Code Dx IntelliJ plugin automatically adds source code markers to help you determine the location of the findings within your code.

There are markers in both the left and right gutters. The markers in the left gutter use the Code Dx severity icons to show the highest level severity on the given line. The markers in the right gutter show the findings throughout the entire file.

The context menu on the marker will show a submenu for each finding on the given line.

Please note that Code Dx line markers coexist with other IntelliJ line markers.

Running an Analysis

If you have the create role on a Code Dx project, you have the ability to perform Code Dx analyses on that project from within the IntelliJ IDE. Just select the Run Analysis option from the Code Dx menu.

When the dialog is displayed, select the Code Dx project from the dropdown, and click Run. The IntelliJ Project is the current project open in the IntelliJ window. If your IntelliJ project contains external libraries or modules from external sources, check the "Include External Libraries", and/or "Include Modules From External Sources" check mark(s) in order to add those files to the analysis.

An analysis job is created and the progress is displayed in the bottom right corner of the IDE. The Findings table and line markers will automatically be updated upon completion of the analysis.

Burp Suite

The Code Dx Burp Suite plugin provides a way to upload Burp Suite findings to your Code Dx server from within Burp Suite.

A Code Dx project and an API key are required. The API key must have the create role on the project it needs to interact with.

This section of the Plugins Guide explains how to install and use the Burp Suite plugin. For more information, you may visit our GitHub Repository. This plugin is open source and we welcome community involvement.

Installation

The Code Dx Burp Suite plugin is available for download from the BApp Store and from our GitHub Repository.

BApp Store

To install the Code Dx Burp Suite plugin from the BApp Store, go to the Extender tab in Burp Suite, click the BApp Store tab, and click on Code Dx.

On the right panel, click the Install button.

GitHub Respository

The Burp Suite plugin can be found on our GitHub Repository.

To install the extension, go to the Extender tab in Burp Suite and click Add in the Burp Suite Extensions section.

Click Select file for the Extension file field and navigate to the burp-extension-assembly jar, then click Next to load the extension.

Configuration

To configure the Burp Suite plugin, navigate to the Code Dx tab.

The Server URL and API Key are required fields for sending data to Code Dx. Ask your Code Dx administrator to generate the server API key with the create role for the project(s) which the plugin must interact with.

Once the Server URL and API Key fields are populated, click the Refresh button to list the projects available to the API key in the Project dropdown. It is highly recommended that you specify an HTTPS URL, since using HTTP is insecure.

If you receive a warning regarding an invalid certificate, you will be prompted to Reject, Accept Temporarily, or Accept Permanently. Accepting temporarily will remember the exception until the session ends. Accepting permanently will create a .usertrust directory containing the truststore information. On Windows this will be in your appdata directory, on Mac it will be in the Application Support folder, and on Linux it will be in the .codedx folder in the home directory.

Sending Results to Code Dx

After scanning with Burp Suite, there are two ways you can send the results to Code Dx. The first is to choose a Target URL from the dropdown in the Code Dx Settings in Burp Suite. After performing a scan, click the refresh button to list all of the available targets. Choosing All URLs will send the results from all targets.

Select the project you would like to use, then click the Send to Code Dx button to send the results.

You will receive a message indicating whether or not the action was successful.

The second method to send the results is to use the context menu in the Issues panel of the Target view. To do this, open the Target view and select your target or targets from the Site map.

Select the issues that you want to analyze and right click in the Issues panel. Click the Send to Code Dx button at the bottom of the context menu.

A menu will pop up and will ask you to select the Code Dx project. Note that this option is independent of the project and target settings from the Code Dx view.

As with the previous method, you will receive a message indicating whether or not the action was successful.

OWASP ZAP

The Code Dx OWASP ZAP plugin provides a way to upload OWASP ZAP alerts to your Code Dx server from within OWASP ZAP.

A Code Dx project and an API key are required. The API key must have the create role for the project.

This section of the Plugins Guide explains how to install and use the OWASP ZAP plugin. For more information, you may visit our GitHub Repository. This plugin is open source and we welcome community involvement.

Installation

The Code Dx OWASP ZAP extension is available for installation through the OWASP ZAP Marketplace.

Sending Results to Code Dx

The OWASP ZAP plugin can generate a compatible XML file which can be uploaded manually, or it can upload a report directly to Code Dx.

To upload a report to Code Dx, select the Code Dx: Upload Report option from the Report menu.

You will be prompted for the Server URL, API Key and Project. Your settings will be remembered between sessions and are stored in the codedx.properties file located in the OWASP ZAP folder in your user directory.

After entering the Server URL and API Key, click the Refresh button to populate the Project dropdown.

If you receive a warning regarding an invalid certificate, you will be prompted to Reject, Accept Temporarily, or Accept Permanently. Accepting temporarily will remember the exception until the session ends. Accepting permanently will create a .usertrust directory containing the truststore information. On Windows this will be in your appdata directory, on Mac it will be in the Application Support folder, and on Linux it will be in the home directory.

You will receive a message indicating whether or not the action was successful.

You can generate an XML file for use with Code Dx by selecting the Code Dx: Generate XML Report option from the Report menu.