2.7.0
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

With the Bitnami-powered installation, Code Dx now comes pre-packaged with most of its requirements making it significantly easier to get started for both evaluation and production installations of Code Dx.

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.

.NET Analysis

In order to run the bundled .NET tools supported by Code Dx, the .NET runtime is required for Windows and the Mono runtime is required for Linux and Mac.

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.

Depending on the version of FxCop you plan to use, it will either be bundled with Visual Studio (as Code Analysis) or in the Windows SDK. For the best results, install Visual Studio 2012, 2013, or 2015 Premium. This will give you the latest rules available. Code Dx 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). Code Dx supports versions 10, 11, 12, and 14 of FxCop. Since FxCop 10, Microsoft has stopped shipping a stand-alone version of FxCop and instead ships it as part of Visual Studio. Despite the Visual Studio dependency, it is recommended to install the latest version of Visual Studio to get the latest version of FxCop.

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

Code Dx is a web-based application that should be installed using the Bitnami provided installer. This installer takes care of adding the necessary pre-requisites to the system and configures them for use with Code Dx. In addition, these are setup as services on the host system so they will automatically startup whenever the system is restarted.

Some of the Code Dx dependencies will be setting up services that listen for network activity (the web server for instance to accept incoming requests). If a port conflict is detected you will be prompted for an alternate port configuration.

For most installations we recommend the standard graphical installer which will be detailed in the following sections and should for the most part apply to all three major supported platforms. For instructions specific 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 instance:

./codedx-2.4.0-0-linux-x64-installer.run --mode text

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.

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).

Trusting Self-Signed Certificates

Many of the options in Project Management involve setting up communication between Code Dx and a third-party application such as JIRA, Git, or certain enterprise tools. Some users will have these applications protected with https, using a self-signed certificate. Even if you've added the certificate to your operating system's trust store, Code Dx may still reject the certificate, leading to issues like "couldn't connect to...". Code Dx comes with its own Java installation, which has its own "trust store". To get Code Dx to trust your self-signed certificate, you'll need to add that certificate to Code Dx's Java trust store.

  1. Get a copy of the certificate as a file
    • The following steps use Windows+Chrome
    • Navigate to the page with the untrusted certificate using your browser (i.e. chrome)
    • Click the lock icon in the URL bar to open the connection info popup
    • There should be a message like "your connection is [not] private" with a "Details" link. Click the "Details" link, which brings up the "Security" tab in Chrome's dev tools
    • Click the "View certificate" button to bring up the certificate details popup
    • Go to the "Details" tab in the "Certificate" popup
    • Click the "Copy to File..." button
    • Use the default format (DER encoded binary X.509 (.CER))
    • Use C:\my-self-signed.cer as the filename
    • When you click the Finish button it should say "the export was successful"
  2. Add the saved .cer file to Code Dx's keystore
    • Open a command prompt in admin mode (necessary to modify files in Program Files)
    • cd into C:\Program Files\Code Dx\java\bin (path may vary based on options picked during installation)
    • run keytool -import -keystore ..\lib\security\cacerts -file C:\my-self-signed.cer
      • Replace C:\my-self-signed.cer with whatever path you used at the end of step 1
    • When prompted for the keystore password, enter changeit
    • enter yes when asked to "Trust this certificate"
    • It should say "Certificate was added to keystore"
  3. Restart the Code Dx services to make the keystore changes take effect

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.

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

A valid Code Dx license is required to run Code Dx. When you first install and run Code Dx, a free 14-day trial license will automatically be generated (requires internet access), giving you access to Code Dx Stat!.

If your license expired, is invalid, or you don't have internet access, 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 (sales@codedx.com) 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 you're using does not have access to the internet, please use a different system and contact the sales team via email (sales@codedx.com).

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. Although you can setup Code Dx to have two instances of Code Dx running on it, it is not a recommended setup as it will likely lead to resource contention resulting in performance degradation to the multiple installations.

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 /Applications/codedx/apps/codedx/codedx_data/codedx_appdata/ on OS X.

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.driver = com.mysql.jdbc.Driver
swa.db.user = database_username
swa.db.password = database_password

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. The available settings include:

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

User DN Template

The user DN is the fully qualified LDAP identifier for the user when logging in. The user DN template controls how the user DN is generated for a username entered into Code Dx. This value is simply a full user DN, with a {0} placeholder in place of the actual username. This is where the username entered will be inserted.

In the example above (cn={0},ou=users,dc=codedx,dc=com), when the user "test" attempts to log in, the user DN that will be checked will be cn=test,ou=users,dc=codedx,dc=com.

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 DN 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.

More information may be found here.

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.

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.

Analysis Behavior

Various settings allow you to affect Code Dx's behavior regarding the analyses it conducts.

  1. For the analyses that are stored, Code Dx will, by default, maintain a copy of the raw inputs it received for processing. While these inputs are not used by Code Dx once it finishes the analysis process, they are kept around for archival purposes. The default is true. If storage space is an issue, the swa.storage.keep-raw-inputs can be set to false to prevent Code Dx from storing the raw inputs.

  2. There is also an option to keep archived inputs using swa.storage.keep-archived-inputs. The purpose of this setting is to store tool inputs that are archived. By default, the value is false. If, however, you would like to keep the archived information, you can set swa.storage.keep-archived-inputs to true. Please note this setting is dependent upon the value of swa.storage.keep-raw-inputs, which must also be true in order to keep the archived data.

  3. The swa.tools.keep-all-logs setting determines whether or not to keep all the log files for the tools that Code Dx runs. If false, only the failure logs are kept. Default is false.

  4. Code Dx bundles various static analyzers 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.

    • java.tools.maxmemory determines the maximum heap size for java-based tools. Default is 1024 (1GB).
    • ruby.tools.maxmemory determines the maximum heap size for Ruby-based tools, which are run with Java via JRuby. Default is 1024 (1GB).
    • python.tools.maxmemory determines the maximum heap size for Python-based tools, which are run with Java via Jython. Default is 1024 (1GB).
    • cat.net.maxmemory determines the maximum allowed memory usage for CAT.NET. Default is 2048 (2GB).
    • php.tools.maxmemory determines the maximum heap size for PHP tools. Default is 1024 (1GB).
  5. You can adjust the number of concurrent jobs running at the same time. Higher numbers translate to more available resources of that type. The minimum value allowed is 1000 jobs. The default is 2000 jobs.

    • swa.jobs.cpu-limit determines the maximum cpu resources
    • swa.jobs.memory-limit determines the maximum memory resources
    • swa.jobs.database-limit determines the maximum database resources
  6. The swa.jobs.expiration option specifies the time the job results are cached for (in minutes). Default is 60 minutes.

  7. The swa.upload.maxfilesize setting provides the maximum allowed size (in megabytes) of a single file in a multi-part upload. Default is 2048 MB (2 GB).

  8. You can adjust the maximum allowed size (in megabyes) of a complete upload by changing swa.upload.maxuploadsize. Default is 2048 MB (2 GB).

  9. The tools bundled with Code Dx may be disabled entirely if desired by setting bundled-tools.disable to true. When this flag is set, no bundled tools will be available on the new analysis page nor will they be run. Default is false.

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.

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:

Tool 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.

Cppcheck

Currently, Code Dx only supports the optional use of Cppcheck's multithreaded checking option (see the Cppcheck Manual for details). Place a cppcheck.conf 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).

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 user_ruleset.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.