Security/Application Security Pipeline

Purpose
This document provides guidance on how to implement security into the CI/CD pipeline, leveraging both GitLab's integrated tools and custom tools provided and developed by the Security Team.

In an effort to improve application security testing, our goal has been to “shift left” to remove more vulnerabilities earlier. The idea is to empower developers to find and fix vulnerabilities earlier in the software development lifecycle, when changes are less costly and more timely.

With security embedded into the development workflow, developers can get feedback on the security of their code as they are working, they can remediate in real time, and free up the security team’s time to focus on monitoring issues, assessing risk, and solving vulnerabilities that can’t be fixed by the developer. By continuously testing even small, incremental code changes, an avalanche of work is avoided at the end of the SDLC.

Note: The Security Team strongly recommends including security scanning tools into either migrated or new repository pipelines. These features have to be triggered both for new Merge Requests and for Continuous Development/Delivery.

Use Cases

 * Allows security flaws to be fixed early, when less expensive, removes context-switching, and minimizes risk by preventing vulnerabilities from reaching production.
 * Reduces security and compliance risks.

Templates Provided by the Security Team
The Security Team strongly suggest to use the relevant templates located at this GitLab repository. In order to include these templates, please see the documentation.

NPM Audit
Name of the template:

Description: The audit command submits a description of the dependencies configured in your project to your default registry and asks for a report of known vulnerabilities. If any vulnerabilities are found, then the impact and appropriate remediation will be calculated. If the  argument is provided, then remediations will be applied to the package tree.

How to include it: change your  accordingly:

Environmental variables: These tools are triggered for each and every new push or merge request. It is also possible to trigger them manually by visiting the CI/CD section on GitLab.


 * the suggested image is:
 * Use this variable to specify custom flags. Default ones:

Expected output: The command will exit with a 0 exit code if no vulnerabilities were found.

Risk Ratings and Acceptance:

Nancy
Name of the template:

Description: It is a tool to check for vulnerabilities in your Golang dependencies, powered by Sonatype OSS Index. It currently works for projects that use  or   for dependencies.

How to include it: change your  accordingly:

Environmental variables:


 * the suggested image is:
 * Use this variable to specify custom flags.

Expected output: Multiple different output formats are supported.

Risk Ratings and Acceptance:

AuditJS
Name of the template:

Description: Audits JavaScript projects using the OSS Index v3 REST API to identify known vulnerabilities and outdated package versions.

How to include it: change your  accordingly: Environmental variables:
 * the suggested image is:
 * use this variable to specify custom flags.

Expected output:  can output directly as   or as   specifically formatted for JUnit test cases.''' Risk Ratings and Acceptance:'''

Npm Outdated
Name of the template:

Description: This tool will check the registry to see if any (or, specific) installed packages are currently outdated.

How to include it: change your  accordingly: Environmental variables:


 * the suggested image is:


 * use this variable to specify custom flags.

Expected output: Risk Ratings and Acceptance:

Php composer outdated
Name of the template:

Description: Composer is a tool for dependency management in PHP. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.

How to include it: change your  accordingly: Environmental variables: Expected output:  can output directly as   or as   specifically formatted for JUnit test cases.''' Risk Ratings and Acceptance:'''
 * the suggested image is:
 * Use this variable to specify custom flags.

Php security checker
Name of the template:

Description: The Local PHP Security Checker is a command line tool that checks if your PHP application depends on PHP packages with known security vulnerabilities. It uses the Security Advisories Database behind the scenes.

How to include it: change your  accordingly: Environmental variables: Expected output: ''' Risk Ratings and Acceptance:'''
 * the suggested image is:
 * Use this variable to specify custom flags.

Safety db
Name of the template:

Description: Safety DB is a database of known security vulnerabilities in Python packages. The data is made available by pyup.io and synced with this repository once per month. Most of the entries are found by filtering CVEs and changelogs for certain keywords and then manually reviewing them.

How to include it: change your  accordingly:

Semgrep
In order to use Semgrep, include it in your  like any other provided templates.

You can configure which ruleset to run by changing the variable  as showed here (you can chain multiple  ): (TODO: explain behaviour about provided templates)  You can select one of the available docker image from https://docker-registry.wikimedia.org/.

Note: The Security Team discourages the use of --config=auto because metrics will be reported back to Semgrep.

Default Rulesets
The semgrep-ci template contains the most relevant security-related ruleset picked by the security team:



Suggested Rulesets
In order to keep the workload at the minimum, the security team has picked the most relevant security rulesets, however here are reported some other good generic and language-specific candidates that could be added:

Custom Rulesets
Semgrep offers the chance to develop your own ruleset. The suggested way to do that would be by creating a new  file that contains your rules (either on your repository, or on the security/gitlab-ci-security-templates repository), and then referencing this   file from the   like this:

Default Scanning behaviour
Semgrep by default will only check the changed files from any Push and Merge Requests. In order to trigger a full scan, you must manually run the pipeline or schedule it.

Note: It is still possible to override this default behaviour by setting the variable  to "true" in your. :

Custom Templates
Even though the Security Team strongly advises against the use of custom templates, there is the possibility to implement your own custom ones.

GitLab Default Templates
For all of the remaining Languages/Frameworks not supported by the Security Team, there is the possibility to use the GitLab default one. It features automatic language detection which works even for mixed-language projects. If any supported language is detected in the project source code it automatically runs the appropriate SAST analyzers.

Even though the results may not be the greatest, it could still provide some value. Here is the list of GitLab supported languages.

How to configure GitLab default SAST templates
To enable and configure SAST with default settings:
 * 1) On the top bar, select Menu > Projects and find your project.
 * 2) On the left sidebar, select Security & Compliance > Configuration.
 * 3) In the SAST section, select.
 * 4) Review the draft MR that enables SAST with the default recommended settings in the   file.
 * 5) Merge the MR to enable SAST. You should see SAST jobs run in that MR’s pipeline.

Results
Security automation is far from perfect. Even though our goal is to have straight-forward scan results and fully automated remediations, unfortunately that is not always possible. Results may be polluted by False Positives, and remediations may appear unclear. When these scenarios occur, please get in touch with the Security Team to work on possible solutions.

Note: Repository owners are implicitly accepting the risk of the findings. It is your own responsibility to fix issues or to accept potential threats. Please contact the Security Team to get help on how to address the issues.

How to check results
In order to check for tool output, please go to the Jobs section.

Based on the specific tool configuration, a job could never fail, or fail only when new critical/high/moderate vulnerabilities are discovered.

JSON Artifacts
Usually security tools emit a report that is in the form of a JSON result file.

The JSON report file can be downloaded from the CI pipelines page, or the pipelines tab on merge requests by setting  to. For more information see the documentation and.

E.g.:

For phpcs-security-tool add this to the  file:

Known Guides and Documentation

 * Configure SAST in the UI with default settings
 * GitLab CI Security Repository