Starts content organization for a Clair book

clair/docinfo.xml

@@ -0,0 +1,10 @@
+<productname>{productname}</productname>
+<productnumber>{producty}</productnumber>
+<subtitle>Vulnerability reporting with Clair on {productname}</subtitle>
+<abstract>
+    <para>Get started with {productname}</para>
+</abstract>
+<authorgroup>
+    <orgname>Red Hat OpenShift Documentation Team</orgname>
+</authorgroup>
+<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

clair/master.adoc

@@ -0,0 +1,70 @@
+:_content-type: ASSEMBLY
+
+include::modules/attributes.adoc[]
+
+[id="vulnerability-reporting-clair-quay-preface"]
+= Vulnerability reporting with Clair on {productname} preface
+
+The contents within this guide provide an overview of Clair for {productname}, running Clair on standalone {productname} and Operator deployments, and advanced Clair configuration.
+
+[id="vulnerability-reporting-clair-quay-overview"]
+= Vulnerability reporting with Clair on {productname} overview
+
+The content in this guide explains the key purposes and concepts of Clair on {productname}. It also contains information about Clair releases and the location of official Clair containers.
+
+include::modules/clair-vulnerability-scanner-overview.adoc[leveloffset=+1]
+include::modules/clair-vulnerability-scanner-hosts.adoc[leveloffset=+2]
+include::modules/clair-concepts.adoc[leveloffset=+1]
+// include::modules/internal-api.adoc[leveloffset=+2]
+include::modules/clair-authentication.adoc[leveloffset=+2]
+//include::modules/testing-clair.adoc[leveloffset=+1]
+include::modules/clair-updaters.adoc[leveloffset=+2]
+include::modules/clair-updater-urls.adoc[leveloffset=+3]
+include::modules/about-clair.adoc[leveloffset=+1]
+include::modules/clair-cve.adoc[leveloffset=+2]
+include::modules/fips-overview.adoc[leveloffset=+2]
+
+[id="testing-clair-with-quay"]
+= Clair on {productname}
+
+This guide contains procedures for running Clair on {productname} in both standalone and {ocp} Operator deployments.
+
+include::modules/clair-standalone-configure.adoc[leveloffset=+1]
+
+include::modules/clair-openshift.adoc[leveloffset=+1]
+// include::modules/clair-openshift-manual.adoc[leveloffset=+2]
+
+include::modules/clair-testing.adoc[leveloffset=+1]
+
+
+[id="advanced-clair-configuration"]
+= Advanced Clair configuration
+
+Use this section to configure advanced Clair features.
+
+include::modules/clair-unmanaged.adoc[leveloffset=+1]
+include::modules/unmanaging-clair-database.adoc[leveloffset=+2]
+include::modules/configuring-custom-clair-database.adoc[leveloffset=+2]
+
+include::modules/custom-clair-configuration-managed-database.adoc[leveloffset=+1]
+include::modules/managed-clair-database.adoc[leveloffset=+2]
+include::modules/configuring-custom-clair-database-managed.adoc[leveloffset=+2]
+
+include::modules/clair-disconnected.adoc[leveloffset=+1]
+
+
+include::modules/clair-clairctl.adoc[leveloffset=+2]
+include::modules/clair-openshift-config.adoc[leveloffset=+3]
+include::modules/clair-export-bundle.adoc[leveloffset=+3]
+include::modules/clair-openshift-airgap-database.adoc[leveloffset=+3]
+include::modules/clair-openshift-airgap-import-bundle.adoc[leveloffset=+3]
+
+
+include::modules/clair-clairctl-standalone.adoc[leveloffset=+2]
+include::modules/clair-standalone-config-location.adoc[leveloffset=+3]
+include::modules/clair-export-bundle-standalone.adoc[leveloffset=+3]
+include::modules/clair-openshift-airgap-database-standalone.adoc[leveloffset=+3]
+include::modules/clair-openshift-airgap-import-bundle-standalone.adoc[leveloffset=+3]
+
+include::modules/clair-crda-configuration.adoc[leveloffset=+2]
+include::modules/mapping-repositories-to-cpe-information.adoc[leveloffset=+2]

clair/modules

@@ -0,0 +1 @@
+../modules

deploy_quay_on_openshift_op_tng/master.adoc

@@ -91,7 +91,7 @@ include::modules/operator-external-access.adoc[leveloffset=+2]
 include::modules/operator-console-monitoring-alerting.adoc[leveloffset=+2]
 
 
-include::modules/clair-openshift-airgap-update.adoc[leveloffset=+2]
+include::modules/clair-disconnected.adoc[leveloffset=+2]
 include::modules/clair-clairctl.adoc[leveloffset=+3]
 ==== Retrieving the Clair config
 include::modules/clair-openshift-config.adoc[leveloffset=+4]
@@ -111,6 +111,8 @@ include::modules/operator-resize-storage.adoc[leveloffset=+2]
 include::modules/operator-customize-images.adoc[leveloffset=+2]
 include::modules/operator-cloudfront.adoc[leveloffset=+2]
 include::modules/clair-unmanaged.adoc[leveloffset=+3]
+include::modules/unmanaging-clair-database.adoc[leveloffset=+4]
+include::modules/configuring-custom-clair-database.adoc[leveloffset=+4]
 
 
 include::modules/build-enhancements.adoc[leveloffset=+1]

manage_quay/master.adoc

@@ -58,16 +58,25 @@ include::modules/proc_manage-log-storage.adoc[leveloffset=+1]
 :context: security-scanning
 
 
-include::modules/clair-intro2.adoc[leveloffset=+1]
+include::modules/clair-vulnerability-scanner-overview.adoc[leveloffset=+1]
 include::modules/clair-openshift.adoc[leveloffset=+2]
 include::modules/clair-openshift-manual.adoc[leveloffset=+3]
 include::modules/clair-standalone.adoc[leveloffset=+2]
+
+[id="advanced-clair-configuration"]
+= Advanced Clair configuration
+
+Use the content in this section to configure advanced Clair settings.
+
 include::modules/clair-unmanaged.adoc[leveloffset=+2]
+include::modules/unmanaging-clair-database.adoc[leveloffset=+3]
 include::modules/clair-crda-configuration.adoc[leveloffset=+2]
 include::modules/clair-using.adoc[leveloffset=+2]
 include::modules/clair-cve.adoc[leveloffset=+2]
 include::modules/clair-disconnected.adoc[leveloffset=+2]
-include::modules/clair-updater-urls.adoc[leveloffset=+2]
+include::modules/configuring-clair-disconnected-environment.adoc[leveloffset=+3]
+include::modules/mapping-repositories-to-cpe-information.adoc[leveloffset=+3]
+include::modules/clair-vulnerability-scanner-hosts.adoc[leveloffset=+2]
 include::modules/clair-add-info.adoc[leveloffset=+2]
 
 

modules/about-clair.adoc

@@ -0,0 +1,130 @@
+// Module included in the following assemblies:
+//
+// clair/master.adoc
+
+:_content-type: CONCEPT
+[id="about-clair"]
+= About Clair
+
+The content in this section highlights Clair releases, official Clair containers, and information about CVSS enrichment data.
+
+[id="clair-releases"]
+== Clair releases
+
+New versions of Clair are regularly released. The source code needed to build Clair is packaged as an archive and attached to each release. Clair releases can be found at link:https://github.com/quay/clair/releases[Clair releases].
+
+
+Release artifacts also include the `clairctl` command line interface tool, which obtains updater data from the internet by using an open host.
+
+[id="clair-supported-languages"]
+== Clair supported languages
+
+Clair supports the following languages:
+* Python
+* Java (CRDA must be enabled)
+
+[id="clair-containers"]
+== Clair containers
+
+Official downstream Clair containers bundled with {productname} can be found on the link:registry.redhat.io[Red Hat Ecosystem Catalog].
+
+Official upstream containers are packaged and released as a container at link:quay.io/projectquay/clair[Quay.io/projectquay/clair]. The latest tag tracks the Git development branch. Version tags are built from the corresponding release.
+
+////
+
+[id="notifier-pagination"]
+===== Notifier pagination
+
+The URL returned in the callback field takes the client to a paginated result.
+
+The following example shows the callback endpoint specification:
+[source,json]
+----
+GET /notifier/api/v1/notification/{id}?[page_size=N][next=N]
+{
+  page: {
+    size:    int,
+    next:   string, //  if present, the next id to fetch.
+  }
+  notifications: [ Notification… ] // array of notifications; max len == page.size
+}
+----
+.small
+--
+* The `GET` callback request implements a simple paging mechanism.
+* A `page` object accompanying the notification list specifies `next` and `size` fields.
+* The `next` field returned in the page must be provided as the subsequent request's `next` URL parameter to retrieve the next set of notifications.
+* The `size` field will echo back to the request `page_size` parameter.
+
+
+
+* The `page_size` URL parameter controls how many notifications rae returned in a single page. If unprovided, a default of `500` is used.
+* The `next` URL parameter informs Clair of the next set of paginated notifications to return. If not provided, the `0th` page is assumed.
+*
+
+////
+
+////
+
+.Prerequisites
+
+* The Linux `make` command is required to start the local development environment.
+
+* Podman v3.0 or greater. Alternatively, you can use Docker or Docker Compose, however not all versions of Docker or Docker Compose have been tested. As a result, some versions might not work properly.
++
+This guide uses Podman with an implementation of Compose Specification.
+
+* Go v1.16 or greater.
+
+.Procedure
+
+. Enter the following command to close the Clair github repository:
++
+[source,terminal]
+----
+$ git clone git@github.com:quay/clair.git
+----
+
+. Change into the Clair directory by entering the following command:
++
+[source,terminal]
+----
+$ cd clair
+----
+
+. Start the Clair container by entering the following command:
++
+[source,terminal]
+----
+$ podman-compose up -d
+----
+
+After the local development environment starts, the following infrastructure is available to you:
+
+* `localhost:8080`. This includes dashboards and debugging services. You can see Traefik configuration logs in `local-dev/traefik`, where various services are served.
+
+* `localhost:6060`. This includes Clair services.
+
+* {productname}. If started, {productname} will be started in a single node, local storage configuration. A random port will be forwarded from `localhost`. Use `podman port` to view mapping information.
+
+* PostgreSQL. PostgreSQL has a random port forwarded from `localhost` to the database server. See `local-dev/clair/init.sql` for credentials and permissions. Use `podman port` to view mapping information.
+
+[id="testing-clair"]
+== Testing Clair on the local development environment
+
+After starting the Clair container, a {productname} server is forwarded to a random port on the host.
+
+. Locate, and open, the port hosting {productname}.
+
+. Click *Create Account* and create a new user, for example, `admin`.
+
+. Set a password.
+
+. To push to the {productname} container, you must exec into the skopeo container. For example:
++
+[source,terminal]
+----
+$ podman exec -it quay-skopeo /usr/bin/skopeo copy --dst-creds '<user>:<pass>' --dst-tls-verify=false <src> clair-quay:8080/<namespace>/<repo>:<tag>
+----
+
+////

modules/clair-airgap.adoc

@@ -0,0 +1,5 @@
+:_content-type: CONCEPT
+[id="clair-airgap"]
+== Air gapped Clair 
+
+For flexability, Clair supports running updaters in a separate environment and importing the results. This is aimed at supporting installations that reject the Clair cluster from communication with the internet directly. 

modules/clair-authentication.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+// clair/master.adoc
+
+:_content-type: CONCEPT
+[id="clair-authentication"]
+= Clair authentication
+
+In its current iteration, Clair v4 (Clair) handles authentication internally.
+
+[NOTE]
+====
+Previous versions of Clair used JWT Proxy to gate authentication.
+====
+
+Authentication is configured by specifying configuration objects underneath the `auth` key of the configuration. Multiple authentication configurations might be present, but they are used preferentially in the following order:
+
+. PSK. With this authentication configuration, Clair implements JWT-based authentication using a pre-shared key.
+
+. Configuration. For example:
++
+[source,yaml]
+----
+auth:
+  psk:
+    key: >-
+      MDQ4ODBlNDAtNDc0ZC00MWUxLThhMzAtOTk0MzEwMGQwYTMxCg==
+    iss: 'issuer'
+----
++
+In this configuration the `auth` field requires two parameters: `iss`, which is the issuer to validate all incoming requests, and `key`, which is a base64 coded symmetric key for validating the requests.

modules/clair-clairctl-standalone.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// clair/master.adoc
+
+:_content-type: PROCEDURE
+[id="clair-disconnected-standalone-configuration"]
+= Setting up a self-managed deployment of Clair for a disconnected {ocp} cluster
+
+Use the following procedures to set up a self-managed deployment of Clair for a disconnected {ocp} cluster.
+
+[id="clair-clairctl-standalone"]
+== Installing the clairctl command line utility tool for a self-managed Clair deployment on {ocp}
+
+Use the following procedure to install the `clairctl` CLI tool for self-managed Clair deployments on {ocp}.
+
+.Procedure
+
+. Install the `clairctl` program for a self-managed Clair deployment by using the `podman cp` command, for example:
++
+[source,terminal]
+----
+$ sudo podman cp clairv4:/usr/bin/clairctl ./clairctl
+----
+
+. Set the permissions of the `clairctl` file so that it can be executed and run by the user, for example:
++
+[source,terminal]
+----
+$ chmod u+x ./clairctl
+----

modules/clair-clairctl.adoc

@@ -1,17 +1,35 @@
-[[clair-clairctl]]
-= Obtaining clairctl 
+// Module included in the following assemblies:
+//
+// clair/master.adoc
 
-To obtain the `clairctl` program from a Clair deployment in an OpenShift cluster, use the `oc cp` command, for example:
+:_content-type: PROCEDURE
+[id="clair-disconnected-ocp-configuration"]
+= Setting up Clair in a disconnected {ocp} cluster
 
-----
-$ oc -n quay-enterprise cp example-registry-clair-app-64dd48f866-6ptgw:/usr/bin/clairctl ./clairctl
-$ chmod u+x ./clairctl
-----
+Use the following procedures to set up an {ocp} provisioned Clair pod in a disconnected {ocp} cluster.
+
+[id="clair-clairctl-ocp"]
+== Installing the clairctl command line utility tool for {ocp} deployments
 
-For a standalone Clair deployment, use the `podman cp` command, for example:
+Use the following procedure to install the `clairctl` CLI tool for {ocp} deployments.
 
+.Procedure
+
+. Install the `clairctl` program for a Clair deployment in an {ocp} cluster by using the `oc cp` command, for example:
++
+[source,terminal]
 ----
-$ sudo podman cp clairv4:/usr/bin/clairctl ./clairctl
-$ chmod u+x ./clairctl
+$ oc -n quay-enterprise exec example-registry-clair-app-64dd48f866-6ptgw -- cat /usr/bin/clairctl > clairctl
 ----
++
+[NOTE]
+====
+Unofficially, the `clairctl` tool can be downloaded
+====
 
+. Set the permissions of the `clairctl` file so that it can be executed and run by the user, for example:
++
+[source,terminal]
+----
+$ chmod u+x ./clairctl
+----