New scan from web console section

_topic_map.yml

@@ -395,6 +395,9 @@ Topics:
 - Name: Encrypting etcd data
   File: encrypting-etcd
   Distros: openshift-enterprise,openshift-webscale,openshift-origin
+- Name: Scanning pods for vulnerabilities
+  File: pod-vulnerability-scan
+  Distros: openshift-enterprise,openshift-webscale,openshift-origin
 ---
 Name: Authentication and authorization
 Dir: authentication

modules/security-pod-scan-cso.adoc

@@ -0,0 +1,70 @@
+// Module included in the following assemblies:
+//
+// * security/pod-vulnerabilities-scan.adoc
+
+[id="security-pod-scan-cso_{context}"]
+= Running the Container Security Operator
+
+You can start the Container Security Operator from the {product-title}
+web console by selecting and installing that Operator from the Operator Hub,
+as described here.
+
+.Prerequisites
+
+* Have administrator privileges to the {product-title} cluster
+* Have containers that come from a Red Hat Quay or Quay.io registry running on your cluster
+
+.Procedure
+
+. Navigate to *Operators* -> *OperatorHub* and select *Security*.
+
+. Select the *Container Security* Operator, then select *Install*
+to go to the Create Operator Subscription page.
+
+. Check the settings. All namespaces and automatic approval strategy are selected, by default
+
+. Select *Subscribe*. The *Container Security* Operator appears after a few moments on the *Installed Operators* screen.
+
+. Optionally, you can add custom certificates to the CSO. In this example, create a certificate
+named `quay.crt` in the current directory. Then run the following command to add the cert to the CSO:
++
+----
+$ oc create secret generic container-security-operator-extra-certs --from-file=quay.crt -n openshift-operators
+----
+
+. If you added a custom certificate, restart the Operator pod for the new certs to take effect.
+
+. Open the OpenShift Dashboard (`Home` -> `Overview`). A link to
+*Quay Image Security* appears under the status section, with a listing of the number
+of vulnerabilities found so far. Select the link to see a *Quay Image Security breakdown*, as shown in the following figure:
++
+image:image_security.png[Access image scanning data from {product-title} dashboard]
+
+. You can do one of two things at this point to follow up on any detected vulnerabilities:
++
+*  Select the link to the vulnerability. You are taken to the container
+registry that the container came
+from, where you can see information about the vulnerability. The following
+figure shows an example of detected vulnerabilities from a Quay.io registry:
++
+image:cso-registry-vulnerable.png[The CSO points you to a registry containing the vulnerable image]
++
+* Select the namespaces link to go to the *ImageManifestVuln* screen,
+where you can see the name of the selected image
+and all namespaces where that image is running.
+The following figure indicates that a particular vulnerable image
+is running in the `quay-enterprise` namespace:
++
+image:cso-namespace-vulnerable.png[View namespaces a vulnerable image is running in]
+
+At this point, you know what images are vulnerable, what
+you need to do to fix those vulnerabilities,
+and every namespace that the image was run in. So you can:
+
+* Alert anyone running the image that
+they need to correct the vulnerability
+* Stop the images from running by deleting the deployment
+or other object that started the pod that the image is in
+
+Note that if you do delete the pod, it may take several minutes
+for the vulnerability to reset on the dashboard.

modules/security-pod-scan-query-cli.adoc

@@ -0,0 +1,42 @@
+// Module included in the following assemblies:
+//
+// * security/pod-vulnerabilities-scan.adoc
+
+[id="security-pod-scan-query-cli_{context}"]
+= Querying image vulnerabilities from the CLI
+Using the `oc` command, you can display information about
+vulnerabilities detected by the Container Security Operator.
+
+.Prerequisites
+* Be running the Container Security Operator on your
+{product-title} instance
+
+.Procedure
+
+* To query for detected container image vulnerabilities, type:
++
+----
+$ oc get vuln --all-namespaces
+NAMESPACE     NAME              AGE
+default       sha256.ca90...    6m56s
+skynet        sha256.ca90...    9m37s
+----
+
+* To display details for a particular vulnerability, provide the
+vulnerability name and its namespace to the `oc describe` command.
+This example shows an active container whose image includes an RPM package with a vulnerability:
++
+----
+$ oc describe vuln --namespace mynamespace sha256.ac50e3752...
+Name:         sha256.ac50e3752...
+Namespace:    quay-enterprise
+...
+Spec:
+  Features:
+    Name:            nss-util
+    Namespace Name:  centos:7
+    Version:         3.44.0-3.el7
+    Versionformat:   rpm
+    Vulnerabilities:
+      Description: Network Security Services (NSS) is a set of libraries...
+----

security/pod-vulnerability-scan.adoc

@@ -0,0 +1,27 @@
+[id="pod-vulnerability-scan"]
+= Scanning pods for vulnerabilities
+include::modules/common-attributes.adoc[]
+:context: pod-vulnerability-scan
+
+toc::[]
+
+Using the Container Security Operator (CSO), you can access vulnerability
+scan results from the {product-title} web console for container images
+used in active pods on the cluster. The CSO:
+
+* Watches containers associated with pods on all or specified namespaces
+* Queries the container registry where the containers came from for
+vulnerability information, provided an image’s registry is running image
+scanning (such as
+link:https://quay.io[Quay.io] or a
+link:https://access.redhat.com/products/red-hat-quay[Red Hat Quay] registry with Clair scanning)
+* Exposes vulnerabilities via the ImageManifestVuln object in the Kubernetes API
+
+Using the instructions here, the CSO is installed in the `openshift-operators`
+namespace, so it is available to all namespaces on your OpenShift cluster.
+
+//
+include::modules/security-pod-scan-cso.adoc[leveloffset=+1]
+
+//
+include::modules/security-pod-scan-query-cli.adoc[leveloffset=+1]