Merge branch '429537-reorg-apifuzz-docs' into 'master'

Reorganize documentation for API Fuzzing

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142604



Merged-by: Russell Dickenson <rdickenson@gitlab.com>
Approved-by: Russell Dickenson <rdickenson@gitlab.com>
Co-authored-by: Michael Eddington <meddington@gitlab.com>

doc/ci/yaml/artifacts_reports.md

@@ -103,10 +103,10 @@ as artifacts.
 
 GitLab can display the results of one or more reports in:
 
-- The merge request [security widget](../../user/application_security/api_fuzzing/index.md#view-details-of-an-api-fuzzing-vulnerability).
+- The merge request [security widget](../../user/application_security/api_fuzzing/configuration/enabling_the_analyzer.md#view-details-of-an-api-fuzzing-vulnerability).
 - The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md).
 - The pipeline [**Security** tab](../../user/application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline).
-- The [security dashboard](../../user/application_security/api_fuzzing/index.md#security-dashboard).
+- The [security dashboard](../../user/application_security/api_fuzzing/configuration/enabling_the_analyzer.md#security-dashboard).
 
 ## `artifacts:reports:browser_performance`
 

doc/user/application_security/api_fuzzing/configuration/index.md

+---
+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
+type: reference, howto
+---
+
+# Configuration
+
+- [Requirements](requirements.md)
+- [Enabling the analyzer](enabling_the_analyzer.md)
+- [Customize analyzer settings](customizing_analyzer_settings.md)
+- [Overriding analyzer jobs](overriding_analyzer_jobs.md)
+- [Available CI/CD variables](variables.md)
+- [Offline configuration](offline_configuration.md)

doc/user/application_security/api_fuzzing/configuration/offline_configuration.md

+---
+stage: Secure
+group: Dynamic Analysis
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
+---
+
+# Offline configuration
+
+For self-managed GitLab instances in an environment with limited, restricted, or intermittent access to external resources through the internet, some adjustments are required for the Web API Fuzz testing job to successfully run.
+
+Steps:
+
+1. Host the Docker image in a local container registry.
+1. Set the `SECURE_ANALYZERS_PREFIX` to the local container registry.
+
+The Docker image for API Fuzzing must be pulled (downloaded) from the public registry and then pushed (imported) into a local registry. The GitLab container registry can be used to locally host the Docker image. This process can be performed using a special template. See [loading Docker images onto your offline host](../../offline_deployments/index.md#loading-docker-images-onto-your-offline-host) for instructions.
+
+Once the Docker image is hosted locally, the `SECURE_ANALYZERS_PREFIX` variable is set with the location of the local registry. The variable must be set such that concatenating `/api-security:2` results in a valid image location.
+
+For example, the below line sets a registry for the image `registry.gitlab.com/security-products/api-security:2`:
+
+`SECURE_ANALYZERS_PREFIX: "registry.gitlab.com/security-products"`
+
+NOTE:
+Setting `SECURE_ANALYZERS_PREFIX` changes the Docker image registry location for all GitLab Secure templates.
+
+For more information, see [Offline environments](../../offline_deployments/index.md).

doc/user/application_security/api_fuzzing/configuration/overriding_analyzer_jobs.md

+---
+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
+type: reference, howto
+---
+
+# Overriding API Fuzzing jobs
+
+To override a job definition, (for example, change properties like `variables`, `dependencies`, or [`rules`](../../../../ci/yaml/index.md#rules)),
+declare a job with the same name as the DAST job to override. Place this new job after the template
+inclusion and specify any additional keys under it. For example, this sets the target APIs base URL:
+
+```yaml
+include:
+  - template: Security/API-Fuzzing.gitlab-ci.yml
+
+apifuzzing_fuzz:
+  variables:
+    FUZZAPI_TARGET_URL: https://target/api
+```

doc/user/application_security/api_fuzzing/configuration/requirements.md

+---
+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
+type: reference, howto
+---
+
+# Requirements
+
+- A web API using one of the supported API types:
+  - REST API
+  - SOAP
+  - GraphQL
+  - Form bodies, JSON, or XML
+- An API specification in one of the following formats:
+  - [OpenAPI v2 or v3 Specification](enabling_the_analyzer.md#openapi-specification)
+  - [GraphQL Schema](enabling_the_analyzer.md#graphql-schema)
+  - [HTTP Archive (HAR)](enabling_the_analyzer.md#http-archive-har)
+  - [Postman Collection v2.0 or v2.1](enabling_the_analyzer.md#postman-collection)
+- [GitLab Runner](../../../../ci/runners/index.md) available, with the
+  [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html) on Linux/amd64.
+- Target application deployed. For more details, read [Deployment options](#application-deployment-options).
+- `fuzz` stage added to the CI/CD pipeline definition. This should be added after the deploy step, for example:
+
+  ```yaml
+  stages:
+    - build
+    - test
+    - deploy
+    - fuzz
+  ```
+
+## Recommendations
+
+- Configure runners to use the [always pull policy](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy) to run the latest versions of the analyzers.
+- By default, API Fuzzing downloads all artifacts defined by previous jobs in the pipeline. If
+  your API Fuzzing job does not rely on `environment_url.txt` to define the URL under test or any other files created
+  in previous jobs, we recommend you don't download artifacts. To avoid downloading
+  artifacts, extend the analyzer CI/CD job to specify no dependencies. For example, for the DAST proxy-based analyzer add the following to your `.gitlab-ci.yml` file:
+
+  ```yaml
+  apifuzzer_fuzz:
+    dependencies: []
+  ```
+
+## Application deployment options
+
+API Fuzzing requires a deployed application to be available to scan.
+
+Depending on the complexity of the target application, there are a few options as to how to deploy and configure
+the API Fuzzing template.
+
+### Review Apps
+
+Review Apps are the most involved method of deploying your API Fuzzing target application. To assist in the process,
+we created a Review App deployment using Google Kubernetes Engine (GKE). This example can be found in our
+[Review Apps - GKE](https://gitlab.com/gitlab-org/security-products/demos/dast/review-app-gke) project, along with detailed
+instructions in the [README.md](https://gitlab.com/gitlab-org/security-products/demos/dast/review-app-gke/-/blob/master/README.md)
+on how to configure Review Apps for DAST.
+
+### Docker Services
+
+If your application uses Docker containers you have another option for deploying and scanning with API Fuzzing.
+After your Docker build job completes and your image is added to your container registry, you can use the image as a
+[service](../../../../ci/services/index.md).
+
+By using service definitions in your `.gitlab-ci.yml`, you can scan services with the DAST analyzer.
+
+When adding a `services` section to the job, the `alias` is used to define the hostname that can be used to access the service. In the following example, the `alias: yourapp` portion of the `dast` job definition means that the URL to the deployed application uses `yourapp` as the hostname (`https://yourapp/`).
+
+```yaml
+stages:
+  - build
+  - fuzz
+
+include:
+  - template: API-Fuzzing.gitlab-ci.yml
+
+# Deploys the container to the GitLab container registry
+deploy:
+  services:
+  - name: docker:dind
+    alias: dind
+  image: docker:20.10.16
+  stage: build
+  script:
+    - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
+    - docker pull $CI_REGISTRY_IMAGE:latest || true
+    - docker build --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:latest .
+    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
+    - docker push $CI_REGISTRY_IMAGE:latest
+
+apifuzzer_fuzz:
+  services: # use services to link your app container to the dast job
+    - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
+      alias: yourapp
+
+variables:
+  FUZZAPI_TARGET_URL: https://yourapp
+```
+
+Most applications depend on multiple services such as databases or caching services. By default, services defined in the services fields cannot communicate
+with each another. To allow communication between services, enable the `FF_NETWORK_PER_BUILD` [feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags).
+
+```yaml
+variables:
+  FF_NETWORK_PER_BUILD: "true" # enable network per build so all services can communicate on the same network
+
+services: # use services to link the container to the dast job
+  - name: mongo:latest
+    alias: mongo
+  - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
+    alias: yourapp
+```

doc/user/application_security/api_fuzzing/configuration/variables.md

+---
+stage: Secure
+group: Dynamic Analysis
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
+---
+
+# Available CI/CD variables
+
+| CI/CD variable                                              | Description |
+|-------------------------------------------------------------|-------------|
+| `SECURE_ANALYZERS_PREFIX`                                   | Specify the Docker registry base address from which to download the analyzer. |
+| `FUZZAPI_VERSION`                                           | Specify API Fuzzing container version. Defaults to `2`. |
+| `FUZZAPI_IMAGE_SUFFIX`                                      | Specify a container image suffix. Defaults to none. |
+| `FUZZAPI_API_PORT`                                          | Specify the communication port number used by API Fuzzing engine. Defaults to `5500`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367734) in GitLab 15.5. |
+| `FUZZAPI_TARGET_URL`                                        | Base URL of API testing target. |
+| `FUZZAPI_CONFIG`                                            | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/276395) in GitLab 13.12, replaced with default `.gitlab/gitlab-api-fuzzing-config.yml`. API Fuzzing configuration file. |
+|[`FUZZAPI_PROFILE`](customizing_analyzer_settings.md#api-fuzzing-profiles)                   | Configuration profile to use during testing. Defaults to `Quick-10`. |
+|[`FUZZAPI_EXCLUDE_PATHS`](customizing_analyzer_settings.md#exclude-paths)                    | Exclude API URL paths from testing. |
+|[`FUZZAPI_EXCLUDE_URLS`](customizing_analyzer_settings.md#exclude-urls)                      | Exclude API URL from testing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357195) in GitLab 14.10. |
+|[`FUZZAPI_EXCLUDE_PARAMETER_ENV`](customizing_analyzer_settings.md#exclude-parameters)       | JSON string containing excluded parameters. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292196) in GitLab 14.10. |
+|[`FUZZAPI_EXCLUDE_PARAMETER_FILE`](customizing_analyzer_settings.md#exclude-parameters)      | Path to a JSON file containing excluded parameters. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292196) in GitLab 14.10. |
+|[`FUZZAPI_OPENAPI`](enabling_the_analyzer.md#openapi-specification)                  | OpenAPI Specification file or URL. |
+|[`FUZZAPI_OPENAPI_RELAXED_VALIDATION`](enabling_the_analyzer.md#openapi-specification) | Relax document validation. Default is disabled. Introduced in GitLab 14.7. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/345950`. |
+|[`FUZZAPI_OPENAPI_ALL_MEDIA_TYPES`](enabling_the_analyzer.md#openapi-specification)  | Use all supported media types instead of one when generating requests. Causes test duration to be longer. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. |
+|[`FUZZAPI_OPENAPI_MEDIA_TYPES`](enabling_the_analyzer.md#openapi-specification)  | Colon (`:`) separated media types accepted for testing. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. |
+|[`FUZZAPI_HAR`](enabling_the_analyzer.md#http-archive-har)                           | HTTP Archive (HAR) file. |
+|[`FUZZAPI_GRAPHQL`](enabling_the_analyzer.md#graphql-schema)                         | Path to GraphQL endpoint, for example `/api/graphql`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352780) in GitLab 15.4. |
+|[`FUZZAPI_GRAPHQL_SCHEMA`](enabling_the_analyzer.md#graphql-schema)                  | A URL or filename for a GraphQL schema in JSON format. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352780) in GitLab 15.4. |
+|[`FUZZAPI_POSTMAN_COLLECTION`](enabling_the_analyzer.md#postman-collection)          | Postman Collection file. |
+|[`FUZZAPI_POSTMAN_COLLECTION_VARIABLES`](enabling_the_analyzer.md#postman-variables) | Path to a JSON file to extract Postman variable values. The support for comma-separated (`,`) files was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1. |
+|[`FUZZAPI_OVERRIDES_FILE`](customizing_analyzer_settings.md#overrides)                       | Path to a JSON file containing overrides. |
+|[`FUZZAPI_OVERRIDES_ENV`](customizing_analyzer_settings.md#overrides)                        | JSON string containing headers to override. |
+|[`FUZZAPI_OVERRIDES_CMD`](customizing_analyzer_settings.md#overrides)                        | Overrides command. |
+|[`FUZZAPI_OVERRIDES_CMD_VERBOSE`](customizing_analyzer_settings.md#overrides)                | When set to any value. It shows overrides command output as part of the job output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334578) in GitLab 14.8. |
+|`FUZZAPI_PRE_SCRIPT`                                         | Run user command or script before scan session starts. |
+|`FUZZAPI_POST_SCRIPT`                                        | Run user command or script after scan session has finished. |
+|[`FUZZAPI_OVERRIDES_INTERVAL`](customizing_analyzer_settings.md#overrides)                   | How often to run overrides command in seconds. Defaults to `0` (once). |
+|[`FUZZAPI_HTTP_USERNAME`](customizing_analyzer_settings.md#http-basic-authentication)        | Username for HTTP authentication. |
+|[`FUZZAPI_HTTP_PASSWORD`](customizing_analyzer_settings.md#http-basic-authentication)        | Password for HTTP authentication. |
+|[`FUZZAPI_HTTP_PASSWORD_BASE64`](customizing_analyzer_settings.md#http-basic-authentication) | Password for HTTP authentication, Base64-encoded. [Introduced](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing-src/-/merge_requests/702) in GitLab 15.4. |

doc/user/application_security/api_fuzzing/create_har_files.md

@@ -4,7 +4,7 @@ group: Dynamic Analysis
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# HTTP Archive format
+# Create HAR Files
 
 DETAILS:
 **Tier:** Ultimate
@@ -14,7 +14,7 @@ HTTP Archive (HAR) format files are an industry standard for exchanging informat
 requests and HTTP responses. A HAR file's content is JSON formatted, containing browser interactions
 with a web site. The file extension `.har` is commonly used.
 
-The HAR files can be used to perform [web API Fuzz Testing](index.md#http-archive-har) as part of
+The HAR files can be used to perform [web API Fuzz Testing](configuration/enabling_the_analyzer.md#http-archive-har) as part of
 your [GitLab CI/CD](../../../ci/index.md) pipelines.
 
 WARNING:
@@ -82,7 +82,7 @@ To verify the HAR contains all requests, use an online HAR viewer, for example:
 
 [Insomnia API Client](https://insomnia.rest/) is an API design tool that among many uses, helps
 you to design, describe, and test your API. You can also use it to generate HAR files that can be
-used in [Web API Fuzz Testing](index.md#http-archive-har).
+used in [Web API Fuzz Testing](configuration/enabling_the_analyzer.md#http-archive-har).
 
 #### Create a HAR file with the Insomnia API Client
 

doc/user/application_security/api_fuzzing/performance.md

+---
+stage: Secure
+group: Dynamic Analysis
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
+---
+
+# Performance tuning and testing speed
+
+Security tools that perform API fuzz testing, such as API Fuzzing, perform testing by sending requests to an instance of your running application. The requests are mutated by our fuzzing engine to trigger unexpected behavior that might exist in your application. The speed of an API fuzzing test depends on the following:
+
+- How many requests per second can be sent to your application by our tooling
+- How fast your application responds to requests
+- How many requests must be sent to test the application
+  - How many operations your API is comprised of
+  - How many fields are in each operation (think JSON bodies, headers, query string, cookies, etc.)
+
+If API Fuzzing testing job still takes longer than expected after following the advice in this performance guide, reach out to support for further assistance.
+
+## Diagnosing performance issues
+
+The first step to resolving performance issues is to understand what is contributing to the slower-than-expected testing time. Some common issues we see are:
+
+- API Fuzzing is running on a slow or single-CPU GitLab Runner (GitLab Shared Runners are single-CPU)
+- The application deployed to a slow/single-CPU instance and is not able to keep up with the testing load
+- The application contains a slow operation that impacts the overall test speed (> 1/2 second)
+- The application contains an operation that returns a large amount of data (> 500K+)
+- The application contains a large number of operations (> 40)
+
+### The application contains a slow operation that impacts the overall test speed (> 1/2 second)
+
+The API Fuzzing job output contains helpful information about how fast we are testing, how fast each operation being tested responds, and summary information. Let's take a look at some sample output to see how it can be used in tracking down performance issues:
+
+```shell
+API Fuzzing: Loaded 10 operations from: assets/har-large-response/large_responses.har
+API Fuzzing:
+API Fuzzing: Testing operation [1/10]: 'GET http://target:7777/api/large_response_json'.
+API Fuzzing:  - Parameters: (Headers: 4, Query: 0, Body: 0)
+API Fuzzing:  - Request body size: 0 Bytes (0 bytes)
+API Fuzzing:
+API Fuzzing: Finished testing operation 'GET http://target:7777/api/large_response_json'.
+API Fuzzing:  - Excluded Parameters: (Headers: 0, Query: 0, Body: 0)
+API Fuzzing:  - Performed 767 requests
+API Fuzzing:  - Average response body size: 130 MB
+API Fuzzing:  - Average call time: 2 seconds and 82.69 milliseconds (2.082693 seconds)
+API Fuzzing:  - Time to complete: 14 minutes, 8 seconds and 788.36 milliseconds (848.788358 seconds)
+```
+
+This job console output snippet starts by telling us how many operations were found (10), followed by notifications that testing has started on a specific operation and a summary of the operation has been completed. The summary is the most interesting part of this log output. In the summary, we can see that it took API Fuzzing 767 requests to fully test this operation and its related fields. We can also see that the average response time was 2 seconds and the time to complete was 14 minutes for this one operation.
+
+An average response time of 2 seconds is a good initial indicator that this specific operation takes a long time to test. Further, we can see that the response body size is quite large. The large body size is the culprit here, transferring that much data on each request is what takes the majority of that 2 seconds.
+
+For this issue, the team might decide to:
+
+- Use a multi-CPU runner. Using a multi-CPU runner allows API Fuzzing to parallelize the work being performed. This helps lower the test time, but getting the test down under 10 minutes might still be problematic without moving to a high CPU machine due to how long the operation takes to test.
+  - Trade off between how many CPUs and cost.
+- [Exclude this operation](#excluding-slow-operations) from the API Fuzzing test. While this is the simplest, it has the downside of a gap in security test coverage.
+- [Exclude the operation from feature branch API Fuzzing tests, but include it in the default branch test](#excluding-operations-in-feature-branches-but-not-default-branch).
+- [Split up the API Fuzzing testing into multiple jobs](#splitting-a-test-into-multiple-jobs).
+
+The likely solution is to use a combination of these solutions to reach an acceptable test time, assuming your team's requirements are in the 5-7 minute range.
+
+## Addressing performance issues
+
+The following sections document various options for addressing performance issues for API Fuzzing:
+
+- [Using a multi-CPU Runner](#using-a-multi-cpu-runner)
+- [Excluding slow operations](#excluding-slow-operations)
+- [Splitting a test into multiple jobs](#splitting-a-test-into-multiple-jobs)
+- [Excluding operations in feature branches, but not default branch](#excluding-operations-in-feature-branches-but-not-default-branch)
+
+### Using a multi-CPU Runner
+
+One of the easiest performance boosts can be achieved using a multi-CPU runner with API Fuzzing. This table shows statistics collected during benchmarking of a Java Spring Boot REST API. In this benchmark, the target and API Fuzzing share a single runner instance.
+
+| CPU Count            | Request per Second |
+|----------------------|--------------------|
+| 1 CPU (Shared Runner)| 75  |
+| 4 CPU                | 255 |
+| 8 CPU                | 400 |
+
+As we can see from this table, increasing the CPU count of the runner can have a large impact on testing speed/performance.
+
+To use a multi-CPU typically requires deploying a self-managed GitLab Runner onto a multi-CPU machine or cloud compute instance.
+
+When multiple types of GitLab Runners are available for use, the various instances are commonly set up with tags that can be used in the job definition to select a type of runner.
+
+Here is an example job definition for API Fuzzing that adds a `tags` section with the tag `multi-cpu`. The job automatically extends the job definition included through the API Fuzzing template.
+
+```yaml
+apifuzzer_fuzz:
+  tags:
+  - multi-cpu
+```
+
+To verify that API Fuzzing can detect multiple CPUs in the runner, download the `gl-api-security-scanner.log` file from a completed job's artifacts. Search the file for the string `Starting work item processor` and inspect the reported max DOP (degree of parallelism). The max DOP should be greater than or equal to the number of CPUs assigned to the runner. The value is never lower than 2, even on single CPU runners, unless forced through a configuration variable. If the value reported is less than the number of CPUs assigned to the runner, then something is wrong with the runner deployment. If unable to identify the problem, open a ticket with support to assist.
+
+Example log entry:
+
+`17:00:01.084 [INF] <Peach.Web.Core.Services.WebRunnerMachine> Starting work item processor with 2 max DOP`
+
+### Excluding slow operations
+
+In the case of one or two slow operations, the team might decide to skip testing the operations. Excluding the operation is done using the `FUZZAPI_EXCLUDE_PATHS` configuration [variable as explained in this section.](configuration/customizing_analyzer_settings.md#exclude-paths)
+
+In this example, we have an operation that returns a large amount of data. The operation is `GET http://target:7777/api/large_response_json`. To exclude it we provide the `FUZZAPI_EXCLUDE_PATHS` configuration variable with the path portion of our operation URL `/api/large_response_json`.
+
+To verify the operation is excluded, run the API Fuzzing job and review the job console output. It includes a list of included and excluded operations at the end of the test.
+
+```yaml
+apifuzzer_fuzz:
+  variables:
+    FUZZAPI_EXCLUDE_PATHS: /api/large_response_json
+```
+
+Excluding operations from testing could allow some vulnerabilities to go undetected.
+{: .alert .alert-warning}
+
+### Splitting a test into multiple jobs
+
+Splitting a test into multiple jobs is supported by API Fuzzing through the use of [`FUZZAPI_EXCLUDE_PATHS`](configuration/customizing_analyzer_settings.md#exclude-paths) and [`FUZZAPI_EXCLUDE_URLS`](configuration/customizing_analyzer_settings.md#exclude-urls). When splitting a test up, a good pattern is to disable the `apifuzzer_fuzz` job and replace it with two jobs with identifying names. In this example we have two jobs, each job is testing a version of the API, so our names reflect that. However, this technique can be applied to any situation, not just with versions of an API.
+
+The rules we are using in the `apifuzzer_v1` and `apifuzzer_v2` jobs are copied from the [API Fuzzing template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml).
+
+```yaml
+# Disable the main apifuzzer_fuzz job
+apifuzzer_fuzz:
+  rules:
+  - if: $CI_COMMIT_BRANCH
+    when: never
+
+apifuzzer_v1:
+  extends: apifuzzer_fuzz
+  variables:
+    FUZZAPI_EXCLUDE_PATHS: /api/v1/**
+  rules:
+    rules:
+    - if: $API_FUZZING_DISABLED == 'true' || $API_FUZZING_DISABLED == '1'
+      when: never
+    - if: $API_FUZZING_DISABLED_FOR_DEFAULT_BRANCH == 'true' &&
+            $CI_DEFAULT_BRANCH == $CI_COMMIT_REF_NAME
+      when: never
+    - if: $API_FUZZING_DISABLED_FOR_DEFAULT_BRANCH == '1' &&
+            $CI_DEFAULT_BRANCH == $CI_COMMIT_REF_NAME
+      when: never
+    - if: $CI_COMMIT_BRANCH &&
+          $CI_GITLAB_FIPS_MODE == "true"
+      variables:
+          FUZZAPI_IMAGE_SUFFIX: "-fips"
+    - if: $CI_COMMIT_BRANCH
+
+apifuzzer_v2:
+  variables:
+    FUZZAPI_EXCLUDE_PATHS: /api/v2/**
+  rules:
+    rules:
+    - if: $API_FUZZING_DISABLED == 'true' || $API_FUZZING_DISABLED == '1'
+      when: never
+    - if: $API_FUZZING_DISABLED_FOR_DEFAULT_BRANCH &&
+            $CI_DEFAULT_BRANCH == $CI_COMMIT_REF_NAME
+      when: never
+    - if: $CI_COMMIT_BRANCH &&
+          $CI_GITLAB_FIPS_MODE == "true"
+      variables:
+          FUZZAPI_IMAGE_SUFFIX: "-fips"
+    - if: $CI_COMMIT_BRANCH
+```
+
+### Excluding operations in feature branches, but not default branch
+
+In the case of one or two slow operations, the team might decide to skip testing the operations, or exclude them from feature branch tests, but include them for default branch tests. Excluding the operation is done using the `FUZZAPI_EXCLUDE_PATHS` configuration [variable as explained in this section.](configuration/customizing_analyzer_settings.md#exclude-paths)
+
+In this example, we have an operation that returns a large amount of data. The operation is `GET http://target:7777/api/large_response_json`. To exclude it we provide the `FUZZAPI_EXCLUDE_PATHS` configuration variable with the path portion of our operation URL `/api/large_response_json`. Our configuration disables the main `apifuzzer_fuzz` job and creates two new jobs `apifuzzer_main` and `apifuzzer_branch`. The `apifuzzer_branch` is set up to exclude the long operation and only run on non-default branches (for example, feature branches). The `apifuzzer_main` branch is set up to only execute on the default branch (`main` in this example). The `apifuzzer_branch` jobs run faster, allowing for quick development cycles, while the `apifuzzer_main` job which only runs on default branch builds, takes longer to run.
+
+To verify the operation is excluded, run the API Fuzzing job and review the job console output. It includes a list of included and excluded operations at the end of the test.
+
+```yaml
+# Disable the main job so we can create two jobs with
+# different names
+apifuzzer_fuzz:
+  rules:
+  - if: $CI_COMMIT_BRANCH
+    when: never
+
+# API Fuzzing for feature branch work, excludes /api/large_response_json
+apifuzzer_branch:
+  extends: apifuzzer_fuzz
+  variables:
+    FUZZAPI_EXCLUDE_PATHS: /api/large_response_json
+  rules:
+    rules:
+    - if: $API_FUZZING_DISABLED == 'true' || $API_FUZZING_DISABLED == '1'
+      when: never
+    - if: $API_FUZZING_DISABLED_FOR_DEFAULT_BRANCH &&
+            $CI_DEFAULT_BRANCH == $CI_COMMIT_REF_NAME
+      when: never
+    - if: $CI_COMMIT_BRANCH &&
+          $CI_GITLAB_FIPS_MODE == "true"
+      variables:
+          FUZZAPI_IMAGE_SUFFIX: "-fips"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+      when: never
+    - if: $CI_COMMIT_BRANCH
+
+# API Fuzzing for default branch (main in our case)
+# Includes the long running operations
+apifuzzer_main:
+  extends: apifuzzer_fuzz
+    rules:
+    - if: $API_FUZZING_DISABLED == 'true' || $API_FUZZING_DISABLED == '1'
+      when: never
+    - if: $API_FUZZING_DISABLED_FOR_DEFAULT_BRANCH &&
+            $CI_DEFAULT_BRANCH == $CI_COMMIT_REF_NAME
+      when: never
+    - if: $CI_COMMIT_BRANCH &&
+          $CI_GITLAB_FIPS_MODE == "true"
+      variables:
+          FUZZAPI_IMAGE_SUFFIX: "-fips"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```

doc/user/application_security/configuration/index.md

@@ -68,7 +68,7 @@ You can configure the following security controls:
   - Select **Configure with a merge request** to create a merge request with the changes required to
     enable Secret Detection. For more details, read [Use an automatically configured merge request](../secret_detection/index.md#use-an-automatically-configured-merge-request).
 - [API Fuzzing](../api_fuzzing/index.md)
-  - Select **Enable API Fuzzing** to use API Fuzzing for the current project. For more details, read [API Fuzzing](../../../user/application_security/api_fuzzing/index.md#enable-web-api-fuzzing).
+  - Select **Enable API Fuzzing** to use API Fuzzing for the current project. For more details, read [API Fuzzing](../../../user/application_security/api_fuzzing/configuration/enabling_the_analyzer.md).
 - [Coverage Fuzzing](../coverage_fuzzing/index.md)
   - Can be configured with `.gitlab-ci.yml`. For more details, read [Coverage Fuzzing](../../../user/application_security/coverage_fuzzing/index.md#enable-coverage-guided-fuzz-testing).
 

doc/user/application_security/offline_deployments/index.md

@@ -95,7 +95,7 @@ above. You can find more information at each of the pages below:
 - [SAST offline directions](../sast/index.md#running-sast-in-an-offline-environment)
 - [Secret Detection offline directions](../secret_detection/index.md#running-secret-detection-in-an-offline-environment)
 - [DAST offline directions](../dast/run_dast_offline.md#run-dast-in-an-offline-environment)
-- [API Fuzzing offline directions](../api_fuzzing/index.md#running-api-fuzzing-in-an-offline-environment)
+- [API Fuzzing offline directions](../api_fuzzing/configuration/offline_configuration.md)
 - [License Scanning offline directions](../../compliance/license_scanning_of_cyclonedx_files/index.md#running-in-an-offline-environment)
 - [Dependency Scanning offline directions](../dependency_scanning/index.md#running-dependency-scanning-in-an-offline-environment)