2.7.2
User Guide

Getting Started

Please refer to the Install Guide for detailed information on getting Code Dx up and running.

Please note that for .NET analysis, Code Dx requires the installation of the .NET runtime, FxCop (Code Analysis), and CAT.NET. See the Installing .NET Tools section in the Install Guide on instructions about how to install these tools.

Code Dx Quick Start

  1. Launch the downloaded Code Dx installer for your platform

  2. Customize the installer defaults as needed; see the Install Guide for details

  3. Once the installation is complete the installer will launch your default browser to your Code Dx installation

  4. In the login area, sign-in using the admin credentials you configured in the installer and accept the license agreement

  5. Once Code Dx is open in your browser, you should see this:

  6. Open the Project List page. At this point there are no projects currently present in Code Dx. The next step will be to create a project by selecting the New Project button and entering the project name.

  7. Then select New Analysis, which is located to the right of the project name.

  8. Select Add File then upload your own Java source, JVM binaries, C/C++ source, PHP source, Scala source, Ruby on Rails source, JavaScript source, Python source, and/or .NET binaries/source. Note: source and binary files must be uploaded in specific file formats. If you would like, you can use one of the sample datasets we recommend in the next section.

Sample Datasets

If you would like to use sample code for testing purposes, the following are some datasets that are all intentionally vulnerable applications used for educational and training purposes. They're referenced by their primary language although some of them are multi-language.

For the following datasets, you can configure your new project's Git Config to fetch the source directly from GitHub using their git URL.

For other datasets, we recommend that you browse GitHub for different projects and scan some of them for testing purposes. Here are some queries to get you started:

Session Management

Logging In

Code Dx is a web-based application. Using a browser, the first thing you should do is navigate to Code Dx and log in. If this is the first time visiting the site after installation, the only usable login credentials will be the Super User's credentials, as configured during installation.

If Remember Me is checked, the server will remember your session until you explicitly log out. This means that even if you leave the site and come back, or if the server restarts, you will not need to log in again. The Remember Me option can be disabled entirely or configured to just remember the username, so please keep in mind that the behavior of this option might vary dependent on how Code Dx is configured by your administrator.

Once more users are added to the Code Dx system, they will be able to log in using this same form.

Log in as the Super User (for this guide, the Super User's username is admin). Once logged in, the Home page will display the User's name ("admin") at the top next to the user icon, and the log-in form will be gone. Note there are now additional page links to visit.

Changing your Password

To change your password, hover over the User icon and User name in the top navigation area and select the Change Password option from the User sub-menu:

From there, a new dialog will show up allowing you to change your password after confirming your existing one.

In the event you’ve forgotten your password, please contact your Code Dx administrator so they may reset your account’s password.

Logging Out

Logging out can happen in one of two ways. The first is by selecting the Logout option from the user sub-menu of the navigation menu:

The second is an automated logout once your session expires. If you leave the Code Dx site for a certain period of time (this is configuration dependent but is usually 30 minutes) you will be automatically logged out. If you select the Remember Me option when logging in, Code Dx will remember you on that computer for your next site visit, but only if this option is enabled by your administrator.

Code Dx Administration

Admin users have access to the Admin page, where they can easily manage Code Dx.

The Admin page is divided into four sections: project management, user management, API key management, and manual entry configuration.

Projects Administration

The Projects section lists all of the projects in your Code Dx installation. You can create new projects and configure them. The main differences are:

The Config dropdown menu (the gear button next to each project) provides options for configuring a project. The options are Rename, Analysis Config, Git Config, JIRA Config, User Roles, Tool Config, and Tool Connectors. As opposed to the Project List page, all config options will always be available on this page, since the page is only available to admin users.

Projects are deleted by clicking the trash can icon to the right of the project name and clicking the confirmation.

For details about the project configurations, please see the Project Management section.

Users Administration

The Users section lets admins add new users, control whether they are admins, and reset passwords. Users can be marked as inactive or deleted. The Super User's admin and active states may not be modified.

There are two ways to add users to Code Dx:

Adding a local user is simple. Just click the Create Local User button to open the New User form. Enter the name and password for the user you want to create, then click Create User.

After adding a few more local users, the Users List will look like this.

To reset an existing user’s password, click the key icon to the right of the Active button and enter the new user password.

Adding an LDAP user is easy as well (note that you need to have LDAP configured in order to add LDAP users – see the Install Guide for instructions on how to configure Code Dx for LDAP integration). Just click the Add LDAP User button to open its corresponding form.

Since the user already exists in your LDAP system, your only job is to let Code Dx know that they exist by adding their "principal" to the Code Dx system. Depending on the LDAP configuration, the principal may be different; for example Bill Lumbergh's username at Initech is blumbergh, so his principal might be blumbergh or blumbergh@initech.com. Once you've added Bill to Code Dx as an LDAP user, he can log into Code Dx with his Initech password instead of having to remember a new password just for Code Dx.

You can easily make any user an admin or change whether or not they are active with a simple switch. Select the trash can icon to the far right to delete a user.

In the screenshot above, Milton has been marked as inactive, and blumbergh has been made an admin. Note the column of Admin switch. When an Admin switch is showing a checkmark with a red background, the corresponding user has administrative privileges within Code Dx. Also note the Active buttons. When an Active button is showing an X with a grey background, the corresponding user is inactive. Being inactive is similar to being deleted in that the user cannot log into Code Dx. Note that any activity performed by inactive and deleted users are still recorded by Code Dx.

API Keys Administration

API Keys can be generated for use with the Code Dx API. Typically one key would be generated for a specific purpose, such as integrating with a specific tool or plugin. This would allow for fine-grained control over each API key’s active/inactive state, as well as setting specific user roles for each key.

Clicking on the Create New Key button will offer up a form to enter in a name for the new API key:

Entering in the new name, and pressing enter or the Create button will create the new API key displaying it in the Key listing:

The key can be regenerated at any point in time by clicking on the wrench icon and can be deleted by clicking on the trash can icon.

Managing roles for each API key is done from the user roles configuration form, just as with regular users.

For more information on Code Dx API capabilities, please read the Code Dx API Guide.

Manual Entry Configuration

The Manual Entry Configuration section, located below the API Keys section, allows Code Dx administrators to define custom values which can be entered into certain fields in the Manual Results form. Note that this section will only appear for users with an Enterprise edition of Code Dx.

The *Manual Entry Configuration* section with all subsections collapsed

There are two sections, both shown above in their "collapsed" state, for configuration; Detection Methods and Allowed Tools.

Configuring Detection Methods

Default state of the "Detection Methods" config area

Code Dx provides four built-in detection methods, i.e. ways to describe how a finding was discovered. These built-in detection methods reflect the types of tools currently supported by Code Dx. For manual entry, you may wish to specify your own custom detection methods. To do so, click the Add Detection Method button, fill in a name, and click OK.

A custom detection method has been added

You can rename your custom detection methods at will. The built-in detection methods cannot be edited in any way (indicated by the lock icon next to their edit/delete buttons).

You can delete your custom detection methods without hassle as long as they are not in use (i.e. as long as no manually-entered results use it as their own detection method). If your custom detection is in use when you try to delete it, you will have to choose a replacement. All results using that detection method will be edited to use the replacement detection method instead. This will likely trigger the recorrelation prompt, since detection method is one of the correlation criteria.

Deleting a custom detection method, and choosing a replacement

Configuring "Allowed Tools"

The Allowed Tools section lets you define which tools will appear in the Tool dropdown in the Manual Result form. The names you add to this list do not necessarily need to correspond to a tool known to Code Dx, or even a real tool, for that matter; you can enter any tool name you want. To add a name to the list, click the Add Allowed Tool button, fill in a name, and click OK. To remove a name from the list, click the red delete button to its right. Unlike the Detection Methods delete, you don't need to pick a replacement to delete an item in this list; this list only controls which tools are available when creating a new manual result, not which tools exist.

The "Allowed Tools" section, with a few tools added

License Management

Code Dx requires a valid license to run. When you first install and run Code Dx, a free 14-day trial license will automatically be generated (requires internet access) for Stat!. You will want to change your license when you purchase Code Dx, do not have internet access, or if your license expired or is invalid.

When you purchase Code Dx, you will receive (usually via email) a new license (a blob of letters and numbers). Please see the Install Guide for information about installing the license.

If the computer you're using does not have access to the internet, please use a different system and contact the sales team via email at sales@codedx.com.

If your license expired or is invalid, the License Management page is automatically displayed with a message indicating the problem. The message is located in the header. Please see the Install Guide for instructions about requesting a new license.

Once a license is installed, its summary will be displayed at the top of the Admin page.

In the example above, the license summary includes the company name (Code Dx, Inc.), product (Enterprise), user-count restriction (5), number of active users (4), and expiration date with timestamp (Fri Jan 13, 2017 at 23:59:31 Eastern Standard Time).

Depending on your license, it may have a user-count restriction. The restriction limits the number of active user accounts managed by Code Dx, regardless of whether they’re Code Dx local users or LDAP users. The "admin" user does not count against this limit. In the example below, Peter, Michael, Samir, and blumbergh@initech.com all count against the license count because they are active users. However, Milton does not count against the license count because he is inactive.

If the system reaches the limit of the licensed user count, an error notification will be displayed when creating or reactivating users. This can be remedied by deactivating or deleting users that no longer have a need to log in and use Code Dx. Alternatively, arrangements can be made with our sales team to upgrade and replace the current license with one that has a larger user-limit.

Project Metadata Fields

Project Metadata Fields are an Enterprise-only feature which allows users of Code Dx to create and configure custom metadata for their projects. A form on the Admin page allows for the definition of custom fields which may be used by any project in your Code Dx installation. This section covers how to define those fields. For information on how to enter values for those fields on projects, refer to the Project Metadata section under Project Management.

Assuming you have a Code Dx license that supports the Project Metadata feature, there will be a metadata fields button in the upper-right corner of the Admin page's Projects section. Clicking this button will expand/collapse the Project Metadata Fields section:

after expanding the Project Metadata Fields section

*Note that the first time you expand the area shown above, no fields will be defined yet.

To create a field, press the Create a field button. The following form will appear in its place:

the "Create a field" form

The Field Type dropdown menu lets you pick how users will enter values into the field:

When you pick "Dropdown" as the Field Type, you must also define at least one "choice" by clicking the Add a choice button.

Creating a dropdown field, need to click "Add a choice"

Each choice must have a Display - this is what a user will pick from the dropdown menu when filling in the choice's respective field. ID is optional - it's most useful when programmatically consuming metadata. For example, the Dropdown field named "Criticality", which is shown in the first screenshot, uses the numbers 0 through 4 as IDs, and a more human-readable value as Display. In a Project configured as "Medium" criticality, an XML would include the number 2 alongside the word "Medium" in the project metadata section.

Creating a dropdown field, one choice created, a second one on the way

Fill in the ID however you see fit, or not at all, but note that if you do specify an ID, it needs to be different from the other IDs for that field.

Filling in the same ID in the same field is an error

You can add, edit, and remove choices for Dropdown fields while editing that field. Don't forget to click OK when you're done. The OK button is located to the right of the Dropdown name.

Sometimes when you try to save a field after having removed choices, a conflict occurs:

Project Management

Terminology

The following are the key terms used throughout Code Dx and this guide.

Projects contain any number of Findings. Findings can either be created manually, or automatically via Analysis. Results (either from tools during Analysis, or from manual entry) are processed, correlated, and associated with Findings.

The Project List

The Project List page presents a list of Code Dx projects that currently exist. To access the Project List page, just click the Projects link in the page header after logging in. If this is the first time using Code Dx, the Project List may be empty. Admin users can create new projects by clicking the button labeled New Project.

Click the button to open the New Project form.

Create a new project by entering a name and clicking the Create Project button. The new project appears in the project list.

The Findings link opens the Findings page, which provides an overview of the analysis results. It focuses on a powerful filtering system, triage workflow, and issue tracking, with links to drill into more details via the Finding Details page.

The Config dropdown menu gives a user the manage role the ability to configure a project. The options are Rename, Analysis Config, Project Metadata, Git Config, JIRA Config, User Roles, Tool Config, and Tool Connectors. For details about these options, refer to the sections that follow.

A project's config menu

Once a project is created it is recommended to assign one or more users to it and give them the manage role. This enables them to create and archive analyses and control the project configurations. If you're using Code Dx Enterprise, someone with the create role can access the Tool Connectors option in the Config dropdown menu; however, this is the only option available to them and they can only run the tool connectors.

Filtering Projects

In the case where you have many projects, it can be tedious scrolling to the project you are looking for. To help with this, the project filter lets you filter the Project List by name. To filter, enter your text into the Filter projects text box. The Project List will update as you type. In the screenshot below, the word "sample" has been entered, and the Project List displays only those projects that have the text "sample" (case-insensitive) in their project names.

Using the Project Filter to show Projects with "sample" in the name

You can clear your text by pressing the "X" button on the Filter projects text box.

Users of Code Dx Enterprise will also have access to advanced filters, which operate on Project Metadata. To expand the advanced filter section, click the "advanced" link to the right of the project name filter input. Note that if you have not configured any Project Metadata Fields, the "advanced" link will not appear. If you have, an input for each field will appear. Enter your search criteria in its respective input to filter the project list. Text fields behave similarly to the basic (project name) filter; as long as some part of a project's metadata on that field matches your input, that project matches. Dropdown fields operate on exact matches, for example; "Projects with 'High' Criticality". Tag fields operate on the principle, "if a project's tags contain at least one of the tags in my filter input, that project matches." In the example below, we filter on projects where the Project Owner field is "Richard Hendricks".

Using the advanced project filter to filter on project metadata

Project Groups

Projects may be repositioned in a hierarchy, where one project may become the parent (or group) containing another project. This functionality may be accessed via the Move into option in a project's config menu: Click Move into, then select a "parent project" from the dropdown that appears (or clear the dropdown to pick "no parent project"), and click the OK button.

selecting a parent for a project

Once you move one or more projects into a "parent" project, the parent project can be considered as a "project group". The Project List UI will display project groups as a summary of all findings for all projects in that group, including the group project itself. Project groups in the UI can be expanded to show their respective "child" projects using the chevron (>) button next to the name. Note that a project group is still a project, and can still have findings of its own. The summary of findings specific to the parent project will appear above the child projects when you expand the group. There is no inherent limit to how deeply-nested projects can be. A child project can have its own child projects, and so on.

a project group

Analysis Configuration

The Analysis Configuration dialog is used to control two analysis-related settings for a given project. Users with the manage role for a project can access the Analysis Configuration dialog from the Project List page. Locate the project to be configured, open the Config dropdown, and select Analysis Config from the menu.

Sample Analysis Config Dialog

Auto-Archival

As files are analyzed with Code Dx, each one is remembered as an analysis input. As more and more analyses are performed with a project, these analysis inputs could start to pile up. The Auto-Archival setting in the Analysis Configuration dialog controls how old analysis inputs are handled.

By default, auto-archival is enabled. As new inputs are analyzed, old inputs of the same type will be archived. For example, two analyses are performed in series on a project, both supplying a FindBugs results file. In this scenario, the Findbugs results file provided for the second analysis is perceived as "newer", so it will replace the FindBugs results from the first analysis. The analysis input for FindBugs results in the first analysis will be archived. Any findings that were present in the first file but not the second will have their statuses changed to Gone as a part of this process.

With auto-archival disabled, the two FindBugs result files will both remain present. This can be useful if you wish to provide one FindBugs results file for a part of your application, but a different FindBugs results file for a different part of your application. Both files may be analyzed without interfering with each other. A downside to this approach is that without manual management of the analysis inputs, they will begin to pile up, potentially degrading the performance of filters and other interactions. You can manually archive old inputs from the Analysis Inputs List

Prevent Correlation

If the Prevent tool result correlation option is checked, then multiple tool results will not be added to a finding. This will give you a separate finding for every issue reported by a tool. Tool results will still be associated with rules according to the selected Rule Set; however, when multiple instances of the same issue occur at the same location, they will not be merged.

Rule Set Associations

Rule Sets allow general rules to be created, encapsulating results from different tools and providing standard information for the finding. For example, a general "SQL Injection" rule may be created to capture specific results from multiple tools and provide a shared description, making it easier to locate and recognize standard vulnerabilities.

When tool result correlation is enabled, the selected Rule Set is also responsible for determining which issues represent the same issue. When results exist at the same location that map to the same rule, they will be merged into a single finding.

Rule Sets can be associated with projects via the Analysis Configuration dialog. By default, new projects will use the built-in "Code Dx Rules" set. The "Don't use any Rules" option is available in case you don't want tool results to be mapped to rules.

Users with the admin role can create new Rule Sets either by clicking the Add button at the bottom of the list, or clicking the Clone button.

Pointing out the Add and Clone buttons for Rule Sets

Adding a Rule Set via the Add button will initialize a blank Rule Set.

"Add Rule Set" Form

A cloned Rule Set will be initialized as a copy of the "parent" set. This can be useful if you want one project to use mostly the same correlation logic, but with a few alterations from another project. Also note that the default Code Dx Rules set is read-only. To make modifications to it, create a clone of it, then make the modifications to the clone instead.

"Clone Rule Set" Form

To modify an existing Rule Set (or simply view it, in the case of the read-only Code Dx Rules set), click the pencil button (or the eye button) next to the Rule Set's name. This will open in a new tab.

Reminder: When making changes to the Analysis Configuration dialog, make sure to press the OK button to save them.

The Rule Set Page

Each Rule Set has Rules, and each Rule has Criteria and identifying information.

Rules are applied during ingestion, when findings are created from tool results. If there are multiple tool results belonging to the same rule and they occur at the same location, they will all be associated with the same finding.

Rule Identifying Information

The identifying information for a rule includes severity, CWE, and a description. These fields are all optional; when provided, they will alter the corresponding values for findings associated with that rule.

Each rule's identifying information is collapsed by default. To expand it, click the button to the right of its name.

Expand/Collapse Rule identifying information

If you have the admin role, you can edit an existing rule's identifying information (aside from the read-only Code Dx Rule Set).

To rename a rule, click on its name to open a renaming input. Enter a new name then press Enter.

Rename Rule

To change the severity, CWE, or description for a rule, expand the identifying information section, then click the pencil icon next to the corresponding header. This will activate an inline form allowing you to make changes to the value. Once you've set the desired value, click the Save button to apply the change. Click Cancel to discard your changes without saving.

Edit Rule Details

You can add criteria from editable rules via the forms at the bottom of each rule's criteria list.

Rule Criteria

A rule's criteria control which tool results will be matched with a rule. Note that each criterion can only appear once in a Rule Set. If you attempt to add a criterion that already exists in a different rule, you will be given the option to move the criterion out of that rule, or just cancel. Users with the admin role can edit the criteria for each rule.

Criteria can be created for rules using the add criterion buttons for that rule. These buttons are located at the bottom of the criteria list.

Add Criterion Buttons

Criteria can be deleted from rules using the delete button for that criterion. The button is hidden until you hover over the criterion in a rule's criteria list.

Delete Criterion Button

Tool Criteria

The Add Tool Criterion form allows you to create criteria that operate on a tool result's type. An individual tool criterion specifies a tool, category, and code. It will match tool results whose raw values match the values specified by the criterion.

Example Tool Criterion

Note: The exact values for the tool criterion fields vary depending on what is reported by the tool. One way to discover these values is to look at the Finding Details page for existing findings in Code Dx. The Tool, Tool Category, and Tool Code are displayed in the Tool Details for each associated tool result.

Example Tool Details

The category and code fields are both optional. Omitting both will create a criterion that matches all results from the specified tool. Omitting just the code will create a criterion that matches all results from the specified tool marked as part of the specified category. Some tools do not specify a tool category, in these cases the tool category field will need to be left blank. Note: leaving the tool category field blank does not act as a wildcard, so if the tool specifies categories, they must be included in all rule criteria.

CWE Criteria

The Add CWE Criterion form allows you to create criteria that operate on a tool result's CWE. By specifying a CWE ID value, a CWE criterion will match tool results with that CWE value.

After Changing Rule Sets

Since a project's configured Rule Set determines the manner in which results are correlated, changing that configuration necessitates an update of the correlation. This happens when the configured Rule Set for a project is modified in any way, or the Analysis Configuration is changed to use a different Rule Set. When this happens, the Findings page will display a notification prompting users to do so.

Trigger Re-Correlation

Tool Configuration

During analysis, tool results are identified by a tool result type, which is a combination of the tool's name, any number of "groupings" (e.g. categories), and a name. The Tool Configuration page allows users with the manage role on a project to enable and disable tool result types for that project. Results whose tool result types are disabled by configuration will be ignored during analysis.

Users with the manage role on a project can access the Tool Configuration page for that project via the Project List page. On that page, locate the desired project, open the Config dropdown menu, and click the Tool Config link from the dropdown. Admin users can also access the Tool Configuration page from a similar dropdown on the Admin page.

Overview of the Tool Configuration Page

Tool result types are organized in a hierarchy, grouped by tool, then category(ies), then name. Tool result types can be enabled and disabled at any level of their hierarchy by clicking its respective on/off switch. For example, it is possible to completely disable a tool by clicking the switch next to that tool in the Tool Configuration page. Some entries will be disabled by default. The default enabled state is carefully selected by the Code Dx team to provide the best results for the Code Dx users. However, this can be overridden at any time from this page by just re-enabling the desired tool result types. Clicking on an entry (aside from its toggle switch) will expand (or collapse) it, showing all of its sub-entries.

Note that any changes made on this page are project-wide, impacting all users of the project.

For instance, the following screenshot shows the Experimental group within Findbugs disabled by default.

Disabling the 'Experimental' category under FindBugs

Code Dx comes with a large set of predefined tool result types, based on the results generated by a collection of open-source tools. When Code Dx encounters a new type of tool result, it will create a corresponding entry based on the result's raw tool code. These entries are referred to as "observed", and are marked with an eye icon.

If a change to the tool configuration would cause existing tool results to be disabled, it does not immediately remove those results. Instead a notification will appear, indicating the number of results that would be affected, prompting the user to purge those results. Clicking the Purge button in the notification will remove any tool results that still exist despite being disabled. Doing so is highly recommended, as having fewer tool results will improve the performance and responsiveness of Code Dx. If you do not purge disabled tool results, they will remain present in the project, and will continue to appear in filters and affect future analyses.

The 'Purge' notification

User Roles Configuration

To manage user roles for a project, click the User Roles option from that project's configuration menu (on the Project List page or the Admin page). Each role designates a set of specific actions that a user is allowed to take on a project.

The User Roles dialog will appear. In this view, there is a row for each user. Each button represents a role which that user has in that project. All roles are assigned per-user, per-project, meaning that a user's roles for one project are not necessarily the same as his or her roles for another project. For each user, if they are marked as admin or inactive, the view will display a marker next to their name to show that fact.

The different roles are as follows:

Clicking one of the role buttons in the User Roles dialog will give the corresponding user all roles up to (and including) that role. For example, giving a user the create role will also give him or her the read and update roles. Clicking the X button will remove all of that user's roles. Admin users automatically have all roles; you cannot modify the roles of admin users.

Git Configuration

To manage the git configuration for a project, click the Git Config option from that project's configuration menu, on the Project List page or the Admin page.

The Git Configuration popup will appear. The form inside is used to tell Code Dx to use a Git repository as the subject of analysis for this project. Once configured, Code Dx will automatically include the contents of the configured repository as an input for each analysis with this project.

The form (shown above) has two fields: Repository URL and Branch. The Repository URL should be filled out with the URL that you would use to clone the repository. The Branch field should be filled with the name of the branch in that repository that you want Code Dx to analyze. If left blank, Code Dx will assume you mean the "master" branch, which is the main branch for most Git repositories.

For many projects, setting up a Git configuration is as easy as copying the repository's URL into the form. For example, if you wanted to analyze the contents of the open-source WebGoat repository, you would find the clone URL on the side of the GitHub repository page, and copy it into the Repository URL field of the Git Configuration form.

Code Dx will verify the repository's existence and determine whether it needs credentials to connect. For public (open-source) repositories, no credentials are required, and you can press the Ok button to save and close the form. If this is the case, you may skip to Saving the Git Configuration; otherwise, read on.

Git Credentials

Some Git repositories are private, and require credentials for access. Code Dx supports two forms of authentication; HTTP and SSH. Depending on the URL in the Repository URL field, Code Dx will automatically determine which type of credentials are required.

HTTP Credentials

HTTP credentials are a username and password. For GitHub repositories, these will generally be your GitHub account name and password. GitHub also supports creating "Personal access tokens" (see https://github.com/settings/tokens), which can be used in place of a password.

SSH Credentials

SSH uses a pair of files known together as a "keypair", or separately as a "private key" and "public key". For Code Dx to connect to a repository via SSH, it needs your "private key". The system in charge of the repository's security will also need your "public key".

If you are trying to access a private GitHub repository, visit your SSH Keys page at https://github.com/settings/ssh to register your SSH key with GitHub. GitHub also provides help with SSH-related issues at https://help.github.com/categories/ssh/

Some users will already have an SSH keypair on their computer. The two files are generally located in <userhome>/.ssh/ and will be named id_rsa for the private key, and id_rsa.pub for the public key. It is possible to use this pair, but you may want to generate a separate pair for use with Code Dx.

Once you have located or generated a keypair, copy the contents of the private key file into the Private Key field of the form.

When generating a keypair, you have the option to provide a "passphrase" for the private key. If you do this, Code Dx will need that passphrase in order to use your private key. Enter it in the Key Passphrase field of the form.

Two-Factor Authentication with GitHub

If you need to connect to a GitHub repository, and your GitHub account has two-factor authentication set up, you cannot use your regular username and password to authenticate. To connect over HTTP (e.g. https://github.com/user/repo), you will have to set up a Personal Access Token and use it in place of your regular password. You can still connect over SSH (e.g. git@github.com:user/repo.git) as usual.

Saving the Git Configuration

Once you have entered a URL, an optional Branch, and entered whatever Credentials are necessary, you can click the Ok button to save the configuration. Doing so will close the form and tell Code Dx to obtain a local clone of the configured repository. Depending on the size of the repository, the length of its history, and your network connection, the clone operation may take anywhere from seconds to hours. Once started, a progress bar will be displayed underneath the project's title in the Project List page.

The "cloning" job has several subtasks, so you will see the progress bar fill up several times. When the job is complete, the progress bar will turn blue, wait for a couple of seconds, then slide out of view.

Once the clone is ready, the New Analysis page will automatically include the latest contents of the configured branch of the configured repository as an input. See the Analyses section for more detail.

Issue Tracker Configuration

Code Dx allows you to associate findings with issues in an issue tracker, either by creating a new issue, or by identifying an existing issue. Currently, JIRA is the only issue tracker we support. In order to use the JIRA integration, you must have access to an account on a JIRA server, either hosted locally or in the cloud.

To configure an Issue Tracker for a project, select the JIRA Config option from that project's Config menu on either the Project List page or the Projects List on the Admin page. That will bring up a dialog. Note: the "Field Mapping" and "Status Mapping" tabs are visible in Code Dx Enterprise only.

Issue Tracker Configuration Modal

Enter the URL for your Issue Tracker server (including the "http://" or "https://", even if you're using an IP address), as well as the username and password for the user in whose name the issues will be created. Then click the Verify Connection button. Code Dx will connect with the server and retrieve a list of projects the user can access. Select the project you want from the dropdown menu. Code Dx will periodically query the issue tracker server to refresh the status for all of the issues associated with a given project. The Refresh Interval specifies the number of minutes between refreshes (the default is 60 minutes). Click Ok to save your configuration.

If you delete the issue tracker configuration for a given project, all of the issue associations tied to the findings in that project are deleted. None of the issues on the issue tracker server itself are affected.

Advanced Field Configuration

Note: this section is only applicable to Code Dx Enterprise users.

When creating an issue from Code Dx, we provide several standard fields (e.g., summary, description). But many issue trackers provide more than just a few fields for issues and can be configured to require these additional fields when creating an issue. Issue trackers also sometimes allow the creation of custom fields on a per-project or per-server basis. Code Dx provides for this situation through "Advanced Fields". JIRA users should note that Code Dx supports all of JIRA's "Standard" custom fields; while many of JIRA's "Advanced" custom fields will also work correctly, some are implemented via third party plugins and cannot be fully supported. These fields will still appear and can be used if the correct format is known, but they should be left empty otherwise.

If you're using Code Dx Enterprise, you can create template expressions for any of the fields available when creating an issue for the configured issue tracker server. These expressions will be applied to the relevant Code Dx finding (or findings) when you create an issue, which allows Code Dx to pre-populate the field with data from the finding, according to your specification. More technical users should be advised that the template language is the JavaScript Handlebars library and that all of the template expressions are Handlebars Expressions.

Code Dx will use its own default values for Summary and Description fields if none are specified.

Users should also note that because fields can be given template expressions, which won't be evaluated until a finding is available, the validation that can be done on the fields is limited. The issue tracker field mappings are an advanced feature, and it is incumbent upon the user to make sure that the default values and expressions entered will produce valid values for the relevant JIRA field types.

Expression Basics

The template engine will use the text you provide as-is, but it will treat anything inside pairs of double braces, {{ }} as an expression to be evaluated using the active finding or findings. Code Dx defines three basic data objects that can be used in the template expressions:

Each finding object has the following fields:

These objects can be used to construct expressions containing data from the active findings. For example,

Finding {{finding.id}} has {{finding.severity.name}} severity

will, when applied to a Code Dx finding with ID 1 and High severity, produce the text:

Finding 1 has High severity.

The project object has the following fields:

Expression Logic

You can add basic boolean logic to your expressions by using

{{#if condition}}this will be used{{/if}}. condition

will be evaluated as a boolean expression, and if it's true, the text will be used in the template's output. You can use {{else}} to create an else condition. For example,

{{#if finding.detection.isDast}}DAST{{else}}Not DAST{{/if}} finding

will result in

DAST finding

if the finding in question is a DAST result (i.e., finding.detection.isDast == true), and

Not DAST finding

otherwise.

You can add loops to your expression using

{{#each array}}Text for each item {{this.field}}{{/each}}.

The template engine will loop through array, adding the contained text for each item in the array. The item in the array will be bound to this within template expressions inside the loop. For example,

{{#each allFindings}}{{this.id}}{{/each}}

will generate the finding ID for each active finding.

{{#each}} is important, because as you can see in the above summary of the properties of the finding objects, many of the properties are arrays and therefore can't simply be accessed directly—you need to iterate over them and access each property inside the loop.

Formatting Helpers

Code Dx provides several "helpers" to improve your ability to format the finding data.

The formatDate helper allows you to format a date by specifying a format string. For example:

{{formatDate finding.firstSeenOn 'YYYY-MM-DD'}}

will take the creation date for the finding and convert it into an ISO-8601 valid format. You can use the symbols below to create your format string:

The formatDate helper uses Moment.js under the hood, so you can look at its documentation for more formatting symbols.

The makeOxfordList helper is similar to each described above. It will take an array of elements and transform it into a list with a separator between each element and a conjunction between the last two elements. For example, given an array

fruits = [apple, banana, orange, peach],

{{#makeOxfordList fruits ',' 'and'}}{{this}}{{/makeOxfordList}}

will produce

apple, banana, orange, and peach.

The formatLocation helper creates a human-readable version of a finding's location.

{{formatLocation finding.location}}

might produce

AbstractLesson.java:182.

You can optionally use a boolean value to request the full location, as well as location column information used:

{{formatLocation finding.location true}}

might produce

WEB-INF/classes/org/owasp/webgoat/lessons/AbstractLesson.java:182

The formatCWE helper creates a more informative representation of a finding's CWE (if one is available).

{{formatCWE finding.cwe}}

might produce

CWE 78 - Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection')

or an empty string if no CWE is available for the finding. You can optionally use a boolean value (as with the formatLocation helper above) to request links to CWEVis and MITRE data about the CWE, as well as a full sentence indicating no CWE is available (if applicable), rather than merely an empty string.

Other Examples

This is the template expression used to pre-populate the Description field, if the user doesn't override it:

{{#each allFindings}}
    [Code Dx Finding {{this.id}}|{{this.link}}]
    {{this.descriptor.name}}

    {{#if this.detection.isManual}}manually entered {{else}}
        detected by {{this.detectedBy}}
    {{/if}}
    {{#if this.location}}
    {{formatLocation this.location}}
    {{/if}}

    {{formatCWE this.cwe true}}
{{/each}}

Enumerable Fields

Custom fields that are represented as one of a set of enumerable values (e.g., a set of radio buttons or a dropdown menu) can be configured to be pre-populated by selecting the enumerable Code Dx field from the available dropdown menu. The currently defined enumerable fields are:

Once you select a Code Dx enumerable field, you'll see a table with a row for each possible value, along with a dropdown containing the possible values of your custom field. Simply choose from the dropdown which of your custom values you want to use for each Code Dx value. The Static Value option is there if you wish to define a single value for the JIRA field, regardless of the values in the Code Dx finding.

Automatic Status Updating

Note: this section is only applicable to Code Dx Enterprise users.

Code Dx can be configured to automatically update JIRA issue statuses in response to triage status changes within Code Dx. This is configurable on the "Status Mapping" tab.

Issue Tracker Status Mapping

When automatic status updating is enabled, a list of Code Dx triage statuses will be shown, along with a drop down to pick the associated JIRA status. These mappings are optional, if one is not selected, then no action will be taken on findings with that status.

After configuring status mappings, any time the status of a finding is updated, the associated JIRA issue will be updated according to the mapping (if applicable). If a transition is not available, or requires user input, to update the JIRA issue from its current status to the desired status, then no action will be taken. Additionally, if multiple findings are associated with the same JIRA issue, the JIRA status will only be updated if all findings map to the same status.

Tool Connectors

Tool Connectors allow Code Dx to pull results directly from external tools, without the manual work of exporting the results from those tools and uploading the results into Code Dx. Users with the manage role can configure a connection to their tools one time, and have Code Dx take care of the rest.

Code Dx currently supports connectors for the following tools:

The Tool Connectors dialog for a project can be accessed from its respective Config menu on the Project List page or the Admin page.

On a new project, no tool connectors will be configured.

Tool Connectors dialog with no configured connectors

In the image above, there are no tool connectors configured. Clicking any of the links in the bottom section will open a form to configure a connector for the link's respective tool. For this example, we'll configure a new Checkmarx connector by clicking the New Checkmarx Connector link.

A blank Checkmarx Connector configuration form

Each tool connector configuration form will have a common set of fields:

Note that credentials entered for tool connector configurations will be stored (encrypted, but still reversible) by Code Dx. Cautious users may wish to create one-off accounts in a tool, with the sole purpose of connecting Code Dx to that tool. This will help avoid actual users' credentials from being stolen if the Code Dx server is somehow compromised.

When entering credentials like passwords, a Verify button will sometimes appear on a field. When it does, the user must click the Verify button in order to continue on to fields that depend on the password (e.g. the project dropdown). This is done to avoid inadvertently locking out a user by attempting to log in while the user is typing his or her password.

Connector configuration before password validation

This is how the form looks after you click the Verify button.

Connector configuration after password validation

Once all of the fields are completed, press the OK button to save the configuration and return to the connectors list. In the image below, three connectors have been configured.

Tool Connectors dialog with three configured connectors

Each configured connector has three buttons:

After pressing the Run Now button, the Tool Connectors dialog will close, a new analysis will begin in the background, and a notification will display.

A tool connector analysis has started

Project Metadata

Project Metadata is an Enterprise-only feature which allows users of Code Dx to enter values into Project Metadata Fields for any project they have the manage role for.

The Project Metadata dialog can be opened by clicking the Project Metadata... option in the project's Config menu on either the Project List page or the Projects List section on the Admin page.

It is up to an admin user to define the fields; once defined, they will be available to every project in your Code Dx installation. Below is a screenshot of the Project Metadata dialog after some example fields have been created by an admin user.

Example Project Metadata with blank fields

And a screenshot of the same Project Metadata dialog with some values filled in.

Example Project Metadata with filled fields

Each field has a Reset button (with a circular arrow icon) to the right, which will reset the field back to its saved state. If you make any edits to that field and want to undo them, just click the Reset button.

Each field also has a Clear button (with an "X" icon) to the right, which will clear any value in that field. (Note that the Reset can also undo clears, as long as they aren't saved yet.)

There are four types of fields:

Analyses

This section explains the analysis capabilities of Code Dx. Both the Code Dx Enterprise and Stat! products come with bundled tools to scan the applications of interest to you. The languages we support and expected inputs for the built-in scanners are described in the Built-in Code Scanners and the Built-in Dependency Scanners sections. In addition to the bundled tools, Code Dx Enterprise can import the results of several commercial and open source tools. The supported tools and generic input formats are described in the Importing Scan Results section. There are a number of different options to configure and run analyses for Code Dx: manually using the web interface; from the IDE or Jenkins plugins; automatically (such as from your continous integration server) using the API. These are all detailed in the Starting Analyses section.

Incremental Analysis

As of Code Dx version 2.0, analysis is done incrementally. This means that as new analysis inputs (files) are added to a project, any findings associated with them are added to the project. Prior to version 2.0, the entire set of files was replaced with the new set of inputs.

With this change to incremental analysis, the life of a finding becomes tied to the inputs in which it was reported. When the last input contributing to a finding is archived, the finding itself is marked as 'Gone' and hidden by default (see View Options).

Analysis inputs can be archived manually or automatically. For more information on archival, see Auto-Archival.

Built-in Code Scanners

Code Dx analyzes C/C++, Java, JavaScript, JSP, .NET (C#, VB), PHP, Scala, Python, and Ruby on Rails applications. For all supported languages, Code Dx will analyze the source using bundled tools built specifically for a target language. For applications built with any combination of the supported languages, Code Dx will run the appropriate checkers on the provided source.

For Java applications, Code Dx supports scanning compiled bytecode. In fact, the preferred approach for Java projects is to upload both source and bytecode to Code Dx in the supported file format described in the bullets below. This yields the best coverage for issue detection.

For .NET applications, Code Dx supports scanning compiled DLLs. It is also recommended that the source be uploaded. This will provide better source location information and will allow for viewing the source while looking at finding details. Note: If you choose to upload an entire Visual Studio solution folder, there may be duplicates of the build DLLs and third-party DLLs. This will cause a longer analysis time and possibly incorrect results if some DLLs are stale. To achieve the best results, upload a zip that contains only the DLLs and PDB files for the binaries you wish to analyze. Upload the source as a separate zip.

Code Dx accepts application inputs in the following formats:

Note that Code Dx enforces a single source zip archive per analysis. So even though Code Dx supports multiple languages, the expectation is that they will all be packaged in a single zip archive to enable consistent path correlation across all the checkers. Although source and bytecode inputs can be uploaded in separate files, they do not have be split up. A single zip file containing C/C++ source, Java source, Java bytecode, .NET DLLs, .NET source, PHP source, Scala source, Ruby on Rails source, Python Source, and JavaScript source is perfectly acceptable.

Built-in Dependency Scanners

Code Dx also scans input to check for dependencies with known vulnerabilities. The following are checked:

Importing Scan Results

Code Dx Enterprise supports importing the results of more than 40 commercial and open source application security testing tools (AST), in addition to a couple of generic tool result listing formats. The list of supported tools for scan imports includes the built-in ones mentioned in the previous section. If one of the tools you want to import is not supported, please let us know. However, in the meantime you can convert your data to the generic Code Dx Input XML format. The schema definition for this format and an example can be accessed via the download icon in the Code Dx header.

SAST Tools

The following are the supported SAST tools and import formats supported by Code Dx Enterprise:

DAST Tools

The following are the supported DAST tools and import formats supported by Code Dx Enterprise:

Threat Modeling Tools

The following are the supported Threat Modeling tools and import formats supported by Code Dx Enterprise:

AppSpider Support

Code Dx accepts the VulnerabilitiesSummary.xml file from AppSpider. This file is output as part of the report generation process within AppSpider. The following instructions describe how to generate a report and locate the summary XML file:

  1. Run a new scan or open an existing scan in AppSpider
  2. Generate a report by clicking the Generate Report button on the scan toolbar Generate Report
  3. Locate the generated report on disk - the default location is Documents/AppSpider/Scans, however this option is configurable within AppSpider
  4. Within the report folder, there will be a VulnerabilitiesSummary.xml file - this is what should be uploaded to Code Dx for analysis

CodeSonar Support

The preferred means of importing CodeSonar result into Code Dx is to use the CodeSonar Tool Connector. But in situations where the machine running Code Dx and the machine running CodeSonar cannot communicate with each other, the CodeSonar-Scrape utility helps bridge the gap.

CodeSonar-Scrape is a command-line utility that you can use to generate a Zip file that Code Dx understands as CodeSonar results. You provide it the URL of your CodeSonar server, the name of the project you want to import into Code Dx, and optionally your username and password. It will then find all of the "warnings" associated with that project, downloading them into a Zip file which you can then upload to Code Dx. Results imported in this manner will include descriptions (tracing) information, and links back to CodeSonar's hub for warning details and category documentation. Detailed instructions for this tool can be found in the CodeSonar-Scrape User Guide. If you need CodeSonar-Scrape or have questions on the topic please contact us.

Starting Analyses

There are a number of different ways to prepare and initiate an analysis within Code Dx:

Note that only users with the create role for projects can initiate new analyses.

Starting Analyses Manually from the Web Interface

Analyses can be prepared and initiated manually from the Code Dx web interface. To do so, the first step is to go to the Project List page, find the project that you want to run the analysis for, and click the New Analysis button.

This will take you to the New Analysis page.

To add a file to the page, you can use the Add File button. A file picker dialog will open and you may select one or more files, as is shown in the next image.

Alternatively you can drag the files over the same button area. When dragging and dropping, the page will change to display the drop region:

Please note the drag-and-drop functionality is not supported by all browsers.

As you add files to the page, they will be uploaded to the Code Dx server for identification. Once the server has identified the file contents, the page will update to display the detected content along with any errors or warnings about the contents.

In the image above, a zip file containing Java .class files was added, and tagged as a Java Library. Based on this content, Code Dx identified Dependency-Check and FindBugs as the tools to run on this file. Each tag in the Detected Content and Tools to Run sections can be disabled. If desired, click the checkbox on the tag to disable (or re-enable) that tag. Sometimes, disabling a content tag will make Code Dx decide that a certain tool is no longer applicable to that file. Disabling a tag in the Tools to Run section will tell Code Dx not to run that tool, even though it is applicable to that file.

In the image above, a second zip file was added, containing .java files as well as some C# source files and .NET (CLR) compilation artifacts. The file was tagged as C# Source, Java Source, and CLR Binary. Code Dx identified five different tools to run on that file. Additionally, since both files have been tagged as a "Library", Code Dx won't allow an analysis. This can be solved by disabling the CLR Library tag on the new file. In this example, since we are only interested in the Java-related contents of the project, we disable the C# Source tag as well.

With the two tags unchecked, the warnings and tools that were only applicable to those tags have disappeared, and Code Dx will once again allow the analysis to start.

Once ready, click the Begin Analysis button at the bottom of the files area to start the analysis of those files. If for some reason there is a problem with the files, the Begin Analysis button will be replaced by one or more messages indicating what is wrong. You'll have to address whatever problems are mentioned there before starting an analysis.

Analysis is conducted as a "job". The work order is placed in the job queue and will be executed once enough resources are free. Often, the time spent in the queue is negligible, but you may still see a brief flash of a message stating that the analysis has been queued. Once the analysis job is finished queueing, the analysis will begin. The page will display a timer to indicate the current duration of the analysis.

The actual duration of the analysis depends on many factors.

Once the analysis has been queued, it is safe to leave the page. The analysis will continue in the background. It is still advisable to keep the page open in order to see any warnings or errors that might occur during the analysis. Occasionally a tool will fail, or some other unexpected problem will arise. Depending on the problem, the analysis might fail, or a message will be added to the New Analysis page.

If the analysis completes successfully, the analysis timer will become a link to the Findings page. Any currently-opened Findings pages will be updated to reflect the latest analysis results.

Inputs from Git Repositories

If you set up a Git configuration for a project, the New Analysis page will automatically include the latest contents of the configured branch of the configured repository as an input.

Normally, Code Dx will update the local clone and check out the appropriate branch before sending the files to the analysis. If you set up your configuration to use the master branch, it will fetch the latest changes from master. As development is done on that branch, analysis of that branch will change along with the contents. But if you want to analyze a specific point in the repository, you can tell Code Dx to use a specific tag or commit by clicking on the underlined section of the input.

Fill in the field with a tag name or a commit hash, and click the Use this button.

Starting Analyses Manually from the IDE Plugins

Code Dx offers plugins for Visual Studio and Eclipse. These plugins offer many features to view and interact with the results of Code Dx analyses within the comfort of developers' familiar development environment. Among the features offered by the IDE plugins is the ability to initiate a scan directly from the development environment. This simplifies the process of packaging the relevant source and compiled artifacts (when applicable) since it is largely an automated process beyond some basic configuration options. For more details on how to initiate analyses from the IDE plugins, please see the Plugins Guide's relevant sections for the Visual Studio and Eclipse plugins.

Starting Analyses Automatically Using the API

Code Dx offers an expanding API to interface with the system's functionality programmatically. The ability to push files for an analysis by Code Dx is exposed by the API. This enables automated integration scenarios such as continuous integration. In a continuous integration scenario, a post-build step can be added to the build jobs to automatically push the source and compiled artifacts to Code Dx for analysis. This type of setup is strongly recommended for development teams to catch potential issues within their codebases early for quick remediation. "Test early and often" is advice that most certainly applies to static analysis. Code Dx does offer a Jenkins plugin, to facilitate use in a continuous integration context.

In order to use an API key for automated analyses, the key must be assigned the create role for the project. The API call to push the files and initiate the analysis is documented in the API Guide.

Findings

The Findings page gives an overview of the findings in a project, focusing on a powerful filtering system, triage workflow, and issue tracking, with links to drill into more details via the Finding Details page. To access the Findings page, click the Findings button next to a project in the Project List page.

This section is structured around the various user interface elements on this page that contribute towards the triage process.

CWE Support

The Common Weakness Enumeration (CWE) is a community effort lead by MITRE to provide a common language to express software weaknesses.

Code Dx leverages the CWE to provide correlation across the diverse set of testing tools it supports. Code Dx also allows you to define your own correlation logic via the Rule Set page. This allows you to correlate based on a group of CWEs or tool specific rule codes.

Code Dx uses the CWE identifier specified by the tool or in cases where the tool does not provide a CWE, the Code Dx team has done that mapping for you.

CWE information is readily available in Code Dx. On the Findings page you can search by CWE or filter by CWE. This includes grouping CWEs by various standards such as OWASP Top 10 or CWE/SANS Top 25. The CWE identifier is also shown in the Findings Table and you can hover on that identifier to get the full CWE name.

CWE information is also provided on the Finding Details page. There you can see the full CWE name for the aggregated finding. For each individual tool result, the CWE used for each tool is also provided. In both cases links to MITRE's CWE website and Code Dx's developed CWEvis site are provided.

Finally, all reports (CSV, XML, PDF, Nessus, and AlienVault/NBE) contain CWE information.

CWE Version

This version of Code Dx uses CWE Version 2.11. As new CWE versions are released, Code Dx will include it in it's next version update. Note: Since the CWE represents root weakness in code rather than exploited vulnerabilities, the taxonomy is not updated as frequently as the CVE.

Filtering

The filters are interactive bar charts that show the distribution of various properties of all findings in the displayed project. Each bar has a check box next to it that lets you filter on that value. Some filters have a tree structure, where certain elements can be expanded to reveal more elements. These elements will have a triangle next to them which you can click to expand or collapse them.

As you check and uncheck boxes, the entire page will update to match the current filter state. When the page first loads, all filters are in an "off" state, and the page displays data for every finding in the project.

When the page is first loaded, certain filters will be expanded by default while others will be in a collapsed state. Clicking the arrow to the left of each filter will toggle the collapse or expand state.

Expanded filters have sorting options as well. Clicking the sort button in the filter header will open a menu containing the possible sort choices.

Filters can be resized vertically by dragging the bar at the bottom of the widget

Filter vertical resize example

Filters can be resized horizontally by dragging the vertical bar between the filters area and the table area. While dragging, a shadow of the vertical bar will follow the mouse, indicating how wide the filters area will be. Once you release the mouse, the filters area will change size accordingly.

Filter horizontal resize example, after

Filter horizontal resize example, after

Filter Breadcrumbs

As you activate filters in the Findings page, the page will update and filter breadcrumbs will appear. The breadcrumbs show an overview of what your current filter state is; they also let you turn off bits of the filter by clicking the X in each orange box.

Rule Filter

The Rule Filter shows which rules are associated with the project. They are dependent upon the Rule Set that was configured for the project. If no rule set was selected, the filter will only display Others.

Tool Filter

The Tool Filter breaks down findings by their associated tool results' types. The tool result type hierarchy typically follows a hierarchy of "Tool" » "Category" » "Name", following the same hierarchy as in the Tool Config page.

Detection Method

The Detection Method Filter categorizes findings based on the method used to detect them. Only the categories that apply to your project will be displayed. The detection methods currently supported are:

Severity Filter

The Severity Filter shows the distribution of findings by how severe they are reported to be. Code Dx maps all reported severities to a scale of Info, Low, Medium, High, and Critical. Some tools don't report a severity, so they are represented as Unspecified.

Codebase Location Filter

The Codebase Location Filter shows where each finding is located, reflecting the directory and file hierarchy of the codebase. Location categories that may apply to your project are files, URLs, and logical locations.

For .NET results, in some cases (especially if PDB files are not uploaded), source locations may not be available. Instead, a Logical Locations item will be shown. Under it will be locations organized by namespace, class, and method.

Age Filter

The Age Filter shows how old each finding is, i.e. how long since the finding was first seen in an analysis. The Age Filter displays a set of pre-defined age ranges, although users of the REST API may customize the ranges for their own use.

Tool Overlaps Filter

The Tool Overlaps Filter breaks down findings based on the degree of correlation of its associated tool results. For example, was a finding detected by 1 tool, 2 tools, or more? Were the 2 tools FindBugs and PMD, or JSHint and PMD? Actual correlation logic is determined by the project's Analysis Configuration.

Standards Filter

The Standards Filter shows the distribution of findings based on several industry standards. Various standards are supported and can be selected using the standard button in the filter header.

Sample of the standards menu on the Standards Filter

Note: the Defense Information Systems Agency Security Technical Implementation Guide (DISA STIG) versions 3.10 and 4.0, Health Insurance Portability and Accountability Act (HIPAA), National Institute of Standards and Technology (NIST) 800-53, OWASP Mobile Top Ten, and Payment Card Industry Data Security Standard (PCI DSS) version 3.1 standards are available in Code Dx Enterprise only.

Status Filter

The Status Filter shows the distribution of each finding's triage status. Initially, all findings in a project are set to New, but findings' statuses can be changed.

JIRA Status

If a project has a JIRA Configuration, the JIRA Status Filter will be shown. You can filter on findings that have no issues and those that do. Additionally, you can expand "Associated Issues" to drill down to the workflow status and the individual issues.

Time Filters

A Time Filter is a special type of filter which groups findings by analysis, i.e. the filter will decide which analysis each finding belongs to, and display the groupings as a barchart. The analysis number or analysis date will make up the X axis, while the finding count makes up the Y axis.

Unlike the other filters, a Time Filter may not be resized vertically. Instead, as more analyses are displayed it will grow horizontally, eventually adding a horizontal scrollbar.

Making a filter selection with a Time Filter is done by drag-selecting a range in the selection area above the barchart:

A time filter, before and after a selection has been made

The X axis of each Time Filter can be toggled between "Ordinal" and "Time".

Ordinal scale uses the analysis number (e.g. 1st, 2nd, ...) to determine where each analysis is placed on the X axis. It allots the same amount of horizontal space for each analysis, making it a reliable way to visually separate one analysis from another. Ordinal scale is the default mode for each Time Filter when the page loads.

Time scale uses the start time of the analysis to determine where each analysis is placed on the X axis. Since the lifespan of a project may be very long, and several analyses may be clustered close together, bars may overlap when using time scale mode. This scale mode is most useful when you want to highlight a particular date range, and separating individual analyses is not desired.

The different time filter scale modes

As you hover over the selection area of a Time Filter, you will see a tooltip indicating the X value that your cursor is hovering over. In time scale mode, the X value is a date and time. In ordinal scale mode, the smaller text indicates the "physical" selection range, while the larger text indicates the rounded range, which will be used as the actual filter selection. For example, in the image below the physical selection is "7.2 to 10.8", which encapsulates a filter selection of analyses "8 to 10". Once you click and drag to make a selection, the tooltip will expand to show you the "min" and "max" of your selection.

An existing selection can be altered by clicking and dragging either of the paddles (the purple and green shapes at either end of the selection) to resize, or the area between the paddles to pan. Double-clicking a paddle will move it all the way to the beginning or end of the chart. Double-clicking the area between the paddles will clear the selection (or you can simply click the "clear filter" button just above it).

Time filter selection tooltips

As you hover over bars in a Time Filter's chart area, a tooltip will appear to display information about the currently-hovered analysis. The information includes the start time, duration, number of associated findings (the height of the bar), the analysis number (e.g. the 10th analysis in that project), and the Name (see below for more details about analysis names).

Time filter analysis tooltips

Note that when an analysis has a name, the circle below its bar in the barchart will be filled in; when it has no name, the circle will only have a dotted outline. Users with the update role can edit analysis names by clicking the pencil icon next to the name. Naming an analysis can be useful if you want to associate it with a particular release version of your software, a Git commit, a Jenkins build, or any number of things.

As an added convenience, analysis names allow you to write Markdown-style links, e.g. [link text](link url):

Time filter analysis name using a link

Note that the contents of the analysis tooltip are rearranged depending on the scale mode; in ordinal mode the analysis number is shown as the title while the analysis date is shown in the body, and in time mode the analysis time is shown as the title while the analysis number is shown in the body.

Time filter analysis tooltip arrangement is different in time scale mode

First Seen

The First Seen filter is a Time Filter which groups findings based on the analysis during which the finding was first seen, i.e. the analysis that introduced the finding. This filter can be useful for answering questions like "how many findings were introduced by release 2.1.0?" Note that the First Seen filter is similar to the Age Filter, except that instead of grouping by age ranges, it groups by analysis.

The "First Seen" filter

Last Modified

The Last Modified filter is a Time Filter which groups findings based on the analysis during which the finding was last modified. (For findings modified by users or other non-analysis interactions, it picks the most recent analysis at the time of the modification.) An example usage of this filter could be in combination with the Status Filter to answer the question "How many findings have been fixed since release 2.1.0?" In this example, you would unhide the "completed" triage statuses by using the View button.

The "Last Modified" filter

The search area in the Filters section allows you to search for findings by CWE ID, Finding ID, Finding Location, or Rule/Tool. Searches made via the search widget will affect the page in the same way that Filters do. The default search option is Finding Location.

Search widget location

To search, select the search type from the dropdown, enter your search criteria in the text box, then press Enter (or click the magnifying glass). Note that if you type but do not trigger the search for several seconds, a popup message will appear, reminding you to do so.

Searching by Location

The default "search by" option is Location and it is case-sensitive. When searching by Location, the criteria can be any part of a file path. For example, to look for Findings in the webapp/javascript folder, enter webapp/javascript. To search Findings in files with the .java extension, enter .java. You can use * to indicate a wildcard, e.g. a search for src/*.java will match locations like src/main/java/Example.java. If you want to have the literal asterisk (*) as part of your search, use \*. If you want to have a literal backslash (\) as part of your search, use \\.

Searching for findings in the webapp/javascript folder

Searching by CWE ID

When searching by CWE, the criteria should be a number, or a comma-separated list of numbers. For example, to search for findings with a CWE of 91, simply enter 91. To search for findings with a CWE of either 91 or 94, enter 91, 94. Note that ranges (e.g. 100 - 200) are currently not supported.

Searching for findings with CWE 133

Searching by Finding ID

When searching by Finding ID, the same formatting rules apply as with the CWE search. To search for Finding 123, enter 123. To search for Findings 123, 456, and 789, enter 123, 456, 789. Note that the search will not look for Findings from other projects.

Searching for finding 11005

Searching by Rule / Tool

When searching by Rule / Tool, the criteria can be any text (case-insensitive) which may appear in the name or grouping of a Rule or Tool descriptor. For example, searching for "inject" by Rule / Tool can match Rules like "SQL Injection", and Tool descriptors like PMD / Security / Possible SQL Injection. This search is case insensitive. Wildcards are not supported.

Searching for "inject"

Searching by Tool-Specific Fields

Results from some enterprise tools will have tool-specific data attached to them. For example, Veracode provides a "Flaw ID". Many of these fields may be used as criteria in the search area, as long as they are present in the project. If you upload data from an enterprise tool, you may notice one or more options in the "search by" dropdown, related to that tool. When searching with these options, you must enter an exact match; e.g. if the Veracode Flaw ID is 123, you must enter "123" (without the quotes) in the search input. Note that if any tool-specific metadata is present on a finding's results, you can see it on that finding's Details.

Searching for tool-specific metadata

Bulk Operations

Bulk operations are actions that affect all findings that match the current filter. When no filter is set, these actions will apply to all findings in the project.

Change Status

The Change Status dropdown menu is available to users with the update role. It allows users to change the triage status of all findings matching the current filter.

Bulk Operations - Change Status

Generate Report

The Generate Report button opens the Generate Report dialog. The dialog is used to select and customize a report. Several report types are supported, including PDF, CSV, XML, Nessus, and AlienVault/NBE.

To generate a report, select one of the report types and configure the associated option(s), then click the Generate Report button. Code Dx will trigger a background task to create your report.

Bulk Operations - Report Generating

When the background task finishes generating your report, a link will be provided to download and view it.

Bulk Operations - Report Complete

PDF Report

You can customize the PDF report in several ways. There are options to include or exclude a simplified or detailed executive summary section; finding details (with or without source code); tool details; and comments that appear in the Activity Stream (on the Finding Details page). The "Result details" section contains these options: "Include result provided details" and "Include HTTP requests and responses". Please note the "Include result provided details" option must be selected if you want to include the HTTP requests and responses in the PDF report.

If you'd like your company logo to appear on the cover sheet, please contact your Code Dx administrator to configure it for you.

Bulk Operations - PDF Report Options

CSV Report

The CSV report provides options allowing you to select which columns will be included in the generated file.

Bulk Operations - CSV Report Options

XML Report

Customizations for the XML report include the option to enumerate standards violations for each finding, provide source code snippets, and whether to include copies of the rule descriptions for each finding.

Note: There is a limit of eight lines of code per source snippet for each finding. When the limit is exceeded, no source code is provided.

Bulk Operations - XML Report Options

Nessus Report

Code Dx Enterprise users will be able to select the Nessus report. This reporter generates a report in the Nessus format, which can be imported by many applications.

The default host and MAC address fields are required, while the operating system and NetBIOS name fields are optional. When exporting a finding that doesn't contain any request data, the default host value will be used.

Bulk Operations - Nessus Report Options

AlienVault/NBE Report

Code Dx Enterprise users will be able to select the AlienVault/NBE report. This reporter generates an NBE report that is compatible with AlienVault.

The report options require that a host address (IPv4) be specified for inclusion in the report.

Bulk Operations - NBE Report Options

Issue Tracker Integration

If a project has an Issue Tracker Configuration, the Issue Tracker dropdown menu will be available, allowing users with the update role to interact with the configured issue tracker. The options are create issue, associate with existing issue, and remove association. Currently, JIRA is the only issue tracker we support.

Creating New Issues

To create a new issue, click the Issue Tracker dropdown menu and select the Create issue option.

A dialog will open.

All of the fields are editable. If you've configured your issue tracker to allow the user to set an Assignee and a Due Date when creating an issue, those fields will be available. Required fields will have a red asterisk by their name.

If you have Code Dx Enterprise, you will use the template expressions that were defined when configuring the issue tracker to pre-populate the relevant fields with data from the active findings. Code Dx provides default templates for the Summary and Description fields.

If you have fewer than twenty findings in the current filter, the Description field will be pre-populated with a brief description for each Finding. JIRA descriptions can be set to allow for the use of WikiMarkup. Code Dx takes advantage of that to make the descriptions more readable from within JIRA. If you have twenty or more findings in the current filter, the Description field will be pre-populated with the filter name.

JIRA puts a maximum length on some of its fields (e.g., the description field), and the twenty-finding limit is intended to prevent a field from overflowing if a large number of findings with long descriptions are used to create a single JIRA issue.

Associating with Existing Issues

To associate a finding with an existing issue, click the Issue Tracker dropdown menu and select the Associate with existing issue option.

Enter the issue key that you want to associate with the finding(s). Clicking outside the textbox or pressing Enter will cause Code Dx to look up the issue in question. If it's able to find it, and if it's part of the same JIRA project you selected when you configured the issue tracker for this Code Dx project, the issue's summary will be displayed, allowing you to confirm that you've entered the issue you want. Click OK to associate the finding (or findings) with that issue.

Refreshing Issue Status

Code Dx will regularly check the JIRA server to refresh the status for all of the issues associated with findings in a given project. The interval at which the check is done is configurable in the Issue tracker configuration. However, you can also manually trigger a refresh of all the issues for a project by clicking the Refresh Issues button on the Findings page.

Removing Issue Associations

You can remove the issue associations for all of the findings in the current filter by using the Issue tracker dropdown menu and selecting the Remove association option. Note this only removes the association, it doesn't touch the issue itself.

Findings Table

The Findings Table shows a concise representation of each individual finding. The number in the ID column is the unique identifier assigned to each finding and the text for the ID doubles as a link to the finding's details.

Users with the update role in a project can use the dropdown menu in the Status column to change the current status of a finding.

Projects often have more findings than can be displayed in the Findings Table all at once. Because of this, the table is split into pages. By default, each page shows 25 findings. Users can change the number of findings per page using the Show button, seen below.

The Findings Table columns can be hidden or displayed using the dropdown menu in the upper right corner of the table. This is done by toggling the column name.

In the menu, visible columns have a check mark to the left of the column name. Hidden columns can be made visible again by selecting them in the menu.

Flow Viz

The Flow Viz is a categorical breakdown of the findings in a project. By default the Flow Viz is collapsed to the left side of the Findings page. Clicking the "Flow Viz" button will pull the view out from the side, bringing it in front of the Filters. Clicking the button again will collapse it.

Each row represents different values in a category. In this example, the severity category has values for Low, Info, Medium, and High.

Each path (colorful, curvy lines) represents a set of findings that have values matching each category value that the path passes through. Hovering the mouse over one of the paths will reveal more information about that path.

The black boxes with white circles at the side of each row are draggable. You can use them to re-order the rows in the Flow Viz, updating the visualization in real time.

Analysis Inputs List

The Analysis Inputs List is a widget on the Findings page that shows the files that were provided to Code Dx for analysis. It can be shown by clicking the Show Inputs button found in the Findings page header.

Analysis Inputs Example

The Analysis Inputs List is broken down first by analysis, then by file. For example, when viewing a project in which two analyses had been performed, there would be a section for each analysis. Analyses are ordered by date, with the most recent analysis shown at the top of the list, and the oldest analysis at the bottom.

Within each section, individual entries represent files. For example, if a "findbugs-results.xml" file had been uploaded to Code Dx during one analysis, a corresponding entry would appear in the section for that analysis. Each entry has three main parts: input name, tool result summary, and archive button.

Input Name

The first part of an entry shows the file's name and the name of the tool it came from. For auto-generated tool outputs (i.e. files generated by Code Dx's bundled tools), the name of the analyzed file will be shown instead of the name of the auto-generated temporary file. Next to the names, a download link allows users to download a copy of the file.

Tool Result Summary

The second part of an entry shows a summary of the tool results originating from that file. Note that due to result correlation and other factors, the total tool result count will not necessarily match the total finding count. Next to the tool result count for each entry, a bar chart shows a breakdown of the tool results by severity. The highest-severity results are shown in red, while the lowest-severity results are shown in gray. You can hover over each bar to see the severity it represents, and see the number of tool results belonging to that severity.

Archive Button

Users with the create role for a project have the ability to archive an analysis input using the Archive button located on the far right of each entry. Tool results from archived inputs will be removed. Any finding whose last tool result was removed in this manner will have its triage status automatically changed to Gone. Normally archival is done automatically (see Auto Archival).

When you click the Archive button for an analysis input, you will be prompted to confirm your choice.

Analysis Input Archive Confirmation

When you confirm, the archival will be performed. The page will update to reflect the updated tool result and finding counts.

Analysis Inputs After Archiving

Adding Manual Results

Code Dx Enterprise users with the create role for a project will have access to the Add Result button located in the page header. This allows you to add manual results to Code Dx (during a manual code review for instance), as opposed to the ones automatically discovered by tools. Clicking on the Add Result button will trigger the following form to appear.

Information entered under the Contextual Information section describes the result itself. Expanding the General Information section of the form will allow values to be specified that will be shared among all manual results of the same name. Contextual information will override general information if specified. Note that this form creates results, which can be thought of as "evidence" for a finding. Multiple results may be correlated to a single finding. As with tool results, two manual results will typically be correlated if they have the same CWE, Location, and Detection Method, even if their names are different.

If the result name entered matches a rule in the current rule set, then the manual result will be associated with the general information for that rule. In this case, the general information can only be changed by revising the rule set. Both the general and contextual information will be included on the details page.

The Tool field allows the user to state that the manually-entered result actually came from a tool. The options available to this field are configured on the admin page, in the Allowed Tools section.

Once you’ve completed the form, clicking the Add Result button at the bottom will dismiss the form and update the Findings page with the new finding. A notification will appear, indicating the ID of the finding to which the result was correlated. To delete or edit a manually added finding, click on the finding's ID in the Findings Table to access its details view. The result will appear in the Evidence section, where there will be buttons to edit and delete it.

View Options

The View menu in the header provides options for how the Findings page will look. The options are "Color-blind friendly mode" and "Hide findings marked as ..." the "completed" triage statuses.

View Menu

Color-blind friendly mode

Users with colorblindness should have little trouble with most of the widgetry on this page, possibly with the exception of the Flow Viz. The Color-blind friendly mode switch in the View menu will change the color scheme of that visualization to a palette with fewer colors and higher-contrast.

Comparison of the Flow Viz with and without "Color-blind friendly mode" turned on

Hide findings marked as...

There are several options in the View menu labelled "Hide findings marked as...". The purpose of "hiding" or "unhiding" findings is to exclude or include the associated findings from the Findings page. The "completed" triage statuses in these options are "Gone", "Fixed", "Mitigated", "False Positive", and "Ignored". When turned ON, each setting will cause the findings marked with the particular triage status to be excluded from the page. This affects the table, filters and counts throughout the Findings page. When turned OFF, the findings associated with that status will be included on the page. The default settings are ON.

Note: Findings marked as "Gone" will generally have no tool results associated with them. This can lead to a somewhat confusing scenario where the "total findings" count will be greater than the "total tool results" count when the "Hide findings marked as Gone" setting is off.

Finding Details

To access the details for a single finding, navigate to the Findings page, locate a finding in the Findings Table, and click the link in the ID column.

Details Summary

The Details Summary in the header gives a quick overview of the finding and the file where it is located. If the finding is associated with a CWE, the CWE is noted, with links to CWEVis and the official CWE Mitre site.

The summary area also has "jump links". One link will scroll the source viewer to the location of the finding in the file. The other link (which appears once you scroll down the page) will bring you back to the top of the page.

Severity Override

Code Dx does its best to pick a reasonable severity for each finding, but if a user (with the update role) disagrees with an individual finding's severity, they have the ability to override it. The severity override popup can be accessed by clicking the severity icon for a finding, either in the Finding Details page's header, or in the Findings page's findings table.

The Severity Override Popup on the Finding Details Page

Once the popup is opened, simply click one of the options to set the override. The popup will close and the new setting will be applied. When a finding has an overridden severity, the white border around its severity icon will be green instead.

A Finding with Overridden Severity

Here's the same finding shown with its severity override popup on the Findings page.

Severity Override Popup on the Findings Page

Activity Stream

The Activity Stream area has widgets that let you change the status of the finding as well as comment on it. As users change the status and comment on a finding, messages appear in the activity stream, with newer messages at the top.

Descriptions

The description information shown by Code Dx can come from a variety of sources, with varying levels of detail. At a high level, descriptions are divided into "general" and "contextual".

The main "Description" section of the details page is a "general" description. Most of the time, the main description comes from a Rule Set. When a finding matches up to a rule, the main description section will use that rule's description. For findings created by observed tool results (i.e. types of findings that Code Dx doesn't already know about - see the Tool Configuration section), if the tool result does not match a rule, the general description may be created from that tool result, as long as the tool result provides one. This will often be the case with enterprise-grade tools such as Fortify and Veracode.

The "Description" section

The finding itself will not have a "contextual" description. This will instead be found on the individual results shown in the Evidence section. The "general" and "contextual" descriptions for results will be shown in the Tool Rule Description and Contextual Description sections of their display area, respectively (see below).

Evidence

The Evidence section of the Finding Details page shows the raw results that make up a finding. (Note: results can originate both from analysis tools and from manual entry). Each result in the Evidence section will be displayed in its own subsection, with the result's "type" as the header. The screenshot below shows two results from two different tools which both describe a SQL Injection vulnerability in the same location.

The Evidence section showing two SQL Injection results

Each result in the evidence section has a handful of fields shown:

Some enterprise-grade tools report additional information that may appear in this section. One example of this is Veracode's Flaw ID. When these additional fields are present in a project, some of them will also become available in the Finding Search on the Findings page.

Source Display

The Source Code area shows the contents of the file where the finding is located. The "on line 100" link (shown in the screenshot below) will scroll the source display so that it shows the exact lines of the finding, which are highlighted in dark grey in the line number gutter. The presence of severity markers in the gutter denote other findings in the same file. When multiple findings are present in a single line, the severity marker will show the highest level severity at that line. If you hover your mouse over any highlighted lines, a popup containing links to the Finding Details pages for the other findings will appear.

Source Search

Searching within the Source Code area is separate from your browser's default search function. (For performance reasons, the Source Code view does not render the entire source file at once, and so the browser might not be able to find lines that are not currently in view.) Click in the Source View first. Note: for keyboard shortcuts, use Ctrl and Cmd interchangeably depending on whether or not you use a Mac. Use Ctrl+F to open the search dialog. Type in your search and press Enter. You can jump to the next result by pressing Enter again, or by pressing Ctrl+G. You can jump to the previous result by pressing Shift+Enter, or by pressing Ctrl+Shift+G. You can also jump to a specific line using Alt+G, typing a line number, and pressing Enter.

Issue Tracker

If a project has an Issue Tracker Configuration, the Create Issue and Associate with Existing Issue buttons will be shown. Users with the update role are allowed to interact with the configured issue tracker.

Creating an Issue

You can click the Create issue button, which will open a dialog.

The dialog functions the same way as the dialog opened from the Bulk Operations area of the Findings Table, except the Description field will be pre-populated with information about this finding.

Associating with Existing Issues

Click the Associate with Existing Issue button to associate this finding with an existing issue. A dialog will open.

The dialog functions the same way as the dialog opened from the Bulk Operations area of the Findings Table.

Refreshing Issue Status

You can select the refresh icon to manually trigger a refresh of the issue.

Removing Issue Associations

Clicking the trash can icon removes the association between the finding and its related issue. Note this only removes the association; it doesn't touch the issue itself.