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:
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:
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.123means the target of the build rules will be the scan with an ID of 123.--target tag.branch=nifty-featuremeans the target of the build rules will be the last scan tagged as belonging to branchnifty-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
sourceentry in your shiftleft.yml config file:source:scan: 123to compare the target against a specific scan, or provide
source:branch: nifty-featureto 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: previousto 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.
| Parameters | Description |
|---|---|
| finding_types | The 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. |
| id | An identifier (name) of your choice for the rule |
| options | Allows 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_category | The OWASP categories of vulnerabilities for which you want to filter (e.g., a1-injection) |
| owasp_2021_category | The OWASP 2021 categories of vulnerabilities for which you want to filter (e.g., a09-security-logging-and-monitoring-failures) |
| cvss_31_severity_ratings | The severity levels for which you want to filter. Accepted values: critical, high, medium, low |
| threshold | The number of vulnerabilities found that would lead to a failed build. Default is 0, so any vulnerability identified would lead to a build failure |
| type | The 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)