admin.openapi.yml

openapi: "3.0.2"
info:
  title: WHIDS API documentation
  version: "1.0"
servers:
  - url: https://127.0.0.1:8001

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api-key
security:
  - ApiKeyAuth: []

paths:
  /stats:
    get:
      summary: Get EDR statistics
      tags:
        - Statistics
      description: >
        Use to retrieve basic statistics about the EDR manager
      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK (successfully authenticated)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      endpoint-count:
                        type: number
                      rule-count:
                        type: number
                  message:
                    type: string
                  error:
                    type: string

  /rules:
    get:
      summary: List rules loaded in the EDR
      tags:
        - Rules management
      description: >
        Use to list rules loaded in the EDR manager deployed on all the endpoints connected
      parameters:
        - in: query
          name: name
          required: true
          schema:
            type: string
          description: >
            Regex used to find to the rule
      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK (successfully authenticated)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      endpoint-count:
                        type: number
                      rule-count:
                        type: number
                  message:
                    type: string
                  error:
                    type: string
    delete:
      summary: Delete a rule
      tags:
        - Rules management
      description: >
        Used to delete a rule from the EDR manager. The engine needs to be reloaded after deletion
      parameters:
        - in: query
          name: name
          required: true
          schema:
            type: string
          description: >
            Rule's name
      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                  message:
                    type: string
                  error:
                    type: string

    post:
      summary: Adding a new rule
      tags:
        - Rules management
      description: >
        Use to add a new rule to the manager or update an existing rule. In case of update the rule engine needs to be reloaded
      parameters:
        - in: query
          name: update
          required: true
          schema:
            type: boolean
          description: >
            Set to true to force update if rule already exists [1|0|t|f|true|false]
      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  Name:
                    type: string
                  Tags:
                    type: array
                    items:
                      type: string
                  Meta:
                    type: object
                    properties:
                      EventIDs:
                        type: array
                        items:
                          type: number
                      Channels:
                        type: array
                        items:
                          type: string
                      Computers:
                        type: array
                        items:
                          type: string
                      ATTACK:
                        type: array
                        items:
                          type: object
                          properties:
                            ID:
                              type: string
                            Tactic:
                              type: string
                            Reference:
                              type: string
                      Criticality:
                        type: number
                      Disable:
                        type: boolean
                      Filter:
                        type: boolean
                  Matches:
                    type: array
                    items:
                      type: string
                  Condition:
                    type: string
  /rules/save:
    get:
      summary: Save rules
      tags:
        - Rules management
      description: >
        Endpoint to use to save rules.
      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK (successfully authenticated)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                  message:
                    type: string
                  error:
                    type: string
  /rules/reload:
    get:
      summary: Reloading rules
      tags:
        - Rules management
      description: >
        Use to reload the rule engine.
      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK (successfully authenticated)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      endpoint-count:
                        type: number
                      rule-count:
                        type: number
                  message:
                    type: string
                  error:
                    type: string

  /endpoints:
    get:
      summary: List all endpoints
      tags:
        - Endpoints management
      description: >
        Use to list the available endpoints and configured to communicate with the manager or define endpoint settings (group, status, ...)
      parameters:
        - in: query
          name: group
          schema:
            type: string
          description: >
            filter on specified endpoints' group
        - in: query
          name: status
          schema:
            type: string
          description: >
            filter on specified endpoints' status
        - in: query
          name: status_definition
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                description: >
                  Set a status on the endpoint
        - in: query
          name: group_definition
          content:
            application/json:
              schema:
                type: object
                properties:
                  group:
                    type: string
                description: >
                  Affect the endpoint to a group

      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK (successfully authenticated)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        uuid:
                          type: string
                        hostname:
                          type: string
                        ip:
                          type: string
                        group:
                          type: string
                        score:
                          type: number
                        status:
                          type: string
                        last-detection:
                          type: string
                        last-connection:
                          type: string
                      required: [
                          uuid
                          hostname
                          ip
                          group
                          score
                          status
                          last-detection
                          last-connection,
                        ]
                  message:
                    type: string
                  error:
                    type: string

    put:
      summary: Adding a new endpoints
      tags:
        - Endpoints management
      description: >
        Add a new endpoint to the EDR. The endpoint will also be added to the configuration of the manager and committed to disk. 
        You can now configure a new EDR agent on any endpoint.
      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      uuid:
                        type: string
                      hostname:
                        type: string
                      ip:
                        type: string
                      key:
                        type: string
                      last-connection:
                        type: string
                  message:
                    type: string
                  error:
                    type: string

  /endpoints/{endpoint_UUID}:
    get:
      summary: Get a single endpoints
      tags:
        - Endpoints management
      description: >
        Use to list information about the specified endpoint.
      parameters:
        - in: path
          name: endpoint_UUID
          required: true
          schema:
            type: string
            format: uuid

      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      uuid:
                        type: string
                      hostname:
                        type: string
                      ip:
                        type: string
                      group:
                        type: string
                      score:
                        type: number
                      status:
                        type: string
                      last-detection:
                        type: string
                      last-connection:
                        type: string
                  message:
                    type: string
                  error:
                    type: string
    delete:
      summary: Delete an endpoint
      tags:
        - Endpoints management
      description: >
        Delete endpoint from the EDR. This change is immediate and persistent. Thus if an EDR agent is still configured using these
        credentials it will not be able to communicate with the manager any longer.
      parameters:
        - in: path
          name: endpoint_UUID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      uuid:
                        type: string
                      hostname:
                        type: string
                      ip:
                        type: string
                      key:
                        type: string
                      last-connection:
                        type: string
                  message:
                    type: string
                  error:
                    type: string

  /endpoints/{endpoint_UUID}/detections:
    get:
      summary: Getting endpoint detections
      tags:
        - Endpoints detections
      description: >
        Use to retrieve detections collected from a given endpoint
      parameters:
        - in: path
          name: endpoint_UUID
          required: true
          schema:
            type: string
            format: uuid

        - in: query
          name: start
          schema:
            type: string
          description: RFC 3339 formatted timestamp used as starting point for getting detections

        - in: query
          name: since
          schema:
            type: string
          description: RFC 3339 formatted timestamp used as stopping point for getting detections

        - in: query
          name: pivot
          schema:
            type: string
          description: RFC 3339 formatted timestamp used as pivot point for retrieving logs

        - in: query
          name: delta
          schema:
            type: string
          description: duration string used for getting detections around pivot point. Specifying a pivot and a delta will search detections from pivot-delta to pivot+delta

      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        Event:
                          type: object
                          properties:
                            EventData:
                              type: object
                              properties:
                                Ancestors:
                                  type: string
                                CommandLine:
                                  type: string
                                Company:
                                  type: string
                                CurrentDirectory:
                                  type: string
                                Description:
                                  type: string
                                FileVersion:
                                  type: string
                                Hashes:
                                  type: string
                                Image:
                                  type: string
                                ImageSize:
                                  type: string
                                IntegrityLevel:
                                  type: string
                                LogonGuid:
                                  type: string
                                LogonId:
                                  type: string
                                OriginalFileName:
                                  type: string
                                ParentCommandLine:
                                  type: string
                                ParentImage:
                                  type: string
                                ParentIntegrityLevel:
                                  type: string
                                ParentProcessGuid:
                                  type: string
                                ParentProcessId:
                                  type: string
                                ParentServices:
                                  type: string
                                ParentUser:
                                  type: string
                                ProcessGuid:
                                  type: string
                                ProcessId:
                                  type: string
                                Product:
                                  type: string
                                RuleName:
                                  type: string
                                Services:
                                  type: string
                                TerminalSessionId:
                                  type: string
                                User:
                                  type: string
                                UtcTime:
                                  type: string
                            GeneInfo:
                              type: object
                              properties:
                                Criticality:
                                  type: number
                                Signature:
                                  type: array
                                  items:
                                    type: string
                            System:
                              type: object
                              properties:
                                Channel:
                                  type: string
                                Computer:
                                  type: string
                                Correlation:
                                  type: object
                                  properties:
                                    EventID:
                                      type: string
                                EventRecordID:
                                  type: string
                                Execution:
                                  type: object
                                  properties:
                                    ProcessID:
                                      type: string
                                    ThreadID:
                                      type: string
                                Keywords:
                                  type: string
                                Level:
                                  type: string
                                Opcode:
                                  type: string
                                Provider:
                                  type: object
                                  properties:
                                    Guid:
                                      type: string
                                    Name:
                                      type: string
                                Security:
                                  type: object
                                  properties:
                                    UserID:
                                      type: string
                                Task:
                                  type: string
                                TimeCreated:
                                  type: object
                                  properties:
                                    SystemTime:
                                      type: string
                                Version:
                                  type: string
                  message:
                    type: string
                  error:
                    type: string

  /endpoints/{endpoint_UUID}/artifacts:
    get:
      summary: List available endpoint artifacts
      tags:
        - Endpoints artifacts
      description: >
        Use to list the artifacts collected (following an detections) on a given endpoint.
      parameters:
        - in: path
          name: endpoint_UUID
          required: true
          schema:
            type: string
            format: uuid
        - in: query
          name: since
          schema:
            type: string
          description: RFC 3339 formatted timestamp used to retrieve artifact collected last updated after this date

      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        update:
                          type: string
                        process-guid:
                          type: string
                        event-hash:
                          type: string
                        base-url:
                          type: string
                        files:
                          type: array
                          items:
                            type: string
                  message:
                    type: string
                  error:
                    type: string

  /endpoints/{endpoint_UUID}/artifacts/{process_GUID}/{event_hash}/{filename}:
    get:
      summary: Download a given artifact
      tags:
        - Endpoints artifacts

      description: >
        Use to download a given artifact
      parameters:
        - in: path
          name: endpoint_UUID
          required: true
          schema:
            type: string
            format: uuid
        - in: path
          name: process_GUID
          required: true
          schema:
            type: string
        - in: path
          name: event_hash
          required: true
          schema:
            type: string
        - in: path
          name: filename
          required: true
          schema:
            type: string
        - in: query
          name: raw
          schema:
            type: boolean
          description: >
            If you need to download the raw file
        - in: query
          name: gunzip
          schema:
            type: boolean
          description: >
            If you need to gunzip that the artifact before being sent

      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                  message:
                    type: string
                  error:
                    type: string

  /endpoints/{endpoint_UUID}/logs:
    get:
      summary: List available endpoint logs
      tags:
        - Endpoints logs
      description: >
        Use to retrieve logs of an endpoint. Those logs includes filtered in events as well as detection.
      parameters:
        - in: path
          name: endpoint_UUID
          required: true
          schema:
            type: string
            format: uuid
        - in: query
          name: limit
          schema:
            type: number
          description: Define limit

      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK

  /endpoints/reports:
    get:
      summary: List all endpoints reports
      tags:
        - Endpoints reports
      description: >
        Use to get EDR reports about all the endpoints connected. Reports are not persistent accross restart of the manager.
      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: object
                    properties:
                      03e31275-2277-d8e0-bb5f-480fac7ee4ef:
                        type: object
                        properties:
                          identifier:
                            type: string
                          alert-count:
                            type: number
                          count-by-signature:
                            type: object
                            properties:
                              DefenderConfigChanged:
                                type: number
                              ExecTimestomping:
                                type: number
                              ExecutableFileCreated:
                                type: number
                              HeurPersistentRAT:
                                type: number
                              HeurSpawnShell:
                                type: number
                              NewAutorun:
                                type: number
                              StopSvchostAccess:
                                type: number
                              UnknownServices:
                                type: number
                              UntrustedDriverLoaded:
                                type: number
                              UntrustedService:
                                type: number
                          signatures:
                            type: array
                            items:
                              type: string
                          techniques:
                            type: array
                            items:
                              type: string
                          tactics:
                            type: array
                            items:
                              type: string
                          signature-count:
                            type: number
                          sum-alert-criticality:
                            type: number
                          avg-alert-criticality:
                            type: number
                          std-dev-alert-criticality:
                            type: number
                          sum-rule-criticality:
                            type: number
                          avg-signature-criticality:
                            type: number
                          std-dev-signature-criticality:
                            type: number
                          signature-diversity:
                            type: number
                          count-uniq-signatures:
                            type: number
                          signature-criticality-metric:
                            type: number
                          alert-criticality-metric:
                            type: number
                          score:
                            type: number
                          start-time:
                            type: string
                          median-time:
                            type: string
                          stop-time:
                            type: string
                  message:
                    type: string
                  error:
                    type: string

  /endpoints/{endpoint_UUID}/reports:
    get:
      summary: Get a single endpoints report
      tags:
        - Endpoints reports
      description: >
        Use to get an EDR report about a given endpoint.
      parameters:
        - in: path
          name: endpoint_UUID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: object
                    properties:
                      identifier:
                        type: string
                      alert-count:
                        type: number
                      count-by-signature:
                        type: object
                        properties:
                          DefenderConfigChanged:
                            type: number
                          ExecTimestomping:
                            type: number
                          ExecutableFileCreated:
                            type: number
                          HeurPersistentRAT:
                            type: number
                          HeurSpawnShell:
                            type: number
                          NewAutorun:
                            type: number
                          StopSvchostAccess:
                            type: number
                          UnknownServices:
                            type: number
                          UntrustedDriverLoaded:
                            type: number
                          UntrustedService:
                            type: number
                      signatures:
                        type: array
                        items:
                          type: string
                      techniques:
                        type: array
                        items:
                          type: string
                      tactics:
                        type: array
                        items:
                          type: string
                      signature-count:
                        type: number
                      sum-alert-criticality:
                        type: number
                      avg-alert-criticality:
                        type: number
                      std-dev-alert-criticality:
                        type: number
                      sum-rule-criticality:
                        type: number
                      avg-signature-criticality:
                        type: number
                      std-dev-signature-criticality:
                        type: number
                      signature-diversity:
                        type: number
                      count-uniq-signatures:
                        type: number
                      signature-criticality-metric:
                        type: number
                      alert-criticality-metric:
                        type: number
                      score:
                        type: number
                      start-time:
                        type: string
                      median-time:
                        type: string
                      stop-time:
                        type: string
                  message:
                    type: string
                  error:
                    type: string

    delete:
      summary: Delete an endpoint report
      tags:
        - Endpoints reports
      description: >
        Use to delete a report for a given endpoint. A report can be deleted after an enpoint has been investigated.
      parameters:
        - in: path
          name: endpoint_UUID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK

  /endpoints/{endpoint_UUID}/command:
    get:
      summary: Getting command information
      tags:
        - Command execution
      description: >
        this API endpoint is used to get information about a pending or executed command. In order to make sure the command has been ran, a specific flag in the response can be checked.
      parameters:
        - in: path
          name: endpoint_UUID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK (successfully authenticated)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      uuid:
                        type: string
                      name:
                        type: string
                      args:
                        type: array
                        items:
                          type: string
                      fetch:
                        type: object
                      stdout:
                        type: string
                      stderr:
                        type: string
                      error:
                        type: string
                      sent:
                        type: boolean
                      background:
                        type: boolean
                      completed:
                        type: boolean
                      timeout:
                        type: number
                      sent-time:
                        type: string
                  message:
                    type: string
                  error:
                    type: string

    post:
      summary: Execute command on endpoint
      tags:
        - Command execution
      description: >
        this endpoint can be used to ask the endpoint to execute a command or fetch files from the endpoint. 
        Files can also be dropped prior to command execution, this way it is possible to execute binaries or scripts not initially present on the endpoint.
        Such dropped files are removed post command execution.
        It is worth mentionning that it is the EDR agent installed on the endpoint which is responsible for checking commands to execute. 
        So no connection from the EDR manager to the agent is made.
      parameters:
        - in: path
          name: endpoint_UUID
          required: true
          schema:
            type: string
            format: uuid

        - in: query
          name: command example
          content:
            application/json:
              schema:
                type: object
                properties:
                  command-line:
                    type: string
                    example:
                      - "drivers"
                  fetch-files:
                    type: array
                    items:
                      type: string
                      example:
                        - ""
                  drop-files:
                    type: array
                    items:
                      type: string
                      example:
                        - ""
                  timeout:
                    type: number
      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK (successfully authenticated)

  /endpoints/{endpoint_UUID}/command/{field}:
    get:
      summary: Getting a specific field information
      tags:
        - Command execution
      description: >
        use to retrieve only one field of the command. This way it allows saving bandwith for polling patterns. Not all fields are accessible through that endpoint.
      parameters:
        - in: path
          name: endpoint_UUID
          required: true
          schema:
            type: string
            format: uuid
        - in: path
          name: field
          required: true
          schema:
            type: string

      responses:
        "403":
          description: Not Authorized
        "200":
          description: OK (successfully authenticated)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: boolean
                  message:
                    type: string
                  error:
                    type: string