Iru Vulnerability Management API

openapi: 3.2.0
info:
  title: Iru Endpoint Management Vulnerability Management API
  description: "# Welcome to the Iru Endpoint Management API Documentation\n\n**Note:** Kandji is in the process of changing to Iru. Many URLs and notes within this documentation will continue to reference Kandji for some time.\n\nYou can find your API URL in Settings > Access. The API URL will follow the below formats.\n\n- US - `https://SubDomain.api.kandji.io`\n    \n- EU - `https://SubDomain.api.eu.kandji.io`\n    \n\nFor information on how to obtain an API token, please refer to the Iru docs.\n\n[https://docs.iru.com/](https://docs.iru.com/)\n\n#### Rate Limit\n\nThe Iru Endpoint Management API currently has an API rate limit of 10,000 requests per hour per customer.\n\n#### Request Methods\n\nHTTP request methods supported by the API.\n\n| Method | Definition |\n| --- | --- |\n| GET | The `GET` method requests a representation of the specified resource. |\n| POST | The `POST` method submits an entity to the specified resource. |\n| PATCH | The `PATCH` method applies partial modifications to a resource. |\n| DELETE | The `DELETE` method deletes the specified resource. |\n\n#### Response codes\n\nNot all response codes apply to every endpoint.\n\n| Code | Response |\n| --- | --- |\n| 200 | OK |\n| 201 | Created |\n| 204 | No content |\n|  | Typical response when sending the DELETE method. |\n| 400 | Bad Request |\n|  | \"Command already running\" - The command may already be running in a _Pending_ state waiting on the device. |\n|  | \"Command is not allowed for current device\" - The command may not be compatible with the target device. |\n|  | \"JSON parse error - Expecting ',' delimiter: line 3 column 2 (char 65)\" |\n| 401 | Unauthorized |\n|  | This error can occur if the token is incorrect, was revoked, or the token has expired. |\n| 403 | Forbidden |\n|  | The request was understood but cannot be authorized. |\n| 404 | Not found |\n|  | Unable to locate the resource in the Iru tenant. |\n| 415 | Unsupported Media Type |\n|  | The request contains a media type which the server or resource does not support. |\n| 500 | Internal server error |\n| 503 | Service unavailable |\n|  | This error can occur if a file upload is still being processed via the custom apps API. |\n\n#### Data structure\n\nThe API returns all structured responses in JSON schema format.\n\n#### Examples\n\nCode examples using the API can be found in the Iru Endpoint Management support [GitHub](https://github.com/kandji-inc/support/tree/main/api-tools)."
  version: 1.0.0
servers:
- url: https://{subdomain}.api.kandji.io
  description: US Server
  variables:
    subdomain:
      default: your-subdomain
      description: Your Iru Endpoint Management subdomain
- url: https://{subdomain}.api.eu.kandji.io
  description: EU Server
  variables:
    subdomain:
      default: your-subdomain
      description: Your Iru Endpoint Management subdomain
security:
- BearerAuth: []
tags:
- name: Vulnerability Management
paths:
  /api/v1/vulnerability-management/detections:
    get:
      summary: List Detections
      description: Retrieve a list of all vulnerability detections across the device fleet.
      parameters:
      - name: after
        in: query
        required: false
        description: 'Cursor token for pagination. Example: `eyJpZCI6MTIzNDU2Nzg5fQ==`'
        schema:
          type: string
        example: eyJpZCI6MTIzNDU2Nzg5fQ==
      - name: size
        in: query
        required: false
        description: 'A hard upper `limit` is set at 300 records returned per request. If more records are expected, pagination should be used using the URL value returned in the `next` attribute. Additionally, filters can be added to a request to limit the results. Example: `300`'
        schema:
          type: integer
          maximum: 300
          default: 300
        example: 300
      - name: filter
        in: query
        required: false
        description: 'Filter on any key attribute within the response.


          Available fields: `device_id`, `device_name`, `device_serial_number`, `device_model`, `device_os_version`, `blueprint_id`, `blueprint_name`, `name`, `path`, `version`, `bundle_id`, `cve_id`, `cve_description`, `cve_link`, `cvss_score`, `cvss_severity`, `detection_datetime`, `cve_published_at`, `cve_modified_at`.


          Example: `{"cve_id":{"in":["CVE-2024-24795"]}}`'
        schema:
          type: string
        example: '{"cve_id":{"in":["CVE-2024-24795"]}}'
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: object
              example:
                next: null
                previous: null
                results:
                - device_id: abcd
                  device_name: accuhive MacBook Air
                  device_serial_number: FVFGHGK7Q6L7
                  device_model: MacBook
                  device_os_version: '12.9'
                  blueprint_id: 396cdae2-147e-4e61-8a27-2f6b6963da4f
                  blueprint_name: Threat
                  name: Example
                  version: 1.0.0
                  path: /path/to/app
                  bundle_id: com.microsoft
                  cve_id: CVE-2024-12345
                  cve_description: description of the cve from nvd
                  cve_link: https://nvd.nist.gov/vuln/detail/CVE-2024-12345
                  cvss_score: 3.2
                  cvss_severity: Low
                  first_detection_date: '2023-10-13 16:15:00.000000'
                  latest_detection_date: '2023-10-13 16:15:00.000000'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Vulnerability Management
  /api/v1/vulnerability-management/vulnerabilities:
    get:
      summary: List Vulnerabilities
      description: Retrieve a list of all vulnerabilities grouped by CVE.
      parameters:
      - name: page
        in: query
        required: false
        description: 'The page number of the response. Example: `1`'
        schema:
          type: integer
          minimum: 1
          default: 1
        example: 1
      - name: size
        in: query
        required: false
        description: 'A hard upper `limit` is set at 50 records returned per request. If more records are expected, pagination should be used using the URL value returned in the `next` attribute. Additionally, filters can be added to a request to limit the results. Example: `50`'
        schema:
          type: integer
          maximum: 50
          default: 50
        example: 50
      - name: sort_by
        in: query
        required: false
        description: 'Field to sort by. Available options: `age`, `cve_id`, `cvss_score`, `device_count`, `known_exploit`, `software` (software name), `severity`, `status`. Example: `cve_id`'
        schema:
          type: string
          enum:
          - age
          - cve_id
          - cvss_score
          - device_count
          - known_exploit
          - software
          - severity
          - status
        example: cve_id
      - name: filter
        in: query
        required: false
        description: 'Filter results. Similar to prism filters.


          Filterable columns: `cve_id`, `software`, `severity`, `first_detection_date`, `status`.


          Example: `{"cve_id":{"in":["CVE-2024-24795"]}}`'
        schema:
          type: string
        example: '{"cve_id":{"in":["CVE-2024-24795"]}}'
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: object
              example:
                total: 1
                size: 50
                results:
                - cve_id: CVE-2024-24795
                  severity: High
                  cvss_score: 7.5
                  kev_score: 0
                  cve_link: https://nvd.nist.gov/vuln/detail/CVE-2018-25032
                  first_detection_date: '2025-05-23T13:21:37.792889Z'
                  latest_detection_date: '2025-05-23T13:21:37.831775Z'
                  device_count: 1
                  software:
                  - macOS 12 Monterey
                  status: Active
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Vulnerability Management
  /api/v1/vulnerability-management/vulnerabilities/{cve_id}:
    get:
      summary: Get Vulnerability Description
      description: Retrieve information about a CVE.
      parameters:
      - name: cve_id
        in: path
        required: true
        description: 'The unique identifier of the vulnerability. Example: `CVE-2024-12345`'
        schema:
          type: string
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: object
                example:
                  cve_id: CVE-2024-12345
                  severity: Low
                  cvss_score: 3.2
                  kev_score: 1
                  epss_score: 0
                  cve_link: https://nvd.nist.gov/vuln/detail/CVE-2023-12345
                  description: description of the cve from nvd
                  first_detection_date: '2023-10-13 16:15:00.000000'
                  software_count: 3
                  latest_detection_date: '2023-10-13 16:15:00.000000'
                  device_count: 2
                  cve_published_at: '2023-10-13 16:15:00.000000'
                  cve_modified_at: '2023-10-13 16:15:00.000000'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Vulnerability Management
  /api/v1/vulnerability-management/vulnerabilities/{cve_id}/devices:
    get:
      summary: List Affected Devices
      description: Retrieve a list of devices impacted by a specified cve_id vulnerability for a tenants fleet.
      parameters:
      - name: cve_id
        in: path
        required: true
        description: 'The unique identifier of the vulnerability. Example: `CVE-2024-12345`'
        schema:
          type: string
        example: CVE-2024-12345
      - name: page
        in: query
        required: false
        description: 'The page number of the response. Example: `1`'
        schema:
          type: integer
          minimum: 1
          default: 1
        example: 1
      - name: size
        in: query
        required: false
        description: 'A hard upper `limit` is set at 50 records returned per request. If more records are expected, pagination should be used using the URL value returned in the `next` attribute. Additionally, filters can be added to a request to limit the results. Example: `50`'
        schema:
          type: integer
          maximum: 50
          default: 50
        example: 50
      - name: sort_by
        in: query
        required: false
        description: 'Field to sort by. Available options: `name` (device name), `detection_datetime`. Example: `software_name`'
        schema:
          type: string
          enum:
          - name
          - detection_datetime
        example: software_name
      - name: filter
        in: query
        required: false
        description: 'Filter results.


          Filterable columns: `name`, `detection_datetime`.


          Example: `{"detection_datetime":{"gte":"2025-05-23T17:11:31.816587Z"}}`'
        schema:
          type: string
        example: '{"detection_datetime":{"gte":"2025-05-23T17:11:31.816587Z"}}'
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: object
              example:
                total: 2
                page: 1
                size: 50
                results:
                - device_id: abcd
                  name: accuhive MacBook Air
                  serial_number: FVFGHGK7Q6L7
                  model: Macbook
                  os_version: '12.5'
                  blueprint_id: 396cdae2-147e-4e61-8a27-2f6b6963da4f
                  blueprint_name: Vuln
                  assigned_user: User Name
                  no_of_installs: 2
                  software_summary:
                    name: macOS 11 Catalina
                    detection_date: '2023-10-13 16:15:00.000000'
                    path: /path/to/app
                    version: 1.2.1
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Vulnerability Management
  /api/v1/vulnerability-management/vulnerabilities/{cve_id}/software:
    get:
      summary: List Affected Software
      description: This endpoint makes a request to retrieve a list of software impacted by a specified cve_id vulnerability for a tenant's fleet.
      parameters:
      - name: cve_id
        in: path
        required: true
        description: 'The unique identifier of the vulnerability. Example: `CVE-2024-12345`'
        schema:
          type: string
        example: CVE-2024-12345
      - name: page
        in: query
        required: false
        description: 'The page number of the response. Example: `1`'
        schema:
          type: integer
          minimum: 1
          default: 1
        example: 1
      - name: size
        in: query
        required: false
        description: 'A hard upper `limit` is set at 50 records returned per request. If more records are expected, pagination should be used using the URL value returned in the `next` attribute. Additionally, filters can be added to a request to limit the results. Example: `50`'
        schema:
          type: integer
          maximum: 50
          default: 50
        example: 50
      - name: sort_by
        in: query
        required: false
        description: 'Field to sort by. Available options: `software` (software name), `detection_datetime`. Example: `software`'
        schema:
          type: string
          enum:
          - software
          - detection_datetime
        example: software
      - name: filter
        in: query
        required: false
        description: 'Filter results. Similar to prism filters.


          Filterable columns: `blueprint_id`, `detection_datetime`.


          Example: `{"detection_datetime":{"gte":"2025-05-23T17:11:31.816587Z"}}`'
        schema:
          type: string
        example: '{"detection_datetime":{"gte":"2025-05-23T17:11:31.816587Z"}}'
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: object
                example:
                  total: 1
                  page: 1
                  size: 50
                  results:
                  - name: app_name
                    bundle_id: bundle_id
                    num_versions: 2
                    type: null
                    blueprints:
                    - id: blueprint
                      name: name_blueprint
                    num_devices: 2
                    software_versions:
                    - latest_detection_date: '2023-10-13 16:15:00.000000'
                      blueprints:
                      - id: id_num
                        name: my_blueprint
                      version: 1.2.1
                      devices_impacted: 2
                    - latest_detection_date: '2023-10-13 16:15:00.000000'
                      blueprints:
                      - id: id_num
                        name: my_blueprint
                      version: 1.3.1
                      devices_impacted: 1
                  - cve_id: CVE-2018-25032
                    severity: High
                    cvss_score: 7.5
                    kev_score: 0
                    cve_link: https://nvd.nist.gov/vuln/detail/CVE-2018-25032
                    first_detection_date: '2025-05-23T13:21:37.792889Z'
                    latest_detection_date: '2025-05-23T13:21:37.831775Z'
                    device_count: 1
                    software:
                    - macOS 12 Monterey
                    status: Active
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Vulnerability Management
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT