openapi: 3.1.0
info:
  title: Clair Container Analyzer
  description: |-
    Clair is a set of cooperating microservices which can index and match a container image's content with known vulnerabilities.

    **Note:** Any endpoints tagged "internal" are documented for completeness but are considered exempt from versioning.
  version: 1.2.0
  contact:
    name: Clair Team
    url: http://github.com/quay/clair
    email: clair-devel@googlegroups.com
  license:
    name: Apache License 2.0
    url: http://www.apache.org/licenses/
externalDocs:
  url: https://quay.github.io/clair/
tags:
  - name: indexer
    description: |-
      Indexer service endpoints.

      These are responsible for determining the contents of containers.
  - name: matcher
    description: |-
      Matcher service endpoints.

      These are responsible for generating reports against current vulnerability data.
  - name: notifier
    description: |-
      Matcher service endpoints.

      These are responsible for serving notifications.
  - name: internal
    description: |-
      These are internal endpoints, documented for completeness.

      They are exempted from API stability guarentees.
paths:
  /indexer/api/v1/index_report:
    post:
      operationId: Index
      requestBody:
        description: Manifest to index.
        required: true
        content:
          application/vnd.clair.manifest.v1+json:
            schema:
              $ref: '#/components/schemas/manifest'
          application/json:
            schema:
              $ref: '#/components/schemas/manifest'
      responses:
        "400":
          $ref: '#/components/responses/bad_request'
        "415":
          $ref: '#/components/responses/unsupported_media_type'
        default:
          $ref: '#/components/responses/oops'
        "201":
          description: |-
            IndexReport created.

            Clients may want to avoid reading the body if simply submitting the manifest for later vulnerability reporting.
          content:
            application/vnd.clair.index_report.v1+json:
              schema:
                $ref: '#/components/schemas/index_report'
            application/json:
              schema:
                $ref: '#/components/schemas/index_report'
          headers:
            Location:
              $ref: '#/components/headers/Location'
            Link:
              $ref: '#/components/headers/Link'
          links:
            retrieve:
              operationId: GetIndexReport
              parameters:
                digest: $request.body#/hash
            delete:
              operationId: DeleteManifest
              parameters:
                digest: $request.body#/hash
            report:
              operationId: GetVulnerabilityReport
              parameters:
                digest: $request.body#/hash
        "412":
          description: Precondition Failed
      tags:
        - indexer
      summary: Index a Manifest
      description: 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.
    delete:
      operationId: DeleteManifests
      requestBody:
        description: Array of manifest digests to delete.
        required: true
        content:
          application/vnd.clair.bulk_delete.v1+json:
            schema:
              $ref: '#/components/schemas/bulk_delete'
          application/json:
            schema:
              $ref: '#/components/schemas/bulk_delete'
      responses:
        "200":
          description: Successfully deleted manifests.
          headers:
            Clair-Error:
              $ref: '#/components/headers/Clair-Error'
          content:
            application/vnd.clair.bulk_delete.v1+json:
              schema:
                $ref: '#/components/schemas/bulk_delete'
            application/json:
              schema:
                $ref: '#/components/schemas/bulk_delete'
        "400":
          $ref: '#/components/responses/bad_request'
        "415":
          $ref: '#/components/responses/unsupported_media_type'
        default:
          $ref: '#/components/responses/oops'
      tags:
        - indexer
      summary: Delete Indexed Manifests
      description: Given a Manifest's content addressable hash, any data related to it will be removed if it exists.
  /indexer/api/v1/index_report/{digest}:
    delete:
      operationId: DeleteManifest
      responses:
        "400":
          $ref: '#/components/responses/bad_request'
        "415":
          $ref: '#/components/responses/unsupported_media_type'
        default:
          $ref: '#/components/responses/oops'
        "204":
          description: Success
      tags:
        - indexer
      summary: Delete an Indexed Manifest
      description: Given a Manifest's content addressable hash, any data related to it will be removed it it exists.
    get:
      operationId: GetIndexReport
      responses:
        "200":
          description: IndexReport retrieved
          headers:
            Clair-Error:
              $ref: '#/components/headers/Clair-Error'
          content:
            application/vnd.clair.index_report.v1+json:
              schema:
                $ref: '#/components/schemas/index_report'
            application/json:
              schema:
                $ref: '#/components/schemas/index_report'
        "400":
          $ref: '#/components/responses/bad_request'
        "415":
          $ref: '#/components/responses/unsupported_media_type'
        default:
          $ref: '#/components/responses/oops'
        "404":
          $ref: '#/components/responses/not_found'
      tags:
        - indexer
      summary: Retrieve the IndexReport for a Manifest
      description: Given a Manifest's content addressable hash, an IndexReport will be retrieved if it exists.
    parameters:
      - $ref: '#/components/parameters/digest'
  /indexer/api/v1/index_state:
    get:
      operationId: IndexState
      responses:
        "200":
          description: Indexer State
          headers:
            Etag:
              $ref: '#/components/headers/Etag'
          content:
            application/vnd.clair.index_state.v1+json:
              schema:
                $ref: '#/components/schemas/index_state'
            application/json:
              schema:
                $ref: '#/components/schemas/index_state'
        "304":
          description: Not Modified
      tags:
        - indexer
      summary: Report the Indexer's State
      description: |-
        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.
  /indexer/api/v1/internal/affected_manifest:
    post:
      operationId: AffectedManifests
      requestBody:
        description: Array of vulnerability summaries to report on.
        required: true
        content:
          application/vnd.clair.vulnerability_summaries.v1+json:
            schema:
              $ref: '#/components/schemas/vulnerability_summaries'
          application/json:
            schema:
              $ref: '#/components/schemas/vulnerability_summaries'
      responses:
        "200":
          description: The list of manifests and the corresponding vulnerabilities.
          headers:
            Clair-Error:
              $ref: '#/components/headers/Clair-Error'
          content:
            application/vnd.clair.affected_manifests.v1+json:
              schema:
                $ref: '#/components/schemas/affected_manifests'
            application/json:
              schema:
                $ref: '#/components/schemas/affected_manifests'
        "400":
          $ref: '#/components/responses/bad_request'
        "415":
          $ref: '#/components/responses/unsupported_media_type'
        default:
          $ref: '#/components/responses/oops'
      tags:
        - internal
      summary: Retrieve Manifests Affected by a Vulnerability
      description: The provided vulnerability summaries are attempted to be run "backwards" through the indexer to produce a set of manifests.
      x-cli-ignore: true
  /matcher/api/v1/internal/update_diff:
    get:
      operationId: GetUpdateDiff
      responses:
        "200":
          description: Changes between two Update Operations.
          headers:
            Clair-Error:
              $ref: '#/components/headers/Clair-Error'
          content:
            application/vnd.clair.update_diff.v1+json:
              schema:
                $ref: '#/components/schemas/update_diff'
            application/json:
              schema:
                $ref: '#/components/schemas/update_diff'
        "400":
          $ref: '#/components/responses/bad_request'
        "415":
          $ref: '#/components/responses/unsupported_media_type'
        default:
          $ref: '#/components/responses/oops'
      parameters:
        - in: query
          name: cur
          schema:
            $ref: '#/components/schemas/token'
          description: '"Current" Update Operation ref.'
        - in: query
          name: prev
          required: true
          schema:
            $ref: '#/components/schemas/token'
          description: '"Previous" Update Operation ref.'
      tags:
        - internal
      summary: Retrieve Vulnerability Changes Between Two Update Operations
      description: Given IDs for two Update Operations, this will return the difference between them. This is used in the notification flow.
      x-cli-ignore: true
  /matcher/api/v1/internal/update_operation:
    get:
      operationId: GetUpdateOperation
      responses:
        "200":
          description: Update Operations, keyed by updater.
          headers:
            Clair-Error:
              $ref: '#/components/headers/Clair-Error'
          content:
            application/vnd.clair.update_operations.v1+json:
              schema:
                $ref: '#/components/schemas/update_operations'
            application/json:
              schema:
                $ref: '#/components/schemas/update_operations'
        "400":
          $ref: '#/components/responses/bad_request'
        "415":
          $ref: '#/components/responses/unsupported_media_type'
        default:
          $ref: '#/components/responses/oops'
      parameters:
        - in: query
          name: kind
          schema:
            enum:
              - vulnerability
              - enrichment
            default: vulnerability
          description: The "kind" of updaters to query.
        - in: query
          name: latest
          schema:
            type: boolean
            default: false
          description: Return only the latest Update Operations instead of all known Update Operations.
      tags:
        - internal
      summary: Retrieve Update Operations
      description: Retrive all known or just the latest Update Operations.
      x-cli-ignore: true
  /matcher/api/v1/internal/update_operation/{digest}:
    delete:
      operationId: DeleteUpdateOperation
      responses:
        "200":
          description: Success
          headers:
            Clair-Error:
              $ref: '#/components/headers/Clair-Error'
        "400":
          $ref: '#/components/responses/bad_request'
        "415":
          $ref: '#/components/responses/unsupported_media_type'
        default:
          $ref: '#/components/responses/oops'
      tags:
        - internal
      summary: Delete an Update Operation
      description: |-
        Issues a delete of the provided Update Operation ID and all associated data.
        After this delete clients will no longer be able to generate a diff against this Update Operation.
      x-cli-ignore: true
    parameters:
      - $ref: '#/components/parameters/digest'
  /matcher/api/v1/vulnerability_report/{digest}:
    get:
      operationId: GetVulnerabilityReport
      responses:
        "400":
          $ref: '#/components/responses/bad_request'
        "415":
          $ref: '#/components/responses/unsupported_media_type'
        default:
          $ref: '#/components/responses/oops'
        "201":
          description: Vulnerability Report Created
          content:
            application/vnd.clair.vulnerability_report.v1+json:
              schema:
                $ref: '#/components/schemas/vulnerability_report'
            application/json:
              schema:
                $ref: '#/components/schemas/vulnerability_report'
        "404":
          $ref: '#/components/responses/not_found'
      tags:
        - matcher
      summary: Retrieve a VulnerabilityReport for a Manifest
      description: Given a Manifest's content addressable hash a VulnerabilityReport will be created. The Manifest **must** have been Indexed first via the Index endpoint.
    parameters:
      - $ref: '#/components/parameters/digest'
  /notifier/api/v1/notification/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          $ref: '#/components/schemas/token'
        description: A notification ID returned by a callback
    delete:
      operationId: DeleteNotification
      responses:
        "200":
          description: Delete the notification referenced by the "id" parameter.
          headers:
            Clair-Error:
              $ref: '#/components/headers/Clair-Error'
        "400":
          $ref: '#/components/responses/bad_request'
        "415":
          $ref: '#/components/responses/unsupported_media_type'
        default:
          $ref: '#/components/responses/oops'
      tags:
        - notifier
      summary: Delete a Notification Set
      description: |-
        Issues a delete of the provided notification ID and all associated notifications.
        After this delete clients will no longer be able to retrieve notifications.
    get:
      operationId: GetNotification
      parameters:
        - in: query
          name: page_size
          schema:
            type: integer
            default: 500
          description: The maximum number of notifications to deliver in a single page.
        - in: query
          name: next
          schema:
            $ref: '#/components/schemas/token'
          description: The next page to fetch via id. Typically this number is provided on initial response in the "page.next" field. The first request should omit this field.
      responses:
        "200":
          description: A paginated list of notifications
          headers:
            Clair-Error:
              $ref: '#/components/headers/Clair-Error'
          content:
            application/vnd.clair.notification_page.v1+json:
              schema:
                $ref: '#/components/schemas/notification_page'
            application/json:
              schema:
                $ref: '#/components/schemas/notification_page'
        "400":
          $ref: '#/components/responses/bad_request'
        "415":
          $ref: '#/components/responses/unsupported_media_type'
        default:
          $ref: '#/components/responses/oops'
        "304":
          description: Not Modified
      tags:
        - notifier
      summary: Retrieve Pages of a Notification Set
      description: By performing a GET with an id as a path parameter, the client will retrieve a paginated response of notification objects.
security:
  - {}
  - PSK: []
webhooks:
  notification:
    post:
      tags:
        - notifier
      description: If configured, Clair will issue webhooks when notifications are available for retrieval.
      requestBody:
        content:
          application/vnd.clair.notification_webhook.v1+json:
            schema:
              $ref: '#/components/schemas/notification_webhook'
      responses:
        "200":
          description: OK
components:
  schemas:
    token:
      type: string
      description: An opaque token previously obtained from the service.
    affected_manifests:
      $id: https://clairproject.org/api/http/v1/affected_manifests.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Affected Manifests
      type: object
      description: |-
        **This is an internal type, documented for completeness.**

        Manifests affected by the specified vulnerability objects.
      properties:
        vulnerabilities:
          type: object
          description: Vulnerability objects.
          additionalProperties:
            $ref: vulnerability.schema.json
        vulnerable_manifests:
          type: object
          description: Mapping of manifest digests to vulnerability identifiers.
          additionalProperties:
            type: array
            items:
              type: string
              description: An identifier to be used in the "vulnerabilities" object.
      required:
        - vulnerabilities
        - vulnerable_manifests
      examples:
        - vulnerabilities:
            "42":
              id: "42"
          vulnerable_manifests:
            sha256:01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b:
              - "42"
    bulk_delete:
      $id: https://clairproject.org/api/http/v1/bulk_delete.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Bulk Delete
      type: array
      description: Array of manifest digests to delete from the system.
      items:
        $ref: digest.schema.json
        description: Manifest digest to delete from the system.
      examples:
        - - sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3
    cpe:
      $id: https://clairproject.org/api/http/v1/cpe.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Common Platform Enumeration Name
      description: This is a CPE Name in either v2.2 "URI" form or v2.3 "Formatted String" form.
      $comment: Clair only produces v2.3 CPE Names. Any v2.2 Names will be normalized into v2.3 form.
      oneOf:
        - description: 'This is the CPE 2.2 regexp: https://cpe.mitre.org/specification/2.2/cpe-language_2.2.xsd'
          type: string
          pattern: ^[c][pP][eE]:/[AHOaho]?(:[A-Za-z0-9\._\-~%]*){0,6}$
        - description: 'This is the CPE 2.3 regexp: https://csrc.nist.gov/schema/cpe/2.3/cpe-naming_2.3.xsd'
          type: string
          pattern: ^cpe:2\.3:[aho\*\-](:(((\?*|\*?)([a-zA-Z0-9\-\._]|(\\[\\\*\?!"#$$%&'\(\)\+,/:;<=>@\[\]\^`\{\|}~]))+(\?*|\*?))|[\*\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[\*\-]))(:(((\?*|\*?)([a-zA-Z0-9\-\._]|(\\[\\\*\?!"#$$%&'\(\)\+,/:;<=>@\[\]\^`\{\|}~]))+(\?*|\*?))|[\*\-])){4}$
      examples:
        - cpe:/a:microsoft:internet_explorer:8.0.6001:beta
        - cpe:2.3:a:microsoft:internet_explorer:8.0.6001:beta:*:*:*:*:*:*
    digest:
      $id: https://clairproject.org/api/http/v1/digest.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Digest
      description: A digest acts as a content identifier, enabling content addressability.
      type: string
      anyOf:
        - $comment: 'SHA256: MUST be implemented'
          description: SHA256
          type: string
          pattern: ^sha256:[a-f0-9]{64}$
        - $comment: 'SHA512: MAY be implemented'
          description: SHA512
          type: string
          pattern: ^sha512:[a-f0-9]{128}$
        - $comment: 'BLAKE3: MAY be implemented'
          description: |-
            BLAKE3

            **Currently not implemented.**
          type: string
          pattern: ^blake3:[a-f0-9]{64}$
      examples:
        - sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
        - sha512:27c74670adb75075fad058d5ceaf7b20c4e7786c83bae8a32f626f9782af34c9a33c2046ef60fd2a7878d378e29fec851806bbd9a67878f3a9f1cda4830763fd
        - blake3:6e46dd10defc9b56c29a6ec56b508c21f54c08192194e4df25bf36f0c9c3c279
    distribution:
      $id: https://clairproject.org/api/http/v1/distribution.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Distribution
      type: object
      description: Distribution is the accompanying system context of a Package.
      properties:
        id:
          description: Unique ID for this Distribution. May be unique to the response document, not the whole system.
          type: string
        did:
          description: A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_", and "-") identifying the operating system, excluding any version information and suitable for processing by scripts or usage in generated filenames.
          type: string
        name:
          description: A string identifying the operating system.
          type: string
        version:
          description: A string identifying the operating system version, excluding any OS name information, possibly including a release code name, and suitable for presentation to the user.
          type: string
        version_code_name:
          description: A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_", and "-") identifying the operating system release code name, excluding any OS name information or release version, and suitable for processing by scripts or usage in generated filenames.
          type: string
        version_id:
          description: A lower-case string (mostly numeric, no spaces or other characters outside of 0–9, a–z, ".", "_", and "-") identifying the operating system version, excluding any OS name information or release code name.
          type: string
        arch:
          description: A string identifying the OS architecture.
          type: string
        cpe:
          description: Common Platform Enumeration name.
          $ref: cpe.schema.json
        pretty_name:
          description: A pretty operating system name in a format suitable for presentation to the user.
          type: string
      additionalProperties: false
      required:
        - id
      examples:
        - id: "1"
          did: ubuntu
          name: Ubuntu
          version: 18.04.3 LTS (Bionic Beaver)
          version_code_name: bionic
          version_id: "18.04"
          pretty_name: Ubuntu 18.04.3 LTS
    environment:
      $id: https://clairproject.org/api/http/v1/environment.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Environment
      type: object
      description: Environment describes the surrounding environment a package was discovered in.
      properties:
        package_db:
          description: The database the associated Package was discovered in.
          type: string
        distribution_id:
          description: The ID of the Distribution of the associated Package.
          type: string
        introduced_in:
          description: The Layer the associated Package was introduced in.
          $ref: digest.schema.json
        repository_ids:
          description: The IDs of the Repositories of the associated Package.
          type: array
          items:
            type: string
      additionalProperties: false
      examples:
        - value:
            package_db: var/lib/dpkg/status
            introduced_in: sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a
            distribution_id: "1"
    error:
      $id: https://clairproject.org/api/http/v1/error.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Error
      type: object
      description: A general error response.
      properties:
        code:
          type: string
          description: a code for this particular error
        message:
          type: string
          description: a message with further detail
      required:
        - message
    index_report:
      $id: https://clairproject.org/api/http/v1/index_report.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Index Report
      type: object
      description: An index of the contents of a Manifest.
      properties:
        manifest_hash:
          $ref: digest.schema.json
          description: The Manifest's digest.
        state:
          type: string
          description: The current state of the index operation
        err:
          type: string
          description: An error message on event of unsuccessful index
        success:
          type: boolean
          description: A bool indicating succcessful index
        packages:
          type: object
          description: A map of Package objects indexed by a document-local identifier.
          additionalProperties:
            $ref: package.schema.json
        distributions:
          type: object
          description: A map of Distribution objects indexed by a document-local identifier.
          additionalProperties:
            $ref: distribution.schema.json
        repository:
          type: object
          description: A map of Repository objects indexed by a document-local identifier.
          additionalProperties:
            $ref: repository.schema.json
        environments:
          type: object
          description: A map of Environment arrays indexed by a Package's identifier.
          additionalProperties:
            type: array
            items:
              $ref: environment.schema.json
      additionalProperties: false
      required:
        - manifest_hash
        - state
        - success
    index_state:
      $id: https://clairproject.org/api/http/v1/index_state.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Index State
      type: object
      description: Information on the state of the indexer system.
      properties:
        state:
          type: string
          description: an opaque token
      required:
        - state
    layer:
      $id: https://clairproject.org/api/http/v1/layer.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Layer
      type: object
      description: Layer is a description of a container layer. It should contain enough information to fetch the layer.
      properties:
        hash:
          $ref: digest.schema.json
          description: Digest of the layer blob.
        uri:
          type: string
          description: A URI indicating where the layer blob can be downloaded from.
        headers:
          description: Any additional HTTP-style headers needed for requesting layers.
          type: object
          patternProperties:
            ^[a-zA-Z0-9\-_]+$:
              type: array
              items:
                type: string
        media_type:
          description: The OCI Layer media type for this layer.
          type: string
          pattern: ^application/vnd\.oci\.image\.layer\.v1\.tar(\+(gzip|zstd))?$
      additionalProperties: false
      required:
        - hash
        - uri
    manifest:
      $id: https://clairproject.org/api/http/v1/manifest.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Manifest
      type: object
      description: A description of an OCI Image Manifest.
      properties:
        hash:
          $ref: digest.schema.json
          description: |-
            The OCI Image Manifest's digest.

            This is used as an identifier throughout the system. This **SHOULD** be the same as the OCI Image Manifest's digest, but this is not enforced.
        layers:
          type: array
          description: The OCI Layers making up the Image, in order.
          items:
            $ref: layer.schema.json
      additionalProperties: false
      required:
        - hash
      examples:
        - hash: sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3
          layers:
            - hash: sha256:2f077db56abccc19f16f140f629ae98e904b4b7d563957a7fc319bd11b82ba36
              uri: https://storage.example.com/blob/2f077db56abccc19f16f140f629ae98e904b4b7d563957a7fc319bd11b82ba36
              headers:
                Authoriztion:
                  - Bearer hunter2
    normalized_severity:
      $id: https://clairproject.org/api/http/v1/normalized_severity.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Normalized Severity
      description: Standardized severity values.
      enum:
        - Unknown
        - Negligible
        - Low
        - Medium
        - High
        - Critical
    notification_page:
      $id: https://clairproject.org/api/http/v1/notification_page.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Notification Page
      type: object
      description: A page description and list of notifications.
      properties:
        page:
          description: An object informing the client the next page to retrieve.
          type: object
          properties:
            size:
              description: The number of notifications contained in this page.
              type: integer
            next:
              description: |-
                The identififer to pass into the "next" parameter of a future GetNotification request.

                If not present, there are no additional pages.
              type: string
          additionalProperties: false
          required:
            - size
        notifications:
          description: Notifications within this page.
          type: array
          items:
            $ref: notification.schema.json
      additionalProperties: false
      required:
        - page
        - notifications
      examples:
        - 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://example.com/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."
                normalized_severity: Unknown
                package:
                  id: "10"
                  name: libapt-pkg5.0
                  version: 1.6.11
                  kind: BINARY
                  arch: x86
                  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"
                  pretty_name: Ubuntu 18.04.3 LTS
    notification:
      $id: https://clairproject.org/api/http/v1/notification.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Notification
      type: object
      description: A change in a manifest affected by a vulnerability.
      properties:
        id:
          description: Unique identifier for this notification.
          type: string
        manifest:
          $ref: digest.schema.json
          description: The digest of the manifest affected by the provided vulnerability.
        reason:
          description: The reason for the notifcation.
          enum:
            - added
            - removed
        vulnerability:
          $ref: vulnerability_summary.schema.json
      additionalProperties: false
      required:
        - id
        - manifest
        - reason
        - vulnerability
    notification_webhook:
      $id: https://clairproject.org/api/http/v1/notification_webhook.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Notification Webhook
      type: object
      description: Webhook sent to a configured service to begin retrieving notifications.
      properties:
        notification_id:
          description: Unique identifier for this notification.
          type: string
        callback:
          description: A URL to retrieve paginated Notification objects.
          type: string
          format: uri
      additionalProperties: false
      required:
        - notification_id
        - callback
    package:
      $id: https://clairproject.org/api/http/v1/package.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Package
      type: object
      description: Description of installed software.
      properties:
        id:
          description: Unique ID for this Package. May be unique to the response document, not the whole system.
          type: string
        name:
          description: |-
            Identifier of this Package.

            The uniqueness and scoping of this name depends on the packaging system.
          type: string
        version:
          description: Version of this Package, as reported by the packaging system.
          type: string
        kind:
          description: The "kind" of this Package.
          enum:
            - BINARY
            - SOURCE
          default: BINARY
        source:
          $ref: '#'
          description: Source Package that produced the current binary Package, if known.
        normalized_version:
          description: |-
            Normalized representation of the discoverd version.

            The format is not specific, but is guarenteed to be forward compatible.
          type: string
        module:
          description: |-
            An identifier for intra-Repository grouping of packages.

            Likely only relevant on rpm-based systems.
          type: string
        arch:
          description: Native architecture for the Package.
          type: string
          $comment: This should become and enum in the future.
        cpe:
          $ref: cpe.schema.json
          description: CPE Name for the Package.
      additionalProperties: false
      required:
        - name
        - version
      examples:
        - 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
    range:
      $id: https://clairproject.org/api/http/v1/range.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Range
      type: object
      description: A range of versions.
      properties:
        '[':
          type: string
          description: Lower bound, inclusive.
        ):
          type: string
          description: Upper bound, exclusive.
      minProperties: 1
      additionalProperties: false
    repository:
      $id: https://clairproject.org/api/http/v1/repository.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Repository
      type: object
      description: Description of a software repository
      properties:
        id:
          description: Unique ID for this Repository. May be unique to the response document, not the whole system.
          type: string
        name:
          description: Human-relevant name for the Repository.
          type: string
        key:
          description: Machine-relevant name for the Repository.
          type: string
        uri:
          description: URI describing the Repository.
          type: string
          format: uri
        cpe:
          description: CPE name for the Repository.
          $ref: cpe.schema.json
      additionalProperties: false
      required:
        - id
    update_diff:
      $id: https://clairproject.org/api/http/v1/update_diff.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Update Difference
      type: object
      description: |-
        **This is an internal type, documented for completeness.**

        An update difference describes changes between two Update Operations.
      properties:
        prev:
          description: The previous Update Operation.
          $ref: update_operation.schema.json
        cur:
          description: The current Update Operation.
          $ref: update_operation.schema.json
        added:
          description: Vulnerabilities present in "cur", but not "prev".
          type: array
          items:
            $ref: vulnerability.schema.json
        removed:
          description: Vulnerabilities present in "prev", but not "cur".
          type: array
          items:
            $ref: vulnerability.schema.json
      additionalProperties: false
      required:
        - cur
        - added
        - removed
    update_operation:
      $id: https://clairproject.org/api/http/v1/update_operation.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Update Operation
      type: object
      description: |-
        **This is an internal type, documented for completeness.**

        An update operations describes an update of the internal vulnerability database.
      properties:
        ref:
          type: string
          description: A unique identifier for this update operation.
          format: uuid
        updater:
          description: The "updater" component that was run.
          $comment: 'This is not as useful as it could be: an end user needs to know too much about Clair(core)''s internals to make sense of it.'
          type: string
        fingerprint:
          description: The stored "fingerprint" of this run.
          type: string
        date:
          type: string
          description: When this operation was run.
          format: date-time
        kind:
          description: The kind of data this operation updated.
          enum:
            - vulnerability
            - enrichment
      additionalProperties: false
      required:
        - ref
        - updater
        - fingerprint
        - date
        - kind
    update_operations:
      $id: https://clairproject.org/api/http/v1/update_operations.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Update Operations
      type: object
      description: |-
        **This is an internal type, documented for completeness.**

        A mapping of updater id to Update Operation(s).
      additionalProperties:
        type: array
        items:
          $ref: update_operation.schema.json
    vulnerability_core:
      $id: https://clairproject.org/api/http/v1/vulnerability_core.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Vulnerability Core
      type: object
      description: The core elements of vulnerabilities in the Clair system.
      properties:
        name:
          type: string
          description: Human-readable name, as presented in the vendor data.
        fixed_in_version:
          type: string
          description: Version string, as presented in the vendor data.
        severity:
          type: string
          description: Severity, as presented in the vendor data.
        normalized_severity:
          $ref: normalized_severity.schema.json
          description: A well defined set of severity strings guaranteed to be present.
        range:
          $ref: range.schema.json
          description: Range of versions the vulnerability applies to.
        arch_op:
          description: Flag indicating how the referenced package's "arch" member should be interpreted.
          enum:
            - equals
            - not equals
            - pattern match
        package:
          $ref: package.schema.json
          description: A package description
        distribution:
          $ref: distribution.schema.json
          description: A distribution description
        repository:
          $ref: repository.schema.json
          description: A repository description
      required:
        - name
        - normalized_severity
      dependentRequired:
        package:
          - arch_op
      anyOf:
        - required:
            - package
        - required:
            - repository
        - required:
            - distribution
    vulnerability_report:
      $id: https://clairproject.org/api/http/v1/vulnerability_report.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Vulnerability Report
      type: object
      description: A report with discovered packages, package environments, and package vulnerabilities within a Manifest.
      properties:
        manifest_hash:
          $ref: digest.schema.json
          description: The Manifest's digest.
        packages:
          type: object
          description: A map of Package objects indexed by a document-local identifier.
          additionalProperties:
            $ref: package.schema.json
        distributions:
          type: object
          description: A map of Distribution objects indexed by a document-local identifier.
          additionalProperties:
            $ref: distribution.schema.json
        repository:
          type: object
          description: A map of Repository objects indexed by a document-local identifier.
          additionalProperties:
            $ref: repository.schema.json
        environments:
          type: object
          description: A map of Environment arrays indexed by a Package's identifier.
          additionalProperties:
            type: array
            items:
              $ref: environment.schema.json
        vulnerabilities:
          type: object
          description: A map of Vulnerabilities indexed by a document-local identifier.
          additionalProperties:
            $ref: vulnerability.schema.json
        package_vulnerabilities:
          type: object
          description: A mapping of Vulnerability identifier lists indexed by Package identifier.
          additionalProperties:
            type: array
            items:
              type: string
        enrichments:
          type: object
          description: A mapping of extra "enrichment" data by type
          additionalProperties:
            type: array
      additionalProperties: false
      required:
        - distributions
        - environments
        - manifest_hash
        - packages
        - package_vulnerabilities
        - vulnerabilities
    vulnerability:
      $id: https://clairproject.org/api/http/v1/vulnerability.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Vulnerability
      type: object
      description: Description of a software flaw.
      $ref: vulnerability_core.schema.json
      properties:
        id:
          description: Unique ID for this Vulnerabiltity. May be unique to the response document, not the whole system.
          type: string
        updater:
          description: The updater component this Vulnerability came from.
          type: string
        description:
          description: A human-readable description of the vulnerability.
          type: string
        issued:
          description: The datetime this Vulnerability was issued, if known.
          type: string
          format: date-time
        links:
          description: Space-separated URIs to more information.
          type: string
      unevaluatedProperties: false
      required:
        - id
        - updater
      examples:
        - id: "356835"
          updater: ubuntu
          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: 2.27-0ubuntu1
            kind: binary
            source: null
          dist:
            id: "0"
            did: ubuntu
            name: Ubuntu
            version: 18.04.3 LTS (Bionic Beaver)
            version_code_name: bionic
            version_id: "18.04"
            arch: amd64
          repo:
            id: "0"
            name: Ubuntu 18.04.3 LTS
          issued: "2019-10-12T07:20:50.52Z"
          fixed_in_version: 2.28-0ubuntu1
    vulnerability_summaries:
      $id: https://clairproject.org/api/http/v1/vulnerability_summaries.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Vulnerability Summaries
      type: array
      description: |-
        **This is an internal type, documented for completeness.**

        This is an array of pseudo-Vulnerability objects used for reverse-lookup.
      items:
        description: Summary vulnerability objects.
        $ref: vulnerability_summary.schema.json
    vulnerability_summary:
      $id: https://clairproject.org/api/http/v1/vulnerability_summary.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      title: Vulnerability Summary
      type: object
      description: A summary of a vulnerability.
      $ref: vulnerability_core.schema.json
      unevaluatedProperties: false
      examples:
        - 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.
          normalized_severity: Low
          fixed_in_version: v0.0.1
          links: http://link-to-advisory
          package:
            id: "0"
            name: glibc
            version: v0.0.1-rc1
          dist:
            id: "0"
            did: ubuntu
            name: Ubuntu
            version: 18.04.3 LTS (Bionic Beaver)
            version_code_name: bionic
            version_id: "18.04"
          repo:
            id: "0"
            name: Ubuntu 18.04.3 LTS
  responses:
    bad_request:
      description: Bad Request
      content:
        application/vnd.clair.error.v1+json:
          schema:
            $ref: '#/components/schemas/error'
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    oops:
      description: Internal Server Error
      content:
        application/vnd.clair.error.v1+json:
          schema:
            $ref: '#/components/schemas/error'
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    not_found:
      description: Not Found
      content:
        application/vnd.clair.error.v1+json:
          schema:
            $ref: '#/components/schemas/error'
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    unsupported_media_type:
      description: Unsupported Media Type
      content:
        application/vnd.clair.error.v1+json:
          schema:
            $ref: '#/components/schemas/error'
        application/json:
          schema:
            $ref: '#/components/schemas/error'
  parameters:
    digest:
      description: OCI-compatible digest of a referred object.
      name: digest
      in: path
      schema:
        $ref: '#/components/schemas/digest'
      required: true
  headers:
    Clair-Error:
      description: This is a trailer containing any errors encountered while writing the response.
      style: simple
      schema:
        type: string
    Etag:
      description: HTTP [ETag header](https://httpwg.org/specs/rfc9110.html#field.etag)
      style: simple
      schema:
        type: string
    Link:
      description: Web Linking [Link header](https://httpwg.org/specs/rfc8288.html#header)
      style: simple
      schema:
        type: string
    Location:
      description: HTTP [Location header](https://httpwg.org/specs/rfc9110.html#field.location)
      style: simple
      required: true
      schema:
        type: string
  securitySchemes:
    PSK:
      type: http
      scheme: bearer
      bearerFormat: JWT with preshared key and allow-listed issuers
      description: |-
        Clair's authentication scheme.

        This is a [JWT](https://datatracker.ietf.org/doc/html/rfc7519) signed with a configured pre-shared key containing an allowlisted `iss` claim.