
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:
- Dual-core CPU if you're not using Machine Learning (ML); Quad-Core if using ML
- 8GB of RAM if you're not using ML; 16 GB if using ML
- 10 GB hard-disk, SSD is strongly recommended
- Windows (10 and Server 2016+), macOS 10.14+, or Linux (Ubuntu 18+, RHEL/CentOS 7+)
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
- Open a command prompt in administrator mode
- Change directory to Code Dx's Java trust store:
cd <installation-directory>\Code Dx\java\bin
where the<installation-directory>
default isC:\Program Files\Code Dx
- 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. - Restart the Code Dx services for the change to take affect
Linux
- Open a Terminal
- 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 - 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.
- [root] use
- Restart the Code Dx services for the change to take affect
Deleting a Certificate from the Trust Store
- Open a Windows command prompt in administrator mode or a terminal in Linux
- Change directory to Code Dx's Java trust store:
cd <installation-directory>/java/bin
where the<installation-directory>
defaults areC:\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
.
- [Windows] use
- 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.
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.
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.
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).
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:
- Open the installation directory (E.g:
C:\Program Files\Code D
or/opt/codedx/codedx
). - Remove the specified file(s) or folder(s) and leave the backup folder (
backup-timestamp
), theupgrade.ini
file, and theproperties.ini
file.
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:
- Open the “Command Prompt” application as an administrator.
- Remove the presented service by doing:
Note: Replace CodeDxMariaDB with the service name that the installer displays> sc delete CodeDxMariaDB [SC] DeleteService SUCCESS
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
- Open the “Resource Monitor” application as an administrator.
- Click the “Network” tab.
- Click the “TCP Connections” bar to see a list of TCP connections established.
- Look for one of the ports in the presented list.
- In order to continue with the upgrade process, you have to make sure that the presented ports are available. If the process using the required ports is a version of Code Dx, please follow the "Remove Serivces" section. If it is not Code Dx related, make sure to find the conflicting program and ensure that the problem will not occur after installation.
Linux and OS X
List the processes listening to a TCP connection using terminal:
sudo lsof -iTCP:8009 -sTCP:LISTEN COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME java 81106 codedx 50u IPv4 40576813 0t0 TCP *:8009 (LISTEN)
Note: Only use sudo if installed as root
In order to continue with the upgrade process, you have to make sure that the presented ports are available. You should stop the process that spawned the service and ensure that the conflict will not occur after installation
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
- 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 - To restore to your current installation and data folders: right-click on
restore-backup.bat
and choose Run as administrator - To restore to different installation and/or backup folders, right-click on
restore-backup.bat
, choose Run as administrator, and runrestore-backup <\path\to\new\installation\folder> <\path\to\new\data\folder>
substituting the paths and folder names to the new directories
Linux Root Installation
- 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 - Open a terminal and run
sudo chmod +x restore-backup.sh
- To restore to your current installation and data folders, run
sudo ./restore-backup.sh
- 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
- 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 - Open a terminal and run
chmod +x restore-backup.sh
- To restore to your current installation and data folders, run
./restore-backup.sh
- 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:
Start individual services (you can replace "start" with "stop" or "restart"):
./ctlscript.sh start tomcat
./ctlscript.sh start apache
./ctlscript.sh start mysql
Start, stop, or restart all services:
./ctlscript.sh start
./ctlscript.sh stop
./ctlscript.sh restart
Obtain the current status of all services:
./ctlscript.sh status
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.
swa.db.url
- The JDBC URL of the database Code Dx will be communicating withswa.db.user
- The username that will be used to access the databaseswa.db.password
- The password that will be used to access the database
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:
- Update notifications - Code Dx will no longer periodically check for newer versions and display an update notification when one is available
- Dependency-Check updates - Dependency-Check will no longer be able to periodically download updates from the National Vulnerability Database, the Retire.js repository, or reach out to Maven Central while scanning Java dependencies (this aids in the dependency identification process, to cut down on both false positive and false negative results). This may lead to lower quality results when running Dependency-Check as a bundled tool.
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.
- https://jeremylong.github.io/DependencyCheck/current.txt
- https://nvd.nist.gov/feeds/json/cve/1.1/nvdcve-1.1-modified.json.gz
- https://nvd.nist.gov/feeds/json/cve/1.1/nvdcve-1.1-%d.json.gz (where %d is a year)
- https://static.nvd.nist.gov/feeds/xml/cpe/dictionary/official-cpe-dictionary_v2.3.xml.gz
- https://repository.sonatype.org/service/local/
- https://search.maven.org/solrsearch/select
- https://search.maven.org/remotecontent?filepath=
- https://ossindex.sonatype.org
- https://registry.npmjs.org/-/npm/v1/security/audits
- https://raw.githubusercontent.com/Retirejs/retire.js/master/repository/jsrepository.json
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:
auth.ldap.url = ldap://127.0.0.1:389/
- sets the LDAP URL to connect to; this setting is required for LDAP usageauth.ldap.systemUsername = sAMAccountName=admin,ou=users,dc=codedx,dc=com
- sets the system username (full account DN) that is used when connecting to the LDAP server for authorization queries; this setting is not required if the LDAP server accepts anonymous queriesauth.ldap.systemPassword = secret
- sets the password corresponding with the system username (above) that is used when connecting to the LDAP server for authorization queries; this setting is not required if the LDAP server accepts anonymous queriesauth.ldap.authenticationMechanism = simple
- sets LDAP authentication mechanism for authorization queries; accepted values are none (anonymous) and simple [default: none]auth.ldap.userSearchTemplate = sAMAccountName={0},ou=users,dc=codedx,dc=com
- controls the template to generate the user search query for authorization; more information can be found here [default:<direct user input>
]auth.ldap.useAsDnTemplate = false
- whether to use the provided search template(s) as DN templates instead [default: false]auth.ldap.useStartTLS = false
- enable or disable the use of StartTLS after establishing an LDAP connection [default: false]auth.ldap.legacyMode = false
- enable or disable the legacy Code Dx LDAP implementation [default: false]auth.ldap.user.groupAttribute = memberOf
- set the name of the LDAP attribute on a user that lists their groups [default: memberOf]auth.ldap.group.nameAttribute = cn
- set the name of the LDAP attribute on a group that indicates their readable name (leave blank for pass-through) [default: cn]auth.ldap.user.displayNameAttribute = cn
- set the comma-separated list of LDAP attributes names on a user indicating their display name, see section below for syntax [default: cn, userPrincipalName, sAMAccountName]auth.ldap.sync.autoUpdate = false
- set whether or not to automatically schedule LDAP group membership updates [default: false]auth.ldap.sync.refreshInterval = 5 minutes
- set the refresh interval for automatic LDAP group membership updates in readable text [default: "5 minutes"]auth.ldap.searchSubTree = true
- sets whether or not to search sub-trees for users with the provided userSearchTemplate(s) [default: true]
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.
auth.saml2.identityProviderMetadataPath
- [required] sets the file path to the XML metadata for your SAML IdP (file must exist on the Code Dx host)auth.saml2.keystorePath
[default: internal Code Dx path] - sets the signing key for SAML requests by Code Dx; must be JKS format with the appropriate cert, private key, and an assigned password for both the JKS` key store and private key; will be auto-generated at an internal Code Dx location if unassignedauth.saml2.keystorePassword
- [required] sets the password used to open the assigned JKS fileauth.saml2.privateKeyPassword
- [required] sets the password to use with the private key stored in the assigned JKS fileauth.saml2.responseUniqueNameAttribute
[default: from IDP XML] - sets the specific attribute to use as the unique username ID; the value of this attribute is used as the user's login ID and display nameauth.saml2.namePolicyFormat
[default: from IDP XML] - sets the accepted/required format of the username IDauth.saml2.entityId
[default: https://codedx.com] - sets the entity ID used to identify Code Dx as a service provider when registering with your IdPauth.saml2.destinationBindingType
[default:urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
] - sets the Assertion Consumer Service (ACS) binding type for Code Dxauth.saml2.maximumAuthenticationLifetime
[default: 3600] - sets the maximum lifetime of a SAML-authenticated user session in seconds; this value must be the same as the time specified by your IdPauth.saml2.maxSkewSeconds
[default: 120] - sets the maximum allowable difference in UTC time between the Code Dx server and an IdP serverauth.saml2.passive
[default:false
] - sets whether or not to use passive authentication against your IdPauth.saml2.forceAuth
[default:false
] - sets whether or not to force re-authentication with your IdP when the user starts a new browser sessionauth.saml2.requireSignedAssertions
[default:true
] - sets whether or not Code Dx should require signed assertions from your IdPauth.saml2.signAuthenticationRequests
[default:false
] - sets whether or not Code Dx should sign authentication requests to your IdPauth.saml2.useNameQualifier
[default:true
] - sets whether or not Code Dx should include a name qualifier in requests to your IdPauth.autoExternalRedirect
[default:true
] - sets whether or not to automatically redirect unauthenticated users to your IdP login portalui.auth.samlLabel
[default: SAML] - sets the label for SAML-related operations within the Code Dx interface; this will be displayed when signing in to Code Dx or when creating new users
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:
- Register entity
https://codedx-foo.com
with its ACShttps://foo.com/codedx/login/callback/saml
- Register entity
https://codedx-bar.com
with its ACShttps://bar.com/codedx/login/callback/saml
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:
- Set
auth.autoExternalRedirect = false
in yourcodedx.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. - 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 ofauth.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:
auth.auto-create.enabled = false
- set whether to auto-create externally-authenticated users that don't exist yet in Code Dx [default: false]auth.auto-create.ldap.group-names = foo, bar
- a comma-separated list of group names, where an LDAP user must be a member of at least one of those groups to allow auto-creation [default: none]auth.auto-create.ldap.auto-toggle-enabled = false
- set whether to automatically enable/disable registered users based on their membership in the provided LDAP group names (no effect ifgroup-names
is unassigned or empty) [default: false]
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:
session.lifetime
- sets the duration of inactivity required before automatically signing out a user; if unassigned, sessions will never expiresession.timeout-notice
- sets the point at which the user will be notified when their session will expire
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.
swa.jobs.cpu-limit
determines the maximum available CPUswa.jobs.memory-limit
determines the maximum available memoryswa.jobs.database-limit
determines the maximum available database I/Oswa.jobs.disk-limit
determines the maximum available disk I/O
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.
analysis.concurrent-analysis-limit
(default:2
) - the maximum number of analyses to run concurrently. Please note that this does not override the Job Configuration settings, but merely sets another limit.storage.keep-raw-inputs
(default:true
) - when this setting is true, Code Dx will keep copies of all files uploaded for analysis. While these inputs are not required by Code Dx after the analysis is complete, keeping them for archival purposes will allow them to be downloaded from the Show Inputs list. If storage space is an issue, setting this tofalse
will prevent Code Dx from storing the raw inputs.storage.keep-archived-inputs
(default:false
) - when this setting is true, Code Dx will keep all uploaded files, regardless of if they are archived or not. Leaving this settingfalse
will cause Code Dx to delete stored copies of data upon archival. Please note this setting is dependent upon the value ofstorage.keep-raw-inputs
, which must also betrue
in order to keep the archived data.swa.tools.keep-all-logs
(default:false
) - this setting determines whether or not to keep all the log files for the tools that Code Dx runs. If false, only the logs from failures are kept.swa.upload.maxfilesize
(default:2048
) - this setting controls the maximum file upload size allowed (in megabytes) for a single file.swa.upload.maxuploadsize
(default:2048
) - this setting controls the maximum size of all uploaded files (in megabytes) for a single analysis.codedx.analysis.hybrid-enabled-by-default
(default:false
) - this setting determines the default value for "Enable hybrid analysis" setting in Analysis Config. Since hybrid analysis requires some relatively time-consuming steps, this setting isfalse
by default.codedx.analysis.auto-archive-enabled-by-default
(default:true
) - this setting determines the default value for the "Archive findings" setting in Analysis Config. Most projects will only upload a scan from a tool if it represents a new state of the project, but an organization may want to be able to upload many tool result files in sequence without having them interfere with each other. Such organizations should set this setting tofalse
.codedx.analysis.auto-archive.excluded-tools
(default: none) - this setting allows excluding outputs from certain tools from the auto archival process. This setting is a comma-separated list of the names of the tools to exempt from auto archival.ingestion.skip-code-metrics
(default: false) - if set to true, code metrics will not be gathered during analysisfinding.reopen-gone
(default: true) - this setting determines the default value for the "Allow gone findings to be reopened" setting in Analysis Configfinding.reopen-resolved
(default: false) - this setting determines the default value for the "Reopen resolved findings when updated" setting in Analysis Configstorage.keep-failed-analysis-inputs
(default: false) - this setting determines whether or not to keep files associated with failed analyses
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.
java.tools.maxmemory
(default:1024
(1GB)) determines the maximum heap size for java-based tools.java.tools.maxmemorypercentage
(default:<none>
) determines maximum heap size for java-based tools as a percentage of total system memory.ruby.tools.maxmemory
(default:1024
(1GB)) determines the maximum heap size for Ruby-based tools, which are run with Java via JRuby.ruby.tools.maxmemorypercentage
(default:<none>
) determines the maximum heap size for Ruby-based tools as a percentage of total system memory, which are run with Java via JRuby.cat.net.maxmemory
(default:2048
(2GB)) determines the maximum allowed memory usage for CAT.NET.php.tools.maxmemory
(default:1024
(1GB)) determines the maximum heap size for PHP tools.
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:
- Archived sessions are hidden by default on the Instrumentation Page; when shown, they have a special appearance.
- Any trace data from an archived session which is not associated with any result data (i.e. DAST tool findings) will be deleted.
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 session contains trace data that is associated with result data in the project (i.e. you just uploaded the DAST tool results after running a scan with tracing active).
- The session is at least 24 hours (configurable) old, and a newer session exists, belonging to the same agent, which is already archived.
The following configuration properties can be used to adjust this behavior:
codedx.ingestion.trace-session-archival.enabled
(defaulttrue
) - if set tofalse
, Code Dx will not automatically archive any trace sessions.codedx.ingestion.trace-session-archival.unused-sessions
(defaulttrue
) - if set tofalse
, Code Dx will not automatically archive "old" trace sessions (the 2nd of the criteria listed above).codedx.ingestion.trace-session-archival.unused-sessions.age-threshold-hours
(default24
) - determines how old (based on end time) a trace session must be before it can be considered an "old" session and become a candidate for auto-archival under the 2nd criteria listed above.
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:
full
- Code Dx will remember any user who logs in. Once logged in, users will not need to log in via the login form even after their session expires. They will be remembered by a special cookie, until that cookie expires. TherememberMe
cookie does not contain the user’s password in any way, shape, or form.username-only
- Code Dx will remember the username of any user who logs in. This is used to auto-fill the username field of the login form. Users are remembered by a cookie, until that cookie expires. This cookie simply contains the user’s name.off
- Code Dx will not remember anything about a user once that user’s session expires or if they log off.
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:
{{report.name}}
or{{report.type}}
- the type of report, e.g., 'PDF'{{project.id}}
and{{project.name}}
- the ID or name of the project the report was generated for{{user.name}}
- the display name of the user who generated the report{{date:pattern}}
- the current date/time formatted with the given pattern; details on acceptable patterns may be found here
Enterprise users may also include project metadata values as well:
{{meta:foo}}
or{{metadata:foo}}
- provides the contents of the metadata field named "foo" for the project (or a blank string if that value is not specified){{meta.id:bar}}
or{{metadata.id:bar}}
- provides the ID of the chosen metadata value for the field named "bar" (or a blank string if one was not given)
The following modifiers may be applied to any value:
ltruncate:length
- will take up to the lastlength
characters (shortening from the left of the string)truncate:length
orrtruncate:length
- will take up to the firstlength
characters (shortening from the right of the string)labbreviate:length
- will take up to the lastlength
characters, inserting an ellipsis on the left if the string was shortenedmabbreviate:length
orcabbreviate:length
- will take up tolength
characters from the string, inserting an ellipsis in the center of the string if necessaryabbreviate:length
orrabbreviate:length
- will take up to the firstlength
characters, inserting an ellipsis on the right if the string was shortened
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
Company Logo
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:
report.pdf.dast-body-limit
[default: 8192] - sets the limit, in bytes, of DAST bodies to be displayed in the PDF reportreport.pdf.details-simple-limit
[default: 50000] - sets the number of findings to restrict simple details to in the PDF reportreport.pdf.details-source-limit
[default: 5000] - sets the number of findings to restrict source code display to in the PDF reportreport.pdf.dast-finding-limit
[default: 1000] - sets the number of findings to allow DAST request/response bodies to be displayed for in the PDF report
Extended Customization
There are options allowing for extended customization when using Code Dx Enterprise. These customizations may be made by adjusting the following options:
report.pdf.show-code-dx-logo
[default: true] - controls whether the Code Dx logo will be included on the coverreport.pdf.pdf-title
[default: "Assessment Report: {{project.name}}"] - sets the title of generated PDF reports; see the Report Configuration Templates section for details on valid valuesreport.pdf.cover-page-title
[default: "Assessment Report"] - sets the title shown on the cover page of generated PDF reports; see the Report Configuration Templates section for details on valid valuesreport.pdf.page-header
[default: "{{project.name}} - Code Dx Assessment Report"] - sets the header displayed at the top of all PDF report pages; see the Report Configuration Templates section for details on valid valuesreport.pdf.disable-page-header
[default: false] - if true, the page header will be supressed on all pagesreport.pdf.disable-page-footer
[default: false] - if true, the page footer will be supressed on all pagesreport.pdf.japanese-mode
[default: false] - if true, Japanese fonts will be used as the primary font for all text in PDF reports. if false, Japanese fonts will only be used to render Japanese characters
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:
additional-values.extra-for-display
[default: N/A] - a comma-separated list of result metadata fields that you want to appear in the Search dropdown. Leading and trailing spaces around each entry in the list will be trimmed. For example,Field 1, Field 2 , Field 3
will be interpreted as a 3-item list;Field 1
,Field 2
, andField 3
.
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 abc123
or 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).
veracode.callstack-load-enabled
enables loading of the optional "Callstack" information when set totrue
. Defaults tofalse
.
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.
nowsecure.lab-api-subdomain
defines the subdomain for the lab api. Defaults tolab-api
.nowsecure.lab-ui-subdomain
defines the subdomain for the lab user interfance. Defaults tolab
.
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:
unix32
32 bit Unix variantunix64
64 bit Unix variantwin32A
32 bit Windows ASCII character encodingwin32W
32 bit Windows UNICODE character encodingwin64
64 bit Windowsavr8
8 bit AVR microcontrollersnative
Type sizes of host system are assumed, but no further assumptions.unspecified
Unknown type sizes
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:
auto
JSHint will attempt to extract javascript only if the file looks like it's an HTML file. This is the default value (e.g.extract=auto
).always
JSHint will always attempt to extract javascript. Note that if this value is set, JSHint will scan all files as HTML. This means that javascript source files will not be scanned normally. Instead, JSHint will search them for HTML to extract and anything else in the file will be ignored.never
JSHint will never attempt to extract javascript. Note that if this value is set, JSHint will not be able to scan HTML.scan-html
must be set tofalse
, otherwise JSHint will try to scan HTML files as javascript source and will report an error for each one.
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:
- eslint-plugin-security: enabled by default
- eslint-plugin-scanjs-rules: enabled by default
- eslint-plugin-no-unsanitized: included as a requirement of scanjs-rules
- eslint-plugin-xss: enabled by default
- eslint-plugin-html: enabled by default
- eslint-plugin-react: enabled by default
- eslint-plugin-react-hooks: enabled by default
- eslint-plugin-node: enabled by default
- eslint-plugin-import: enabled by default
- eslint-plugin-flowtype: enabled by default
- eslint-plugin-jsx-a11y: disabled by default in Tool Configuration
- babel-eslint: default Code Dx parser
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:
proxy.host
- The hostname, or address, of the proxy server, e.g.1.2.3.4
ormyproxy.mydomain.com
proxy.port
- The port number of the proxy server (default: 80)proxy.username
- The username for authentication if necessaryproxy.password
- The password for authentication if necessaryproxy.nonProxyHosts
- A|
-separated list of hosts that should be accessed without going through the proxy. (default:localhost|127.*|[::1]
)
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:
tws.storage.cleanup.enabled = true
- sets whether or not to enable automatic analysis cleanup [default: true]tws.storage.cleanup.max-total-analyses = 100
- sets the maximum number of orchestrated analyses to keep; further analyses will cause the oldest to be deleted [default: 100]tws.storage.cleanup.max-analyses-per-project = 5
- sets the maximum number of orchestrated analyses to keep per-project; further analyses will cause the oldest in the project to be deleted [default: 5]
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.
azure.auto-create-delay
[default: 50] - sets the delay (in ms) between subsequent work item creation requests made during an auto create jobjira.auto-create-delay
[default: 50 - sets the delay (in ms) between subsequent issue creation requests made during an auto create jobservicenow.request-delay
[default: 750] - - sets the delay (in ms) between subsequent requests made during auto create jobs and bulk update jobs
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:
mltriage.enable-periodic-retrain
[default: true] - enables Code Dx to periodically train a prediction modelmltriage.model-train-time
[default: 01:45:00] - the time at which Code Dx will check if the threshold set in mltriage.retrain-threshold has been met, and if it has, train a prediction model.