From 5de9880e620fbc3cfdd17d7a4e2373e04ccbcd63 Mon Sep 17 00:00:00 2001 From: Javier Marcos Date: Thu, 12 Nov 2020 12:55:23 +0100 Subject: [PATCH] Adding API documentation --- osctrl-api.yaml | 680 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 680 insertions(+) create mode 100644 osctrl-api.yaml diff --git a/osctrl-api.yaml b/osctrl-api.yaml new file mode 100644 index 00000000..a61697f9 --- /dev/null +++ b/osctrl-api.yaml @@ -0,0 +1,680 @@ +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.2.3 +externalDocs: + description: osctrl documentation (https://osctrl.net) + 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 +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: [] + /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: [] + /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: [] + 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: [] + /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: [] + /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: [] + /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: [] + /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: [] + /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: [] + /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: [] + /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: [] +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 + securitySchemes: + Authorization: + type: http + scheme: bearer + bearerFormat: JWT