Iru Behavioral Detections API

openapi: 3.2.0
info:
  title: Iru Endpoint Management Behavioral Detections 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: Behavioral Detections
paths:
  /api/v1/behavioral-detections:
    get:
      summary: Get Behavioral Detections
      description: Get Behavioral Detections.
      parameters:
      - name: threat_id
        in: query
        required: false
        description: 'Filter by a specific threat ID. Example: `Kandji_BD_0096`'
        schema:
          type: string
        example: Kandji_BD_0096
      - name: classification
        in: query
        required: false
        description: 'Filter by threat classification. Example: `malicious`'
        schema:
          type: string
        example: malicious
      - name: status
        in: query
        required: false
        description: 'Filter by threat status. Example: `blocked`'
        schema:
          type: string
        example: blocked
      - name: date_range
        in: query
        required: false
        description: 'Return all records within a specified number of days. Example: `30`'
        schema:
          type: integer
          minimum: 1
        example: 30
      - name: detection_date_from
        in: query
        required: false
        description: 'Start date for detection date range filter. Example: `2024-01-01`'
        schema:
          type: string
          format: date
        example: '2024-01-01'
      - name: detection_date_to
        in: query
        required: false
        description: 'End date for detection date range filter. Example: `2024-01-31`'
        schema:
          type: string
          format: date
        example: '2024-01-31'
      - name: device_id
        in: query
        required: false
        description: 'Search for a specific device by the device id (uuid). Example: `123e4567-e89b-12d3-a456-426614174000`'
        schema:
          type: string
        example: 123e4567-e89b-12d3-a456-426614174000
      - name: malware_family
        in: query
        required: false
        description: 'Filter by malware family. Example: `TrickBot`'
        schema:
          type: string
        example: TrickBot
      - name: parent_process_name
        in: query
        required: false
        description: 'Filter by parent process. Example: `bash`'
        schema:
          type: string
        example: bash
      - name: target_process_name
        in: query
        required: false
        description: 'Filter by target process. Example: `python`'
        schema:
          type: string
        example: python
      - name: informational_tags
        in: query
        required: false
        description: 'Filter by tags. Example: `exploit,privilege_escalation`'
        schema:
          type: string
        example: exploit,privilege_escalation
      - name: term
        in: query
        required: false
        description: 'Search term to filter threat results. Device name, file hash, image path. Example: `device_name`'
        schema:
          type: string
        example: device_name
      - name: sort_by
        in: query
        required: false
        description: 'Detections can be sorted by any of the following keys. Prepending a dash (-) to the parameter value will reverse the order. Example: `status` or `-status`'
        schema:
          type: string
          enum:
          - threat_id
          - classification
          - device_name
          - parent_process_name
          - target_process_name
          - detection_date
          - status
        example: status
      - name: limit
        in: query
        required: false
        description: 'A hard upper limit is set at 1000 records returned per request. If more records are expected, pagination should be used using the limit and offset parameters. Example: `100`'
        schema:
          type: integer
          maximum: 1000
          default: 1000
        example: 100
      - name: offset
        in: query
        required: false
        description: 'Specify the starting record to return. Example: `0`'
        schema:
          type: integer
          minimum: 0
          default: 0
        example: 0
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: object
                example:
                  total_count: 71
                  next: null
                  previous: null
                  malicious_count: 37
                  suspicious_count: 34
                  results:
                  - id: CC80F462-1F4D-4A04-9380-C21743DFC308
                    threat_id: KTI_BD_0163
                    rule_version: 2
                    description: TP2419 long descriptionnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn123
                    classification: malicious
                    informational_tags: []
                    malware_family: []
                    detection_date: '2025-03-08T17:35:30.462076+00:00'
                    threat_status: detected
                    device_info:
                      id: ddfc3341-f319-4ef0-bf9a-80791b15a79a
                      name: arm-14_7_0
                      serial_number: ZMN33JFKKC
                    parent_process:
                      name: zsh
                      command_line: -zsh
                      image_path: /bin/zsh
                      pid: 7657
                      owner: root
                      sha256: 0ba6f44f486330453af994834aa406c8d398bfda68a54f3176bf3696ccc09c91
                    target_process:
                      name: vim
                      command_line: vim 123
                      image_path: /usr/bin/vim
                      pid: 7759
                      owner: root
                      sha256: c765f827442004d59ac6bd907f16fbda645f970a3bec94c2651a9f297a0f8030
                    library_item:
                      id: 6d4efe51-331a-4e92-bd63-33b1f2797ae5
                      name: Andreu LI
                      mal_posture_mode: protect
                    blueprint:
                      id: f8034d27-d566-456e-8bbe-6a4dd1848961
                      name: Andreu BP
                  - id: B42DF93B-1610-42CF-AB12-E8BF8C7A9D13
                    threat_id: KTI_BD_2796
                    rule_version: 4
                    description: QA Testing Rule
                    classification: malicious
                    informational_tags: []
                    malware_family:
                    - 3CX
                    - AceDeceiver
                    - Activator
                    - AdvancedMacCleaner
                    - Adware.Gen
                    - AMCleaner
                    - AnyKeylogger
                    detection_date: '2025-03-08T17:35:30.462076+00:00'
                    threat_status: detected
                    device_info:
                      id: ddfc3341-f319-4ef0-bf9a-80791b15a79a
                      name: arm-14_7_0
                      serial_number: ZMN33JFKKC
                    parent_process:
                      name: zsh
                      command_line: -zsh
                      image_path: /bin/zsh
                      pid: 7657
                      owner: root
                      sha256: 0ba6f44f486330453af994834aa406c8d398bfda68a54f3176bf3696ccc09c91
                    target_process:
                      name: vim
                      command_line: vim 123
                      image_path: /usr/bin/vim
                      pid: 7759
                      owner: root
                      sha256: c765f827442004d59ac6bd907f16fbda645f970a3bec94c2651a9f297a0f8030
                    library_item:
                      id: 6d4efe51-331a-4e92-bd63-33b1f2797ae5
                      name: Andreu LI
                      mal_posture_mode: protect
                    blueprint:
                      id: f8034d27-d566-456e-8bbe-6a4dd1848961
                      name: Andreu BP
                  - id: AA97B8C8-7CBD-401A-9EC3-63A15A9936BC
                    threat_id: KTI_BD_0141
                    rule_version: 10
                    description: Detects removal of Little Snitch by unloading the Little Snitch Launch Daemon.
                    classification: suspicious
                    informational_tags:
                    - exec
                    - Little Snitch
                    - Disable
                    - Launch Daemon
                    - unload
                    malware_family: []
                    detection_date: '2025-03-07T17:40:15.984091+00:00'
                    threat_status: informational
                    device_info:
                      id: ddfc3341-f319-4ef0-bf9a-80791b15a79a
                      name: arm-14_7_0
                      serial_number: ZMN33JFKKC
                    parent_process:
                      name: zsh
                      command_line: -zsh
                      image_path: /bin/zsh
                      pid: 462
                      owner: root
                      sha256: 0ba6f44f486330453af994834aa406c8d398bfda68a54f3176bf3696ccc09c91
                    target_process:
                      name: sudo
                      command_line: sudo launchctl unload /Library/LaunchDaemons/at.obdev.littlesnitchd.plist
                      image_path: /usr/bin/sudo
                      pid: 5735
                      owner: root
                      sha256: 938921ccaa776ab1bf2ca538e1ba63a8f981f047f236197581bcd968cd08f99f
                    library_item:
                      id: 6d4efe51-331a-4e92-bd63-33b1f2797ae5
                      name: Andreu LI
                      mal_posture_mode: protect
                    blueprint:
                      id: f8034d27-d566-456e-8bbe-6a4dd1848961
                      name: Andreu BP
        '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:
      - Behavioral Detections
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT