Troubleshooting

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

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

When running 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 --verbose and/or --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:

sl.exe --version

Specifying Additional Arguments to sl analyze Using the Double Hyphen

The sl cli tool accepts standard arguments, such as --app and --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 (--).

For example, you can chooose to ignore test and docs directories during analysis of a JavaScript app. Notice how this is done:

sl analyze --app js-example --js --cpg . -- --exclude test,docs

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:

sl analyze --app js-example --js --cpg . --verbose

The correct invocation is:

sl analyze --verbose --app js-example --js --cpg .

Java

Java requirements

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:

[TRACE] Looking for prefix:(jre-) suffix:(.tar.gz)
[TRACE] removed 0 files
[TRACE] extracting /home/vsts/.shiftleft/jre172685618
[TRACE] extracting /home/vsts/.shiftleft/jre172685618/lib
[TRACE] extracting /home/vsts/.shiftleft/jre172685618/lib/resources.jar
[TRACE] extracting /home/vsts/.shiftleft/jre172685618/lib/logging.properties

Analysis time outs

If your analysis times out, there are two things to try:

  1. Adjusting the memory allocated to the scan
  2. Tuning your whitelist or blacklist

Adjusting the memory allocated to the scan

First, set the SL_CPG_OPTS environment variable as follows:

export SL_CPG_OPTS="-J-Xms2g -J-Xmx7g"

Set -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 -Xms values):

[TRACE] args [/home/vsts/.shiftleft/jre/bin/java -Xms256m -Xms2g -Xmx6g -jar /home/vsts/.shiftleft/libplugin-latest.jar analyze /tmp/shiftleft-638314335/libplugin-state524922089 --]
...
[TRACE] args [/home/vsts/.shiftleft/jre/bin/java -Xms256m -Xms2g -Xmx6g -jar /home/vsts/.shiftleft/libplugin-latest.jar generate /tmp/shiftleft-638314335/libplugin-state524922089 --]

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:

2020-12-21 15:19:19.793 [java2cpg-jvm-monitor] DEBUG Memory used/committed (MB): 18287 / 22905
2020-12-21 15:19:24.795 [java2cpg-jvm-monitor] DEBUG Memory used/committed (MB): 19912 / 22905
2020-12-21 15:19:29.861 [java2cpg-jvm-monitor] DEBUG Memory used/committed (MB): 2190 / 23290
2020-12-21 15:19:34.864 [java2cpg-jvm-monitor] DEBUG Memory used/committed (MB): 3299 / 23290
2020-12-21 15:19:39.866 [java2cpg-jvm-monitor] DEBUG Memory used/committed (MB): 4307 / 23290
2020-12-21 15:19:44.868 [java2cpg-jvm-monitor] DEBUG Memory used/committed (MB): 5508 / 23290
2020-12-21 15:19:49.875 [java2cpg-jvm-monitor] DEBUG Memory used/committed (MB): 6794 / 23290
2020-12-21 15:19:54.877 [java2cpg-jvm-monitor] DEBUG Memory used/committed (MB): 8082 / 23290
2020-12-21 15:19:59.879 [java2cpg-jvm-monitor] DEBUG Memory used/committed (MB): 10082 / 23290
2020-12-21 15:20:04.881 [java2cpg-jvm-monitor] DEBUG Memory used/committed (MB): 11237 / 23290

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:

2020-12-21 15:17:00.583 [main] DEBUG N2020-12-21 15:17:00.682 [main] DEBUG Not replacing: /tmp/java2cpg_class3799848926187001016/io/netty/util/concurrent/GlobalEventExecutor$1.class

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 sl analyze:

--vcs-prefix-correction "*=/src/main/java"

Similarly, for Scala projects, use

--vcs-prefix-correction "*=/src/main/scala"

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.

C#

OS requirements

  • 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 --dotnet-core parameter.
  • We support Windows and Linux for .NET 5 apps with the --dotnet parameter.

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

Build requirements

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:

dotnet build .sln
msbuild .sln

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:

dotnet restore .sln
nuget restore .sln // for .NET Framework

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 sl analyze:

-- --with-ProjectReference --ignore-tests

If you opt to analyze your .sln files, be sure to omit both --ignore-tests and --with-ProjectReference.

Artifact and dll not found errors

If you see the errors that look like this:

fail: Buildalyzer.Logging.EventProcessor[0]
System.IO.FileNotFoundException: Could not find file '/Users/prabhu/Downloads/EU-OutageStatusQuery/AzureFunctions/OutageStatusFunctions/OmsData.Peco/bin/Debug/netcoreapp3.1/bin/OmsData.Peco.dll'.
File name: '/Users/prabhu/Downloads/EU-OutageStatusQuery/AzureFunctions/OutageStatusFunctions/OmsData.Peco/bin/Debug/netcoreapp3.1/bin/OmsData.Peco.dll'
at Interop.ThrowExceptionForIoErrno(ErrorInfo errorInfo, String path, Boolean isDirectory, Func`2 errorRewriter)
at Microsoft.Win32.SafeHandles.SafeFileHandle.Open(String path, OpenFlags flags, Int32 mode)
at System.IO.FileStream.OpenHandle(FileMode mode, FileShare share, FileOptions options)

Or this

fail[39m[22m[49m: Buildalyzer.Logging.EventProcessor[0]
2021-02-03T18:39:57.5318095Z Metadata file '/src/src/app/Fool.Marthetron.Shared/bin/Release/netstandard2.1/Fool.Marthetron.Shared.dll' could not be found

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:

sl analyze --app app-name /
--verbose /
--csharp /
--dotnet "sln file name" /
-- /p:BuildProjectReferences="true" /
/p:SkipCompilerExecution="false" /
/p:CopyBuildOutputToOutputDirectory="true" /
/p:CopyOutputSymbolsToOutputDirectory="true" /
/p:SkipCopyBuildProduct="false"

If the project fails to rebuild after three attempts, even with the addition of build flags, please contact Support for further assistance.

Windows logs

You can find the logs generated by ShiftLeft in the Windows temp directory.

JavaScript / TypeScript

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

Authentication issues

If you're using a private npm registry, please make sure that you create and include a .npmrc file with your credentials before invoking sl analyze.

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:

error An unexpected error occurred: "https://registry.yarnpkg.com/yourModule/-/recess-5.11.0.tgz: Request failed \"404 Not Found\"".
info If you think this is a bug, please open a bug report with the information provided in "yarn-error.log".
info Visit https://yarnpkg.com/en/docs/cli/add for documentation about this command.

To fix authentication errors:

  1. Create a user in your npm server for ShiftLeft; this user should either have a password or an authentication token
  2. 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:

- name: NextGen Static Analysis
run: |
yarn config set cache-folder ~/.cache/yarn
yarn config set registry YOUR_REGISTRY_URL
yarn config set @yourName:registry YOUR_REGISTRY_URL
echo "//YOUR_REGISTRY_URL:_password=${{ secrets.PASSWORD }}" >> ~/.npmrc
echo "//YOUR_REGISTRY_URL:username=shiftleft" >> ~/.npmrc
echo "//YOUR_REGISTRY_URL:always-auth=true" >> ~/.npmrc
echo "//YOUR_REGISTRY_URL:email=YOUR_EMAIL_ADDRESS" >> ~/.npmrc

Build failures

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 engine "node" is incompatible with this module. Expected version "^12.14". Got "14.15.1"

The application requires Node.js v12, so add a build step similar to the following:

- uses: actions/setup-node@v2
with:
node-version: '12'

Errors with the TypeScript Compiler

When working with TypeScript projects (including those using Angular), you may encounter TypeScript compiler (tsc) errors. This tool is used to transpile TypeScript projects to JavaScript. Depending on how you invoke this tool, you may see syntax or style errors similar to the following:

node_modules/@types/react-router/node_modules/@types/react/index.d.ts(3033,13): error TS2717: Subsequent property declarations must have the same type. Property 'form' must be of type 'DetailedHTMLProps<FormHTMLAttributes<HTMLFormElement>, HTMLFormElement>', but here has type 'DetailedHTMLProps<FormHTMLAttributes<HTMLFormElement>, HTMLFormElement>'.
node_modules/@types/react-router/node_modules/@types/react/index.d.ts(3034,13): error TS2717: Subsequent property declarations must have the same type. Property 'h1' must be of type 'DetailedHTMLProps<HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>', but here has type 'DetailedHTMLProps<HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>'.

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

Go

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:

make build

Otherwise, use:

go build ./...

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.

Python

Before running analysis on your Python application, make sure to run pip install:

pip install -r requirements.txt

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

Error: analyze: python3.8 is required but not found | issuer=/go/src/github.com/ShiftLeftSecurity/go-services/cmd/sl/main.go:1824
analyze: python3.8 is required but not found
Error: Process completed with exit code 1.

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:

sl analyze --app <name> --python [<path>] -- --extra-sys-paths [<path>]

Some applications have development and test scripts that contain errors preventing security analysis. To omit specific paths from the analysis:

sl analyze --app <name> --python [<path>] -- --ignore-paths [<ignore_path_1>] [<ignore_path_2>]

The paths are separated by spaces.

To ignore specific directory by name from the analysis:

sl analyze --app <name> --python [<path>] -- --ignore-dir-names [<ignore_dir_name_1>] [<ignore_dir_name_2>]

To enable detailed logging of the analysis in case of troubleshooting:

sl analyze --verbose --app <name> --python [<path>] -- -l debug

The detailed log file can then be found in the user's temporary directory.