Merge branch 'update-offline-docs' into 'master'

Update docs to be more consistent with respect to offline use cases

See merge request gitlab-org/gitlab!30539

doc/user/application_security/container_scanning/index.md

@@ -229,25 +229,29 @@ To use Container Scanning in an offline environment, you need:
 
 NOTE: **Note:**
 GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
-meaning the runner may try to pull remote images even if a local copy is available. Set GitLab
-Runner's [`pull_policy` to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy)
-in an offline environment if you prefer using only locally available Docker images.
+meaning the Runner tries to pull Docker images from the GitLab container registry even if a local
+copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy)
+in an offline environment if you prefer using only locally available Docker images. However, we
+recommend keeping the pull policy setting to `always` if not in an offline environment, as this
+enables the use of updated scanners in your CI/CD pipelines.
 
 #### Make GitLab Container Scanning analyzer images available inside your Docker registry
 
-For Container Scanning, import and host the following images from `registry.gitlab.com` to your
-offline [local Docker container registry](../../packages/container_registry/index.md):
+For Container Scanning, import the following default images from `registry.gitlab.com` into your
+[local Docker container registry](../../packages/container_registry/index.md):
 
-- [arminc/clair-db vulnerabilities database](https://hub.docker.com/r/arminc/clair-db)
-- GitLab klar analyzer: `registry.gitlab.com/gitlab-org/security-products/analyzers/klar`
+```plaintext
+registry.gitlab.com/gitlab-org/security-products/analyzers/klar
+https://hub.docker.com/r/arminc/clair-db
+```
 
 The process for importing Docker images into a local offline Docker registry depends on
 **your network security policy**. Please consult your IT staff to find an accepted and approved
-process by which external resources can be imported or temporarily accessed.
-
-Note that these scanners are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database)
+process by which you can import or temporarily access external resources. Note that these scanners
+are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database)
 with new definitions, so consider if you are able to make periodic updates yourself.
-You can read more specific steps on how to do this [below](#automating-container-scanning-vulnerability-database-updates-with-a-pipeline).
+
+For more information, see [the specific steps on how to update an image with a pipeline](#automating-container-scanning-vulnerability-database-updates-with-a-pipeline).
 
 For details on saving and transporting Docker images as a file, see Docker's documentation on
 [`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/),
@@ -255,8 +259,6 @@ For details on saving and transporting Docker images as a file, see Docker's doc
 
 #### Set Container Scanning CI job variables to use local Container Scanner analyzers
 
-Container Scanning can be executed on an offline GitLab Ultimate installation using the following process:
-
 1. [Override the container scanning template](#overriding-the-container-scanning-template) in your `.gitlab-ci.yml` file to refer to the Docker images hosted on your local Docker container registry:
 
    ```yaml

doc/user/application_security/dast/index.md

@@ -523,14 +523,15 @@ To use DAST in an offline environment, you need:
 
 NOTE: **Note:**
 GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
-meaning the runner may try to pull remote images even if a local copy is available. Set GitLab
-Runner's [`pull_policy` to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy)
-in an offline environment if you prefer using only locally available Docker images.
+meaning the Runner tries to pull Docker images from the GitLab container registry even if a local
+copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy)
+in an offline environment if you prefer using only locally available Docker images. However, we
+recommend keeping the pull policy setting to `always` if not in an offline environment, as this
+enables the use of updated scanners in your CI/CD pipelines.
 
 ### Make GitLab DAST analyzer images available inside your Docker registry
 
-For DAST, import the following default DAST analyzer image from `registry.gitlab.com` to your local "offline"
-registry:
+For DAST, import the following default DAST analyzer image from `registry.gitlab.com` to your [local Docker container registry](../../packages/container_registry/index.md):
 
 - `registry.gitlab.com/gitlab-org/security-products/dast:latest`
 
@@ -548,16 +549,18 @@ For details on saving and transporting Docker images as a file, see Docker's doc
 
 ### Set DAST CI job variables to use local DAST analyzers
 
-1. Add the following configuration to your `.gitlab-ci.yml` file. You must replace `image` to refer
-   to the DAST Docker image hosted on your local Docker container registry:
+Add the following configuration to your `.gitlab-ci.yml` file. You must replace `image` to refer to
+the DAST Docker image hosted on your local Docker container registry:
 
-   ```yaml
-   include:
-     - template: DAST.gitlab-ci.yml
+```yaml
+include:
+  - template: DAST.gitlab-ci.yml
+dast:
+  image: registry.example.com/namespace/dast:latest
+```
 
-   dast:
-     image: registry.example.com/namespace/dast:latest
-   ```
+The DAST job should now use local copies of the DAST analyzers to scan your code and generate
+security reports without requiring internet access.
 
 ## Reports
 

doc/user/application_security/dependency_scanning/index.md

@@ -420,32 +420,33 @@ You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security
 ## Running Dependency Scanning in an offline environment
 
 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 dependency scanning jobs to run successfully. For more information, see [Offline environments](../offline_deployments/index.md).
+to external resources through the internet, some adjustments are required for Dependency Scanning
+jobs to run successfully. For more information, see [Offline environments](../offline_deployments/index.md).
 
 ### Requirements for offline Dependency Scanning
 
-The requirements for using Dependency Scanning in an offline environment are:
+Here are the requirements for using Dependency Scanning in an offline environment:
 
 - [Disable Docker-In-Docker](#disabling-docker-in-docker-for-dependency-scanning).
 - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements).
-- Docker Container Registry with locally available copies of dependency scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images.
+- Docker Container Registry with locally available copies of Dependency Scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images.
 - Host an offline Git copy of the [gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/)
 - _Only if scanning Ruby projects_: Host an offline Git copy of the [advisory database](https://github.com/rubysec/ruby-advisory-db).
 - _Only if scanning npm/yarn projects_: Host an offline copy of the [retire.js](https://github.com/RetireJS/retire.js/) [node](https://github.com/RetireJS/retire.js/blob/master/repository/npmrepository.json) and [js](https://github.com/RetireJS/retire.js/blob/master/repository/jsrepository.json) advisory databases.
 
 NOTE: **Note:**
 GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
-meaning the runner will try to pull Docker images from the GitLab container registry even if a local
+meaning the Runner tries to pull Docker images from the GitLab container registry even if a local
 copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy)
-in an offline environment, if you prefer using only locally available Docker images. However, we
-recommend keeping the pull policy setting to `always` as it will better enable updated scanners to
-be utilized within your CI/CD pipelines.
+in an offline environment if you prefer using only locally available Docker images. However, we
+recommend keeping the pull policy setting to `always` if not in an offline environment, as this
+enables the use of updated scanners in your CI/CD pipelines.
 
 ### Make GitLab Dependency Scanning analyzer images available inside your Docker registry
 
-For Dependency Scanning, import Docker images ([supported languages and frameworks](#supported-languages-and-package-managers))
-from `registry.gitlab.com` to your offline Docker registry. The Dependency Scanning analyzer
-Docker images are:
+For Dependency Scanning with all [supported languages and frameworks](#supported-languages-and-package-managers),
+import the following default Dependency Scanning analyzer images from `registry.gitlab.com` into
+your [local Docker container registry](../../packages/container_registry/index.md):
 
 ```plaintext
 registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium:2
@@ -465,10 +466,10 @@ For details on saving and transporting Docker images as a file, see Docker's doc
 [`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/),
 [`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/).
 
-### Set Dependency Scanning CI config for "offline" use
+### Set Dependency Scanning CI job variables to use local Dependency Scanning analyzers
 
-Below is a general `.gitlab-ci.yml` template to configure your environment for running
-Dependency Scanning offline:
+Add the following configuration to your `.gitlab-ci.yml` file. You must replace
+`DS_ANALYZER_IMAGE_PREFIX` to refer to your local Docker container registry:
 
 ```yaml
 include:

doc/user/application_security/sast/index.md

@@ -527,17 +527,17 @@ To use SAST in an offline environment, you need:
 
 NOTE: **Note:**
 GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
-meaning the runner will try to pull Docker images from the GitLab container registry even if a local
+meaning the Runner tries to pull Docker images from the GitLab container registry even if a local
 copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy)
 in an offline environment if you prefer using only locally available Docker images. However, we
-recommend keeping the pull policy setting to `always` as it will better enable updated scanners to
-be utilized within your CI/CD pipelines.
+recommend keeping the pull policy setting to `always` if not in an offline environment, as this
+enables the use of updated scanners in your CI/CD pipelines.
 
 ### Make GitLab SAST analyzer images available inside your Docker registry
 
 For SAST with all [supported languages and frameworks](#supported-languages-and-frameworks),
-import the following default SAST analyzer images from `registry.gitlab.com` to your local "offline"
-registry:
+import the following default SAST analyzer images from `registry.gitlab.com` into your
+[local Docker container registry](../../packages/container_registry/index.md):
 
 ```plaintext
 registry.gitlab.com/gitlab-org/security-products/analyzers/bandit:2
@@ -568,10 +568,8 @@ For details on saving and transporting Docker images as a file, see Docker's doc
 
 ### Set SAST CI job variables to use local SAST analyzers
 
-[Override SAST environment variables](#customizing-the-sast-settings) to use to your [local container registry](./analyzers.md#using-a-custom-docker-mirror)
-as the source for SAST analyzer images.
-
-For example, assuming a local Docker registry repository of `localhost:5000/analyzers`:
+Add the following configuration to your `.gitlab-ci.yml` file. You must replace
+`SAST_ANALYZER_IMAGE_PREFIX` to refer to your local Docker container registry:
 
   ```yaml
 include:

doc/user/compliance/license_compliance/index.md

@@ -333,7 +333,7 @@ license_scanning:
 
 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 License Compliance job to
-successfully run.
+successfully run. For more information, see [Offline environments](../../application_security/offline_deployments/index.md).
 
 ### Requirements for offline License Compliance
 
@@ -344,11 +344,11 @@ To use License Compliance in an offline environment, you need:
 
 NOTE: **Note:**
 GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
-meaning the runner will try to pull Docker images from the GitLab container registry even if a local
+meaning the Runner tries to pull Docker images from the GitLab container registry even if a local
 copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy)
 in an offline environment if you prefer using only locally available Docker images. However, we
-recommend leaving the pull policy set to `always`, as it better enables updated scanners to be used
-within your CI/CD pipelines.
+recommend keeping the pull policy setting to `always` if not in an offline environment, as this
+enables the use of updated scanners in your CI/CD pipelines.
 
 ### Make GitLab License Compliance analyzer images available inside your Docker registry
 
@@ -371,10 +371,8 @@ For details on saving and transporting Docker images as a file, see Docker's doc
 
 ### Set License Compliance CI job variables to use local License Compliance analyzers
 
-Override License Compliance environment variables to use to your local container registry
-as the source for License Compliance analyzer images.
-
-For example, this assumes a local Docker registry repository of `localhost:5000/analyzers`:
+Add the following configuration to your `.gitlab-ci.yml` file. You must replace `image` to refer to
+the License Compliance Docker image hosted on your local Docker container registry:
 
 ```yaml
 include: