From d5caa2aa6cbe6e6aa87d72cc257226104d4f21c0 Mon Sep 17 00:00:00 2001 From: Lyn Landon Date: Tue, 27 Dec 2022 13:46:52 -0800 Subject: [PATCH 01/11] Adding Compliance Pipeline tutorial --- doc/tutorials/compliance_pipeline_guide.md | 121 +++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 doc/tutorials/compliance_pipeline_guide.md diff --git a/doc/tutorials/compliance_pipeline_guide.md b/doc/tutorials/compliance_pipeline_guide.md new file mode 100644 index 00000000000000..f290950fac1ffe --- /dev/null +++ b/doc/tutorials/compliance_pipeline_guide.md @@ -0,0 +1,121 @@ +--- +stage: none +group: Tutorials +--- + +# Tutorial: Set up a compliance pipeline + +In this tutorial, learn to configure and create a [compliance framework](../../user/group/compliance_frameworks.md#configure-a-compliance-pipeline) that adds a label to identify projects that have specific compliance requirements. + +Pre-requisites: + +- ? + +To set up a compliance framework: + +1. [Import the project template](#import-the-project-template). +1. [Create a compliance framework](#create-a-compliance-framework). +1. [Create a new project](#create-a-new-project). +1. [Apply a compliance framework to a project](#apply-a-compliance-framework-to-a-project). +1. [Add a vulnerability for testing](#add-a-vulnerability-for-testing). + +## Import the project template + +To import the project template: + +1. Download the [Compliance Pipeline project template](https://gitlab.com/tanuki-workshops/secure-demos/templates/compliance-pipeline) as a `tar.gz` file. +1. [Create a new project using the template](../../user/project/working_with_projects.md#create-a-project-from-a-built-in-template). +1. Select the `compliance-pipeline` template. +1. Rename the template `sast-compliance-pipeline`. + +This project template contains the following `.compliance-ci.yml` file: + +```yaml +stages: + - test + - greetings + +good_morning: + stage: greetings + tags: [ saas-linux-large-amd64 ] + script: + - echo "🥐 Good Morning 😃" + +# This job will run at the begining of the pipeline +hello_world: + stage: .pre + tags: [ saas-linux-large-amd64 ] + script: + - echo "👋 Hello World 🌍" + +# Sast won't scan the `/tests` directory +variables: + SAST_EXCLUDED_PATHS: /tests + +# Include SAST template +include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) + - project: '$CI_PROJECT_PATH' + file: '$CI_CONFIG_PATH' + ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch + - template: Jobs/SAST.latest.gitlab-ci.yml + #- template: Security/SAST.gitlab-ci.yml + +# Override the SAST Job +semgrep-sast: + tags: [ saas-linux-large-amd64 ] +``` + +In the next steps, we link this pipeline to a compliance framework. + +## Create a compliance framework + +To create a compliance framework: + +1. In the `sast-compliance-pipeline` project, go to the highest level group. +1. From the left sidebar, select **Settings > General**. +1. Expand the `Compliance frameworks` section. +1. Select `Add framework` and name it `sast compliance framework`, then complete any additional required information. +1. Select `Add framework`. + +The compliance pipeline configuration value is composed like this: `@`. + +For example, `compliance-ci.yml@tanuki-workshops/secure-demos/sast-compliance-pipeline`. + +## Create a new project + +To create a new project: + +1. Download the [Demo Project for Compliance template](https://gitlab.com/tanuki-workshops/secure-demos/templates/demo-project-for-compliance) as a `tar.gz` file. +1. [Create a new project using the template](../../user/project/working_with_projects.md#create-a-project-from-a-built-in-template). +1. Select the `demo-project-for-compliance` template. +1. Rename the template `sast-compliance-demo`. + +## Apply a compliance framework to a project + +To apply a compliance framework to a project: + +1. Go to the `sast-compliance-demo` project. +1. From the left sidebar, select **Settings > General**. +1. From the list, select `sast-compliance-framework`. +1. Select `Save changes`. + +In the projects list, you now see a new label next to the project name. + +## Add a vulnerability for testing + +To add a vulnerability for testing: + +1. In the `sast-compliance-demo` project, move the following files to the root directory of the project: + + - `tests/.gitlab-ci.yml` + - `tests/main.ts` + +1. Commit your changes to the `main` branch. + +This may take a few minutes. + +1. From the left sidebar, go to **Pipelines > Security**. + +The pipeline executed three jobs and detected a vulnerability. + +You now know how to set up and configure a compliance pipeline for use with your projects! -- GitLab From a766e42c6d753ae0a1aba3d2ec626c3b3470152d Mon Sep 17 00:00:00 2001 From: Lyn Landon Date: Mon, 6 Feb 2023 11:04:56 -0800 Subject: [PATCH 02/11] Committing first part of tutorial --- doc/tutorials/compliance_pipeline_guide.md | 121 --------------------- doc/tutorials/fuzz_testing_tutorial.md | 116 ++++++++++++++++++++ 2 files changed, 116 insertions(+), 121 deletions(-) delete mode 100644 doc/tutorials/compliance_pipeline_guide.md create mode 100644 doc/tutorials/fuzz_testing_tutorial.md diff --git a/doc/tutorials/compliance_pipeline_guide.md b/doc/tutorials/compliance_pipeline_guide.md deleted file mode 100644 index f290950fac1ffe..00000000000000 --- a/doc/tutorials/compliance_pipeline_guide.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -stage: none -group: Tutorials ---- - -# Tutorial: Set up a compliance pipeline - -In this tutorial, learn to configure and create a [compliance framework](../../user/group/compliance_frameworks.md#configure-a-compliance-pipeline) that adds a label to identify projects that have specific compliance requirements. - -Pre-requisites: - -- ? - -To set up a compliance framework: - -1. [Import the project template](#import-the-project-template). -1. [Create a compliance framework](#create-a-compliance-framework). -1. [Create a new project](#create-a-new-project). -1. [Apply a compliance framework to a project](#apply-a-compliance-framework-to-a-project). -1. [Add a vulnerability for testing](#add-a-vulnerability-for-testing). - -## Import the project template - -To import the project template: - -1. Download the [Compliance Pipeline project template](https://gitlab.com/tanuki-workshops/secure-demos/templates/compliance-pipeline) as a `tar.gz` file. -1. [Create a new project using the template](../../user/project/working_with_projects.md#create-a-project-from-a-built-in-template). -1. Select the `compliance-pipeline` template. -1. Rename the template `sast-compliance-pipeline`. - -This project template contains the following `.compliance-ci.yml` file: - -```yaml -stages: - - test - - greetings - -good_morning: - stage: greetings - tags: [ saas-linux-large-amd64 ] - script: - - echo "🥐 Good Morning 😃" - -# This job will run at the begining of the pipeline -hello_world: - stage: .pre - tags: [ saas-linux-large-amd64 ] - script: - - echo "👋 Hello World 🌍" - -# Sast won't scan the `/tests` directory -variables: - SAST_EXCLUDED_PATHS: /tests - -# Include SAST template -include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) - - project: '$CI_PROJECT_PATH' - file: '$CI_CONFIG_PATH' - ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch - - template: Jobs/SAST.latest.gitlab-ci.yml - #- template: Security/SAST.gitlab-ci.yml - -# Override the SAST Job -semgrep-sast: - tags: [ saas-linux-large-amd64 ] -``` - -In the next steps, we link this pipeline to a compliance framework. - -## Create a compliance framework - -To create a compliance framework: - -1. In the `sast-compliance-pipeline` project, go to the highest level group. -1. From the left sidebar, select **Settings > General**. -1. Expand the `Compliance frameworks` section. -1. Select `Add framework` and name it `sast compliance framework`, then complete any additional required information. -1. Select `Add framework`. - -The compliance pipeline configuration value is composed like this: `@`. - -For example, `compliance-ci.yml@tanuki-workshops/secure-demos/sast-compliance-pipeline`. - -## Create a new project - -To create a new project: - -1. Download the [Demo Project for Compliance template](https://gitlab.com/tanuki-workshops/secure-demos/templates/demo-project-for-compliance) as a `tar.gz` file. -1. [Create a new project using the template](../../user/project/working_with_projects.md#create-a-project-from-a-built-in-template). -1. Select the `demo-project-for-compliance` template. -1. Rename the template `sast-compliance-demo`. - -## Apply a compliance framework to a project - -To apply a compliance framework to a project: - -1. Go to the `sast-compliance-demo` project. -1. From the left sidebar, select **Settings > General**. -1. From the list, select `sast-compliance-framework`. -1. Select `Save changes`. - -In the projects list, you now see a new label next to the project name. - -## Add a vulnerability for testing - -To add a vulnerability for testing: - -1. In the `sast-compliance-demo` project, move the following files to the root directory of the project: - - - `tests/.gitlab-ci.yml` - - `tests/main.ts` - -1. Commit your changes to the `main` branch. - -This may take a few minutes. - -1. From the left sidebar, go to **Pipelines > Security**. - -The pipeline executed three jobs and detected a vulnerability. - -You now know how to set up and configure a compliance pipeline for use with your projects! diff --git a/doc/tutorials/fuzz_testing_tutorial.md b/doc/tutorials/fuzz_testing_tutorial.md new file mode 100644 index 00000000000000..26c77c0af3ccff --- /dev/null +++ b/doc/tutorials/fuzz_testing_tutorial.md @@ -0,0 +1,116 @@ +--- +stage: none +group: Tutorials +--- + +# Tutorial: Perform fuzz testing in GitLab + +In this tutorial, learn how to set up, configure, and perform [coverage-guided fuzz testing](../user/application_security/coverage_fuzzing/index.md#coverage-guided-fuzz-testing-process) using JavaScript in GitLab. + +Fuzz testing sets operation parameters to unexpected values in an effort to cause unexpected behavior and errors. This helps you discover bugs and potential security issues that other QA processes may miss. + +Use fuzz testing in addition to other security scanners and your own test processes. If you're using GitLab CI/CD, you can run fuzz tests as part your CI/CD workflow. + +To set up fuzz scanning: + +1. [Import the project template](#import-the-project-template). +1. [Create the fuzz targets](#create-the-fuzz-targets). +1. [Enable coverage-guided fuzz testing](#enable-coverage-guided-fuzz-testing). +1. [Run the fuzz test pipeline](#run-the-fuzz-test-pipeline). +1. [Fix the vulnerability](#fix-the-vulnerability). + +## Import the project template + +To import the project template: + +1. Download the [Fuzz testing template](https://gitlab.com/gitlab-org/tutorial-project-templates/fuzz-testing) as a `tar.gz` file. +1. [Create a new project using the template](../user/project/index.md#create-a-project-from-a-built-in-template). +1. Select the `fuzz-testing` template. +1. Rename the template `fuzz-testing-demo`. + This project uses `node.js` with JavaScript functions included in the `my-tools.js` file. + +The template is ready for testing. + +## Create the fuzz targets + +Before you begin, make sure you have [imported the project template](#import-the-project-template). + +The fuzz targets call a function of the `my-tools.js` file using a random buffer as a parameter. + +To create fuzz targets: + +1. On the top bar, select **Main menu > Projects** and select the `fuzz-testing-demo` project. +1. Create a file in the root directory of the project: + - Name the file `fuzz-sayhello.js` and add the following code: + + ```Javascript + let tools = require('./my-tools') + + function fuzz(buf) { + const text = buf.toString() + tools.sayHello(text) + } + + module.exports = { + fuzz + } + ``` + +1. Create a second file in the root directory of the project: + - Name the file `fuzz-readme.js` and add the following code: + + ```Javascript + let tools = require('./my-tools') + function fuzz(buf) { + const text = buf.toString() + tools.readmeContent(text) + } + module.exports = { + fuzz + } + ``` + +You now have two fuzz targets for scanning. + +## Enable coverage-guided fuzz testing + +To enable coverage-guided fuzz testing: + +1. In the root directory of the `fuzz-testing-demo` project, create a new file: + - Name the file `.gitlab-ci.yml` and add the following code: + + ```yaml + image: node:18 + stages: + - fuzz + include: + - template: Coverage-Fuzzing.gitlab-ci.yml + + readme_fuzz_target: + extends: .fuzz_base + tags: [saas-linux-large-amd64] # this is not mandatory + variables: + COVFUZZ_ADDITIONAL_ARGS: '--fuzzTime=60' + script: + - npm config set @gitlab-org:registry https://gitlab.com/api/v4/packages/npm/ && npm i -g @gitlab-org/jsfuzz + - ./gitlab-cov-fuzz run --engine jsfuzz -- fuzz-readme.js + + hello_fuzzing_target: + extends: .fuzz_base + tags: [saas-linux-large-amd64] # this is not mandatory + variables: + COVFUZZ_ADDITIONAL_ARGS: '--fuzzTime=60' + script: + - npm config set @gitlab-org:registry https://gitlab.com/api/v4/packages/npm/ && npm i -g @gitlab-org/jsfuzz + - ./gitlab-cov-fuzz run --engine jsfuzz -- fuzz-sayhello.js + ``` + + This step adds a `fuzz` stage to your pipeline using a template, and adds two jobs, `readme_fuzz` and `hello-fuzz`. Each job runs using the `jsfuzz` engine, which reports unhandled exceptions as crashes. + +1. + +## Run the fuzz test pipeline + +To run the fuzz test: + +1. On the left side -- GitLab From e470d202cae1a86ad540491e66e7b17d37c69584 Mon Sep 17 00:00:00 2001 From: Lyn Landon Date: Wed, 8 Feb 2023 16:11:18 -0800 Subject: [PATCH 03/11] Fixed YAML code for better copying --- doc/tutorials/fuzz_testing_tutorial.md | 54 ++++++++++++++------------ 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/doc/tutorials/fuzz_testing_tutorial.md b/doc/tutorials/fuzz_testing_tutorial.md index 26c77c0af3ccff..2d7fa8795e8ddf 100644 --- a/doc/tutorials/fuzz_testing_tutorial.md +++ b/doc/tutorials/fuzz_testing_tutorial.md @@ -7,7 +7,7 @@ group: Tutorials In this tutorial, learn how to set up, configure, and perform [coverage-guided fuzz testing](../user/application_security/coverage_fuzzing/index.md#coverage-guided-fuzz-testing-process) using JavaScript in GitLab. -Fuzz testing sets operation parameters to unexpected values in an effort to cause unexpected behavior and errors. This helps you discover bugs and potential security issues that other QA processes may miss. +Fuzz testing sets the operation parameters to unexpected values to cause unexpected behavior and errors. This helps you discover bugs and potential security issues that other QA processes may miss. Use fuzz testing in addition to other security scanners and your own test processes. If you're using GitLab CI/CD, you can run fuzz tests as part your CI/CD workflow. @@ -23,7 +23,7 @@ To set up fuzz scanning: To import the project template: -1. Download the [Fuzz testing template](https://gitlab.com/gitlab-org/tutorial-project-templates/fuzz-testing) as a `tar.gz` file. +1. Download the [Fuzz testing template](https://gitlab.com/gitlab-org/tutorial-project-templates/fuzz-testing) as a `tar.gz` file. 1. [Create a new project using the template](../user/project/index.md#create-a-project-from-a-built-in-template). 1. Select the `fuzz-testing` template. 1. Rename the template `fuzz-testing-demo`. @@ -40,8 +40,8 @@ The fuzz targets call a function of the `my-tools.js` file using a random buffer To create fuzz targets: 1. On the top bar, select **Main menu > Projects** and select the `fuzz-testing-demo` project. -1. Create a file in the root directory of the project: - - Name the file `fuzz-sayhello.js` and add the following code: +1. Create a file in the root directory of the project. +1. Name the file `fuzz-sayhello.js` and add the following code: ```Javascript let tools = require('./my-tools') @@ -56,8 +56,9 @@ To create fuzz targets: } ``` -1. Create a second file in the root directory of the project: - - Name the file `fuzz-readme.js` and add the following code: +1. Commit the changes. +1. Return to the root directory of the project and create the second file. +1. Name the file `fuzz-readme.js` and add the following code: ```Javascript let tools = require('./my-tools') @@ -70,16 +71,18 @@ To create fuzz targets: } ``` +1. Commit the changes. + You now have two fuzz targets for scanning. ## Enable coverage-guided fuzz testing To enable coverage-guided fuzz testing: -1. In the root directory of the `fuzz-testing-demo` project, create a new file: - - Name the file `.gitlab-ci.yml` and add the following code: +1. In the root directory of the `fuzz-testing-demo` project, create a new file. +1. Name the file `.gitlab-ci.yml` and add the following code: - ```yaml + ```YAML image: node:18 stages: - fuzz @@ -87,30 +90,31 @@ To enable coverage-guided fuzz testing: - template: Coverage-Fuzzing.gitlab-ci.yml readme_fuzz_target: - extends: .fuzz_base - tags: [saas-linux-large-amd64] # this is not mandatory - variables: - COVFUZZ_ADDITIONAL_ARGS: '--fuzzTime=60' - script: - - npm config set @gitlab-org:registry https://gitlab.com/api/v4/packages/npm/ && npm i -g @gitlab-org/jsfuzz - - ./gitlab-cov-fuzz run --engine jsfuzz -- fuzz-readme.js + extends: .fuzz_base + tags: [saas-linux-large-amd64] # this is not mandatory + variables: + COVFUZZ_ADDITIONAL_ARGS: '--fuzzTime=60' + script: + - npm config set @gitlab-org:registry https://gitlab.com/api/v4/packages/npm/ && npm i -g @gitlab-org/jsfuzz + - ./gitlab-cov-fuzz run --engine jsfuzz -- fuzz-readme.js hello_fuzzing_target: - extends: .fuzz_base - tags: [saas-linux-large-amd64] # this is not mandatory - variables: - COVFUZZ_ADDITIONAL_ARGS: '--fuzzTime=60' - script: - - npm config set @gitlab-org:registry https://gitlab.com/api/v4/packages/npm/ && npm i -g @gitlab-org/jsfuzz - - ./gitlab-cov-fuzz run --engine jsfuzz -- fuzz-sayhello.js + extends: .fuzz_base + tags: [saas-linux-large-amd64] # this is not mandatory + variables: + COVFUZZ_ADDITIONAL_ARGS: '--fuzzTime=60' + script: + - npm config set @gitlab-org:registry https://gitlab.com/api/v4/packages/npm/ && npm i -g @gitlab-org/jsfuzz + - ./gitlab-cov-fuzz run --engine jsfuzz -- fuzz-sayhello.js ``` This step adds a `fuzz` stage to your pipeline using a template, and adds two jobs, `readme_fuzz` and `hello-fuzz`. Each job runs using the `jsfuzz` engine, which reports unhandled exceptions as crashes. -1. + 1. Select **Commit** to commit your changes. ## Run the fuzz test pipeline To run the fuzz test: -1. On the left side +1. On the left sidebar, select **Merge requests**. +1. Select -- GitLab From 1c72594f86276f3eaad77836e5632d35fc5e78d1 Mon Sep 17 00:00:00 2001 From: Jonathan Glassman Date: Tue, 4 Apr 2023 10:58:03 +0100 Subject: [PATCH 04/11] Draft tutorial --- doc/tutorials/fuzz_testing_tutorial.md | 157 ++++++++++++++++++++----- 1 file changed, 129 insertions(+), 28 deletions(-) diff --git a/doc/tutorials/fuzz_testing_tutorial.md b/doc/tutorials/fuzz_testing_tutorial.md index 2d7fa8795e8ddf..02df1d5fa3dde0 100644 --- a/doc/tutorials/fuzz_testing_tutorial.md +++ b/doc/tutorials/fuzz_testing_tutorial.md @@ -5,39 +5,55 @@ group: Tutorials # Tutorial: Perform fuzz testing in GitLab -In this tutorial, learn how to set up, configure, and perform [coverage-guided fuzz testing](../user/application_security/coverage_fuzzing/index.md#coverage-guided-fuzz-testing-process) using JavaScript in GitLab. +[Coverage-guided fuzz testing](../user/application_security/coverage_fuzzing/index.md#coverage-guided-fuzz-testing-process): -Fuzz testing sets the operation parameters to unexpected values to cause unexpected behavior and errors. This helps you discover bugs and potential security issues that other QA processes may miss. +- Send unexpected, malformed or random data to an instrumented version of your application + to try to cause unexpected behavior. +- Monitors your application for unstable behaviours and crashes, as this indicates + a bug that you should fix. -Use fuzz testing in addition to other security scanners and your own test processes. If you're using GitLab CI/CD, you can run fuzz tests as part your CI/CD workflow. +This helps you discover bugs and potential security issues that other QA processes may miss. -To set up fuzz scanning: +Use fuzz testing in addition to other security scanners and your own test processes. +If you're using GitLab CI/CD, you can run fuzz tests as part your CI/CD workflow. -1. [Import the project template](#import-the-project-template). +To set up, configure, and perform coverage-guided fuzz testing +using JavaScript in GitLab in this tutorial, you: + +1. [Fork the project template](#import-the-project-template). 1. [Create the fuzz targets](#create-the-fuzz-targets). 1. [Enable coverage-guided fuzz testing](#enable-coverage-guided-fuzz-testing). -1. [Run the fuzz test pipeline](#run-the-fuzz-test-pipeline). -1. [Fix the vulnerability](#fix-the-vulnerability). +1. [Run the fuzz test](#run-the-fuzz-test). +1. [Fix the vulnerabilities](#fix-the-vulnerabilities). + +Prerequisites: -## Import the project template +- TBC -To import the project template: +## Fork the project template -1. Download the [Fuzz testing template](https://gitlab.com/gitlab-org/tutorial-project-templates/fuzz-testing) as a `tar.gz` file. -1. [Create a new project using the template](../user/project/index.md#create-a-project-from-a-built-in-template). -1. Select the `fuzz-testing` template. -1. Rename the template `fuzz-testing-demo`. - This project uses `node.js` with JavaScript functions included in the `my-tools.js` file. +First, to create a project to try out fuzz testing in, you must fork the `fuzz-testing` project template: -The template is ready for testing. +1. Open the [`fuzz-testing` project template](https://gitlab.com/gitlab-org/tutorial-project-templates/fuzz-testing). +1. [Fork the project template](../user/project/repository/forking_workflow.md). +1. When forking the project template: + - Name the forked project `fuzz-testing-demo`. + - Select an appropriate [namespace](../user/namespace/index.md). + - Set [project visibility](../user/public_access.md) to TBC. + +You have now created a project to try out fuzz testing. ## Create the fuzz targets -Before you begin, make sure you have [imported the project template](#import-the-project-template). +Before you begin, make sure you have [forked the project template](#fork-the-project-template). + +Now you create the fuzz targets. A fuzz target is a function or program that, +given an input, makes a call to the application being tested. -The fuzz targets call a function of the `my-tools.js` file using a random buffer as a parameter. +In this example, the fuzz targets call a function of the `my-tools.js` file using +a random buffer as a parameter. -To create fuzz targets: +To create the two fuzz targets, you create : 1. On the top bar, select **Main menu > Projects** and select the `fuzz-testing-demo` project. 1. Create a file in the root directory of the project. @@ -56,9 +72,12 @@ To create fuzz targets: } ``` -1. Commit the changes. -1. Return to the root directory of the project and create the second file. -1. Name the file `fuzz-readme.js` and add the following code: +1. Name the **Target Branch** `add-fuzz-test` and write a descriptive commit message. + - Do not select the **Start a new merge request with these changes** checkbox. +1. Select **Commit changes**. +1. Return to the root directory of the project. +1. Make sure you are in the `add-fuzz-test` branch. +1. Create the second file named `fuzz-readme.js` and add the following code: ```Javascript let tools = require('./my-tools') @@ -71,14 +90,18 @@ To create fuzz targets: } ``` -1. Commit the changes. +1. Write a descriptive commit message. +1. Make sure the **Target Branch** is `add-fuzz-test`. +1. Select **Commit changes**. -You now have two fuzz targets for scanning. +You now have two fuzz targets that can make calls to the application being tested. ## Enable coverage-guided fuzz testing -To enable coverage-guided fuzz testing: +To enable coverage-guided fuzz testing, you next create a GitLab CI pipeline running +the `gitlab-cov-fuzz` CLI to execute the fuzzer on the two fuzz targets: +1. Make sure you are in the `add-fuzz-test` branch. 1. In the root directory of the `fuzz-testing-demo` project, create a new file. 1. Name the file `.gitlab-ci.yml` and add the following code: @@ -108,13 +131,91 @@ To enable coverage-guided fuzz testing: - ./gitlab-cov-fuzz run --engine jsfuzz -- fuzz-sayhello.js ``` - This step adds a `fuzz` stage to your pipeline using a template, and adds two jobs, `readme_fuzz` and `hello-fuzz`. Each job runs using the `jsfuzz` engine, which reports unhandled exceptions as crashes. + This step adds: + - A `fuzz` stage to your pipeline using a template. + - Two jobs, `readme_fuzz` and `hello-fuzz`. Each job runs using the `jsfuzz` + engine, which reports unhandled exceptions as crashes. - 1. Select **Commit** to commit your changes. +1. Write a descriptive commit message. +1. Make sure the **Target Branch** is `add-fuzz-test`. +1. Select **Commit changes**. -## Run the fuzz test pipeline +You have successfully enabled coverage-guided fuzz testing. + +Next you run the fuzz test using the created pipeline. + +## Run the fuzz test To run the fuzz test: 1. On the left sidebar, select **Merge requests**. -1. Select +1. Select **New merge request**. +1. In the **Source branch** section, select the `add-fuzz-test` branch. +1. In the **Target branch** section, make sure that your namespace and the `main` branch are selected. +1. Select **Compare branches and continue**. +1. [Create the merge request](../user/project/merge_requests/creating_merge_requests.md). + +Creating the merge request triggers a new pipeline, which runs the fuzz test. +When the pipeline is finished running, you should see a security vulnerability +alert on the merge request page. + +To see more information on each vulnerability, select the individual **Uncaught-exception** links. + +You have successfully run the fuzz test. + +## Fix the vulnerabilities + +The fuzz test identified two security vulnerabilities. To fix those +vulnerabilities, you must catch them in the functions of the `my-tools.js` library. + +1. Make sure you are in the `add-fuzz-test` branch. +1. Go to the root directory of your project and open the `my-tools.js` file. +1. Replace the contents of this file with the following code: + + ```Javascript + const fs = require('fs') + + function sayHello(name) { + if(name.includes("z")) { + //throw new Error("😡 error name: " + name) + console.log("😡 error name: " + name) + } else { + return "😀 hello " + name + } + } + + function readmeContent(name) { + + let fileName = name => { + if(name.includes("w")) { + return "./README.txt" + } else { + return "./README.md" + } + } + + //const data = fs.readFileSync(fileName(name), 'utf8') + try { + const data = fs.readFileSync(fileName(name), 'utf8') + return data + } catch (err) { + console.error(err.message) + return "" + } + + } + + module.exports = { + sayHello, readmeContent + } + ``` + +1. Select **Commit changes**. This triggers another pipeline to run another fuzz test. +1. When the pipeline is finished, check the merge request page. You should see + that the security scan detected no new vulnerabilities. +1. Merge your changes. + +Congratulations, you've successfully run a fuzz test and fixed the identified +security vulnerabilities! + +For more information, see [coverage-guided fuzz testing](../user/application_security/coverage_fuzzing/index.md). -- GitLab From ce6ff989d8ffca93ec671b3b5c81107bb94927cc Mon Sep 17 00:00:00 2001 From: Jonathan Glassman Date: Tue, 4 Apr 2023 11:28:03 +0100 Subject: [PATCH 05/11] Fix broken link --- doc/tutorials/fuzz_testing_tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorials/fuzz_testing_tutorial.md b/doc/tutorials/fuzz_testing_tutorial.md index 02df1d5fa3dde0..31bede43ccc5e0 100644 --- a/doc/tutorials/fuzz_testing_tutorial.md +++ b/doc/tutorials/fuzz_testing_tutorial.md @@ -20,7 +20,7 @@ If you're using GitLab CI/CD, you can run fuzz tests as part your CI/CD workflow To set up, configure, and perform coverage-guided fuzz testing using JavaScript in GitLab in this tutorial, you: -1. [Fork the project template](#import-the-project-template). +1. [Fork the project template](#fork-the-project-template). 1. [Create the fuzz targets](#create-the-fuzz-targets). 1. [Enable coverage-guided fuzz testing](#enable-coverage-guided-fuzz-testing). 1. [Run the fuzz test](#run-the-fuzz-test). -- GitLab From 75e7e1ff0fc3e4537ab5a91e1ab6629c61b1b28b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Charri=C3=A8re?= Date: Tue, 4 Apr 2023 14:01:26 +0000 Subject: [PATCH 06/11] Apply code indents --- doc/tutorials/fuzz_testing_tutorial.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/tutorials/fuzz_testing_tutorial.md b/doc/tutorials/fuzz_testing_tutorial.md index 31bede43ccc5e0..879352c2ef0e4e 100644 --- a/doc/tutorials/fuzz_testing_tutorial.md +++ b/doc/tutorials/fuzz_testing_tutorial.md @@ -63,12 +63,12 @@ To create the two fuzz targets, you create : let tools = require('./my-tools') function fuzz(buf) { - const text = buf.toString() - tools.sayHello(text) + const text = buf.toString() + tools.sayHello(text) } module.exports = { - fuzz + fuzz } ``` @@ -108,9 +108,9 @@ the `gitlab-cov-fuzz` CLI to execute the fuzzer on the two fuzz targets: ```YAML image: node:18 stages: - - fuzz + - fuzz include: - - template: Coverage-Fuzzing.gitlab-ci.yml + - template: Coverage-Fuzzing.gitlab-ci.yml readme_fuzz_target: extends: .fuzz_base @@ -133,7 +133,7 @@ the `gitlab-cov-fuzz` CLI to execute the fuzzer on the two fuzz targets: This step adds: - A `fuzz` stage to your pipeline using a template. - - Two jobs, `readme_fuzz` and `hello-fuzz`. Each job runs using the `jsfuzz` + - Two jobs, `readme_fuzz_target` and `hello_fuzzing_target`. Each job runs using the `jsfuzz` engine, which reports unhandled exceptions as crashes. 1. Write a descriptive commit message. -- GitLab From a8af0cf16e6d44638edd71c8e64fd6a840e28f0c Mon Sep 17 00:00:00 2001 From: Jonathan Glassman Date: Tue, 4 Apr 2023 16:48:06 +0100 Subject: [PATCH 07/11] Implement PC changes --- doc/tutorials/fuzz_testing_tutorial.md | 60 +++++++++++++++++--------- 1 file changed, 40 insertions(+), 20 deletions(-) diff --git a/doc/tutorials/fuzz_testing_tutorial.md b/doc/tutorials/fuzz_testing_tutorial.md index 879352c2ef0e4e..a3787dcb7eb4d7 100644 --- a/doc/tutorials/fuzz_testing_tutorial.md +++ b/doc/tutorials/fuzz_testing_tutorial.md @@ -3,7 +3,7 @@ stage: none group: Tutorials --- -# Tutorial: Perform fuzz testing in GitLab +# Tutorial: Perform fuzz testing in GitLab **(ULTIMATE)** [Coverage-guided fuzz testing](../user/application_security/coverage_fuzzing/index.md#coverage-guided-fuzz-testing-process): @@ -26,10 +26,6 @@ using JavaScript in GitLab in this tutorial, you: 1. [Run the fuzz test](#run-the-fuzz-test). 1. [Fix the vulnerabilities](#fix-the-vulnerabilities). -Prerequisites: - -- TBC - ## Fork the project template First, to create a project to try out fuzz testing in, you must fork the `fuzz-testing` project template: @@ -39,21 +35,27 @@ First, to create a project to try out fuzz testing in, you must fork the `fuzz-t 1. When forking the project template: - Name the forked project `fuzz-testing-demo`. - Select an appropriate [namespace](../user/namespace/index.md). - - Set [project visibility](../user/public_access.md) to TBC. + - Set [project visibility](../user/public_access.md) to **Private**. -You have now created a project to try out fuzz testing. +You have successfully forked the `fuzz-testing` project template. Before you can +start fuzz testing, remove the relationship between the project template and the fork: -## Create the fuzz targets +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced**. +1. In the **Remove fork relationship** section, select **Remove fork relationship**. + Enter the name of the project when prompted. -Before you begin, make sure you have [forked the project template](#fork-the-project-template). +Your project is ready and you can now start creating the fuzz test. -Now you create the fuzz targets. A fuzz target is a function or program that, -given an input, makes a call to the application being tested. +## Create the fuzz targets -In this example, the fuzz targets call a function of the `my-tools.js` file using +Now you have a project, you create the fuzz targets. A fuzz target is a function +or program that, given an input, makes a call to the application being tested. + +In this tutorial, the fuzz targets call a function of the `my-tools.js` file using a random buffer as a parameter. -To create the two fuzz targets, you create : +To create the two fuzz target files: 1. On the top bar, select **Main menu > Projects** and select the `fuzz-testing-demo` project. 1. Create a file in the root directory of the project. @@ -72,8 +74,11 @@ To create the two fuzz targets, you create : } ``` + You can also copy this code from the `fuzz-testing-demo/fuzzers/fuzz-sayhello.js` + project file. + 1. Name the **Target Branch** `add-fuzz-test` and write a descriptive commit message. - - Do not select the **Start a new merge request with these changes** checkbox. + - Do not select the **Start a new merge request with these changes** checkbox yet. 1. Select **Commit changes**. 1. Return to the root directory of the project. 1. Make sure you are in the `add-fuzz-test` branch. @@ -90,6 +95,9 @@ To create the two fuzz targets, you create : } ``` + You can also copy this code from the `fuzz-testing-demo/fuzzers/fuzz-readme.js` + project file. + 1. Write a descriptive commit message. 1. Make sure the **Target Branch** is `add-fuzz-test`. 1. Select **Commit changes**. @@ -99,7 +107,9 @@ You now have two fuzz targets that can make calls to the application being teste ## Enable coverage-guided fuzz testing To enable coverage-guided fuzz testing, you next create a GitLab CI pipeline running -the `gitlab-cov-fuzz` CLI to execute the fuzzer on the two fuzz targets: +the `gitlab-cov-fuzz` CLI to execute the fuzzer on the two fuzz targets. + +To create the pipeline file: 1. Make sure you are in the `add-fuzz-test` branch. 1. In the root directory of the `fuzz-testing-demo` project, create a new file. @@ -107,14 +117,16 @@ the `gitlab-cov-fuzz` CLI to execute the fuzzer on the two fuzz targets: ```YAML image: node:18 + stages: - fuzz + include: - template: Coverage-Fuzzing.gitlab-ci.yml readme_fuzz_target: extends: .fuzz_base - tags: [saas-linux-large-amd64] # this is not mandatory + tags: [saas-linux-large-amd64] variables: COVFUZZ_ADDITIONAL_ARGS: '--fuzzTime=60' script: @@ -123,7 +135,7 @@ the `gitlab-cov-fuzz` CLI to execute the fuzzer on the two fuzz targets: hello_fuzzing_target: extends: .fuzz_base - tags: [saas-linux-large-amd64] # this is not mandatory + tags: [saas-linux-large-amd64] variables: COVFUZZ_ADDITIONAL_ARGS: '--fuzzTime=60' script: @@ -136,6 +148,9 @@ the `gitlab-cov-fuzz` CLI to execute the fuzzer on the two fuzz targets: - Two jobs, `readme_fuzz_target` and `hello_fuzzing_target`. Each job runs using the `jsfuzz` engine, which reports unhandled exceptions as crashes. + You can also copy this code from the `fuzz-testing-demo/fuzzers/fuzzers.yml` + project file. + 1. Write a descriptive commit message. 1. Make sure the **Target Branch** is `add-fuzz-test`. 1. Select **Commit changes**. @@ -168,7 +183,9 @@ You have successfully run the fuzz test. The fuzz test identified two security vulnerabilities. To fix those vulnerabilities, you must catch them in the functions of the `my-tools.js` library. -1. Make sure you are in the `add-fuzz-test` branch. +To create the `my-tools.js` file: + +1. Make sure you are in the `add-fuzz-test` branch of the project. 1. Go to the root directory of your project and open the `my-tools.js` file. 1. Replace the contents of this file with the following code: @@ -210,9 +227,12 @@ vulnerabilities, you must catch them in the functions of the `my-tools.js` libra } ``` + You can also copy the code from the `fuzz-testing-demo/javascript/my-tools.js` + project file. + 1. Select **Commit changes**. This triggers another pipeline to run another fuzz test. -1. When the pipeline is finished, check the merge request page. You should see - that the security scan detected no new vulnerabilities. +1. When the pipeline is finished, check the merge request **Overview** page. You + should see that the security scan detected no new potential vulnerabilities. 1. Merge your changes. Congratulations, you've successfully run a fuzz test and fixed the identified -- GitLab From 807676b71b2831cd53539ac8bf59a9d0adaeafae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Charri=C3=A8re?= Date: Thu, 6 Apr 2023 10:27:40 +0000 Subject: [PATCH 08/11] Correct syntax labels --- doc/tutorials/fuzz_testing_tutorial.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/tutorials/fuzz_testing_tutorial.md b/doc/tutorials/fuzz_testing_tutorial.md index a3787dcb7eb4d7..71e73f129a6485 100644 --- a/doc/tutorials/fuzz_testing_tutorial.md +++ b/doc/tutorials/fuzz_testing_tutorial.md @@ -61,7 +61,7 @@ To create the two fuzz target files: 1. Create a file in the root directory of the project. 1. Name the file `fuzz-sayhello.js` and add the following code: - ```Javascript + ```javascript let tools = require('./my-tools') function fuzz(buf) { @@ -84,7 +84,7 @@ To create the two fuzz target files: 1. Make sure you are in the `add-fuzz-test` branch. 1. Create the second file named `fuzz-readme.js` and add the following code: - ```Javascript + ```javascript let tools = require('./my-tools') function fuzz(buf) { const text = buf.toString() @@ -115,7 +115,7 @@ To create the pipeline file: 1. In the root directory of the `fuzz-testing-demo` project, create a new file. 1. Name the file `.gitlab-ci.yml` and add the following code: - ```YAML + ```yaml image: node:18 stages: @@ -189,7 +189,7 @@ To create the `my-tools.js` file: 1. Go to the root directory of your project and open the `my-tools.js` file. 1. Replace the contents of this file with the following code: - ```Javascript + ```javascript const fs = require('fs') function sayHello(name) { -- GitLab From ecc7a959702411d67bcad71b76eddc9027cd04ce Mon Sep 17 00:00:00 2001 From: Jonathan Glassman Date: Thu, 6 Apr 2023 11:44:13 +0100 Subject: [PATCH 09/11] Add optional comments --- doc/tutorials/fuzz_testing_tutorial.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/tutorials/fuzz_testing_tutorial.md b/doc/tutorials/fuzz_testing_tutorial.md index 71e73f129a6485..61ca48c2d03457 100644 --- a/doc/tutorials/fuzz_testing_tutorial.md +++ b/doc/tutorials/fuzz_testing_tutorial.md @@ -126,7 +126,7 @@ To create the pipeline file: readme_fuzz_target: extends: .fuzz_base - tags: [saas-linux-large-amd64] + tags: [saas-linux-large-amd64] # Optional variables: COVFUZZ_ADDITIONAL_ARGS: '--fuzzTime=60' script: @@ -135,7 +135,7 @@ To create the pipeline file: hello_fuzzing_target: extends: .fuzz_base - tags: [saas-linux-large-amd64] + tags: [saas-linux-large-amd64] # Optional variables: COVFUZZ_ADDITIONAL_ARGS: '--fuzzTime=60' script: -- GitLab From 884cb27246abdb156733c6488d41ac7d5c500bad Mon Sep 17 00:00:00 2001 From: Jonathan Glassman Date: Thu, 6 Apr 2023 12:42:49 +0100 Subject: [PATCH 10/11] Minor style changes --- doc/tutorials/fuzz_testing_tutorial.md | 53 +++++++++++++------------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/doc/tutorials/fuzz_testing_tutorial.md b/doc/tutorials/fuzz_testing_tutorial.md index 61ca48c2d03457..44a8597c8a51e3 100644 --- a/doc/tutorials/fuzz_testing_tutorial.md +++ b/doc/tutorials/fuzz_testing_tutorial.md @@ -5,30 +5,29 @@ group: Tutorials # Tutorial: Perform fuzz testing in GitLab **(ULTIMATE)** -[Coverage-guided fuzz testing](../user/application_security/coverage_fuzzing/index.md#coverage-guided-fuzz-testing-process): - -- Send unexpected, malformed or random data to an instrumented version of your application - to try to cause unexpected behavior. -- Monitors your application for unstable behaviours and crashes, as this indicates - a bug that you should fix. +[Coverage-guided fuzz testing](../user/application_security/coverage_fuzzing/index.md#coverage-guided-fuzz-testing-process)sends unexpected, malformed or random data to your application, and then monitors +your application for unstable behaviours and crashes. This helps you discover bugs and potential security issues that other QA processes may miss. -Use fuzz testing in addition to other security scanners and your own test processes. +You should use fuzz testing in addition to other security scanners and your own test processes. If you're using GitLab CI/CD, you can run fuzz tests as part your CI/CD workflow. To set up, configure, and perform coverage-guided fuzz testing using JavaScript in GitLab in this tutorial, you: -1. [Fork the project template](#fork-the-project-template). +1. [Fork the project template](#fork-the-project-template) to create a project + to run the fuzz tests in. 1. [Create the fuzz targets](#create-the-fuzz-targets). -1. [Enable coverage-guided fuzz testing](#enable-coverage-guided-fuzz-testing). -1. [Run the fuzz test](#run-the-fuzz-test). -1. [Fix the vulnerabilities](#fix-the-vulnerabilities). +1. [Enable coverage-guided fuzz testing](#enable-coverage-guided-fuzz-testing) + in your forked project. +1. [Run the fuzz test](#run-the-fuzz-test) to identify security vulnerabilities. +1. [Fix any vulnerabilities](#fix-the-vulnerabilities) identified by the fuzz test. ## Fork the project template -First, to create a project to try out fuzz testing in, you must fork the `fuzz-testing` project template: +First, to create a project to try out fuzz testing in, you must fork the `fuzz-testing` +project template: 1. Open the [`fuzz-testing` project template](https://gitlab.com/gitlab-org/tutorial-project-templates/fuzz-testing). 1. [Fork the project template](../user/project/repository/forking_workflow.md). @@ -45,12 +44,14 @@ start fuzz testing, remove the relationship between the project template and the 1. In the **Remove fork relationship** section, select **Remove fork relationship**. Enter the name of the project when prompted. -Your project is ready and you can now start creating the fuzz test. +Your project is ready and you can now create the fuzz test. Next you will create +the fuzz targets. ## Create the fuzz targets -Now you have a project, you create the fuzz targets. A fuzz target is a function -or program that, given an input, makes a call to the application being tested. +Now you have a project for fuzz testing, you create the fuzz targets. A fuzz target +is a function or program that, given an input, makes a call to the application +being tested. In this tutorial, the fuzz targets call a function of the `my-tools.js` file using a random buffer as a parameter. @@ -103,11 +104,12 @@ To create the two fuzz target files: 1. Select **Commit changes**. You now have two fuzz targets that can make calls to the application being tested. +Next you will enable the fuzz testing. ## Enable coverage-guided fuzz testing -To enable coverage-guided fuzz testing, you next create a GitLab CI pipeline running -the `gitlab-cov-fuzz` CLI to execute the fuzzer on the two fuzz targets. +To enable coverage-guided fuzz testing, you create a GitLab CI pipeline running +the `gitlab-cov-fuzz` CLI to execute the fuzz test on the two fuzz targets. To create the pipeline file: @@ -143,10 +145,10 @@ To create the pipeline file: - ./gitlab-cov-fuzz run --engine jsfuzz -- fuzz-sayhello.js ``` - This step adds: - - A `fuzz` stage to your pipeline using a template. - - Two jobs, `readme_fuzz_target` and `hello_fuzzing_target`. Each job runs using the `jsfuzz` - engine, which reports unhandled exceptions as crashes. + This step adds the following to your pipeline: + - A `fuzz` stage using a template. + - Two jobs, `readme_fuzz_target` and `hello_fuzzing_target`. Each job runs using + the `jsfuzz` engine, which reports unhandled exceptions as crashes. You can also copy this code from the `fuzz-testing-demo/fuzzers/fuzzers.yml` project file. @@ -155,9 +157,8 @@ To create the pipeline file: 1. Make sure the **Target Branch** is `add-fuzz-test`. 1. Select **Commit changes**. -You have successfully enabled coverage-guided fuzz testing. - -Next you run the fuzz test using the created pipeline. +You have successfully enabled coverage-guided fuzz testing. Next you will run the +fuzz test using the pipeline you've just created. ## Run the fuzz test @@ -176,12 +177,12 @@ alert on the merge request page. To see more information on each vulnerability, select the individual **Uncaught-exception** links. -You have successfully run the fuzz test. +You have successfully run the fuzz test and identified vulnerabilities to fix. ## Fix the vulnerabilities The fuzz test identified two security vulnerabilities. To fix those -vulnerabilities, you must catch them in the functions of the `my-tools.js` library. +vulnerabilities, you use the `my-tools.js` library. To create the `my-tools.js` file: -- GitLab From fd2eebc982bcd63ecc8cb2e00d367c69eebd5ce8 Mon Sep 17 00:00:00 2001 From: Kati Paizee Date: Thu, 6 Apr 2023 15:57:56 +0000 Subject: [PATCH 11/11] Apply KP suggestions --- doc/tutorials/fuzz_testing_tutorial.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/tutorials/fuzz_testing_tutorial.md b/doc/tutorials/fuzz_testing_tutorial.md index 44a8597c8a51e3..5a8209d971622a 100644 --- a/doc/tutorials/fuzz_testing_tutorial.md +++ b/doc/tutorials/fuzz_testing_tutorial.md @@ -1,12 +1,13 @@ --- -stage: none -group: Tutorials +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Perform fuzz testing in GitLab **(ULTIMATE)** -[Coverage-guided fuzz testing](../user/application_security/coverage_fuzzing/index.md#coverage-guided-fuzz-testing-process)sends unexpected, malformed or random data to your application, and then monitors -your application for unstable behaviours and crashes. +[Coverage-guided fuzz testing](../user/application_security/coverage_fuzzing/index.md#coverage-guided-fuzz-testing-process) sends unexpected, malformed, or random data to your application, and then monitors +your application for unstable behaviors and crashes. This helps you discover bugs and potential security issues that other QA processes may miss. @@ -14,7 +15,7 @@ You should use fuzz testing in addition to other security scanners and your own If you're using GitLab CI/CD, you can run fuzz tests as part your CI/CD workflow. To set up, configure, and perform coverage-guided fuzz testing -using JavaScript in GitLab in this tutorial, you: +using JavaScript in this tutorial, you: 1. [Fork the project template](#fork-the-project-template) to create a project to run the fuzz tests in. @@ -108,7 +109,7 @@ Next you will enable the fuzz testing. ## Enable coverage-guided fuzz testing -To enable coverage-guided fuzz testing, you create a GitLab CI pipeline running +To enable coverage-guided fuzz testing, create a CI/CD pipeline running the `gitlab-cov-fuzz` CLI to execute the fuzz test on the two fuzz targets. To create the pipeline file: -- GitLab