Proposal: Pluggable Image Vulnerability Scanning

proposals/assets/pluggable-image-vulnerability-scanning/harbor-api-delta-scanner-registry-mgmt.yaml

@@ -0,0 +1,209 @@
+swagger: '2.0'
+info:
+  title: Harbor API (DELTA)
+  version: "1.10"
+  description: |
+    Paths added to Harbor API in order to support Scanner Registry management.
+host: localhost
+paths:
+  /scanner/registrations:
+    get:
+      summary: List scanner registrations
+      description: |
+        Returns a list of currently configured scanner registrations.
+      tags:
+        - Scanners
+      responses:
+        '200':
+          description: A list of scanner registrations.
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/ScannerRegistration'
+    post:
+      summary: Create a scanner registration
+      description: |
+        Creats a new scanner registration with the given data.
+      tags:
+        - Scanners
+      parameters:
+        - name: registration
+          in: body
+          description: A scanner registration to be created.
+          required: true
+          schema:
+            $ref: '#/definitions/ScannerRegistrationReq'
+      responses:
+        '201':
+          description: Created successfully
+  /scanner/registrations/ping:
+    post:
+      summary: Tests scanner registration settings
+      description: |
+        Pings Scanner Adapter to test EndpointURL and Authorization settings.
+      tags:
+        - Scanners
+      parameters:
+        - name: settings
+          in: body
+          description: A scanner registration settings to be tested.
+          required: true
+          schema:
+            $ref: '#/definitions/ScannerRegistrationSettings'
+      responses:
+        '200':
+          description: Test succeeded
+  /scanner/registrations/{registration_id}:
+    get:
+      summary: Get a scanner registration details
+      description: |
+        Retruns the details of the specified scanner registration.
+      tags:
+        - Scanners
+      parameters:
+        - name: registration_id
+          in: path
+          description: The scanner registration identifer.
+          required: true
+          type: integer
+          format: int64
+      responses:
+        '200':
+          description: The details of the scanner registration.
+          schema:
+            $ref: '#/definitions/ScannerRegistration'
+    put:
+      summary: Update a scanner registration
+      description: |
+        Updates the specified scanner registration.
+      tags:
+        - Scanners
+      parameters:
+        - name: registration_id
+          in: path
+          description: The scanner registration identifier.
+          required: true
+          type: integer
+          format: int64
+        - name: registration
+          in: body
+          required: true
+          description: A scanner registraiton to be updated.
+          schema:
+            $ref: '#/definitions/ScannerRegistrationReq'
+      responses:
+        '200':
+          description: Updated successfully
+    delete:
+      summary: Delete a scanner registration
+      description: |
+        Deletes the specified scanner registration.
+      tags:
+        - Scanners
+      parameters:
+        - name: registration_id
+          in: path
+          description: The scanner registration identifier.
+          required: true
+          type: integer
+          format: int64
+      responses:
+        '201':
+          description: Deleted successfully
+  /scanner/registrations/{registration_id}/default:
+    put:
+      summary: Update a scanner registration to change it to the default one
+      description: |
+        Marks the specified scanner registration as default.
+      tags:
+        - Scanners
+      parameters:
+        - name: registration_id
+          in: path
+          required: true
+          description: The scanner registration identifier.
+          type: integer
+          format: int64
+        - name: payload
+          in: body
+          required: true
+          schema:
+            $ref: '#/definitions/IsDefault'
+      responses:
+        '201':
+          description: OK
+
+definitions:
+  ScannerRegistration:
+    type: object
+    description: |
+      Registration represents a named configuration for invoking a scanner via its adapter.
+    properties:
+      id:
+        type: integer
+        format: int64
+        description: The unique identifier of this registration.
+      name:
+        type: string
+        example: MicroScanner
+        description: The name of this registration.
+      description:
+        type: string
+        description: An optional description of this registration.
+        example: |
+          A free-to-use tool that scans container images for package vulnerabilities.
+      endpoint_url:
+        type: string
+        format: url
+        description: A base URL of the Scanner Adapter
+        example: http://harbor-scanner-microscanner:8080
+      authorization:
+        type: string
+        description: |
+          An optional value of the HTTP Authorization header sent with each request to the Scanner Adapter API.
+        example: "Bearer: JWTTOKENGOESHERE"
+      is_default:
+        type: boolean
+        default: false
+        description: A flag indicating whether this registration is the default one.
+  ScannerRegistrationReq:
+    type: object
+    properties:
+      name:
+        type: string
+        description: The name of this registration
+        example: MicroScanner
+      description:
+        type: string
+        description: An optional description of this registration.
+        example: |
+          A free-to-use tool that scans container images for package vulnerabilities.
+      endpoint_url:
+        type: string
+        format: url
+        description: A base URL of the Scanner Adapter.
+        example: http://harbor-scanner-microscanner:8080
+      authorization:
+        type: string
+        description: |
+          An optional value of the HTTP Authorization header sent with each request to the Scanner Adapter API.
+        example: "Bearer: JWTTOKENGOESHERE"
+  ScannerRegistrationSettings:
+    type: object
+    properties:
+      endpoint_url:
+        type: string
+        format: url
+        description: A base URL of the Scanner Adapter.
+        example: http://harbor-scanner-microscanner:8080
+      authorization:
+        type: string
+        description: |
+          An optional value of the HTTP Authorization header sent with each request to the Scanner Adapter API.
+        example: "Bearer: JWTTOKENGOESHERE"
+  IsDefault:
+    type: object
+    properties:
+      is_default:
+        type: boolean
+        description: A flag indicating whether a scanner registration is default.