JavaScript/TypeScript

This article shows you how to analyze your applications written in JavaScript or TypeScript (including those that use the Angular, React.js, and Vue.js frameworks) using NG SAST. It assumes that you have already set up and authenticated with ShiftLeft.

note

ShiftLeft offers sample applications that you can use to run and test NG SAST. They also include functioning configuration files to demonstrate how you can leverage GitHub Actions to automate code analysis whenever you open a new Pull Request (PR).

• Angular
• JavaScript
• React
• Vue.js
• TypeScript

Requirements

You must have Node.js installed and added to the PATH variable of the machine on which NG SAST runs.

Before analyzing your application, please make sure that your code builds correctly with npm or yarn. However, applications should not be built before invoking ShiftLeft. ShiftLeft automatically installs the project dependencies and builds the project with custom settings that are more suitable for security analysis. Performing npm build or even npm install beforehand would prevent ShiftLeft from working correctly; as such, execute ShiftLeft against a fresh copy of your application.

SCA: To identify open-source vulnerabilities in JavaScript (Node.js) applications, ShiftLeft CORE requires one of the following package formats: package-lock.json, pnpm-lock.yaml, yarn.lock, Rush.js

If your repository doesn't include a package-lock.json or yarn.lock in the repository, then there are additional steps you must take to ensure that the SCA results you obtain are accurate.

Analyzing your JavaScript application

To analyze your JavaScript application, run:

# Ensure node_modules does not exist

sl analyze --app <name> --js [<path>]

Parameter	Description
--app <name>	The name of the application to be analyzed
--js	The flag identifying the application's language
<path>	The path to the application directory

See the CLI reference for additional sl analyze options.

SCA

To identify open-source vulnerabilities, ShiftLeft CORE automatically searches for build manifests in the project path you provided when running sl analyze. However, depending on how your project repo is structured, you may need to provide --oss-project-dir <project-path> so that ShiftLeft CORE can identify where your dependencies are located.

Additional parameters

The analysis accepts additional parameters after a double hyphen --.

For example, the following ignores minified JavaScript sources in the analysis and uses a custom package.json in the config sub-directory:

sl analyze --app Xyz --js /path/to/my/typescript-project -- --ignore-minified --package-json /path/to/my/typescript-project/config/package.json

Such parameters, if valid, are passed directly to the JavaScript plugin.

Parameter	Description
--package-json <path>	The custom path to package.json (by default, NG SAST looks for the file in the JavaScript project directory)
--output <value>	The CPG output file name (defaults to cpg.bin.zip if none provided)
--no-ts	Exclude TypeScript sources from the analysis (by default, NG SAST includes Typescript sources)
--no-babel	Exclude Babel sources in the analysis (by default, NG SAST includes Babel sources)
--include-minified	Include minified Javascript sources (e.g., filenames ending with -min.js or .min.js) in the analysis (by default, NG SAST excludes all such sources)
--include-tests	Include test files (typically required for sample vulnerable apps, such as OWASP Juice Shop)
--include-configs	Include configuration files (e.g., *.conf.js, *.config.js, *.json`). Usually required for OWASP juice shop and other vulnerable apps
--exclude <path-1>,<path-2>,...	Exclude the specified directories during code analysis; the path provided can be a full path or a relative path to the JavaScript project directory
--exclude-html	Exclude HTML files from the analysis
--exclude-regex <value>	A regex specifying the files to exclude during the analysis (the match is to the absolute file path), e.g., --exclude-regex ".*([-.])min\\.js" or `--exclude-regex ".*.(spec
--exclude-private-deps	Exclude private modules/dependencies in 'node_modules/' (defaults to false)
--optimize-dependencies	Optimize project dependencies during transpilation (i.e., reduce dependencies to the minimal set that's required to transpile the JS/TS code). May result in faster execution times. Defaults to false
--private-deps-ns <dep1>,<dep2>,...	Additional private dependencies you would like to be analyzed from node_modules

Tagging results with your branch name

To include the branch name in your NG SAST results, allowing you to distinguish one set of results from another, add the following to your invocation of ShiftLeft:

sl analyze --tag branch=`git symbolic-ref --short HEAD`

If you're working in a GitHub environment (e.g., GitHub Actions), you can also use --tag branch=${{ github.head_ref }} to populate your branch name.

If you don't provide a branch name, but ShiftLeft detects one available in your environment, it will use that name.

Scanning Node.js applications

If your Node.js application either:

1. Uses v8.x.x or
2. Doesn't include package-lock.json or yarn.lock in the repository

Then there are a couple of additional steps you must take when analyzing your application to ensure that the SCA results you obtain are accurate.

1. Run npm install and remove node_modules:

   npm install

   rm -rf node_modules

2. If present, you should also remove any directory that's produced by the build that should not be included in the analysis (e.g., build or dist directories):

   rm -rf frontend/dist frontend/node_modules dist build

Scanning Vue.js applications

When analyzing a Vue.js application, you must include a vue.config.js file in the root of your repository, otherwise NG SAST will return no results:

module.exports = {

configureWebpack: (config) => {

config.devtool = 'source-map'

},

};

You can see how this file is used in the sample Vue.js repo we offer.

Troubleshooting

If you have any issues scanning your project, please see our general troubleshooting page, as well as our JavaScript-specific suggestions that follow.

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