JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

CodeSonar® 9.2p0 CONFIDENTIAL CodeSecure Inc
Third-Party External

Including JavaScript and TypeScript Components in a CodeSonar Project

This page describes how to extend your CodeSonar-facing build so that your CodeSonar project includes:

Overview

This page describes how to extend your CodeSonar-facing build so that your CodeSonar project includes:

Incorporating JavaScript and TypeScript components follows the standard process for including a tier 3 component. The specializations to that process are summarized in the following table. For detailed instructions, see Including JavaScript and TypeScript Components In Your CodeSonar project, below. We also provide an example Makefile.

Language Tools You will need a Node.js installation.
Third-Party Analyzer ESLint and SARIF formatter for ESLint
If you are analyzing TypeScript code, you will also need typescript-eslint.
Third-Party Analysis Step You do not need to explicitly invoke ESLint: it is invoked in the codesonar es_scan.py subcommand.
Extend CodeSonar-facing Build Invoke codesonar es_scan.py on your JavaScript and TypeScript source files. This will analyze the files with ESLint, then add the SARIF results and source files to the CodeSonar project.

Including JavaScript and TypeScript Components In Your CodeSonar Project

Incorporating JavaScript and TypeScript components follows the standard process for including a tier 3 component.

  1. Install any required language tools, such as compilers.
    Make sure you have a Node.js installation.
    If you are installing now, make sure you install the same version that is used in the rest of your organization.
  2. Install the third-party analyzer.
    If you haven't already done so, install ESLint.
    If you are analyzing TypeScript code, also install TypeScript and typescript-eslint.
  3. Install the third-party SARIF converter, if needed.
    If you haven't already done so, install SARIF formatter for ESLint(@microsoft/eslint-formatter-sarif).
  4. Extend the regular build to invoke the third-party analyzer (and SARIF converter, if needed).
    You do not need a separate analysis step.
  5. Extend the CodeSonar-facing build.
    Extend your CodeSonar-facing build by adding one or more invocations of codesonar es_scan.py.
    All the JavaScript and TypeScript source files must be present before codesonar es_scan.py is invoked. Different build systems have different mechanisms for specifying this requirement. For example, you might be able to specify that the CodeSonar-facing build depends on the JavaScript/TypeScript files, or that the CodeSonar-facing build can only take place if the regular build has already occurred.

    If you have not already set up a CodeSonar-facing build for your regular software project, you will need to create one.

  6. Perform the CodeSonar build/analysis, observing the entire execution of your CodeSonar-facing build.

Diagram: including JavaScript and TypeScript components in a CodeSonar project

The following diagram illustrates the extended software build described above, and its interactions with the CodeSonar build/analysis.

Diagram illustrating the procedure described on this page: extend a build that executes ESLint on JavaScript/TypeScript source files into a CodeSonar-facing build by adding invocations of 'codesonar import_sarif.py' to import the SARIF output from ESLint and corresponding JavaScript/TypeScript source files.

Note

In this section (and throughout this manual), $CSONAR indicates the CodeSonar installation directory.

Warning Classes

When a SARIF file is imported into a CodeSonar project, the SARIF importer determines an associated warning class for each rule object in the SARIF rules, creating this warning class if it does not already exist.

The SARIF importer has special handling for warning classes derived from SARIF produced by ESLint. For more information, see:

codesonar es_scan.py

To analyze JavaScript and TypeScript source files with ESLint and then add the source files and analysis results to a project, CodeSonar observes the execution of a command that incorporates one or more invocations of codesonar es_scan.py.

codesonar es_scan.py file_or_dir1 [file_or_dir2 ...] [-C rundir] [-directory rundir] \
[-include-sources file_pat] [-exclude-sources file_pat] [-eslint-cmd cmd] \
[-ext replacement_ext_list] [-ext+ additional_ext_list] [-X+eslint_options_list] \
[-sarif-output sarif_fname] [-source-max-bytes num] [@infile]

where:

file_or_dir1 [file_or_dir2 ...] Each file_or_diri specifies a file or directory path relative to the rundir directory specified with -C rundir or -directory rundir, or relative to the current working directory if no rundir is specified.
  • To analyze the JavaScript and TypeScript source files in the directory tree under rundir, specify . (dot).
  • To analyze the JavaScript and TypeScript source files in a specific directory, specify the directory path relative to rundir.
  • To analyze an individual JavaScript or TypeScript source file, specify the file path relative to rundir.
The codesonar es_scan.py command must include at least one file_or_diri argument.
[-C rundir]
[-directory rundir] 		ESLint will be run in rundir. If -C/-directory is not specified, ESLint will be run in the current working directory.

Any relative file_or_diri arguments are interpreted with respect to rundir. For example:

  • codesonar es_scan.py .
    Analyze all JavaScript and TypeScript source files located anywhere in the directory tree under the current working directory.
  • codesonar es_scan.py path/to/mymodule
    Analyze all JavaScript and TypeScript source files located anywhere in the directory tree under path/to/mymodule.
  • codesonar es_scan.py path/to/myfile.js
    Analyze file path/to/myfile.js.
[-include-sources file_pat]
[-exclude-sources file_pat] 		By default JavaScript and TypeScript source files specified with file_or_diri arguments will be analyzed with ESLint and imported into the CodeSonar project.
Use -include-sources and -exclude-sources to adjust this set by adding or removing files.

file_pat is a recursive glob pattern representing a source file path. It matches all files whose file path matches file_pat.

When a single codesonar es_scan.py invocation contains a combination of -include-sources and -exclude-sources options, the set of analyzed and imported files is determined by applying the corresponding inclusions and exclusions in the order in which they appear on the command line.

Note:

  • Your shell may be configured to expand patterns into file and directory names. If so, make sure you quote the file_pat appropriately to indicate that the shell should pass it through to codesonar es_scan.py. In most cases, this means using single quotes ('); for Windows cmd, use double quotes (").
[-eslint-cmd cmd] Specifies that CodeSonar should invoke ESLint with cmd:
cmd [... options determined by codesonar es_scan.py]
If this option is not specified, CodeSonar will invoke ESLint as follows.
Windows:
npx.cmd eslint [... options determined by codesonar es_scan.py]
otherwise:
npx eslint [... options determined by codesonar es_scan.py]
[-ext replacement_ext_list]
[-ext+ additional_ext_list] 		Adjust the set of file extensions used to identify source files for importing into the CodeSonar analysis.
When specifying multiple extensions in replacement_ext_list or additional_ext_list, use a comma (,) for separation.

For codesonar es_scan.py, source files are recognized by their file extensions as follows.

The default set of recognized file extensions is { .js, .ts, .cjs, .cts, .jsx, .mjs, .mts, .tsx }.

  • If neither -ext nor -ext+ is specified, the default set is used.
  • Otherwise, the default set is adjusted by applying the specified -ext and -ext+ options in order of occurrence.
    • When [-ext replacement_ext_list] is encountered, the current set is replaced by a set containing the elements in replacement_ext_list.
    • When [-ext+ additional_ext_list] is encountered, the current set is extended by adding all elements in additional_ext_list.
For a directory specified with a positional file_or_diri argument, CodeSonar will import all files that:
  • are located in the directory tree under the specified directory, and
  • have recognized extensions, and
  • have not been excluded from the analysis and import with -exclude-sources.
For a source file specified with a positional file_or_diri argument or with -include-sources, CodeSonar will import that file unless it has been excluded from the analysis and import with -exclude-sources.
[-X+eslint_options_list] The +-separated list of options and values in eslint_options_list are passed to the ESLint invocation.
  • You can specify multiple ESLint options in a single eslint_options_list; you can also specify -X multiple times in a single codesonar es_scan.py invocation.
For example, the following are equivalent: both specify that ESLint must be invoked with --no-inline-config and --cache.
codesonar es_scan.py -X+--no-inline-config+--cache [... remaining es_scan.py options]
codesonar es_scan.py --X+--no-inline-config -X+--cache [... remaining es_scan.py options]
[-sarif-output sarif_fname] Specifies that the SARIF output from ESLint should be written to file sarif_fname.
The primary use case for this option is in projects for which you wish to retain the SARIF results after the CodeSonar build/analysis has finished.

If -sarif-output sarif_fname is not specified, codesonar es_scan.py will use a temporary file for the SARIF output.
[-source-max-bytes num] Specifies a maximum size of num bytes for imported JavaScript and TypeScript source files: files larger than this maximum size will be ignored by the importer.
If -source-max-bytes is not specified, the importer will ignore files larger than 500KB.
[@infile] infile is a text file containing a list of build option entries to be added to the codesonar es_scan.py command line.
  • The entries must be separated by one or more whitespace characters (including newline).
  • The entries will be added to the command line at the location where the @infile argument occurred, in the order in which they appear in infile.

Importing JavaScript and TypeScript source files with codesonar es_scan.py

The codesonar es_scan.py subcommand imports JavaScript and Typescript source files into the CodeSonar project using the same mechanism as codesonar import_sarif.py, because CodeSonar does not have a full front end for these languages.

There are several consequences when files are directly imported with codesonar import_sarif.py.

Example Makefile

An example Makefile for a JavaScript and TypeScript project is shown below. We also provide an example Makefile for a mixed-language project that has a JavaScript or TypeScript component: see Including Tier 3 Components in a CodeSonar Project: Example Makefile

Note: This Makefile assumes that the JavaScript or TypeScript module has already been initialized and ESLint has already been configured for the module.

The Makefile illustrates a case where the JavaScript/TypeScript component is not compiled. The all dependencies are thus all the .js and .ts source files in the component, and there are no binary targets. If the regular build included a compilation step, the CodeSonar-facing build would be the same as shown here.

JSTS_MODULE=$(SRCDIR)/jsts_component

.PHONY: all clean csonar_facing

all: $(JSTS_MODULE)/index.js $(JSTS_MODULE)/ts_file.ts

# Invoke codesonar es_scan.py to analyze our JavaScript and TypeScript
# source files with ESLint, then import the analysis results and source files into
# the CodeSonar project.
csonar_facing: $(JSTS_MODULE)/index.js $(JSTS_MODULE)/ts_file.ts
	"$(CSONAR)"/codesonar/bin/codesonar es_scan.py index.js ts_file.ts -C $(JSTS_MODULE)

clean:

Try the Example Makefile

We have provided a minimal sample project so you can experiment with the example Makefile.

  1. Sign in to a machine where CodeSonar is installed.
  2. Select or create a working directory. The working directory location must be outside both your CodeSonar installation directory and your hub directory.
  3. If Node.js is not installed, install it now.
  4. Save the example files to the working directory (right-click on the link and select Save Target As... or equivalent).
  5. cd to the working directory.
  6. Rename the Makefile (this simplifies the CodeSonar analysis command later).
    mv Makefile.JavaScript_TypeScript.txt Makefile
  7. Extract the example project.
    gzip -cd jsts_component.tar.gz | tar xf -
    If you do not have gzip and tar, use your regular system tools to extract the contents of jsts_component.tar.gz into ./jsts_component.
  8. Set up the example project so that it is ready for analysis.
    1. Change to the ./jsts_component directory.
      cd jsts_component
    2. Install the required analysis and formatting tools: ESLint, TypeScript, typescript-eslint, SARIF formatter for ESLint (@microsoft/eslint-formatter-sarif).
      npm install --save-dev eslint typescript typescript-eslint @microsoft/eslint-formatter-sarif
    3. Specify that the project should be treated as a module.
      npm pkg set type="module";
      This is required for consistency with the example ESLint configuration file (jsts_component/eslint.config.js).
    4. Change back to the working directory.
      cd ..
  9. Edit Makefile to add a settings for SRCDIR at the top (above the JSTS_MODULE setting). If CSONAR isn't defined in your environment, set that as well. 
    SRCDIR=.
    or 
    SRCDIR=.
CSONAR=path/to/your/codesonar/installation
# on Windows, typically CSONAR=C:\\Program Files\\CodeSecure\\CodeSonar
  10. Build and analyze the CodeSonar project. If your hub is at the default location, your command will be something like:
    codesonar analyze JS_TS_Example make csonar_facing
    For full codesonar analyze command details, see Command Line Build/Analysis.
  11. When the analysis finishes, view the Analysis page in the hub GUI.

Other Targets in the Example Makefile

The clean target has an empty recipe because codesonar es_scan.py cleans up its own intermediate files.

Related Links

 

To report problems with this documentation, please visit https://support.codesecure.com/.