This article includes troubleshooting steps you can use to identify and fix issues that may come up when using ShiftLeft CORE's NG SAST. The first section contains general tips applicable to most users; the remaining sections are language-specific.
General troubleshooting tips
sl check-environment to see if there are issues related to your environment (be sure to pass in your language-specific option).
Create an environment variable called
SHIFTLEFT_SHOW_HIDDEN and set it to
true to show the hidden flags supported by the ShiftLeft CLI.
sl analyze, you can include the
--cpg-output-dir flag to specify your CPG output directory. ShiftLeft will place the CPG in this directory after analysis.
You can get verbose logs for additional information by including the
--diagnostic flags when invoking
sl analyze (i.e.,
sl analyze --verbose --diagnostic).
For Windows Users
On Windows platforms, sl.exe doesn't auto-update. Please begin your code analysis or troubleshooting steps by checking your version:
Specifying Additional Arguments to
sl analyze Using the Double Hyphen
sl cli tool accepts standard arguments, such as
--verbose. Additionally, the CPG generator plugins accept additional arguments for each language. To specify these arguments, you must preference the additional arguments for a double hyphen (
Path Argument Positioning
The path argument used with
sl analyze should be the last value. If the path is followed by any other argument,
sl analyze will fail.
The following is an example for an incorrect invocation:
The correct invocation is:
We require Java 1.8 for code analysis. If Java or JRE is unavailable, the ShiftLeft CLI will automatically download and install JRE 1.8 to the $HOME/.shiftleft directory. You can confirm the JRE download in the verbose log:
Analysis time outs
If your analysis times out, there are two things to try:
- Adjusting the memory allocated to the scan
- Tuning your whitelist or blacklist
Adjusting the memory allocated to the scan
First, set the
SL_CPG_OPTS environment variable as follows:
-Xmx to the max RAM available on the workstation running ShiftLeft. For large projects (e.g., those with over 500,000 lines of code), we ask for a minimum of 16 GB RAM.
After you set
SL_CPG_OPTS, re-run the analysis and check the verbose log to make sure that the change is taking effect (ignore duplicate
Both the libplugin analyze and generate steps should have memory-related settings.
At the end of the log, you can also see memory usage information; in the example below, the analysis used 24 GB RAM:
Tuning your whitelist or blacklist
If setting the
SL_CPG_OPTS environment variable isn't fixing the problem, then you can tune the project's whitelist and blacklist.
Building a CPG is a resource-intensive process. ShiftLeft can analyze many frameworks and libraries, but it helps to focus on specific frameworks or namespaces. For example, few are interested in viewing static analysis reports for open source (OSS) libraries; thus, OSS libraries are pre-annotated and blacklisted by default.
However, your app may use libraries that haven't yet been blacklisted. For example, you might be using internal libraries that are common to your applications. Instead of reporting the same vulnerabilities in these libraries across all of your applications, it may make sense to blacklist these so that your findings list is more focused and actionable for your developers.
You can see if your project will benefit from whitelisting by looking for DEBUG Not replacing in your logs:
If you see 500+ occurrences of such a message, your project is a good candidate.
To manipulate your whitelist/blacklist, please contact ShiftLeft, making sure to provide:
- Your org id
- Your app name
- Your verbose logs
ShiftLeft will inform you as to the amount of time required for this work.
VCS Prefix Corrections
For Java apps, you must modify the VCS URL that NG SAST sets by default. To do this, include the following flag with
Similarly, for Scala projects, use
Please note that NG SAST currently cannot support multi-module repos where the
src directory contains multiple separate modules. In such cases, we recommend using the API and applying a transformation script to fix the source code path.
- We require Windows for scanning .NET Framework apps.
- We support Windows and Linux for .NET Core 3.1 apps (we support .NET Core 2.1 apps on a best-effort basis) with the
- We support Windows and Linux for .NET 5 apps with the
.NET Core vs .NET
.NET 5.0 is the major release following .NET Core 3.1 (note the slight name change and the version number shift -- see Microsoft's announcement for more information).
We suggest migrating your applications to .NET 5 as soon as possible. Once you've migrated, please make sure that you have the .NET 5 Runtime installed to ensure that ShiftLeft works as expected.
If you haven't migrated, you can continue to use
--dotnet-core only if you have .NET Core 3.1 Runtime installed, but not the .NET 5 Runtime.
The workstation on which ShiftLeft runs should have MSBuild and the appropriate .NET SDK; it should also be able to build your project/solution.
You can verify this by invoking:
You do not need to build your project before invoking
sl analyze; ShiftLeft will perform a build before code analysis, so you only need to run the .NET or MSBuild restore step beforehand:
Do not proceed with
sl analyze until this step passes.
Please note that the build step performed as part of code analysis may be slower for the following reasons:
- Your project uses a mix of .NET Core versions or combines the usage of the .NET Framework with .NET Core
- Your project uses private dependencies from NuGet servers (fetching dependencies adds to the time required)
- Your project uses special pre- or post-build events to copy .dll files or artifacts
Which files to analyze
We recommend analyzing the .csproj files for speed and more robust results. Be sure to use the following two flags when invoking
If you opt to analyze your .sln files, be sure to omit both
Artifact and dll not found errors
If you see the errors that look like this:
This means that you need to pass additional build parameters to
sl analyze to ensure that the dependent projects can be built successfully. Typically, the developer should be able to provide the necessary build parameters, but we've found that the following five flags to be helpful:
If the project fails to rebuild after three attempts, even with the addition of build flags, please contact Support for further assistance.
You can find the logs generated by ShiftLeft in the Windows temp directory.
Excluding files / directories
While ShiftLeft ignores certain directories, such as test and node_modules, by default, you can exclude additional folders (e.g., minified files).
If you're using a private npm registry, please make sure that you create and include a .npmrc file with your credentials before invoking
If you're using private modules, please make sure that your app is configured properly so that yarn/npm doesn't attempt to install them from the public registry (this will cause the code analysis to fail). The following is an example of how an app is attempting to get a private module from the public yarn registry, causing an HTTP 404 error:
To fix authentication errors:
- Create a user in your npm server for ShiftLeft; this user should either have a password or an authentication token
- Store this user's credentials in a .npmrc file before invoking ShiftLeft.
Here is a sample of what you might include in your .npmrc file:
If you see build failures, make sure that npm or yarn install works correctly before invoking
sl analyze. Fix any errors that result; for example, if you see the following:
The application requires Node.js v12, so add a build step similar to the following:
Errors with the TypeScript Compiler
You can ignore such errors; tsc can throw errors even for mundane coding issues, none of which would affect a security analysis tool. There may be many such messages in the verbose logs, but you can ignore these as they are merely debugging indicators.
Incorrect VCS link for TypeScript projects
If your VCS link ends incorrectly (that is, it uses
.js instead of
.tsx), you might see an HTTP 404 error. This typically happens if ShiftLeft was unable to generate sourcemaps correctly.
If this happens, please submit to ShiftLeft:
- The full verbose log
- Your CI configuration
No findings found
If you run a scan that results in no findings, collect the verbose logs and contact ShiftLeft for additional assistance.
Parsing errors in strict mode
You may see parsing errors due to:
- Use of strict mode
- Unsupported syntaxes, such as spread objects or dynamic imports
yarn parsing errors with TypeScript projects
You should run
sl analyze from the root directory that contains the yarn.lock file. If you perform the analysis from a different directory, NG SAST defaults to npm, which may not work correctly for yarn projects (this is a limitation we will address in the future).
Most of the errors seen regarding analysis of Go applications involve an environment that wasn't set up correctly.
First, try building the app. If the application uses a Makefile, run:
For applications that involve complex build process or Docker, review the Dockerfile to get ideas or seek help from the Go developer.
When the Go application includes private modules that are available in a non GitHub environment, such as GitLab or AWS CodeCommit, ensure the authentication keys are set up and the application builds cleanly before performing code analysis.
Before running analysis on your Python application, make sure to run
If you receive the following error when analyzing your Python application, please make sure that you have Python v3.8 installed (regardless of which version of Python you app uses):
Module import errors
Check if running
pip install for your application was successful.
If using a private registry, such as Sonatype or JFrog, ensure the
.pypirc file contains the authentication token required to install all the dependencies.
Some applications might have a common directory that is referred to by multiple packages. To provide this additional module search path for the analysis:
Some applications have development and test scripts that contain errors preventing security analysis. To omit specific paths from the analysis:
The paths are separated by spaces.
To ignore specific directory by name from the analysis:
To enable detailed logging of the analysis in case of troubleshooting:
The detailed log file can then be found in the user's temporary directory.