How to work with build rules v2 in your repo

You can include a configuration file named shiftleft.yml within your application's repository that contains build rules. ShiftLeft CORE's NG SAST can compare the results of its analyses against your build rules to determine if the build should fail.

With this file, you can:

  • Specify different build rules for each of your applications/repositories
  • Keep your build rules under version control
  • Edit your build rules without needing a separate tool that's outside your development workflow

Once you've created a build rules file, you can compare your analysis results against your newly defined rules using sl check-analysis:

# shiftleft.yml is the default name of your build rules file
sl check-analysis --v2 --app yourApp --config shiftleft.yml

The shiftleft.yml file

By default, the location of your configuration file in your repository should be ./shiftleft.yml. The file should be formatted as follows:

source:
branch: main
scan: 1 # provide either branch or scan, not both
build_rules:
- id: "Allow zero high SAST vulnerabilities" # is the build rule identifier
finding_types:
- vuln
- secret
cvss_31_severity_ratings:
- high
- critical
threshold: 0
options:
num_findings: 0 # return only 10 SAST findings
- id: "Allow zero reachable SCA vulnerabilities"
finding_types:
- oss_vuln
cvss_31_severity_ratings:
- critical
- high
threshold: 0
options:
reachable: true
num_findings: 10 # return 10 reachable SCA findings
- id: "Allow zero high severity container vulnerabilities"
finding_types:
- container
cvss_31_severity_ratings:
- critical
- high
threshold: 0
options:
num_findings: 10 # return 10 container findings
- id: "Example with mix and match findings"
type:
- SQL Injection
- Sensitive Data Leak
owasp_category:
- a1-injection
owasp_2021_category:
- a09-security-logging-and-monitoring-failures
cvss_31_severity_ratings:
- low
- medium
- high
- critical
threshold: 100

As shown in the above example, you can include multiple build rules in the file. Each build rule is assigned its own id, which acts as the identifier (and in your results, you'll see which build rule failed based on the identifier).

Parameters

The following sections describe the parameters accepted by the different parts of the shiftleft.yml file.

All build rule parameters are optional.

By default, running build rules checks all findings in the latest scan of an application. Use the --target flag to specify other scans:

  • --target scan.123 means the target of the build rules will be the scan with an ID of 123.
  • --target tag.branch=nifty-feature means the target of the build rules will be the last scan tagged as belonging to branch nifty-feature.

You can provide a source scan against which to compare the target scan. In this case, the build rules only apply to new findings in the target when compared to source:

  • Provide a source entry in your shiftleft.yml config file:

    source:
    scan: 123

    to compare the target against a specific scan, or provide

    source:
    branch: nifty-feature

    to compare with the previous scan in that branch (or the last scan in that branch if it's a different branch to the target).

    You could even provide

    source:
    scan: previous

    to compare the target scan to the previous scan irrespective of the branch.

If you'd like to provide these parameters via the CLI, you can provide a --source flag, similar to --target above: --source scan.123, --source tag.branch=nifty-feature, or --source scan.previous. ShiftLeft also accepts --branch=nifty-feature as a shorthand for --source=tag.branch=nifty-feature.

build_rules

The following are the parameters accepted under the build_rules section.

ParametersDescription
finding_typesThe specific type of finding to which the build rule should be applied. Accepted values: vuln, oss_vuln, container, secret, insight, extscan, package. You could also provide *, which returns all except package. If you omit this parameter, ShiftLeft defaults to returning only vulnerabilities.
idAn identifier (name) of your choice for the rule
optionsAllows for modification of a specific rule. Accepts reachable and num_findings. For reachable, provide true if you want to restrict the OSS vulnerabilities identified to only those that are reachable; otherwise, provide false. For num_findings, set the max number of findings to return for the rule; the default is 5, but ShiftLeft accepts values from 0 to 100
owasp_categoryThe OWASP categories of vulnerabilities for which you want to filter (e.g., a1-injection)
owasp_2021_categoryThe OWASP 2021 categories of vulnerabilities for which you want to filter (e.g., a09-security-logging-and-monitoring-failures)
cvss_31_severity_ratingsThe severity levels for which you want to filter. Accepted values: critical, high, medium, low
thresholdThe number of vulnerabilities found that would lead to a failed build. Default is 0, so any vulnerability identified would lead to a build failure
typeThe types of vulnerabilities for which you want to filter (e.g., SQL Injection or Sensitive Data Leak)

Vulnerability types

The following is a partial list of accepted values for the type parameter (this parameter also accepts custom tags defined using modification rules):

  • Authentication Bypass
  • Command Injection
  • CRLF Injection
  • Cross-Site Scripting
  • Crypto
  • Denial of Service
  • Deprecated Function Use
  • Deserialization
  • Directory Traversal
  • Error Handling
  • Header Injection
  • HTTP to Database
  • HTTP to Model
  • Insecure Authentication
  • Intent Redirection
  • JSON Injection
  • LDAP Injection
  • Log Forging
  • Mail Injection
  • NoSQL Injection
  • Open Redirect
  • Potential SQL Injection
  • Potential Regex Injection
  • Prototype Pollution
  • Race Condition
  • Regex Injection
  • Remote Code Execution
  • Security Best Practices
  • Security Misconfiguration
  • Sensitive Data Exposure
  • Sensitive Data Leak
  • Sensitive Data Usage
  • Server-Side Request Forgery
  • Session Injection
  • SQL Injection
  • Template Injection
  • Unsafe Reflection
  • Weak Cipher
  • Weak Hash
  • Weak Random
  • XML External Entities
  • XPath Injection

OWASP categories

The following is a list of possible values that you provide for the owasp_category parameter:

  • a1-injection
  • a2-broken-authentication
  • a3-sensitive-data-exposure
  • a4-xxe
  • a5-broken-access-control
  • a6-misconfiguration
  • a6-security-misconfiguration
  • a7-cross-site-scripting
  • a7-xss
  • a8-deserialization

ShiftLeft also accepts the following tags for OWASP 2021 categories using the owasp_2021_category parameter:

  • a01-broken-access-control
  • a02-cryptographic-failures
  • a03-injection
  • a04-insecure-design
  • a05-security-misconfiguration
  • a06-vulnerable-and-outdated-components
  • a07-identification-and-authentication-failures
  • a08-software-and-data-integrity-failures
  • a09-security-logging-and-monitoring-failures
  • a10-server-side-request-forgery-(ssrf)

If you'd like to use OWASP 2021 categories with the owasp_category tag (i.e., for backward compatibility purposes), you can distinguish the 2021 categories from the 2017 categories by including the year:

  • a01-2021-broken-access-control
  • a02-2021-cryptographic-failures
  • a03-2021-injection
  • a04-2021-insecure-design
  • a05-2021-security-misconfiguration
  • a06-2021-vulnerable-and-outdated-components
  • a07-2021-identification-and-authentication-failures
  • a08-2021-software-and-data-integrity-failures
  • a09-2021-security-logging-and-monitoring-failures
  • a10-2021-server-side-request-forgery-(ssrf)