manager.admin.spec.yaml

openapi: "3.0.0"

info:
  title: Vulnerability Engine Manager Admin
  version: {{ app_version }}

paths:
  /version:
    get:
      summary: Application version
      description: Get application version.
      operationId: manager.version_handler.GetVersion.get
      x-methodName: getVersion
      responses:
        200:
          description: Application version.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/VersionOut'

  /systems/missing_in_inventory:
    get:
      summary: Get count of systems in system_platform table but missing in inventory.
      description: Get count of systems in system_platform table but missing in inventory. Admin interface, available only to admin users.
      operationId: manager.admin_handler.GetMissingInInventory.get
      x-methodName: getMissingInInventory
      security:
        - ApiKeyAuthAdmin: []
      responses:
        200:
          description: Count of systems missing in inventory.
    delete:
      summary: Delete systems from system_platform table missing in inventory.
      description: Delete systems from system_platform table missing in inventory. Admin interface, available only to admin users.
      operationId: manager.admin_handler.DeleteMissingInInventory.delete
      x-methodName: deleteMissingInInventory
      security:
        - ApiKeyAuthAdmin: []
      responses:
        200:
          description: Systems deleted.
        503:
          description: Service is running in read-only mode.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'

  /taskomatic/run/{job_name}:
    put:
      summary: Trigger immediate run of taskomatic job with given name.
      description: Trigger immediate run of taskomatic job with given name. Admin interface, available only to admin users.
      operationId: manager.admin_handler.TaskomaticRun.put
      x-methodName: taskomaticRun
      security:
        - ApiKeyAuthAdmin: []
      parameters:
        - in: path
          name: job_name
          description: Job name.
          required: true
          schema:
            type: string
          example: stale_systems
      responses:
        200:
          description: Job run triggered.
        404:
          description: Job with given name not found.

  /cves/{cve_id}:
    delete:
      summary: Delete CVE with given name.
      description: Delete CVE with given name. Deletes this CVE from all associated systems. Admin interface, available only to admin users.
      operationId: manager.admin_handler.DeleteCve.delete
      x-methodName: deleteCve
      security:
        - ApiKeyAuthAdmin: []
      parameters:
        - in: path
          name: cve_id
          description: CVE name.
          required: true
          schema:
            type: string
          example: CVE-2020-1111
      responses:
        200:
          description: CVE deleted.

  /content_version:
    get:
      summary: Get content revisions.
      description: Get revisions of content imported to Vulnerability application.
      operationId: manager.admin_handler.GetContentVersion.get
      x-methodName: getContentVersion
      security:
        - ApiKeyAuthAdmin: []
      responses:
        200:
          description: Content revisions.
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  insights_content_vulnerability:
                    type: string
                    example: 5ec1896cefc6d3de960a80742fe513091e065cfd
                    description: SHA of latest commit imported for content repository.
                  insights_content_vulnerability_repo:
                    type: string
                    example: https://github.com/RedHatInsights/insights-content-vulnerability.git
                    description: URL of content repository.
                  insights_playbooks:
                    type: string
                    example: c702f6358a8e49590308ee005a175e7378852c7b
                    description: SHA of latest commit imported for playbooks repository.
                  insights_playbooks_repo:
                    type: string
                    example: https://github.com/RedHatInsights/insights-playbooks.git
                    description: URL of playbooks repository.

  /database/queries:
    get:
      summary: Get list of running queries.
      description: Get statistics about active running queries, defined by threshold.
      operationId: manager.admin_handler.GetQueries.get
      x-methodName: getQueries
      security:
        - ApiKeyAuthAdmin: []
      parameters:
        - in: query
          name: ms_threshold
          schema:
            type: number
          description: Threshold in ms for the minimum running query.
        - in: query
          name: username
          schema:
            type: string
          description: Search for queries by author
        - in: query
          name: wait_event_type
          schema:
            type: string
          description: Filter queries by event wait event type
          example: Lock
      responses:
        200:
          description: Queries result.
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  queries:
                    type: array
                    items:
                      type: object
                      properties:
                        pid:
                          type: integer
                          example: 40277
                          description: PID of the DB server process
                        db_name:
                          type: string
                          example: vulnerability
                          description: Name of the database where process is connected
                        username:
                          type: string
                          example: ve_db_user_listener
                          description: Author of the query
                        app_name:
                          type: string
                          example: psql
                          description: Name of the application that is connected
                        query_start:
                          type: string
                          example: 2021-06-10 11:03:18.824233+00
                          description: Timestamp when query execution started
                        running_time:
                          type: string
                          example: 0:00:02.644451
                          description: Duration of query execution
                        wait_event_type:
                          type: string
                          example: LWLock
                          description: Signifies the type of waiting event
                          nullable: true
                        wait_event:
                          type: string
                          example: ControlFileLock
                          description: Wait event name in backend
                          nullable: true
                        query:
                          type: string
                          example: select system_profile->'operating_system' from inventory.host where system_profile->'operating_system' is not null;
                          description: Actual running query

  /database/query/{pid}:
    delete:
      summary: Kill a query execution by PID.
      description: Kill query by provided PID.
      operationId: manager.admin_handler.KillQuery.delete
      x-methodName: killQuery
      security:
        - ApiKeyAuthAdmin: []
      parameters:
        - in: path
          name: pid
          schema:
            type: integer
          description: PID running the query
          required: true
      responses:
        200:
          description: Query killed

  /database/vacuum/table/{table_name}:
    get:
      summary: Start vacuum on table.
      description: Starts a pg_repack process to vacuum a table.
      operationId: manager.admin_handler.VacuumTable.get
      x-methodName: vacuumTable
      security:
        - ApiKeyAuthAdmin: []
      parameters:
        - in: path
          name: table_name
          schema:
            type: string
          description: Name of the table NEEDS to be with schema name.
          example: public.system_platform
          required: True
        - in: query
          name: only_indexes
          schema:
            type: boolean
          description: If true, vacuums only indexes of table.
      responses:
        200:
          description: Vacuuming started.

  /database/vacuum/user/{rh_account_id}:
    get:
      summary: Vacuum system_vulnerabilities table occupied by user.
      description: Starts a pg_repack process to partitioned sv tables vacuum which has data by given user id.
      operationId: manager.admin_handler.VacuumUser.get
      x-methodName: vacuumUser
      security:
        - ApiKeyAuthAdmin: []
      parameters:
        - $ref: '#/components/parameters/rh_account_id'
      responses:
        200:
          description: Vacuuming started.

  /database/bloat/table/{table_name}:
    get:
      summary: Get bloat statistics for given database table.
      description: Gets the bloat statistics for the database table.
      operationId: manager.admin_handler.GetBloat.get
      x-methodName: getTableBloat
      security:
        - ApiKeyAuthAdmin: []
      parameters:
        - in: path
          name: table_name
          schema:
            type: string
          description: Name of the table in schema.
          required: True
      responses:
        200:
          description: Bloat result.
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  table_len:
                    type: integer
                    description: Physical relation length in bytes
                    example: 8192
                  tuple_count:
                    type: integer
                    description: Number of live tuples
                    example: 19
                  tuple_len:
                    type: integer
                    description: Total length of live tuples in bytes
                    example: 3956
                  tuple_percent:
                    type: number
                    description: Percentage of live tuples
                    example: 48.29
                  dead_tuple_count:
                    type: integer
                    description: Number of dead tuples
                    example: 0
                  dead_tuple_len:
                    type: integer
                    description: Total length of dead tuples in bytes
                    example: 0
                  dead_tuple_percent:
                    type: number
                    description: Percentage of dead tuples
                    example: 0
                  free_space:
                    type: integer
                    description: Total free space in bytes
                    example: 4024
                  free_percent:
                    type: number
                    description: Percentage of free space
                    example: 49.12

  /database/bloat/user/{rh_account_id}:
    get:
      summary: Get table statistics for user.
      description: Get system_vulnerabilities table statistics for given user id.
      operationId: manager.admin_handler.GetUserBloat.get
      x-methodName: GetUserBloat
      security:
        - ApiKeyAuthAdmin: []
      parameters:
        - $ref: '#/components/parameters/rh_account_id'
      responses:
        200:
          description: Bloat results.
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  tables:
                    type: array
                    items:
                      type: object
                      properties:
                        table_name:
                          type: string
                          description: Name of the table with user info.
                          example: system_vulnerabilities_active_101
                        table_len:
                          type: integer
                          description: Physical relation length in bytes
                          example: 8192
                        tuple_count:
                          type: integer
                          description: Number of live tuples
                          example: 19
                        tuple_len:
                          type: integer
                          description: Total length of live tuples in bytes
                          example: 3956
                        tuple_percent:
                          type: number
                          description: Percentage of live tuples
                          example: 48.29
                        dead_tuple_count:
                          type: integer
                          description: Number of dead tuples
                          example: 0
                        dead_tuple_len:
                          type: integer
                          description: Total length of dead tuples in bytes
                          example: 0
                        dead_tuple_percent:
                          type: number
                          description: Percentage of dead tuples
                          example: 0
                        free_space:
                          type: integer
                          description: Total free space in bytes
                          example: 4024
                        free_percent:
                          type: number
                          description: Percentage of free space
                          example: 49.12

  /database/systems/{inventory_id}:
    delete:
      summary: Delete system.
      description: Deletes system from database.
      operationId: manager.admin_handler.DeleteSystem.delete
      x-methodName: deleteSystem
      security:
        - ApiKeyAuthAdmin: []
      responses:
        200:
          description: System has been deleted.
        404:
          description: System has not been found in the database.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
      parameters:
        - $ref: '#/components/parameters/inventory_id'

  /announcement:
    delete:
      summary: Remove the announcement.
      description: Removes the announcement.
      operationId: manager.admin_handler.DeleteAnnouncement.delete
      x-methodName: DeleteAnnouncement
      security:
        - ApiKeyAuthAdmin: []
      responses:
        200:
          description: Delete announcement.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/AnnouncementDeleteOut'

    put:
      summary: Set new announcement.
      description: Sets new announcement.
      operationId: manager.admin_handler.SetAnnouncement.put
      x-methodName: SetAnnouncement
      security:
        - ApiKeyAuthAdmin: []
      requestBody:
        description: List of CVEs to provide info about.
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/AnnouncementIn'
              x-body-name: data
      responses:
        200:
          description: New announcement.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/AnnouncementPutOut'

  /notifications/{org_id}:
    delete:
      summary: Remove remembered sent notifications for account
      description: Remove remembered cve-customer_id tuples from notified_accounts table
      operationId: manager.admin_handler.DeleteNotifications.delete
      x-methodName: DeleteNotifications
      security:
        - ApiKeyAuthAdmin: []
      parameters:
        - $ref: '#/components/parameters/org_id'
      responses:
        200:
          description: Notifications deleted

  /rule/{rule_id}/reports/:
    get:
      summary: List all the reports for the given rule.
      description: This is used by the content preview internal application to help content editors see how their content looks with the most recent rule reports.
      operationId: manager.admin_handler.RuleReports.get
      x-methodName: RuleReports
      security:
        - ApiKeyAuthAdmin: []
      parameters:
        - $ref: '#/components/parameters/rule_id'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/data_format'
      responses:
        200:
          description: "data"
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/RuleReportsOut'

  /rule/{rule_id}/err_key:
    delete:
      summary: Delete error key for given rule from database.
      description: Completely deletes rules error key and all system vulnerabilities matched by this rule error key.
      operationId: manager.admin_handler.RuleErrorKey.delete
      x-methodName: DeleteRuleErrorKey
      security:
        - ApiKeyAuthAdmin: []
      parameters:
        - $ref: '#/components/parameters/rule_id'
      responses:
        200:
          description: "data"
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/RuleErrKeyDeleteOut'
        400:
          description: Rule does not exist

  /system_vulnerabilities/inactive:
    delete:
      summary: Truncate system_vulnerabilities_inactive partition
      description: Truncates unused system_vulnerabilities_inactive partition.
      operationId: manager.admin_handler.TruncateInactivePartition.delete
      x-methodName: TruncateInactivePartition
      security:
        - ApiKeyAuthAdmin: []
      responses:
        200:
          description: Partition was truncated

  /recalc/accounts:
    put:
      summary: Trigger recalc of all systems in specified account org_ids.
      description: Trigger recalc of all systems in specified account org_ids. Admin interface, available only to admin users.
      operationId: manager.admin_handler.RecalcAccounts.put
      x-methodName: recalcAccounts
      security:
        - ApiKeyAuthAdmin: []
      requestBody:
        description: Account org_ids to be re-evaluated.
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                org_ids:
                  type: array
                  items:
                    type: string
                  description: List of org_ids to be recalculated.
                  example: ['123456', '654321']
      responses:
        200:
          description: Systems from account are scheduled for recalculation.

  /recalc/systems:
    put:
      summary: Trigger recalc of specified inventory_ids.
      description: Trigger recalc of specified inventory_ids. Admin interface, available only to admin users.
      operationId: manager.admin_handler.RecalcSystems.put
      x-methodName: recalcSystems
      security:
        - ApiKeyAuthAdmin: []
      requestBody:
        description: System inventory_ids to be re-evaluated.
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                inventory_ids:
                  type: array
                  items:
                    type: string
                  description: List of inventory_ids to be recalculated.
                  example: ['INV-ID-0000-1234', 'INV-ID-0000-5678']
      responses:
        200:
          description: Systems are scheduled for recalculation.

components:
  parameters:
    inventory_id:
      in: path
      name: inventory_id
      description: Inventory ID.
      required: true
      schema:
        type: string
      example: INV-ID-0000-1234

    cve_id:
      in: path
      name: cve_id
      description: CVE id.
      required: true
      schema:
        type: string
      example: CVE-2016-0800

    account_id:
      in: path
      name: account_id
      description: Account ID of user.
      required: true
      schema:
        type: string
      example: '123456'

    org_id:
      in: path
      name: org_id
      description: Org ID of user.
      required: true
      schema:
        type: string
      example: '123456'

    rh_account_id:
      in: path
      name: rh_account_id
      schema:
        type: integer
      description: ID of the user.
      required: True

    rule_id:
      name: rule_id
      in: path
      description: "Rule ID from Insights"
      schema:
        type: string
      required: true

    limit:
      name: limit
      in: query
      description: "Number of results to return per page."
      schema:
        type: integer
        minimum: 1
        maximum: 100
      required: false


    offset:
      name: offset
      in: query
      description: "The initial index from which to return the results."
      schema:
        type: integer
      required: false

    data_format:
      in: query
      name: data_format
      description: Format of the output data, either JSON (default) or CSV.
      schema:
        type: string
        example: json

  securitySchemes:
    ApiKeyAuthAdmin:
      type: apiKey
      in: header
      name: x-rh-identity
      description: Identity header provided by Turnpike (for non-prod testing only).
      x-apikeyInfoFunc: manager.base.auth_admin

  schemas:
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              detail:
                type: string
                description: Error detail.
                example: Record not found.
              status:
                type: string
                description: String representation of HTTP status code.
                example: 404
            required:
              - detail
              - status
          minItems: 1
      required:
        - errors

    VersionOut:
      type: object
      properties:
        application_version:
          type: string
          description: Version of application.
          example: 0.1.2
        database_version:
          oneOf:
            - type: string
            - type: number
          description: Version of database schema.
          example: 1
      required:
        - application_version
        - database_version

    AnnouncementIn:
      type: object
      properties:
        message:
          type: string
          description: Announcement message.
          example: Hello from Vulnerability team :).
      required:
        - message

    AnnouncementPutOut:
      type: object
      properties:
        message:
          type: string
          description: Announcement message.
          example: Hello from Vulnerability team :).
        last_updated:
          type: string
          description: Datetime string.
          example: '2004-10-19 10:23:54+02'
      required:
        - message
        - last_updated

    AnnouncementDeleteOut:
      type: object
      properties:
        status:
          type: string
          description: Result of the deletion.
          example: OK
      required:
        - status

    RuleReportsOut:
      type: object
      properties:
        data:
          oneOf:
            - type: string
              description: CSV export of the JSON.
            - type: array
              items:
                type: object
                properties:
                  delta:
                    type: integer
                    description: "Delta"
                  details:
                    type: object
                    description: "Details"
        meta:
          $ref: '#/components/schemas/Meta'
        links:
          $ref: '#/components/schemas/Links'
      required:
        - data

    RuleErrKeyDeleteOut:
      type: object
      properties:
        deleted_playbooks:
          type: number
          description: Number of playbooks deleted, which were associated to this rule error key.
          example: 2
        deleted_system_vulnerabilities:
          type: number
          description: Number of system vulnerabilities, which were associated to this rule error key.
          example: 100
        rule_id:
          type: string
          description: Rule and error key, which got deleted.
          example: CVE_2019_11135_cpu_taa|CVE_2019_11135_CPU_TAA_KERNEL
      required:
        - deleted_playbooks
        - deleted_system_vulnerabilities
        - rule_id

    Meta:
      type: object
      properties:
        filter:
          type: string
          description: Full text filter
          example: CVE-2016-0800
          nullable: true
        limit:
          type: integer
          description: Maximum number of paginated results.
          example: 25
        offset:
          type: integer
          description: First record of paginated response.
          example: 0
        page:
          type: integer
          description: Page number of paginated response.
          example: 1
        page_size:
          type: integer
          description: Number of records per page of paginated response.
          example: 25
        pages:
          type: integer
          description: Total number of pages of paginated response.
          example: 1
        sort:
          type: string
          description: Sorting filter.
          example: -inventory_id
          nullable: true
        total_items:
          type: integer
          description: Total number of records.
          example: 37
        data_format:
          type: string
          description: Format of the output data, either JSON (default) or CSV.
          example: JSON
      required:
        - filter
        - limit
        - offset
        - page
        - page_size
        - pages
        - sort
        - total_items
        - data_format

    Links:
      type: object
      properties:
        first:
          type: string
          description: Link to first page.
          example: /api?offset=0&limit=1
        last:
          type: string
          description: Link to last page.
          example: /api?offset=7&limit=1
        next:
          type: string
          description: Link to next page.
          example: /api?offset=5&limit=1
          nullable: true
        previous:
          type: string
          description: Link to next page.
          example: /api?offset=3&limit=1
          nullable: true
      required:
        - first
        - last
        - next
        - previous