Skip to main content

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. Qwiet preZero 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:

version: 2 # implies that check-analysis v2 should be used and therefore
           # the --v2 flag can be omitted when running sl check-analysis
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
    severities:
      - high
      - critical
    threshold: 0
    options:
      num_findings: 10 # return only 10 SAST findings
  - id: "Allow zero secrets"
    finding_types:
      - secret
    threshold: 0
  - id: "Allow zero reachable SCA vulnerabilities"
    finding_types:
      - oss_vuln
    severities:
      - 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
    severities:
      - critical
      - high
    threshold: 0
    options:
      num_findings: 10 # return 10 container findings
  - id: "Example with mix and match findings"
    types:
      - SQL Injection
      - Sensitive Data Leak
    owasp_categories:
      - a1-injection
    owasp_2021_categories:
      - a09-security-logging-and-monitoring-failures
    severities:
      - low
      - medium
      - high
      - critical
  - id: "Allow no license violations"
    licenses:
      allow:
        - Apache-2.0
        - Public-Domain
        - Unknown
      block:
        - GPL-3.0
  - id: Identify security issues
    finding_types:
      - security_issue
    severities:
      - medium
      - high
    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. Qwiet 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, security_issue. You could also provide *, which returns all except package. If you omit this parameter, Qwiet defaults to returning only vulnerabilities.
idAn identifier (name) of your choice for the rule
licenseThe licenses that should be allowed/blocked. You can specify licenses to block or allow (licenses on the block list supersede the allow list). Accepted license values: ISC, BSD, Unknown, Apache-2.0, UNLICENSED, MIT, CCO-1.0
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 Qwiet accepts values from 0 to 100
owasp_categoriesThe OWASP categories of vulnerabilities for which you want to filter (e.g., a1-injection)
owasp_2021_categoriesThe OWASP 2021 categories of vulnerabilities for which you want to filter (e.g., a09-security-logging-and-monitoring-failures)
severitiesThe 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. If not defined, the default is 0, so any vulnerability identified would lead to a build failure
typesThe types of vulnerabilities for which you want to filter (e.g., SQL Injection or Sensitive Data Leak)
versionThe config file version you're using

Vulnerability types​

The following is a partial list of accepted values for the types parameter (type in the deprecated version 1 of build-rules). 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_categories parameter (owasp_category in the deprecated version 1 of build-rules):

  • 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

Qwiet also accepts the following tags for OWASP 2021 categories using the owasp_2021_categories 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_categories 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)