Rapid7 Vulnerability Result API

openapi: 3.2.0
info:
  description: '# Overview


    This guide documents the InsightVM Application Programming Interface (API) Version 3.'
  version: '3'
  title: InsightVM Vulnerability Result API
  contact:
    name: Rapid7
    email: support@rapid7.com
servers:
- url: https://localhost:3780/
tags:
- name: Vulnerability Result
  description: Resources and operations for retrieving vulnerability results on assessed assets.
paths:
  /api/3/assets/{id}/services/{protocol}/{port}/vulnerabilities:
    get:
      tags:
      - Vulnerability Result
      summary: Asset Service Vulnerabilities
      description: Retrieves the vulnerabilities present on a service running on an asset. A finding may be `invulnerable` if all instances on the service have exceptions applied.
      operationId: getAssetServiceVulnerabilities
      parameters:
      - name: id
        in: path
        description: The identifier of the asset.
        required: true
        schema:
          type: integer
          format: int64
      - name: protocol
        in: path
        description: The protocol of the service.
        required: true
        schema:
          type: string
          enum:
          - ip
          - icmp
          - igmp
          - ggp
          - tcp
          - pup
          - udp
          - idp
          - esp
          - nd
          - raw
      - name: port
        in: path
        description: The port of the service.
        required: true
        schema:
          type: integer
          format: int32
      - name: page
        in: query
        description: The index of the page (zero-based) to retrieve.
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: size
        in: query
        description: The number of records per page to retrieve.
        required: false
        schema:
          type: integer
          format: int32
          default: 10
      - name: sort
        in: query
        description: 'The criteria to sort the records by, in the format: `property[,ASC|DESC]`. The default sort order is ascending. Multiple sort criteria can be specified using multiple sort query parameters.'
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/PageOf_VulnerabilityFinding'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableError'
      security: []
  /api/3/assets/{id}/vulnerabilities:
    get:
      tags:
      - Vulnerability Result
      summary: Asset Vulnerabilities
      description: Retrieves all vulnerability findings on an asset. A finding may be `invulnerable` if all instances have exceptions applied.
      operationId: getAssetVulnerabilities
      parameters:
      - name: id
        in: path
        description: The identifier of the asset.
        required: true
        schema:
          type: integer
          format: int64
      - name: page
        in: query
        description: The index of the page (zero-based) to retrieve.
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: size
        in: query
        description: The number of records per page to retrieve.
        required: false
        schema:
          type: integer
          format: int32
          default: 10
      - name: sort
        in: query
        description: 'The criteria to sort the records by, in the format: `property[,ASC|DESC]`. The default sort order is ascending. Multiple sort criteria can be specified using multiple sort query parameters.'
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/PageOf_VulnerabilityFinding'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableError'
      security: []
  /api/3/assets/{id}/vulnerabilities/{vulnerabilityId}:
    get:
      tags:
      - Vulnerability Result
      summary: Asset Vulnerability
      description: Retrieves the details for a vulnerability finding on an asset.
      operationId: getAssetVulnerability
      parameters:
      - name: id
        in: path
        description: The identifier of the asset.
        required: true
        schema:
          type: integer
          format: int64
      - name: vulnerabilityId
        in: path
        description: The identifier of the vulnerability.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/VulnerabilityFinding'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableError'
      security: []
  /api/3/assets/{id}/vulnerabilities/{vulnerabilityId}/validations:
    get:
      tags:
      - Vulnerability Result
      summary: Asset Vulnerability Validations
      description: Returns all vulnerability validations for a vulnerability on an asset. The asset must be currently vulnerable to the validated vulnerable for the validation to be returned.
      operationId: getVulnerabilityValidations
      parameters:
      - name: id
        in: path
        description: The identifier of the asset.
        required: true
        schema:
          type: integer
          format: int64
      - name: vulnerabilityId
        in: path
        description: The identifier of the vulnerability.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/Resources_VulnerabilityValidationResource'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableError'
      security: []
    post:
      tags:
      - Vulnerability Result
      summary: Asset Vulnerability Validations
      description: Creates a vulnerability validation for a vulnerability on an asset. The validation signifies that the vulnerability has been confirmed exploitable by an external tool, such as Metasploit.
      operationId: createVulnerabilityValidation
      parameters:
      - name: id
        in: path
        description: The identifier of the asset.
        required: true
        schema:
          type: integer
          format: int64
      - name: vulnerabilityId
        in: path
        description: The identifier of the vulnerability.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/CreatedReference_VulnerabilityValidationID_Link'
        '400':
          description: Bad Request
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableError'
      security: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VulnerabilityValidationResource'
        description: A vulnerability validation for a vulnerability on an asset. The  validation signifies that the vulnerability has been confirmed exploitable by an external tool, such as <a target="_blank" rel="noopener noreferrer" href="https://www.metasploit.com">Metasploit</a>.
  /api/3/assets/{id}/vulnerabilities/{vulnerabilityId}/validations/{validationId}:
    get:
      tags:
      - Vulnerability Result
      summary: Asset Vulnerability Validation
      description: Returns a vulnerability validation for a vulnerability on an asset. The asset must be currently vulnerable to the validated vulnerable for the validation to be returned.
      operationId: getVulnerabilityValidation
      parameters:
      - name: id
        in: path
        description: The identifier of the asset.
        required: true
        schema:
          type: integer
          format: int64
      - name: vulnerabilityId
        in: path
        description: The identifier of the vulnerability.
        required: true
        schema:
          type: string
      - name: validationId
        in: path
        description: The identifier of the vulnerability validation.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/VulnerabilityValidationResource'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableError'
      security: []
    delete:
      tags:
      - Vulnerability Result
      summary: Asset Vulnerability Validation
      description: Removes a vulnerability validation for a vulnerability from an asset.
      operationId: deleteVulnerabilityValidation
      parameters:
      - name: id
        in: path
        description: The identifier of the asset.
        required: true
        schema:
          type: integer
          format: int64
      - name: vulnerabilityId
        in: path
        description: The identifier of the vulnerability.
        required: true
        schema:
          type: string
      - name: validationId
        in: path
        description: The identifier of the vulnerability validation.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/Links'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableError'
      security: []
components:
  schemas:
    InternalServerError:
      type: object
      required:
      - status
      properties:
        links:
          type: array
          description: Hypermedia links to corresponding or related resources.
          items:
            $ref: '#/components/schemas/Link'
        message:
          type: string
          example: An error has occurred.
          description: The messages indicating the cause or reason for failure.
        status:
          type: string
          example: '500'
          description: The HTTP status code for the error (same as in the HTTP response).
          enum:
          - '500'
      description: ''
    Link:
      type: object
      properties:
        href:
          type: string
          example: https://hostname:3780/api/3/...
          description: 'A hypertext reference, which is either a URI (see <a target="_blank" rel="noopener noreferrer" href="https://tools.ietf.org/html/rfc3986">RFC 3986</a>) or URI template (see <a target="_blank" rel="noopener noreferrer" href="https://tools.ietf.org/html/rfc6570">RFC 6570</a>). '
        rel:
          type: string
          example: self
          description: The link relation type. This value is one from the <a target="_blank" rel="noopener noreferrer" href="https://tools.ietf.org/html/rfc5988#section-6.2">Link Relation Type Registry</a> or is the type of resource being linked to.
      description: ''
    UnauthorizedError:
      type: object
      required:
      - status
      properties:
        links:
          type: array
          description: Hypermedia links to corresponding or related resources.
          items:
            $ref: '#/components/schemas/Link'
        message:
          type: string
          example: An error has occurred.
          description: The messages indicating the cause or reason for failure.
        status:
          type: string
          example: '401'
          description: The HTTP status code for the error (same as in the HTTP response).
          enum:
          - '401'
      description: ''
    CreatedReference_VulnerabilityValidationID_Link:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
          description: The identifier of the resource created.
        links:
          type: array
          description: Hypermedia links to corresponding or related resources.
          items:
            $ref: '#/components/schemas/Link'
      description: ''
    PageInfo:
      type: object
      properties:
        number:
          type: integer
          format: int64
          example: 6
          description: The index (zero-based) of the current page returned.
        size:
          type: integer
          format: int64
          example: 10
          description: The maximum size of the page returned.
        totalPages:
          type: integer
          format: int64
          example: 13
          description: The total number of pages available.
        totalResources:
          type: integer
          format: int64
          example: 123
          description: The total number of resources available across all pages.
      description: ''
    NotFoundError:
      type: object
      required:
      - status
      properties:
        links:
          type: array
          description: Hypermedia links to corresponding or related resources.
          items:
            $ref: '#/components/schemas/Link'
        message:
          type: string
          example: An error has occurred.
          description: The messages indicating the cause or reason for failure.
        status:
          type: string
          example: '404'
          description: The HTTP status code for the error (same as in the HTTP response).
          enum:
          - '404'
      description: ''
    BadRequestError:
      type: object
      required:
      - status
      properties:
        links:
          type: array
          description: Hypermedia links to corresponding or related resources.
          items:
            $ref: '#/components/schemas/Link'
        message:
          type: string
          example: An error has occurred.
          description: The messages indicating the cause or reason for failure.
        status:
          type: string
          example: '400'
          description: The HTTP status code for the error (same as in the HTTP response).
          enum:
          - '400'
      description: ''
    AssessmentResult:
      type: object
      required:
      - status
      properties:
        checkId:
          type: string
          example: ssh-openssh-x11uselocalhost-x11-forwarding-session-hijack
          description: The identifier of the vulnerability check.
        exceptions:
          type: array
          description: If the result is vulnerable with exceptions applied, the identifier(s) of the exceptions actively applied to the result.
          items:
            type: integer
            format: int32
        key:
          type: string
          example: ''
          description: An additional discriminating key used to uniquely identify between multiple instances of results on the same finding.
        links:
          type: array
          description: Hypermedia links to corresponding or related resources.
          readOnly: true
          items:
            $ref: '#/components/schemas/Link'
        port:
          type: integer
          format: int32
          example: 22
          description: The port of the service the result was discovered on.
        proof:
          type: string
          example: <p><p>OpenBSD OpenSSH 4.3 on Linux</p></p>
          description: The proof explaining why the result was found vulnerable. The proof may container embedded HTML formatting markup.
        protocol:
          type: string
          example: tcp
          description: The protocol of the service the result was discovered on.
          enum:
          - ip
          - icmp
          - igmp
          - ggp
          - tcp
          - pup
          - udp
          - idp
          - esp
          - nd
          - raw
        since:
          type: string
          example: '2017-08-09T11:32:33.658Z'
          description: The date and time the result was first recorded, in the ISO8601 format. If the result changes status this value is the date and time of the status change.
        status:
          type: string
          example: vulnerable-version
          description: The status of the vulnerability check result.
          enum:
          - unknown
          - not-vulnerable
          - vulnerable
          - vulnerable-version
          - vulnerable-potential
          - vulnerable-with-exception-applied
          - vulnerable-version-with-exception-applied
          - vulnerable-potential-with-exception-applied
      description: ''
    PageOf_VulnerabilityFinding:
      type: object
      properties:
        links:
          type: array
          description: Hypermedia links to corresponding or related resources.
          items:
            $ref: '#/components/schemas/Link'
        page:
          example: ''
          description: The details of pagination indicating which page was returned, and how the remaining pages can be retrieved.
          $ref: '#/components/schemas/PageInfo'
        resources:
          type: array
          description: The page of resources returned.
          items:
            $ref: '#/components/schemas/VulnerabilityFinding'
      description: ''
    Links:
      type: object
      properties:
        links:
          type: array
          description: Hypermedia links to corresponding or related resources.
          items:
            $ref: '#/components/schemas/Link'
      description: ''
    VulnerabilityFinding:
      type: object
      required:
      - id
      - instances
      - status
      properties:
        id:
          type: string
          example: ssh-openssh-x11uselocalhost-x11-forwarding-session-hijack
          description: The identifier of the vulnerability.
        instances:
          type: integer
          format: int32
          example: 1
          description: The number of vulnerable occurrences of the vulnerability. This does not include `invulnerable` instances.
        links:
          type: array
          description: Hypermedia links to corresponding or related resources.
          readOnly: true
          items:
            $ref: '#/components/schemas/Link'
        results:
          type: array
          description: The vulnerability check results for the finding. Multiple instances may be present if one or more checks fired, or a check has multiple independent results.
          items:
            $ref: '#/components/schemas/AssessmentResult'
        since:
          type: string
          example: '2017-08-09T11:32:33.658Z'
          description: The date and time the finding was was first recorded, in the ISO8601 format. If the result changes status this value is the date and time of the status change.
        status:
          type: string
          example: vulnerable
          description: The status of the finding.
          enum:
          - vulnerable
          - invulnerable
          - no-results
      description: ''
    VulnerabilityValidationSource:
      type: object
      properties:
        key:
          type: string
          example: exploit/windows/iis/iis_webdav_scstoragepathfromurl
          description: The identifier or name of the exploit that was used to validate the vulnerability.
        name:
          type: string
          example: metasploit
          description: The name of the source used to validate the vulnerability.
          enum:
          - metasploit
          - other
      description: ''
    VulnerabilityValidationResource:
      type: object
      properties:
        date:
          type: string
          example: '2017-12-21T04:54:32.314Z'
          description: The date and time the vulnerability was validated, in the ISO8601 format.
        id:
          type: integer
          format: int64
          example: 46
          description: The identifier of the vulnerability validation.
          readOnly: true
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        source:
          example: ''
          description: The source used to validate the vulnerability.
          $ref: '#/components/schemas/VulnerabilityValidationSource'
      description: ''
    Resources_VulnerabilityValidationResource:
      type: object
      properties:
        links:
          type: array
          description: Hypermedia links to corresponding or related resources.
          items:
            $ref: '#/components/schemas/Link'
        resources:
          type: array
          description: The resources returned.
          items:
            $ref: '#/components/schemas/VulnerabilityValidationResource'
      description: ''
    ServiceUnavailableError:
      type: object
      required:
      - status
      properties:
        links:
          type: array
          description: Hypermedia links to corresponding or related resources.
          items:
            $ref: '#/components/schemas/Link'
        message:
          type: string
          example: An error has occurred.
          description: The messages indicating the cause or reason for failure.
        status:
          type: string
          example: '503'
          description: The HTTP status code for the error (same as in the HTTP response).
          enum:
          - '503'
      description: ''
  securitySchemes:
    Basic:
      type: http
      scheme: basic