Scanning the Codebase (Server Scans)

After a project’s codebase has been uploaded to (or synchronized to) the Scan Server and the appropriate scan profile is selected, the codebase is ready to be scanned. To perform the scan, you must have proper permissions (see Code Insight User Roles and Permissions), and the Scan Server must be running—that is, the Tomcat server (installed on the same instance as the Scan Server) must be running.

The following instructions describe how to start a server scan on your codebase. (For information about the differences between server and remotes scans, refer to About Code Insight Scans.)

Note:When using a MySQL database, Code Insight is certified to scan a codebase up to 35 GB in size and containing no more than 700,000 files. When using a SQL Server database, Code Insight is certified to scan a codebase up to 15 GB and containing no more than 300,000 files. Also see Codebase Size Limitations for Uploads and Scans.

To start the scan, do the following:

Navigate to the Summary tab for the project that you want to scan. (If necessary, see Opening the Project Summary Tab).

Click the Start Scan button (or the link in Scan Server Status) to trigger the scan. The scan is queued and runs in the background. You can monitor the scan’s progress by clicking the “here” link in Past Server Scans to obtain information about scheduled, active, and past scans on the project. You can also monitor the scan in the Jobs queue (see Monitoring the Code Insight Jobs Queue). Note the following:

•

If a scan is running on another project, your scan will automatically start based on queue order. Additionally, if the Scan Server is temporarily inactive, the scan will automatically start based on queue order once the server is running again.

•

The project currently open can have only one scan in queue or in progress at a time. If you attempt to schedule a scan when your project already has a scan queued or running, the Start Scan button will be disabled until the scan completes. For more reasons for Start Scan button disablement and the actions you can take, see Actions to Take When the Start Scan Button is Disabled.

•

If a report generation is currently in queue or in progress for the project, the scan is not triggered. Instead, a pop-up error message is displayed, explaining that you must wait until the report generation has completed before repeating this step to attempt to trigger the scan again.

Information about the scan’s progress appears in the Scan Server Status section on the Summary tab.

When the scan completes, Last Server Scan will display one of the following messages:

•

Completed—The scan succeeded with no warnings during scan or analysis. This message appears on the screen in green.

•

Completed with warnings—The scan succeeded but the analysis produced warnings. For more information, check the scanEngineDetail log for the Scan Server.

•

Failed—The scan failed. This message appears on the screen in red. For more information, see Scan Failure Reasons and Troubleshooting Measures.

For an overall understanding of the scan results, see Overview of Scan Results.

Do any of the following:

•

Manage the project. For example, you can assign users to project analyzer or reviewer roles, define the project’s scan settings, configure an automated review and remediation workflow, configure a connection to a remote data source such as Perforce or Jira, and more. See Configuring Project Settings for details.

•

Analyze the scan results, as described in Analyzing Scan Results in a Project.

•

Generate the following standard reports and any applicable custom reports that have been added:

•

Project Report

•

Audit Report

•

Notices Report

Actions to Take When the Start Scan Button is Disabled

The Start Scan button on the Summary tab for a project is disabled under the following two conditions.

•

The project that you are attempting to scan is already in the scan queue or is currently being scanned— Check the Scan Server Status field on the Summary tab to confirm the “Scan scheduled” or “Project being scanned” status. Then wait until the scan completes before attempting to schedule another on the same project.

Note:Under certain circumstances, the Scan Server Status field might not update quickly enough to reflect the “Scan scheduled” or “Project being scanned” status. However, if a scan on the current project is indeed already in queue or running, an attempt to click the field’s “here” link to schedule a scan will result in an error message, stating that you cannot start another scan on the project. For your reference, the message also provides the task ID for the currently queued or running scan. (This ID can be used with the Get Scan Status API to check the scan status outside of the UI when necessary.)

•

The Scan Server associated with the project is disabled for scanning—If no scan is scheduled or running for the current project, check with the Code Insight System Administrator to determine the status of the Scan Server. If it is disabled, you will need to create a new project for the codebase and associate it with an enabled Scan Server. (The Start Scan button and the “here” link in the Scan Server Status field should still be enabled if the Scan Server is only temporarily inactive.)

Scan Failure Reasons and Troubleshooting Measures

The following lists possible causes and troubleshooting help for the failures of a server scan.

Scan Failure Causes and Troubleshooting Measures

Scan Failure Cause

Troubleshooting Measures

Scan server is not accessible

Verify that the correct hostname and port for the selected Scan Server have been identified in Code Insight.

Scan server is unable to access or read the CL files

Verify that the correct Compliance Library (CL) path has been identified for the Scan Server.

Scan server ran out of memory

Ensure that the JVM heap (memory) size is adequate for running the Scan Server. (Recommended JVM heap sizes are listed in the Code Insight Installation and Configuration Guide.)

Codebase file(s) are not accessible and cannot be read

Verify (and adjust if necessary) the codebase file permissions.

Codebase file(s) are encrypted and cannot be read

Attempt to open the codebase files in 7-zip or winzip. This application might provide a clearer description of the error than the scan process can.

Codebase file(s) are corrupted and cannot be read

Attempt to open the files in an external text editor. The editor might provide a clearer description of the error than the scan process can.

Codebase file(s) contain unparseable characters

This type of error is rare. Should it occur, verify that your database character set and collation settings are correct and that they match the requirements listed in the Code Insight Installation and Configuration Guide.

Indexing of the scanned codebase files and results failed

To help you identify the problem and troubleshoot, review the scanEngineDetail log for the Scan Server.

Unable to communicate with CodeAware

This scan failure can occur when both of these conditions exist:

•

Code Insight is running in a proxy-enabled environment.

•

The Scan Server is running under its fully qualified domain name.

The Scan Server must call Code Insight Automated Analysis to analyze the codebase files. If the time required by Automated Analysis to analyze files exceeds the proxy server “read timeout” limit, the scan fails (even though Automated Analysis might still finish).

Try either of these methods to resolve this scan-failure issue:

•

If the Core Server and Scan Server are running on the same instance, change the Scan Server hostname to localhost. (If you are running Code Insight in SSL mode, ensure that the SSL certificates accommodate the hostname change.)

•

If the Core Server and Scan Server are not running on the same instance, try excluding the Scan Server from the proxy by adding its hostname to the http.nonProxyHosts property in the proxy details.

The Code Insight Installation and Configuration Guide provides information about configuring Code Insight to run in SSL mode or in a proxy-enabled environment.

No alternative DNS name found that matches localhost

This scan failure occurs when all these conditions exist:

•

Code Insight is running in a proxy-enabled environment.

•

The Core Server and Scan Server are installed on separate instances.

•

Both servers are configured for SSL.

Try these methods to resolve the scan-failure issue:

•

Ensure that the Secure Site SSL certificate on each instance has been properly configured.

•

Try excluding the Scan Server from the proxy by adding its hostname to the http.nonProxyHosts property in the proxy details.

The Code Insight Installation and Configuration Guide provides information about configuring Code Insight to run in SSL mode or in a proxy-enabled environment.

Unable to find valid certificate

This scan failure can occur when both of these conditions exist:

•

The Core Server and Scan Server are installed on separate instances.

•

Both servers are configured for SSL.

The scan fails when the Core Server is unable to communicate with the Scan Server.

Ensure that the Secure Site SSL certificate on each instance is valid and has been properly imported. (The Code Insight Installation and Configuration Guide provides information about procuring and importing these certificates as part of the SSL configuration for Code Insight.)