openapi.yaml

---
openapi: "3.0.2"
info:
  title: "ClairV4"
  description: |
    ClairV4 is a set of cooperating microservices which scan, index, and
    match your container's content with known vulnerabilities.
  version: "0.1"
  termsOfService: ""
  contact:
    name: "Clair Team"
    url: "http://github.com/quay/clair"
    email: "quay-devel@redhat.com"
  license:
    name: "Apache License 2.0"
    url: "http://www.apache.org/licenses/"

paths:
  notifier/api/v1/notification/{notification_id}:
    delete:
      tags:
        - Notifier
      operationId: "DeleteNotification"
      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.
      parameters:
        - in: path
          name: notification_id
          schema:
            type: string
          description: "A notification ID returned by a callback"
      responses:
        200:
          description: "OK"
        400:
          $ref: '#/components/responses/BadRequest'
        405:
          $ref: '#/components/responses/MethodNotAllowed'
        500:
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
        - Notifier
      operationId: "GetNotification"
      summary: Retrieve a paginated result of notifications for the provided id.
      description: |
        By performing a GET with a notification_id as a path parameter, the
        client will retrieve a paginated response of notification objects.
      parameters:
        - in: path
          name: notification_id
          schema:
            type: string
          description: "A notification ID returned by a callback"
        - in: query
          name: page_size
          schema:
            type: int
          description: |
            The maximum number of notifications to deliver in a single page.
        - in: query
          name: next
          schema:
            type: string
          description: |
            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.
      responses:
        200:
          description: "A paginated list of notifications"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedNotifications'
        400:
          $ref: '#/components/responses/BadRequest'
        405:
          $ref: '#/components/responses/MethodNotAllowed'
        500:
          $ref: '#/components/responses/InternalServerError'

  indexer/api/v1/index_report:
    post:
      tags:
        - Indexer
      operationId: "Index"
      summary: "Index the contents of 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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Manifest'
      responses:
        201:
          description: IndexReport Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexReport'
        400:
          $ref: '#/components/responses/BadRequest'
        405:
          $ref: '#/components/responses/MethodNotAllowed'
        500:
          $ref: '#/components/responses/InternalServerError'

  indexer/api/v1/index_report/{manifest_hash}:
    get:
      tags:
        - Indexer
      operationId: "GetIndexReport"
      summary: "Retrieve an IndexReport for the given Manifest hash if exists."
      description: |
        Given a Manifest's content addressable hash an IndexReport will
        be retrieved if exists.
      parameters:
        - name: manifest_hash
          in: path
          description: |
            A digest of a manifest that has been indexed previous to this
            request.
          required: true
          schema:
            $ref: '#/components/schemas/Digest'
      responses:
        200:
          description: IndexReport retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexReport'
        400:
          $ref: '#/components/responses/BadRequest'
        404:
          $ref: '#/components/responses/NotFound'
        405:
          $ref: '#/components/responses/MethodNotAllowed'
        500:
          $ref: '#/components/responses/InternalServerError'

  matcher/api/v1/vulnerability_report/{manifest_hash}:
    get:
      tags:
        - Matcher
      operationId: "GetVulnerabilityReport"
      summary: |
        Retrieve a VulnerabilityReport for a given manifest's content
        addressable hash.
      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:
        - name: manifest_hash
          in: path
          description: |
            A digest of a manifest that has been indexed previous to this
            request.
          required: true
          schema:
            $ref: '#/components/schemas/Digest'
      responses:
        201:
          description: VulnerabilityReport Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VulnerabilityReport'
        400:
          $ref: '#/components/responses/BadRequest'
        404:
          $ref: '#/components/responses/NotFound'
        405:
          $ref: '#/components/responses/MethodNotAllowed'
        500:
          $ref: '#/components/responses/InternalServerError'
  indexer/api/v1/index_state:
    get:
      tags:
        - Indexer
      operationId: IndexState
      summary: Report the indexer's internal configuration and 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.
      responses:
        200:
          description: Indexer State
          headers:
            Etag:
              description: 'Entity Tag'
              schema: {type: string}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/State'
        304:
          description: Indexer State Unchanged

components:
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    MethodNotAllowed:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  examples:
    Environment:
      value:
        package_db: "var/lib/dpkg/status"
        introduced_in: |-
          sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a
        distribution_id: "1"

    Vulnerability:
      value:
        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"

    Distribution:
      value:
        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"

    Package:
      value:
        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

    VulnSummary:
      value:
        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: ""
          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: ""

  schemas:
    Page:
      title: Page
      description: |
        A page object indicating to the client how to retrieve multiple pages of
        a particular entity.
      properties:
        size:
          description: "The maximum number of elements in a page"
          type: int
          example: 1
        next:
          description: "The next id to submit to the api to continue paging"
          type: string
          example: "1b4d0db2-e757-4150-bbbb-543658144205"

    PagedNotifications:
      title: PagedNotifications
      type: object
      description: "A page object followed by a list of notifications"
      properties:
        page:
          description: |
            A page object informing the client the next page to retrieve.
            If page.next becomes "-1" the client should stop paging.
          type: object
          example:
            size: 100
            next: "1b4d0db2-e757-4150-bbbb-543658144205"
        notifications:
          description: "A list of notifications within this page"
          type: array
          items:
            $ref: '#/components/schemas/Notification'

    Callback:
      title: Callback
      type: object
      description: "A callback for clients to retrieve notifications"
      properties:
        notification_id:
          description: "the unique identifier for this set of notifications"
          type: string
          example: "269886f3-0146-4f08-9bf7-cb1138d48643"
        callback:
          description: "the url where notifications can be retrieved"
          type: string
          example: |-
            http://clair-notifier/notifier/api/v1/notifications/269886f3-0146-4f08-9bf7-cb1138d48643

    VulnSummary:
      title: VulnSummary
      type: object
      description: "A summary of a vulnerability"
      properties:
        name:
          description: "the vulnerability name"
          type: string
          example: "CVE-2009-5155"
        fixed_in_version:
          description: |
            The version which the vulnerability is fixed in. Empty if not fixed.
          type: string
          example: "v0.0.1"
        links:
          description: "links to external information about vulnerability"
          type: string
          example: "http://link-to-advisory"
        description:
          description: "the vulnerability name"
          type: string
          example: |
            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:
          description: |
            A well defined set of severity strings guaranteed to be present.
          type: string
          enum: [Unknown, Negligible, Low, Medium, High, Critical, Defcon1]
        package:
          $ref: '#/components/schemas/Package'
        distribution:
          $ref: '#/components/schemas/Distribution'
        repository:
          $ref: '#/components/schemas/Repository'

    Notification:
      title: Notification
      type: object
      description: |
        A notification expressing a change in a manifest affected by a
        vulnerability.
      properties:
        id:
          description: "a unique identifier for this notification"
          type: string
          example: "5e4b387e-88d3-4364-86fd-063447a6fad2"
        manifest:
          description: |
            The hash of the manifest affected by the provided vulnerability.
          type: string
          example: |-
            sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a
        reason:
          description: "the reason for the notifcation, [added | removed]"
          type: string
          example: "added"
        vulnerability:
          $ref: '#/components/schemas/VulnSummary'

    Environment:
      title: Environment
      type: object
      description: "The environment a particular package was discovered in."
      properties:
        package_db:
          description: |
            The filesystem path or unique identifier of a package database.
          type: string
          example: "var/lib/dpkg/status"
        introduced_in:
          $ref: '#/components/schemas/Digest'
        distribution_id:
          description: |
            The distribution ID found in an associated IndexReport or
            VulnerabilityReport.
          type: string
          example: "1"
      required:
        - package_db
        - introduced_in
        - distribution_id

    IndexReport:
      title: IndexReport
      type: object
      description: |
        A report of the Index process for a particular manifest. A
        client's usage of this is largely information. Clair uses this
        report for matching Vulnerabilities.
      properties:
        manifest_hash:
          $ref: '#/components/schemas/Digest'
        state:
          description: "The current state of the index operation"
          type: string
          example: "IndexFinished"
        packages:
          type: object
          description: "A map of Package objects indexed by Package.id"
          example:
            "10":
              $ref: '#/components/examples/Package/value'
          additionalProperties:
            $ref: '#/components/schemas/Package'
        distributions:
          type: object
          description: |
            A map of Distribution objects keyed by their Distribution.id
            discovered in the manifest.
          example:
            "1":
              $ref: '#/components/examples/Distribution/value'
          additionalProperties:
            $ref: '#/components/schemas/Distribution'
        environments:
          type: object
          description: |
            A map of lists containing Environment objects keyed by the
            associated Package.id.
          example:
            "10":
              # swagger bug does not allow inline reference here -_-
              # - $ref: '#/components/examples/Environment/value'
              - package_db: "var/lib/dpkg/status"
                introduced_in: |-
                  sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a
                distribution_id: "1"

          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/Environment'
        success:
          type: boolean
          description: "A bool indicating succcessful index"
          example: true
        err:
          type: string
          description: "An error message on event of unsuccessful index"
          example: ""
      required:
        - manifest_hash
        - state
        - packages
        - distributions
        - environments
        - success
        - err

    VulnerabilityReport:
      title: VulnerabilityReport
      type: object
      description: |
        A report expressing discovered packages, package environments,
        and package vulnerabilities within a Manifest.
      properties:
        manifest_hash:
          $ref: '#/components/schemas/Digest'
        packages:
          type: object
          description: "A map of Package objects indexed by Package.id"
          example:
            "10":
              $ref: '#/components/examples/Package/value'
          additionalProperties:
            $ref: '#/components/schemas/Package'
        distributions:
          type: object
          description: |
            A map of Distribution objects indexed by Distribution.id.
          example:
            "1":
              $ref: '#/components/examples/Distribution/value'
          additionalProperties:
            $ref: '#/components/schemas/Distribution'
        environments:
          type: object
          description: "A mapping of Environment lists indexed by Package.id"
          example:
            "10":
              # swagger bug does not allow inline reference here -_-
              # - $ref: '#/components/examples/Environment/value'
              - package_db: "var/lib/dpkg/status"
                introduced_in: |-
                  sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a
                distribution_id: "1"
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/Environment'
        vulnerabilities:
          description: "A map of Vulnerabilities indexed by Vulnerability.id"
          type: object
          example:
            "356835":
              $ref: '#/components/examples/Vulnerability/value'
          additionalProperties:
            $ref: '#/components/schemas/Vulnerability'
        package_vulnerabilities:
          description: |
            A mapping of Vulnerability.id lists indexed by Package.id.
          example:
            "10":
              - "356835"
          additionalProperties:
            type: array
            items:
              type: string
      required:
        - manifest_hash
        - packages
        - distributions
        - environments
        - vulnerabilities
        - package_vulnerabilities

    Vulnerability:
      title: Vulnerability
      type: object
      description: "A unique vulnerability indexed by Clair"
      example:
        $ref: '#/components/examples/Vulnerability/value'
      properties:
        id:
          description: "A unique ID representing this vulnerability."
          type: string
        updater:
          description: "A unique ID representing this vulnerability."
          type: string
        name:
          description: "Name of this specific vulnerability."
          type: string
        description:
          description: "A description of this specific vulnerability."
          type: string
        links:
          description: |
            A space separate list of links to any external information.
          type: string
        severity:
          description: |
            A severity keyword taken verbatim from the vulnerability source.
          type: string
        normalized_severity:
          description: |
            A well defined set of severity strings guaranteed to be present.
          type: string
          enum: [Unknown, Negligible, Low, Medium, High, Critical, Defcon1]
        package:
          $ref: '#/components/schemas/Package'
        distribution:
          $ref: '#/components/schemas/Distribution'
        repository:
          $ref: '#/components/schemas/Repository'
        issued:
          description: |
            The timestamp in which the vulnerability was issued
          type: string
        range:
          description: |
            The range of package versions affected by this vulnerability.
          type: string
        fixed_in_version:
          description: "A unique ID representing this vulnerability."
          type: string
      required:
        - id
        - updater
        - name
        - description
        - links
        - severity
        - normalized_severity
        - fixed_in_version

    Distribution:
      title: Distribution
      type: object
      description: |
        An indexed distribution discovered in a layer. See
        https://www.freedesktop.org/software/systemd/man/os-release.html
        for explanations and example of fields.
      example:
        $ref: '#/components/examples/Distribution/value'
      properties:
        id:
          description: "A unique ID representing this distribution"
          type: string
        did:
          type: string
        name:
          type: string
        version:
          type: string
        version_code_name:
          type: string
        version_id:
          type: string
        arch:
          type: string
        cpe:
          type: string
        pretty_name:
          type: string
      required:
        - id
        - did
        - name
        - version
        - version_code_name
        - version_id
        - arch
        - cpe
        - pretty_name

    SourcePackage:
      title: SourcePackage
      type: object
      description: "A source package affiliated with a Package"
      example:
        $ref: '#/components/examples/Package/value'
      properties:
        id:
          description: "A unique ID representing this package"
          type: string
        name:
          description: "Name of the Package"
          type: string
        version:
          description: "Version of the Package"
          type: string
        kind:
          description: "Kind of package. Source | Binary"
          type: string
        source:
          type: string
        normalized_version:
          $ref: '#/components/schemas/Version'
        arch:
          type: string
        module:
          type: string
        cpe:
          description: "A CPE identifying the package"
          type: string
      required:
        - id
        - name
        - version

    Package:
      title: Package
      type: object
      description: "A package discovered by indexing a Manifest"
      example:
        $ref: '#/components/examples/Package/value'
      properties:
        id:
          description: "A unique ID representing this package"
          type: string
        name:
          description: "Name of the Package"
          type: string
        version:
          description: "Version of the Package"
          type: string
        kind:
          description: "Kind of package. Source | Binary"
          type: string
        source:
          $ref: '#/components/schemas/SourcePackage'
        normalized_version:
          $ref: '#/components/schemas/Version'
        arch:
          description: "The package's target system architecture"
          type: string
        module:
          description: "A module further defining a namespace for a package"
          type: string
        cpe:
          description: "A CPE identifying the package"
          type: string
      required:
        - id
        - name
        - version

    Repository:
      title: Repository
      type: object
      description: "A package repository"
      properties:
        id:
          type: string
        name:
          type: string
        key:
          type: string
        uri:
          type: string
        cpe:
          type: string

    Version:
      title: Version
      type: string
      description: |
        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.
      example: |-
        pep440:0.0.0.0.0.0.0.0.0

    Manifest:
      title: Manifest
      type: object
      description: |
        A Manifest representing a container. The 'layers' array must
        preserve the original container's layer order for accurate usage.
      properties:
        hash:
          $ref: '#/components/schemas/Digest'
        layers:
          type: array
          items:
            $ref: '#/components/schemas/Layer'
      required:
        - hash
        - layers

    Layer:
      title: Layer
      type: object
      description: "A Layer within a Manifest and where Clair may retrieve it."
      properties:
        hash:
          $ref: '#/components/schemas/Digest'
        uri:
          type: string
          description: |
            A URI describing where the layer may be found. Implementations
            MUST support http(s) schemes and MAY support additional
            schemes.
          example: |
            https://storage.example.com/blob/2f077db56abccc19f16f140f629ae98e904b4b7d563957a7fc319bd11b82ba36
        headers:
          type: object
          description: |
            map of arrays of header values keyed by header
            value. e.g. map[string][]string
          additionalProperties:
            type: array
            items:
              type: string
      required:
        - hash
        - uri
        - headers

    Error:
      title: Error
      type: object
      description: "A general error schema returned when status is not 200 OK"
      properties:
        code:
          type: string
          description: "a code for this particular error"
        message:
          type: string
          description: "a message with further detail"

    State:
      title: State
      type: object
      description: an opaque identifier
      example:
        state: "aae368a064d7c5a433d0bf2c4f5554cc"
      properties:
        state:
          type: string
          description: an opaque identifier
      required:
        - state

    Digest:
      title: Digest
      type: string
      description: |
        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.
      example: |-
        sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3