From 95527b39565f377a9ca459d1ea6a54fb0c6aa77f Mon Sep 17 00:00:00 2001 From: mrhid6 Date: Thu, 13 Aug 2026 08:31:20 +0000 Subject: [PATCH] fix: Exclude /install and /update scripts from the OpenAPI document MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit handleInstallScript and handleUpdateScript are registered on the bare gin engine at /install and /update, outside the /api group the generated document's BasePath assumes. Their @Router annotations therefore published /api/install and /api/update, paths that 404 — the reference page told a reader to curl a URL that does not exist. Removed the swag annotations from both handlers (replaced with a plain comment explaining why) rather than adding a corrected @Router, since swag has no per-route BasePath override and there is nothing lost by leaving two shell-script endpoints out of a JSON API reference — their .ps1 counterparts were already undocumented for the same reason. Regenerated internal/api/docs/openapi.json accordingly. --- server/internal/api/docs/openapi.json | 64 +-------------------------- server/internal/api/handlers.go | 31 ++++++------- 2 files changed, 14 insertions(+), 81 deletions(-) diff --git a/server/internal/api/docs/openapi.json b/server/internal/api/docs/openapi.json index 94a528b..ca00a52 100644 --- a/server/internal/api/docs/openapi.json +++ b/server/internal/api/docs/openapi.json @@ -3129,47 +3129,6 @@ ] } }, - "/install": { - "get": { - "description": "Dynamically generated shell script that downloads, verifies and installs the agent, seeded with a pre-registration token.", - "parameters": [ - { - "description": "Server ID", - "in": "query", - "name": "server_id", - "required": true, - "schema": { - "type": "string" - } - }, - { - "description": "Pre-registration token", - "in": "query", - "name": "token", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "content": { - "text/plain": { - "schema": { - "type": "string" - } - } - }, - "description": "shell script" - } - }, - "summary": "Agent install script (Linux)", - "tags": [ - "install" - ] - } - }, "/instance/users": { "get": { "responses": { @@ -7140,7 +7099,7 @@ ] }, "post": { - "description": "The plaintext token is returned exactly once and stored nowhere. A token's role and scopes cannot exceed the creator's own.", + "description": "The plaintext token is returned exactly once and stored nowhere. A token's role cannot exceed the creator's own; when the request is itself token-authenticated, its scopes cannot exceed the calling token's scopes either.", "requestBody": { "content": { "application/json": { @@ -7335,27 +7294,6 @@ ] } }, - "/update": { - "get": { - "description": "Dynamically generated shell script that downloads and installs the latest agent.", - "responses": { - "200": { - "content": { - "text/plain": { - "schema": { - "type": "string" - } - } - }, - "description": "shell script" - } - }, - "summary": "Agent update script (Linux)", - "tags": [ - "install" - ] - } - }, "/vuln-rules": { "get": { "responses": { diff --git a/server/internal/api/handlers.go b/server/internal/api/handlers.go index 08c1334..0f8c15e 100644 --- a/server/internal/api/handlers.go +++ b/server/internal/api/handlers.go @@ -711,14 +711,13 @@ func applyUpdates(c *gin.Context) { c.JSON(http.StatusAccepted, MessageResponse{Message: "apply updates command sent to agent"}) } -// handleUpdateScript godoc -// -// @Summary Agent update script (Linux) -// @Description Dynamically generated shell script that downloads and installs the latest agent. -// @Tags install -// @Produce plain -// @Success 200 {string} string "shell script" -// @Router /update [get] +// handleUpdateScript serves a dynamically generated shell script that +// downloads and installs the latest agent. Deliberately not in the generated +// OpenAPI document: it is registered on the bare engine, not under the /api +// group the document's BasePath assumes, so a @Router annotation here would +// publish /api/update — a path that 404s — rather than the real top-level +// /update. It serves a shell script, not JSON, so there is nothing lost by +// leaving it out of a JSON API reference. func handleUpdateScript(c *gin.Context) { giteaHost := "gitea.hostxtra.co.uk" @@ -878,16 +877,12 @@ func saveSettings(c *gin.Context) { c.JSON(http.StatusOK, SavedResponse{Saved: true}) } -// handleInstallScript godoc -// -// @Summary Agent install script (Linux) -// @Description Dynamically generated shell script that downloads, verifies and installs the agent, seeded with a pre-registration token. -// @Tags install -// @Produce plain -// @Param server_id query string true "Server ID" -// @Param token query string true "Pre-registration token" -// @Success 200 {string} string "shell script" -// @Router /install [get] +// handleInstallScript serves a dynamically generated shell script that +// downloads, verifies and installs the agent, seeded with a pre-registration +// token. Deliberately not in the generated OpenAPI document, for the same +// reason as handleUpdateScript: it is registered on the bare engine, outside +// the /api group the document's BasePath assumes, so a @Router annotation +// would publish a /api/install path that 404s. func handleInstallScript(c *gin.Context) { serverID := c.Query("server_id") token := c.Query("token")