osctrl-api.yaml

openapi: 3.0.1
servers:
  - url: "{server}/api/v1"
    variables:
      server:
        default: https://osctrl.net
info:
  title: osctrl-api
  description: "This the API for osctrl, a fast and efficient osquery management solution."
  version: 0.3.6
externalDocs:
  description: osctrl documentation
  url: https://osctrl.net
tags:
  - name: nodes
    description: Enrolled nodes in osctrl
    externalDocs:
      description: osctrl nodes
      url: https://github.com/jmpsec/osctrl/tree/master/nodes
  - name: queries
    description: On-demand queries in osctrl
    externalDocs:
      description: on-demand queries
      url: https://github.com/jmpsec/osctrl/tree/master/queries
  - name: platforms
    description: Platforms of enrolled nodes in osctrl
    externalDocs:
      description: osctrl platforms
      url: https://github.com/jmpsec/osctrl/tree/master/queries
  - name: environments
    description: Environments within osctrl
    externalDocs:
      description: osctrl environments
      url: https://github.com/jmpsec/osctrl/tree/master/environments
  - name: tags
    description: Tags for enrolled nodes in osctrl
    externalDocs:
      description: osctrl tags
      url: https://github.com/jmpsec/osctrl/tree/master/tags
  - name: settings
    description: Settings for all osctrl components
    externalDocs:
      description: osctrl settings
      url: https://github.com/jmpsec/osctrl/tree/master/settings
paths:
  /nodes:
    get:
      tags:
        - nodes
      summary: Get a single node by UUID
      description: Returns the osctrl node by the provided UUID
      operationId: apiNodesHandler
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/OsqueryNode"
        403:
          description: no access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        404:
          description: no nodes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        500:
          description: error getting nodes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
      security:
        - Authorization:
            - read
            - write
  /nodes/{uuid}:
    get:
      tags:
        - nodes
      summary: Get node
      description: Returns all enrolled osctrl nodes
      operationId: apiNodeHandler
      parameters:
        - name: uuid
          in: path
          description: UUID of the requested enrolled node
          required: true
          schema:
            type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OsqueryNode"
        403:
          description: no access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        404:
          description: node not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        500:
          description: error getting node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
      security:
        - Authorization:
            - read
            - write
  /queries:
    get:
      tags:
        - queries
      summary: Get on-demand queries
      description: Returns all hidden osctrl on-demand queries
      operationId: apiHiddenQueriesShowHandler
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DistributedQuery"
        403:
          description: no access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        404:
          description: no queries
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        500:
          description: error getting queries
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
      security:
        - Authorization:
            - read
            - write
    post:
      tags:
        - queries
      summary: Run new query
      description: Creates a new on-demand query to run
      operationId: apiQueriesRunHandler
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DistributedQueryRequest"
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiQueriesResponse"
        403:
          description: no access
          content: {}
        404:
          description: no queries
          content: {}
        500:
          description: error getting queries
          content: {}
      security:
        - Authorization:
            - read
            - write
  /queries/{name}:
    get:
      tags:
        - queries
      summary: Get on-demand query
      description: Returns the requested on-demand query by name
      operationId: apiQueryShowHandler
      parameters:
        - name: name
          in: path
          description: Name of the requested on-demand query
          required: true
          schema:
            type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DistributedQuery"
        403:
          description: no access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        404:
          description: query not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        500:
          description: error getting query
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
      security:
        - Authorization:
            - read
            - write
  /queries/results/{name}:
    get:
      tags:
        - queries
      summary: Get on-demand query results
      description: Returns the requested on-demand query results by name
      operationId: apiQueryResultsHandler
      parameters:
        - name: name
          in: path
          description: Name of the requested on-demand query
          required: true
          schema:
            type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIQueryData"
        403:
          description: no access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        404:
          description: query not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        500:
          description: error getting results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
      security:
        - Authorization:
            - read
            - write
  /all-queries:
    get:
      tags:
        - queries
      summary: Get on-demand queries
      description: Returns all osctrl on-demand queries
      operationId: apiAllQueriesShowHandler
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DistributedQuery"
        403:
          description: no access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        404:
          description: no queries
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        500:
          description: error getting queries
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
      security:
        - Authorization:
            - read
            - write
  /platforms:
    get:
      tags:
        - platforms
      summary: Get platforms
      description: Returns all osctrl platforms of enrolled nodes
      operationId: apiPlatformsHandler
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        403:
          description: no access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        404:
          description: no queries
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        500:
          description: error getting queries
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
      security:
        - Authorization:
            - read
            - write
  /environments:
    get:
      tags:
        - environments
      summary: Get environments
      description: Returns all osctrl environments to enroll nodes
      operationId: apiEnvironmentsHandler
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TLSEnvironment"
        403:
          description: no access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        404:
          description: no environments
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        500:
          description: error getting environments
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
      security:
        - Authorization:
            - read
            - write
  /environments/{environment}:
    get:
      tags:
        - environments
      summary: Get environment
      description: Returns the requested osctrl environment to enroll nodes
      operationId: apiEnvironmentHandler
      parameters:
        - name: environment
          in: path
          description: Name of the requested osctrl environment to enroll nodes
          required: true
          schema:
            type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TLSEnvironment"
        403:
          description: no access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        500:
          description: error getting environment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
      security:
        - Authorization:
            - read
            - write
  /tags:
    get:
      tags:
        - tags
      summary: Get tags
      description: Returns all osctrl environments to enroll nodes
      operationId: apiTagsHandler
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AdminTag"
        403:
          description: no access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        500:
          description: error getting tags
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
      security:
        - Authorization:
            - read
            - write
  /settings:
    get:
      tags:
        - settings
      summary: Get settings
      description: Returns all osctrl services settings
      operationId: apiSettingsHandler
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SettingValue"
        403:
          description: no access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        500:
          description: error getting settings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
      security:
        - Authorization:
            - read
            - write
  /settings/{service}:
    get:
      tags:
        - settings
      summary: Get settings
      description: Returns all osctrl settings per service
      operationId: apiSettingsServiceHandler
      parameters:
        - name: service
          in: path
          description: Name of the service to retrieve settings, including JSON
          required: true
          schema:
            type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SettingValue"
        403:
          description: no access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        500:
          description: error getting settings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
      security:
        - Authorization:
            - read
            - write
  /settings/{service}/json:
    get:
      tags:
        - settings
      summary: Get JSON settings
      description: Returns JSON osctrl settings per service
      operationId: apiSettingsServiceJSONHandler
      parameters:
        - name: service
          in: path
          description: Name of the service to retrieve JSON only settings
          required: true
          schema:
            type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SettingValue"
        403:
          description: no access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        500:
          description: error getting settings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
      security:
        - Authorization:
            - read
            - write
components:
  schemas:
    OsqueryNode:
      type: object
      properties:
        ID:
          type: integer
          format: int32
        CreatedAt:
          type: string
          format: date-time
        UpdatedAt:
          type: string
          format: date-time
        DeletedAt:
          type: string
          format: date-time
        NodeKey:
          type: string
        UUID:
          type: string
        Platform:
          type: string
        PlatformVersion:
          type: string
        OsqueryVersion:
          type: string
        Hostname:
          type: string
        Localname:
          type: string
        Username:
          type: string
        OsqueryUser:
          type: string
        Environment:
          type: string
        CPU:
          type: string
        Memory:
          type: string
        HardwareSerial:
          type: string
        DaemonHash:
          type: string
        ConfigHash:
          type: string
        RawEnrollment:
          type: string
        LastStatus:
          type: string
          format: date-time
        LastResult:
          type: string
          format: date-time
        LastConfig:
          type: string
          format: date-time
        LastQueryRead:
          type: string
          format: date-time
        LastQueryWrite:
          type: string
          format: date-time
    DistributedQuery:
      type: object
      properties:
        ID:
          type: integer
          format: int32
        CreatedAt:
          type: string
          format: date-time
        UpdatedAt:
          type: string
          format: date-time
        DeletedAt:
          type: string
          format: date-time
        Name:
          type: string
        Creator:
          type: string
        Query:
          type: string
        Expected:
          type: integer
          format: int32
        Executions:
          type: integer
          format: int32
        Errors:
          type: integer
          format: int32
        Active:
          type: boolean
        Hidden:
          type: boolean
        Protected:
          type: boolean
        Completed:
          type: boolean
        Deleted:
          type: boolean
        Type:
          type: string
        Path:
          type: string
    DistributedQueryRequest:
      type: object
      properties:
        environment_list:
          type: array
          items:
            type: string
        platform_list:
          type: array
          items:
            type: string
        uuid_list:
          type: array
          items:
            type: string
        host_list:
          type: array
          items:
            type: string
        query:
          type: string
    ApiQueriesResponse:
      type: object
      properties:
        query_name:
          type: string
    ApiErrorResponse:
      type: object
      properties:
        error:
          type: string
    APIQueryData:
      type: object
    TLSEnvironment:
      type: object
      properties:
        ID:
          type: integer
          format: int32
        CreatedAt:
          type: string
          format: date-time
        UpdatedAt:
          type: string
          format: date-time
        DeletedAt:
          type: string
          format: date-time
        Name:
          type: string
        Hostname:
          type: string
        Secret:
          type: string
        EnrollSecretPath:
          type: string
        EnrollExpire:
          type: string
          format: date-time
        RemoveSecretPath:
          type: string
        RemoveExpire:
          type: string
          format: date-time
        Type:
          type: string
        DebugHTTP:
          type: boolean
        Icon:
          type: string
        Configuration:
          type: string
        Flags:
          type: string
        Certificate:
          type: string
        ConfigTLS:
          type: boolean
        ConfigInterval:
          type: integer
          format: int32
        LoggingTLS:
          type: boolean
        LogInterval:
          type: integer
          format: int32
        QueryTLS:
          type: boolean
        QueryInterval:
          type: integer
          format: int32
        CarvesTLS:
          type: boolean
        EnrollPath:
          type: string
        LogPath:
          type: string
        ConfigPath:
          type: string
        QueryReadPath:
          type: string
        QueryWritePath:
          type: string
        CarverInitPath:
          type: string
        CarverBlockPath:
          type: string
    AdminTag:
      type: object
      properties:
        ID:
          type: integer
          format: int32
        CreatedAt:
          type: string
          format: date-time
        UpdatedAt:
          type: string
          format: date-time
        DeletedAt:
          type: string
          format: date-time
        Name:
          type: string
        Description:
          type: string
        Color:
          type: string
        Icon:
          type: string
    SettingValue:
      type: object
      properties:
        ID:
          type: integer
          format: int32
        CreatedAt:
          type: string
          format: date-time
        UpdatedAt:
          type: string
          format: date-time
        DeletedAt:
          type: string
          format: date-time
        Service:
          type: string
        JSON:
          type: boolean
        Type:
          type: string
        String:
          type: string
        Boolean:
          type: boolean
        Integer:
          type: integer
          format: int64
        Info:
          type: string
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      bearerFormat: JWT