chore(security): P3 batch — placeholder email + swagger gate

Two of the eight P3 audit findings warrant a focused fix; the others are
informational / future-proofing / feature-requests and stay in the
findings doc as backlog.

### P3-1 — SECURITY.md placeholder contact email

SECURITY.md instructed reporters to email security@example.com "(replace
with actual email)" — a TODO that never got replaced. Two call sites
(line 25 and line 213) just stripped both. GitHub Security Advisories
is the recommended path anyway: report stays private to the maintainer
until a fix is ready to ship, doesn't require running a security
inbox, and integrates with CVE numbering when needed.

### P3-2 — Swagger UI gate

`/swagger` and `/swagger/*` were registered unconditionally with no
auth. In production, this lets any unauthenticated caller enumerate
every endpoint + JSON schema of the agent — a fingerprinting aid for
attackers, and the kind of detail that pairs with CVE search to find
known-vulnerable builds. In development the UI is genuinely useful for
debugging the API contract.

Gate behind a new opt-in: GEARBOX_AGENT_SWAGGER_ENABLED=true. Default
is off (production-safe). When enabled, the startup log emits a WARN
making the operator aware the UI is reachable.

config.SwaggerEnabled wires through ServerConfig.SwaggerEnabled to the
NewServer route registration. Existing prod deployments inherit the
default (off) without action.

P3-1 and P3-2 from the 2026-05 security audit.

Author: sarg3nt

SECURITY.md

@@ -19,10 +19,9 @@ Please do not report security vulnerabilities through public GitHub issues, disc
 
 ### 2. Report Privately
 
-Please report security vulnerabilities via one of these methods:
-
-- **GitHub Security Advisories** (Preferred): Use the "Security" tab and click "Report a vulnerability"
-- **Email**: Send details to security@example.com (replace with actual email)
+Please report security vulnerabilities via GitHub Security Advisories: use the
+"Security" tab and click "Report a vulnerability". This keeps the report
+private to the maintainer until a fix is ready to ship.
 
 ### 3. Include the Following Information
 
@@ -208,10 +207,12 @@ Subscribe to the repository to receive notifications of security updates.
 
 ## Contact
 
-For security-related questions or concerns, please contact:
+For security-related questions or concerns, please use GitHub Security
+Advisories on this repository — click the "Security" tab, then "Report a
+vulnerability". Reports stay private to the maintainer until a fix lands.
 
-- **Security Team**: security@example.com (replace with actual email)
-- **GitHub Security**: Use the "Security" tab to report vulnerabilities
+For non-vulnerability security questions (e.g. deployment hardening
+guidance), open a regular GitHub Discussion or issue.
 
 ## License
 

gearbox-agent/cmd/gearbox-agent/main.go

@@ -312,12 +312,13 @@ func main() {
 
 	// Create and start API server
 	serverCfg := api.ServerConfig{
-		ListenAddr: cfg.ListenAddr,
-		APIKey:     apiKey,
-		CertFile:   tlsCfg.CertPath,
-		KeyFile:    tlsCfg.KeyPath,
-		Version:    Version,
-		Logger:     logger,
+		ListenAddr:     cfg.ListenAddr,
+		APIKey:         apiKey,
+		CertFile:       tlsCfg.CertPath,
+		KeyFile:        tlsCfg.KeyPath,
+		Version:        Version,
+		Logger:         logger,
+		SwaggerEnabled: cfg.SwaggerEnabled, // P3-2: off by default; opt in via GEARBOX_AGENT_SWAGGER_ENABLED=true
 	}
 	// Only set MetadataProvider if sync service is configured
 	// (Go interfaces holding nil pointers are not themselves nil)

gearbox-agent/internal/api/server.go

@@ -45,6 +45,13 @@ type ServerConfig struct {
 	WebhookURL     string
 	SyncTrigger    SyncTrigger
 
+	// SwaggerEnabled controls whether the Swagger UI / OpenAPI spec are
+	// served at /swagger and /swagger/*. Useful in development; in
+	// production it lets unauthenticated callers enumerate the agent's
+	// endpoints + schemas. Default false (off in production). See
+	// 2026-05 security audit P3-2.
+	SwaggerEnabled bool
+
 	// WebSocket settings (optional)
 	EventBus *events.Bus
 
@@ -85,9 +92,16 @@ func NewServer(cfg ServerConfig) *Server {
 	// Health endpoint (no auth required, no rate limit)
 	r.Get("/health", handlers.Health)
 
-	// Swagger UI (no auth required)
-	r.Get("/swagger", httpSwagger.Handler(httpSwagger.URL("/swagger/doc.json")))
-	r.Get("/swagger/*", httpSwagger.Handler(httpSwagger.URL("/swagger/doc.json")))
+	// Swagger UI (no auth required) — only served when explicitly enabled.
+	// In production, leaving this on lets unauthenticated callers enumerate
+	// every endpoint + schema, which is a fingerprinting aid for attackers
+	// (2026-05 security audit P3-2). Set SWAGGER_ENABLED=true at deploy
+	// time when debugging an API contract; default off.
+	if cfg.SwaggerEnabled {
+		r.Get("/swagger", httpSwagger.Handler(httpSwagger.URL("/swagger/doc.json")))
+		r.Get("/swagger/*", httpSwagger.Handler(httpSwagger.URL("/swagger/doc.json")))
+		cfg.Logger.Warn("Swagger UI enabled at /swagger; unauth-readable. Disable for production deploys.")
+	}
 
 	// Webhook endpoint (uses GitHub signature verification, not API key)
 	var webhookHandler *WebhookHandler

gearbox-agent/internal/framework/config/config.go

@@ -60,6 +60,12 @@ type Config struct {
 
 	// Certificate renewal detection
 	CertbotTimer string // Custom certbot timer name (default: auto-detect)
+
+	// SwaggerEnabled, when true, serves the Swagger UI + OpenAPI spec at
+	// /swagger and /swagger/*. Off by default to avoid exposing the agent's
+	// endpoint + schema list to unauthenticated callers in production. See
+	// 2026-05 security audit P3-2.
+	SwaggerEnabled bool
 }
 
 // DefaultConfig returns the default configuration.
@@ -152,6 +158,9 @@ func Load() (*Config, error) {
 	// Certificate renewal detection (optional override)
 	cfg.CertbotTimer = os.Getenv("HAPROXY_CERTBOT_TIMER")
 
+	// Swagger UI off by default; opt in for dev / API debugging.
+	cfg.SwaggerEnabled = os.Getenv("GEARBOX_AGENT_SWAGGER_ENABLED") == "true"
+
 	return cfg, nil
 }