diff --git a/Makefile b/Makefile index 324f71a6..4a839d73 100644 --- a/Makefile +++ b/Makefile @@ -30,8 +30,9 @@ STATIC_ARGS = -ldflags "-linkmode external -extldflags -static" BUILD_ARGS = -ldflags "-s -w -X main.buildCommit=$(shell git rev-parse HEAD) -X main.buildDate=$(shell date -u +%Y-%m-%dT%H:%M:%SZ)" SWAG_VERSION ?= v1.16.6 SWAG = go run github.com/swaggo/swag/cmd/swag@$(SWAG_VERSION) +SWAG_OUTPUT_DIR ?= $(API_DIR)/docs -.PHONY: build static clean tls admin cli api swagger release release-build release-check release-init clean-dist frontend frontend-install frontend-dev frontend-build frontend-test +.PHONY: build static clean tls admin cli api swagger openapi openapi-check release release-build release-check release-init clean-dist frontend frontend-install frontend-dev frontend-build frontend-test # Build code according to caller OS and architecture build: @@ -73,7 +74,15 @@ api-static: # Generate Swagger 2.0 YAML and JSON files from API annotations swagger: - $(SWAG) init -d $(API_DIR),$(API_DIR)/handlers,pkg/types,pkg/nodes,pkg/queries,pkg/environments,pkg/users,pkg/settings,pkg/tags,pkg/carves -g main.go -o $(API_DIR)/docs --outputTypes yaml,json --parseDependencyLevel 1 + $(SWAG) init -d $(API_DIR),$(API_DIR)/handlers,pkg/types,pkg/nodes,pkg/queries,pkg/environments,pkg/users,pkg/settings,pkg/tags,pkg/carves -g main.go -o $(SWAG_OUTPUT_DIR) --outputTypes yaml,json --parseDependencyLevel 1 + +# Generate Swagger 2.0 docs and update the OpenAPI 3 spec +openapi: + ./tools/update-openapi.sh + +# Verify generated API docs are up to date +openapi-check: + ./tools/update-openapi.sh --check # Build the CLI cli: diff --git a/osctrl-api.yaml b/osctrl-api.yaml index 7b261fbc..2b14be05 100644 --- a/osctrl-api.yaml +++ b/osctrl-api.yaml @@ -1,2664 +1,7899 @@ -openapi: 3.0.1 -servers: - - url: "{server}/api/v1" - variables: - server: - default: https://osctrl.net +openapi: 3.0.0 info: - title: osctrl-api - description: "This the API for osctrl, a fast and efficient osquery management solution." + contact: + name: osctrl + url: https://github.com/jmpsec/osctrl + description: API service for osctrl, a fast and efficient osquery management solution. + license: + name: MIT + url: https://github.com/jmpsec/osctrl/blob/master/LICENSE + termsOfService: https://github.com/jmpsec/osctrl + title: osctrl API version: 0.5.2 -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/pkg/nodes - - name: queries - description: On-demand queries in osctrl - externalDocs: - description: on-demand queries - url: https://github.com/jmpsec/osctrl/tree/master/pkg/queries - - name: carves - description: File carves in osctrl - externalDocs: - description: osctrl file carves - url: https://github.com/jmpsec/osctrl/tree/master/pkg/carves - - name: users - description: Existing users in osctrl - externalDocs: - description: osctrl users - url: https://github.com/jmpsec/osctrl/tree/master/pkg/users - - name: platforms - description: Platforms of enrolled nodes in osctrl - externalDocs: - description: osctrl platforms - url: https://github.com/jmpsec/osctrl/tree/master/pkg/queries - - name: environments - description: Environments within osctrl - externalDocs: - description: osctrl environments - url: https://github.com/jmpsec/osctrl/tree/master/pkg/environments - - name: tags - description: Tags for enrolled nodes in osctrl - externalDocs: - description: osctrl tags - url: https://github.com/jmpsec/osctrl/tree/master/pkg/tags - - name: settings - description: Settings for all osctrl components - externalDocs: - description: osctrl settings - url: https://github.com/jmpsec/osctrl/tree/master/pkg/settings paths: - /nodes/{env}/all: + /: get: - tags: - - nodes - summary: Get all the nodes by environment - description: Returns all the enrolled nodes by environment - operationId: AllNodesHandler - parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment - required: true - schema: - type: string + description: Returns the API root liveness response. responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/OsqueryNode" - 400: - description: bad request + type: string + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no nodes + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting nodes + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - admin - /nodes/{env}/active: - get: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + summary: API root liveness check tags: - - nodes - summary: Get all the active nodes by environment - description: Returns all the enrolled active nodes by environment - operationId: ActiveNodesHandler + - system + "/api/v1/all-queries/{env}": + get: + description: Returns on-demand queries for an environment. parameters: - - name: env + - description: Environment name or UUID in: path - description: Name or UUID of the requested osctrl environment + name: env required: true schema: type: string responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - type: array items: - $ref: "#/components/schemas/OsqueryNode" - 400: - description: bad request + $ref: "#/components/schemas/queries.DistributedQuery" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no nodes + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting nodes + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - admin - /nodes/{env}/inactive: - get: + - ApiKeyAuth: [] + summary: List queries tags: - - nodes - summary: Get all the inactive nodes by environment - description: Returns all the enrolled inactive nodes by environment - operationId: InactiveNodesHandler + - queries + /api/v1/audit-logs: + get: + description: Returns paginated API audit log entries. parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment - required: true + - description: Page number + in: query + name: page + schema: + type: integer + - description: Page size + in: query + name: page_size + schema: + type: integer + - description: Search query + in: query + name: q + schema: + type: string + - description: Service filter + in: query + name: service + schema: + type: string + - description: Username filter + in: query + name: username + schema: + type: string + - description: Environment filter + in: query + name: env schema: type: string responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/OsqueryNode" - 400: - description: bad request + $ref: "#/components/schemas/types.AuditLogsPagedResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no nodes + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting nodes + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - admin - /nodes/node/{identifier}: - get: + - ApiKeyAuth: [] + summary: List audit logs tags: - - nodes - summary: Get a single node by identifier - description: Returns a single enrolled node by identifier (UUID, hostname or localname) - operationId: NodeHandler - parameters: - - name: identifier - in: path - description: Identifier of the requested enrolled node (UUID, hostname or localname) - required: true - schema: - type: string + - audit + /api/v1/auth/methods: + get: + description: Returns the authentication methods enabled for the API login UI. responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - $ref: "#/components/schemas/OsqueryNode" - 400: - description: bad request + $ref: "#/components/schemas/handlers.AuthMethodsResponse" + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: node not found + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting node + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - read - /nodes/{env}/delete: - post: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + summary: List authentication methods tags: - - nodes - summary: Delete node - description: Deletes an enrolled node by identifier (UUID, hostname or localname) - operationId: DeleteNodeHandler + - auth + /api/v1/auth/oidc/callback: + get: + description: Handles the OIDC authorization callback and creates an API session. parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment - required: true + - description: OIDC authorization code + in: query + name: code + schema: + type: string + - description: OIDC state + in: query + name: state schema: type: string - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/ApiNodeGenericRequest" responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - $ref: "#/components/schemas/ApiGenericResponse" - 400: - description: bad request + type: string + "302": + description: Found content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + type: string + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no nodes + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error deleting node + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - admin - /nodes/{env}/tag: - post: - tags: - - nodes - summary: Tags node - description: Tags an existing node by identifier (UUID, hostname or localname) - operationId: TagNodeHandler - parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/ApiNodeTagRequest" - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - $ref: "#/components/schemas/ApiGenericResponse" - 400: - description: bad request + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no nodes + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error tagging node + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - admin - /nodes/lookup: - post: + $ref: "#/components/schemas/types.ApiErrorResponse" + summary: Complete OIDC login tags: - - nodes - summary: Lookup node by identifier - description: Looks up an enrolled node by identifier (UUID, hostname or localname) - operationId: LookupNodeHandler - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/ApiLookupRequest" + - auth + /api/v1/auth/oidc/login: + get: + description: Redirects the browser to the configured OIDC identity provider. responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - $ref: "#/components/schemas/OsqueryNode" - 400: - description: bad request + type: string + "302": + description: Found content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + type: string + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no nodes + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error deleting node + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - admin - /queries/{env}: - get: - tags: - - queries - summary: Get all on-demand queries - description: Returns all on-demand queries by environment - operationId: AllQueriesShowHandler - parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment - required: true - schema: - type: string - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/DistributedQuery" - 400: - description: bad request + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - query - post: + $ref: "#/components/schemas/types.ApiErrorResponse" + summary: Start OIDC login tags: - - queries - summary: Run new query - description: Creates a new on-demand query to run - operationId: QueriesRunHandler + - auth + /api/v1/auth/saml/acs: + post: + description: Handles the SAML assertion consumer service callback and creates an + API session. requestBody: content: - application/json: + application/x-www-form-urlencoded: schema: - $ref: "#/components/schemas/ApiDistributedQueryRequest" + type: object + properties: + SAMLResponse: + description: SAML response assertion + type: string + RelayState: + description: SAML relay state + type: string responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - $ref: "#/components/schemas/ApiQueriesResponse" - 400: - description: bad request + type: string + "302": + description: Found content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + type: string + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - query - /queries/{env}/list/{target}: - get: - tags: - - queries - summary: Get on-demand queries - description: Returns all on-demand queries by target and environment - operationId: QueryListHandler - parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment - required: true - schema: - type: string - - name: target - in: path - description: Query target to retrieve (all, all-full, active, hidden-active, completed, expired, saved, hidden-completed, deleted, hidden) - required: true - schema: - type: string - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/DistributedQuery" - 400: - description: bad request + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - query - /queries/{env}/{name}: - get: + $ref: "#/components/schemas/types.ApiErrorResponse" + summary: Complete SAML login tags: - - queries - summary: Get on-demand query - description: Returns the requested on-demand query by name and environment - operationId: QueryShowHandler - parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment - required: true - schema: - type: string - - name: name - in: path - description: Name of the requested on-demand query - required: true - schema: - type: string + - auth + /api/v1/auth/saml/login: + get: + description: Redirects the browser to the configured SAML identity provider. responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - $ref: "#/components/schemas/DistributedQuery" - 400: - description: bad request + type: string + "302": + description: Found content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + type: string + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: query not found + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting query + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - query - /queries/{env}/results/{name}: - get: - tags: - - queries - summary: Get on-demand query results - description: Returns the requested on-demand query results by name and environment - operationId: QueryResultsHandler - parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment - required: true - schema: - type: string - - name: name - in: path - description: Name of the requested on-demand query - required: true - schema: - type: string - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - $ref: "#/components/schemas/APIQueryData" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: query not found + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting results + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - query - /queries/{env}/{action}/{name}: - post: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + summary: Start SAML login tags: - - queries - summary: Execute action on on-demand query - description: Executes an action (delete/expire) in the on-demand query by name and environment - operationId: QueriesActionHandler + - auth + /api/v1/auth/saml/metadata: + get: + description: Returns service provider metadata for SAML identity provider + registration. + responses: + "200": + description: OK + content: + application/xml: + schema: + type: string + "400": + description: Bad request + content: + application/xml: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/xml: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/xml: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/xml: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/xml: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/xml: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/xml: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/xml: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + summary: Get SAML metadata + tags: + - auth + "/api/v1/carves/{env}": + get: + description: Returns paginated file carves for an environment. parameters: - - name: env + - description: Environment name or UUID in: path - description: Name or UUID of the requested osctrl environment + name: env required: true schema: type: string - - name: action - in: path - description: Action to execute (delete, expire) - required: true + - description: Page number + in: query + name: page schema: - type: string - - name: name - in: path - description: Name of the requested on-demand query - required: true + type: integer + - description: Page size + in: query + name: page_size + schema: + type: integer + - description: Search query + in: query + name: q schema: type: string responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - $ref: "#/components/schemas/ApiGenericResponse" - 400: - description: bad request + $ref: "#/components/schemas/types.CarvesPagedResponse" + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - admin - /all-queries/{env}: - get: - tags: - - queries - summary: Get all on-demand queries - description: Returns all on-demand queries by environment - operationId: AllQueriesShowHandler - parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment to get queries - required: true - schema: - type: string - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/DistributedQuery" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - query - /carves/{env}: - get: + - ApiKeyAuth: [] + summary: List file carves tags: - carves - summary: Get file carves - description: Returns all file carves by environment - operationId: CarvesShowHandler + post: + description: Starts a new file carve. parameters: - - name: env + - description: Environment name or UUID in: path - description: Name or UUID of the requested osctrl environment to get carves + name: env required: true schema: type: string + requestBody: + $ref: "#/components/requestBodies/types.ApiDistributedQueryRequest" responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/CarvedFile" - 403: - description: no access + $ref: "#/components/schemas/types.ApiQueriesResponse" + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no carves + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting carves + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - carve - post: - tags: - - queries - summary: Run new file carve - description: Creates a new file carve to run - operationId: CarveListHandler - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/ApiDistributedQueryRequest" - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiQueriesResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - carve - /carves/{env}/list: - get: + - ApiKeyAuth: [] + summary: Run file carve tags: - carves - summary: Get file carves - description: Returns all file carves by target and environment - operationId: CarveListHandler + "/api/v1/carves/{env}/{action}/{name}": + post: + description: Deletes, expires, or otherwise acts on a file carve. parameters: - - name: env + - description: Environment name or UUID in: path - description: Name or UUID of the requested osctrl environment + name: env required: true schema: type: string - responses: - 200: - description: successful operation - content: - application/json: - schema: - type: array - items: - $ref: "#/components/schemas/CarvedFile" - 400: - description: bad request + - description: Carve action + in: path + name: action + required: true + schema: + type: string + - description: Carve query name + in: path + name: name + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiGenericResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - carve - /carves/{env}/queries/{target}: - get: + - ApiKeyAuth: [] + summary: Execute carve action tags: - carves - summary: Get file carves queries - description: Returns all file carves queries by target and environment - operationId: CarveQueriesHandler + "/api/v1/carves/{env}/{name}": + get: + description: Returns a file carve and the files produced by it. parameters: - - name: env + - description: Environment name or UUID in: path - description: Name or UUID of the requested osctrl environment + name: env required: true schema: type: string - - name: target + - description: Carve query name in: path - description: Carve target to retrieve (all, all-full, active, hidden-active, completed, expired, saved, hidden-completed, deleted, hidden) + name: name required: true schema: type: string responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/DistributedQuery" - 400: - description: bad request + $ref: "#/components/schemas/types.CarveDetailResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - carve - /carves/{env}/{name}: - get: + - ApiKeyAuth: [] + summary: Get file carve tags: - carves - summary: Get a file carve - description: Returns a file carve by environment and name - operationId: CarveShowHandler + "/api/v1/carves/{env}/archive/{name}": + get: + description: Downloads the archive for a completed file carve. parameters: - - name: env + - description: Environment name or UUID in: path - description: Name or UUID of the requested osctrl environment to get carves + name: env required: true schema: type: string - - name: name + - description: Carve query name in: path - description: Name of the requested file carve + name: name required: true schema: type: string responses: - 200: - description: successful operation + "200": + description: OK content: - application/json: + application/octet-stream: schema: - type: array - items: - $ref: "#/components/schemas/CarvedFile" - 403: - description: no access + type: string + format: binary + "400": + description: Bad request content: - application/json: + application/octet-stream: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no carves + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: - application/json: + application/octet-stream: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting carve + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: - application/json: + application/octet-stream: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/octet-stream: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/octet-stream: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/octet-stream: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/octet-stream: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/octet-stream: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - carve - /carves/{env}/{action}/{name}: - post: + - ApiKeyAuth: [] + summary: Download carve archive tags: - carves - summary: Execute action on file carve - description: Executes an action (delete/expire) in the file carve by name and environment - operationId: CarvesActionHandler + "/api/v1/carves/{env}/list": + get: + description: Returns paginated file carves for an environment. parameters: - - name: env + - description: Environment name or UUID in: path - description: Name or UUID of the requested osctrl environment + name: env required: true schema: type: string - - name: action - in: path - description: Action to execute (delete, expire) - required: true + - description: Page number + in: query + name: page schema: - type: string - - name: name - in: path - description: Name of the requested file carve - required: true + type: integer + - description: Page size + in: query + name: page_size + schema: + type: integer + - description: Search query + in: query + name: q schema: type: string responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - $ref: "#/components/schemas/ApiGenericResponse" - 400: - description: bad request + $ref: "#/components/schemas/types.CarvesPagedResponse" + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting queries + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - admin - /users: - get: - tags: - - users - summary: Get users - description: Returns all users in osctrl - operationId: UsersHandler - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/AdminUser" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no users + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting users + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - admin - /users/{username}: - get: + - ApiKeyAuth: [] + summary: List file carves tags: - - users - summary: Get a user - description: Returns a single users in osctrl by username - operationId: UserHandler + - carves + "/api/v1/carves/{env}/queries/{target}": + get: + description: Returns file carve queries by target and environment. parameters: - - name: username + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Carve target filter in: path - description: Username of the requested user + name: target required: true schema: type: string responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - type: object items: - $ref: "#/components/schemas/AdminUser" - 403: - description: no access + $ref: "#/components/schemas/queries.DistributedQuery" + type: array + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no users + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting users + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - admin - /users/{username}/{action}: - post: - tags: - - users - summary: Get - description: Perform user related actions in users by username - operationId: UserActionHandler - parameters: - - name: username - in: path - description: Username of the requested user - required: true - schema: - type: string - - name: action - in: path - description: Action to execute (add, edit, remove) - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/ApiUserRequest" - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - type: array - items: - type: string - 400: - description: bad request + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no users + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting users + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - admin - /platforms: - get: + - ApiKeyAuth: [] + summary: List carve queries tags: - - platforms - summary: Get platforms - description: Returns all platforms of enrolled nodes in osctrl - operationId: PlatformsHandler + - carves + /api/v1/carves/samples: + get: + description: Returns sample carve path templates. responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - type: array items: - type: string - 403: - description: no access + $ref: "#/components/schemas/carves.CarveSample" + type: array + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting platforms + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - admin - /platforms/{env}: - get: - tags: - - platforms - summary: Get platforms - description: Returns all platforms of enrolled nodes in osctrl by environment - operationId: PlatformsEnvHandler - parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment to get platforms - required: true - schema: - type: string - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - type: array - items: - type: string - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no platforms + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting platforms + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - admin - /environments: - get: - tags: - - environments - summary: Get environments - description: Returns all osctrl environments to enroll nodes - operationId: EnvironmentsHandler - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/TLSEnvironment" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no environments + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List carve samples + tags: + - carves + /api/v1/checks-auth: + get: + description: Returns API availability for an authenticated user. + responses: + "200": + description: OK content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting environments + type: string + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - read - /environments/{env}: - get: - tags: - - environments - summary: Get environment - description: Returns the requested osctrl environment to enroll nodes - operationId: EnvironmentHandler - parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment - required: true - schema: - type: string - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/TLSEnvironment" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting environment + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - read - /environments/map/id: - get: - tags: - - environments - summary: Get environment name, UUID and ID in a map by ID - description: Returns a reduced map by ID of all environments, containing only the ID, Name and UUID - operationId: EnvironmentMapHandler - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/MapEnvByID" - 400: - description: invalid target + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting environment + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - admin - /environments/map/{target}: - get: + - ApiKeyAuth: [] + summary: Authenticated API check tags: - - environments - summary: Get environment name, UUID and ID in a map by name or UUID - description: Returns a reduced map of all environments, containing only the ID, Name and UUID - operationId: EnvironmentMapHandler - parameters: - - name: target - in: path - description: Name or UUID for the osctrl environments map - required: true - schema: - type: string + - checks + /api/v1/checks-no-auth: + get: + description: Returns API availability without requiring authentication. responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - $ref: "#/components/schemas/MapEnvByString" - 400: - description: invalid target + type: string + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting environment + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - admin - /environments/{env}/enroll/{target}: - get: - tags: - - environments - summary: Get enroll values for an environment - description: Returns each of the node enrollment values (secret, certificate, flags, one-liner) for the requested osctrl environment - operationId: EnvEnrollHandler - parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment - required: true - schema: - type: string - - name: target - in: path - description: Target to retrieve (secret, cert, flags, enroll.sh, enroll.ps1) - required: true - schema: - type: string - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/ApiDataResponse" - 400: - description: bad request + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no environments + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting environments + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - read - post: + $ref: "#/components/schemas/types.ApiErrorResponse" + summary: Unauthenticated API check tags: - - environments - summary: Get enroll values for an environment - description: Returns each of the node enrollment values (secret, certificate, flags, one-liner) for the requested osctrl environment - operationId: EnvEnrollActionsHandler - parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment - required: true - schema: - type: string - - name: target - in: path - description: Target to retrieve (secret, cert, flags, enroll.sh, enroll.ps1) - required: true - schema: - type: string + - checks + /api/v1/environments: + get: + description: Returns environments visible to the authenticated user. responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - type: array items: - $ref: "#/components/schemas/ApiDataResponse" - 400: - description: bad request + $ref: "#/components/schemas/types.TLSEnvironmentView" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no environments + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting environments + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - read - /environments/{env}/enroll/{action}: - post: + - ApiKeyAuth: [] + summary: List environments tags: - environments - summary: Perform enroll actions for an environment - description: Executes an action (extend/rotate/expire/notexpire) in the enrollment URL for the requested osctrl environment - operationId: EnvEnrollActionsHandler - parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment - required: true - schema: - type: string - - name: action - in: path - description: Action to execute (extend, rotate, expire, notexpire) - required: true - schema: - type: string + post: + description: Creates an environment. requestBody: content: application/json: schema: - $ref: "#/components/schemas/ApiActionsRequest" + $ref: "#/components/schemas/types.EnvCreateRequest" + description: Request body + required: true responses: - 200: - description: successful operation - content: - application/json: - schema: - type: array - items: - $ref: "#/components/schemas/ApiDataResponse" - 400: - description: bad request + "200": + description: OK content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/environments.TLSEnvironment" + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no environments + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting environments + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - admin - /environments/{env}/remove/{target}: - get: - tags: - - environments - summary: Get remove values for an environment - description: Returns each of the node removal values (one-liner shell or powershell) for the requested osctrl environment - operationId: EnvironmentHandler - parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment - required: true - schema: - type: string - - name: target - in: path - description: Target to retrieve (remove.sh, remove.ps1) - required: true - schema: - type: string - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/ApiDataResponse" - 400: - description: bad request + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no environments + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting environments + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - read - /environments/{env}/remove/{action}: - post: + - ApiKeyAuth: [] + summary: Create environment tags: - environments - summary: Perform remove actions for an environment - description: Executes an action (extend/rotate/expire/notexpire) in the remove URL for the requested osctrl environment - operationId: EnvRemoveActionsHandler + "/api/v1/environments/{env}": + delete: + description: Deletes an environment. parameters: - - name: env - in: path - description: Name or UUID of the requested osctrl environment - required: true - schema: - type: string - - name: action + - description: Environment name or UUID in: path - description: Action to execute (extend, rotate, expire, notexpire) + name: env required: true schema: type: string - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/ApiActionsRequest" responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/ApiDataResponse" - 400: - description: bad request + $ref: "#/components/schemas/types.ApiGenericResponse" + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no environments + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting environments + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - admin - /tags: - get: - tags: - - tags - summary: Get tags - description: Returns all osctrl tags for enrolled nodes - operationId: AllTagsHandler - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/AdminTag" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting tags + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - admin - /tags/{env}: + - ApiKeyAuth: [] + summary: Delete environment + tags: + - environments get: + description: Returns one environment by name or UUID. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.TLSEnvironmentView" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Get environment tags: - - tags - summary: Get tags - description: Returns all osctrl tags for enrolled nodes by environment - operationId: TagsEnvHandler + - environments + patch: + description: Updates an environment. parameters: - - name: env + - description: Environment name or UUID in: path - description: Name or UUID of the requested osctrl environment to get tags + name: env required: true schema: type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.EnvUpdateRequest" + description: Request body + required: true responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/AdminTag" - 400: - description: bad request + $ref: "#/components/schemas/environments.TLSEnvironment" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no tags + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting tags + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - admin - /tags/{env}/{name}: - get: + - ApiKeyAuth: [] + summary: Update environment tags: - - tags - summary: Get tag by name - description: Returns the osctrl tag by name and environment - operationId: TagEnvHandler + - environments + "/api/v1/environments/{env}/enroll/{action}": + post: + description: Extends, expires, rotates, or updates enrollment values for an + environment. parameters: - - name: env + - description: Environment name or UUID in: path - description: UUID of the requested osctrl environment to get tag by name + name: env required: true schema: type: string - - name: name + - description: Enrollment action in: path - description: Name of requested osctrl tag to get by environment + name: action required: true schema: type: string + requestBody: + $ref: "#/components/requestBodies/types.ApiActionsRequest" responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - items: - $ref: "#/components/schemas/AdminTag" - 400: - description: bad request + $ref: "#/components/schemas/types.ApiGenericResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no tags + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting tags + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - admin - /tags/{env}/{action}: - post: + - ApiKeyAuth: [] + summary: Execute enrollment action tags: - - tags - summary: Get tags - description: Perform tag related actions in tags by environment - operationId: TagsActionHandler + - environments + "/api/v1/environments/{env}/enroll/{target}": + get: + description: Returns enrollment helper values for an environment. parameters: - - name: env + - description: Environment name or UUID in: path - description: Name or UUID of the requested osctrl environment to get platforms + name: env required: true schema: type: string - - name: action + - description: Enrollment target in: path - description: Action to execute (add, edit, remove) + name: target required: true schema: type: string - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/ApiTagsRequest" responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - type: array - items: - type: string - 400: - description: bad request + $ref: "#/components/schemas/types.ApiDataResponse" + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 404: - description: no tags + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting tags + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - admin - /settings: - get: - tags: - - settings - summary: Get settings - description: Returns all osctrl services settings - operationId: SettingsHandler - responses: - 200: - description: successful operation + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/SettingValue" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting settings + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - admin - /settings/{service}: - get: + - ApiKeyAuth: [] + summary: Get enrollment values tags: - - settings - summary: Get settings - description: Returns all osctrl settings per service - operationId: SettingsServiceHandler + - environments + "/api/v1/environments/{env}/remove/{action}": + post: + description: Extends, expires, rotates, or updates removal values for an environment. parameters: - - name: service + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Removal action in: path - description: Name of the service to retrieve settings, including JSON + name: action required: true schema: type: string + requestBody: + $ref: "#/components/requestBodies/types.ApiActionsRequest" responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/SettingValue" - 400: - description: bad request + $ref: "#/components/schemas/types.ApiGenericResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting settings + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - admin - /settings/{service}/{env}: - get: + - ApiKeyAuth: [] + summary: Execute removal action tags: - - settings - summary: Get settings - description: Returns all osctrl settings per service and environment - operationId: SettingsServiceHandler + - environments + "/api/v1/environments/{env}/remove/{target}": + get: + description: Returns removal helper values for an environment. parameters: - - name: service + - description: Environment name or UUID in: path - description: Name of the service to retrieve settings, including JSON + name: env required: true schema: type: string - - name: env + - description: Removal target in: path - description: Name or UUID of the requested osctrl environment to get settings + name: target required: true schema: type: string responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/SettingValue" - 400: - description: bad request + $ref: "#/components/schemas/types.ApiDataResponse" + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting settings + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - admin - /settings/{service}/json: - get: + - ApiKeyAuth: [] + summary: Get removal values tags: - - settings - summary: Get JSON settings - description: Returns JSON osctrl settings per service - operationId: SettingsServiceJSONHandler + - environments + /api/v1/environments/actions: + post: + description: Creates or modifies an environment using the legacy action endpoint. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiEnvRequest" + description: Request body + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiGenericResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Execute environment action + tags: + - environments + "/api/v1/environments/config/{env}": + get: + description: Returns raw osquery config sections for an environment. parameters: - - name: service + - description: Environment name or UUID in: path - description: Name of the service to retrieve JSON only settings + name: env required: true schema: type: string responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/SettingValue" - 403: - description: no access + $ref: "#/components/schemas/types.EnvConfigResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting settings + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" security: - - Authorization: - - admin - /settings/{service}/json/{env}: - get: + - ApiKeyAuth: [] + summary: Get environment config tags: - - settings - summary: Get JSON settings - description: Returns JSON osctrl settings per service - operationId: SettingsServiceEnvJSONHandler + - environments + patch: + description: Updates raw osquery config sections for an environment. parameters: - - name: service + - description: Environment name or UUID in: path - description: Name of the service to retrieve JSON only settings + name: env required: true schema: type: string - - name: env + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.EnvConfigPatchRequest" + description: Request body + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.EnvConfigResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Update environment config + tags: + - environments + "/api/v1/environments/expiration/{env}": + patch: + description: Updates enrollment expiration state for an environment. + parameters: + - description: Environment name or UUID in: path - description: Name or UUID of the requested osctrl environment to get JSON settings + name: env required: true schema: type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.EnvExpirationPatchRequest" + description: Request body + required: true responses: - 200: - description: successful operation + "200": + description: OK content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/SettingValue" - 400: - description: bad request + $ref: "#/components/schemas/environments.TLSEnvironment" + "400": + description: Bad request content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 403: - description: no access + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - 500: - description: error getting settings + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/ApiErrorResponse" - security: - - Authorization: - - admin -components: - schemas: - OsqueryNode: - type: object - properties: - ID: - type: integer - format: int32 - CreatedAt: - type: string - format: date-time - UpdatedAt: - type: string - format: date-time - DeletedAt: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Update environment expiration + tags: + - environments + "/api/v1/environments/intervals/{env}": + patch: + description: Updates osquery interval settings for an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.EnvIntervalsPatchRequest" + description: Request body + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/environments.TLSEnvironment" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Update environment intervals + tags: + - environments + "/api/v1/environments/map/{target}": + get: + description: Returns an environment lookup map by target key. + parameters: + - description: "Map target: id, name, or uuid" + in: path + name: target + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + additionalProperties: + $ref: "#/components/schemas/environments.NameUUID" + type: object + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Map environments + tags: + - environments + /api/v1/login: + post: + description: Authenticates an API user and returns a JWT token. + requestBody: + $ref: "#/components/requestBodies/types.ApiLoginRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiLoginResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + summary: Log in + tags: + - auth + "/api/v1/login/{env}": + post: + description: Authenticates an API user and returns a JWT token. + parameters: + - description: Environment name or UUID + in: path + name: env + schema: + type: string + required: true + requestBody: + $ref: "#/components/requestBodies/types.ApiLoginRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiLoginResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + summary: Log in + tags: + - auth + /api/v1/login/environments: + get: + description: Returns pre-auth environment choices for the login UI. + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/types.LoginEnvironment" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + summary: List login environments + tags: + - auth + /api/v1/logout: + post: + description: Clears API session cookies and revokes the active token when present. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/handlers.LogoutResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + summary: Log out + tags: + - auth + "/api/v1/logs/{type}/{env}/{uuid}": + get: + description: Returns recent status or result logs for a node. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: "Log type: status or result" + in: path + name: type + required: true + schema: + type: string + - description: Node UUID + in: path + name: uuid + required: true + schema: + type: string + - description: Maximum number of log rows + in: query + name: limit + schema: + type: integer + - description: RFC3339 lower bound + in: query + name: since + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/handlers.NodeLogsResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Get node logs + tags: + - logs + "/api/v1/nodes/{env}": + get: + description: Returns paginated, filtered, and sorted nodes for an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Page number + in: query + name: page + schema: + type: integer + - description: Page size + in: query + name: page_size + schema: + type: integer + - description: Search query + in: query + name: q + schema: + type: string + - description: Node status filter + in: query + name: status + schema: + type: string + - description: Platform filter + in: query + name: platform + schema: + type: string + - description: Sort field + in: query + name: sort + schema: + type: string + - description: Sort order + in: query + name: order + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.NodesPagedResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List paginated nodes + tags: + - nodes + "/api/v1/nodes/{env}/active": + get: + description: Returns active enrolled nodes for an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/nodes.OsqueryNode" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List active nodes + tags: + - nodes + "/api/v1/nodes/{env}/all": + get: + description: Returns all enrolled nodes for an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/nodes.OsqueryNode" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List all nodes + tags: + - nodes + "/api/v1/nodes/{env}/delete": + post: + description: Deletes a node from an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiNodeGenericRequest" + description: Request body + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiGenericResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Delete node + tags: + - nodes + "/api/v1/nodes/{env}/inactive": + get: + description: Returns inactive enrolled nodes for an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/nodes.OsqueryNode" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List inactive nodes + tags: + - nodes + "/api/v1/nodes/{env}/node/{node}": + get: + description: Returns a single enrolled node in an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Node UUID, hostname, or local name + in: path + name: node + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.NodeView" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Get node + tags: + - nodes + "/api/v1/nodes/{env}/tag": + post: + description: Adds or updates a tag on a node. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiNodeTagRequest" + description: Request body + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiGenericResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Tag node + tags: + - nodes + /api/v1/nodes/lookup: + post: + description: Looks up a node by UUID, hostname, or local name. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiLookupRequest" + description: Request body + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/nodes.OsqueryNode" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Lookup node + tags: + - nodes + /api/v1/osquery/tables: + get: + description: Returns the osquery schema table metadata known to the API. + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/types.OsqueryTable" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List osquery tables + tags: + - osquery + "/api/v1/platforms/{env}": + get: + description: Returns platform counts for an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/nodes.PlatformCounts" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List platforms + tags: + - platforms + "/api/v1/queries/{env}": + get: + description: Returns on-demand queries for an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/queries.DistributedQuery" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List queries + tags: + - queries + post: + description: Starts a new distributed query. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + requestBody: + $ref: "#/components/requestBodies/types.ApiDistributedQueryRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiQueriesResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Run query + tags: + - queries + "/api/v1/queries/{env}/{action}/{name}": + post: + description: Deletes, expires, or otherwise acts on an on-demand query. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Query action + in: path + name: action + required: true + schema: + type: string + - description: Query name + in: path + name: name + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiGenericResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Execute query action + tags: + - queries + "/api/v1/queries/{env}/{name}": + get: + description: Returns a single on-demand query. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Query name + in: path + name: name + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/queries.DistributedQuery" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Get query + tags: + - queries + "/api/v1/queries/{env}/list/{target}": + get: + description: Returns paginated on-demand queries by target and environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Query target filter + in: path + name: target + required: true + schema: + type: string + - description: Page number + in: query + name: page + schema: + type: integer + - description: Page size + in: query + name: page_size + schema: + type: integer + - description: Search query + in: query + name: q + schema: + type: string + - description: Sort field + in: query + name: sort + schema: + type: string + - description: Sort order + in: query + name: order + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.QueriesPagedResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List paginated queries + tags: + - queries + "/api/v1/queries/{env}/results/{name}": + get: + description: Returns paginated results for an on-demand query. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Query name + in: path + name: name + required: true + schema: + type: string + - description: Page number + in: query + name: page + schema: + type: integer + - description: Page size + in: query + name: page_size + schema: + type: integer + - description: RFC3339 lower bound + in: query + name: since + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.QueryResultsResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Get query results + tags: + - queries + "/api/v1/queries/{env}/results/csv/{name}": + get: + description: Streams query results as CSV. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Query name + in: path + name: name + required: true + schema: + type: string + responses: + "200": + description: OK + content: + text/csv: + schema: + type: string + "400": + description: Bad request + content: + text/csv: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + text/csv: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + text/csv: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + text/csv: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + text/csv: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + text/csv: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + text/csv: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + text/csv: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Export query results CSV + tags: + - queries + /api/v1/queries/samples: + get: + description: Returns sample query templates. + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/queries.QuerySample" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List query samples + tags: + - queries + "/api/v1/saved-queries/{env}": + get: + description: Returns paginated saved queries for an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Page number + in: query + name: page + schema: + type: integer + - description: Page size + in: query + name: page_size + schema: + type: integer + - description: Search query + in: query + name: q + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.SavedQueriesPagedResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List saved queries + tags: + - saved-queries + post: + description: Creates a saved query in an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.SavedQueryCreateRequest" + description: Request body + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.SavedQueryView" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Create saved query + tags: + - saved-queries + "/api/v1/saved-queries/{env}/{name}": + delete: + description: Deletes a saved query in an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Saved query name + in: path + name: name + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiGenericResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Delete saved query + tags: + - saved-queries + patch: + description: Updates a saved query in an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Saved query name + in: path + name: name + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.SavedQueryUpdateRequest" + description: Request body + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.SavedQueryView" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Update saved query + tags: + - saved-queries + /api/v1/settings: + get: + description: Returns settings for all services. + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/settings.SettingValue" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List settings + tags: + - settings + "/api/v1/settings/{service}": + get: + description: Returns settings for a service. + parameters: + - description: Service name + in: path + name: service + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/settings.SettingValue" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List service settings + tags: + - settings + "/api/v1/settings/{service}/{env}": + get: + description: Returns settings for a service and environment. + parameters: + - description: Service name + in: path + name: service + required: true + schema: + type: string + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/settings.SettingValue" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List service environment settings + tags: + - settings + "/api/v1/settings/{service}/{name}": + patch: + description: Updates a mutable setting value. + parameters: + - description: Service name + in: path + name: service + required: true + schema: + type: string + - description: Setting name + in: path + name: name + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.SettingPatchRequest" + description: Request body + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/settings.SettingValue" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Update setting + tags: + - settings + "/api/v1/settings/{service}/json": + get: + description: Returns JSON settings for a service. + parameters: + - description: Service name + in: path + name: service + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/settings.SettingValue" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List service JSON settings + tags: + - settings + "/api/v1/settings/{service}/json/{env}": + get: + description: Returns JSON settings for a service and environment. + parameters: + - description: Service name + in: path + name: service + required: true + schema: + type: string + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/settings.SettingValue" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List service environment JSON settings + tags: + - settings + /api/v1/stats: + get: + description: Returns cross-environment dashboard statistics. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/handlers.StatsResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Get dashboard stats + tags: + - stats + "/api/v1/stats/activity/{env}": + get: + description: Returns activity buckets for an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Number of hours to include + in: query + name: hours + schema: + type: integer + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/handlers.ActivityBucket" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Get environment activity + tags: + - stats + "/api/v1/stats/activity/node-batch/{env}": + get: + description: Returns activity buckets for multiple nodes in an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Comma-separated node UUIDs + in: query + name: uuids + schema: + type: string + - description: Number of hours to include + in: query + name: hours + schema: + type: integer + responses: + "200": + description: OK + content: + application/json: + schema: + additionalProperties: + items: + $ref: "#/components/schemas/handlers.NodeActivityBucket" + type: array + type: object + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Get node activity batch + tags: + - stats + "/api/v1/stats/activity/node/{env}/{uuid}": + get: + description: Returns activity buckets for a node. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Node UUID + in: path + name: uuid + required: true + schema: + type: string + - description: Number of hours to include + in: query + name: hours + schema: + type: integer + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/handlers.NodeActivityBucket" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Get node activity + tags: + - stats + /api/v1/stats/osquery-versions: + get: + description: Returns fleet-wide osquery version counts. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/nodes.OsqueryVersionCount" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Get osquery version stats + tags: + - stats + /api/v1/tags: + get: + description: Returns tags across environments. + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/tags.AdminTag" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List tags + tags: + - tags + "/api/v1/tags/{env}": + get: + description: Returns tags for an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/tags.AdminTag" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List environment tags + tags: + - tags + "/api/v1/tags/{env}/{action}": + post: + description: Creates, updates, deletes, or applies tags in an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Tag action + in: path + name: action + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiTagsRequest" + description: Request body + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiDataResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Execute tag action + tags: + - tags + "/api/v1/tags/{env}/{name}": + get: + description: Returns one tag by name for an environment. + parameters: + - description: Environment name or UUID + in: path + name: env + required: true + schema: + type: string + - description: Tag name + in: path + name: name + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/tags.AdminTag" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Get environment tag + tags: + - tags + /api/v1/users: + get: + description: Returns API users. + responses: + "200": + description: OK + content: + application/json: + schema: + items: + $ref: "#/components/schemas/types.AdminUserView" + type: array + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: List users + tags: + - users + "/api/v1/users/{username}": + get: + description: Returns an API user by username. + parameters: + - description: Username + in: path + name: username + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.AdminUserView" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Get user + tags: + - users + "/api/v1/users/{username}/{action}": + post: + description: Creates, updates, deletes, or changes flags on a user. + parameters: + - description: Username + in: path + name: username + required: true + schema: + type: string + - description: User action + in: path + name: action + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiUserRequest" + description: Request body + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiDataResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Execute user action + tags: + - users + "/api/v1/users/{username}/permissions": + get: + description: Returns per-environment permissions for a user. + parameters: + - description: Username + in: path + name: username + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.GetPermissionsResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Get user permissions + tags: + - users + post: + description: Sets per-environment permissions for a user. + parameters: + - description: Username + in: path + name: username + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.SetPermissionsRequest" + description: Request body + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.EnvAccessView" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Set user permissions + tags: + - users + "/api/v1/users/{username}/permissions/all": + post: + description: Sets permissions across all environments for a user. + parameters: + - description: Username + in: path + name: username + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.SetPermissionsAllRequest" + description: Request body + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.SetPermissionsAllResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Set all user permissions + tags: + - users + "/api/v1/users/{username}/token": + delete: + description: Deletes an API token for a user. + parameters: + - description: Username + in: path + name: username + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiGenericResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Delete user token + tags: + - users + "/api/v1/users/{username}/token/refresh": + post: + description: Refreshes an API token for a user. + parameters: + - description: Username + in: path + name: username + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.TokenResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Refresh user token + tags: + - users + /api/v1/users/me: + get: + description: Returns the currently authenticated user profile. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.UserMeResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Get current user + tags: + - users + patch: + description: Updates the current user's profile fields. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.UserMePatchRequest" + description: Request body + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.UserMeResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Update current user + tags: + - users + /api/v1/users/me/password: + post: + description: Changes the current user's password. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/types.PasswordChangeRequest" + description: Request body + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiGenericResponse" + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + security: + - ApiKeyAuth: [] + summary: Change current user password + tags: + - users + /error: + get: + description: Returns a generic API error response. + responses: + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + type: string + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + summary: API error response + tags: + - system + /forbidden: + get: + description: Returns a generic forbidden response. + responses: + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + type: string + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + summary: API forbidden response + tags: + - system + /health: + get: + description: Returns the API health response. + responses: + "200": + description: OK + content: + application/json: + schema: + type: string + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "403": + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "409": + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "429": + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + "503": + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiErrorResponse" + summary: API health check + tags: + - system +servers: + - url: / +components: + requestBodies: + types.ApiActionsRequest: + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiActionsRequest" + description: Request body + required: true + types.ApiDistributedQueryRequest: + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiDistributedQueryRequest" + description: Request body + required: true + types.ApiLoginRequest: + content: + application/json: + schema: + $ref: "#/components/schemas/types.ApiLoginRequest" + description: Request body + required: true + securitySchemes: + ApiKeyAuth: + in: header + name: Authorization + type: apiKey + schemas: + carves.CarveSample: + properties: + category: + $ref: "#/components/schemas/carves.CarveSampleCategory" + label: + type: string + notes: + description: |- + Notes is a brief operator-facing description of why this file is + worth grabbing during an investigation. Surfaced as a tooltip in + the SPA template row. + type: string + path: + type: string + platform: + $ref: "#/components/schemas/carves.CarveSamplePlatform" + type: object + carves.CarveSampleCategory: + enum: + - auth + - logs + - registry + - keychain + - history + - config + type: string + x-enum-varnames: + - CarveCategoryAuth + - CarveCategoryLogs + - CarveCategoryRegistry + - CarveCategoryKeychain + - CarveCategoryHistory + - CarveCategoryConfig + carves.CarveSamplePlatform: + enum: + - linux + - darwin + - windows + type: string + x-enum-varnames: + - CarvePlatformLinux + - CarvePlatformDarwin + - CarvePlatformWindows + environments.NameUUID: + properties: + id: + type: integer + name: + type: string + uuid: + type: string + type: object + environments.TLSEnvironment: + properties: + accept_enrolls: + type: boolean + atc: + type: string + carver_block_path: + type: string + carver_init_path: + type: string + carves_tls: + type: boolean + certificate: + type: string + config_interval: + type: integer + config_path: + type: string + config_tls: + type: boolean + configuration: + type: string + created_at: + type: string + deb_package: + type: string + debug_http: + type: boolean + decorators: + type: string + enroll_expire: + type: string + enroll_path: + type: string + enroll_secret_path: type: string - format: date-time - NodeKey: + flags: type: string - UUID: + hostname: type: string - Platform: + icon: type: string - PlatformVersion: + id: + type: integer + log_interval: + type: integer + log_path: + type: string + logging_tls: + type: boolean + msi_package: + type: string + name: + type: string + options: + type: string + packs: + type: string + pkg_package: + type: string + query_interval: + type: integer + query_read_path: + type: string + query_tls: + type: boolean + query_write_path: + type: string + remove_expire: + type: string + remove_secret_path: + type: string + rpm_package: + type: string + schedule: + type: string + secret: + type: string + type: + type: string + updated_at: + type: string + user_id: + type: integer + uuid: + type: string + type: object + gorm.DeletedAt: + properties: + time: + type: string + valid: + description: Valid is true if Time is not NULL + type: boolean + type: object + handlers.ActivityBucket: + properties: + bucket_start: + type: string + carve: + type: integer + config: + type: integer + enroll: + type: integer + query: + type: integer + type: object + handlers.AuthMethod: + properties: + loginUrl: + description: |- + LoginURL is the relative URL the SPA should redirect the + browser to when this method is chosen. For "password" this + is "/api/v1/login/{env}" (env is interpolated client-side + from the env switcher). For "oidc" this is the global + "/api/v1/auth/oidc/login" — env is irrelevant for federated + login because the federated user resolves to a single + AdminUser row regardless of which env tab they were viewing. + type: string + type: + type: string + type: object + handlers.AuthMethodsResponse: + properties: + methods: + items: + $ref: "#/components/schemas/handlers.AuthMethod" + type: array + type: object + handlers.EnvStats: + properties: + active: + type: integer + active_carves: + type: integer + active_queries: + type: integer + inactive: + type: integer + name: + type: string + platform_counts: + allOf: + - $ref: "#/components/schemas/nodes.PlatformCounts" + description: >- + PlatformCounts buckets the env's nodes by OS family (linux / darwin + / + + windows / other). Drives the Nodes-table QuickFilters chip row. Counts + + are total (active + inactive), since the filter chip lists all nodes + + of that platform regardless of staleness — the Active/Inactive toggle + + is independent. + total: + type: integer + uuid: + type: string + type: object + handlers.LogoutResponse: + properties: + auth_source: + type: string + idp_client_id: + type: string + idp_id_token_hint: + type: string + idp_logout_url: + type: string + type: object + handlers.NodeActivityBucket: + properties: + bucket_start: + type: string + carve: + type: integer + query: + type: integer + result: + type: integer + status: + type: integer + type: object + handlers.NodeLogsResponse: + properties: + env: + type: string + items: + items: + additionalProperties: {} + type: object + type: array + limit: + type: integer + since: + type: string + type: + type: string + uuid: + type: string + type: object + handlers.StatsResponse: + properties: + active_nodes: + type: integer + environments: + description: Per-env breakdown, in stable alphabetical order by name. + items: + $ref: "#/components/schemas/handlers.EnvStats" + type: array + inactive_nodes: + type: integer + platform_counts: + allOf: + - $ref: "#/components/schemas/nodes.PlatformCounts" + description: Cross-env platform breakdown — sum of every accessible env's + PlatformCounts. + total_active_carves: + description: TotalActiveCarves counts active carve-type queries. + type: integer + total_active_queries: + description: TotalActiveQueries counts standard query-type active queries + (excludes carves). + type: integer + total_nodes: + description: Cross-env totals (the user's allowed envs only). + type: integer + type: object + nodes.OsqueryNode: + properties: + bytes_received: + type: integer + config_hash: + type: string + cpu: + type: string + created_at: + type: string + daemon_hash: + type: string + environment: + type: string + environment_id: + type: integer + extra_data: + type: string + hardware_serial: + type: string + hostname: + type: string + id: + type: integer + ip_address: + type: string + last_seen: + type: string + localname: + type: string + memory: + type: string + osquery_user: + type: string + osquery_version: + type: string + platform: + type: string + platform_version: + type: string + updated_at: + type: string + user_id: + type: integer + username: + type: string + uuid: + type: string + type: object + nodes.OsqueryVersionCount: + properties: + count: + type: integer + version: + type: string + type: object + nodes.PlatformCounts: + properties: + darwin: + type: integer + linux: + type: integer + other: + type: integer + windows: + type: integer + type: object + queries.DistributedQuery: + properties: + active: + type: boolean + completed: + type: boolean + created_at: + type: string + creator: + type: string + deleted: + type: boolean + environment_id: + type: integer + errors: + type: integer + executions: + type: integer + expected: + type: integer + expiration: + type: string + expired: + type: boolean + extra_data: + type: string + hidden: + type: boolean + id: + type: integer + name: + type: string + path: + type: string + protected: + type: boolean + query: + type: string + target: + type: string + type: + type: string + updated_at: + type: string + type: object + queries.QuerySample: + properties: + category: + $ref: "#/components/schemas/queries.QuerySampleCategory" + description: + type: string + name: + type: string + platforms: + items: + $ref: "#/components/schemas/queries.QuerySamplePlatform" + type: array + sql: + type: string + type: object + queries.QuerySampleCategory: + enum: + - recon + - processes + - users + - network + - persistence + - file_integrity + - packages + type: string + x-enum-varnames: + - CategoryRecon + - CategoryProcesses + - CategoryUsers + - CategoryNetwork + - CategoryPersistence + - CategoryFileIntegrity + - CategoryPackages + queries.QuerySamplePlatform: + enum: + - linux + - darwin + - windows + type: string + x-enum-varnames: + - PlatformLinux + - PlatformDarwin + - PlatformWindows + settings.SettingValue: + properties: + boolean: + type: boolean + createdAt: + type: string + deletedAt: + $ref: "#/components/schemas/gorm.DeletedAt" + environmentID: + type: integer + id: + type: integer + info: + type: string + integer: + format: int64 + type: integer + json: + type: boolean + name: + type: string + service: + type: string + string: type: string - OsqueryVersion: + type: + type: string + updatedAt: + type: string + type: object + tags.AdminTag: + properties: + auto_tag: + type: boolean + cohort: + type: boolean + color: type: string - Hostname: + created_at: type: string - Localname: + created_by: type: string - IPAddress: + custom_tag: type: string - Username: + description: type: string - OsqueryUser: + environment_id: + type: integer + icon: type: string - Environment: + id: + type: integer + name: type: string - CPU: + tag_type: + type: integer + updated_at: type: string - Memory: + type: object + types.AdminUserView: + properties: + admin: + type: boolean + auth_source: + description: |- + AuthSource is empty for the password-login path (the default) + and "oidc" for users JIT-provisioned through the federated + callback. Surfaced so the SPA Users page can show an "OIDC" + badge alongside the existing admin/service labels. type: string - HardwareSerial: + created_at: type: string - DaemonHash: + email: type: string - ConfigHash: + environment_id: + type: integer + fullname: type: string - BytesReceived: + id: type: integer - format: int32 - RawEnrollment: + service: + type: boolean + token_expire: + type: string + updated_at: type: string - LastSeen: + username: + type: string + uuid: + type: string + type: object + types.ApiActionsRequest: + properties: + certificate: + type: string + url_deb_pkg: + type: string + url_mac_pkg: type: string - format: date-time - UserID: + url_msi_pkg: + type: string + url_rpm_pkg: + type: string + type: object + types.ApiDataResponse: + properties: + data: + type: string + type: object + types.ApiDistributedQueryRequest: + properties: + environment_list: + items: + type: string + type: array + exp_hours: type: integer - format: int32 - EnvironmentID: + hidden: + type: boolean + host_list: + items: + type: string + type: array + path: + type: string + platform_list: + items: + type: string + type: array + query: + type: string + tag_list: + items: + type: string + type: array + uuid_list: + items: + type: string + type: array + type: object + types.ApiEnvRequest: + properties: + action: + type: string + hostname: + type: string + icon: + type: string + name: + type: string + type: + type: string + uuid: + type: string + type: object + types.ApiErrorResponse: + properties: + code: + type: string + error: + type: string + type: object + types.ApiGenericResponse: + properties: + message: + type: string + type: object + types.ApiLoginRequest: + properties: + exp_hours: type: integer - format: int32 - ExtraData: + password: + type: string + username: + type: string + type: object + types.ApiLoginResponse: + properties: + csrf_token: + type: string + token: type: string - ApiNodeGenericRequest: type: object + types.ApiLookupRequest: properties: - uuid: + identifier: type: string - ApiNodeTagRequest: type: object + types.ApiNodeGenericRequest: properties: uuid: type: string + type: object + types.ApiNodeTagRequest: + properties: + custom: + type: string tag: type: string type: type: integer - format: int32 - ApiUserRequest: + uuid: + type: string type: object + types.ApiQueriesResponse: properties: - username: + query_name: type: string - password: + type: object + types.ApiTagsRequest: + properties: + color: type: string - email: + custom: type: string - fullname: + description: + type: string + env: + type: string + icon: + type: string + name: type: string + tagtype: + type: integer + type: object + types.ApiUserRequest: + properties: admin: type: boolean - not_admin: + admin_access: type: boolean - service: + api: type: boolean - not_service: + carve_access: type: boolean + email: + type: string environments: - type: array items: type: string - DistributedQuery: - type: object - properties: - ID: - type: integer - format: int32 - CreatedAt: - type: string - format: date-time - UpdatedAt: + type: array + fullname: type: string - format: date-time - DeletedAt: + not_admin: + type: boolean + not_service: + type: boolean + password: type: string - format: date-time - Name: + query_access: + type: boolean + service: + type: boolean + user_access: + type: boolean + username: type: string - Creator: + type: object + types.AuditLogView: + properties: + created_at: type: string - Query: + env_uuid: type: string - Expected: - type: integer - format: int32 - Executions: + environment_id: type: integer - format: int32 - Errors: + id: type: integer - format: int32 - Active: - type: boolean - Hidden: - type: boolean - Protected: - type: boolean - Completed: - type: boolean - Deleted: - type: boolean - Type: + line: type: string - Path: + log_type: + type: integer + service: type: string - EnvironmentID: + severity: type: integer - format: int32 - ExtraData: + source_ip: + type: string + username: type: string - ApiDistributedQueryRequest: type: object + types.AuditLogsPagedResponse: properties: - environment_list: - type: array - items: - type: string - platform_list: - type: array - items: - type: string - uuid_list: - type: array + items: items: - type: string - host_list: + $ref: "#/components/schemas/types.AuditLogView" type: array - items: - type: string - query: - type: string - ApiQueriesResponse: + page: + type: integer + page_size: + type: integer + total_items: + type: integer + total_pages: + type: integer type: object + types.BIOSInfo: properties: - query_name: + address: + type: string + date: + type: string + revision: + type: string + size: + type: string + vendor: + type: string + version: + type: string + volume_size: type: string - APIQueryData: type: object - CarvedFile: + types.CarveDetailResponse: + properties: + files: + items: + $ref: "#/components/schemas/types.CarveFileView" + type: array + query: + $ref: "#/components/schemas/queries.DistributedQuery" type: object + types.CarveFileView: properties: - ID: + archived: + type: boolean + block_size: type: integer - format: int32 - CreatedAt: - type: string - format: date-time - UpdatedAt: + carve_id: type: string - format: date-time - DeletedAt: - type: string - format: date-time - CarveID: + carve_size: + type: integer + completed_at: type: string - RequestID: + completed_blocks: + type: integer + created_at: type: string - SessionID: + path: type: string - QueryName: + session_id: type: string - UUID: + status: type: string - NodeID: + total_blocks: type: integer - format: int32 - Environment: - type: string - Path: + uuid: type: string - CarveSize: + type: object + types.CarvesPagedResponse: + properties: + items: + items: + $ref: "#/components/schemas/queries.DistributedQuery" + type: array + page: type: integer - format: int32 - BlockSize: + page_size: type: integer - format: int32 - TotalBlocks: + total_items: type: integer - format: int32 - CompletedBlocks: + total_pages: type: integer - format: int32 - Status: - type: string - CompletedAt: - type: string - format: date-time - Carver: - type: string - Archived: + type: object + types.EnvAccessView: + properties: + admin: + type: boolean + carve: + type: boolean + query: + type: boolean + user: type: boolean - ArchivePath: - type: string - EnvironmentID: - type: integer - format: int32 - AdminUser: type: object + types.EnvConfigPatchRequest: properties: - ID: - type: integer - format: int32 - CreatedAt: + atc: type: string - format: date-time - UpdatedAt: + decorators: type: string - format: date-time - DeletedAt: + flags: type: string - format: date-time - Username: + options: type: string - Email: + packs: type: string - Fullname: + schedule: type: string - PassHash: + type: object + types.EnvConfigResponse: + properties: + atc: type: string - APIToken: + decorators: type: string - TokenExpire: + flags: type: string - format: date-time - Admin: - type: boolean - UUID: + options: + type: string + packs: type: string - CSRFToken: + schedule: type: string - LastIPAddress: + type: object + types.EnvCreateRequest: + properties: + hostname: type: string - LastUserAgent: + icon: type: string - LastAccess: + name: type: string - format: date-time - LastTokenUse: + type: type: string - format: date-time - EnvironmentID: - type: integer - format: int32 - TLSEnvironment: type: object + types.EnvExpirationPatchRequest: properties: - ID: + action: + type: string + type: object + types.EnvIntervalsPatchRequest: + properties: + config_interval: + type: integer + log_interval: type: integer - format: int32 - CreatedAt: + query_interval: + type: integer + type: object + types.EnvUpdateRequest: + properties: + accept_enrolls: + type: boolean + debug_http: + type: boolean + hostname: + type: string + icon: type: string - format: date-time - UpdatedAt: + name: + type: string + type: type: string - format: date-time - DeletedAt: + type: object + types.GetPermissionsResponse: + properties: + permissions: + additionalProperties: + $ref: "#/components/schemas/types.EnvAccessView" + type: object + username: type: string - format: date-time - Name: + type: object + types.LoginEnvironment: + properties: + name: type: string - Hostname: + uuid: type: string - Secret: + type: object + types.NodeEnrichment: + properties: + bios: + $ref: "#/components/schemas/types.BIOSInfo" + os: + $ref: "#/components/schemas/types.OSInfo" + osquery: + $ref: "#/components/schemas/types.OsqueryRuntime" + system: + $ref: "#/components/schemas/types.SystemInfo" + type: object + types.NodeView: + properties: + bytes_received: + type: integer + config_hash: type: string - EnrollSecretPath: + cpu: type: string - EnrollExpire: + created_at: type: string - format: date-time - RemoveSecretPath: + daemon_hash: type: string - RemoveExpire: + environment: type: string - format: date-time - Type: + environment_id: + type: integer + extra_data: type: string - DebPackage: + hardware_serial: type: string - RpmPackage: + hostname: type: string - MsiPackage: + id: + type: integer + ip_address: type: string - PkgPackage: + last_seen: type: string - DebugHTTP: - type: boolean - Icon: + localname: type: string - Options: + memory: type: string - Schedule: + osquery_user: type: string - Packs: + osquery_version: type: string - Decorators: + platform: type: string - ATC: + platform_version: type: string - Configuration: + system_info: + $ref: "#/components/schemas/types.NodeEnrichment" + updated_at: type: string - Flags: + user_id: + type: integer + username: type: string - Certificate: + uuid: type: string - ConfigTLS: - type: boolean - ConfigInterval: + type: object + types.NodesPagedResponse: + properties: + items: + items: + $ref: "#/components/schemas/types.NodeView" + type: array + page: type: integer - format: int32 - LoggingTLS: - type: boolean - LogInterval: + page_size: type: integer - format: int32 - QueryTLS: - type: boolean - QueryInterval: + total_items: type: integer - format: int32 - CarvesTLS: - type: boolean - EnrollPath: + total_pages: + type: integer + type: object + types.OSInfo: + properties: + codename: type: string - LogPath: + major: type: string - ConfigPath: + minor: type: string - QueryReadPath: + name: type: string - QueryWritePath: + patch: type: string - CarverInitPath: + platform: type: string - CarverBlockPath: + platform_like: + type: string + version: type: string - AcceptEnrolls: - type: boolean - UserID: - type: integer - format: int32 - AdminTag: type: object + types.OsqueryRuntime: properties: - ID: - type: integer - format: int32 - CreatedAt: + build_distro: type: string - format: date-time - UpdatedAt: + build_platform: type: string - format: date-time - DeletedAt: + config_valid: type: string - format: date-time - Name: + extensions: type: string - Description: + start_time: type: string - Color: + version: type: string - Icon: + type: object + types.OsqueryTable: + properties: + filter: + type: string + name: + type: string + platforms: + items: + type: string + type: array + url: + type: string + type: object + types.PasswordChangeRequest: + properties: + current_password: type: string - CreatedBy: + new_password: + type: string + type: object + types.QueriesPagedResponse: + properties: + items: + items: + $ref: "#/components/schemas/queries.DistributedQuery" + type: array + page: + type: integer + page_size: + type: integer + total_items: + type: integer + total_pages: + type: integer + type: object + types.QueryResultsResponse: + properties: + items: + items: + additionalProperties: {} + type: object + type: array + page: + type: integer + page_size: + type: integer + since: type: string - SettingValue: + total_items: + type: integer + total_pages: + type: integer type: object + types.SavedQueriesPagedResponse: properties: - ID: + items: + items: + $ref: "#/components/schemas/types.SavedQueryView" + type: array + page: + type: integer + page_size: + type: integer + total_items: + type: integer + total_pages: type: integer - format: int32 - CreatedAt: + type: object + types.SavedQueryCreateRequest: + properties: + name: + type: string + query: type: string - format: date-time - UpdatedAt: + type: object + types.SavedQueryUpdateRequest: + properties: + query: type: string - format: date-time - DeletedAt: + type: object + types.SavedQueryView: + properties: + created_at: type: string - format: date-time - Name: + creator: type: string - Service: + environment_id: + type: integer + extra_data: type: string - EnvironmentID: + id: type: integer - format: int32 - JSON: - type: boolean - Type: + name: + type: string + query: + type: string + updated_at: type: string - String: + type: object + types.SetPermissionsAllRequest: + properties: + access: + $ref: "#/components/schemas/types.EnvAccessView" + type: object + types.SetPermissionsAllResponse: + properties: + access: + $ref: "#/components/schemas/types.EnvAccessView" + total: + type: integer + updated: + type: integer + type: object + types.SetPermissionsRequest: + properties: + access: + $ref: "#/components/schemas/types.EnvAccessView" + env_uuid: type: string - Boolean: + type: object + types.SettingPatchRequest: + properties: + boolean: type: boolean - Integer: + integer: type: integer - format: int64 - Info: + string: + type: string + type: type: string - ApiActionsRequest: type: object + types.SystemInfo: properties: - Certificate: + computer_name: type: string - MacPkgURL: + cpu_brand: type: string - MsiPkgURL: + cpu_logical_cores: type: string - RpmPkgURL: + cpu_physical_cores: type: string - DebPkgURL: + cpu_subtype: type: string - ApiTagsRequest: - type: object - properties: - Name: + cpu_type: type: string - Description: + hardware_model: type: string - Color: + hardware_serial: type: string - Icon: + hardware_vendor: type: string - EnvUUID: + hardware_version: type: string - TagType: - type: integer - format: uint32 - Custom: + local_hostname: type: string - ApiLookupRequest: - type: object - properties: - Identifier: + physical_memory: type: string - ApiLookupResponse: type: object + types.TLSEnvironmentView: properties: - ID: + accept_enrolls: + type: boolean + carves_tls: + type: boolean + config_interval: type: integer - format: int32 - UUID: - type: string - Hostname: + config_tls: + type: boolean + created_at: type: string - Localname: + debug_http: + type: boolean + enroll_expire: type: string - IPAddress: + hostname: type: string - Username: + icon: type: string - HardwareSerial: + id: + type: integer + log_interval: + type: integer + logging_tls: + type: boolean + name: type: string - Platform: + query_interval: + type: integer + query_tls: + type: boolean + remove_expire: type: string - PlatformVersion: + type: type: string - OsqueryVersion: + updated_at: type: string - Environment: + uuid: type: string - EnvironmentUUID: + type: object + types.TokenResponse: + properties: + expires: type: string - LastSeen: + token: type: string - MapEnvByID: type: object + types.UserMePatchRequest: properties: - ID: - type: integer - format: int32 - Name: + email: type: string - UUID: + fullname: type: string - additionalProperties: - type: integer - MapEnvByString: type: object + types.UserMeResponse: properties: - ID: - type: integer - format: int32 - Name: + admin: + type: boolean + email: + type: string + fullname: type: string - UUID: + last_access: type: string - additionalProperties: - type: string - securitySchemes: - Authorization: - type: http - scheme: bearer - bearerFormat: JWT + permissions: + additionalProperties: + $ref: "#/components/schemas/types.EnvAccessView" + type: object + service: + type: boolean + token_expire: + type: string + username: + type: string + uuid: + type: string + type: object diff --git a/tools/update-openapi.sh b/tools/update-openapi.sh new file mode 100755 index 00000000..65254cbb --- /dev/null +++ b/tools/update-openapi.sh @@ -0,0 +1,77 @@ +#!/usr/bin/env bash +set -euo pipefail + +usage() { + cat <<'EOF' +Usage: tools/update-openapi.sh [--check] + +Regenerates the Swagger 2 spec from API annotations and converts it to the +root OpenAPI 3 spec. + +Options: + --check Verify osctrl-api.yaml is up to date without modifying it. +EOF +} + +check_mode=0 +if [[ "${1:-}" == "--check" ]]; then + check_mode=1 + shift +fi + +if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then + usage + exit 0 +fi + +if [[ $# -ne 0 ]]; then + usage + exit 2 +fi + +script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +repo_root="$(cd "${script_dir}/.." && pwd)" +openapi_yaml="${repo_root}/osctrl-api.yaml" +converter_version="${SWAGGER2OPENAPI_VERSION:-7.0.8}" + +if ! command -v npx >/dev/null 2>&1; then + echo "error: npx is required to run swagger2openapi" >&2 + exit 1 +fi + +cd "${repo_root}" + +tmp_dir="$(mktemp -d)" +tmp_openapi="${tmp_dir}/osctrl-api.yaml" +trap 'rm -rf "${tmp_dir}"' EXIT + +if [[ "${check_mode}" -eq 1 ]]; then + swagger_output_dir="${tmp_dir}/docs" +else + swagger_output_dir="${repo_root}/cmd/api/docs" +fi + +make SWAG_OUTPUT_DIR="${swagger_output_dir}" swagger + +swagger_yaml="${swagger_output_dir}/swagger.yaml" + +if [[ ! -s "${swagger_yaml}" ]]; then + echo "error: generated Swagger file is missing or empty: ${swagger_yaml}" >&2 + exit 1 +fi + +npx --yes "swagger2openapi@${converter_version}" \ + --patch \ + --yaml \ + --outfile "${tmp_openapi}" \ + "${swagger_yaml}" + +if [[ "${check_mode}" -eq 1 ]]; then + if ! cmp -s "${tmp_openapi}" "${openapi_yaml}"; then + echo "error: ${openapi_yaml} is out of date. Run tools/update-openapi.sh and commit the result." >&2 + exit 1 + fi + exit 0 +fi + +mv "${tmp_openapi}" "${openapi_yaml}"