Merge pull request #2928 from steven-zou/master

Update document for Clair user guide

docs/user_guide.md

@@ -14,6 +14,7 @@ This guide walks you through the fundamentals of using Harbor. You'll learn how
 * Pull and push images using Docker client.
 * Delete repositories and images.
 * Content trust.  
+* Vulnerability scanning via Clair.
 
 ## Role Based Access Control(RBAC)  
 
@@ -248,3 +249,71 @@ If you are using a self-signed cert, make sure to copy the CA cert into ```/etc/
 
 When an image is signed, it has a tick shown in UI; otherwise, a cross sign(X) is displayed instead.  
 ![browse project](img/content_trust.png)
+
+### Vulnerability scanning via Clair 
+**CAUTION: Clair is an optional component, please make sure you have already installed it in your Harbor instance before you go through this section.**
+
+Static analysis of vulnerabilities is provided through open source project [Clair](https://github.com/coreos/clair). You can initiate scanning on a particular image, or on all images in Harbor. Additionally, you can also set a policy to scan all the images at a specified time everyday.
+
+**Vulnerability metadata** 
+
+Clair depends on the vulnerability metadata to complete the analysis process. After the first initial installation, Clair will automatically start to update the metadata database from different vulnerability repositories. The updating process may take a while based on the data size and network connection. If the database has not been fully populated, there is a warning message at the footer of the repository datagrid view.
+![browse project](img/clair_not_ready.png)
+
+The 'database not fully ready' warning message is also displayed in the **'Vulnerability'** tab of **'Configuration'** section under **'Administration'** for your awareness.
+![browse project](img/clair_not_ready2.png)
+
+Once the database is ready, an overall database updated timestamp will be shown in the **'Vulnerability'** tab of **'Configuration'** section under **'Administration'**. Click on the timestamp drop-down list, the timestamps of different namespaces are listed.
+![browse project](img/clair_ready.png)
+
+**Scanning an image** 
+
+Enter your project and locate the specified repository. Expand the tag list via clicking the arrow icon on the left side. For each tag there will be an 'Vulnerability' column to display vulnerability scanning status and related information. You can click on the vertical ellipsis to open a popup menu and then click on 'Scan' to start the vulnerability analysis process. 
+![browse project](img/scan_menu_item.png)
+**NOTES: Only the users with 'Project Admin' role have the privilege to launch the analysis process.**
+
+The analysis process may have the following status that are indicated in the 'Vulnerability' column:
+* **Not Scanned:** The tag has never been scanned.
+* **Queued:** The scanning task is scheduled but not executed yet.
+* **Scanning:** The scanning process is in progress.
+* **Error:** The scanning process failed to complete.
+* **Complete:** The scanning process was successfully completed.
+
+For the **'Not Scanned'** and **'Queued'** statuses, a text label with status information is shown. For the **'Scanning'**, a progress bar will be displayed.
+If an error occurred, you can click on the **'View Log'** link to view the related logs.
+![browse project](img/log_viewer.png)
+
+If the process was successfully completed, a result bar is created. The width of the different colored sections indicates the percentage of features with vulnerabilities for a particular severity level.
+* **Red:** **High** level of vulnerabilities
+* **Orange:** **Medium** level of vulnerabilities
+* **Yellow:** **Low** level of vulnerabilities
+* **Grey:** **Unknown** level of vulnerabilities
+* **Green:** **No** vulnerabilities
+![browse project](img/bar_chart.png)
+
+Move the cursor over the bar, a tooltip with summary report will be displayed. Besides showing the total number of features with vulnerabilities and the total number of features in the scanned image tag, the report also lists the counts of features with vulnerabilities of different severity levels. The completion time of the last analysis process is shown at the bottom of the tooltip.
+![browse project](img/summary_tooltip.png)
+
+Click on the tag name link, the detail page will be opened. Besides the information about the tag, all the vulnerabilities found in the last analysis process will be listed with the related information. You can order or filter the list by columns.
+![browse project](img/tag_detail.png)
+
+**NOTES: You can initiate the vulnerability analysis for a tag at anytime you want as long as the status is not 'Queued' or 'Scanning'.** 
+
+**Scanning all images**
+
+In the **'Vulnerability'** tab of **'Configuration'** section under **'Administration'**, click on the **'SCAN NOW'** button to start the analysis process for all the existing images. 
+
+**NOTES: The scanning process is executed via multiple concurrent asynchronous tasks. There is no guarantee on the order of scanning or the returned results.** 
+![browse project](img/scan_all.png)
+
+To avoid frequently triggering the resource intensive scanning process, the availability of the button is restricted. It can be only triggered once in a predefined period. The next available time will be displayed besides the button.
+![browse project](img/scan_all2.png)
+
+**Scheduled Scan by Policy** 
+
+You can set policies to control the vulnerability analysis process. Currently, two options are available:
+* **None:** No policy is selected.
+* **Daily:** Policy is activated daily. It means an analysis job is scheduled to be executed at the specified time everyday. The scheduled job will scan all the images in Harbor.
+![browse project](img/scan_policy.png)
+
+**NOTES: Once the scheduled job is executed, the completion time of scanning all images will be updated accordingly. Please be aware that the completion time of the images may be different because the execution of analysis for each image may be carried out at different time.**