Configuration File

In your application's repository, you can include a file named ngsast.yaml that contains configuration information for how you want ShiftLeft CORE's NG SAST to analyze your code.

Within the ngsast.yaml configuration file, you can define:

  • A default configuration to be used during the analysis of the artifact
  • A custom configuration to be used for the analysis of the specific artifact
  • Configurations that are not typically available via sl
  • Your analysis configuration once and save for future use instead of providing parameters before each code analysis
  • Modification rules that allow you match findings and change its attributes (e.g., severity or CVSS score)

Adding a Configuration File

To use a configuration file, you will need to:

  1. Create a configuration file
  2. Modify your configuration file
  3. Ensure that your configuration file is in the root folder of your application's repository; NG SAST will automatically look for an ngsast.yaml file in this location and load the included options if it finds a file

You can generate a sample configuration file by running the following:

sl ngsast default

Once ShiftLeft generates the necessary configuration file for you, you can edit to it reflect your preferences for how the code analysis runs. Then, move the ngsast.yaml file to the root folder of your app repository.

Working with the Configuration File

The following is a sample of what a configuration file might look like:

ngsast:
- app:
name: helloshiftleft
policy: io.shiftleft/helloshiftleft
language: JAVA
- app:
name: helloshiftleft-js
additional-findings:
- hsl-js-secrets
- insights
language: JAVASCRIPT
- default:
policy: io.shiftleft/defaultWithDict
additional-findings:
hsl-js-secrets:
entropy: 0.5
name: secrets
include:
- "**/*.properties"
- src/**
exclude:
- src/test/**
insights:

The config file is divided into two sections: ngsast and additional-findings. Only the ngsast parameter is required; you can provide additional-findings parameters to customize your code analysis further using features designed to return additional findings (e.g., identifying Insights or Secrets in your code).

In the example above, the ngsast portion of the file contains configuration information for two applications: helloshiftleft and helloshiftleft-js. There is also a default section, which provides configuration information when analyzing applications that aren't explicitly named.

For the application named helloshiftleft, the configuration file states that its analysis should use the io.shiftleft/helloshiftleft policy and that the application is written in Java.

However, for the application helloshiftleft-js, the configuration file specifies that the analysis should be run with slightly different parameters. More specifically, the application is written in JavaScript and while running the analysis, ShiftLeft should look to a custom additional-findings configuration with the custom ID of hsl-js-secrets. The configuration for helloshiftleft-js also requires additional findings analysis - insights - but with a default configuration (insights is not a custom ID).

The specifics of hsl-js-secrets are defined at the bottom of the config file; more specifically, the analysis should include looking for hard-coded credentials only in .properties files and files in src directory without files in src/test subdirectory, and using an entropy (or sensitivity) level of 0.5.

Parameters

Different sections of the configuration file accept different parameters for defining how the code analysis should run.

NGSAST Parameters

The following is a list of parameters you can include in the ngsast section of your configuration file.

ParameterDescription
nameThe unique name of the application. Required for the app parameter; disallowed for the default parameter
languageOptional. The language of the application. Accepted values: JAVA, CSHARP, JAVASCRIPT, GO
policyOptional. The custom policy to use during analysis. Default: io.shiftleft/defaultWithDict
additional-findingsOptional. The additional analyses to be run in NG SAST. Accepted value: secrets or the custom ID (as defined in the additional-findings section of the config file)

Additional NGSAST Parameters

The following is a list of parameters you can include in your additional-findings section.

ParameterDescription
secretsThe default configuration for analyzing for secrets
custom-idA default configuration with a name of your choice, eg., hsl-js-secrets, for one of the above analysis modes. Requires a sub-parameter name with accepted value secrets

Secrets Parameters

The following is a list of parameters you can include in the secrets portion under additional-findings.

ParameterDescription
entropyOptional. Entropy level to be used during the hard-coded credentials analysis. The accepted value is between 0 and 1 (inclusive). Default: 0.0
obfuscateOptional. A Boolean parameter indicating whether the literals returned in the results should be obfuscated. Default: false
nameThe name of the analysis and the value to be provided in place of custom_id. If you include the configuration for hard-coded credentials, this parameter is not optional and must be secrets
includeOptional. A list of paths that you want included during secrets detection. Accepts wildcards; use * to search the provided directory, and use ** to search the provided directory and its subdirectories
excludeOptional. A list of paths that you want excluded during secrets detection. Accepts wildcards; use * to search the provided directory, and use ** to search the provided directory and its subdirectories

Currently, insights do not allow for further customization.

Modifying the Severity of Findings after Code Analysis

You can modify the severity of findings after analysis using modification rules. Modification rules match findings and change attributes of the findings like severity or CVSS score.

note

Only ShiftLeft users with admin privileges may modify the severity of findings after analysis.

Modification rules match findings using filters that consider attributes like:

  • Finding type (e.g., vuln, secret, insight)
  • Category (e.g., XSS, SQL Injection)
  • Severity (e.g., critical, moderate, info)

To create modification rules:

  1. Add a section to your configuration file called finding_modifications
  2. Define individual modification rules with unique names of your choosing in the finding_modifications section.
  3. Indicate the specific modification rules to include on analysis of the app(s) by including the modify-findings parameter under app in the config file:
- app:
additional-findings:
- hsl-js-secrets
- insights
language: GO
modify-findings:
- my_modification_rule_name
name: tarpit_go

Modification Rules Example

To add a modification rule called my_modification_rule that changes all critical Sensitive Data Leaks to moderate severity and a CVSS score of 5.0, add the following to your configuration file:

finding-modifications:
my_modification_rule_name:
filter:
category:
- Sensitive Data Leak
id:
- 97
type:
- vuln
severity:
- info
- moderate
tags:
- key: cvss_score
value: 5
- key: severity
value: moderate
- key: some-custom-tag
value: todo

In all, a full configuration file with an app section calling a specific rule and a finding-modifications section that define the rules will look like this (be sure to update the parameteres used, such as the app name, which are helloshiftleft and tarpit_go in this example, as appropriate):

ngsast:
- app:
language: JAVA
name: helloshiftleft
policy: io.shiftleft/helloshiftleft
- app:
additional-findings:
- hsl-js-secrets
- insights
language: GO
modify-findings:
- my_modification_rule
name: tarpit_go
- default:
policy: io.shiftleft/defaultWithDict
finding-modifications:
my_modification_rule:
filter:
category:
- Sensitive Data Leak
id:
- 97
type:
- vuln
severity:
- info
- moderate
tags:
- key: cvss_score
value: 5
- key: severity
value: moderate
- key: some-custom-tag
value: todo

Applying Modification Rules

Once you've created your config file, ShiftLeft automatically updates your findings whenever you run sl analyze. This affects your current and subsequent scans only; it does not update prior scans.

Validating the Config File

NG SAST will validate the config file every time you attempt a code analysis if present. If the config file has syntax or semantic errors, the analysis will fail.

You can, at any time, manually validate the config file without running a code analysis by running the following:

sl ngsast validate

If the config file isn't located in the default location (i.e., you have a test file located elsewhere on your drive), you can use:

sl ngsast validate --config path/to/config/file.yaml