5.3.2
Install Guide

Requirements

This section details the hardware and software requirements for Code Dx along with special requirements needed for installations that will be conducting .NET codebase scans.

Hardware Requirements

Although we often get asked what the hardware requirements are, there is no one answer since it largely depends on how many Code Dx projects will be active at the same time, how frequently analyses will be conducted, and how many concurrent users are expected to use the system.

Having said that there is a recommended minimum hardware configuration:

Software Requirements

Code Dx is pre-packaged with most of its requirements. There are, however, certain pre-requisites for installations that will be leveraging the .NET scanning support of Code Dx. For .NET analysis, the .NET runtime is required, and it is strongly recommended to install FxCop and CAT.NET. Details on these will be covered in the next section on .NET Analysis.

The bundled Dependency-Check periodically updates its database of vulnerabilities. If Code Dx is installed in an environment without a connection to the internet, this update will not succeed. For more information, please refer to the Internet Access section.

.NET Analysis

In order to run the bundled .NET tools supported by Code Dx, the .NET Framework runtime is required for Windows and the Mono runtime is required for Linux and macOS. Additionally, Dependency-Check requires the .NET Core 3.1 SDK on all platforms. Note that the .NET Core 3.1 SDK is preferred over the .NET Core 3.1 Runtime, as the Runtime may cause Dependency-Check .NET analyses to fail in some environments.

Windows Users

It is recommended that the latest version of .NET be installed.

Code Dx is capable of running multiple .NET analysis tools on your codebase. FxCop and CAT.NET are two of the supported tools and are developed and distributed by Microsoft. The end-user license agreements for these products forbid their redistribution, therefore, we are unable to legally bundle these tools. So in order for Code Dx to run these tools on your behalf, you must install them separately. Code Dx will then automatically discover their location and run them.

Code Dx supports FxCop versions 10+ and will automatically discover the location of the latest version of FxCop installed on your machine. If you would like to provide a specific location, set the fxcop.path property in the Code Dx configuration file (codedx.props). FxCop is a legacy analyzer which is no longer available through Microsoft. Starting with Visual Studio 2019 and .NET 5.0, FxCop is replaced with Microsoft Code Analysis (Roslyn) Analyzers.

Code Dx will work with either CAT.NET 32-bit or CAT.NET 64-bit. CAT.NET 32-bit has an installer and Code Dx will automatically look in the default installation directory for this application. The 64-bit version is in a zip file. The best approach to using the 64-bit version is to overwrite the 32-bit files with the 64-bit files. Alternatively, the path can be manually set using the cat.net.path property in the Code Dx configuration file.

Installation

Note that while multiple Code Dx installations are supported, it is discouraged to run them on the same machine. This will likely lead to resource contention, resulting in performance degradation in those installations.

This section describes the Code Dx installer. For Docker installation instructions, follow the codedx-docker documentation. If you would like to install Code Dx on Kubernetes, refer to the codedx-kubernetes documentation.

The Code Dx installer is self-contained as it includes all of the software necessary to run Code Dx and is dependent upon its own Tomcat, Apache and MariaDB services. The services automatically start whenever Code Dx is restarted.

Some of the Code Dx dependencies listen for network activity (e.g., the web server to accept incoming requests). If a port conflict is detected, you will be prompted with a suggested alternate port. It is your choice to accept that port or change it.

There is an installer for Windows and Linux. For Linux deployments, please see the Linux Considerations section.

When first starting the installer downloaded for your platform, you should see the following screen.

Linux Considerations

For headless Linux environments the installer comes with an option to interact from the command line. To do so, run the installer with the --mode text option.

For example:

./codedx-<version>-linux-x64-installer.run --mode text

where you substitute the installer version number for "version".

The installer behaves differently dependent on whether it is executed by the root user (or with sudo privileges) or alternatively with a standard user. The default suggested directories will change and the port numbers used for the installation will also be different (port 80 for HTTP access for instance when using the root user vs port 8080 for non-root users). For production installations we strongly recommend triggering the installer with root/sudo privileges.

Installation Directory

The Code Dx installer places all its dependencies and program executables in the installation directory. The installer will suggest a location on your file system that sticks with common conventions for your adopted platform; however, you can choose to install Code Dx to a different location if needed.

Admin Account

Similar to other web-based applications, Code Dx has a built-in admin user to manage the system. The installer prompts you for the credentials you want to use for that account. Be sure to keep note of these credentials in a secure location as they are not retrievable once the admin user has been created. When new Code Dx releases are available, you will download and run the latest installer. Your installer admin credentials are required to complete the installation.

Note: the first time you use Code Dx, you must log in using the installer admin credentials. After that, you can change the admin's password within Code Dx; however, changing the password in Code Dx does not change the admin's password for the installer.

Data Directory

Code Dx stores data in the data directory you configure during the installation. Once again, the default suggested location is the typical place on your adopted platform to place program data files. This can be changed if needed from the relevant installer screen. For production installations of Code Dx we strongly recommend that this data directory be part of your backup plan as it contains all data managed by Code Dx.

SSL Configuration

What you do with the SSL configuration largely depends on your deployment scenario. By default the installer will setup Code Dx's dependencies to offer both HTTP and HTTPS access to Code Dx. This is sufficient for most evaluation scenarios. If, however, you are deploying Code Dx for production usage then we strongly recommend that you use/obtain a valid SSL certificate for the host machine. If you don't use your own certificates, HTTPS is enabled by default with a self-signed certificate generated during the installation. This will ensure secure communications to all clients accessing Code Dx. One thing to keep in mind is that if you use the default HTTPS option with the self-signed certificate most browsers will display a security warning when connecting that will need to be accepted in order to proceed with access to the site.

If Code Dx will be used in a networked environment then we strongly recommend using HTTPS to connect. So for instance once Code Dx is installed use https://<hostname>/codedx instead of http://<hostname>/codedx (substituting in your machine's hostname).

Click the "Next" button if you're using Code Dx's self-signed certificate. Otherwise, use your own SSL certificate by getting the certificate and associated private key in PEM-encoded X.509 format. Some issuers refer to this as “Apache format.” Click "Do you want to import your own SSL certificate?" and browse to the those files.

Trusting Certificates

If you're connecting with an application (such as Jira, Git, or certain enterprise tools) that is using a self-signed HTTPS certificate, you will need to add it to the Code Dx Java trust store. This section describes how to do so.

Getting Code Dx to Trust Your Third-Party or Self-signed Certificate

Windows

  1. Open a command prompt in administrator mode
  2. Change directory to Code Dx's Java trust store: cd <installation-directory>\Code Dx\java\bin where the <installation-directory> default is C:\Program Files\Code Dx
  3. Run keytool -printcert -rfc -sslserver <server hostname:port> | keytool -importcert -keystore "../lib/security/cacerts" -storepass changeit -alias <name for your server> -noprompt. Replace <server hostname:port> and <name for your server> with the appropriate information for your environment.
  4. Restart the Code Dx services for the change to take affect

Linux

  1. Open a Terminal
  2. Change directory to Code Dx's Java trust store: cd <installation-directory>/java/bin where the <installation-directory> defaults are /opt/codedx/ for Linux root and /home/<user>/codedx/ for Linux non-root
  3. Import the key to Code Dx's Java installation's keystore:
    • [root] use ./keytool -printcert -rfc -sslserver <server hostname:port> | sudo ./keytool -importcert -keystore "../lib/security/cacerts" -storepass changeit -alias <name for your server> -noprompt. Replace <server hostname:port> and <name for your server> with the appropriate information for your environment.
    • [non-root] use ./keytool -printcert -rfc -sslserver <server hostname:port> | ./keytool -importcert -keystore "../lib/security/cacerts" -storepass changeit -alias <name for your server> -noprompt. Replace <server hostname:port> and <name for your server> with the appropriate information for your environment.
  4. Restart the Code Dx services for the change to take affect

Deleting a Certificate from the Trust Store

  1. Open a Windows command prompt in administrator mode or a terminal in Linux
  2. Change directory to Code Dx's Java trust store: cd <installation-directory>/java/bin where the <installation-directory> defaults are C:\Program Files\Code Dx on Windows; /opt/codedx for Linux root; and /home/<user>/codedx/ for Linux non-root. Replace <name for your server> with the appropriate information for your environment.
    • [Windows] use keytool -delete <name for your server> -keystore ../lib/security/cacerts.
    • [Linux root installation] use sudo ./keytool -delete <name for your server> -keystore ../lib/security/cacerts.
    • [Linux non-root installation] use ./keytool -delete <name for your server> -keystore ../lib/security/cacerts.
  3. Restart the Code Dx services for the change to take affect

Time Expectations

Once all the configuration is complete, Code Dx will take a handful of minutes to install on your system. Keep in mind that this varies dependent on the hardware performance for the deployment machine.

Firewall

Code Dx is a web application that requires a web server to house it. The Apache web server is provided and configured automatically with the installer. However, for most systems this means that a firewall exception is necessary to allow incoming connections over the network so that other users (yourself included potentially) can access the installation from other machines. By default the firewall ports that need to be opened up are 80 and 443, for HTTP and HTTPS respectively.

On Windows you will be prompted with the following alert in order to grant the firewall exception.

Note: the first time you use Code Dx, you must log in using the installer admin credentials. After that, you can change the admin's password within Code Dx; however, changing the password in Code Dx does not change the admin's password for the installer.

License File

If you do not have a license, your license expired or it is invalid, please request a license from our Sales Team.

When you purchase Code Dx, you will receive (usually via email) a new license (a blob of letters and numbers), which you will need to install.

Installing a New License

To install a new license, you must access the License Management page. If your license expired or is invalid, the License Management page will automatically open. Otherwise, you can open the License Management page by clicking the license summary link at the top of the Admin page.

The image below shows the state of the page when you first arrive.

License Management Page on first arrival

The header area provides the current license status. In this case the license is valid, but if the license expired or is invalid, the header will show a message indicating what is wrong.

The form shown in the image above allows you to upload the license you received. Simply open your license key file using any ASCII text editor (such as Notepad), copy the license text, and paste it in the Use a new license form, as seen below.

License Management Page with the new license form filled

Click the Use this license button. If the license is valid, you will be sent to the Code Dx home page; otherwise, the License Management page will just reload.

Please don't hesitate to contact us ([email protected]) if you require additional assistance.

Requesting a License

As a convenience, the License Management page also provides a form for requesting a new license. Click the I don't have a license link to display the Request a new license form.

The License Request Form

Fill in the form, then click the Request a license button. The Code Dx application will notify our Sales Team on your behalf (requires the Code Dx application to have access to the Internet).

License Request Form after submitting

If the computer does not have Internet access, please use a different system and contact the Sales Team via email ([email protected]).

Uninstallation/Reinstallation

Code Dx is distributed with an uninstaller. At any time you can fire it up and it will go through the process of removing the files and system services that were setup for Code Dx. You will be prompted with the choice of removing the data files used by Code Dx. Please be aware that removing the data files is an irreversible action that will result in data deletion.

To reinstall Code Dx we recommend uninstalling first and then starting the installer again.

Upgrading

During the upgrade process, the installer may present you with a list of issues. These issues must be resolved before being able to continue.

Clean File System

The upgrade process expects only certain files and folders to exist in the installation location. If you are presented with a list of files, you can continue the upgrade process by following the steps below:

Remove Services

On Windows, the upgrade process requires specific Code Dx services. Other Code Dx services should be removed. If you are presented with a list of services, you could remove them by following the steps below:

Free Ports

The upgrade process requires certain ports to be available. If you are presented with a list of ports, you can free them by following the steps below:

Windows

Linux and OS X

Restoring to a Previous Version

In your backup folder, there’s a file called restore-backup, which is used to restore to a previous version.

Windows

  1. Navigate to the backup folder, which is in the installation folder that you provided during installation. The default folder is C:\Program Files\Code Dx\backup-<timestamp>\backup where <timestamp> is the date and time the upgrade was performed
  2. To restore to your current installation and data folders: right-click on restore-backup.bat and choose Run as administrator
  3. To restore to different installation and/or backup folders, right-click on restore-backup.bat, choose Run as administrator, and run restore-backup <\path\to\new\installation\folder> <\path\to\new\data\folder> substituting the paths and folder names to the new directories

Linux Root Installation

  1. Navigate to the backup folder that was created during the upgrade process. The default folder is /opt/codedx/backup-<timestamp>/backup where <timestamp> is the date and time the upgrade was performed
  2. Open a terminal and run sudo chmod +x restore-backup.sh
  3. To restore to your current installation and data folders, run sudo ./restore-backup.sh
  4. To restore to different installation and/or backup folders, run sudo ./restore-backup </path/to/new/installation/folder> </path/to/new/data/folder> substituting the paths and folder names to the new directories

Linux Non-Root Installation

  1. Navigate to the backup folder that was created during the upgrade process. The default folder is /home/<user>/codedx/backup-<timestamp>/backup where <timestamp> is the date and time the upgrade was performed
  2. Open a terminal and run chmod +x restore-backup.sh
  3. To restore to your current installation and data folders, run ./restore-backup.sh
  4. To restore to different installation and/or backup folders, run ./restore-backup </path/to/new/installation/folder> </path/to/new/data/folder> substituting the paths and folder names to the new directories

Manage Code Dx Services

The Code Dx installer includes a graphical tool to manage services, which can be found in the Code Dx installation folder. The tool is called manager-windows for Windows, and manager-linux-x64.run for Linux. Open the tool and go to the Manage Servers tab to view and change the status of the services. To start, stop, or restart individual services, highlight the service, then click the desired action to the right. Use the buttons on the bottom to change the status of all the services.

Alternatively, you can use the Windows Service Manager, or the ctlscript shell files for Linux to change the status of Code Dx services. To start, stop, or restart any Code Dx services using ctlscript, navigate to the Code Dx installation folder and follow the examples below:

Code Dx Configuration

For the most part, the installer takes care of the configuration to match the system and user selection made during the installation process. However, certain advanced options are configurable from the Code Dx configuration files. This section describes the configuration options for Code Dx, although please keep in mind that most installations will not need to change the default setup.

Understanding the AppData Directory

Code Dx needs a place to store a variety of files: the analysis inputs it receives including the source code that it uses to display in the Finding Details page; log files; and configuration files. We group all of these under what we call the Code Dx appdata directory. This directory contains important information from the ongoing Code Dx usage activity, and therefore it is recommended that it be in a stable location that is periodically backed up. Normally, you won’t need to touch this folder other than making the occasional configuration tweak as needed.

The location of the appdata directory is set during the initial installation of Code Dx. By default the appdata directory will be in C:\ProgramData\Code Dx\codedx_appdata\ on Windows, /var/opt/codedx/ on Linux (installed as root), /home/<user>/codedx/apps/codedx/codedx_data/codedx_appdata/ on Linux (installed as non-root), and /opt/codedx/ on Docker-based installations.

Configuration Files

Log Configuration File

Code Dx uses Logback for logging. A sample logback.xml file is provided in the appdata directory. For more information about the logging configuration, consult the Logback manual.

You must restart the Tomcat server after you've completed your revisions. This can be done by launching the Code Dx Manager Tool, clicking the Manage Servers tab, selecting Tomcat server, and clicking Restart.

Code Dx Properties File

The most important configuration file is codedx.props ("the 'props' file"), which is located in the appdata directory. The 'props' file configuration determines a variety of settings including the database connection information, the analysis behavior, and Active Directory integration, among other things.

The 'props' file is formatted as a .properties file, using key-value pairs to set configuration fields.

When changing this file, delete the # at the beginning of the line as # denotes a comment.

You must restart the Tomcat server after you've completed your revisions. This can be done by launching the Code Dx Manager Tool, clicking the Manage Servers tab, selecting Tomcat server, and clicking Restart.

Database Connection Config

Code Dx requires a MariaDB database for storage. The MariaDB database is automatically installed and configured during the installation process. The following properties are used to configure Code Dx database connections and are set automatically during the installation. Please do not modify these settings unless there is a strong need to setup an alternate database for use with Code Dx. However, doing so might prevent future upgrades using the installer from happening smoothly.

For instance, to configure Code Dx to communicate with a MariaDB database running on the same machine as the Code Dx server, with a username of "database_username" and password of "database_password" use the following configuration:

swa.db.url = jdbc:mysql://localhost/codedx
swa.db.user = database_username
swa.db.password = database_password

Internet Access

Code Dx uses internet access in the background for some activities, such as keeping tool data up-to-date and periodically checking for a new Code Dx release.

It is preferable that Code Dx be able to access the internet for full functionality. However, we recognize that this may not be possible in all installations. In those cases, Code Dx is still able to operate, albeit with limitations.

To disable background internet access by Code Dx, add codedx.offline-mode = true in your properties file (codedx.props). The default is false. Note that this will not disable any internet access that may occur as a result of user action or configuration settings, such as Tool Connector, Git, or Issue Tracker configurations.

Putting Code Dx in offline mode will cause the following functionality to be lost:

Dependency-Check External Access

The base paths below are external resources that Dependency-Check may attempt to access during analyses and/or updates. If Code Dx is not running in offline mode, ensure that all of them are accessible to allow normal operation.

Note that the first resource (https://jeremylong.github.io/DependencyCheck/current.txt) is not necessary for proper operation, but Dependency-Check will occasionally attempt to access it to check the latest release version number.

External URL

In most cases, Code Dx can infer its own external URL based on the requests sent to it from users. For example, you might access Code Dx from https://localhost/codedx or https://codedx.mycompany.com. This information is necessary for some subprocesses of Code Dx that need to communicate back to Code Dx over HTTP, or to provide accurate links back to Code Dx when generating content e.g. for Issue Trackers.

In some cases, the accurate "external URL" may not be available through inspection of user requests, and so the value must be provided from your codedx.props file via the codedx.external-url property.

codedx.external-url = https://codedx.mycompany.com

Additionally, there are some cases where you may want internal services (running on the same machine as Code Dx) to access Code Dx from a different URL compared to the external URL. By default, the external URL will be used in this scenario, unless overridden by setting codedx.internal-url:

codedx.internal-url = https://localhost:8443/codedx/

Active Directory/LDAP Configuration

Code Dx allows you to create and deactivate new users that are only known to the Code Dx system. You may, however, want to let users use the same credentials as they do for your organization. To facilitate this, you may provide an LDAP or Active Directory configuration in the properties file (codedx.props). The available settings include:

Note: LDAP property names were changed in Code Dx version 3.5.4. The previous names may still be used.

You may be able to get by with only setting the auth.ldap.url property, depending on the complexity of your LDAP setup. It may be necessary to use a fully-qualified username (e.g., [email protected] rather than just john.doe) when adding the user to Code Dx.

The systemUsername, systemPassword, and authenticationMechanism properties don't need to be set for a secure LDAP configuration. These are not used during user authentication, but for querying user information that will be used during their authentication. Read the section below for more details.

User Search Template

The user DN is the fully qualified LDAP identifier for the user when logging in. In some LDAP systems, the user DN may require an attribute that the actual user isn't aware of, such as an integer ID. Rather than asking the user for this hidden attribute, the user provides a different unique identifier (such as their account name) and Code Dx will insert that into the given query to find a matching user with that attribute. The text they enter as their username is used to replace the {0} part of the template.

In the example above (sAMAccountName={0},ou=users,dc=codedx,dc=com), when the user attempts to log in, a query will be run on sAMAccountName=test,ou=users,dc=codedx,dc=com to retrieve the user DN, which may give something like uid=12345,ou=users,dc=codedx,dc=com. This user DN is then used to bind an LDAP connection using the discovered DN and the user's given password.

Note: In order to make this query, Code Dx needs to be able to authenticate against the LDAP server without the user's credentials. If the LDAP server supports anonymous queries, this isn't an issue. If the LDAP server requires authentication, assign auth.ldap.authenticationMechanism = simple and assign auth.ldap.systemUsername/auth.ldap.systemPassword to the credentials to use when making these queries. The systemUsername should be the full, bindable DN for the user.

If no template is provided, the username entered by the user will be directly used. This may not map to what your LDAP server is expecting. When specifying a user search template, the {0} placeholder must be present. If it is missing, an error will be logged at Code Dx startup, and LDAP authentication will be disabled until the template is corrected. After correcting the LDAP authentication, restart the Code Dx Tomcat server.

Using as a DN Template

If performing a user search before binding is untennable in your environment, you can set Code Dx to treat the search templates as direct DN templates instead by assigning auth.ldap.useAsDnTemplate = true. This means that each authentication performs only one bind, using the resolved DN and the provided user password.

This may be slightly more performant, but is mostly useful when anonymous binds are unsupported and there is no system user account available to perform a search.

Note: Enabling this option will disable LDAP connection pooling, so a new connection will be made and bound for each authentication attempt..

Note: This option cannot be enabled when using multiple templates.

Multiple Templates

Multiple search templates can be used by adding multiple, differently-named properties, starting with auth.ldap.userSearchTemplate. For example:

auth.ldap.userSearchTemplate-A = sAMAccountName={0},ou=users,dc=codedx,dc=com
auth.ldap.userSearchTemplate.B = cn={0},ou=customers,dc=codedx,dc=com

With the above properties, both of those search templates will be used to resolve a user DN when signing in. The property names can be anything, as long as they start with auth.ldap.userSearchTemplate and are named differently. If auth.ldap.userSearchTemplate-A was used twice in the above example, the second assignment would overwrite the first.

Make sure that any LDAP user added to Code Dx can be resolved by only one of the registered search templates.

Sign-in with Multiple Names

When multiple search templates are provided, it's possible for the same LDAP user to sign in using different names. Code Dx resolves each LDAP user to their DN and stores that as their identity, allowing the user to sign into the same Code Dx account regardless of the name they use.

This DN resolution occurs when a user signs in, and not when a user is manually registered through the User Admin page. For their first sign-in, they must use the name that had been registered. This causes their DN to be properly resolved and stored, allowing sign-in under different names.

User Merging

In rare cases it's possible for two LDAP user entries to exist in Code Dx which refer to the same LDAP user. If two separate accounts resolve to the same DN during authentication, Code Dx will automatically merge the users. This merge creates a new user with the same name that's being authenticated, reassigns all content from matching users to the new user, deletes those previous users, and authenticates with that new user. This invalidates any active sessions using either of the two previous LDAP users.

Note: Any user merging will be accompanied by an entry in the Code Dx server logs, as well as the Visual Log with appropriate details.

Display Names

The LDAP attribute used for display names can be set with auth.ldap.user.displayNameAttribute, which is a comma-separated list of attribute names. Each attribute is checked in order, and the first received value is used. If unassigned, Code Dx will attempt to use their CN, UPN, and SAN, in that order.

Display names are automatically updated when a user signs in. Changes to the displayNameAttribute property won't affect users until they sign in again.

Single-value LDAP attributes will be used as-is, if available. Multi-value attributes will have their first entry selected by default. You can choose a specific index in the list if desired, by using the syntax myAttribute{n}, where n is the 0-based index in the attribute list. For example, you can select the second value in a list while falling back to another attribute with:

auth.ldap.user.displayNameAttribute = myAttribute{1}, someOtherAttribute

You could also prioritize a second value while falling back to the first with:

auth.ldap.user.displayNameAttribute = myAttribute{1}, myAttribute{0}

Note: myAttribute{0} and myAttribute are equivalent - they both select the first value available from the attribute.

LDAP Group Mapping

LDAP groups for your users can be mapped to Code Dx groups in Code Dx. This requires connection to an LDAP server that provides a user attribute listing its groups, such as Active Directory and its memberOf attribute.

See the section User Group - Configure LDAP for information on how to work with User Groups in Code Dx and how to map them to LDAP groups.

This group mapping requires a valid groupAttribute and nameAttribute to be assigned in your codedx.props file. The defaults are suitable for use with an Active Directory server and can be left unassigned if using Active Directory.

The auth.ldap.user.groupAttribute is the name of the attribute on your user objects that lists the groups that the user is a member of. This is typically a multi-value attribute containing the full DN paths for a user's groups.

The auth.ldap.group.nameAttribute is the name of the attribute on your group objects that determine how you refer to those groups in Code Dx. When defining the what a Code Dx group will map to, you will use the values provided by that attribute. This is used to pull a readable name from the groupAttribute of any authenticated users.

Legacy Mode

Code Dx version 3.5.4 introduced a new LDAP implementation, bringing more flexibility in integration. Care has been taken to ensure backwards-compatibility in this change. You can revert to the previous implementation if necessary by assigning auth.ldap.legacyMode = true in your properties file (codedx.props) [default: false].

SAML Configuration

Note that this section only applies to users with an Enterprise edition of Code Dx.

Code Dx can also be configured to authenticate against a SAML 2.0 IdP (Identity Provider). This can be done by using the settings below.

Note - SAML property names were changed in Code Dx 3.5.4, but the old names can still be used.

Basic Configuration

Upon successful configuration and after navigating to the Code Dx Login page, your codedx.log file should contain the message "Successfully configured SAML authentication". Otherwise, it will contain "SAML authentication was either incomplete or missing, skipping." A minimal configuration looks like:

    auth.saml2.identityProviderMetadataPath = C:/idp-metadata.xml
    auth.saml2.keystorePassword = jkspassword
    auth.saml2.privateKeyPassword = pkpassword

The IdP XML should have a root element of <*:EntitiesDescriptor>. with <*:EntityDescriptor> elements inside. The recommended location for this file is in the Code Dx appdata folder, but this is not in a requirement. Ensure that Code Dx has the necessary permissions to read the XML file.

The keystore is used by Code Dx to sign requests to your IdP. This keystore will be created automatically unless keystorePath is assigned and a file exists at the assigned path. The passwords for the keystore and its private key must be set manually through the keystorePassword and privateKeyPassword properties. The assigned passwords will be used to create the keystore if necessary. The default path for the keystore is in Code Dx appdata directory, at .../codedx_appdata/keystore/codedx-saml.jks. If a custom keystore is provided, this folder is the recommended location. Ensure that Code Dx has the necessary permissions to read the keystore file.

Code Dx has no inherent requirements for the IdP it authenticates against. Requests from Code Dx can be configured as necessary using the properties listed above to meet the needs of your IdP.

Navigating to Code Dx will redirect you to your IdP Login Portal, which you may sign into but will not provide access to Code Dx. You must first add your SAML account as a user recognized by Code Dx. See the the User Guide for more information. By default, Code Dx will redirect you to your IdP, but you can sign in using the Code Dx Login page by navigating to /login?local. Here you can enter the default Code Dx admin and password to sign in and add yourself and others as SAML-authenticated users.

If you get a generic Code Dx error page after signing in with SAML, you may need to explicitly assign the Code Dx base path. This should match what you have registered with your IdP. See the section on Multiple Hosts below for more information.

SP Metadata

The full XML Metadata for Code Dx as an SP can be downloaded from the Admin page if SAML has been configured. Notable details are provided below.

The Code Dx Assertion Consumer Service (ACS) endpoint is at /login/callback/saml, relative to your Code Dx URL. For example, if hosting at https://localhost/codedx, the ACS is https://localhost/codedx/login/callback/saml.

The metadata XML will list the ACS binding type as HTTP-POST regardless of the binding type set in codedx.props. This can be ignored - Code Dx will use the binding type specified in codedx.props. You can change the binding type in that XML if necessary. This behavior will be corrected in a future release.

Callback URL, Proxies, and Multiple Hosts

Code Dx can be accessed through a variety of hosts (ie machine name, FQDN, IP address, reverse proxy) but only one will be recognized by Code Dx as its ACS. The Code Dx ACS is built dynamically when the first request is made, and is based on the first URL requested from Code Dx. If you access Code Dx through https://192.168.1.10/codedx, the ACS URL will be at https://192.168.1.10/codedx/login/callback/saml and Code Dx will only respond to SAML requests to that endpoint. SP metadata will also be based on this URL.

In this case, SAML authentication will fail unless your IdP has the Code Dx ACS at the https://192.168.1.10/... endpoint. The downloaded SP metadata will have your SAML IdP redirect using Code Dx's IP, when you may want it to point to a reverse proxy instead.

You can assign the auth.hostBasePath property in your codedx.props file to force a consistent ACS URL. This affects the endpoint that Code Dx will listen to, and the SP metadata that it generates. If Code Dx is accessible at https://myhost/codedx, you can add:

    auth.hostBasePath = https://myhost/codedx

.. to force a consistent ACS URL to https://myhost/codedx. (Note that this only affects authentication, and will not change the base path of Code Dx itself.)

Automatic SAML Authentication

Once SAML is configured within Code Dx, all login requests will be redirected to your IdP authentication portal. Authenticated users will be redirected back to Code Dx, where they can view the Projects page if they are registered with Code Dx. Otherwise, they will be redirected to the Code Dx Login page where they can log in as a local user or retry authentication with your IdP. Code Dx does not perform any single sign-out; signing in with a different SAML user will require signing out through your IdP portal and re-authenticating with the new user information.

You can disable the automatic redirect to your IdP by setting auth.autoExternalRedirect = false in your codedx.props.

Multiple Code Dx Deployments With the Same IdP

Authenticating multiple Code Dx instances against the same IdP requires setting a unique Service Provider Entity ID for each deployment. Assign the auth.saml.entityId property to different values for each deployment, and register each new Entity ID with your IdP using the appropriate ACS for the associated deployment.

For example: Two Code Dx deployments are hosted at https://foo.com/codedx and https://bar.com/codedx. Modify auth.saml.entityId for both; in this case they are assigned to https://codedx-foo.com and https://codedx-bar.com, respectively. Code Dx places no restrictions on Entity IDs - assign them as appropriate for your case.

Restart both Code Dx deployments, and register them with your IdP as such:

Both deployments will authenticate against your SAML provider. Note that users registered with one Code Dx deployment will not be registered with another, even if they authenticate against the same IdP. Accessing both deployments with SAML user "John Doe" will require registering them with each Code Dx deployment individually.

Note that while multiple Code Dx installations are supported, it is discouraged to run them on the same machine. This will likely lead to resource contention, resulting in performance degradation in those installations.

Forcing Local Sign-in

Code Dx does not validate that the configured IdP is available before attempting to authenticate. If your SAML IdP becomes unavailable or you need to sign in through a local account, there are two options:

  1. Set auth.autoExternalRedirect = false in your codedx.props. Unauthenticated users will be redirected to the Code Dx Login page instead of your IdP portal, where they can sign in with a local account or attempt to sign in through your IdP portal through a link below the sign in form.
  2. Manually navigate to /login?local, relative to your Code Dx hosting path. This will force the Code Dx Login page to display regardless of the value of auth.autoExternalRedirect.

Note that you may not be able to sign in as a SAML user while your IdP is offline, even if you had been previously authenticated.

Header-Based Authentication

Code Dx allows you to authenticate users via a request header. Requests to the Code Dx server which provide the configured header with a username as its value will be treated as "logged in" as that user. You can optionally restrict the IP addresses from which such requests can originate. For example, if you put Code Dx behind a proxy server which manages its own authentication and adds the header only to authenticated requests, you would specify the proxy server's IP address as the only "allowed" IP address.

The name of the request header, and the set of allowed IP addresses are configured by the following keys in the codedx.props file:

codedx.header-authentication.header = My-Magic-Authentication-Header
codedx.header-authentication.allowed-ips = 172.1.1.1, 127.0.0.1, 0:0:0:0:0:0:0:1

There is no default value for header key. If omitted, header-based authentication will be disabled. If the allowed-ips key is not specified, all IP addresses will be considered "allowed". This will also cause a warning in your log, as it is not recommended to configure a header without an allowed-ips whitelist.

Once configured, header-based authentication and username/password logins will be mutually-exclusive; you cannot log in via header while already logged in via username/password, and vice versa. There is no "log out" functionality for a header-based session. Instead, you just need to stop sending the header with your requests.

Header-based authentication may be used to log in as any enabled user that has been added to Code Dx. This includes the super-admin user, all local users, and all LDAP users. Because of this, it is highly recommended to provide an allowed-ips whitelist, and hide the Code Dx server behind a proxy which can manage the header.

External User Auto-Registration

Code Dx supports auto-registration of users that sign in through external methods such as LDAP. This can include automatic creation, enabling, and disabling of users based on their properties. This is particularly useful when managing an installation using third-party authentication, where there may be many users in your organization that need to be maintained.

Note: Code Dx currently only supports auto-registration for LDAP authentication.

Auto-registration can be configured in your codedx.props file with the following settings:

Note: User auto-registration respects the user limit of your license; if a new user attempts to sign in without any seats available, they will receive an error message regarding license limitations.

Auto-Registration with LDAP

When using auto-registration with LDAP, we recommend using both the group-names and auto-toggle-enabled options. Without group-names, any LDAP user can sign in to Code Dx. Without auto-toggle-enabled, a user leaving one of those required groups would still be allowed to sign in to Code Dx.

Note: LDAP group membership checks are only available for LDAP providers that maintain an attribute on users listing their memberships, eg Active Directory and its memberOf attribute.

Auto-registration with LDAP requires a valid LDAP configuration in your codedx.props file, and Code Dx must have permission to read the necessary LDAP objects and attributes to check for group membership. This depends on your LDAP server configuration, but typically requires that you've assigned a systemUser, systemPassword, and set authenticationMechanism = simple in your codedx.props file.

Note: Automatic enable/disable of user occurs upon logging in. Changing the user's LDAP group membership will not sign the user out or disable them. If necessary, you can disable or delete the user manually. Configuring session durations in Code Dx may also be useful.

Note: LDAP group names in the group-names property does not need to match any LDAP group mappings in your Code Dx user groups, though there may happen to be overlap.

Session Expiration

By default, the session of a logged-in user will never expire until they click Logout. You can set user sessions to expire after a period of inactivity using the settings below:

Both of these properties use a readable duration format, ie 1 hour, 1 hour and 30 minutes, 3 days, etc.

Enabling session expiration requires assignment of session.lifetime, but session.timeout-notice is optional. If left unassigned, the timeout notice will be the shortest of either two minutes or 25% of the session expiration period.

If session expiration is enabled, the user's session will be closed if it either times out or if the user closes their browser.

If session expiration is enabled and remember-me functionality is set to full, remember-me will be effectively disabled.

If combining session expiration with SAML authentication, make sure to set shiro.saml2.realm.forceAuth = true so that the user always has to re-authenticate with your IdP.

EULA Acceptance

Normally after the initial installation of Code Dx, the end-user license agreement (EULA) will be presented to the first admin user to log in. You can configure Code Dx to skip this step by accepting the EULA via the props file:

codedx.eula-accepted = true

Git Related Configuration

Code Dx allows you to configure each project to automatically use source from a git repository as input for each analysis. When configuring a connection to a git repository, Code Dx will, by default, disallow the usage of “local” URLs (i.e., URLs that point to a file in Code Dx’s own file system). This is enforced as a security measure to prevent system information exposure via the validation user interface. Although it is strongly recommended that this setting be left disabled, in the exceptional cases where it is necessary to use local git repositories, set the git.config.allow-local-urls property to true.

Job Configuration

Code Dx performs most long-running tasks, including background cleanup tasks, on a job system. Controls are in place to limit the number of such tasks running concurrently to ensure the system isn't overloaded. The resource limits listed below may be adjusted. Higher numbers translate to more available resources of that type. The minimum value allowed is 1000, and the default is 2000. Values for this setting are unitless; they are relative measures of the power of your Code Dx server. Certain jobs are more CPU-intensive, and others are more database-intensive. Each running job uses a certain amount of the "limit", and this is the mechanism for limiting job concurrency.

These values should be adjusted in relation to the default value. That is, if you believe your server is twice as powerful as an average server, set these settings to 4000 (double the default) to increase the number of concurrent jobs that may be run.

In addition, certain jobs (e.g., generating reports for a project) may produce outputs. The swa.jobs.expiration (default: 60) setting specifies the time the job results are available for (in minutes).

Analysis Behavior

Various settings allow you to affect Code Dx's behavior regarding the analyses it conducts. Changing any of the analysis behavior properties can be done at any time after the initial installation; however, you will still need to restart the Tomcat server in order to reload the properties.

Bundled Tools

Code Dx bundles various tools that run independently during the analysis process. Each of these tools requires a memory budget during its own analysis. The memory requirements vary based on the sizes of the codebases the analyzers are checking. The memory budget for each of these tools is configurable in the properties file; each of the following settings specify the number of megabytes allotted to their respective tools. In general, the static analyzers will require more memory in order to analyze larger projects.

Additionally, these bundled tools may be disabled entirely if desired by setting bundled-tools.disable to true (default: false). When this flag is set, no bundled tools will be available on the new analysis page nor will they be run.

Trace Session Archival

If you use Code Dx's tracing capabilities to perform hybrid analysis, huge volumes of trace data will be collected and will accumulate over time. To alleviate the strain on your server's hard drive and database, trace sessions will automatically be archived. Trace session archival has the following effects:

Code Dx's default behavior is to automatically archive trace sessions at the end of an analysis, if those sessions meet either of the following criteria:

The following configuration properties can be used to adjust this behavior:

Remember-Me Config

As a user convenience, Code Dx can optionally remember users' logged-in state on trusted devices. Although support for this feature is turned on by default, this can be changed to one of three levels via the swa.user.rememberme field in the properties file. The supported configuration values are:

Note: for full and username-only modes, users can opt-out of being remembered by Code Dx by unchecking the “remember me” checkbox in the login form.

Report Configuration Templates

Several report configuration options accept templates for their values. These templates may contain plain text and various substitutions, surrounded by {{ and }}. To include a { } or \, prefix them with a backslash (e.g., \{).

The available substitutions are:

Enterprise users may also include project metadata values as well:

The following modifiers may be applied to any value:

For example, {{project.name|abbreviate:8}} will limit the length of the project name to the first 5 characters followed by an ellipse. A project name of "My Project" would be shortened to "My Pr..." for display purposes.

Report Filename

The template used to generate filenames for reports may be customized. This can be done by setting the report.filename-template property. See the Report Configuration Templates section for details on valid values.

The default template is {{project.name}} ({{date:dd MMM YYYY}}) - which will produce filenames such as "My Project (27 Mar 2017).xml"

PDF Report Configuration

Your company logo can be displayed on the cover of PDF reports. For best results, the image should be at least 432 pixels wide and/or 144 pixels tall. Set the report.pdf.custom-logo property to the filename of the logo. The file can be located in the same folder as the codedx.props file or, if the file is located elsewhere, specify the path with the filename. The default is no company logo.

Limits

There are limitations in place on the PDF report. Depending on the hardware configuration of the machine running Code Dx, you may be able to increase these limits. Be aware that raising these limits will increase memory requirements.

The limits may be changed by adjusting the following options:

Extended Customization

There are options allowing for extended customization when using Code Dx Enterprise. These customizations may be made by adjusting the following options:

Finding Search

On the Findings Page, the Search area lets you filter findings based on metadata fields from their results (a.k.a. "Evidence" on the Details Page). The fields presented in the Search dropdown are the intersection of the set of fields present in that project, and the set of fields present in a "for display" whitelist. The "for display" whitelist can be augmented via configuration:

Note that when searching based on a result metadata field, you must enter the full, case sensitive value of the metadata in order to get a match. For example, searching by Field 1 for abc will not match a Field 1 with a value of abc123or ABC.

Tool Configuration

Props Settings

Code Dx has tool-specific settings for some tools which control how Code Dx will behave in response to data from those tools.

Veracode

When accessing Veracode via a Tool Connector, it is possible to load "Callstack" information for each Veracode Flaw. (Veracode Callstack information is interpreted as Code Dx Data Flow information for the corresponding results.) Doing so will improve the decision-making process of agentless hybrid correlation, but comes at a steep performance cost (roughly 1-2 seconds per flaw).

NowSecure

NowSecure uses lab-api as the default subdomain for the lab api, and lab as the default subdomain for the user interface. Code Dx allows user-defined values for these subdomains in the props file.

Configuration Files

For some of the bundled tools, Code Dx provides the ability to define a configuration file, either system-wide, or on a per-project basis. Within the Code Dx appdata directory, locate the tool-data directory (or create it if it's not present). To define a configuration file for a tool, create a directory with that tool's name (as specified below). A system-wide configuration should be placed in that directory, or for a per-project config, create a sub-directory named with the given project's ID, and place the configuration file in that sub-directory.

Scalastyle

Code Dx supports user-defined config.xml scalastyle config files. Place the file within the tool-data/scalastyle directory, or within a project-specific subdirectory. Files should follow the format defined by scalastyle.

Code Dx also supports a user-defined scalastyle.props config file, for configuring the JVM environment in which the scalastyle tool runs. Currently, the only supported property is file.encoding, which will be passed to the JVM via the -Dfile.encoding environment variable. This allows you to run scalastyle on projects that don't use the standard encoding.

Checkstyle

Code Dx supports user-defined config.xml Checkstyle configuration files. Place the file within the tool-data/checkstyle directory, or within a project-specific subdirectory. Files should follow the format defined by Checkstyle.

Cppcheck

Code Dx supports a user defined cppcheck.conf config file. Create the file in the tool-data/cppcheck directory, or within a project-specific subdirectory. Within that file, you can define a value for the useThreads property (e.g. useThreads=4 to request that Cppcheck use four threads). Also, Cppcheck will run with the --inline-suppr option enabled by default, allowing you to suppress errors from within your source code. This behaviour can be disabled by setting inlineSuppression=false. See the Cppcheck Manual for more details on these settings.

You can also choose to define the platform property. This affects Cppcheck's configuration for platform specific types and sizes. By default Cppcheck will choose the platform your Code Dx server is running on. Available platform options are as follows:

JSHint

Code Dx supports a user defined jshint.conf config file. Create the file in the tool-data/jshint directory, or within a project-specific subdirectory. Within that file, you can define a value for the scan-html property, which tells JSHint to additionally scan .htm and .html files. This property is enabled by default (e.g. scan-html=true).

You can also define a value for the extract property, which sets the value for the --extract flag from JSHint. This flag controls how JSHint extracts HTML from files. Available extract options are as follows:

PHPMD

Code Dx supports user-defined config.xml PHPMD ruleset files. Place the file within the tool-data/phpmd directory, or within a project-specific subdirectory. Files should follow the format defined by PHPMD.

PHP_CodeSniffer

Code Dx supports user-defined config.xml PHP_CodeSniffer ruleset files. Place the file within the tool-data/phpcodesniffer directory, or within a project-specific subdirectory. Files should follow the format defined by PHP_CodeSniffer.

PMD

Code Dx supports a user defined pmd.conf config file. Create the file in the tool-data/pmd directory, or within a project-specific subdirectory. Within that file, you can define a value for the debug-logging property (e.g. debug-logging=true to enable verbose PMD logs). You can also define a value for the encoding property (e.g. encoding=UTF-8 to set the character encoding PMD expects source to be in. Acceptable values are any standard java.nio.charset.Charset character set). By default debug-logging=false, and encoding=UTF-8.

ESLint

By default, Code Dx will pass --ignore-pattern **/node_modules/*

Configuration

Code Dx supports user-defined .eslintrc and .eslintignore ESLint config files. Place the file(s) within the tool-data/eslint directory, or within a project-specific subdirectory. Files should follow the format defined by ESLint. You can use the js, yml, json, or eslintrc formats. In the event that there are multiple config files present in different formats, Code Dx will follow the same priority that ESLint uses. ESLint will also use any .eslintrc config files uploaded in the project as defined by the rules explained here. Additionally, Code Dx will search for an .eslintignore file in the root directory of the uploaded zip file. The .eslintignore file in the zip will take precedence over the .eslintignore file in the tool-data/eslint or project-specific directories. If you use a custom config, be sure to adjust your Tool Configuration. By default, only the recommended ESLint rules are enabled.

Code Dx also supports user-defined extension of the default eslintrc.json file. For users wanting to add small tweaks to the default configuration, a eslint-config-extra.js can be placed within the tool-data/eslint directory, or within a project-specific subdirectory (a directory whose name is the numeric id of the Code Dx project), as with the custom .eslintrc and .eslintignore files mentioned in the previous paragraph. When running ESLint, Code Dx will search for this "extra" config file and, if present, will include it as an extension of its default ESLint config file. The contents of the eslint-config-extra.js file should be in the form module.exports = { ... }, where the ... is replaced by your custom configuration as defined in the ESLint configuration guide.

Important note about using a custom .eslintignore file: If an .eslintignore file is neither found in the uploaded zip file nor provided in the tool-data/eslint directory, Code Dx will pass --ignore-pattern **/node_modules/* as a command-line argument to ESLint. If you want to provide an .eslintignore file, it is a good idea to include the **/node_modules/* pattern in that file; linting the contents of your third-party dependencies is not recommended, and in some cases can cause ESLint to fail.

Several ESLint plugins are made available when running as a bundled tool in Code Dx:

Any of these plugins can be used in or excluded from your user-defined configs. All plugins use their default or recommended rules and settings, except for no-location-href-assign from eslint-plugin-xss. For this rule, Code Dx uses encodeURIComponent for the escapeFunc option instead of the default escape function, which has been deprecated. More information about how to configure these plugins can be found on their respective npmjs or github pages.

By default, Code Dx will run ESLint on .js, .html, and .htm files. If you want to change this behaviour, you can specify a comma separated list of file extensions with the eslint.extensions setting in your codedx.props file. You do not need to include the . with each file extension (eslint.extensions = js,html,htm). Note that if you decide not to use the html plugin in your custom configs, you must use this setting to specify that you want ESLint to only run on .js files. Otherwise it will try to scan any .html and .htm files it finds as javascript, which will cause ESLint parsing errors.

Custom Plugins and ESLint Installations

Code Dx allows you to install third-party ESLint plugins, shareable configs, and parsers. To do so, first make sure you have npm installed and accessible from the command line by installing Node.js. Then, open a command line and navigate to the tool-data/eslint directory, or a project-specific subdirectory. From there, you can install any plugins, shareable configs, and parsers you wish to use by running the command npm install ... --save. You do not need to install any of the plugins included with Code Dx by default.

If instead you want to use your own ESLint environment, you can specify the path to it in your codedx.props file with the eslint.path setting. Code Dx expects that the provided directory will point to the folder containing ESLint's bin folder. Code Dx will also try to find any of the supported ESLint config files in this directory. Note that if you use the global or project config files as described above, they will take precedence over the ones in this folder. Also, when using an external installation, Code Dx will ignore any custom plugin folders in the tool-data/eslint directory.

JVM System Properties

You can set custom system properties for the JVM process that hosts Code Dx. To do so, use the prefix codedx.jvmprops. on a line in your codedx.props file. For example, to set the http.proxyHost system property to 1.2.3.4, add the following line:

codedx.jvmprops.http.proxyHost = 1.2.3.4

Note that specifying a setting this way will overwrite existing settings in the JVM. For example, it is possible to overwrite the user.home property, which may be used by logic within Code Dx. Beware of overwriting an important value! For a non-exhaustive list of system properties to watch out for see https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html

Proxies

Some enterprise features like JIRA Integration and Tool Connectors reach out to third-party programs via HTTP(S). If your Code Dx server is running behind a proxy, you can configure Code Dx to use that proxy for communications with these programs by setting the appropriate properites:

A typical proxy configuration in your codedx.props file will look something like this (of course you will replace the values with ones specific to your own proxy):

proxy.host = 123.234.156.178
proxy.port = 3128
proxy.username = myproxyuser
proxy.password = myproxypassword

Visual Log Configuration

By default, the visual log will not record successful-login events. To enable this, set the auth.logging.recordSuccess = true. Note that changing this property will not retroactively reveal successful logins from the past, as this setting determines whether to record successful logins, not whether to show them.

Tool Orchestration Configuration

Code Dx can use the Tool Orchestration Service to run orchestrated analyses in whole or in part on a Kubernetes (k8s) cluster. The tool service is disabled by default, but you can enable it after using the codedx-orchestration Helm chart to install the tool orchestration components on your cluster - see the chart for installation instructions.

Set tws.enabled = true to enable the tool service, and then specify the base URL of the service running on your k8s cluster with tws.service-url and the service's API key with tws.api-key. The API key must match what you specified for the toolServiceApiKey Helm chart parameter.

For example, the following configuration will let Code Dx use the tool service running at https://tool-service.cdx-svc.svc.cluster.local:3333 with API key cc224a8f-a307-416e-a6dd-769600ac8e2c:

tws.enabled = true
tws.serviceUrl = https://tool-service.cdx-svc.svc.cluster.local:3333
tws.apiKey = cc224a8f-a307-416e-a6dd-769600ac8e2c

Analysis Cleanup

By default, Code Dx will remove old analyses and related storage from the tool service automatically. You can customize or disable this behavior with the following options in your codedx.props file:

Note: Both successful and failed analyses count towards the "total" being tracked.

Issue Tracker Configuration

To support issue tracker integrations, Code Dx will make requests to the issue tracker server from time to time in order to create, update, and read issues. Due to the volume of requests that can be made in quick succession, issue tracker servers may begin to deny requests to prevent the server from being overloaded. The following properties will affect how Code Dx makes requests.

Machine Learning Triage Server Memory Usage

Code Dx's machine learning aided triage functionality is handled by a separate process, the Machine Learning Triage Server, which Code Dx spawns and manages. Training a new prediction model is computationally intensive and can use large amounts of memory. There are times where training performance can be improved with the availability of more memory. The upper bound on the amount of memory that the Machine Learning Triage Server JVM can use during training and making predictions can be configured by setting the following props setting:

mltriage.service.maxheap [default: none] -- sets the max heap size (in megabytes) of the Machine Learning Triage Server JVMs

Automatic Updating of Code Dx Prediction Model

Code Dx can automatically update your prediction model. This feature can be configured or turned off completely by setting the following props settings in your codedx.props file: