Merge pull request #11897 from heww/vulns-scanning-docs

docs(scan): add docs about image index scanning

docs/administration/vulnerability-scanning/deployment-security.md

@@ -0,0 +1,10 @@
+---
+title: Deployment security
+weight: 31
+---
+
+Starting in version 2.0, Harbor has added capabilities to check for supported artifact types in the pluggable scanners. It will use the **consumes_mime_types** metadata of the scanner to decide whether a requested artifact is supported by this scanner. For example, helm charts cannot be scanned for vulnerabilities by any of the supported scanners like Clair or Aqua Trivy.
+
+Harbor v2.0 now supports OCI image index, which is a higher-level manifest which points to specific image manifests, ideal for one or more platform. Scanning for OCI image index is also supported, with the scan result of the index being an aggregation of the scan results of the artifacts referenced within.
+
+Harbor has ‘deployment security’ which can prevent artifacts from being pulled if vulnerabilities are discovered. For pulling indexes, ‘deployment security’ will skip this policy checking for the index artifact itself and will only apply policy checking on the referenced artifacts and at the individual artifact level and not on the index as a whole. This means when pulling Redis for ARM for example, it only checks to see if whether Redis for ARM has vulnerabilities and not impacted by whether amd64 has CVEs. This applies to CNABs as well.

docs/administration/vulnerability-scanning/scan-all-artifacts.md

@@ -1,14 +1,14 @@
 ---
-title: Scan All Images
+title: Scan All Artifacts
 weight: 35
 ---
 
-In addition to scanning individual images in projects, you can run global scans on all of the images in a Harbor instance, across all projects.
+In addition to scanning individual artifacts in projects, you can run global scans on all of the artifacts in a Harbor instance, across all projects.
 
 1. Log in to the Harbor interface with an account that has Harbor system administrator privileges.
 1. Expand **Administration**, and select **Interrogation Services**.
-1. Select the **Vulnerability** tab and click **Scan Now** to scan all of the images in all projects.
+1. Select the **Vulnerability** tab and click **Scan Now** to scan all of the artifacts in all projects.
 
-   ![Scan all images](../../../img/scan-all.png)
+   ![Scan all artifacts](../../../img/scan-all.png)
 
 Scanning requires intensive resource consumption. If scanning is in progress, the **Scan Now** button is unavailable.

docs/administration/vulnerability-scanning/scan-individual-artifact.md

@@ -0,0 +1,70 @@
+---
+title: Scan Individual Artifacts
+weight: 30
+---
+
+1. Log in to the Harbor interface with an account that has at least project administrator privileges.
+1. Go to **Projects** and select a project.
+1. Select the **Scanner** tab.
+
+    The **Scanner** tab shows the details of the scanner that is currently set as the scanner to use for this project.
+
+    ![Project scanner tab](../../../img/project-scanners.png)
+
+1. Click **Edit** to select a different scanner from the list of scanners that are connected to this Harbor instance, and click **OK**.
+
+   ![Project scanner tab](../../../img/select-scanner.png)
+
+   {{< note >}}
+   If you have selected the **Prevent vulnerable images from running** option in the project **Configuration** tab, the prevention of pulling vulnerable artifacts is determined by the scanner that is set in the project, or by the global default scanner if no scanner is configured specifically for the project. Different scanners might apply different levels of severity to artifact vulnerabilities.
+   {{< /note >}}
+
+1. Select the **Repositories** tab and select a repository.
+
+    For each artifact in the repository, the **Vulnerabilities** column displays the vulnerability scanning status and related information.
+
+    ![Artifact vulnerability status](../../../img/artifact-vulnerability-status.png)
+
+1. Select a artifact, or use the check box at the top to select all artifacts in the repository, and click the **Scan** button to run the vulnerability scan on this artifact.
+
+    ![Scan an artifact](../../../img/scan-artifact.png)
+
+    **NOTE**: You can start a scan at any time, unless the status is **Queued** or **Scanning**. If the database has not been fully populated, you should not run a scan. The following statuses are displayed in the **Vulnerabilities** column:
+
+    * **Not Scanned:** The artifact has never been scanned.
+    * **Unsupported:** The artifact is not supported by the scanner.
+    * **Queued:** The scanning task is scheduled but has not run yet.
+    * **Scanning:** The scanning task is in progress and a progress bar is displayed.
+    * **View log:** The scanning task failed to complete. Click **View Log** link to view the related logs.
+    * **Complete:** The scanning task completed successfully.
+
+    If the process completes successfully, the result indicates the overall severity level, with the total number of vulnerabilities found for each severity level, and the number of fixable vulnerabilities.
+
+    ![Scan result](../../../img/scan-result.png)
+
+    * **Red:** At least one critical vulnerability found
+    * **Orange:** At least one high level vulnerability found
+    * **Yellow:** At least one medium level vulnerability found
+    * **Blue:** At least one low level vulnerability found
+    * **Green:** No vulnerabilities found
+    * **Grey:** Unknown vulnerabilities
+
+1. Hover over the number of fixable vulnerabilities to see a summary of the vulnerability report.
+
+    ![Vulnerability summary](../../../img/vulnerability-summary.png)
+
+1. Click on the artifact digest to see a detailed vulnerability report.
+
+    ![Vulnerability report](../../../img/artifact-detail.png)
+
+    In addition to information about the artifact, all of the vulnerabilities found in the last scan are listed. You can order or filter the list by the different columns. You can also click **Scan** in the report page to run a scan on this artifact.
+
+
+## Vulnerability scanning for OCI image index
+
+When scanning an OCI image index, Harbor will send scan requests for each of the referenced artifact which is supported by the scanner to the scanner. If the image scanning status of any referenced image is **Scanning**, the status for the OCI image index as a whole will also be **Scanning**. The scan for the index is considered successful only if all referenced images are successfully scanned. It is considered limited successful when not all referenced images are successfully scanned but at least one of referenced image is successfully scanned, otherwise it is considered failed.
+
+![Limited successful](../../img/limited-successful-status.png)
+
+
+When an OCI image index is successfully scanned, the summary of the vulnerability report for the OCI image index is aggregated from the individual scan results of the the artifacts referenced by the index. The vulnerability report will show both sets of statistics.

docs/administration/vulnerability-scanning/scan-individual-image.md

@@ -1,59 +0,0 @@
----
-title: Scan Individual Images
-weight: 30
----
-
-1. Log in to the Harbor interface with an account that has at least project administrator privileges.
-1. Go to **Projects** and select a project. 
-1. Select the **Scanner** tab.
-
-    The **Scanner** tab shows the details of the scanner that is currently set as the scanner to use for this project.
-   
-    ![Project scanner tab](../../../img/project-scanners.png)
-
-1. Click **Edit** to select a different scanner from the list of scanners that are connected to this Harbor instance, and click **OK**.
-
-   ![Project scanner tab](../../../img/select-scanner.png)
-   
-   {{< note >}}
-   If you have selected the **Prevent vulnerable images from running** option in the project **Configuration** tab, the prevention of pulling vulnerable images is determined by the scanner that is set in the project, or by the global default scanner if no scanner is configured specifically for the project. Different scanners might apply different levels of severity to image vulnerabilities.
-   {{< /note >}}
-
-1. Select the **Repositories** tab and select a repository.
-
-    For each tag in the repository, the **Vulnerabilities** column displays the vulnerability scanning status and related information.
-   
-    ![Tag vulnerability status](../../../img/tag-vulnerability-status.png)
-
-1. Select a tag, or use the check box at the top to select all tags in the repository, and click the **Scan** button to run the vulnerability scan on this image.
-
-    ![Scan an image](../../../img/scan-image.png)
-
-    **NOTE**: You can start a scan at any time, unless the status is **Queued** or **Scanning**. If the database has not been fully populated, you should not run a scan. The following statuses are displayed in the **Vulnerabilities** column:
-    
-    * **Not Scanned:** The tag has never been scanned.
-    * **Queued:** The scanning task is scheduled but has not run yet.
-    * **Scanning:** The scanning task is in progress and a progress bar is displayed.
-    * **View log:** The scanning task failed to complete. Click **View Log** link to view the related logs.
-    * **Complete:** The scanning task completed successfully.
-
-    If the process completes successfully, the result indicates the overall severity level, with the total number of vulnerabilities found for each severity level, and the number of fixable vulnerabilities.
-
-    ![Scan result](../../../img/scan-result.png)
-
-    * **Red:** At least one critical vulnerability found
-    * **Orange:** At least one high level vulnerability found
-    * **Yellow:** At least one medium level vulnerability found
-    * **Blue:** At least one low level vulnerability found
-    * **Green:** No vulnerabilities found
-    * **Grey:** Unknown vulnerabilities
-
-1. Hover over the number of fixable vulnerabilities to see a summary of the vulnerability report. 
-
-    ![Vulnerability summary](../../../img/vulnerability-summary.png)
-
-1. Click on the tag name to see a detailed vulnerability report.
- 
-    ![Vulnerability report](../../../img/tag-detail.png)
-  
-    In addition to information about the tag, all of the vulnerabilities found in the last scan are listed. You can order or filter the list by the different columns. You can also click **Scan** in the report page to run a scan on this image tag.