Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/concepts/api_internal.html b/v4.7.2/concepts/api_internal.html
new file mode 100644
index 0000000000..d9184781fc
--- /dev/null
+++ b/v4.7.2/concepts/api_internal.html
@@ -0,0 +1,244 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Concepts
+The following sections give a conceptual overview of how Clair works internally.
+ + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/concepts/authentication.html b/v4.7.2/concepts/authentication.html
new file mode 100644
index 0000000000..0df0ca5bff
--- /dev/null
+++ b/v4.7.2/concepts/authentication.html
@@ -0,0 +1,246 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Internal
+Internal endpoints are underneath /api/v1/internal and are meant for
+communication between Clair microservices. If Clair is operating in combo mode,
+these endpoints may not exist. Any sort of API ingress should disallow clients
+to talk to these endpoints.
We do not formally expose these APIs in our OpenAPI spec. +Further information and usage is an effort left to the reader.
+Updates Diffs
+The update_diff/ endpoint exposes the api for diffing two update operations.
+This is used by the notifier to determine the added and removed vulnerabilities on security databsae update.
Update Operation
+The update_operation endpoint exposes the api for viewing updaters' activity.
+This is used by the notifier to determine if new updates have occured and triggers an update diff to see what has changed.
AffectedManifest
+The affected_manifest endpoint exposes the api for retreiving affected manifests given a list of Vulnerabilities.
+This is used by the notifier to determine the manifests that need to have a notification generated.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/concepts/indexing.html b/v4.7.2/concepts/indexing.html
new file mode 100644
index 0000000000..51333b2111
--- /dev/null
+++ b/v4.7.2/concepts/indexing.html
@@ -0,0 +1,241 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Authentication
+Previous versions of Clair used jwtproxy to gate authentication. For ease of +building and deployment, v4 handles authentication itself.
+Authentication is configured by specifying configuration objects underneath the
+auth key of the configuration. Multiple authentication configurations may be
+present, but they will be used preferentially in the order laid out below.
PSK
+Clair implements JWT-based authentication using a pre-shared key.
+Configuration
+The auth stanza of the configuration file requires two parameters: iss, which
+is the issuer to validate on all incoming requests; and key, which is a base64
+encoded symmetric key for validating the requests.
auth:
+ psk:
+ key: >-
+ MDQ4ODBlNDAtNDc0ZC00MWUxLThhMzAtOTk0MzEwMGQwYTMxCg==
+ iss: 'issuer'
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/concepts/matching.html b/v4.7.2/concepts/matching.html
new file mode 100644
index 0000000000..3a6d5e1fd4
--- /dev/null
+++ b/v4.7.2/concepts/matching.html
@@ -0,0 +1,242 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Indexing
+The Indexer service is responsble for "indexing a manifest".
+Indexing involves taking a manifest representing a container image and computing its constituent parts. The indexer is trying to discover what packages exist in the image, what distribution the image is derived from, and what package repositories are used within the image. Once this information is computed it is persisted in an IndexReport.
+The IndexReport is an intermediate data structure describing the contents of a container image. This report can be fed to a Matcher node for vulnerability analysis.
+Content Addressability
+ClairV4 treats all manifests and layers as content addressable. In the context of ClairV4 this means once we index a specific manifest we will not index it again unless it's required, and likewise with individual layers. This allows a large reduction in work.
+For example, consider how many images in a registry may use "ubuntu:artful" as a base layer. It could be a large majority of images if the developers prefer basing their images off ubuntu. Treating the layers and manifests as content addressable means we will only fetch and scan the base layer once.
+There are of course conditions where ClairV4 should re-index a manifest.
+When an internal component such as a package scanner is updated, Clair will know to perform the scan with the new package scanner. Clair has enough information to determine that a component has changed and the IndexReport may be different this time around.
+A client can track ClairV4's index_state endpoint to understand when an internal component has changed and subsequently issue re-indexes. See our api guide to learn how to view our api specification.
Summary
+In summary, you should understand that Indexing is the process Clair uses to understand the contents of layers.
+For a more indepth look at indexing check out the ClairCore Documentation
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/concepts/notifications.html b/v4.7.2/concepts/notifications.html
new file mode 100644
index 0000000000..df9f44d21d
--- /dev/null
+++ b/v4.7.2/concepts/notifications.html
@@ -0,0 +1,328 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Matching
+A Matcher node is responsible for matching vulnerabilities to a provided IndexReport.
+Matchers by default are also responsible for keeping the database of vulnerabilities up to date. Matchers will typically run a set of Updaters which periodically probe their data sources for new contents, storing new vulnerabilities in the database when discovered.
+The matcher API is designed to be called often and will always provide the most up-to-date VulnerabilityReport when queried. This VulnerabilityReport summaries both a manifest's contents and any vulnerabilities affecting the contents.
+See our api guide to learn how to view our api specification and work with the Matcher api.
+Remote Matching
+A remote matcher behaves similarly to a matcher, except that it uses api calls to fetch vulnerability data for a provided IndexReport. +Remote matchers are useful when it is not possible to persist data from a given source into the database.
+The crda remote matcher is responsible for fetching vulnerabilities from Red Hat Code Ready Dependency Analytics (CRDA).
+By default, this matcher serves 100 requests per minute.
+The rate-limiting can be lifted by requesting a dedicated API key, which is done via this form.
Summary
+In summary you should understand that a Matcher node provides vulnerability reports given the output of an Indexing process. By default it will also run background Updaters keeping the vulnerability database up-to-date.
+For a more indepth look at indexing check out the ClairCore Documentation
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/concepts/operation.html b/v4.7.2/concepts/operation.html
new file mode 100644
index 0000000000..2647609f49
--- /dev/null
+++ b/v4.7.2/concepts/operation.html
@@ -0,0 +1,229 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Notifications
+ClairV4 implements a notification system.
+The notifier service will keep track of new security database updates and inform an interested client if new or removed vulnerabilites affect an indexed manifest.
+The interested client can subscribe to notifications via several mechanisms:
+-
+
- Webhook delivery +
- AMQP delivery +
- STOMP delivery +
Configuring the notifier is done via the yaml configuration.
+See the "Notifier" object in our config reference
+A Notification
+When the notifier becomes aware of new vulnerabilities affecting a previously indexed manifest, it will use the configured method(s) to issue notifications about the new changes. Any given notification expresses the most severe vulnerability discovered because of the change. This avoids creating a flurry of notifications for the same security database update.
+Once a client receives a notification, it should issue a new request against the matcher to receive an up-to-date vulnerability report.
+The notification schema is the JSON marshaled form of the following types:
+// Reason indicates the catalyst for a notification
+type Reason string
+const (
+ Added Reason = "added"
+ Removed Reason = "removed"
+ Changed Reason = "changed"
+)
+type Notification struct {
+ ID uuid.UUID `json:"id"`
+ Manifest claircore.Digest `json:"manifest"`
+ Reason Reason `json:"reason"`
+ Vulnerability VulnSummary `json:"vulnerability"`
+}
+type VulnSummary struct {
+ Name string `json:"name"`
+ Description string `json:"description"`
+ Package *claircore.Package `json:"package,omitempty"`
+ Distribution *claircore.Distribution `json:"distribution,omitempty"`
+ Repo *claircore.Repository `json:"repo,omitempty"`
+ Severity string `json:"severity"`
+ FixedInVersion string `json:"fixed_in_version"`
+ Links string `json:"links"`
+}
+Webhook Delivery
+See the "Notifier.Webhook" object in the config reference for complete configuration details.
+When you configure notifier for webhook delivery you provide the service with the following pieces of information:
+-
+
- A target URL where the webhook will fire +
- The callback URL where the notifier may be reached including its API path
+
-
+
- e.g. "http://clair-notifier/notifier/api/v1/notifications" +
+
When the notifier has determined an updated security database has changed the affected status of an indexed manifest, it will deliver the following JSON body to the configured target:
+{
+ "notifiction_id": {uuid_string},
+ "callback": {url_to_notifications}
+}
+On receipt, the server can immediately browse to the URL provided in the callback field.
+Pagination
+The URL returned in the callback field brings the client to a paginated result.
+The callback endpoint specification follows:
+GET /notifier/api/v1/notification/{id}?[page_size=N][next=N]
+{
+ page: {
+ size: int, // maximum number of notifications in the response
+ next: string, // if present, the next id to fetch.
+ }
+ notifications: [ Notification… ] // array of notifications; max len == page.size
+}
+The GET callback request implements a simple bare-minimum paging mechanism.
+The "page_size" url param controls how many notifications are returned in a single page. +If not provided a default of 500 is used.
+The "next" url param informs Clair the next set of paged notifications to return. If not provided the 0th page is assumed.
+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 simply echo back the request page_size parameter.
+When the final page is served to the client the returned "page" data structure will not contain a "next" member.
+Therefore the following loop is valid for obtaining all notifications for a notification id in pages of a specified size.
+{ page, notifications } = http.Get("http://clairv4/notifier/api/v1/notifications/{id}?page_size=1000")
+
+while (page.Next != None) {
+ { page, notifications } = http.Get("http://clairv4/notifier/api/v1/notifications/{id}?next={page.Next},page_size=1000")
+}
+Note: If the client specifies a custom page_size it must specify this page_size on every request for accurate responses.
+Deleting Notifications
+While not mandatory, the client may issue a delete of the notification via a DELETE method. See api to view the delete api.
+Deleting a notification ID will clean up resources in the notifier quicker. Otherwise the notifier will wait a predetermined length of time before clearing delivered notifications from its database.
+AMQP Delivery
+See the "Notifier.AMQP" object in our config reference for complete configuration details.
+The notifier also supports delivering to an AMQP broker. With AMQP delivery you can control whether a callback is delivered to the broker or whether notifications are directly delivered to the queue.
+This allows the developer of the AMQP consumer to determine the logic of notification processing.
+Note that AMQP delivery only supports AMQP 0.x protocol (e.g. RabbitMQ). If you need to publish notifications on AMQP 1.x message queue (e.g. ActiveMQ), you can use STOMP delivery.
+Direct Delivery
+If the notifier's configuration specifies direct: true for AMQP, notifications will be delivered directly to the configured exchange.
When direct is set, the rollup property may be set to instruct the notifier to send a max number of notifications in a single AMQP message. This allows a balance between size of the message and number of messages delivered to the queue.
Testing and Development
+The notifier has a testing mode enabled when it sees the "NOTIFIER_TEST_MODE" environment variable set. It can be set to any value as we only check to see if it exists.
+When this environment variable is set, the notifier will begin sending fake notifications to the configured delivery mechanism every "poll_interval" interval. This provides an easy way to implement and test new or existing deliverers.
+The notifier will run in this mode until the environment variable is cleared and the service is restarted.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/concepts/updatersandairgap.html b/v4.7.2/concepts/updatersandairgap.html
new file mode 100644
index 0000000000..fa1edda054
--- /dev/null
+++ b/v4.7.2/concepts/updatersandairgap.html
@@ -0,0 +1,304 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Operation
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/contribution.html b/v4.7.2/contribution.html
new file mode 100644
index 0000000000..6ed636d504
--- /dev/null
+++ b/v4.7.2/contribution.html
@@ -0,0 +1,234 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Updaters
+Clair utilizes go packages we call "updaters" that encapsulate the logic of +fetching and parsing different vulnerability databases. Updaters are usually +pared with a matcher to interpret if and how any vulnerability is related to a +package.
+Operators may wish to update the vulnerability database less frequently or not +import vulnerabilities from databases that they know will not be used.
+Configuration
+Updaters can be configured by updaters key at the top of the configuration. If
+updaters are being run automatically within the matcher processes, as is the
+default, the period for running updaters is configured under the matcher's
+configuration stanza.
Choosing Sets
+Specific sets of updaters can be selected by the sets list. If not present,
+the defaults of all upstream updaters will be used.
updaters:
+ sets:
+ - rhel
+Specific Updaters
+Configuration for specific updaters can be passed by putting a key underneath
+the config member of the updaters object. The name of an updater may be
+constructed dynamically; users should examine logs to double-check names.
+The specific object that an updater expects should be covered in the updater's
+documentation.
For example, to have the "rhel" updater fetch a manifest from a different +location:
+updaters:
+ config:
+ rhel:
+ url: https://example.com/mirror/oval/PULP_MANIFEST
+Airgap
+For additional flexibility, Clair supports running updaters in a different
+environment and importing the results. This is aimed at supporting installations
+that disallow the Clair cluster from talking to the Internet directly. An update
+procedure needs to arrange to call the relevant clairctl command in an
+environment with access to the Internet, move the resulting artifact across the
+airgap according to site policy, and then call the relevant clairctl command
+to import the updates.
For example:
+# On a workstation, run:
+clairctl export-updaters updates.json.gz
+# Move the resulting file to a place reachable by the cluster:
+scp updates.json.gz internal-webserver:/var/www/
+# On a pod inside the cluster, import the file:
+clairctl import-updaters http://web.svc/updates.json.gz
+Note that a configuration file is needed to run these commands.
+Configuration
+Matcher processes should have the disable_updaters key set to disable
+automatic updaters running.
matcher:
+ disable_updaters: true
+Indexers
+Configuration
+Airgap
+indexer:
+ airgap: true
+Specific Scanners
+indexer:
+ scanner:
+ package:
+ name:
+ key: value
+ repo:
+ name:
+ key: value
+ dist:
+ name:
+ key: value
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/contribution/commit_style.html b/v4.7.2/contribution/commit_style.html
new file mode 100644
index 0000000000..60c0e5cc2c
--- /dev/null
+++ b/v4.7.2/contribution/commit_style.html
@@ -0,0 +1,252 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Contribuion
+The following sections provides information on how to contribute to Clair.
+-
+
- Commit Style +
- Releases +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/contribution/releases.html b/v4.7.2/contribution/releases.html
new file mode 100644
index 0000000000..b7d5dd886b
--- /dev/null
+++ b/v4.7.2/contribution/releases.html
@@ -0,0 +1,260 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Commit Style
+The Clair project utilizes well structured commits to keep the history useful and help with release automation. +We suggest signing off on your commits as well.
+A typical commit will take on the following structure:
+<scope>: <subject>
+
+<body>
+Fixes #1
+Pull Request #2
+
+Signed-Off By: <email>
+The header of the commit is regexp checked before commit and your commit will be kicked back if it does not conform.
+Scope
+This is the section of code this commit influences.
+You will often see scopes such as "notifier", "auth", "chore", "cicd".
+We use this field to group commits by scope in our automated changelog generation.
+It would be wise to take a look at our changelog before contributing to get an idea of the common scopes we use.
+Subject
+Subject is a short and concise summary of the change the commit is introducing. It should be a sentence fragment without starting capitalization and ending punctuation and limited to about 60 characters, to allow for the scope prefix and decoration in the git log.
+Body
+Body should be full of detail.
+Explain what this commit is doing and why it is necessary.
+You may include references to issues and pull requests as well. Our automated changelog process will discover references prefixed with "Fixes", "Closed" and "Pull Request"
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/css/chrome.css b/v4.7.2/css/chrome.css
new file mode 100644
index 0000000000..2314f7a161
--- /dev/null
+++ b/v4.7.2/css/chrome.css
@@ -0,0 +1,587 @@
+/* CSS for UI elements (a.k.a. chrome) */
+
+@import 'variables.css';
+
+html {
+ scrollbar-color: var(--scrollbar) var(--bg);
+}
+#searchresults a,
+.content a:link,
+a:visited,
+a > .hljs {
+ color: var(--links);
+}
+
+/*
+ body-container is necessary because mobile browsers don't seem to like
+ overflow-x on the body tag when there is a tag.
+*/
+#body-container {
+ /*
+ This is used when the sidebar pushes the body content off the side of
+ the screen on small screens. Without it, dragging on mobile Safari
+ will want to reposition the viewport in a weird way.
+ */
+ overflow-x: clip;
+}
+
+/* Menu Bar */
+
+#menu-bar,
+#menu-bar-hover-placeholder {
+ z-index: 101;
+ margin: auto calc(0px - var(--page-padding));
+}
+#menu-bar {
+ position: relative;
+ display: flex;
+ flex-wrap: wrap;
+ background-color: var(--bg);
+ border-block-end-color: var(--bg);
+ border-block-end-width: 1px;
+ border-block-end-style: solid;
+}
+#menu-bar.sticky,
+.js #menu-bar-hover-placeholder:hover + #menu-bar,
+.js #menu-bar:hover,
+.js.sidebar-visible #menu-bar {
+ position: -webkit-sticky;
+ position: sticky;
+ top: 0 !important;
+}
+#menu-bar-hover-placeholder {
+ position: sticky;
+ position: -webkit-sticky;
+ top: 0;
+ height: var(--menu-bar-height);
+}
+#menu-bar.bordered {
+ border-block-end-color: var(--table-border-color);
+}
+#menu-bar i, #menu-bar .icon-button {
+ position: relative;
+ padding: 0 8px;
+ z-index: 10;
+ line-height: var(--menu-bar-height);
+ cursor: pointer;
+ transition: color 0.5s;
+}
+@media only screen and (max-width: 420px) {
+ #menu-bar i, #menu-bar .icon-button {
+ padding: 0 5px;
+ }
+}
+
+.icon-button {
+ border: none;
+ background: none;
+ padding: 0;
+ color: inherit;
+}
+.icon-button i {
+ margin: 0;
+}
+
+.right-buttons {
+ margin: 0 15px;
+}
+.right-buttons a {
+ text-decoration: none;
+}
+
+.left-buttons {
+ display: flex;
+ margin: 0 5px;
+}
+.no-js .left-buttons button {
+ display: none;
+}
+
+.menu-title {
+ display: inline-block;
+ font-weight: 200;
+ font-size: 2.4rem;
+ line-height: var(--menu-bar-height);
+ text-align: center;
+ margin: 0;
+ flex: 1;
+ white-space: nowrap;
+ overflow: hidden;
+ text-overflow: ellipsis;
+}
+.js .menu-title {
+ cursor: pointer;
+}
+
+.menu-bar,
+.menu-bar:visited,
+.nav-chapters,
+.nav-chapters:visited,
+.mobile-nav-chapters,
+.mobile-nav-chapters:visited,
+.menu-bar .icon-button,
+.menu-bar a i {
+ color: var(--icons);
+}
+
+.menu-bar i:hover,
+.menu-bar .icon-button:hover,
+.nav-chapters:hover,
+.mobile-nav-chapters i:hover {
+ color: var(--icons-hover);
+}
+
+/* Nav Icons */
+
+.nav-chapters {
+ font-size: 2.5em;
+ text-align: center;
+ text-decoration: none;
+
+ position: fixed;
+ top: 0;
+ bottom: 0;
+ margin: 0;
+ max-width: 150px;
+ min-width: 90px;
+
+ display: flex;
+ justify-content: center;
+ align-content: center;
+ flex-direction: column;
+
+ transition: color 0.5s, background-color 0.5s;
+}
+
+.nav-chapters:hover {
+ text-decoration: none;
+ background-color: var(--theme-hover);
+ transition: background-color 0.15s, color 0.15s;
+}
+
+.nav-wrapper {
+ margin-block-start: 50px;
+ display: none;
+}
+
+.mobile-nav-chapters {
+ font-size: 2.5em;
+ text-align: center;
+ text-decoration: none;
+ width: 90px;
+ border-radius: 5px;
+ background-color: var(--sidebar-bg);
+}
+
+/* Only Firefox supports flow-relative values */
+.previous { float: left; }
+[dir=rtl] .previous { float: right; }
+
+/* Only Firefox supports flow-relative values */
+.next {
+ float: right;
+ right: var(--page-padding);
+}
+[dir=rtl] .next {
+ float: left;
+ right: unset;
+ left: var(--page-padding);
+}
+
+/* Use the correct buttons for RTL layouts*/
+[dir=rtl] .previous i.fa-angle-left:before {content:"\f105";}
+[dir=rtl] .next i.fa-angle-right:before { content:"\f104"; }
+
+@media only screen and (max-width: 1080px) {
+ .nav-wide-wrapper { display: none; }
+ .nav-wrapper { display: block; }
+}
+
+/* sidebar-visible */
+@media only screen and (max-width: 1380px) {
+ #sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wide-wrapper { display: none; }
+ #sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wrapper { display: block; }
+}
+
+/* Inline code */
+
+:not(pre) > .hljs {
+ display: inline;
+ padding: 0.1em 0.3em;
+ border-radius: 3px;
+}
+
+:not(pre):not(a) > .hljs {
+ color: var(--inline-code-color);
+ overflow-x: initial;
+}
+
+a:hover > .hljs {
+ text-decoration: underline;
+}
+
+pre {
+ position: relative;
+}
+pre > .buttons {
+ position: absolute;
+ z-index: 100;
+ right: 0px;
+ top: 2px;
+ margin: 0px;
+ padding: 2px 0px;
+
+ color: var(--sidebar-fg);
+ cursor: pointer;
+ visibility: hidden;
+ opacity: 0;
+ transition: visibility 0.1s linear, opacity 0.1s linear;
+}
+pre:hover > .buttons {
+ visibility: visible;
+ opacity: 1
+}
+pre > .buttons :hover {
+ color: var(--sidebar-active);
+ border-color: var(--icons-hover);
+ background-color: var(--theme-hover);
+}
+pre > .buttons i {
+ margin-inline-start: 8px;
+}
+pre > .buttons button {
+ cursor: inherit;
+ margin: 0px 5px;
+ padding: 3px 5px;
+ font-size: 14px;
+
+ border-style: solid;
+ border-width: 1px;
+ border-radius: 4px;
+ border-color: var(--icons);
+ background-color: var(--theme-popup-bg);
+ transition: 100ms;
+ transition-property: color,border-color,background-color;
+ color: var(--icons);
+}
+@media (pointer: coarse) {
+ pre > .buttons button {
+ /* On mobile, make it easier to tap buttons. */
+ padding: 0.3rem 1rem;
+ }
+}
+pre > code {
+ padding: 1rem;
+}
+
+/* FIXME: ACE editors overlap their buttons because ACE does absolute
+ positioning within the code block which breaks padding. The only solution I
+ can think of is to move the padding to the outer pre tag (or insert a div
+ wrapper), but that would require fixing a whole bunch of CSS rules.
+*/
+.hljs.ace_editor {
+ padding: 0rem 0rem;
+}
+
+pre > .result {
+ margin-block-start: 10px;
+}
+
+/* Search */
+
+#searchresults a {
+ text-decoration: none;
+}
+
+mark {
+ border-radius: 2px;
+ padding-block-start: 0;
+ padding-block-end: 1px;
+ padding-inline-start: 3px;
+ padding-inline-end: 3px;
+ margin-block-start: 0;
+ margin-block-end: -1px;
+ margin-inline-start: -3px;
+ margin-inline-end: -3px;
+ background-color: var(--search-mark-bg);
+ transition: background-color 300ms linear;
+ cursor: pointer;
+}
+
+mark.fade-out {
+ background-color: rgba(0,0,0,0) !important;
+ cursor: auto;
+}
+
+.searchbar-outer {
+ margin-inline-start: auto;
+ margin-inline-end: auto;
+ max-width: var(--content-max-width);
+}
+
+#searchbar {
+ width: 100%;
+ margin-block-start: 5px;
+ margin-block-end: 0;
+ margin-inline-start: auto;
+ margin-inline-end: auto;
+ padding: 10px 16px;
+ transition: box-shadow 300ms ease-in-out;
+ border: 1px solid var(--searchbar-border-color);
+ border-radius: 3px;
+ background-color: var(--searchbar-bg);
+ color: var(--searchbar-fg);
+}
+#searchbar:focus,
+#searchbar.active {
+ box-shadow: 0 0 3px var(--searchbar-shadow-color);
+}
+
+.searchresults-header {
+ font-weight: bold;
+ font-size: 1em;
+ padding-block-start: 18px;
+ padding-block-end: 0;
+ padding-inline-start: 5px;
+ padding-inline-end: 0;
+ color: var(--searchresults-header-fg);
+}
+
+.searchresults-outer {
+ margin-inline-start: auto;
+ margin-inline-end: auto;
+ max-width: var(--content-max-width);
+ border-block-end: 1px dashed var(--searchresults-border-color);
+}
+
+ul#searchresults {
+ list-style: none;
+ padding-inline-start: 20px;
+}
+ul#searchresults li {
+ margin: 10px 0px;
+ padding: 2px;
+ border-radius: 2px;
+}
+ul#searchresults li.focus {
+ background-color: var(--searchresults-li-bg);
+}
+ul#searchresults span.teaser {
+ display: block;
+ clear: both;
+ margin-block-start: 5px;
+ margin-block-end: 0;
+ margin-inline-start: 20px;
+ margin-inline-end: 0;
+ font-size: 0.8em;
+}
+ul#searchresults span.teaser em {
+ font-weight: bold;
+ font-style: normal;
+}
+
+/* Sidebar */
+
+.sidebar {
+ position: fixed;
+ left: 0;
+ top: 0;
+ bottom: 0;
+ width: var(--sidebar-width);
+ font-size: 0.875em;
+ box-sizing: border-box;
+ -webkit-overflow-scrolling: touch;
+ overscroll-behavior-y: contain;
+ background-color: var(--sidebar-bg);
+ color: var(--sidebar-fg);
+}
+[dir=rtl] .sidebar { left: unset; right: 0; }
+.sidebar-resizing {
+ -moz-user-select: none;
+ -webkit-user-select: none;
+ -ms-user-select: none;
+ user-select: none;
+}
+.no-js .sidebar,
+.js:not(.sidebar-resizing) .sidebar {
+ transition: transform 0.3s; /* Animation: slide away */
+}
+.sidebar code {
+ line-height: 2em;
+}
+.sidebar .sidebar-scrollbox {
+ overflow-y: auto;
+ position: absolute;
+ top: 0;
+ bottom: 0;
+ left: 0;
+ right: 0;
+ padding: 10px 10px;
+}
+.sidebar .sidebar-resize-handle {
+ position: absolute;
+ cursor: col-resize;
+ width: 0;
+ right: 0;
+ top: 0;
+ bottom: 0;
+}
+[dir=rtl] .sidebar .sidebar-resize-handle { right: unset; left: 0; }
+.js .sidebar .sidebar-resize-handle {
+ cursor: col-resize;
+ width: 5px;
+}
+/* sidebar-hidden */
+#sidebar-toggle-anchor:not(:checked) ~ .sidebar {
+ transform: translateX(calc(0px - var(--sidebar-width)));
+ z-index: -1;
+}
+[dir=rtl] #sidebar-toggle-anchor:not(:checked) ~ .sidebar {
+ transform: translateX(var(--sidebar-width));
+}
+.sidebar::-webkit-scrollbar {
+ background: var(--sidebar-bg);
+}
+.sidebar::-webkit-scrollbar-thumb {
+ background: var(--scrollbar);
+}
+
+/* sidebar-visible */
+#sidebar-toggle-anchor:checked ~ .page-wrapper {
+ transform: translateX(var(--sidebar-width));
+}
+[dir=rtl] #sidebar-toggle-anchor:checked ~ .page-wrapper {
+ transform: translateX(calc(0px - var(--sidebar-width)));
+}
+@media only screen and (min-width: 620px) {
+ #sidebar-toggle-anchor:checked ~ .page-wrapper {
+ transform: none;
+ margin-inline-start: var(--sidebar-width);
+ }
+ [dir=rtl] #sidebar-toggle-anchor:checked ~ .page-wrapper {
+ transform: none;
+ }
+}
+
+.chapter {
+ list-style: none outside none;
+ padding-inline-start: 0;
+ line-height: 2.2em;
+}
+
+.chapter ol {
+ width: 100%;
+}
+
+.chapter li {
+ display: flex;
+ color: var(--sidebar-non-existant);
+}
+.chapter li a {
+ display: block;
+ padding: 0;
+ text-decoration: none;
+ color: var(--sidebar-fg);
+}
+
+.chapter li a:hover {
+ color: var(--sidebar-active);
+}
+
+.chapter li a.active {
+ color: var(--sidebar-active);
+}
+
+.chapter li > a.toggle {
+ cursor: pointer;
+ display: block;
+ margin-inline-start: auto;
+ padding: 0 10px;
+ user-select: none;
+ opacity: 0.68;
+}
+
+.chapter li > a.toggle div {
+ transition: transform 0.5s;
+}
+
+/* collapse the section */
+.chapter li:not(.expanded) + li > ol {
+ display: none;
+}
+
+.chapter li.chapter-item {
+ line-height: 1.5em;
+ margin-block-start: 0.6em;
+}
+
+.chapter li.expanded > a.toggle div {
+ transform: rotate(90deg);
+}
+
+.spacer {
+ width: 100%;
+ height: 3px;
+ margin: 5px 0px;
+}
+.chapter .spacer {
+ background-color: var(--sidebar-spacer);
+}
+
+@media (-moz-touch-enabled: 1), (pointer: coarse) {
+ .chapter li a { padding: 5px 0; }
+ .spacer { margin: 10px 0; }
+}
+
+.section {
+ list-style: none outside none;
+ padding-inline-start: 20px;
+ line-height: 1.9em;
+}
+
+/* Theme Menu Popup */
+
+.theme-popup {
+ position: absolute;
+ left: 10px;
+ top: var(--menu-bar-height);
+ z-index: 1000;
+ border-radius: 4px;
+ font-size: 0.7em;
+ color: var(--fg);
+ background: var(--theme-popup-bg);
+ border: 1px solid var(--theme-popup-border);
+ margin: 0;
+ padding: 0;
+ list-style: none;
+ display: none;
+ /* Don't let the children's background extend past the rounded corners. */
+ overflow: hidden;
+}
+[dir=rtl] .theme-popup { left: unset; right: 10px; }
+.theme-popup .default {
+ color: var(--icons);
+}
+.theme-popup .theme {
+ width: 100%;
+ border: 0;
+ margin: 0;
+ padding: 2px 20px;
+ line-height: 25px;
+ white-space: nowrap;
+ text-align: start;
+ cursor: pointer;
+ color: inherit;
+ background: inherit;
+ font-size: inherit;
+}
+.theme-popup .theme:hover {
+ background-color: var(--theme-hover);
+}
+
+.theme-selected::before {
+ display: inline-block;
+ content: "✓";
+ margin-inline-start: -14px;
+ width: 14px;
+}
diff --git a/v4.7.2/css/general.css b/v4.7.2/css/general.css
new file mode 100644
index 0000000000..e7d20da725
--- /dev/null
+++ b/v4.7.2/css/general.css
@@ -0,0 +1,234 @@
+/* Base styles and content styles */
+
+@import 'variables.css';
+
+:root {
+ /* Browser default font-size is 16px, this way 1 rem = 10px */
+ font-size: 62.5%;
+ color-scheme: var(--color-scheme);
+}
+
+html {
+ font-family: "Open Sans", sans-serif;
+ color: var(--fg);
+ background-color: var(--bg);
+ text-size-adjust: none;
+ -webkit-text-size-adjust: none;
+}
+
+body {
+ margin: 0;
+ font-size: 1.6rem;
+ overflow-x: hidden;
+}
+
+code {
+ font-family: var(--mono-font) !important;
+ font-size: var(--code-font-size);
+ direction: ltr !important;
+}
+
+/* make long words/inline code not x overflow */
+main {
+ overflow-wrap: break-word;
+}
+
+/* make wide tables scroll if they overflow */
+.table-wrapper {
+ overflow-x: auto;
+}
+
+/* Don't change font size in headers. */
+h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
+ font-size: unset;
+}
+
+.left { float: left; }
+.right { float: right; }
+.boring { opacity: 0.6; }
+.hide-boring .boring { display: none; }
+.hidden { display: none !important; }
+
+h2, h3 { margin-block-start: 2.5em; }
+h4, h5 { margin-block-start: 2em; }
+
+.header + .header h3,
+.header + .header h4,
+.header + .header h5 {
+ margin-block-start: 1em;
+}
+
+h1:target::before,
+h2:target::before,
+h3:target::before,
+h4:target::before,
+h5:target::before,
+h6:target::before {
+ display: inline-block;
+ content: "»";
+ margin-inline-start: -30px;
+ width: 30px;
+}
+
+/* This is broken on Safari as of version 14, but is fixed
+ in Safari Technology Preview 117 which I think will be Safari 14.2.
+ https://bugs.webkit.org/show_bug.cgi?id=218076
+*/
+:target {
+ /* Safari does not support logical properties */
+ scroll-margin-top: calc(var(--menu-bar-height) + 0.5em);
+}
+
+.page {
+ outline: 0;
+ padding: 0 var(--page-padding);
+ margin-block-start: calc(0px - var(--menu-bar-height)); /* Compensate for the #menu-bar-hover-placeholder */
+}
+.page-wrapper {
+ box-sizing: border-box;
+ background-color: var(--bg);
+}
+.no-js .page-wrapper,
+.js:not(.sidebar-resizing) .page-wrapper {
+ transition: margin-left 0.3s ease, transform 0.3s ease; /* Animation: slide away */
+}
+[dir=rtl] .js:not(.sidebar-resizing) .page-wrapper {
+ transition: margin-right 0.3s ease, transform 0.3s ease; /* Animation: slide away */
+}
+
+.content {
+ overflow-y: auto;
+ padding: 0 5px 50px 5px;
+}
+.content main {
+ margin-inline-start: auto;
+ margin-inline-end: auto;
+ max-width: var(--content-max-width);
+}
+.content p { line-height: 1.45em; }
+.content ol { line-height: 1.45em; }
+.content ul { line-height: 1.45em; }
+.content a { text-decoration: none; }
+.content a:hover { text-decoration: underline; }
+.content img, .content video { max-width: 100%; }
+.content .header:link,
+.content .header:visited {
+ color: var(--fg);
+}
+.content .header:link,
+.content .header:visited:hover {
+ text-decoration: none;
+}
+
+table {
+ margin: 0 auto;
+ border-collapse: collapse;
+}
+table td {
+ padding: 3px 20px;
+ border: 1px var(--table-border-color) solid;
+}
+table thead {
+ background: var(--table-header-bg);
+}
+table thead td {
+ font-weight: 700;
+ border: none;
+}
+table thead th {
+ padding: 3px 20px;
+}
+table thead tr {
+ border: 1px var(--table-header-bg) solid;
+}
+/* Alternate background colors for rows */
+table tbody tr:nth-child(2n) {
+ background: var(--table-alternate-bg);
+}
+
+
+blockquote {
+ margin: 20px 0;
+ padding: 0 20px;
+ color: var(--fg);
+ background-color: var(--quote-bg);
+ border-block-start: .1em solid var(--quote-border);
+ border-block-end: .1em solid var(--quote-border);
+}
+
+.warning {
+ margin: 20px;
+ padding: 0 20px;
+ border-inline-start: 2px solid var(--warning-border);
+}
+
+.warning:before {
+ position: absolute;
+ width: 3rem;
+ height: 3rem;
+ margin-inline-start: calc(-1.5rem - 21px);
+ content: "ⓘ";
+ text-align: center;
+ background-color: var(--bg);
+ color: var(--warning-border);
+ font-weight: bold;
+ font-size: 2rem;
+}
+
+blockquote .warning:before {
+ background-color: var(--quote-bg);
+}
+
+kbd {
+ background-color: var(--table-border-color);
+ border-radius: 4px;
+ border: solid 1px var(--theme-popup-border);
+ box-shadow: inset 0 -1px 0 var(--theme-hover);
+ display: inline-block;
+ font-size: var(--code-font-size);
+ font-family: var(--mono-font);
+ line-height: 10px;
+ padding: 4px 5px;
+ vertical-align: middle;
+}
+
+:not(.footnote-definition) + .footnote-definition,
+.footnote-definition + :not(.footnote-definition) {
+ margin-block-start: 2em;
+}
+.footnote-definition {
+ font-size: 0.9em;
+ margin: 0.5em 0;
+}
+.footnote-definition p {
+ display: inline;
+}
+
+.tooltiptext {
+ position: absolute;
+ visibility: hidden;
+ color: #fff;
+ background-color: #333;
+ transform: translateX(-50%); /* Center by moving tooltip 50% of its width left */
+ left: -8px; /* Half of the width of the icon */
+ top: -35px;
+ font-size: 0.8em;
+ text-align: center;
+ border-radius: 6px;
+ padding: 5px 8px;
+ margin: 5px;
+ z-index: 1000;
+}
+.tooltipped .tooltiptext {
+ visibility: visible;
+}
+
+.chapter li.part-title {
+ color: var(--sidebar-fg);
+ margin: 5px 0px;
+ font-weight: bold;
+}
+
+.result-no-output {
+ font-style: italic;
+}
diff --git a/v4.7.2/css/print.css b/v4.7.2/css/print.css
new file mode 100644
index 0000000000..dcf0ba64b9
--- /dev/null
+++ b/v4.7.2/css/print.css
@@ -0,0 +1,50 @@
+
+#sidebar,
+#menu-bar,
+.nav-chapters,
+.mobile-nav-chapters {
+ display: none;
+}
+
+#page-wrapper.page-wrapper {
+ transform: none;
+ margin-inline-start: 0px;
+ overflow-y: initial;
+}
+
+#content {
+ max-width: none;
+ margin: 0;
+ padding: 0;
+}
+
+.page {
+ overflow-y: initial;
+}
+
+code {
+ direction: ltr !important;
+}
+
+pre > .buttons {
+ z-index: 2;
+}
+
+a, a:visited, a:active, a:hover {
+ color: #4183c4;
+ text-decoration: none;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ page-break-inside: avoid;
+ page-break-after: avoid;
+}
+
+pre, code {
+ page-break-inside: avoid;
+ white-space: pre-wrap;
+}
+
+.fa {
+ display: none !important;
+}
diff --git a/v4.7.2/css/variables.css b/v4.7.2/css/variables.css
new file mode 100644
index 0000000000..10a7590944
--- /dev/null
+++ b/v4.7.2/css/variables.css
@@ -0,0 +1,277 @@
+
+/* Globals */
+
+:root {
+ --sidebar-width: 300px;
+ --page-padding: 15px;
+ --content-max-width: 750px;
+ --menu-bar-height: 50px;
+ --mono-font: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace;
+ --code-font-size: 0.875em /* please adjust the ace font size accordingly in editor.js */
+}
+
+/* Themes */
+
+.ayu {
+ --bg: hsl(210, 25%, 8%);
+ --fg: #c5c5c5;
+
+ --sidebar-bg: #14191f;
+ --sidebar-fg: #c8c9db;
+ --sidebar-non-existant: #5c6773;
+ --sidebar-active: #ffb454;
+ --sidebar-spacer: #2d334f;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #737480;
+ --icons-hover: #b7b9cc;
+
+ --links: #0096cf;
+
+ --inline-code-color: #ffb454;
+
+ --theme-popup-bg: #14191f;
+ --theme-popup-border: #5c6773;
+ --theme-hover: #191f26;
+
+ --quote-bg: hsl(226, 15%, 17%);
+ --quote-border: hsl(226, 15%, 22%);
+
+ --warning-border: #ff8e00;
+
+ --table-border-color: hsl(210, 25%, 13%);
+ --table-header-bg: hsl(210, 25%, 28%);
+ --table-alternate-bg: hsl(210, 25%, 11%);
+
+ --searchbar-border-color: #848484;
+ --searchbar-bg: #424242;
+ --searchbar-fg: #fff;
+ --searchbar-shadow-color: #d4c89f;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #888;
+ --searchresults-li-bg: #252932;
+ --search-mark-bg: #e3b171;
+
+ --color-scheme: dark;
+}
+
+.coal {
+ --bg: hsl(200, 7%, 8%);
+ --fg: #98a3ad;
+
+ --sidebar-bg: #292c2f;
+ --sidebar-fg: #a1adb8;
+ --sidebar-non-existant: #505254;
+ --sidebar-active: #3473ad;
+ --sidebar-spacer: #393939;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #43484d;
+ --icons-hover: #b3c0cc;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #c5c8c6;
+
+ --theme-popup-bg: #141617;
+ --theme-popup-border: #43484d;
+ --theme-hover: #1f2124;
+
+ --quote-bg: hsl(234, 21%, 18%);
+ --quote-border: hsl(234, 21%, 23%);
+
+ --warning-border: #ff8e00;
+
+ --table-border-color: hsl(200, 7%, 13%);
+ --table-header-bg: hsl(200, 7%, 28%);
+ --table-alternate-bg: hsl(200, 7%, 11%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #b7b7b7;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #98a3ad;
+ --searchresults-li-bg: #2b2b2f;
+ --search-mark-bg: #355c7d;
+
+ --color-scheme: dark;
+}
+
+.light {
+ --bg: hsl(0, 0%, 100%);
+ --fg: hsl(0, 0%, 0%);
+
+ --sidebar-bg: #fafafa;
+ --sidebar-fg: hsl(0, 0%, 0%);
+ --sidebar-non-existant: #aaaaaa;
+ --sidebar-active: #1f1fff;
+ --sidebar-spacer: #f4f4f4;
+
+ --scrollbar: #8F8F8F;
+
+ --icons: #747474;
+ --icons-hover: #000000;
+
+ --links: #20609f;
+
+ --inline-code-color: #301900;
+
+ --theme-popup-bg: #fafafa;
+ --theme-popup-border: #cccccc;
+ --theme-hover: #e6e6e6;
+
+ --quote-bg: hsl(197, 37%, 96%);
+ --quote-border: hsl(197, 37%, 91%);
+
+ --warning-border: #ff8e00;
+
+ --table-border-color: hsl(0, 0%, 95%);
+ --table-header-bg: hsl(0, 0%, 80%);
+ --table-alternate-bg: hsl(0, 0%, 97%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #fafafa;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #888;
+ --searchresults-li-bg: #e4f2fe;
+ --search-mark-bg: #a2cff5;
+
+ --color-scheme: light;
+}
+
+.navy {
+ --bg: hsl(226, 23%, 11%);
+ --fg: #bcbdd0;
+
+ --sidebar-bg: #282d3f;
+ --sidebar-fg: #c8c9db;
+ --sidebar-non-existant: #505274;
+ --sidebar-active: #2b79a2;
+ --sidebar-spacer: #2d334f;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #737480;
+ --icons-hover: #b7b9cc;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #c5c8c6;
+
+ --theme-popup-bg: #161923;
+ --theme-popup-border: #737480;
+ --theme-hover: #282e40;
+
+ --quote-bg: hsl(226, 15%, 17%);
+ --quote-border: hsl(226, 15%, 22%);
+
+ --warning-border: #ff8e00;
+
+ --table-border-color: hsl(226, 23%, 16%);
+ --table-header-bg: hsl(226, 23%, 31%);
+ --table-alternate-bg: hsl(226, 23%, 14%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #aeaec6;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #5f5f71;
+ --searchresults-border-color: #5c5c68;
+ --searchresults-li-bg: #242430;
+ --search-mark-bg: #a2cff5;
+
+ --color-scheme: dark;
+}
+
+.rust {
+ --bg: hsl(60, 9%, 87%);
+ --fg: #262625;
+
+ --sidebar-bg: #3b2e2a;
+ --sidebar-fg: #c8c9db;
+ --sidebar-non-existant: #505254;
+ --sidebar-active: #e69f67;
+ --sidebar-spacer: #45373a;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #737480;
+ --icons-hover: #262625;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #6e6b5e;
+
+ --theme-popup-bg: #e1e1db;
+ --theme-popup-border: #b38f6b;
+ --theme-hover: #99908a;
+
+ --quote-bg: hsl(60, 5%, 75%);
+ --quote-border: hsl(60, 5%, 70%);
+
+ --warning-border: #ff8e00;
+
+ --table-border-color: hsl(60, 9%, 82%);
+ --table-header-bg: #b3a497;
+ --table-alternate-bg: hsl(60, 9%, 84%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #fafafa;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #888;
+ --searchresults-li-bg: #dec2a2;
+ --search-mark-bg: #e69f67;
+
+ --color-scheme: light;
+}
+
+@media (prefers-color-scheme: dark) {
+ .light.no-js {
+ --bg: hsl(200, 7%, 8%);
+ --fg: #98a3ad;
+
+ --sidebar-bg: #292c2f;
+ --sidebar-fg: #a1adb8;
+ --sidebar-non-existant: #505254;
+ --sidebar-active: #3473ad;
+ --sidebar-spacer: #393939;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #43484d;
+ --icons-hover: #b3c0cc;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #c5c8c6;
+
+ --theme-popup-bg: #141617;
+ --theme-popup-border: #43484d;
+ --theme-hover: #1f2124;
+
+ --quote-bg: hsl(234, 21%, 18%);
+ --quote-border: hsl(234, 21%, 23%);
+
+ --warning-border: #ff8e00;
+
+ --table-border-color: hsl(200, 7%, 13%);
+ --table-header-bg: hsl(200, 7%, 28%);
+ --table-alternate-bg: hsl(200, 7%, 11%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #b7b7b7;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #98a3ad;
+ --searchresults-li-bg: #2b2b2f;
+ --search-mark-bg: #355c7d;
+ }
+}
diff --git a/v4.7.2/elasticlunr.min.js b/v4.7.2/elasticlunr.min.js
new file mode 100644
index 0000000000..94b20dd2ef
--- /dev/null
+++ b/v4.7.2/elasticlunr.min.js
@@ -0,0 +1,10 @@
+/**
+ * elasticlunr - http://weixsong.github.io
+ * Lightweight full-text search engine in Javascript for browser search and offline search. - 0.9.5
+ *
+ * Copyright (C) 2017 Oliver Nightingale
+ * Copyright (C) 2017 Wei Song
+ * MIT Licensed
+ * @license
+ */
+!function(){function e(e){if(null===e||"object"!=typeof e)return e;var t=e.constructor();for(var n in e)e.hasOwnProperty(n)&&(t[n]=e[n]);return t}var t=function(e){var n=new t.Index;return n.pipeline.add(t.trimmer,t.stopWordFilter,t.stemmer),e&&e.call(n,n),n};t.version="0.9.5",lunr=t,t.utils={},t.utils.warn=function(e){return function(t){e.console&&console.warn&&console.warn(t)}}(this),t.utils.toString=function(e){return void 0===e||null===e?"":e.toString()},t.EventEmitter=function(){this.events={}},t.EventEmitter.prototype.addListener=function(){var e=Array.prototype.slice.call(arguments),t=e.pop(),n=e;if("function"!=typeof t)throw new TypeError("last argument must be a function");n.forEach(function(e){this.hasHandler(e)||(this.events[e]=[]),this.events[e].push(t)},this)},t.EventEmitter.prototype.removeListener=function(e,t){if(this.hasHandler(e)){var n=this.events[e].indexOf(t);-1!==n&&(this.events[e].splice(n,1),0==this.events[e].length&&delete this.events[e])}},t.EventEmitter.prototype.emit=function(e){if(this.hasHandler(e)){var t=Array.prototype.slice.call(arguments,1);this.events[e].forEach(function(e){e.apply(void 0,t)},this)}},t.EventEmitter.prototype.hasHandler=function(e){return e in this.events},t.tokenizer=function(e){if(!arguments.length||null===e||void 0===e)return[];if(Array.isArray(e)){var n=e.filter(function(e){return null===e||void 0===e?!1:!0});n=n.map(function(e){return t.utils.toString(e).toLowerCase()});var i=[];return n.forEach(function(e){var n=e.split(t.tokenizer.seperator);i=i.concat(n)},this),i}return e.toString().trim().toLowerCase().split(t.tokenizer.seperator)},t.tokenizer.defaultSeperator=/[\s\-]+/,t.tokenizer.seperator=t.tokenizer.defaultSeperator,t.tokenizer.setSeperator=function(e){null!==e&&void 0!==e&&"object"==typeof e&&(t.tokenizer.seperator=e)},t.tokenizer.resetSeperator=function(){t.tokenizer.seperator=t.tokenizer.defaultSeperator},t.tokenizer.getSeperator=function(){return t.tokenizer.seperator},t.Pipeline=function(){this._queue=[]},t.Pipeline.registeredFunctions={},t.Pipeline.registerFunction=function(e,n){n in t.Pipeline.registeredFunctions&&t.utils.warn("Overwriting existing registered function: "+n),e.label=n,t.Pipeline.registeredFunctions[n]=e},t.Pipeline.getRegisteredFunction=function(e){return e in t.Pipeline.registeredFunctions!=!0?null:t.Pipeline.registeredFunctions[e]},t.Pipeline.warnIfFunctionNotRegistered=function(e){var n=e.label&&e.label in this.registeredFunctions;n||t.utils.warn("Function is not registered with pipeline. This may cause problems when serialising the index.\n",e)},t.Pipeline.load=function(e){var n=new t.Pipeline;return e.forEach(function(e){var i=t.Pipeline.getRegisteredFunction(e);if(!i)throw new Error("Cannot load un-registered function: "+e);n.add(i)}),n},t.Pipeline.prototype.add=function(){var e=Array.prototype.slice.call(arguments);e.forEach(function(e){t.Pipeline.warnIfFunctionNotRegistered(e),this._queue.push(e)},this)},t.Pipeline.prototype.after=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i+1,0,n)},t.Pipeline.prototype.before=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i,0,n)},t.Pipeline.prototype.remove=function(e){var t=this._queue.indexOf(e);-1!==t&&this._queue.splice(t,1)},t.Pipeline.prototype.run=function(e){for(var t=[],n=e.length,i=this._queue.length,o=0;n>o;o++){for(var r=e[o],s=0;i>s&&(r=this._queue[s](r,o,e),void 0!==r&&null!==r);s++);void 0!==r&&null!==r&&t.push(r)}return t},t.Pipeline.prototype.reset=function(){this._queue=[]},t.Pipeline.prototype.get=function(){return this._queue},t.Pipeline.prototype.toJSON=function(){return this._queue.map(function(e){return t.Pipeline.warnIfFunctionNotRegistered(e),e.label})},t.Index=function(){this._fields=[],this._ref="id",this.pipeline=new t.Pipeline,this.documentStore=new t.DocumentStore,this.index={},this.eventEmitter=new t.EventEmitter,this._idfCache={},this.on("add","remove","update",function(){this._idfCache={}}.bind(this))},t.Index.prototype.on=function(){var e=Array.prototype.slice.call(arguments);return this.eventEmitter.addListener.apply(this.eventEmitter,e)},t.Index.prototype.off=function(e,t){return this.eventEmitter.removeListener(e,t)},t.Index.load=function(e){e.version!==t.version&&t.utils.warn("version mismatch: current "+t.version+" importing "+e.version);var n=new this;n._fields=e.fields,n._ref=e.ref,n.documentStore=t.DocumentStore.load(e.documentStore),n.pipeline=t.Pipeline.load(e.pipeline),n.index={};for(var i in e.index)n.index[i]=t.InvertedIndex.load(e.index[i]);return n},t.Index.prototype.addField=function(e){return this._fields.push(e),this.index[e]=new t.InvertedIndex,this},t.Index.prototype.setRef=function(e){return this._ref=e,this},t.Index.prototype.saveDocument=function(e){return this.documentStore=new t.DocumentStore(e),this},t.Index.prototype.addDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.addDoc(i,e),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));this.documentStore.addFieldLength(i,n,o.length);var r={};o.forEach(function(e){e in r?r[e]+=1:r[e]=1},this);for(var s in r){var u=r[s];u=Math.sqrt(u),this.index[n].addToken(s,{ref:i,tf:u})}},this),n&&this.eventEmitter.emit("add",e,this)}},t.Index.prototype.removeDocByRef=function(e){if(e&&this.documentStore.isDocStored()!==!1&&this.documentStore.hasDoc(e)){var t=this.documentStore.getDoc(e);this.removeDoc(t,!1)}},t.Index.prototype.removeDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.hasDoc(i)&&(this.documentStore.removeDoc(i),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));o.forEach(function(e){this.index[n].removeToken(e,i)},this)},this),n&&this.eventEmitter.emit("remove",e,this))}},t.Index.prototype.updateDoc=function(e,t){var t=void 0===t?!0:t;this.removeDocByRef(e[this._ref],!1),this.addDoc(e,!1),t&&this.eventEmitter.emit("update",e,this)},t.Index.prototype.idf=function(e,t){var n="@"+t+"/"+e;if(Object.prototype.hasOwnProperty.call(this._idfCache,n))return this._idfCache[n];var i=this.index[t].getDocFreq(e),o=1+Math.log(this.documentStore.length/(i+1));return this._idfCache[n]=o,o},t.Index.prototype.getFields=function(){return this._fields.slice()},t.Index.prototype.search=function(e,n){if(!e)return[];e="string"==typeof e?{any:e}:JSON.parse(JSON.stringify(e));var i=null;null!=n&&(i=JSON.stringify(n));for(var o=new t.Configuration(i,this.getFields()).get(),r={},s=Object.keys(e),u=0;u
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Releases
+Clair releases are cut roughly every three months and actively maintained for +six.
+This means that bugfixes should be landed on master (if applicable) and then
+marked for backporting to a minor version's release branch. The process for
+doing this is not yet formalized.
Process
+Minor
+When cutting a new minor release, two things need to be done: creating a tag and +creating a release branch. This can be done like so:
+git tag -as v4.x.0 HEAD
+git push upstream HEAD:release-4.x tag v4.x.0
+Then, a "release" needs to be created in the Github UI using the created tag.
+Patch
+A patch release is just like a minor release with the caveat that minor version +tags should only appear on release branches and a new branch does not need to +be created.
+git checkout release-4.x
+git tag -as v4.x.1 HEAD
+git push upstream tag v4.x.1
+Then, a "release" needs to be created in the Github UI using the created tag.
+Creating Artifacts
+Clair's artifact release process is automated and driven off the releases in +Github.
+Publishing a new release in the Github UI automatically triggers the creation of
+a complete source archive and a container. The archive is attached to the
+release, and the container is pushed to the
+quay.io/projectquay/clair
+repository.
This is all powered by a Github Action in .github/workflows/cut-release.yml.
":e:f.tabReplace?e.replace(/\t/g,f.tabReplace):e):e}function E(e){let n=null;const t=function(e){var n=e.className+" ";n+=e.parentNode?e.parentNode.className:"";const t=f.languageDetectRe.exec(n);if(t){var r=T(t[1]);return r||(console.warn(g.replace("{}",t[1])),console.warn("Falling back to no-highlight mode for this block.",e)),r?t[1]:"no-highlight"}return n.split(/\s+/).find(e=>p(e)||T(e))}(e);if(p(t))return;S("before:highlightBlock",{block:e,language:t}),f.useBR?(n=document.createElement("div")).innerHTML=e.innerHTML.replace(/\n/g,"").replace(/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/howto/api.html b/v4.7.2/howto/api.html
new file mode 100644
index 0000000000..32bdc93e77
--- /dev/null
+++ b/v4.7.2/howto/api.html
@@ -0,0 +1,239 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ How Tos
+The following sections provide instructions on accomplish specific goals in Clair.
+ + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/howto/clairv4_combo_multi_db.png b/v4.7.2/howto/clairv4_combo_multi_db.png
new file mode 100644
index 0000000000..fdf306d8c8
Binary files /dev/null and b/v4.7.2/howto/clairv4_combo_multi_db.png differ
diff --git a/v4.7.2/howto/clairv4_combo_single_db.png b/v4.7.2/howto/clairv4_combo_single_db.png
new file mode 100644
index 0000000000..3f7e3dac4c
Binary files /dev/null and b/v4.7.2/howto/clairv4_combo_single_db.png differ
diff --git a/v4.7.2/howto/clairv4_distributed_multi_db.png b/v4.7.2/howto/clairv4_distributed_multi_db.png
new file mode 100644
index 0000000000..c4eaf6969b
Binary files /dev/null and b/v4.7.2/howto/clairv4_distributed_multi_db.png differ
diff --git a/v4.7.2/howto/clairv4_distributed_single_db.png b/v4.7.2/howto/clairv4_distributed_single_db.png
new file mode 100644
index 0000000000..d99ad174ff
Binary files /dev/null and b/v4.7.2/howto/clairv4_distributed_single_db.png differ
diff --git a/v4.7.2/howto/deployment.html b/v4.7.2/howto/deployment.html
new file mode 100644
index 0000000000..ac0246309a
--- /dev/null
+++ b/v4.7.2/howto/deployment.html
@@ -0,0 +1,301 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ API Definition
+Clair provides its API definition via an OpenAPI specification. You can view our OpenAPI spec here
+The OpenAPI spec can be used in a variety of ways.
+-
+
- Generating http clients for your application +
- Validating data returned from Clair +
- Importing into a rest client such as Postman +
- API documentation via Swagger Editor +
See Testing Clair to learn how the local dev tooling starts a local swagger editor. This is handy for making changes to the spec in real time.
+See API Reference for a markdown rendered API reference.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/howto/getting_started.html b/v4.7.2/howto/getting_started.html
new file mode 100644
index 0000000000..cd304e5f17
--- /dev/null
+++ b/v4.7.2/howto/getting_started.html
@@ -0,0 +1,305 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Deploying Clair
+Clair v4 was designed with flexible deployment architectures in mind. The operator is free to choose a deployment model which scales to their use cases.
+Configuration
+Before jumping directly into the models its important to note that Clair is designed to use a single configuration file across all node types. This design decision makes it very easy to deploy on systems like Kubernetes and OpenShift.
+See Config Reference
+Combined Deployment
+In a combined deployment, all the Clair processes run in a single OS process. This is by far the easiest deployment model to configure as it involves the least moving parts.
+A load balancer is still recommended if you plan on performing TLS termination. Typically this will be a OpenShift route or a Kubernetes ingress.
+
In the above diagram, Clair is running in combo mode and talking to a single database. To configure this model you will provide all node types the same database and start Clair in combo mode.
+...
+indexer:
+ connstring: "host=clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+matcher:
+ connstring: "host=clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+ ...
+notifier:
+ connstring: "host=clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+ ...
+In this mode, any configuration informing Clair how to talk to other nodes is ignored, it is not needed as all intra-process communication is done directly.
+For added flexibility, it's also supported to split the databases while in combo mode.
+
In the above diagram, Clair is running in combo mode but database load is split between multiple databases. Since Clair is conceptually a set of micro-services, its processes do not share database tables even when combined into the same OS process.
+To configure this model, you would provide each process its own "connstring" in the configuration.
+...
+indexer:
+ connstring: "host=indexer-clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+matcher:
+ connstring: "host=matcher-clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+ ...
+notifier:
+ connstring: "host=notifier-clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+ ...
+Distributed Deployment
+If your application needs to asymmetrically scale or you expect high load you may want to consider a distributed deployment.
+In a distributed deployment, each Clair process runs in its own OS process. Typically this will be a Kubernetes or OpenShift Pod.
+A load balancer must be setup in this deployment model. The load balancer will route traffic between Clair nodes along with routing API requests via path based routing to the correct services. In a Kubernetes or OpenShift deployment this is usually handled with the Service and Routes abstractions. If deploying on bare metal, a load balancer will need to be configured appropriately.
+
In the above diagram, a load balancer is configured to route traffic coming from the client to the correct service. This routing is path based routing and requires a layer 7 load balancer. Traefik, Nginx, and HAProxy are all capable of this. As mentioned above, this functionality is native to OpenShift and Kubernetes.
+In this configuration, you'd supply each process with database connection strings and addresses for their dependent services. Each OS process will need to have its "mode" CLI flag or environment variable set to the appropriate value. +See Config Reference
+...
+indexer:
+ connstring: "host=indexer-clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+matcher:
+ connstring: "host=matcher-clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+ indexer_addr: "indexer-service"
+ ...
+notifier:
+ connstring: "host=notifier-clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+ indexer_addr: "indexer-service"
+ matcher_addr: "matcher-service"
+ ...
+Keep in mind a config file per process is not need. Processes only use the values necessary for their configured mode.
+TLS Termination
+Currently Clair offloads TLS termination to the load balancing infrastructure. This design choice is due to the ubiquity of Kubernetes and OpenShift infrastructure already providing this facility.
+More On Path Routing
+If you are considering a distributed deployment you will need more details on path based routing.
+Learn how to grab our OpenAPI spec here and either start up a local dev instance of the swagger editor or load the spec file into the online editor
+You will notice particular API paths are grouped by the services which implement them. This is your guide to configure your layer 7 load balancer correctly.
+When the load balancer encounters a particular path prefix it must send those request to the correct set of Clair nodes.
+For example, this is how we configure Traefik in our local development environment:
+- "traefik.enable=true"
+- "traefik.http.routers.notifier.entrypoints=clair"
+- "traefik.http.routers.notifier.rule=PathPrefix(`/notifier`)"
+- "traefik.http.routers.notifier.service=notifier"
+- "traefik.http.services.notifier.loadbalancer.server.port=6000"
+This configuration is saying "take any paths prefixes of /notifier/ and send them to the notifier services on port 6000"
+Every load balancer will have their own way to perform path routing. Check the documentation for your infrastructure of choice.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/howto/testing.html b/v4.7.2/howto/testing.html
new file mode 100644
index 0000000000..12bbd9ab5b
--- /dev/null
+++ b/v4.7.2/howto/testing.html
@@ -0,0 +1,313 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Getting Started With Clair
+Releases
+All of the source code needed to build clair is packaged as an archive and +attached to the release. Releases are tracked at the github releases.
+The release artifacts also include the clairctl command line tool.
+Official Containers
+Clair is officially packaged and released as a container at
+quay.io/projectquay/clair. The latest tag tracks the git development branch,
+and version tags are built from the corresponding release.
Running Clair
+The easiest way to get Clair up and running for test purposes is to use our local dev environment
+If you're the hands on type who wants to get into the details however, continue reading.
+Modes
+Clair can run in several modes. Indexer, matcher, notifier or combo mode. In combo mode, everything runs in a single OS process.
+If you are just starting with Clair you will most likely want to start with combo mode and venture out to a distributed deployment once acquainted.
+This how-to will demonstrate combo mode and introduce some further reading on a distributed deployment.
+Postgres
+Clair uses PostgreSQL for its data persistence. Migrations are supported so you should only need to point Clair to a fresh database and have it do the setup for you.
+We will assume you have setup a postgres database and it's reachable with the following connection string:
+host=clair-db port=5432 user=clair dbname=clair sslmode=disable. Adjust for your environment accordingly.
Starting Clair In Combo Mode
+At this point, you should either have built Clair from source or have pulled the container. In either case, we will assume that the clair-db hostname will resolve to your postgres database.
You may need to configure docker or podman networking if you are utilizing containers. This is out of scope for this how-to.
+A basic config for combo mode can be found here. Make sure to edit this config with your database settings and set "migrations" to true for all mode stanzas. In this basic combo mode, all "connstring" fields should point to the same database and any *_addr fields are simply ignored. For more details see the config reference and deployment models
Clair has 3 requirements to start:
+-
+
- The
modeflag orCLAIR_MODEenvironment variable specifying what mode this instance will run in.
+ - The
confflag orCLAIR_CONFenvironment variable specifying where Clair can find its configuration.
+ - A yaml document providing Clair's configuration. +
If you are running a container, you can mount a Clair config and set the CLAIR_CONF environment variable to the corresponding path.
CLAIR_MODE=combo
+CLAIR_CONF=/path/to/mounted/config.yaml
+If you are running a Clair binary directly, its likely easiest to use the command line.
+clair -conf "path/to/config.yaml" -mode "combo"
+Submitting A Manifest
+The simplest way to submit a manifest to your running Clair is utilizing clairctl. This is a CLI tool capable of grabbing image manifests from public repositories and and submitting them for analysis. +The command will be in the Clair container, but can also be installed locally by running the following command:
+go install github.com/quay/clair/v4/cmd/clairctl@latest
+You can submit a manifest to ClairV4 via the following command.
+$ clairctl report --host ${net_address_of_clair} ${image_tag}
+By default, clairctl will look for Clair at localhost:6060.
If everything is configured correctly, you should see some output like the following informing you of vulnerabilities affecting the supplied image.
+$ clairctl report ubuntu:focal
+ubuntu:focal found bash 5.0-6ubuntu1.1 CVE-2019-18276
+ubuntu:focal found libpcre3 2:8.39-12build1 CVE-2017-11164
+ubuntu:focal found libpcre3 2:8.39-12build1 CVE-2019-20838
+ubuntu:focal found libpcre3 2:8.39-12build1 CVE-2020-14155
+ubuntu:focal found libsystemd0 245.4-4ubuntu3.2 CVE-2018-20839
+ubuntu:focal found libsystemd0 245.4-4ubuntu3.2 CVE-2020-13776
+ubuntu:focal found libtasn1-6 4.16.0-2 CVE-2018-1000654
+ubuntu:focal found libudev1 245.4-4ubuntu3.2 CVE-2018-20839
+ubuntu:focal found libudev1 245.4-4ubuntu3.2 CVE-2020-13776
+ubuntu:focal found login 1:4.8.1-1ubuntu5.20.04 CVE-2013-4235
+ubuntu:focal found login 1:4.8.1-1ubuntu5.20.04 CVE-2018-7169
+ubuntu:focal found coreutils 8.30-3ubuntu2 CVE-2016-2781
+ubuntu:focal found passwd 1:4.8.1-1ubuntu5.20.04 CVE-2013-4235
+ubuntu:focal found passwd 1:4.8.1-1ubuntu5.20.04 CVE-2018-7169
+ubuntu:focal found perl-base 5.30.0-9build1 CVE-2020-10543
+ubuntu:focal found perl-base 5.30.0-9build1 CVE-2020-10878
+ubuntu:focal found perl-base 5.30.0-9build1 CVE-2020-12723
+ubuntu:focal found tar 1.30+dfsg-7 CVE-2019-9923
+ubuntu:focal found dpkg 1.19.7ubuntu3 CVE-2017-8283
+ubuntu:focal found gpgv 2.2.19-3ubuntu2 CVE-2019-13050
+ubuntu:focal found libc-bin 2.31-0ubuntu9 CVE-2016-10228
+ubuntu:focal found libc-bin 2.31-0ubuntu9 CVE-2020-6096
+ubuntu:focal found libc6 2.31-0ubuntu9 CVE-2016-10228
+ubuntu:focal found libc6 2.31-0ubuntu9 CVE-2020-6096
+ubuntu:focal found libgcrypt20 1.8.5-5ubuntu1 CVE-2019-12904
+What's Next
+Now that you see the basic usage of Clair, you can checkout our deployment models to learn different ways of deploying.
+You may also be curious about how clairctl did that work. Check out our API definition to understand how an application interacts with Clair.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/index.html b/v4.7.2/index.html
new file mode 100644
index 0000000000..d2fe939bfd
--- /dev/null
+++ b/v4.7.2/index.html
@@ -0,0 +1,256 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Testing Clair
+We provide dev tooling in order to quickly get a fully configured Clair and Quay environment stood up locally. +This environment can be used to test and develop Clair's Quay integration.
+Requirements
+Make
+Make is used to stand up the the local dev environment. +Make is readily available in just about every package manager you can think of. +It's very likely your workstation already has make on it.
+Docker and Docker Compose
+Currently our local dev tooling is supported by docker and docker-compose. +Podman should work fine since v3.0.
+Docker version 19.03.11 and docker-compose version 1.28.6 are confirmed working. +Our assumption is most recent versions will not have an issue running the local dev tooling.
+See Install Docker
+Go Toolchain
+Go v1.16 or higher is required.
+See Install Golang
+Starting a cluster
+git clone git@github.com:quay/clair.git
+cd clair
+docker-compose up -d
+# or: make local-dev
+# or: make local-dev-debug
+# or: make local-dev-quay
+After the local development environment successfully starts, the following infrastructure is available to you:
+-
+
-
+
+localhost:8080+Dashboards and debugging services -- See the traefik configs inlocal-dev/traefikfor where the various services are served.
+ -
+
+localhost:6060+Clair services
+ -
+
Quay (if started) +Quay will be started in a single node, local storage configuration. +A random port will be forwarded from localhost, see
+podman portfor the mapping.
+ -
+
PostgreSQL +PostgreSQL will have a random port forwarded from localhost to the database server. +See
+local-dev/clair/init.sqlfor credentials and permissions andpodman portfor the mapping.
+
Debugging
+With the local-dev-debug make target the operator has access to some more useful tools:
| Tool | Description | URL | Credentials |
|---|---|---|---|
| pgAdmin | Postgres administration | localhost:8080/pgadmin | clair@clair.com:clair |
| jaeger | Distributed tracing | localhost:8080/jaeger | - |
| prometheus | Metrics collection and querying | localhost:8080/prom | - |
| pyroscope | Continuous profiling | localhost:8080/pyroscope | - |
| grafana | Metrics dashboards | localhost:8080/grafana | admin:admin |
Pushing to the Local Quay
+As mentioned above, Quay is forwarded to a random port on the host.
+You can connect to the server on that port and create a account.
+Creating an account named admin will ensure you are a super user.
+An email is required, but is not validated.
+You'll also need to create a namespace.
To push to Quay, you'll need to exec into the skopeo container:
+podman exec -it quay-skopeo /usr/bin/skopeo copy --dst-creds '<user>:<pass>' --dst-tls-verify=false <src> clair-quay:8080/<namespace>/<repo>:<tag>
+Viewing Results
+By default, Quay displays security scanner results on the Tags page of the given repository.
+Making changes to configuration
+You may want to play with either Clair or Quay's configuration.
+If so, the configuration files can be found inside the repository at local-dev/quay/config.yaml and local-dev/clair/config.yaml.
+Any changes to the configs will require a restart of the relevant service.
+The quay-specific clair config is autogenerated, see the Makefile.
Tearing it down
+docker-compose down
+will rip the entire environment down.
+Troubleshooting
+The most common issue encountered when standing up the dev environment is port conflicts. +Make sure that you do not have any other processes listening on any of the ports outlined above.
+The second issue you may face is your Docker resource settings maybe too constrained to support the local dev stack. +This is typically seen on Docker4Mac since a VM is used with a specific set of resources configured. +See Docker For Mac Manual for instructions on how to change these resources.
+If docker-compose reports errors like Unsupported config option for services.activemq: 'profiles', the docker-compose version is too old and you'll need to upgrade.
+Consult the relevant documentation for your environment for instructions.
Lastly, you can view traefik's ui at localhost:8080/dashboard/.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/listing_test.go b/v4.7.2/listing_test.go
new file mode 100644
index 0000000000..c4d0fba7c6
--- /dev/null
+++ b/v4.7.2/listing_test.go
@@ -0,0 +1,72 @@
+package Documentation
+
+import (
+ "bufio"
+ "io/fs"
+ "os"
+ "path"
+ "regexp"
+ "sort"
+ "testing"
+
+ "github.com/google/go-cmp/cmp"
+)
+
+// TestListing fails if the SUMMARY.md falls out of sync with the markdown files
+// in this directory.
+func TestListing(t *testing.T) {
+ // Check that this is the docs test.
+ // These files are copied into the "book" directory, so when left around in
+ // a work tree, test will run there as well.
+ if _, err := os.Stat("index.html"); err == nil {
+ t.Skip("skip listing check in compiled docs")
+ }
+
+ linkline, err := regexp.Compile(`\s*- \[.+\]\((.+)\)`)
+ if err != nil {
+ t.Fatal(err)
+ }
+ f, err := os.Open("SUMMARY.md")
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer f.Close()
+
+ linked := []string{"SUMMARY.md"}
+ s := bufio.NewScanner(f)
+ for s.Scan() {
+ ms := linkline.FindSubmatch(s.Bytes())
+ switch {
+ case ms == nil, len(ms) == 1:
+ continue
+ case len(ms) == 2:
+ linked = append(linked, path.Clean(string(ms[1])))
+ }
+ }
+ if err := s.Err(); err != nil {
+ t.Error(err)
+ }
+ sort.Strings(linked)
+
+ var files []string
+ err = fs.WalkDir(os.DirFS("."), ".", func(p string, d fs.DirEntry, err error) error {
+ switch {
+ case err != nil:
+ return err
+ case d.IsDir():
+ return nil
+ case path.Ext(d.Name()) != ".md":
+ return nil
+ }
+ files = append(files, p)
+ return nil
+ })
+ if err != nil {
+ t.Error(err)
+ }
+ sort.Strings(files)
+
+ if !cmp.Equal(linked, files) {
+ t.Error(cmp.Diff(linked, files))
+ }
+}
diff --git a/v4.7.2/mark.min.js b/v4.7.2/mark.min.js
new file mode 100644
index 0000000000..1636231883
--- /dev/null
+++ b/v4.7.2/mark.min.js
@@ -0,0 +1,7 @@
+/*!***************************************************
+* mark.js v8.11.1
+* https://markjs.io/
+* Copyright (c) 2014–2018, Julian Kühnel
+* Released under the MIT license https://git.io/vwTVl
+*****************************************************/
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):e.Mark=t()}(this,function(){"use strict";var e="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e},t=function(e,t){if(!(e instanceof t))throw new TypeError("Cannot call a class as a function")},n=function(){function e(e,t){for(var n=0;n
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ What is Clair
+Clair is an application for parsing image contents and reporting vulnerabilities affecting the contents. This is done via static analysis and not at runtime.
+Clair supports the extraction of contents and assignment of vulnerabilities from the following official base containers:
+-
+
- Ubuntu +
- Debian +
- RHEL +
- Suse +
- Oracle +
- Alpine +
- AWS Linux +
- VMWare Photon +
- Python +
The above list defines Clair's current support matrix.
+Architecture
+Clair v4 utilizes the ClairCore library as its engine for examining contents and reporting vulnerabilities. At a high level you can consider Clair a service wrapper to the functionality provided in the ClairCore library.
+
The above diagram expresses the separation of concerns between Clair and the ClairCore library. Most development involving new distributions, vulnerability sources, and layer indexing will occur in ClairCore.
+How Clair Works
+Clair's analysis is broken into three distinct parts.
+Indexing
+Indexing starts with submitting a Manifest to Clair. On receipt, Clair will fetch layers, scan their contents, and return an intermediate representation called an IndexReport.
+Manifests are Clair's representation of a container image. Clair leverages the fact that OCI Manifests and Layers are content-addressed to reduce duplicated work.
+Once a Manifest is indexed, the IndexReport is persisted for later retrieval.
+Matching
+Matching is taking an IndexReport and correlating vulnerabilities affecting the manifest the report represents.
+Clair is continually ingesting new security data and a request to the matcher will always provide you with the most up to date vulnerability analysis of an IndexReport.
+How we implement indexing and matching in detail is covered in ClairCore's documentation.
+Notifications
+Clair implements a notification service.
+When new vulnerabilities are discovered, the notifier service will determine if these vulnerabilities affect any indexed Manifests. The notifier will then take action according to its configuration.
+Getting Started
+At this point you'll probably want to check out Getting Started With Clair.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/reference.html b/v4.7.2/reference.html
new file mode 100644
index 0000000000..4ce3cac166
--- /dev/null
+++ b/v4.7.2/reference.html
@@ -0,0 +1,238 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ What is Clair
+Clair is an application for parsing image contents and reporting vulnerabilities affecting the contents. This is done via static analysis and not at runtime.
+Clair supports the extraction of contents and assignment of vulnerabilities from the following official base containers:
+-
+
- Ubuntu +
- Debian +
- RHEL +
- Suse +
- Oracle +
- Alpine +
- AWS Linux +
- VMWare Photon +
- Python +
The above list defines Clair's current support matrix.
+Architecture
+Clair v4 utilizes the ClairCore library as its engine for examining contents and reporting vulnerabilities. At a high level you can consider Clair a service wrapper to the functionality provided in the ClairCore library.
+
The above diagram expresses the separation of concerns between Clair and the ClairCore library. Most development involving new distributions, vulnerability sources, and layer indexing will occur in ClairCore.
+How Clair Works
+Clair's analysis is broken into three distinct parts.
+Indexing
+Indexing starts with submitting a Manifest to Clair. On receipt, Clair will fetch layers, scan their contents, and return an intermediate representation called an IndexReport.
+Manifests are Clair's representation of a container image. Clair leverages the fact that OCI Manifests and Layers are content-addressed to reduce duplicated work.
+Once a Manifest is indexed, the IndexReport is persisted for later retrieval.
+Matching
+Matching is taking an IndexReport and correlating vulnerabilities affecting the manifest the report represents.
+Clair is continually ingesting new security data and a request to the matcher will always provide you with the most up to date vulnerability analysis of an IndexReport.
+How we implement indexing and matching in detail is covered in ClairCore's documentation.
+Notifications
+Clair implements a notification service.
+When new vulnerabilities are discovered, the notifier service will determine if these vulnerabilities affect any indexed Manifests. The notifier will then take action according to its configuration.
+Getting Started
+At this point you'll probably want to check out Getting Started With Clair.
+How Tos
+The following sections provide instructions on accomplish specific goals in Clair.
+ +Getting Started With Clair
+Releases
+All of the source code needed to build clair is packaged as an archive and +attached to the release. Releases are tracked at the github releases.
+The release artifacts also include the clairctl command line tool.
+Official Containers
+Clair is officially packaged and released as a container at
+quay.io/projectquay/clair. The latest tag tracks the git development branch,
+and version tags are built from the corresponding release.
Running Clair
+The easiest way to get Clair up and running for test purposes is to use our local dev environment
+If you're the hands on type who wants to get into the details however, continue reading.
+Modes
+Clair can run in several modes. Indexer, matcher, notifier or combo mode. In combo mode, everything runs in a single OS process.
+If you are just starting with Clair you will most likely want to start with combo mode and venture out to a distributed deployment once acquainted.
+This how-to will demonstrate combo mode and introduce some further reading on a distributed deployment.
+Postgres
+Clair uses PostgreSQL for its data persistence. Migrations are supported so you should only need to point Clair to a fresh database and have it do the setup for you.
+We will assume you have setup a postgres database and it's reachable with the following connection string:
+host=clair-db port=5432 user=clair dbname=clair sslmode=disable. Adjust for your environment accordingly.
Starting Clair In Combo Mode
+At this point, you should either have built Clair from source or have pulled the container. In either case, we will assume that the clair-db hostname will resolve to your postgres database.
You may need to configure docker or podman networking if you are utilizing containers. This is out of scope for this how-to.
+A basic config for combo mode can be found here. Make sure to edit this config with your database settings and set "migrations" to true for all mode stanzas. In this basic combo mode, all "connstring" fields should point to the same database and any *_addr fields are simply ignored. For more details see the config reference and deployment models
Clair has 3 requirements to start:
+-
+
- The
modeflag orCLAIR_MODEenvironment variable specifying what mode this instance will run in.
+ - The
confflag orCLAIR_CONFenvironment variable specifying where Clair can find its configuration.
+ - A yaml document providing Clair's configuration. +
If you are running a container, you can mount a Clair config and set the CLAIR_CONF environment variable to the corresponding path.
CLAIR_MODE=combo
+CLAIR_CONF=/path/to/mounted/config.yaml
+If you are running a Clair binary directly, its likely easiest to use the command line.
+clair -conf "path/to/config.yaml" -mode "combo"
+Submitting A Manifest
+The simplest way to submit a manifest to your running Clair is utilizing clairctl. This is a CLI tool capable of grabbing image manifests from public repositories and and submitting them for analysis. +The command will be in the Clair container, but can also be installed locally by running the following command:
+go install github.com/quay/clair/v4/cmd/clairctl@latest
+You can submit a manifest to ClairV4 via the following command.
+$ clairctl report --host ${net_address_of_clair} ${image_tag}
+By default, clairctl will look for Clair at localhost:6060.
If everything is configured correctly, you should see some output like the following informing you of vulnerabilities affecting the supplied image.
+$ clairctl report ubuntu:focal
+ubuntu:focal found bash 5.0-6ubuntu1.1 CVE-2019-18276
+ubuntu:focal found libpcre3 2:8.39-12build1 CVE-2017-11164
+ubuntu:focal found libpcre3 2:8.39-12build1 CVE-2019-20838
+ubuntu:focal found libpcre3 2:8.39-12build1 CVE-2020-14155
+ubuntu:focal found libsystemd0 245.4-4ubuntu3.2 CVE-2018-20839
+ubuntu:focal found libsystemd0 245.4-4ubuntu3.2 CVE-2020-13776
+ubuntu:focal found libtasn1-6 4.16.0-2 CVE-2018-1000654
+ubuntu:focal found libudev1 245.4-4ubuntu3.2 CVE-2018-20839
+ubuntu:focal found libudev1 245.4-4ubuntu3.2 CVE-2020-13776
+ubuntu:focal found login 1:4.8.1-1ubuntu5.20.04 CVE-2013-4235
+ubuntu:focal found login 1:4.8.1-1ubuntu5.20.04 CVE-2018-7169
+ubuntu:focal found coreutils 8.30-3ubuntu2 CVE-2016-2781
+ubuntu:focal found passwd 1:4.8.1-1ubuntu5.20.04 CVE-2013-4235
+ubuntu:focal found passwd 1:4.8.1-1ubuntu5.20.04 CVE-2018-7169
+ubuntu:focal found perl-base 5.30.0-9build1 CVE-2020-10543
+ubuntu:focal found perl-base 5.30.0-9build1 CVE-2020-10878
+ubuntu:focal found perl-base 5.30.0-9build1 CVE-2020-12723
+ubuntu:focal found tar 1.30+dfsg-7 CVE-2019-9923
+ubuntu:focal found dpkg 1.19.7ubuntu3 CVE-2017-8283
+ubuntu:focal found gpgv 2.2.19-3ubuntu2 CVE-2019-13050
+ubuntu:focal found libc-bin 2.31-0ubuntu9 CVE-2016-10228
+ubuntu:focal found libc-bin 2.31-0ubuntu9 CVE-2020-6096
+ubuntu:focal found libc6 2.31-0ubuntu9 CVE-2016-10228
+ubuntu:focal found libc6 2.31-0ubuntu9 CVE-2020-6096
+ubuntu:focal found libgcrypt20 1.8.5-5ubuntu1 CVE-2019-12904
+What's Next
+Now that you see the basic usage of Clair, you can checkout our deployment models to learn different ways of deploying.
+You may also be curious about how clairctl did that work. Check out our API definition to understand how an application interacts with Clair.
Deploying Clair
+Clair v4 was designed with flexible deployment architectures in mind. The operator is free to choose a deployment model which scales to their use cases.
+Configuration
+Before jumping directly into the models its important to note that Clair is designed to use a single configuration file across all node types. This design decision makes it very easy to deploy on systems like Kubernetes and OpenShift.
+See Config Reference
+Combined Deployment
+In a combined deployment, all the Clair processes run in a single OS process. This is by far the easiest deployment model to configure as it involves the least moving parts.
+A load balancer is still recommended if you plan on performing TLS termination. Typically this will be a OpenShift route or a Kubernetes ingress.
+
In the above diagram, Clair is running in combo mode and talking to a single database. To configure this model you will provide all node types the same database and start Clair in combo mode.
+...
+indexer:
+ connstring: "host=clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+matcher:
+ connstring: "host=clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+ ...
+notifier:
+ connstring: "host=clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+ ...
+In this mode, any configuration informing Clair how to talk to other nodes is ignored, it is not needed as all intra-process communication is done directly.
+For added flexibility, it's also supported to split the databases while in combo mode.
+
In the above diagram, Clair is running in combo mode but database load is split between multiple databases. Since Clair is conceptually a set of micro-services, its processes do not share database tables even when combined into the same OS process.
+To configure this model, you would provide each process its own "connstring" in the configuration.
+...
+indexer:
+ connstring: "host=indexer-clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+matcher:
+ connstring: "host=matcher-clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+ ...
+notifier:
+ connstring: "host=notifier-clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+ ...
+Distributed Deployment
+If your application needs to asymmetrically scale or you expect high load you may want to consider a distributed deployment.
+In a distributed deployment, each Clair process runs in its own OS process. Typically this will be a Kubernetes or OpenShift Pod.
+A load balancer must be setup in this deployment model. The load balancer will route traffic between Clair nodes along with routing API requests via path based routing to the correct services. In a Kubernetes or OpenShift deployment this is usually handled with the Service and Routes abstractions. If deploying on bare metal, a load balancer will need to be configured appropriately.
+
In the above diagram, a load balancer is configured to route traffic coming from the client to the correct service. This routing is path based routing and requires a layer 7 load balancer. Traefik, Nginx, and HAProxy are all capable of this. As mentioned above, this functionality is native to OpenShift and Kubernetes.
+In this configuration, you'd supply each process with database connection strings and addresses for their dependent services. Each OS process will need to have its "mode" CLI flag or environment variable set to the appropriate value. +See Config Reference
+...
+indexer:
+ connstring: "host=indexer-clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+matcher:
+ connstring: "host=matcher-clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+ indexer_addr: "indexer-service"
+ ...
+notifier:
+ connstring: "host=notifier-clairdb user=pqgotest dbname=pqgotest sslmode=verify-full"
+ indexer_addr: "indexer-service"
+ matcher_addr: "matcher-service"
+ ...
+Keep in mind a config file per process is not need. Processes only use the values necessary for their configured mode.
+TLS Termination
+Currently Clair offloads TLS termination to the load balancing infrastructure. This design choice is due to the ubiquity of Kubernetes and OpenShift infrastructure already providing this facility.
+More On Path Routing
+If you are considering a distributed deployment you will need more details on path based routing.
+Learn how to grab our OpenAPI spec here and either start up a local dev instance of the swagger editor or load the spec file into the online editor
+You will notice particular API paths are grouped by the services which implement them. This is your guide to configure your layer 7 load balancer correctly.
+When the load balancer encounters a particular path prefix it must send those request to the correct set of Clair nodes.
+For example, this is how we configure Traefik in our local development environment:
+- "traefik.enable=true"
+- "traefik.http.routers.notifier.entrypoints=clair"
+- "traefik.http.routers.notifier.rule=PathPrefix(`/notifier`)"
+- "traefik.http.routers.notifier.service=notifier"
+- "traefik.http.services.notifier.loadbalancer.server.port=6000"
+This configuration is saying "take any paths prefixes of /notifier/ and send them to the notifier services on port 6000"
+Every load balancer will have their own way to perform path routing. Check the documentation for your infrastructure of choice.
+API Definition
+Clair provides its API definition via an OpenAPI specification. You can view our OpenAPI spec here
+The OpenAPI spec can be used in a variety of ways.
+-
+
- Generating http clients for your application +
- Validating data returned from Clair +
- Importing into a rest client such as Postman +
- API documentation via Swagger Editor +
See Testing Clair to learn how the local dev tooling starts a local swagger editor. This is handy for making changes to the spec in real time.
+See API Reference for a markdown rendered API reference.
+Testing Clair
+We provide dev tooling in order to quickly get a fully configured Clair and Quay environment stood up locally. +This environment can be used to test and develop Clair's Quay integration.
+Requirements
+Make
+Make is used to stand up the the local dev environment. +Make is readily available in just about every package manager you can think of. +It's very likely your workstation already has make on it.
+Docker and Docker Compose
+Currently our local dev tooling is supported by docker and docker-compose. +Podman should work fine since v3.0.
+Docker version 19.03.11 and docker-compose version 1.28.6 are confirmed working. +Our assumption is most recent versions will not have an issue running the local dev tooling.
+See Install Docker
+Go Toolchain
+Go v1.16 or higher is required.
+See Install Golang
+Starting a cluster
+git clone git@github.com:quay/clair.git
+cd clair
+docker-compose up -d
+# or: make local-dev
+# or: make local-dev-debug
+# or: make local-dev-quay
+After the local development environment successfully starts, the following infrastructure is available to you:
+-
+
-
+
+localhost:8080+Dashboards and debugging services -- See the traefik configs inlocal-dev/traefikfor where the various services are served.
+ -
+
+localhost:6060+Clair services
+ -
+
Quay (if started) +Quay will be started in a single node, local storage configuration. +A random port will be forwarded from localhost, see
+podman portfor the mapping.
+ -
+
PostgreSQL +PostgreSQL will have a random port forwarded from localhost to the database server. +See
+local-dev/clair/init.sqlfor credentials and permissions andpodman portfor the mapping.
+
Debugging
+With the local-dev-debug make target the operator has access to some more useful tools:
| Tool | Description | URL | Credentials |
|---|---|---|---|
| pgAdmin | Postgres administration | localhost:8080/pgadmin | clair@clair.com:clair |
| jaeger | Distributed tracing | localhost:8080/jaeger | - |
| prometheus | Metrics collection and querying | localhost:8080/prom | - |
| pyroscope | Continuous profiling | localhost:8080/pyroscope | - |
| grafana | Metrics dashboards | localhost:8080/grafana | admin:admin |
Pushing to the Local Quay
+As mentioned above, Quay is forwarded to a random port on the host.
+You can connect to the server on that port and create a account.
+Creating an account named admin will ensure you are a super user.
+An email is required, but is not validated.
+You'll also need to create a namespace.
To push to Quay, you'll need to exec into the skopeo container:
+podman exec -it quay-skopeo /usr/bin/skopeo copy --dst-creds '<user>:<pass>' --dst-tls-verify=false <src> clair-quay:8080/<namespace>/<repo>:<tag>
+Viewing Results
+By default, Quay displays security scanner results on the Tags page of the given repository.
+Making changes to configuration
+You may want to play with either Clair or Quay's configuration.
+If so, the configuration files can be found inside the repository at local-dev/quay/config.yaml and local-dev/clair/config.yaml.
+Any changes to the configs will require a restart of the relevant service.
+The quay-specific clair config is autogenerated, see the Makefile.
Tearing it down
+docker-compose down
+will rip the entire environment down.
+Troubleshooting
+The most common issue encountered when standing up the dev environment is port conflicts. +Make sure that you do not have any other processes listening on any of the ports outlined above.
+The second issue you may face is your Docker resource settings maybe too constrained to support the local dev stack. +This is typically seen on Docker4Mac since a VM is used with a specific set of resources configured. +See Docker For Mac Manual for instructions on how to change these resources.
+If docker-compose reports errors like Unsupported config option for services.activemq: 'profiles', the docker-compose version is too old and you'll need to upgrade.
+Consult the relevant documentation for your environment for instructions.
Lastly, you can view traefik's ui at localhost:8080/dashboard/.
Concepts
+The following sections give a conceptual overview of how Clair works internally.
+ +Indexing
+The Indexer service is responsble for "indexing a manifest".
+Indexing involves taking a manifest representing a container image and computing its constituent parts. The indexer is trying to discover what packages exist in the image, what distribution the image is derived from, and what package repositories are used within the image. Once this information is computed it is persisted in an IndexReport.
+The IndexReport is an intermediate data structure describing the contents of a container image. This report can be fed to a Matcher node for vulnerability analysis.
+Content Addressability
+ClairV4 treats all manifests and layers as content addressable. In the context of ClairV4 this means once we index a specific manifest we will not index it again unless it's required, and likewise with individual layers. This allows a large reduction in work.
+For example, consider how many images in a registry may use "ubuntu:artful" as a base layer. It could be a large majority of images if the developers prefer basing their images off ubuntu. Treating the layers and manifests as content addressable means we will only fetch and scan the base layer once.
+There are of course conditions where ClairV4 should re-index a manifest.
+When an internal component such as a package scanner is updated, Clair will know to perform the scan with the new package scanner. Clair has enough information to determine that a component has changed and the IndexReport may be different this time around.
+A client can track ClairV4's index_state endpoint to understand when an internal component has changed and subsequently issue re-indexes. See our api guide to learn how to view our api specification.
Summary
+In summary, you should understand that Indexing is the process Clair uses to understand the contents of layers.
+For a more indepth look at indexing check out the ClairCore Documentation
+Matching
+A Matcher node is responsible for matching vulnerabilities to a provided IndexReport.
+Matchers by default are also responsible for keeping the database of vulnerabilities up to date. Matchers will typically run a set of Updaters which periodically probe their data sources for new contents, storing new vulnerabilities in the database when discovered.
+The matcher API is designed to be called often and will always provide the most up-to-date VulnerabilityReport when queried. This VulnerabilityReport summaries both a manifest's contents and any vulnerabilities affecting the contents.
+See our api guide to learn how to view our api specification and work with the Matcher api.
+Remote Matching
+A remote matcher behaves similarly to a matcher, except that it uses api calls to fetch vulnerability data for a provided IndexReport. +Remote matchers are useful when it is not possible to persist data from a given source into the database.
+The crda remote matcher is responsible for fetching vulnerabilities from Red Hat Code Ready Dependency Analytics (CRDA).
+By default, this matcher serves 100 requests per minute.
+The rate-limiting can be lifted by requesting a dedicated API key, which is done via this form.
Summary
+In summary you should understand that a Matcher node provides vulnerability reports given the output of an Indexing process. By default it will also run background Updaters keeping the vulnerability database up-to-date.
+For a more indepth look at indexing check out the ClairCore Documentation
+Internal
+Internal endpoints are underneath /api/v1/internal and are meant for
+communication between Clair microservices. If Clair is operating in combo mode,
+these endpoints may not exist. Any sort of API ingress should disallow clients
+to talk to these endpoints.
We do not formally expose these APIs in our OpenAPI spec. +Further information and usage is an effort left to the reader.
+Updates Diffs
+The update_diff/ endpoint exposes the api for diffing two update operations.
+This is used by the notifier to determine the added and removed vulnerabilities on security databsae update.
Update Operation
+The update_operation endpoint exposes the api for viewing updaters' activity.
+This is used by the notifier to determine if new updates have occured and triggers an update diff to see what has changed.
AffectedManifest
+The affected_manifest endpoint exposes the api for retreiving affected manifests given a list of Vulnerabilities.
+This is used by the notifier to determine the manifests that need to have a notification generated.
Authentication
+Previous versions of Clair used jwtproxy to gate authentication. For ease of +building and deployment, v4 handles authentication itself.
+Authentication is configured by specifying configuration objects underneath the
+auth key of the configuration. Multiple authentication configurations may be
+present, but they will be used preferentially in the order laid out below.
PSK
+Clair implements JWT-based authentication using a pre-shared key.
+Configuration
+The auth stanza of the configuration file requires two parameters: iss, which
+is the issuer to validate on all incoming requests; and key, which is a base64
+encoded symmetric key for validating the requests.
auth:
+ psk:
+ key: >-
+ MDQ4ODBlNDAtNDc0ZC00MWUxLThhMzAtOTk0MzEwMGQwYTMxCg==
+ iss: 'issuer'
+Notifications
+ClairV4 implements a notification system.
+The notifier service will keep track of new security database updates and inform an interested client if new or removed vulnerabilites affect an indexed manifest.
+The interested client can subscribe to notifications via several mechanisms:
+-
+
- Webhook delivery +
- AMQP delivery +
- STOMP delivery +
Configuring the notifier is done via the yaml configuration.
+See the "Notifier" object in our config reference
+A Notification
+When the notifier becomes aware of new vulnerabilities affecting a previously indexed manifest, it will use the configured method(s) to issue notifications about the new changes. Any given notification expresses the most severe vulnerability discovered because of the change. This avoids creating a flurry of notifications for the same security database update.
+Once a client receives a notification, it should issue a new request against the matcher to receive an up-to-date vulnerability report.
+The notification schema is the JSON marshaled form of the following types:
+// Reason indicates the catalyst for a notification
+type Reason string
+const (
+ Added Reason = "added"
+ Removed Reason = "removed"
+ Changed Reason = "changed"
+)
+type Notification struct {
+ ID uuid.UUID `json:"id"`
+ Manifest claircore.Digest `json:"manifest"`
+ Reason Reason `json:"reason"`
+ Vulnerability VulnSummary `json:"vulnerability"`
+}
+type VulnSummary struct {
+ Name string `json:"name"`
+ Description string `json:"description"`
+ Package *claircore.Package `json:"package,omitempty"`
+ Distribution *claircore.Distribution `json:"distribution,omitempty"`
+ Repo *claircore.Repository `json:"repo,omitempty"`
+ Severity string `json:"severity"`
+ FixedInVersion string `json:"fixed_in_version"`
+ Links string `json:"links"`
+}
+Webhook Delivery
+See the "Notifier.Webhook" object in the config reference for complete configuration details.
+When you configure notifier for webhook delivery you provide the service with the following pieces of information:
+-
+
- A target URL where the webhook will fire +
- The callback URL where the notifier may be reached including its API path
+
-
+
- e.g. "http://clair-notifier/notifier/api/v1/notifications" +
+
When the notifier has determined an updated security database has changed the affected status of an indexed manifest, it will deliver the following JSON body to the configured target:
+{
+ "notifiction_id": {uuid_string},
+ "callback": {url_to_notifications}
+}
+On receipt, the server can immediately browse to the URL provided in the callback field.
+Pagination
+The URL returned in the callback field brings the client to a paginated result.
+The callback endpoint specification follows:
+GET /notifier/api/v1/notification/{id}?[page_size=N][next=N]
+{
+ page: {
+ size: int, // maximum number of notifications in the response
+ next: string, // if present, the next id to fetch.
+ }
+ notifications: [ Notification… ] // array of notifications; max len == page.size
+}
+The GET callback request implements a simple bare-minimum paging mechanism.
+The "page_size" url param controls how many notifications are returned in a single page. +If not provided a default of 500 is used.
+The "next" url param informs Clair the next set of paged notifications to return. If not provided the 0th page is assumed.
+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 simply echo back the request page_size parameter.
+When the final page is served to the client the returned "page" data structure will not contain a "next" member.
+Therefore the following loop is valid for obtaining all notifications for a notification id in pages of a specified size.
+{ page, notifications } = http.Get("http://clairv4/notifier/api/v1/notifications/{id}?page_size=1000")
+
+while (page.Next != None) {
+ { page, notifications } = http.Get("http://clairv4/notifier/api/v1/notifications/{id}?next={page.Next},page_size=1000")
+}
+Note: If the client specifies a custom page_size it must specify this page_size on every request for accurate responses.
+Deleting Notifications
+While not mandatory, the client may issue a delete of the notification via a DELETE method. See api to view the delete api.
+Deleting a notification ID will clean up resources in the notifier quicker. Otherwise the notifier will wait a predetermined length of time before clearing delivered notifications from its database.
+AMQP Delivery
+See the "Notifier.AMQP" object in our config reference for complete configuration details.
+The notifier also supports delivering to an AMQP broker. With AMQP delivery you can control whether a callback is delivered to the broker or whether notifications are directly delivered to the queue.
+This allows the developer of the AMQP consumer to determine the logic of notification processing.
+Note that AMQP delivery only supports AMQP 0.x protocol (e.g. RabbitMQ). If you need to publish notifications on AMQP 1.x message queue (e.g. ActiveMQ), you can use STOMP delivery.
+Direct Delivery
+If the notifier's configuration specifies direct: true for AMQP, notifications will be delivered directly to the configured exchange.
When direct is set, the rollup property may be set to instruct the notifier to send a max number of notifications in a single AMQP message. This allows a balance between size of the message and number of messages delivered to the queue.
Testing and Development
+The notifier has a testing mode enabled when it sees the "NOTIFIER_TEST_MODE" environment variable set. It can be set to any value as we only check to see if it exists.
+When this environment variable is set, the notifier will begin sending fake notifications to the configured delivery mechanism every "poll_interval" interval. This provides an easy way to implement and test new or existing deliverers.
+The notifier will run in this mode until the environment variable is cleared and the service is restarted.
+Updaters
+Clair utilizes go packages we call "updaters" that encapsulate the logic of +fetching and parsing different vulnerability databases. Updaters are usually +pared with a matcher to interpret if and how any vulnerability is related to a +package.
+Operators may wish to update the vulnerability database less frequently or not +import vulnerabilities from databases that they know will not be used.
+Configuration
+Updaters can be configured by updaters key at the top of the configuration. If
+updaters are being run automatically within the matcher processes, as is the
+default, the period for running updaters is configured under the matcher's
+configuration stanza.
Choosing Sets
+Specific sets of updaters can be selected by the sets list. If not present,
+the defaults of all upstream updaters will be used.
updaters:
+ sets:
+ - rhel
+Specific Updaters
+Configuration for specific updaters can be passed by putting a key underneath
+the config member of the updaters object. The name of an updater may be
+constructed dynamically; users should examine logs to double-check names.
+The specific object that an updater expects should be covered in the updater's
+documentation.
For example, to have the "rhel" updater fetch a manifest from a different +location:
+updaters:
+ config:
+ rhel:
+ url: https://example.com/mirror/oval/PULP_MANIFEST
+Airgap
+For additional flexibility, Clair supports running updaters in a different
+environment and importing the results. This is aimed at supporting installations
+that disallow the Clair cluster from talking to the Internet directly. An update
+procedure needs to arrange to call the relevant clairctl command in an
+environment with access to the Internet, move the resulting artifact across the
+airgap according to site policy, and then call the relevant clairctl command
+to import the updates.
For example:
+# On a workstation, run:
+clairctl export-updaters updates.json.gz
+# Move the resulting file to a place reachable by the cluster:
+scp updates.json.gz internal-webserver:/var/www/
+# On a pod inside the cluster, import the file:
+clairctl import-updaters http://web.svc/updates.json.gz
+Note that a configuration file is needed to run these commands.
+Configuration
+Matcher processes should have the disable_updaters key set to disable
+automatic updaters running.
matcher:
+ disable_updaters: true
+Indexers
+Configuration
+Airgap
+indexer:
+ airgap: true
+Specific Scanners
+indexer:
+ scanner:
+ package:
+ name:
+ key: value
+ repo:
+ name:
+ key: value
+ dist:
+ name:
+ key: value
+Operation
+Contribuion
+The following sections provides information on how to contribute to Clair.
+-
+
- Commit Style +
- Releases +
Releases
+Clair releases are cut roughly every three months and actively maintained for +six.
+This means that bugfixes should be landed on master (if applicable) and then
+marked for backporting to a minor version's release branch. The process for
+doing this is not yet formalized.
Process
+Minor
+When cutting a new minor release, two things need to be done: creating a tag and +creating a release branch. This can be done like so:
+git tag -as v4.x.0 HEAD
+git push upstream HEAD:release-4.x tag v4.x.0
+Then, a "release" needs to be created in the Github UI using the created tag.
+Patch
+A patch release is just like a minor release with the caveat that minor version +tags should only appear on release branches and a new branch does not need to +be created.
+git checkout release-4.x
+git tag -as v4.x.1 HEAD
+git push upstream tag v4.x.1
+Then, a "release" needs to be created in the Github UI using the created tag.
+Creating Artifacts
+Clair's artifact release process is automated and driven off the releases in +Github.
+Publishing a new release in the Github UI automatically triggers the creation of
+a complete source archive and a container. The archive is attached to the
+release, and the container is pushed to the
+quay.io/projectquay/clair
+repository.
This is all powered by a Github Action in .github/workflows/cut-release.yml.
Commit Style
+The Clair project utilizes well structured commits to keep the history useful and help with release automation. +We suggest signing off on your commits as well.
+A typical commit will take on the following structure:
+<scope>: <subject>
+
+<body>
+Fixes #1
+Pull Request #2
+
+Signed-Off By: <email>
+The header of the commit is regexp checked before commit and your commit will be kicked back if it does not conform.
+Scope
+This is the section of code this commit influences.
+You will often see scopes such as "notifier", "auth", "chore", "cicd".
+We use this field to group commits by scope in our automated changelog generation.
+It would be wise to take a look at our changelog before contributing to get an idea of the common scopes we use.
+Subject
+Subject is a short and concise summary of the change the commit is introducing. It should be a sentence fragment without starting capitalization and ending punctuation and limited to about 60 characters, to allow for the scope prefix and decoration in the git log.
+Body
+Body should be full of detail.
+Explain what this commit is doing and why it is necessary.
+You may include references to issues and pull requests as well. Our automated changelog process will discover references prefixed with "Fixes", "Closed" and "Pull Request"
+Reference
+The following sections provide reference information useful when exploring the documentation or working with Clair directly.
+ ++
title: ClairV4 v1.1 +language_tabs:
+-
+
- python: Python +
- go: Golang +
- javascript: Javascript +language_clients: +
- python: "" +
- go: "" +
- javascript: "" +toc_footers: [] +includes: [] +search: false +highlight_theme: darkula +headingLevel: 2 +
+ +
ClairV4 v1.1
+++Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
+
ClairV4 is a set of cooperating microservices which scan, index, and match your container's content with known vulnerabilities.
+Email: Clair Team Web: Clair Team +License: Apache License 2.0
+Notifier
+DeleteNotification
+ +++Code samples
+
import requests
+headers = {
+ 'Accept': 'application/json'
+}
+
+r = requests.delete('/notifier/api/v1/notification/{notification_id}', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("DELETE", "/notifier/api/v1/notification/{notification_id}", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+
+const headers = {
+ 'Accept':'application/json'
+};
+
+fetch('/notifier/api/v1/notification/{notification_id}',
+{
+ method: 'DELETE',
+
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+DELETE /notifier/api/v1/notification/{notification_id}
Issues a delete of the provided notification id and all associated notifications. After this delete clients will no longer be able to retrieve notifications.
+Parameters
+| Name | In | Type | Required | Description |
|---|---|---|---|---|
| notification_id | path | string | false | A notification ID returned by a callback |
++Example responses
+
++400 Response
+
{
+ "code": "string",
+ "message": "string"
+}
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | None |
| 400 | Bad Request | Bad Request | Error |
| 405 | Method Not Allowed | Method Not Allowed | Error |
| 500 | Internal Server Error | Internal Server Error | Error |
Retrieve a paginated result of notifications for the provided id.
+ +++Code samples
+
import requests
+headers = {
+ 'Accept': 'application/json'
+}
+
+r = requests.get('/notifier/api/v1/notification/{notification_id}', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("GET", "/notifier/api/v1/notification/{notification_id}", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+
+const headers = {
+ 'Accept':'application/json'
+};
+
+fetch('/notifier/api/v1/notification/{notification_id}',
+{
+ method: 'GET',
+
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+GET /notifier/api/v1/notification/{notification_id}
By performing a GET with a notification_id as a path parameter, the client will retrieve a paginated response of notification objects.
+Parameters
+| Name | In | Type | Required | Description |
|---|---|---|---|---|
| notification_id | path | string | false | A notification ID returned by a callback |
| page_size | query | int | false | The maximum number of notifications to deliver in a single page. |
| next | query | string | false | The next page to fetch via id. Typically this number is provided on initial response in the page.next field. The first GET request may omit this field. |
++Example responses
+
++200 Response
+
{
+ "page": {
+ "size": 100,
+ "next": "1b4d0db2-e757-4150-bbbb-543658144205"
+ },
+ "notifications": [
+ {
+ "id": "5e4b387e-88d3-4364-86fd-063447a6fad2",
+ "manifest": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "reason": "added",
+ "vulnerability": {
+ "name": "CVE-2009-5155",
+ "fixed_in_version": "v0.0.1",
+ "links": "http://link-to-advisory",
+ "description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.\"",
+ "normalized_severity": "Unknown",
+ "package": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ },
+ "distribution": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ },
+ "repository": {
+ "id": "string",
+ "name": "string",
+ "key": "string",
+ "uri": "string",
+ "cpe": "string"
+ }
+ }
+ }
+ ]
+}
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | A paginated list of notifications | PagedNotifications |
| 400 | Bad Request | Bad Request | Error |
| 405 | Method Not Allowed | Method Not Allowed | Error |
| 500 | Internal Server Error | Internal Server Error | Error |
Indexer
+Index the contents of a Manifest
+ +++Code samples
+
import requests
+headers = {
+ 'Content-Type': 'application/json',
+ 'Accept': 'application/json'
+}
+
+r = requests.post('/indexer/api/v1/index_report', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Content-Type": []string{"application/json"},
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("POST", "/indexer/api/v1/index_report", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+const inputBody = '{
+ "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "layers": [
+ {
+ "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "uri": "https://storage.example.com/blob/2f077db56abccc19f16f140f629ae98e904b4b7d563957a7fc319bd11b82ba36",
+ "headers": {
+ "property1": [
+ "string"
+ ],
+ "property2": [
+ "string"
+ ]
+ }
+ }
+ ]
+}';
+const headers = {
+ 'Content-Type':'application/json',
+ 'Accept':'application/json'
+};
+
+fetch('/indexer/api/v1/index_report',
+{
+ method: 'POST',
+ body: inputBody,
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+POST /indexer/api/v1/index_report
By submitting a Manifest object to this endpoint Clair will fetch the layers, scan each layer's contents, and provide an index of discovered packages, repository and distribution information.
+++Body parameter
+
{
+ "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "layers": [
+ {
+ "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "uri": "https://storage.example.com/blob/2f077db56abccc19f16f140f629ae98e904b4b7d563957a7fc319bd11b82ba36",
+ "headers": {
+ "property1": [
+ "string"
+ ],
+ "property2": [
+ "string"
+ ]
+ }
+ }
+ ]
+}
+Parameters
+| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | Manifest | true | none |
++Example responses
+
++201 Response
+
{
+ "manifest_hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "state": "IndexFinished",
+ "packages": {
+ "10": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ }
+ },
+ "distributions": {
+ "1": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ }
+ },
+ "environments": {
+ "10": [
+ {
+ "package_db": "var/lib/dpkg/status",
+ "introduced_in": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "distribution_id": "1"
+ }
+ ]
+ },
+ "success": true,
+ "err": ""
+}
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | IndexReport Created | IndexReport |
| 400 | Bad Request | Bad Request | Error |
| 405 | Method Not Allowed | Method Not Allowed | Error |
| 500 | Internal Server Error | Internal Server Error | Error |
Delete the IndexReport and associated information for the given Manifest hashes, if they exist.
+ +++Code samples
+
import requests
+headers = {
+ 'Content-Type': 'application/json',
+ 'Accept': 'application/json'
+}
+
+r = requests.delete('/indexer/api/v1/index_report', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Content-Type": []string{"application/json"},
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("DELETE", "/indexer/api/v1/index_report", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+const inputBody = '[
+ "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3"
+]';
+const headers = {
+ 'Content-Type':'application/json',
+ 'Accept':'application/json'
+};
+
+fetch('/indexer/api/v1/index_report',
+{
+ method: 'DELETE',
+ body: inputBody,
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+DELETE /indexer/api/v1/index_report
Given a Manifest's content addressable hash, any data related to it will be removed if it exists.
+++Body parameter
+
[
+ "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3"
+]
+Parameters
+| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | BulkDelete | true | none |
++Example responses
+
++200 Response
+
[
+ "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3"
+]
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | BulkDelete |
| 400 | Bad Request | Bad Request | Error |
| 500 | Internal Server Error | Internal Server Error | Error |
Delete the IndexReport and associated information for the given Manifest hash, if exists.
+ +++Code samples
+
import requests
+headers = {
+ 'Accept': 'application/json'
+}
+
+r = requests.delete('/indexer/api/v1/index_report/{manifest_hash}', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("DELETE", "/indexer/api/v1/index_report/{manifest_hash}", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+
+const headers = {
+ 'Accept':'application/json'
+};
+
+fetch('/indexer/api/v1/index_report/{manifest_hash}',
+{
+ method: 'DELETE',
+
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+DELETE /indexer/api/v1/index_report/{manifest_hash}
Given a Manifest's content addressable hash, any data related to it will be removed it it exists.
+Parameters
+| Name | In | Type | Required | Description |
|---|---|---|---|---|
| manifest_hash | path | Digest | true | A digest of a manifest that has been indexed previous to this request. |
++Example responses
+
++400 Response
+
{
+ "code": "string",
+ "message": "string"
+}
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | OK | None |
| 400 | Bad Request | Bad Request | Error |
| 500 | Internal Server Error | Internal Server Error | Error |
Retrieve an IndexReport for the given Manifest hash if exists.
+ +++Code samples
+
import requests
+headers = {
+ 'Accept': 'application/json'
+}
+
+r = requests.get('/indexer/api/v1/index_report/{manifest_hash}', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("GET", "/indexer/api/v1/index_report/{manifest_hash}", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+
+const headers = {
+ 'Accept':'application/json'
+};
+
+fetch('/indexer/api/v1/index_report/{manifest_hash}',
+{
+ method: 'GET',
+
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+GET /indexer/api/v1/index_report/{manifest_hash}
Given a Manifest's content addressable hash an IndexReport will be retrieved if exists.
+Parameters
+| Name | In | Type | Required | Description |
|---|---|---|---|---|
| manifest_hash | path | Digest | true | A digest of a manifest that has been indexed previous to this request. |
++Example responses
+
++200 Response
+
{
+ "manifest_hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "state": "IndexFinished",
+ "packages": {
+ "10": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ }
+ },
+ "distributions": {
+ "1": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ }
+ },
+ "environments": {
+ "10": [
+ {
+ "package_db": "var/lib/dpkg/status",
+ "introduced_in": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "distribution_id": "1"
+ }
+ ]
+ },
+ "success": true,
+ "err": ""
+}
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | IndexReport retrieved | IndexReport |
| 400 | Bad Request | Bad Request | Error |
| 404 | Not Found | Not Found | Error |
| 405 | Method Not Allowed | Method Not Allowed | Error |
| 500 | Internal Server Error | Internal Server Error | Error |
Report the indexer's internal configuration and state.
+ +++Code samples
+
import requests
+headers = {
+ 'Accept': 'application/json'
+}
+
+r = requests.get('/indexer/api/v1/index_state', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("GET", "/indexer/api/v1/index_state", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+
+const headers = {
+ 'Accept':'application/json'
+};
+
+fetch('/indexer/api/v1/index_state',
+{
+ method: 'GET',
+
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+GET /indexer/api/v1/index_state
The index state endpoint returns a json structure indicating the indexer's internal configuration state. +A client may be interested in this as a signal that manifests may need to be re-indexed.
+++Example responses
+
++200 Response
+
{
+ "state": "aae368a064d7c5a433d0bf2c4f5554cc"
+}
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Indexer State | State |
| 304 | Not Modified | Indexer State Unchanged | None |
Response Headers
+| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | Etag | string | Entity Tag |
Matcher
+Retrieve a VulnerabilityReport for a given manifest's content addressable hash.
+ +++Code samples
+
import requests
+headers = {
+ 'Accept': 'application/json'
+}
+
+r = requests.get('/matcher/api/v1/vulnerability_report/{manifest_hash}', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("GET", "/matcher/api/v1/vulnerability_report/{manifest_hash}", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+
+const headers = {
+ 'Accept':'application/json'
+};
+
+fetch('/matcher/api/v1/vulnerability_report/{manifest_hash}',
+{
+ method: 'GET',
+
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+GET /matcher/api/v1/vulnerability_report/{manifest_hash}
Given a Manifest's content addressable hash a VulnerabilityReport will be created. The Manifest must have been Indexed first via the Index endpoint.
+Parameters
+| Name | In | Type | Required | Description |
|---|---|---|---|---|
| manifest_hash | path | Digest | true | A digest of a manifest that has been indexed previous to this request. |
++Example responses
+
++201 Response
+
{
+ "manifest_hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "packages": {
+ "10": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ }
+ },
+ "distributions": {
+ "1": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ }
+ },
+ "environments": {
+ "10": [
+ {
+ "package_db": "var/lib/dpkg/status",
+ "introduced_in": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "distribution_id": "1"
+ }
+ ]
+ },
+ "vulnerabilities": {
+ "356835": {
+ "id": "356835",
+ "updater": "",
+ "name": "CVE-2009-5155",
+ "description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.\"",
+ "links": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-5155 http://people.canonical.com/~ubuntu-security/cve/2009/CVE-2009-5155.html https://sourceware.org/bugzilla/show_bug.cgi?id=11053 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22793 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=32806 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=34238 https://sourceware.org/bugzilla/show_bug.cgi?id=18986\"",
+ "severity": "Low",
+ "normalized_severity": "Low",
+ "package": {
+ "id": "0",
+ "name": "glibc",
+ "version": "",
+ "kind": "",
+ "source": null,
+ "package_db": "",
+ "repository_hint": ""
+ },
+ "dist": {
+ "id": "0",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": ""
+ },
+ "repo": {
+ "id": "0",
+ "name": "Ubuntu 18.04.3 LTS",
+ "key": "",
+ "uri": ""
+ },
+ "issued": "2019-10-12T07:20:50.52Z",
+ "fixed_in_version": "2.28-0ubuntu1"
+ }
+ },
+ "package_vulnerabilities": {
+ "10": [
+ "356835"
+ ]
+ }
+}
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | VulnerabilityReport Created | VulnerabilityReport |
| 400 | Bad Request | Bad Request | Error |
| 404 | Not Found | Not Found | Error |
| 405 | Method Not Allowed | Method Not Allowed | Error |
| 500 | Internal Server Error | Internal Server Error | Error |
Schemas
+Page
+ + + + + +{
+ "size": 1,
+ "next": "1b4d0db2-e757-4150-bbbb-543658144205"
+}
+
+Page
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| size | int | false | none | The maximum number of elements in a page |
| next | string | false | none | The next id to submit to the api to continue paging |
PagedNotifications
+ + + + + +{
+ "page": {
+ "size": 100,
+ "next": "1b4d0db2-e757-4150-bbbb-543658144205"
+ },
+ "notifications": [
+ {
+ "id": "5e4b387e-88d3-4364-86fd-063447a6fad2",
+ "manifest": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "reason": "added",
+ "vulnerability": {
+ "name": "CVE-2009-5155",
+ "fixed_in_version": "v0.0.1",
+ "links": "http://link-to-advisory",
+ "description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.\"",
+ "normalized_severity": "Unknown",
+ "package": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ },
+ "distribution": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ },
+ "repository": {
+ "id": "string",
+ "name": "string",
+ "key": "string",
+ "uri": "string",
+ "cpe": "string"
+ }
+ }
+ }
+ ]
+}
+
+PagedNotifications
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| page | object | false | none | A page object informing the client the next page to retrieve. If page.next becomes "-1" the client should stop paging. |
| notifications | [Notification] | false | none | A list of notifications within this page |
Callback
+ + + + + +{
+ "notification_id": "269886f3-0146-4f08-9bf7-cb1138d48643",
+ "callback": "http://clair-notifier/notifier/api/v1/notifications/269886f3-0146-4f08-9bf7-cb1138d48643"
+}
+
+Callback
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| notification_id | string | false | none | the unique identifier for this set of notifications |
| callback | string | false | none | the url where notifications can be retrieved |
VulnSummary
+ + + + + +{
+ "name": "CVE-2009-5155",
+ "fixed_in_version": "v0.0.1",
+ "links": "http://link-to-advisory",
+ "description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.\"",
+ "normalized_severity": "Unknown",
+ "package": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ },
+ "distribution": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ },
+ "repository": {
+ "id": "string",
+ "name": "string",
+ "key": "string",
+ "uri": "string",
+ "cpe": "string"
+ }
+}
+
+VulnSummary
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| name | string | false | none | the vulnerability name |
| fixed_in_version | string | false | none | The version which the vulnerability is fixed in. Empty if not fixed. |
| links | string | false | none | links to external information about vulnerability |
| description | string | false | none | the vulnerability name |
| normalized_severity | string | false | none | A well defined set of severity strings guaranteed to be present. |
| package | Package | false | none | A package discovered by indexing a Manifest |
| distribution | Distribution | false | none | An indexed distribution discovered in a layer. See https://www.freedesktop.org/software/systemd/man/os-release.html for explanations and example of fields. |
| repository | Repository | false | none | A package repository |
Enumerated Values
+| Property | Value |
|---|---|
| normalized_severity | Unknown |
| normalized_severity | Negligible |
| normalized_severity | Low |
| normalized_severity | Medium |
| normalized_severity | High |
| normalized_severity | Critical |
Notification
+ + + + + +{
+ "id": "5e4b387e-88d3-4364-86fd-063447a6fad2",
+ "manifest": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "reason": "added",
+ "vulnerability": {
+ "name": "CVE-2009-5155",
+ "fixed_in_version": "v0.0.1",
+ "links": "http://link-to-advisory",
+ "description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.\"",
+ "normalized_severity": "Unknown",
+ "package": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ },
+ "distribution": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ },
+ "repository": {
+ "id": "string",
+ "name": "string",
+ "key": "string",
+ "uri": "string",
+ "cpe": "string"
+ }
+ }
+}
+
+Notification
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | false | none | a unique identifier for this notification |
| manifest | string | false | none | The hash of the manifest affected by the provided vulnerability. |
| reason | string | false | none | the reason for the notifcation, [added |
| vulnerability | VulnSummary | false | none | A summary of a vulnerability |
Environment
+ + + + + +{
+ "package_db": "var/lib/dpkg/status",
+ "introduced_in": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "distribution_id": "1"
+}
+
+Environment
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| package_db | string | true | none | The filesystem path or unique identifier of a package database. |
| introduced_in | Digest | true | none | A digest string with prefixed algorithm. The format is described here: https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests Digests are used throughout the API to identify Layers and Manifests. |
| distribution_id | string | true | none | The distribution ID found in an associated IndexReport or VulnerabilityReport. |
IndexReport
+ + + + + +{
+ "manifest_hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "state": "IndexFinished",
+ "packages": {
+ "10": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ }
+ },
+ "distributions": {
+ "1": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ }
+ },
+ "environments": {
+ "10": [
+ {
+ "package_db": "var/lib/dpkg/status",
+ "introduced_in": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "distribution_id": "1"
+ }
+ ]
+ },
+ "success": true,
+ "err": ""
+}
+
+IndexReport
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| manifest_hash | Digest | true | none | A digest string with prefixed algorithm. The format is described here: https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests Digests are used throughout the API to identify Layers and Manifests. |
| state | string | true | none | The current state of the index operation |
| packages | object | true | none | A map of Package objects indexed by Package.id |
| » additionalProperties | Package | false | none | A package discovered by indexing a Manifest |
| distributions | object | true | none | A map of Distribution objects keyed by their Distribution.id discovered in the manifest. |
| » additionalProperties | Distribution | false | none | An indexed distribution discovered in a layer. See https://www.freedesktop.org/software/systemd/man/os-release.html for explanations and example of fields. |
| environments | object | true | none | A map of lists containing Environment objects keyed by the associated Package.id. |
| » additionalProperties | [Environment] | false | none | [The environment a particular package was discovered in.] |
| success | boolean | true | none | A bool indicating succcessful index |
| err | string | true | none | An error message on event of unsuccessful index |
VulnerabilityReport
+ + + + + +{
+ "manifest_hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "packages": {
+ "10": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ }
+ },
+ "distributions": {
+ "1": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ }
+ },
+ "environments": {
+ "10": [
+ {
+ "package_db": "var/lib/dpkg/status",
+ "introduced_in": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "distribution_id": "1"
+ }
+ ]
+ },
+ "vulnerabilities": {
+ "356835": {
+ "id": "356835",
+ "updater": "",
+ "name": "CVE-2009-5155",
+ "description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.\"",
+ "links": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-5155 http://people.canonical.com/~ubuntu-security/cve/2009/CVE-2009-5155.html https://sourceware.org/bugzilla/show_bug.cgi?id=11053 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22793 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=32806 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=34238 https://sourceware.org/bugzilla/show_bug.cgi?id=18986\"",
+ "severity": "Low",
+ "normalized_severity": "Low",
+ "package": {
+ "id": "0",
+ "name": "glibc",
+ "version": "",
+ "kind": "",
+ "source": null,
+ "package_db": "",
+ "repository_hint": ""
+ },
+ "dist": {
+ "id": "0",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": ""
+ },
+ "repo": {
+ "id": "0",
+ "name": "Ubuntu 18.04.3 LTS",
+ "key": "",
+ "uri": ""
+ },
+ "issued": "2019-10-12T07:20:50.52Z",
+ "fixed_in_version": "2.28-0ubuntu1"
+ }
+ },
+ "package_vulnerabilities": {
+ "10": [
+ "356835"
+ ]
+ }
+}
+
+VulnerabilityReport
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| manifest_hash | Digest | true | none | A digest string with prefixed algorithm. The format is described here: https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests Digests are used throughout the API to identify Layers and Manifests. |
| packages | object | true | none | A map of Package objects indexed by Package.id |
| » additionalProperties | Package | false | none | A package discovered by indexing a Manifest |
| distributions | object | true | none | A map of Distribution objects indexed by Distribution.id. |
| » additionalProperties | Distribution | false | none | An indexed distribution discovered in a layer. See https://www.freedesktop.org/software/systemd/man/os-release.html for explanations and example of fields. |
| environments | object | true | none | A mapping of Environment lists indexed by Package.id |
| » additionalProperties | [Environment] | false | none | [The environment a particular package was discovered in.] |
| vulnerabilities | object | true | none | A map of Vulnerabilities indexed by Vulnerability.id |
| » additionalProperties | Vulnerability | false | none | A unique vulnerability indexed by Clair |
| package_vulnerabilities | object | true | none | A mapping of Vulnerability.id lists indexed by Package.id. |
| » additionalProperties | [string] | false | none | none |
Vulnerability
+ + + + + +{
+ "id": "356835",
+ "updater": "",
+ "name": "CVE-2009-5155",
+ "description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.\"",
+ "links": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-5155 http://people.canonical.com/~ubuntu-security/cve/2009/CVE-2009-5155.html https://sourceware.org/bugzilla/show_bug.cgi?id=11053 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22793 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=32806 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=34238 https://sourceware.org/bugzilla/show_bug.cgi?id=18986\"",
+ "severity": "Low",
+ "normalized_severity": "Low",
+ "package": {
+ "id": "0",
+ "name": "glibc",
+ "version": "",
+ "kind": "",
+ "source": null,
+ "package_db": "",
+ "repository_hint": ""
+ },
+ "dist": {
+ "id": "0",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": ""
+ },
+ "repo": {
+ "id": "0",
+ "name": "Ubuntu 18.04.3 LTS",
+ "key": "",
+ "uri": ""
+ },
+ "issued": "2019-10-12T07:20:50.52Z",
+ "fixed_in_version": "2.28-0ubuntu1",
+ "x-widdershins-oldRef": "#/components/examples/Vulnerability/value"
+}
+
+Vulnerability
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | A unique ID representing this vulnerability. |
| updater | string | true | none | A unique ID representing this vulnerability. |
| name | string | true | none | Name of this specific vulnerability. |
| description | string | true | none | A description of this specific vulnerability. |
| links | string | true | none | A space separate list of links to any external information. |
| severity | string | true | none | A severity keyword taken verbatim from the vulnerability source. |
| normalized_severity | string | true | none | A well defined set of severity strings guaranteed to be present. |
| package | Package | false | none | A package discovered by indexing a Manifest |
| distribution | Distribution | false | none | An indexed distribution discovered in a layer. See https://www.freedesktop.org/software/systemd/man/os-release.html for explanations and example of fields. |
| repository | Repository | false | none | A package repository |
| issued | string | false | none | The timestamp in which the vulnerability was issued |
| range | string | false | none | The range of package versions affected by this vulnerability. |
| fixed_in_version | string | true | none | A unique ID representing this vulnerability. |
Enumerated Values
+| Property | Value |
|---|---|
| normalized_severity | Unknown |
| normalized_severity | Negligible |
| normalized_severity | Low |
| normalized_severity | Medium |
| normalized_severity | High |
| normalized_severity | Critical |
Distribution
+ + + + + +{
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS",
+ "x-widdershins-oldRef": "#/components/examples/Distribution/value"
+}
+
+Distribution
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | A unique ID representing this distribution |
| did | string | true | none | none |
| name | string | true | none | none |
| version | string | true | none | none |
| version_code_name | string | true | none | none |
| version_id | string | true | none | none |
| arch | string | true | none | none |
| cpe | string | true | none | none |
| pretty_name | string | true | none | none |
SourcePackage
+ + + + + +{
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ },
+ "x-widdershins-oldRef": "#/components/examples/Package/value"
+}
+
+SourcePackage
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | A unique ID representing this package |
| name | string | true | none | Name of the Package |
| version | string | true | none | Version of the Package |
| kind | string | false | none | Kind of package. Source |
| source | string | false | none | none |
| normalized_version | Version | false | none | Version is a normalized claircore version, composed of a "kind" and an array of integers such that two versions of the same kind have the correct ordering when the integers are compared pair-wise. |
| arch | string | false | none | none |
| module | string | false | none | none |
| cpe | string | false | none | A CPE identifying the package |
Package
+ + + + + +{
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ },
+ "x-widdershins-oldRef": "#/components/examples/Package/value"
+}
+
+Package
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | A unique ID representing this package |
| name | string | true | none | Name of the Package |
| version | string | true | none | Version of the Package |
| kind | string | false | none | Kind of package. Source |
| source | SourcePackage | false | none | A source package affiliated with a Package |
| normalized_version | Version | false | none | Version is a normalized claircore version, composed of a "kind" and an array of integers such that two versions of the same kind have the correct ordering when the integers are compared pair-wise. |
| arch | string | false | none | The package's target system architecture |
| module | string | false | none | A module further defining a namespace for a package |
| cpe | string | false | none | A CPE identifying the package |
Repository
+ + + + + +{
+ "id": "string",
+ "name": "string",
+ "key": "string",
+ "uri": "string",
+ "cpe": "string"
+}
+
+Repository
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | false | none | none |
| name | string | false | none | none |
| key | string | false | none | none |
| uri | string | false | none | none |
| cpe | string | false | none | none |
Version
+ + + + + +"pep440:0.0.0.0.0.0.0.0.0"
+
+Version
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| Version | string | false | none | Version is a normalized claircore version, composed of a "kind" and an array of integers such that two versions of the same kind have the correct ordering when the integers are compared pair-wise. |
Manifest
+ + + + + +{
+ "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "layers": [
+ {
+ "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "uri": "https://storage.example.com/blob/2f077db56abccc19f16f140f629ae98e904b4b7d563957a7fc319bd11b82ba36",
+ "headers": {
+ "property1": [
+ "string"
+ ],
+ "property2": [
+ "string"
+ ]
+ }
+ }
+ ]
+}
+
+Manifest
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| hash | Digest | true | none | A digest string with prefixed algorithm. The format is described here: https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests Digests are used throughout the API to identify Layers and Manifests. |
| layers | [Layer] | true | none | [A Layer within a Manifest and where Clair may retrieve it.] |
Layer
+ + + + + +{
+ "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "uri": "https://storage.example.com/blob/2f077db56abccc19f16f140f629ae98e904b4b7d563957a7fc319bd11b82ba36",
+ "headers": {
+ "property1": [
+ "string"
+ ],
+ "property2": [
+ "string"
+ ]
+ }
+}
+
+Layer
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| hash | Digest | true | none | A digest string with prefixed algorithm. The format is described here: https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests Digests are used throughout the API to identify Layers and Manifests. |
| uri | string | true | none | A URI describing where the layer may be found. Implementations MUST support http(s) schemes and MAY support additional schemes. |
| headers | object | true | none | map of arrays of header values keyed by header value. e.g. map[string][]string |
| » additionalProperties | [string] | false | none | none |
BulkDelete
+ + + + + +[
+ "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3"
+]
+
+BulkDelete
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| BulkDelete | [Digest] | false | none | An array of Digests to be deleted. |
Error
+ + + + + +{
+ "code": "string",
+ "message": "string"
+}
+
+Error
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| code | string | false | none | a code for this particular error |
| message | string | false | none | a message with further detail |
State
+ + + + + +{
+ "state": "aae368a064d7c5a433d0bf2c4f5554cc"
+}
+
+State
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| state | string | true | none | an opaque identifier |
Digest
+ + + + + +"sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3"
+
+Digest
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| Digest | string | false | none | A digest string with prefixed algorithm. The format is described here: https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests Digests are used throughout the API to identify Layers and Manifests. |
Clairctl
+clairctl is a command line tool for working with Clair.
+This CLI is capable of generating manifests from most public registries
+(dockerhub, quay.io, Red Hat Container Catalog) and submitting them for
+analysis to a running Clair.
Note that if the Clair instance has authentication configured, the value
+provided to the issuer flag must be on the list accepted by the server.
NAME:
+ clairctl - interact with a clair API
+
+USAGE:
+ clairctl [global options] command [command options] [arguments...]
+
+VERSION:
+ 0.1.0
+
+DESCRIPTION:
+ A command-line tool for clair v4.
+
+COMMANDS:
+ manifest print a clair manifest for the named container
+ report request vulnerability reports for the named containers
+ export-updaters run updaters and export results
+ import-updaters import updates
+ help, h Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+ -D print debugging logs (default: false)
+ --config value, -c value clair configuration file (default: "config.yaml") [$CLAIR_CONF]
+ --issuer value, --iss value jwt "issuer" to use when making authenticated requests (default: "clairctl")
+ --help, -h show help (default: false)
+ --version, -v print the version (default: false)
+NAME:
+ clairctl manifest - print a clair manifest for the named container
+
+USAGE:
+ clairctl manifest [arguments...]
+
+DESCRIPTION:
+ print a clair manifest for the named container
+NAME:
+ clairctl report - request vulnerability reports for the named containers
+
+USAGE:
+ clairctl report [command options] container...
+
+DESCRIPTION:
+ Request and print a Clair vulnerability report for the named container(s).
+
+OPTIONS:
+ --host value URL for the clairv4 v1 API. (default: "http://localhost:6060/") [$CLAIR_API]
+ --out value, -o value output format: text, json, xml (default: text)
+NAME:
+ clairctl export-updaters - run updaters and export results
+
+USAGE:
+ clairctl export-updaters [command options] [out]
+
+DESCRIPTION:
+ Run configured exporters and export to a file.
+
+ A configuration file is needed to run this command, see 'clairctl help'
+ for how to specify one.
+
+OPTIONS:
+ --strict Return non-zero exit when updaters report errors. (default: false)
+NAME:
+ clairctl import-updaters - import updates
+
+USAGE:
+ clairctl import-updaters input...
+
+DESCRIPTION:
+ Import updates from files or HTTP URIs.
+
+ A configuration file is needed to run this command, see 'clairctl help'
+ for how to specify one.
+Config
+CLI Flags And Environment Variables
+Clair is configured by a structured yaml or JSON1 file and an optional directory of "merge" and "patch" documents1. +Each Clair node needs to specify what mode it will run in and a path to a configuration file via CLI flags or environment variables.
+For example:
+$ clair -conf ./path/to/config.yaml -mode indexer
+$ clair -conf ./path/to/config.yaml -mode matcher
+-mode
+ (also specified by CLAIR_MODE env variable)
+ One of the following strings
+ Sets which mode the clair instances will run in
+
+ "indexer": runs just the indexer node
+ "matcher": runs just the matcher node
+ "notifier": runs just the notifier node
+ "combo": will run all services on the same node.
+-conf
+ (also specified by CLAIR_CONF env variable)
+ A file system path to Clair's config file
+The above example starts two Clair nodes using the same configuration. +One will only run the indexing facilities while the other will only run the matching facilities.
+Environment variables respected by the Go standard library can be specified +if needed. Some notable examples:
+-
+
HTTP_PROXY
+HTTPS_PROXY
+SSL_CERT_DIR
+
If running in "combo" mode you must supply the indexer, matcher,
+and notifier configuration blocks in the configuration.
Configuration dropins
+Starting in Clair version 4.7.0, dropin configuration files are supported.
Given a root configurtaion file of /etc/clair/config.json, all files matching the globs /etc/clair/config.json.d/*.json and /etc/clair/config.json.d/*.json-patch would be loaded in lexical order after the root configuration file.
+Similarly, given /etc/clair/config.yaml, all files matching the globs /etc/clair/config.yaml.d/*.yaml and /etc/clair/config.yaml.d/*.yaml-patch would be loaded.
+Only the extensions yaml and json are supported, and indicate yaml and JSON formatting, respectively.
The dropin files must have the same extension and format as the root file.
+Dropins with the bare suffix are treated as merge documents.
+Dropins with the -patch suffix are treated as patch documents and must contain a valid RFC 6902 structure.
+Yaml documents must be resolvable to the JSON subset.
Take care with the merge behavior around lists; a patch operation may be more suitable.
+The clairctl check-config command can be used to ensure a merged configuration is what is intended.
+In addition, placing test operations in a patch file that's evaluated last (such as zz-validate.json-patch) can be used to have Clair refuse to start if some configuration values are not what is intended.
The application defaults are applied after the configuration is loaded and as such, not reflected in the clairctl check-config command.
+The output of that command is also not currently suitable to be used to "compile" a config to a single file.
Configuration Reference
+Please see the go module documentation for additional documentation on defaults and use.
+Starting in version 4.7.0, unknown keys are disallowed.
+Configurations that looked valid previously and loaded fine may now cause Clair to refuse to start.
http_listen_addr: ""
+introspection_addr: ""
+log_level: ""
+tls: {}
+indexer:
+ connstring: ""
+ scanlock_retry: 0
+ layer_scan_concurrency: 0
+ migrations: false
+ scanner: {}
+ airgap: false
+matcher:
+ connstring: ""
+ indexer_addr: ""
+ migrations: false
+ period: ""
+ disable_updaters: false
+ update_retention: 2
+matchers:
+ names: nil
+ config: nil
+updaters:
+ sets: nil
+ config: nil
+notifier:
+ connstring: ""
+ migrations: false
+ indexer_addr: ""
+ matcher_addr: ""
+ poll_interval: ""
+ delivery_interval: ""
+ disable_summary: false
+ webhook: null
+ amqp: null
+ stomp: null
+auth:
+ psk: nil
+trace:
+ name: ""
+ probability: null
+ jaeger:
+ agent:
+ endpoint: ""
+ collector:
+ endpoint: ""
+ username: null
+ password: null
+ service_name: ""
+ tags: nil
+ buffer_max: 0
+metrics:
+ name: ""
+ prometheus:
+ endpoint: null
+Note: the above just lists every key for completeness. Copy-pasting the above as +a starting point for configuration will result in some options not having their +defaults set normally.
+ +$.http_listen_addr
+A string in <host>:<port> format where <host> can be an empty string.
This configures where the HTTP API is exposed.
+See /openapi/v1 for the API spec.
$.introspection_addr
+A string in <host>:<port> format where <host> can be an empty string.
This configures where Clair's metrics and health endpoints are exposed.
+$.log_level
+Set the logging level.
+One of the following strings:
+-
+
- debug-color +
- debug +
- info +
- warn +
- error +
- fatal +
- panic +
$.tls
+TLS is a map containing the config for serving the HTTP API over TLS (and +HTTP/2).
+$.tls.cert
+The TLS certificate to be used. Must be a full-chain certificate, as in nginx.
+$.tls.key
+A key file for the TLS certificate. Encryption is not supported on the key.
+$.indexer
+Indexer provides Clair Indexer node configuration.
+$.indexer.airgap
+Disables HTTP access to the Internet for indexers and fetchers. +Private IPv4 and IPv6 addresses are allowed. +Database connections are unaffected.
+$.indexer.connstring
+A Postgres connection string.
+Accepts a format as a url (e.g.,
+postgres://pqgotest:password@localhost/pqgotest?sslmode=verify-full)
+or a libpq connection string (e.g.,
+user=pqgotest dbname=pqgotest sslmode=verify-full).
$.indexer.index_report_request_concurrency
+Integer.
+Rate limits the number of index report creation requests.
+Setting this to 0 will attempt to auto-size this value. Setting a negative value +means "unlimited." The auto-sizing is a multiple of the number of available +cores.
+The API will return a 429 status code if concurrency is exceeded.
+$.indexer.scanlock_retry
+A positive integer representing seconds.
+Concurrent Indexers lock on manifest scans to avoid clobbering. +This value tunes how often a waiting Indexer will poll for the lock.
+ +$.indexer.layer_scan_concurrency
+Positive integer limiting the number of concurrent layer scans.
+Indexers will index a Manifest's layers concurrently. +This value tunes the number of layers an Indexer will scan in parallel.
+$.indexer.migrations
+A boolean value.
+Whether Indexer nodes handle migrations to their database.
+$.indexer.scanner
+Indexer configurations.
+Scanner allows for passing configuration options to layer scanners. +The scanner will have this configuration passed to it on construction if +designed to do so.
+$.indexer.scanner.dist
+A map with the name of a particular scanner and arbitrary yaml as a value.
+$.indexer.scanner.package
+A map with the name of a particular scanner and arbitrary yaml as a value.
+$.indexer.scanner.repo
+A map with the name of a particular scanner and arbitrary yaml as a value.
+$.matcher
+Matcher provides Clair matcher node configuration.
+$.matcher.cache_age
+Duration string.
+Controls how long clients should be hinted to cache responses for.
+$.matcher.connstring
+A Postgres connection string.
+Accepts a format as a url (e.g.,
+postgres://pqgotest:password@localhost/pqgotest?sslmode=verify-full)
+or a libpq connection string (e.g.,
+user=pqgotest dbname=pqgotest sslmode=verify-full).
$.matcher.max_conn_pool
+A positive integer limiting the database connection pool size.
+Clair allows for a custom connection pool size. +This number will directly set how many active database +connections are allowed concurrently.
+This parameter will be ignored in a future version. +Users should configure this through the connection string.
+$.matcher.indexer_addr
+A string in <host>:<port> format where <host> can be an empty string.
A Matcher contacts an Indexer to create a VulnerabilityReport. +The location of this Indexer is required.
+$.matcher.migrations
+A boolean value.
+Whether Matcher nodes handle migrations to their databases.
+$.matcher.period
+A time.ParseDuration parseable string.
+Determines how often updates for new security advisories will take place.
+Defaults to 6 hours.
+$.matcher.disable_updaters
+A boolean value.
+Whether to run background updates or not.
+$.matcher.update_retention
+An integer value limiting the number of update operations kept in the database.
+Sets the number of update operations to retain between garbage collection +cycles. This should be set to a safe MAX value based on database size +constraints.
+Defaults to 10.
+If a value less than 0 is provided, GC is disabled. 2 is the minimum value to +ensure updates can be compared for notifications.
+$.matchers
+Matchers provides configuration for the in-tree Matchers and RemoteMatchers.
+$.matchers.names
+A list of string values informing the matcher factory about enabled matchers.
+If the value is nil the default list of Matchers will run:
+-
+
- alpine +
- aws +
- debian +
- oracle +
- photon +
- python +
- rhel +
- suse +
- ubuntu +
- crda +
If an empty list is provided zero matchers will run.
+$.matchers.config
+Provides configuration to specific matcher.
+A map keyed by the name of the matcher containing a sub-object which +will be provided to the matchers factory constructor.
+A hypothetical example:
+config:
+ python:
+ ignore_vulns:
+ - CVE-XYZ
+ - CVE-ABC
+$.updaters
+Updaters provides configuration for the Matcher's update manager.
+$.updaters.sets
+A list of string values informing the update manager which Updaters to run.
+If the value is nil (or null in yaml) the default set of Updaters will run:
-
+
- alpine +
- aws +
- debian +
- oracle +
- photon +
- pyupio +
- rhel +
- suse +
- ubuntu +
If an empty list is provided zero updaters will run.
+$.updaters.config
+Provides configuration to specific updater sets.
+A map keyed by the name of the updater set name containing a sub-object +which will be provided to the updater set's constructor.
+A hypothetical example:
+config:
+ ubuntu:
+ security_tracker_url: http://security.url
+ ignore_distributions:
+ - cosmic
+$.notifier
+Notifier provides Clair notifier node configuration.
+$.notifier.connstring
+A Postgres connection string.
+Accepts a format as a url (e.g.,
+postgres://pqgotest:password@localhost/pqgotest?sslmode=verify-full)
+or a libpq connection string (e.g.,
+user=pqgotest dbname=pqgotest sslmode=verify-full).
$.notifier.migrations
+A boolean value.
+Whether Notifier nodes handle migrations to their database.
+$.notifier.indexer_addr
+A string in <host>:<port> format where <host> can be an empty string.
A Notifier contacts an Indexer to create obtain manifests affected by +vulnerabilities. The location of this Indexer is required.
+$.notifier.matcher_addr
+A string in <host>:<port> format where <host> can be an empty string.
A Notifier contacts a Matcher to list update operations and acquire diffs. +The location of this Indexer is required.
+$.notifier.poll_interval
+A time.ParseDuration parsable string.
+The frequency at which the notifier will query at Matcher for Update Operations.
+$.notifier.delivery_interval
+A time.ParseDuration parsable string.
+The frequency at which the notifier attempt delivery of created or previously +failed notifications.
+$.notifier.disable_summary
+A boolean.
+Controls whether notifications should be summarized to one per manifest or not.
+$.notifier.webhook
+Configures the notifier for webhook delivery.
+$.notifier.webhook.target
+URL where the webhook will be delivered.
+$.notifier.webhook.callback
+The callback url where notifications can be retrieved. +The notification ID will be appended to this url.
+This will typically be where the clair notifier is hosted.
+$.notifier.webhook.headers
+A map associating a header name to a list of values.
+$.notifier.amqp
+Configures the notifier for AMQP delivery.
+Note: Clair does not declare any AMQP components on its own. All attempts +to use an exchange or queue are passive only and will fail The broker +administrators should setup exchanges and queues ahead of time.
+$.notifier.amqp.direct
+A boolean value.
+If true the Notifier will deliver individual notifications (not a callback) +to the configured AMQP broker.
+$.notifier.amqp.rollup
+Integer 0 or greater.
+If direct is true this value will inform notifier how many notifications
+to send in a single direct delivery. For example, if direct is set to
+true and rollup is set to 5, the notifier will deliver no more then
+5 notifications in a single json payload to the broker. Setting the value
+to 0 will effectively set it to 1.
$.notifier.amqp.exchange
+The AMQP Exchange to connect to.
+$.notifier.amqp.exchange.name
+string value
+The name of the exchange to connect to.
+$.notifier.amqp.exchange.type
+string value
+The type of the exchange. Typically:
+-
+
- direct +
- fanout +
- topic +
- headers +
$.notifier.amqp.exchange.durability
+bool value
+Whether the configured queue is durable or not.
+$.notifier.amqp.exchange.auto_delete
+bool value
+Whether the configured queue uses an auto_delete policy.
+$.notifier.amqp.routing_key
+string value
+The name of the routing key each notification will be sent with.
+$.notifier.amqp.callback
+a URL string
+If direct is false, this URL is provided in the notification callback sent
+to the broker. This URL should point to Clair's notification API endpoint.
$.notifier.amqp.uris
+list of URL strings
+A list of one or more AMQP brokers to connect to, in priority order.
+$.notifier.amqp.tls
+Configures TLS connection to AMQP broker.
+$.notifier.amqp.tls.root_ca
+string value
+The filesystem path where a root CA can be read.
+$.notifier.amqp.tls.cert
+string value
+The filesystem path where a tls certificate can be read. Note that clair
+also respects SSL_CERT_DIR, as documented for the Go crypto/x509 package.
$.notifier.amqp.tls.key
+string value
+The filesystem path where a TLS private key can be read.
+$.notifier.stomp
+Configures the notifier for STOMP delivery.
+$.notifier.stomp.direct
+A boolean value.
+If true, the Notifier will deliver individual notifications (not a
+callback) to the configured STOMP broker.
$.notifier.stomp.rollup
+Integer 0 or greater.
+If direct is true, this value will limit the number of notifications
+sent in a single direct delivery. For example, if direct is set to
+true and rollup is set to 5, the notifier will deliver no more
+then 5 notifications in a single json payload to the broker. Setting the value
+to 0 will effectively set it to 1.
$.notifier.stomp.callback
+a URL string
+If direct is false, this URL is provided in the notification callback sent
+to the broker. This URL should point to Clair's notification API endpoint.
$.notifier.stomp.destination
+a string value
+The STOMP destination to deliver notifications to.
+$.notifier.stomp.uris
+list of URL strings
+A list of one or more STOMP brokers to connect to in priority order.
+$.notifier.stomp.tls
+Configures TLS connection to STOMP broker.
+$.notifier.stomp.tls.root_ca
+string value
+The filesystem path where a root CA can be read.
+Note that clair also respects SSL_CERT_DIR, as documented for the Go
+crypto/x509 package.
$.notifier.stomp.tls.cert
+string value
+The filesystem path where a tls certificate can be read.
+$.notifier.stomp.tls.key
+string value
+The filesystem path where a tls private key can be read.
+$.notifier.stomp.user
+Configures login details for the STOMP broker.
+$.notifier.stomp.user.login
+string value
+The STOMP login to connect with.
+$.notifier.stomp.user.passcode
+string value
+The STOMP passcode to connect with.
+$.auth
+Defines ClairV4's external and intra-service JWT based authentication.
+If multiple auth mechanisms are defined, Clair will pick one. Currently, there +are not multiple mechanisms.
+$.auth.psk
+Defines preshared key authentication.
+$.auth.psk.key
+a string value
+A shared base64 encoded key distributed between all parties signing and +verifying JWTs.
+$.auth.psk.iss
+a list of string value
+A list of JWT issuers to verify. An empty list will accept any issuer in a +JWT claim.
+$.trace
+Defines distributed tracing configuration based on OpenTelemetry.
+$.trace.name
+a string value
+The name of the application traces will belong to.
+$.trace.probability
+a float value
+The probability a trace will occur.
+$.trace.jaeger
+Defines values for Jaeger tracing.
+$.trace.jaeger.agent
+Defines values for configuring delivery to a Jaeger agent.
+$.trace.jaeger.agent.endpoint
+a string value
+An address in <host>:<post> syntax where traces can be submitted.
$.trace.jaeger.collector
+Defines values for configuring delivery to a Jaeger collector.
+$.trace.jaeger.collector.endpoint
+a string value
+An address in <host>:<post> syntax where traces can be submitted.
$.trace.jaeger.collector.username
+a string value
+$.trace.jaeger.collector.password
+a string value
+$.trace.jaeger.service_name
+a string value
+$.trace.jaeger.tags
+a mapping of a string to a string
+$.trace.jaeger.buffer_max
+an integer value
+$.metrics
+Defines distributed tracing configuration based on OpenTelemetry.
+$.metrics.name
+a string value
+$.metrics.prometheus
+Configuration for a prometheus metrics exporter.
+$.metrics.prometheus.endpoint
+a string value
+Defines the path where metrics will be served.
++
1
+
+Support added in version 4.7.0.
Indexer
+When Clair is running in Indexer mode, it is responsible for receiving Manifests and generating IndexReports. An IndexReport is an intermediate representation of a manifest's content and is used to discover vulnerabilities.
+Matcher
+When Clair is running in Matcher mode it is responsible for receiving IndexReports and generating VulnerabilityReports. A VulnerabilityReport describes the contents of a manifest and any vulnerabilities affecting it.
+Notifier
+When Clair is running in Notifier mode, it is responsible for generating notifications when new vulnerabilities affecting a previously indexed manifest enters the system. The notifier will send notifications via the configured mechanisms.
+Clair exports metrics on the introspection +port in the Prometheus format.
+The exact metrics exposed are not considered API (and so are subject to change
+between releases) but should be well described. An up-to-date grafana dashboard
+example is in contrib/openshift/grafana.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/reference/api.html b/v4.7.2/reference/api.html
new file mode 100644
index 0000000000..4f917c97d0
--- /dev/null
+++ b/v4.7.2/reference/api.html
@@ -0,0 +1,1987 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/reference/clairctl.html b/v4.7.2/reference/clairctl.html
new file mode 100644
index 0000000000..cb848bc8ce
--- /dev/null
+++ b/v4.7.2/reference/clairctl.html
@@ -0,0 +1,310 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ +
title: ClairV4 v1.1 +language_tabs:
+-
+
- python: Python +
- go: Golang +
- javascript: Javascript +language_clients: +
- python: "" +
- go: "" +
- javascript: "" +toc_footers: [] +includes: [] +search: false +highlight_theme: darkula +headingLevel: 2 +
+ +
ClairV4 v1.1
+++Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
+
ClairV4 is a set of cooperating microservices which scan, index, and match your container's content with known vulnerabilities.
+Email: Clair Team Web: Clair Team +License: Apache License 2.0
+Notifier
+DeleteNotification
+ +++Code samples
+
import requests
+headers = {
+ 'Accept': 'application/json'
+}
+
+r = requests.delete('/notifier/api/v1/notification/{notification_id}', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("DELETE", "/notifier/api/v1/notification/{notification_id}", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+
+const headers = {
+ 'Accept':'application/json'
+};
+
+fetch('/notifier/api/v1/notification/{notification_id}',
+{
+ method: 'DELETE',
+
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+DELETE /notifier/api/v1/notification/{notification_id}
Issues a delete of the provided notification id and all associated notifications. After this delete clients will no longer be able to retrieve notifications.
+Parameters
+| Name | In | Type | Required | Description |
|---|---|---|---|---|
| notification_id | path | string | false | A notification ID returned by a callback |
++Example responses
+
++400 Response
+
{
+ "code": "string",
+ "message": "string"
+}
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | None |
| 400 | Bad Request | Bad Request | Error |
| 405 | Method Not Allowed | Method Not Allowed | Error |
| 500 | Internal Server Error | Internal Server Error | Error |
Retrieve a paginated result of notifications for the provided id.
+ +++Code samples
+
import requests
+headers = {
+ 'Accept': 'application/json'
+}
+
+r = requests.get('/notifier/api/v1/notification/{notification_id}', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("GET", "/notifier/api/v1/notification/{notification_id}", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+
+const headers = {
+ 'Accept':'application/json'
+};
+
+fetch('/notifier/api/v1/notification/{notification_id}',
+{
+ method: 'GET',
+
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+GET /notifier/api/v1/notification/{notification_id}
By performing a GET with a notification_id as a path parameter, the client will retrieve a paginated response of notification objects.
+Parameters
+| Name | In | Type | Required | Description |
|---|---|---|---|---|
| notification_id | path | string | false | A notification ID returned by a callback |
| page_size | query | int | false | The maximum number of notifications to deliver in a single page. |
| next | query | string | false | The next page to fetch via id. Typically this number is provided on initial response in the page.next field. The first GET request may omit this field. |
++Example responses
+
++200 Response
+
{
+ "page": {
+ "size": 100,
+ "next": "1b4d0db2-e757-4150-bbbb-543658144205"
+ },
+ "notifications": [
+ {
+ "id": "5e4b387e-88d3-4364-86fd-063447a6fad2",
+ "manifest": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "reason": "added",
+ "vulnerability": {
+ "name": "CVE-2009-5155",
+ "fixed_in_version": "v0.0.1",
+ "links": "http://link-to-advisory",
+ "description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.\"",
+ "normalized_severity": "Unknown",
+ "package": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ },
+ "distribution": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ },
+ "repository": {
+ "id": "string",
+ "name": "string",
+ "key": "string",
+ "uri": "string",
+ "cpe": "string"
+ }
+ }
+ }
+ ]
+}
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | A paginated list of notifications | PagedNotifications |
| 400 | Bad Request | Bad Request | Error |
| 405 | Method Not Allowed | Method Not Allowed | Error |
| 500 | Internal Server Error | Internal Server Error | Error |
Indexer
+Index the contents of a Manifest
+ +++Code samples
+
import requests
+headers = {
+ 'Content-Type': 'application/json',
+ 'Accept': 'application/json'
+}
+
+r = requests.post('/indexer/api/v1/index_report', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Content-Type": []string{"application/json"},
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("POST", "/indexer/api/v1/index_report", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+const inputBody = '{
+ "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "layers": [
+ {
+ "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "uri": "https://storage.example.com/blob/2f077db56abccc19f16f140f629ae98e904b4b7d563957a7fc319bd11b82ba36",
+ "headers": {
+ "property1": [
+ "string"
+ ],
+ "property2": [
+ "string"
+ ]
+ }
+ }
+ ]
+}';
+const headers = {
+ 'Content-Type':'application/json',
+ 'Accept':'application/json'
+};
+
+fetch('/indexer/api/v1/index_report',
+{
+ method: 'POST',
+ body: inputBody,
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+POST /indexer/api/v1/index_report
By submitting a Manifest object to this endpoint Clair will fetch the layers, scan each layer's contents, and provide an index of discovered packages, repository and distribution information.
+++Body parameter
+
{
+ "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "layers": [
+ {
+ "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "uri": "https://storage.example.com/blob/2f077db56abccc19f16f140f629ae98e904b4b7d563957a7fc319bd11b82ba36",
+ "headers": {
+ "property1": [
+ "string"
+ ],
+ "property2": [
+ "string"
+ ]
+ }
+ }
+ ]
+}
+Parameters
+| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | Manifest | true | none |
++Example responses
+
++201 Response
+
{
+ "manifest_hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "state": "IndexFinished",
+ "packages": {
+ "10": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ }
+ },
+ "distributions": {
+ "1": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ }
+ },
+ "environments": {
+ "10": [
+ {
+ "package_db": "var/lib/dpkg/status",
+ "introduced_in": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "distribution_id": "1"
+ }
+ ]
+ },
+ "success": true,
+ "err": ""
+}
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | IndexReport Created | IndexReport |
| 400 | Bad Request | Bad Request | Error |
| 405 | Method Not Allowed | Method Not Allowed | Error |
| 500 | Internal Server Error | Internal Server Error | Error |
Delete the IndexReport and associated information for the given Manifest hashes, if they exist.
+ +++Code samples
+
import requests
+headers = {
+ 'Content-Type': 'application/json',
+ 'Accept': 'application/json'
+}
+
+r = requests.delete('/indexer/api/v1/index_report', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Content-Type": []string{"application/json"},
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("DELETE", "/indexer/api/v1/index_report", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+const inputBody = '[
+ "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3"
+]';
+const headers = {
+ 'Content-Type':'application/json',
+ 'Accept':'application/json'
+};
+
+fetch('/indexer/api/v1/index_report',
+{
+ method: 'DELETE',
+ body: inputBody,
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+DELETE /indexer/api/v1/index_report
Given a Manifest's content addressable hash, any data related to it will be removed if it exists.
+++Body parameter
+
[
+ "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3"
+]
+Parameters
+| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | BulkDelete | true | none |
++Example responses
+
++200 Response
+
[
+ "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3"
+]
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | BulkDelete |
| 400 | Bad Request | Bad Request | Error |
| 500 | Internal Server Error | Internal Server Error | Error |
Delete the IndexReport and associated information for the given Manifest hash, if exists.
+ +++Code samples
+
import requests
+headers = {
+ 'Accept': 'application/json'
+}
+
+r = requests.delete('/indexer/api/v1/index_report/{manifest_hash}', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("DELETE", "/indexer/api/v1/index_report/{manifest_hash}", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+
+const headers = {
+ 'Accept':'application/json'
+};
+
+fetch('/indexer/api/v1/index_report/{manifest_hash}',
+{
+ method: 'DELETE',
+
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+DELETE /indexer/api/v1/index_report/{manifest_hash}
Given a Manifest's content addressable hash, any data related to it will be removed it it exists.
+Parameters
+| Name | In | Type | Required | Description |
|---|---|---|---|---|
| manifest_hash | path | Digest | true | A digest of a manifest that has been indexed previous to this request. |
++Example responses
+
++400 Response
+
{
+ "code": "string",
+ "message": "string"
+}
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | OK | None |
| 400 | Bad Request | Bad Request | Error |
| 500 | Internal Server Error | Internal Server Error | Error |
Retrieve an IndexReport for the given Manifest hash if exists.
+ +++Code samples
+
import requests
+headers = {
+ 'Accept': 'application/json'
+}
+
+r = requests.get('/indexer/api/v1/index_report/{manifest_hash}', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("GET", "/indexer/api/v1/index_report/{manifest_hash}", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+
+const headers = {
+ 'Accept':'application/json'
+};
+
+fetch('/indexer/api/v1/index_report/{manifest_hash}',
+{
+ method: 'GET',
+
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+GET /indexer/api/v1/index_report/{manifest_hash}
Given a Manifest's content addressable hash an IndexReport will be retrieved if exists.
+Parameters
+| Name | In | Type | Required | Description |
|---|---|---|---|---|
| manifest_hash | path | Digest | true | A digest of a manifest that has been indexed previous to this request. |
++Example responses
+
++200 Response
+
{
+ "manifest_hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "state": "IndexFinished",
+ "packages": {
+ "10": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ }
+ },
+ "distributions": {
+ "1": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ }
+ },
+ "environments": {
+ "10": [
+ {
+ "package_db": "var/lib/dpkg/status",
+ "introduced_in": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "distribution_id": "1"
+ }
+ ]
+ },
+ "success": true,
+ "err": ""
+}
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | IndexReport retrieved | IndexReport |
| 400 | Bad Request | Bad Request | Error |
| 404 | Not Found | Not Found | Error |
| 405 | Method Not Allowed | Method Not Allowed | Error |
| 500 | Internal Server Error | Internal Server Error | Error |
Report the indexer's internal configuration and state.
+ +++Code samples
+
import requests
+headers = {
+ 'Accept': 'application/json'
+}
+
+r = requests.get('/indexer/api/v1/index_state', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("GET", "/indexer/api/v1/index_state", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+
+const headers = {
+ 'Accept':'application/json'
+};
+
+fetch('/indexer/api/v1/index_state',
+{
+ method: 'GET',
+
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+GET /indexer/api/v1/index_state
The index state endpoint returns a json structure indicating the indexer's internal configuration state. +A client may be interested in this as a signal that manifests may need to be re-indexed.
+++Example responses
+
++200 Response
+
{
+ "state": "aae368a064d7c5a433d0bf2c4f5554cc"
+}
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Indexer State | State |
| 304 | Not Modified | Indexer State Unchanged | None |
Response Headers
+| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | Etag | string | Entity Tag |
Matcher
+Retrieve a VulnerabilityReport for a given manifest's content addressable hash.
+ +++Code samples
+
import requests
+headers = {
+ 'Accept': 'application/json'
+}
+
+r = requests.get('/matcher/api/v1/vulnerability_report/{manifest_hash}', headers = headers)
+
+print(r.json())
+
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+ headers := map[string][]string{
+ "Accept": []string{"application/json"},
+ }
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("GET", "/matcher/api/v1/vulnerability_report/{manifest_hash}", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}
+
+
+const headers = {
+ 'Accept':'application/json'
+};
+
+fetch('/matcher/api/v1/vulnerability_report/{manifest_hash}',
+{
+ method: 'GET',
+
+ headers: headers
+})
+.then(function(res) {
+ return res.json();
+}).then(function(body) {
+ console.log(body);
+});
+
+GET /matcher/api/v1/vulnerability_report/{manifest_hash}
Given a Manifest's content addressable hash a VulnerabilityReport will be created. The Manifest must have been Indexed first via the Index endpoint.
+Parameters
+| Name | In | Type | Required | Description |
|---|---|---|---|---|
| manifest_hash | path | Digest | true | A digest of a manifest that has been indexed previous to this request. |
++Example responses
+
++201 Response
+
{
+ "manifest_hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "packages": {
+ "10": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ }
+ },
+ "distributions": {
+ "1": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ }
+ },
+ "environments": {
+ "10": [
+ {
+ "package_db": "var/lib/dpkg/status",
+ "introduced_in": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "distribution_id": "1"
+ }
+ ]
+ },
+ "vulnerabilities": {
+ "356835": {
+ "id": "356835",
+ "updater": "",
+ "name": "CVE-2009-5155",
+ "description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.\"",
+ "links": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-5155 http://people.canonical.com/~ubuntu-security/cve/2009/CVE-2009-5155.html https://sourceware.org/bugzilla/show_bug.cgi?id=11053 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22793 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=32806 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=34238 https://sourceware.org/bugzilla/show_bug.cgi?id=18986\"",
+ "severity": "Low",
+ "normalized_severity": "Low",
+ "package": {
+ "id": "0",
+ "name": "glibc",
+ "version": "",
+ "kind": "",
+ "source": null,
+ "package_db": "",
+ "repository_hint": ""
+ },
+ "dist": {
+ "id": "0",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": ""
+ },
+ "repo": {
+ "id": "0",
+ "name": "Ubuntu 18.04.3 LTS",
+ "key": "",
+ "uri": ""
+ },
+ "issued": "2019-10-12T07:20:50.52Z",
+ "fixed_in_version": "2.28-0ubuntu1"
+ }
+ },
+ "package_vulnerabilities": {
+ "10": [
+ "356835"
+ ]
+ }
+}
+Responses
+| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | VulnerabilityReport Created | VulnerabilityReport |
| 400 | Bad Request | Bad Request | Error |
| 404 | Not Found | Not Found | Error |
| 405 | Method Not Allowed | Method Not Allowed | Error |
| 500 | Internal Server Error | Internal Server Error | Error |
Schemas
+Page
+ + + + + +{
+ "size": 1,
+ "next": "1b4d0db2-e757-4150-bbbb-543658144205"
+}
+
+Page
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| size | int | false | none | The maximum number of elements in a page |
| next | string | false | none | The next id to submit to the api to continue paging |
PagedNotifications
+ + + + + +{
+ "page": {
+ "size": 100,
+ "next": "1b4d0db2-e757-4150-bbbb-543658144205"
+ },
+ "notifications": [
+ {
+ "id": "5e4b387e-88d3-4364-86fd-063447a6fad2",
+ "manifest": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "reason": "added",
+ "vulnerability": {
+ "name": "CVE-2009-5155",
+ "fixed_in_version": "v0.0.1",
+ "links": "http://link-to-advisory",
+ "description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.\"",
+ "normalized_severity": "Unknown",
+ "package": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ },
+ "distribution": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ },
+ "repository": {
+ "id": "string",
+ "name": "string",
+ "key": "string",
+ "uri": "string",
+ "cpe": "string"
+ }
+ }
+ }
+ ]
+}
+
+PagedNotifications
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| page | object | false | none | A page object informing the client the next page to retrieve. If page.next becomes "-1" the client should stop paging. |
| notifications | [Notification] | false | none | A list of notifications within this page |
Callback
+ + + + + +{
+ "notification_id": "269886f3-0146-4f08-9bf7-cb1138d48643",
+ "callback": "http://clair-notifier/notifier/api/v1/notifications/269886f3-0146-4f08-9bf7-cb1138d48643"
+}
+
+Callback
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| notification_id | string | false | none | the unique identifier for this set of notifications |
| callback | string | false | none | the url where notifications can be retrieved |
VulnSummary
+ + + + + +{
+ "name": "CVE-2009-5155",
+ "fixed_in_version": "v0.0.1",
+ "links": "http://link-to-advisory",
+ "description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.\"",
+ "normalized_severity": "Unknown",
+ "package": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ },
+ "distribution": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ },
+ "repository": {
+ "id": "string",
+ "name": "string",
+ "key": "string",
+ "uri": "string",
+ "cpe": "string"
+ }
+}
+
+VulnSummary
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| name | string | false | none | the vulnerability name |
| fixed_in_version | string | false | none | The version which the vulnerability is fixed in. Empty if not fixed. |
| links | string | false | none | links to external information about vulnerability |
| description | string | false | none | the vulnerability name |
| normalized_severity | string | false | none | A well defined set of severity strings guaranteed to be present. |
| package | Package | false | none | A package discovered by indexing a Manifest |
| distribution | Distribution | false | none | An indexed distribution discovered in a layer. See https://www.freedesktop.org/software/systemd/man/os-release.html for explanations and example of fields. |
| repository | Repository | false | none | A package repository |
Enumerated Values
+| Property | Value |
|---|---|
| normalized_severity | Unknown |
| normalized_severity | Negligible |
| normalized_severity | Low |
| normalized_severity | Medium |
| normalized_severity | High |
| normalized_severity | Critical |
Notification
+ + + + + +{
+ "id": "5e4b387e-88d3-4364-86fd-063447a6fad2",
+ "manifest": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "reason": "added",
+ "vulnerability": {
+ "name": "CVE-2009-5155",
+ "fixed_in_version": "v0.0.1",
+ "links": "http://link-to-advisory",
+ "description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.\"",
+ "normalized_severity": "Unknown",
+ "package": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ },
+ "distribution": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ },
+ "repository": {
+ "id": "string",
+ "name": "string",
+ "key": "string",
+ "uri": "string",
+ "cpe": "string"
+ }
+ }
+}
+
+Notification
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | false | none | a unique identifier for this notification |
| manifest | string | false | none | The hash of the manifest affected by the provided vulnerability. |
| reason | string | false | none | the reason for the notifcation, [added |
| vulnerability | VulnSummary | false | none | A summary of a vulnerability |
Environment
+ + + + + +{
+ "package_db": "var/lib/dpkg/status",
+ "introduced_in": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "distribution_id": "1"
+}
+
+Environment
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| package_db | string | true | none | The filesystem path or unique identifier of a package database. |
| introduced_in | Digest | true | none | A digest string with prefixed algorithm. The format is described here: https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests Digests are used throughout the API to identify Layers and Manifests. |
| distribution_id | string | true | none | The distribution ID found in an associated IndexReport or VulnerabilityReport. |
IndexReport
+ + + + + +{
+ "manifest_hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "state": "IndexFinished",
+ "packages": {
+ "10": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ }
+ },
+ "distributions": {
+ "1": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ }
+ },
+ "environments": {
+ "10": [
+ {
+ "package_db": "var/lib/dpkg/status",
+ "introduced_in": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "distribution_id": "1"
+ }
+ ]
+ },
+ "success": true,
+ "err": ""
+}
+
+IndexReport
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| manifest_hash | Digest | true | none | A digest string with prefixed algorithm. The format is described here: https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests Digests are used throughout the API to identify Layers and Manifests. |
| state | string | true | none | The current state of the index operation |
| packages | object | true | none | A map of Package objects indexed by Package.id |
| » additionalProperties | Package | false | none | A package discovered by indexing a Manifest |
| distributions | object | true | none | A map of Distribution objects keyed by their Distribution.id discovered in the manifest. |
| » additionalProperties | Distribution | false | none | An indexed distribution discovered in a layer. See https://www.freedesktop.org/software/systemd/man/os-release.html for explanations and example of fields. |
| environments | object | true | none | A map of lists containing Environment objects keyed by the associated Package.id. |
| » additionalProperties | [Environment] | false | none | [The environment a particular package was discovered in.] |
| success | boolean | true | none | A bool indicating succcessful index |
| err | string | true | none | An error message on event of unsuccessful index |
VulnerabilityReport
+ + + + + +{
+ "manifest_hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "packages": {
+ "10": {
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ }
+ }
+ },
+ "distributions": {
+ "1": {
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS"
+ }
+ },
+ "environments": {
+ "10": [
+ {
+ "package_db": "var/lib/dpkg/status",
+ "introduced_in": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
+ "distribution_id": "1"
+ }
+ ]
+ },
+ "vulnerabilities": {
+ "356835": {
+ "id": "356835",
+ "updater": "",
+ "name": "CVE-2009-5155",
+ "description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.\"",
+ "links": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-5155 http://people.canonical.com/~ubuntu-security/cve/2009/CVE-2009-5155.html https://sourceware.org/bugzilla/show_bug.cgi?id=11053 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22793 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=32806 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=34238 https://sourceware.org/bugzilla/show_bug.cgi?id=18986\"",
+ "severity": "Low",
+ "normalized_severity": "Low",
+ "package": {
+ "id": "0",
+ "name": "glibc",
+ "version": "",
+ "kind": "",
+ "source": null,
+ "package_db": "",
+ "repository_hint": ""
+ },
+ "dist": {
+ "id": "0",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": ""
+ },
+ "repo": {
+ "id": "0",
+ "name": "Ubuntu 18.04.3 LTS",
+ "key": "",
+ "uri": ""
+ },
+ "issued": "2019-10-12T07:20:50.52Z",
+ "fixed_in_version": "2.28-0ubuntu1"
+ }
+ },
+ "package_vulnerabilities": {
+ "10": [
+ "356835"
+ ]
+ }
+}
+
+VulnerabilityReport
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| manifest_hash | Digest | true | none | A digest string with prefixed algorithm. The format is described here: https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests Digests are used throughout the API to identify Layers and Manifests. |
| packages | object | true | none | A map of Package objects indexed by Package.id |
| » additionalProperties | Package | false | none | A package discovered by indexing a Manifest |
| distributions | object | true | none | A map of Distribution objects indexed by Distribution.id. |
| » additionalProperties | Distribution | false | none | An indexed distribution discovered in a layer. See https://www.freedesktop.org/software/systemd/man/os-release.html for explanations and example of fields. |
| environments | object | true | none | A mapping of Environment lists indexed by Package.id |
| » additionalProperties | [Environment] | false | none | [The environment a particular package was discovered in.] |
| vulnerabilities | object | true | none | A map of Vulnerabilities indexed by Vulnerability.id |
| » additionalProperties | Vulnerability | false | none | A unique vulnerability indexed by Clair |
| package_vulnerabilities | object | true | none | A mapping of Vulnerability.id lists indexed by Package.id. |
| » additionalProperties | [string] | false | none | none |
Vulnerability
+ + + + + +{
+ "id": "356835",
+ "updater": "",
+ "name": "CVE-2009-5155",
+ "description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.\"",
+ "links": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-5155 http://people.canonical.com/~ubuntu-security/cve/2009/CVE-2009-5155.html https://sourceware.org/bugzilla/show_bug.cgi?id=11053 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22793 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=32806 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=34238 https://sourceware.org/bugzilla/show_bug.cgi?id=18986\"",
+ "severity": "Low",
+ "normalized_severity": "Low",
+ "package": {
+ "id": "0",
+ "name": "glibc",
+ "version": "",
+ "kind": "",
+ "source": null,
+ "package_db": "",
+ "repository_hint": ""
+ },
+ "dist": {
+ "id": "0",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": ""
+ },
+ "repo": {
+ "id": "0",
+ "name": "Ubuntu 18.04.3 LTS",
+ "key": "",
+ "uri": ""
+ },
+ "issued": "2019-10-12T07:20:50.52Z",
+ "fixed_in_version": "2.28-0ubuntu1",
+ "x-widdershins-oldRef": "#/components/examples/Vulnerability/value"
+}
+
+Vulnerability
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | A unique ID representing this vulnerability. |
| updater | string | true | none | A unique ID representing this vulnerability. |
| name | string | true | none | Name of this specific vulnerability. |
| description | string | true | none | A description of this specific vulnerability. |
| links | string | true | none | A space separate list of links to any external information. |
| severity | string | true | none | A severity keyword taken verbatim from the vulnerability source. |
| normalized_severity | string | true | none | A well defined set of severity strings guaranteed to be present. |
| package | Package | false | none | A package discovered by indexing a Manifest |
| distribution | Distribution | false | none | An indexed distribution discovered in a layer. See https://www.freedesktop.org/software/systemd/man/os-release.html for explanations and example of fields. |
| repository | Repository | false | none | A package repository |
| issued | string | false | none | The timestamp in which the vulnerability was issued |
| range | string | false | none | The range of package versions affected by this vulnerability. |
| fixed_in_version | string | true | none | A unique ID representing this vulnerability. |
Enumerated Values
+| Property | Value |
|---|---|
| normalized_severity | Unknown |
| normalized_severity | Negligible |
| normalized_severity | Low |
| normalized_severity | Medium |
| normalized_severity | High |
| normalized_severity | Critical |
Distribution
+ + + + + +{
+ "id": "1",
+ "did": "ubuntu",
+ "name": "Ubuntu",
+ "version": "18.04.3 LTS (Bionic Beaver)",
+ "version_code_name": "bionic",
+ "version_id": "18.04",
+ "arch": "",
+ "cpe": "",
+ "pretty_name": "Ubuntu 18.04.3 LTS",
+ "x-widdershins-oldRef": "#/components/examples/Distribution/value"
+}
+
+Distribution
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | A unique ID representing this distribution |
| did | string | true | none | none |
| name | string | true | none | none |
| version | string | true | none | none |
| version_code_name | string | true | none | none |
| version_id | string | true | none | none |
| arch | string | true | none | none |
| cpe | string | true | none | none |
| pretty_name | string | true | none | none |
SourcePackage
+ + + + + +{
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ },
+ "x-widdershins-oldRef": "#/components/examples/Package/value"
+}
+
+SourcePackage
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | A unique ID representing this package |
| name | string | true | none | Name of the Package |
| version | string | true | none | Version of the Package |
| kind | string | false | none | Kind of package. Source |
| source | string | false | none | none |
| normalized_version | Version | false | none | Version is a normalized claircore version, composed of a "kind" and an array of integers such that two versions of the same kind have the correct ordering when the integers are compared pair-wise. |
| arch | string | false | none | none |
| module | string | false | none | none |
| cpe | string | false | none | A CPE identifying the package |
Package
+ + + + + +{
+ "id": "10",
+ "name": "libapt-pkg5.0",
+ "version": "1.6.11",
+ "kind": "binary",
+ "normalized_version": "",
+ "arch": "x86",
+ "module": "",
+ "cpe": "",
+ "source": {
+ "id": "9",
+ "name": "apt",
+ "version": "1.6.11",
+ "kind": "source",
+ "source": null
+ },
+ "x-widdershins-oldRef": "#/components/examples/Package/value"
+}
+
+Package
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | A unique ID representing this package |
| name | string | true | none | Name of the Package |
| version | string | true | none | Version of the Package |
| kind | string | false | none | Kind of package. Source |
| source | SourcePackage | false | none | A source package affiliated with a Package |
| normalized_version | Version | false | none | Version is a normalized claircore version, composed of a "kind" and an array of integers such that two versions of the same kind have the correct ordering when the integers are compared pair-wise. |
| arch | string | false | none | The package's target system architecture |
| module | string | false | none | A module further defining a namespace for a package |
| cpe | string | false | none | A CPE identifying the package |
Repository
+ + + + + +{
+ "id": "string",
+ "name": "string",
+ "key": "string",
+ "uri": "string",
+ "cpe": "string"
+}
+
+Repository
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | false | none | none |
| name | string | false | none | none |
| key | string | false | none | none |
| uri | string | false | none | none |
| cpe | string | false | none | none |
Version
+ + + + + +"pep440:0.0.0.0.0.0.0.0.0"
+
+Version
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| Version | string | false | none | Version is a normalized claircore version, composed of a "kind" and an array of integers such that two versions of the same kind have the correct ordering when the integers are compared pair-wise. |
Manifest
+ + + + + +{
+ "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "layers": [
+ {
+ "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "uri": "https://storage.example.com/blob/2f077db56abccc19f16f140f629ae98e904b4b7d563957a7fc319bd11b82ba36",
+ "headers": {
+ "property1": [
+ "string"
+ ],
+ "property2": [
+ "string"
+ ]
+ }
+ }
+ ]
+}
+
+Manifest
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| hash | Digest | true | none | A digest string with prefixed algorithm. The format is described here: https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests Digests are used throughout the API to identify Layers and Manifests. |
| layers | [Layer] | true | none | [A Layer within a Manifest and where Clair may retrieve it.] |
Layer
+ + + + + +{
+ "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
+ "uri": "https://storage.example.com/blob/2f077db56abccc19f16f140f629ae98e904b4b7d563957a7fc319bd11b82ba36",
+ "headers": {
+ "property1": [
+ "string"
+ ],
+ "property2": [
+ "string"
+ ]
+ }
+}
+
+Layer
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| hash | Digest | true | none | A digest string with prefixed algorithm. The format is described here: https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests Digests are used throughout the API to identify Layers and Manifests. |
| uri | string | true | none | A URI describing where the layer may be found. Implementations MUST support http(s) schemes and MAY support additional schemes. |
| headers | object | true | none | map of arrays of header values keyed by header value. e.g. map[string][]string |
| » additionalProperties | [string] | false | none | none |
BulkDelete
+ + + + + +[
+ "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3"
+]
+
+BulkDelete
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| BulkDelete | [Digest] | false | none | An array of Digests to be deleted. |
Error
+ + + + + +{
+ "code": "string",
+ "message": "string"
+}
+
+Error
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| code | string | false | none | a code for this particular error |
| message | string | false | none | a message with further detail |
State
+ + + + + +{
+ "state": "aae368a064d7c5a433d0bf2c4f5554cc"
+}
+
+State
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| state | string | true | none | an opaque identifier |
Digest
+ + + + + +"sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3"
+
+Digest
+Properties
+| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| Digest | string | false | none | A digest string with prefixed algorithm. The format is described here: https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests Digests are used throughout the API to identify Layers and Manifests. |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/reference/config.html b/v4.7.2/reference/config.html
new file mode 100644
index 0000000000..ba28511553
--- /dev/null
+++ b/v4.7.2/reference/config.html
@@ -0,0 +1,710 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Clairctl
+clairctl is a command line tool for working with Clair.
+This CLI is capable of generating manifests from most public registries
+(dockerhub, quay.io, Red Hat Container Catalog) and submitting them for
+analysis to a running Clair.
Note that if the Clair instance has authentication configured, the value
+provided to the issuer flag must be on the list accepted by the server.
NAME:
+ clairctl - interact with a clair API
+
+USAGE:
+ clairctl [global options] command [command options] [arguments...]
+
+VERSION:
+ 0.1.0
+
+DESCRIPTION:
+ A command-line tool for clair v4.
+
+COMMANDS:
+ manifest print a clair manifest for the named container
+ report request vulnerability reports for the named containers
+ export-updaters run updaters and export results
+ import-updaters import updates
+ help, h Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+ -D print debugging logs (default: false)
+ --config value, -c value clair configuration file (default: "config.yaml") [$CLAIR_CONF]
+ --issuer value, --iss value jwt "issuer" to use when making authenticated requests (default: "clairctl")
+ --help, -h show help (default: false)
+ --version, -v print the version (default: false)
+NAME:
+ clairctl manifest - print a clair manifest for the named container
+
+USAGE:
+ clairctl manifest [arguments...]
+
+DESCRIPTION:
+ print a clair manifest for the named container
+NAME:
+ clairctl report - request vulnerability reports for the named containers
+
+USAGE:
+ clairctl report [command options] container...
+
+DESCRIPTION:
+ Request and print a Clair vulnerability report for the named container(s).
+
+OPTIONS:
+ --host value URL for the clairv4 v1 API. (default: "http://localhost:6060/") [$CLAIR_API]
+ --out value, -o value output format: text, json, xml (default: text)
+NAME:
+ clairctl export-updaters - run updaters and export results
+
+USAGE:
+ clairctl export-updaters [command options] [out]
+
+DESCRIPTION:
+ Run configured exporters and export to a file.
+
+ A configuration file is needed to run this command, see 'clairctl help'
+ for how to specify one.
+
+OPTIONS:
+ --strict Return non-zero exit when updaters report errors. (default: false)
+NAME:
+ clairctl import-updaters - import updates
+
+USAGE:
+ clairctl import-updaters input...
+
+DESCRIPTION:
+ Import updates from files or HTTP URIs.
+
+ A configuration file is needed to run this command, see 'clairctl help'
+ for how to specify one.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/reference/indexer.html b/v4.7.2/reference/indexer.html
new file mode 100644
index 0000000000..867d79b674
--- /dev/null
+++ b/v4.7.2/reference/indexer.html
@@ -0,0 +1,230 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Config
+CLI Flags And Environment Variables
+Clair is configured by a structured yaml or JSON1 file and an optional directory of "merge" and "patch" documents1. +Each Clair node needs to specify what mode it will run in and a path to a configuration file via CLI flags or environment variables.
+For example:
+$ clair -conf ./path/to/config.yaml -mode indexer
+$ clair -conf ./path/to/config.yaml -mode matcher
+-mode
+ (also specified by CLAIR_MODE env variable)
+ One of the following strings
+ Sets which mode the clair instances will run in
+
+ "indexer": runs just the indexer node
+ "matcher": runs just the matcher node
+ "notifier": runs just the notifier node
+ "combo": will run all services on the same node.
+-conf
+ (also specified by CLAIR_CONF env variable)
+ A file system path to Clair's config file
+The above example starts two Clair nodes using the same configuration. +One will only run the indexing facilities while the other will only run the matching facilities.
+Environment variables respected by the Go standard library can be specified +if needed. Some notable examples:
+-
+
HTTP_PROXY
+HTTPS_PROXY
+SSL_CERT_DIR
+
If running in "combo" mode you must supply the indexer, matcher,
+and notifier configuration blocks in the configuration.
Configuration dropins
+Starting in Clair version 4.7.0, dropin configuration files are supported.
Given a root configurtaion file of /etc/clair/config.json, all files matching the globs /etc/clair/config.json.d/*.json and /etc/clair/config.json.d/*.json-patch would be loaded in lexical order after the root configuration file.
+Similarly, given /etc/clair/config.yaml, all files matching the globs /etc/clair/config.yaml.d/*.yaml and /etc/clair/config.yaml.d/*.yaml-patch would be loaded.
+Only the extensions yaml and json are supported, and indicate yaml and JSON formatting, respectively.
The dropin files must have the same extension and format as the root file.
+Dropins with the bare suffix are treated as merge documents.
+Dropins with the -patch suffix are treated as patch documents and must contain a valid RFC 6902 structure.
+Yaml documents must be resolvable to the JSON subset.
Take care with the merge behavior around lists; a patch operation may be more suitable.
+The clairctl check-config command can be used to ensure a merged configuration is what is intended.
+In addition, placing test operations in a patch file that's evaluated last (such as zz-validate.json-patch) can be used to have Clair refuse to start if some configuration values are not what is intended.
The application defaults are applied after the configuration is loaded and as such, not reflected in the clairctl check-config command.
+The output of that command is also not currently suitable to be used to "compile" a config to a single file.
Configuration Reference
+Please see the go module documentation for additional documentation on defaults and use.
+Starting in version 4.7.0, unknown keys are disallowed.
+Configurations that looked valid previously and loaded fine may now cause Clair to refuse to start.
http_listen_addr: ""
+introspection_addr: ""
+log_level: ""
+tls: {}
+indexer:
+ connstring: ""
+ scanlock_retry: 0
+ layer_scan_concurrency: 0
+ migrations: false
+ scanner: {}
+ airgap: false
+matcher:
+ connstring: ""
+ indexer_addr: ""
+ migrations: false
+ period: ""
+ disable_updaters: false
+ update_retention: 2
+matchers:
+ names: nil
+ config: nil
+updaters:
+ sets: nil
+ config: nil
+notifier:
+ connstring: ""
+ migrations: false
+ indexer_addr: ""
+ matcher_addr: ""
+ poll_interval: ""
+ delivery_interval: ""
+ disable_summary: false
+ webhook: null
+ amqp: null
+ stomp: null
+auth:
+ psk: nil
+trace:
+ name: ""
+ probability: null
+ jaeger:
+ agent:
+ endpoint: ""
+ collector:
+ endpoint: ""
+ username: null
+ password: null
+ service_name: ""
+ tags: nil
+ buffer_max: 0
+metrics:
+ name: ""
+ prometheus:
+ endpoint: null
+Note: the above just lists every key for completeness. Copy-pasting the above as +a starting point for configuration will result in some options not having their +defaults set normally.
+ +$.http_listen_addr
+A string in <host>:<port> format where <host> can be an empty string.
This configures where the HTTP API is exposed.
+See /openapi/v1 for the API spec.
$.introspection_addr
+A string in <host>:<port> format where <host> can be an empty string.
This configures where Clair's metrics and health endpoints are exposed.
+$.log_level
+Set the logging level.
+One of the following strings:
+-
+
- debug-color +
- debug +
- info +
- warn +
- error +
- fatal +
- panic +
$.tls
+TLS is a map containing the config for serving the HTTP API over TLS (and +HTTP/2).
+$.tls.cert
+The TLS certificate to be used. Must be a full-chain certificate, as in nginx.
+$.tls.key
+A key file for the TLS certificate. Encryption is not supported on the key.
+$.indexer
+Indexer provides Clair Indexer node configuration.
+$.indexer.airgap
+Disables HTTP access to the Internet for indexers and fetchers. +Private IPv4 and IPv6 addresses are allowed. +Database connections are unaffected.
+$.indexer.connstring
+A Postgres connection string.
+Accepts a format as a url (e.g.,
+postgres://pqgotest:password@localhost/pqgotest?sslmode=verify-full)
+or a libpq connection string (e.g.,
+user=pqgotest dbname=pqgotest sslmode=verify-full).
$.indexer.index_report_request_concurrency
+Integer.
+Rate limits the number of index report creation requests.
+Setting this to 0 will attempt to auto-size this value. Setting a negative value +means "unlimited." The auto-sizing is a multiple of the number of available +cores.
+The API will return a 429 status code if concurrency is exceeded.
+$.indexer.scanlock_retry
+A positive integer representing seconds.
+Concurrent Indexers lock on manifest scans to avoid clobbering. +This value tunes how often a waiting Indexer will poll for the lock.
+ +$.indexer.layer_scan_concurrency
+Positive integer limiting the number of concurrent layer scans.
+Indexers will index a Manifest's layers concurrently. +This value tunes the number of layers an Indexer will scan in parallel.
+$.indexer.migrations
+A boolean value.
+Whether Indexer nodes handle migrations to their database.
+$.indexer.scanner
+Indexer configurations.
+Scanner allows for passing configuration options to layer scanners. +The scanner will have this configuration passed to it on construction if +designed to do so.
+$.indexer.scanner.dist
+A map with the name of a particular scanner and arbitrary yaml as a value.
+$.indexer.scanner.package
+A map with the name of a particular scanner and arbitrary yaml as a value.
+$.indexer.scanner.repo
+A map with the name of a particular scanner and arbitrary yaml as a value.
+$.matcher
+Matcher provides Clair matcher node configuration.
+$.matcher.cache_age
+Duration string.
+Controls how long clients should be hinted to cache responses for.
+$.matcher.connstring
+A Postgres connection string.
+Accepts a format as a url (e.g.,
+postgres://pqgotest:password@localhost/pqgotest?sslmode=verify-full)
+or a libpq connection string (e.g.,
+user=pqgotest dbname=pqgotest sslmode=verify-full).
$.matcher.max_conn_pool
+A positive integer limiting the database connection pool size.
+Clair allows for a custom connection pool size. +This number will directly set how many active database +connections are allowed concurrently.
+This parameter will be ignored in a future version. +Users should configure this through the connection string.
+$.matcher.indexer_addr
+A string in <host>:<port> format where <host> can be an empty string.
A Matcher contacts an Indexer to create a VulnerabilityReport. +The location of this Indexer is required.
+$.matcher.migrations
+A boolean value.
+Whether Matcher nodes handle migrations to their databases.
+$.matcher.period
+A time.ParseDuration parseable string.
+Determines how often updates for new security advisories will take place.
+Defaults to 6 hours.
+$.matcher.disable_updaters
+A boolean value.
+Whether to run background updates or not.
+$.matcher.update_retention
+An integer value limiting the number of update operations kept in the database.
+Sets the number of update operations to retain between garbage collection +cycles. This should be set to a safe MAX value based on database size +constraints.
+Defaults to 10.
+If a value less than 0 is provided, GC is disabled. 2 is the minimum value to +ensure updates can be compared for notifications.
+$.matchers
+Matchers provides configuration for the in-tree Matchers and RemoteMatchers.
+$.matchers.names
+A list of string values informing the matcher factory about enabled matchers.
+If the value is nil the default list of Matchers will run:
+-
+
- alpine +
- aws +
- debian +
- oracle +
- photon +
- python +
- rhel +
- suse +
- ubuntu +
- crda +
If an empty list is provided zero matchers will run.
+$.matchers.config
+Provides configuration to specific matcher.
+A map keyed by the name of the matcher containing a sub-object which +will be provided to the matchers factory constructor.
+A hypothetical example:
+config:
+ python:
+ ignore_vulns:
+ - CVE-XYZ
+ - CVE-ABC
+$.updaters
+Updaters provides configuration for the Matcher's update manager.
+$.updaters.sets
+A list of string values informing the update manager which Updaters to run.
+If the value is nil (or null in yaml) the default set of Updaters will run:
-
+
- alpine +
- aws +
- debian +
- oracle +
- photon +
- pyupio +
- rhel +
- suse +
- ubuntu +
If an empty list is provided zero updaters will run.
+$.updaters.config
+Provides configuration to specific updater sets.
+A map keyed by the name of the updater set name containing a sub-object +which will be provided to the updater set's constructor.
+A hypothetical example:
+config:
+ ubuntu:
+ security_tracker_url: http://security.url
+ ignore_distributions:
+ - cosmic
+$.notifier
+Notifier provides Clair notifier node configuration.
+$.notifier.connstring
+A Postgres connection string.
+Accepts a format as a url (e.g.,
+postgres://pqgotest:password@localhost/pqgotest?sslmode=verify-full)
+or a libpq connection string (e.g.,
+user=pqgotest dbname=pqgotest sslmode=verify-full).
$.notifier.migrations
+A boolean value.
+Whether Notifier nodes handle migrations to their database.
+$.notifier.indexer_addr
+A string in <host>:<port> format where <host> can be an empty string.
A Notifier contacts an Indexer to create obtain manifests affected by +vulnerabilities. The location of this Indexer is required.
+$.notifier.matcher_addr
+A string in <host>:<port> format where <host> can be an empty string.
A Notifier contacts a Matcher to list update operations and acquire diffs. +The location of this Indexer is required.
+$.notifier.poll_interval
+A time.ParseDuration parsable string.
+The frequency at which the notifier will query at Matcher for Update Operations.
+$.notifier.delivery_interval
+A time.ParseDuration parsable string.
+The frequency at which the notifier attempt delivery of created or previously +failed notifications.
+$.notifier.disable_summary
+A boolean.
+Controls whether notifications should be summarized to one per manifest or not.
+$.notifier.webhook
+Configures the notifier for webhook delivery.
+$.notifier.webhook.target
+URL where the webhook will be delivered.
+$.notifier.webhook.callback
+The callback url where notifications can be retrieved. +The notification ID will be appended to this url.
+This will typically be where the clair notifier is hosted.
+$.notifier.webhook.headers
+A map associating a header name to a list of values.
+$.notifier.amqp
+Configures the notifier for AMQP delivery.
+Note: Clair does not declare any AMQP components on its own. All attempts +to use an exchange or queue are passive only and will fail The broker +administrators should setup exchanges and queues ahead of time.
+$.notifier.amqp.direct
+A boolean value.
+If true the Notifier will deliver individual notifications (not a callback) +to the configured AMQP broker.
+$.notifier.amqp.rollup
+Integer 0 or greater.
+If direct is true this value will inform notifier how many notifications
+to send in a single direct delivery. For example, if direct is set to
+true and rollup is set to 5, the notifier will deliver no more then
+5 notifications in a single json payload to the broker. Setting the value
+to 0 will effectively set it to 1.
$.notifier.amqp.exchange
+The AMQP Exchange to connect to.
+$.notifier.amqp.exchange.name
+string value
+The name of the exchange to connect to.
+$.notifier.amqp.exchange.type
+string value
+The type of the exchange. Typically:
+-
+
- direct +
- fanout +
- topic +
- headers +
$.notifier.amqp.exchange.durability
+bool value
+Whether the configured queue is durable or not.
+$.notifier.amqp.exchange.auto_delete
+bool value
+Whether the configured queue uses an auto_delete policy.
+$.notifier.amqp.routing_key
+string value
+The name of the routing key each notification will be sent with.
+$.notifier.amqp.callback
+a URL string
+If direct is false, this URL is provided in the notification callback sent
+to the broker. This URL should point to Clair's notification API endpoint.
$.notifier.amqp.uris
+list of URL strings
+A list of one or more AMQP brokers to connect to, in priority order.
+$.notifier.amqp.tls
+Configures TLS connection to AMQP broker.
+$.notifier.amqp.tls.root_ca
+string value
+The filesystem path where a root CA can be read.
+$.notifier.amqp.tls.cert
+string value
+The filesystem path where a tls certificate can be read. Note that clair
+also respects SSL_CERT_DIR, as documented for the Go crypto/x509 package.
$.notifier.amqp.tls.key
+string value
+The filesystem path where a TLS private key can be read.
+$.notifier.stomp
+Configures the notifier for STOMP delivery.
+$.notifier.stomp.direct
+A boolean value.
+If true, the Notifier will deliver individual notifications (not a
+callback) to the configured STOMP broker.
$.notifier.stomp.rollup
+Integer 0 or greater.
+If direct is true, this value will limit the number of notifications
+sent in a single direct delivery. For example, if direct is set to
+true and rollup is set to 5, the notifier will deliver no more
+then 5 notifications in a single json payload to the broker. Setting the value
+to 0 will effectively set it to 1.
$.notifier.stomp.callback
+a URL string
+If direct is false, this URL is provided in the notification callback sent
+to the broker. This URL should point to Clair's notification API endpoint.
$.notifier.stomp.destination
+a string value
+The STOMP destination to deliver notifications to.
+$.notifier.stomp.uris
+list of URL strings
+A list of one or more STOMP brokers to connect to in priority order.
+$.notifier.stomp.tls
+Configures TLS connection to STOMP broker.
+$.notifier.stomp.tls.root_ca
+string value
+The filesystem path where a root CA can be read.
+Note that clair also respects SSL_CERT_DIR, as documented for the Go
+crypto/x509 package.
$.notifier.stomp.tls.cert
+string value
+The filesystem path where a tls certificate can be read.
+$.notifier.stomp.tls.key
+string value
+The filesystem path where a tls private key can be read.
+$.notifier.stomp.user
+Configures login details for the STOMP broker.
+$.notifier.stomp.user.login
+string value
+The STOMP login to connect with.
+$.notifier.stomp.user.passcode
+string value
+The STOMP passcode to connect with.
+$.auth
+Defines ClairV4's external and intra-service JWT based authentication.
+If multiple auth mechanisms are defined, Clair will pick one. Currently, there +are not multiple mechanisms.
+$.auth.psk
+Defines preshared key authentication.
+$.auth.psk.key
+a string value
+A shared base64 encoded key distributed between all parties signing and +verifying JWTs.
+$.auth.psk.iss
+a list of string value
+A list of JWT issuers to verify. An empty list will accept any issuer in a +JWT claim.
+$.trace
+Defines distributed tracing configuration based on OpenTelemetry.
+$.trace.name
+a string value
+The name of the application traces will belong to.
+$.trace.probability
+a float value
+The probability a trace will occur.
+$.trace.jaeger
+Defines values for Jaeger tracing.
+$.trace.jaeger.agent
+Defines values for configuring delivery to a Jaeger agent.
+$.trace.jaeger.agent.endpoint
+a string value
+An address in <host>:<post> syntax where traces can be submitted.
$.trace.jaeger.collector
+Defines values for configuring delivery to a Jaeger collector.
+$.trace.jaeger.collector.endpoint
+a string value
+An address in <host>:<post> syntax where traces can be submitted.
$.trace.jaeger.collector.username
+a string value
+$.trace.jaeger.collector.password
+a string value
+$.trace.jaeger.service_name
+a string value
+$.trace.jaeger.tags
+a mapping of a string to a string
+$.trace.jaeger.buffer_max
+an integer value
+$.metrics
+Defines distributed tracing configuration based on OpenTelemetry.
+$.metrics.name
+a string value
+$.metrics.prometheus
+Configuration for a prometheus metrics exporter.
+$.metrics.prometheus.endpoint
+a string value
+Defines the path where metrics will be served.
++
1
+
+
+ Support added in version 4.7.0.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/reference/matcher.html b/v4.7.2/reference/matcher.html
new file mode 100644
index 0000000000..c41f26dc98
--- /dev/null
+++ b/v4.7.2/reference/matcher.html
@@ -0,0 +1,230 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Indexer
+When Clair is running in Indexer mode, it is responsible for receiving Manifests and generating IndexReports. An IndexReport is an intermediate representation of a manifest's content and is used to discover vulnerabilities.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/reference/metrics.html b/v4.7.2/reference/metrics.html
new file mode 100644
index 0000000000..0391b5a173
--- /dev/null
+++ b/v4.7.2/reference/metrics.html
@@ -0,0 +1,227 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Matcher
+When Clair is running in Matcher mode it is responsible for receiving IndexReports and generating VulnerabilityReports. A VulnerabilityReport describes the contents of a manifest and any vulnerabilities affecting it.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/reference/notifier.html b/v4.7.2/reference/notifier.html
new file mode 100644
index 0000000000..dd2a806c2b
--- /dev/null
+++ b/v4.7.2/reference/notifier.html
@@ -0,0 +1,230 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Clair exports metrics on the introspection +port in the Prometheus format.
+The exact metrics exposed are not considered API (and so are subject to change
+between releases) but should be well described. An up-to-date grafana dashboard
+example is in contrib/openshift/grafana.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v4.7.2/reference_test.go b/v4.7.2/reference_test.go
new file mode 100644
index 0000000000..825c6768c7
--- /dev/null
+++ b/v4.7.2/reference_test.go
@@ -0,0 +1,74 @@
+package Documentation
+
+import (
+ "bufio"
+ "fmt"
+ "os"
+ "reflect"
+ "regexp"
+ "sort"
+ "strings"
+ "testing"
+
+ "github.com/google/go-cmp/cmp"
+ "github.com/quay/clair/config"
+)
+
+func TestConfigReference(t *testing.T) {
+ f, err := os.Open("reference/config.md")
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer f.Close()
+
+ header := regexp.MustCompile("^#+ `\\$[^`]+`")
+ var got []string
+ s := bufio.NewScanner(f)
+ for s.Scan() {
+ if header.Match(s.Bytes()) {
+ got = append(got, strings.Trim(s.Text(), " #`"))
+ }
+ }
+ if err := s.Err(); err != nil {
+ t.Error(err)
+ }
+ var want []string
+ if err := walk(&want, "$", reflect.TypeOf(config.Config{})); err != nil {
+ t.Error(err)
+ }
+ sort.Strings(want)
+ sort.Strings(got)
+ if !cmp.Equal(got, want) {
+ t.Error(cmp.Diff(got, want))
+ }
+}
+
+type walkFunc func(interface{}) ([]string, error)
+
+func walk(ws *[]string, path string, t reflect.Type) error {
+ // Dereference the pointer, if this is a pointer.
+ if t.Kind() == reflect.Ptr {
+ t = t.Elem()
+ }
+ if t.Kind() == reflect.Struct {
+ for i, lim := 0, t.NumField(); i < lim; i++ {
+ f := t.Field(i)
+ var n string
+ switch t := f.Tag.Get("json"); t {
+ case "-", "":
+ continue
+ default:
+ if i := strings.IndexByte(t, ','); i != -1 {
+ t = t[:i]
+ }
+ n = t
+ }
+ p := fmt.Sprintf(`%s.%s`, path, n)
+ *ws = append(*ws, p)
+ if err := walk(ws, p, t.Field(i).Type); err != nil {
+ return err
+ }
+ }
+ }
+ return nil
+}
diff --git a/v4.7.2/searcher.js b/v4.7.2/searcher.js
new file mode 100644
index 0000000000..d2b0aeed38
--- /dev/null
+++ b/v4.7.2/searcher.js
@@ -0,0 +1,483 @@
+"use strict";
+window.search = window.search || {};
+(function search(search) {
+ // Search functionality
+ //
+ // You can use !hasFocus() to prevent keyhandling in your key
+ // event handlers while the user is typing their search.
+
+ if (!Mark || !elasticlunr) {
+ return;
+ }
+
+ //IE 11 Compatibility from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith
+ if (!String.prototype.startsWith) {
+ String.prototype.startsWith = function(search, pos) {
+ return this.substr(!pos || pos < 0 ? 0 : +pos, search.length) === search;
+ };
+ }
+
+ var search_wrap = document.getElementById('search-wrapper'),
+ searchbar = document.getElementById('searchbar'),
+ searchbar_outer = document.getElementById('searchbar-outer'),
+ searchresults = document.getElementById('searchresults'),
+ searchresults_outer = document.getElementById('searchresults-outer'),
+ searchresults_header = document.getElementById('searchresults-header'),
+ searchicon = document.getElementById('search-toggle'),
+ content = document.getElementById('content'),
+
+ searchindex = null,
+ doc_urls = [],
+ results_options = {
+ teaser_word_count: 30,
+ limit_results: 30,
+ },
+ search_options = {
+ bool: "AND",
+ expand: true,
+ fields: {
+ title: {boost: 1},
+ body: {boost: 1},
+ breadcrumbs: {boost: 0}
+ }
+ },
+ mark_exclude = [],
+ marker = new Mark(content),
+ current_searchterm = "",
+ URL_SEARCH_PARAM = 'search',
+ URL_MARK_PARAM = 'highlight',
+ teaser_count = 0,
+
+ SEARCH_HOTKEY_KEYCODE = 83,
+ ESCAPE_KEYCODE = 27,
+ DOWN_KEYCODE = 40,
+ UP_KEYCODE = 38,
+ SELECT_KEYCODE = 13;
+
+ function hasFocus() {
+ return searchbar === document.activeElement;
+ }
+
+ function removeChildren(elem) {
+ while (elem.firstChild) {
+ elem.removeChild(elem.firstChild);
+ }
+ }
+
+ // Helper to parse a url into its building blocks.
+ function parseURL(url) {
+ var a = document.createElement('a');
+ a.href = url;
+ return {
+ source: url,
+ protocol: a.protocol.replace(':',''),
+ host: a.hostname,
+ port: a.port,
+ params: (function(){
+ var ret = {};
+ var seg = a.search.replace(/^\?/,'').split('&');
+ var len = seg.length, i = 0, s;
+ for (;i
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Notifier
+When Clair is running in Notifier mode, it is responsible for generating notifications when new vulnerabilities affecting a previously indexed manifest enters the system. The notifier will send notifications via the configured mechanisms.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ What is Clair
+Clair is an application for parsing image contents and reporting vulnerabilities affecting the contents. This is done via static analysis and not at runtime.
+Clair supports the extraction of contents and assignment of vulnerabilities from the following official base containers:
+-
+
- Ubuntu +
- Debian +
- RHEL +
- Suse +
- Oracle +
- Alpine +
- AWS Linux +
- VMWare Photon +
- Python +
The above list defines Clair's current support matrix.
+Architecture
+Clair v4 utilizes the ClairCore library as its engine for examining contents and reporting vulnerabilities. At a high level you can consider Clair a service wrapper to the functionality provided in the ClairCore library.
+
The above diagram expresses the separation of concerns between Clair and the ClairCore library. Most development involving new distributions, vulnerability sources, and layer indexing will occur in ClairCore.
+How Clair Works
+Clair's analysis is broken into three distinct parts.
+Indexing
+Indexing starts with submitting a Manifest to Clair. On receipt, Clair will fetch layers, scan their contents, and return an intermediate representation called an IndexReport.
+Manifests are Clair's representation of a container image. Clair leverages the fact that OCI Manifests and Layers are content-addressed to reduce duplicated work.
+Once a Manifest is indexed, the IndexReport is persisted for later retrieval.
+Matching
+Matching is taking an IndexReport and correlating vulnerabilities affecting the manifest the report represents.
+Clair is continually ingesting new security data and a request to the matcher will always provide you with the most up to date vulnerability analysis of an IndexReport.
+How we implement indexing and matching in detail is covered in ClairCore's documentation.
+Notifications
+Clair implements a notification service.
+When new vulnerabilities are discovered, the notifier service will determine if these vulnerabilities affect any indexed Manifests. The notifier will then take action according to its configuration.
+Getting Started
+At this point you'll probably want to check out Getting Started With Clair.
+ +