Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Protect agent reporting and configuration authority
rcourtman7ed7fddb813f
diff --git a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md b/docs/release-control/v6/internal/subsystems/agent-lifecycle.mdindex 93105b0f8c..37d8c32ae7 100644--- a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md+++ b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md@@ -3063,6 +3063,13 @@ It uses monitoring-read authority and exact published PNG references. It mustnot accept agent-report credentials as image authority or reinterpret releasescreenshots as enrollment, update readiness or lifecycle verification.+Agent report ingestion and Docker acknowledgements use the organization-admin+session boundary alongside their existing agent-token scopes. Agent config+reads use the same session boundary and retain token-to-host binding. A viewer+session must not impersonate a collector or read its assigned execution+credentials. These checks preserve collector tokens and the existing local+unauthenticated bootstrap behavior.+1. Add or change install-command generation, canonical /api/auto-register behavior, or installer download behavior through the owned `internal/api/` files above.Canonical `/api/auto-register` auth is split by intent: when the setup-tokenbootstrap path succeeds, lifecycle clients must complete registration withdiff --git a/docs/release-control/v6/internal/subsystems/api-contracts.md b/docs/release-control/v6/internal/subsystems/api-contracts.mdindex 291d49f773..8dbb6b9ea5 100644--- a/docs/release-control/v6/internal/subsystems/api-contracts.md+++ b/docs/release-control/v6/internal/subsystems/api-contracts.md@@ -11302,7 +11302,11 @@ The canonical host lifecycle routes are`POST /api/agent-install-command`; the `/api/agents/host/` forms remain legacyaliases only. Deletion and manual allowance require an authenticated admincredential with `settings:write`. Report and config reads retain their-agent-report/config scope gates and exact token-to-agent binding.+agent-report/config scope gates and exact token-to-agent binding. Host, Docker+and Kubernetes telemetry writes, Docker command acknowledgements, and agent+configuration reads also require organization-admin authority for browser or+proxy identities. Scoped agent tokens retain their existing admission and+binding rules; a token scope check alone does not authorize a browser session.A successful delete means the durable removal tombstone exists before the APIreturns. Journal persistence failure returns `500 agent_removal_failed` anddiff --git a/docs/release-control/v6/internal/subsystems/registry.json b/docs/release-control/v6/internal/subsystems/registry.jsonindex fa675c0b76..15a4c3e940 100644--- a/docs/release-control/v6/internal/subsystems/registry.json+++ b/docs/release-control/v6/internal/subsystems/registry.json@@ -3249,7 +3249,8 @@"allow_same_subsystem_tests": false,"test_prefixes": [],"exact_files": [- "internal/api/route_inventory_test.go"+ "internal/api/route_inventory_test.go",+ "internal/api/security_advisory_agent_authority_test.go"]},{diff --git a/docs/release-control/v6/internal/subsystems/storage-recovery.md b/docs/release-control/v6/internal/subsystems/storage-recovery.mdindex c37bff5f0d..fdc93db926 100644--- a/docs/release-control/v6/internal/subsystems/storage-recovery.md+++ b/docs/release-control/v6/internal/subsystems/storage-recovery.md@@ -2719,7 +2719,7 @@ recovery scope, or a storage/recovery-owned secret source.must not be reused as recovery entry points or storage/recovery navigationaliases.25. Keep alert-side recovery follow-up inside the owning platform tab. The resource-incident panel offers no recovery links today, and no shared recovery query vocabulary exists. A future alert-side recovery follow-up for TrueNAS or another API-backed platform must open the platform tab that owns those rows instead of freezing alert-local recovery URLs or reviving the retired Recovery aggregate route.-26. Keep VMware onboarding runtime and recovery semantics separate on that same adjacent platform-connections contract. When `internal/api/router.go`, `internal/api/router_routes_registration.go`, or `internal/api/vmware_handlers.go` evolve VMware connection CRUD, poller-owned `poll` / `observed` summary payloads, saved-test refresh, or observed datastore/VM snapshot visibility, storage and recovery may consume the resulting shared context but must not treat those onboarding/runtime payloads as canonical recovery artifacts, restore capability, or recovery-local control transport.+26. Keep VMware onboarding runtime and recovery semantics separate on that same adjacent platform-connections contract. When `internal/api/router.go`, `internal/api/router_routes_registration.go`, or `internal/api/vmware_handlers.go` evolve VMware connection CRUD, poller-owned `poll` / `observed` summary payloads, saved-test refresh, or observed datastore/VM snapshot visibility, storage and recovery may consume the resulting shared context but must not treat those onboarding/runtime payloads as canonical recovery artifacts, restore capability, or recovery-local control transport. The shared route registry's agent-ingest authorization also does not grant recovery authority or change VMware onboarding.A successful VMware connection test with `degraded` optional signal orperformance diagnostics remains connection-readiness context only; storageand recovery must not reinterpret that warning as datastore protectiondiff --git a/internal/api/router_routes_registration.go b/internal/api/router_routes_registration.goindex 662d78363d..5e97fe71df 100644--- a/internal/api/router_routes_registration.go+++ b/internal/api/router_routes_registration.go@@ -52,13 +52,16 @@ func (r *Router) registerConfigSystemRoutes(updateHandlers *UpdateHandlers) {http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)}})- r.mux.HandleFunc("/api/agents/docker/report", RequireAuth(r.config, RequireScope(config.ScopeDockerReport, r.dockerAgentHandlers.HandleReport)))- r.mux.HandleFunc("/api/agents/kubernetes/report", RequireAuth(r.config, RequireScope(config.ScopeKubernetesReport, r.kubernetesAgentHandlers.HandleReport)))- r.mux.HandleFunc("/api/agents/agent/report", RequireAuth(r.config, RequireScope(config.ScopeAgentReport, r.unifiedAgentHandlers.HandleReport)))+ // Agent scopes constrain token callers. Browser and proxy identities do not+ // have token scopes, so require organization administration for their+ // telemetry writes and agent command acknowledgements.+ r.mux.HandleFunc("/api/agents/docker/report", RequireOrgAdmin(r.config, RequireScope(config.ScopeDockerReport, r.dockerAgentHandlers.HandleReport)))+ r.mux.HandleFunc("/api/agents/kubernetes/report", RequireOrgAdmin(r.config, RequireScope(config.ScopeKubernetesReport, r.kubernetesAgentHandlers.HandleReport)))+ r.mux.HandleFunc("/api/agents/agent/report", RequireOrgAdmin(r.config, RequireScope(config.ScopeAgentReport, r.unifiedAgentHandlers.HandleReport)))r.mux.HandleFunc("/api/agents/action-runner/credential", RequireAuth(r.config, actionRunnerCredentialRoute(r.config, r.handleIssueActionRunnerCredential, r.handleActivateActionRunnerCredential, r.handleSelfRevokeActionRunnerCredential)))r.mux.HandleFunc("/api/agents/action-runner/credential/activation", RequireAuth(r.config, RequireScope(config.ScopeAgentExec, r.handleCancelPendingActionRunnerCredentialActivation)))r.mux.HandleFunc("/api/agents/collector/reduce-authority", RequireAuth(r.config, RequireScope(config.ScopeAgentReport, r.handleReduceCollectorAuthority)))- r.mux.HandleFunc("/api/agents/host/report", wrapLegacyHostAlias("/api/agents/host/report", RequireAuth(r.config, RequireScope(config.ScopeAgentReport, r.unifiedAgentHandlers.HandleReport))))+ r.mux.HandleFunc("/api/agents/host/report", wrapLegacyHostAlias("/api/agents/host/report", RequireOrgAdmin(r.config, RequireScope(config.ScopeAgentReport, r.unifiedAgentHandlers.HandleReport))))r.mux.HandleFunc("/api/agents/agent/lookup", RequireAuth(r.config, RequireScope(config.ScopeAgentReport, r.unifiedAgentHandlers.HandleLookup)))r.mux.HandleFunc("/api/agents/host/lookup", wrapLegacyHostAlias("/api/agents/host/lookup", RequireAuth(r.config, RequireScope(config.ScopeAgentReport, r.unifiedAgentHandlers.HandleLookup))))// Uninstall is a collector's self-removal by token. Anything that is not a@@ -87,7 +90,10 @@ func (r *Router) registerConfigSystemRoutes(updateHandlers *UpdateHandlers) {})(w, req)return}- r.unifiedAgentHandlers.HandleConfig(w, req)+ // Agent configuration may contain credentials for assigned probes.+ // Token ownership and scope are checked by HandleConfig; session and+ // proxy callers must also have administrative authority.+ RequireOrgAdmin(r.config, r.unifiedAgentHandlers.HandleConfig)(w, req)return}// Route POST /api/agents/agent/{id}/allow-reenroll to HandleAllowReenroll@@ -119,7 +125,7 @@ func (r *Router) registerConfigSystemRoutes(updateHandlers *UpdateHandlers) {}r.mux.HandleFunc("/api/agents/agent/", RequireAuth(r.config, unifiedAgentManagementCore))r.mux.HandleFunc("/api/agents/host/", wrapLegacyHostAlias("/api/agents/host/", RequireAuth(r.config, unifiedAgentManagementCore)))- r.mux.HandleFunc("/api/agents/docker/commands/", RequireAuth(r.config, RequireScope(config.ScopeDockerReport, r.dockerAgentHandlers.HandleCommandAck)))+ r.mux.HandleFunc("/api/agents/docker/commands/", RequireOrgAdmin(r.config, RequireScope(config.ScopeDockerReport, r.dockerAgentHandlers.HandleCommandAck)))r.mux.HandleFunc("/api/agents/docker/runtimes/", RequireOrgAdmin(r.config, RequireScope(config.ScopeDockerManage, r.dockerAgentHandlers.HandleDockerHostActions)))r.mux.HandleFunc("/api/agents/docker/containers/update", RequireAdmin(r.config, RequireScope(config.ScopeDockerManage, r.dockerAgentHandlers.HandleContainerUpdate)))r.mux.HandleFunc("/api/agents/kubernetes/clusters/", RequireOrgAdmin(r.config, RequireScope(config.ScopeKubernetesManage, r.kubernetesAgentHandlers.HandleClusterActions)))diff --git a/internal/api/security_advisory_agent_authority_test.go b/internal/api/security_advisory_agent_authority_test.gonew file mode 100644index 0000000000..7881102859--- /dev/null+++ b/internal/api/security_advisory_agent_authority_test.go@@ -0,0 +1,249 @@+package api++import (+ "context"+ "net/http"+ "net/http/httptest"+ "strings"+ "testing"+ "time"++ "github.com/rcourtman/pulse-go-rewrite/internal/api/apicontext"+ "github.com/rcourtman/pulse-go-rewrite/internal/config"+ "github.com/rcourtman/pulse-go-rewrite/internal/models"+ "github.com/rcourtman/pulse-go-rewrite/internal/monitoring"+ internalauth "github.com/rcourtman/pulse-go-rewrite/pkg/auth"+)++func agentAuthorityRouter(t *testing.T, withMonitor bool, tokens ...config.APITokenRecord) (*Router, *monitoring.Monitor) {+ t.Helper()+ dir := t.TempDir()+ t.Setenv("PULSE_DATA_DIR", dir)+ hash, err := internalauth.HashPassword("OriginalPass!1")+ if err != nil {+ t.Fatal(err)+ }+ cfg := &config.Config{DataPath: dir, ConfigPath: dir, AuthUser: "instance-admin", AuthPass: hash, APITokens: tokens}+ InitSessionStore(dir)+ var monitor *monitoring.Monitor+ if withMonitor {+ monitor, err = monitoring.New(cfg)+ if err != nil {+ t.Fatal(err)+ }+ t.Cleanup(monitor.Stop)+ }+ router := NewRouter(cfg, monitor, nil, nil, func() error { return nil }, "test")+ cleanupTestRouter(t, router)+ return router, monitor+}++func agentAuthorityRequest(t *testing.T, method, path, body, session, token string) *http.Request {+ t.Helper()+ req := httptest.NewRequest(method, path, strings.NewReader(body))+ req.Header.Set("Content-Type", "application/json")+ if session != "" {+ req.AddCookie(&http.Cookie{Name: "pulse_session", Value: session})+ req.Header.Set("X-CSRF-Token", generateCSRFToken(session))+ }+ if token != "" {+ req.Header.Set("X-API-Token", token)+ }+ return req+}++func TestAgentIngestRoutesRequireAuthorityForSessions(t *testing.T) {+ const hostToken = "host-report-fixture.12345678"+ const dockerToken = "docker-report-fixture.12345678"+ const kubeToken = "kubernetes-report-fixture.12345678"+ const otherToken = "monitor-read-fixture.12345678"+ router, _ := agentAuthorityRouter(t, false,+ newTokenRecord(t, hostToken, []string{config.ScopeAgentReport}, nil),+ newTokenRecord(t, dockerToken, []string{config.ScopeDockerReport}, nil),+ newTokenRecord(t, kubeToken, []string{config.ScopeKubernetesReport}, nil),+ newTokenRecord(t, otherToken, []string{config.ScopeMonitoringRead}, nil),+ )+ viewer := generateSessionToken()+ GetSessionStore().CreateSession(viewer, time.Hour, "browser", "127.0.0.1", "viewer")+ admin := generateSessionToken()+ GetSessionStore().CreateSession(admin, time.Hour, "browser", "127.0.0.1", "instance-admin")+ for _, tc := range []struct{ method, path, token string }{+ {http.MethodPost, "/api/agents/agent/report", hostToken},+ {http.MethodPost, "/api/agents/host/report", hostToken},+ {http.MethodPost, "/api/agents/docker/report", dockerToken},+ {http.MethodPost, "/api/agents/kubernetes/report", kubeToken},+ {http.MethodPost, "/api/agents/docker/commands/test/ack", dockerToken},+ {http.MethodGet, "/api/agents/agent/host-1/config", hostToken},+ {http.MethodGet, "/api/agents/host/host-1/config", hostToken},+ } {+ t.Run(tc.path, func(t *testing.T) {+ for _, identity := range []struct {+ name, session, token string+ denied bool+ }{+ {"viewer", viewer, "", true},+ {"unrelated token", "", otherToken, true},+ {"administrator", admin, "", false},+ {"agent token", "", tc.token, false},+ } {+ t.Run(identity.name, func(t *testing.T) {+ rec := httptest.NewRecorder()+ router.Handler().ServeHTTP(rec, agentAuthorityRequest(t, tc.method, tc.path, "{", identity.session, identity.token))+ if identity.denied && rec.Code != http.StatusForbidden {+ t.Fatalf("status=%d, want 403: %s", rec.Code, rec.Body.String())+ }+ if !identity.denied && (rec.Code == http.StatusUnauthorized || rec.Code == http.StatusForbidden) {+ t.Fatalf("authorized identity denied: status=%d %s", rec.Code, rec.Body.String())+ }+ })+ }+ })+ }+}++func TestAgentConfigProtectsAvailabilityCredentialsFromViewer(t *testing.T) {+ const agentToken = "agent-config-fixture.12345678"+ record := newTokenRecord(t, agentToken, []string{config.ScopeAgentConfigRead}, nil)+ router, monitor := agentAuthorityRouter(t, true, record)+ hostID := seedUnifiedAgentHost(t, monitor)+ for _, host := range monitor.GetLiveHostsSnapshot() {+ if host.ID == hostID {+ host.TokenID = record.ID+ monitorState(t, monitor).UpsertHost(host)+ }+ }+ monitor.SetLicenseChecker(func(string) bool { return true })+ secret := "synthetic-probe-credential"+ target := config.NormalizeAvailabilityTarget(config.AvailabilityTarget{+ ID: "probe", Name: "fixture", Address: "example.invalid", Protocol: config.AvailabilityProbeHTTPS,+ Enabled: true, ProbeAgentID: hostID,+ HTTP: &config.AvailabilityHTTPConfig{Authentication: config.AvailabilityHTTPAuthentication{+ Type: config.AvailabilityHTTPAuthBearer, BearerToken: &secret,+ }},+ })+ if err := config.NewConfigPersistence(router.config.DataPath).SaveAvailabilityTargets([]config.AvailabilityTarget{target}); err != nil {+ t.Fatal(err)+ }+ viewer := generateSessionToken()+ GetSessionStore().CreateSession(viewer, time.Hour, "browser", "127.0.0.1", "viewer")+ admin := generateSessionToken()+ GetSessionStore().CreateSession(admin, time.Hour, "browser", "127.0.0.1", "instance-admin")+ for _, identity := range []struct {+ name, session, token string+ allowed bool+ }{+ {"viewer", viewer, "", false},+ {"administrator", admin, "", true},+ {"bound agent", "", agentToken, true},+ } {+ t.Run(identity.name, func(t *testing.T) {+ rec := httptest.NewRecorder()+ path := "/api/agents/agent/" + hostID + "/config"+ router.Handler().ServeHTTP(rec, agentAuthorityRequest(t, http.MethodGet, path, "", identity.session, identity.token))+ if identity.allowed {+ if rec.Code != http.StatusOK || !strings.Contains(rec.Body.String(), secret) {+ t.Fatalf("authorized config did not carry assigned credential: status=%d body=%s", rec.Code, rec.Body.String())+ }+ } else if rec.Code != http.StatusForbidden || strings.Contains(rec.Body.String(), secret) {+ t.Fatalf("viewer received config: status=%d body=%s", rec.Code, rec.Body.String())+ }+ })+ }+}++func TestAgentReportRejectsViewerWithoutChangingState(t *testing.T) {+ const token = "host-ingest-fixture.12345678"+ router, monitor := agentAuthorityRouter(t, true,+ newTokenRecord(t, token, []string{config.ScopeAgentReport}, nil),+ )+ viewer := generateSessionToken()+ GetSessionStore().CreateSession(viewer, time.Hour, "browser", "127.0.0.1", "viewer")+ body := `{"agent":{"id":"fixture-agent","version":"1"},"host":{"id":"fixture-host","hostname":"fixture.example.invalid","platform":"linux"}}`+ path := "/api/agents/agent/report"+ rec := httptest.NewRecorder()+ router.Handler().ServeHTTP(rec, agentAuthorityRequest(t, http.MethodPost, path, body, viewer, ""))+ if rec.Code != http.StatusForbidden || len(monitor.GetLiveHostsSnapshot()) != 0 {+ t.Fatalf("viewer report status=%d hosts=%v", rec.Code, monitor.GetLiveHostsSnapshot())+ }+ rec = httptest.NewRecorder()+ router.Handler().ServeHTTP(rec, agentAuthorityRequest(t, http.MethodPost, path, body, "", token))+ if rec.Code != http.StatusOK || len(monitor.GetLiveHostsSnapshot()) != 1 {+ t.Fatalf("agent report status=%d hosts=%v body=%s", rec.Code, monitor.GetLiveHostsSnapshot(), rec.Body.String())+ }+}++func TestAgentIngestRoutesRespectProxyRolesAndLocalBootstrap(t *testing.T) {+ for _, mode := range []string{"proxy", "local bootstrap"} {+ t.Run(mode, func(t *testing.T) {+ dir := t.TempDir()+ cfg := &config.Config{DataPath: dir, ConfigPath: dir}+ if mode == "proxy" {+ cfg.ProxyAuthSecret = "synthetic-proxy-secret"+ cfg.ProxyAuthUserHeader = "X-Remote-User"+ cfg.ProxyAuthRoleHeader = "X-Remote-Roles"+ cfg.ProxyAuthAdminRole = "admin"+ }+ router := NewRouter(cfg, nil, nil, nil, nil, "test")+ cleanupTestRouter(t, router)+ for _, path := range []string{+ "/api/agents/agent/report", "/api/agents/host/report",+ "/api/agents/docker/report", "/api/agents/kubernetes/report",+ "/api/agents/docker/commands/test/ack", "/api/agents/agent/host-1/config",+ } {+ method := http.MethodPost+ if strings.HasSuffix(path, "/config") {+ method = http.MethodGet+ }+ roles := []string{"viewer", "admin"}+ if mode == "local bootstrap" {+ roles = []string{"local"}+ }+ for _, role := range roles {+ req := newLoopbackRequest(method, path, strings.NewReader("{"))+ if mode == "proxy" {+ req.Header.Set("X-Proxy-Secret", cfg.ProxyAuthSecret)+ req.Header.Set("X-Remote-User", "proxy-user")+ req.Header.Set("X-Remote-Roles", role)+ }+ rec := httptest.NewRecorder()+ router.Handler().ServeHTTP(rec, req)+ if role == "viewer" && rec.Code != http.StatusForbidden {+ t.Errorf("%s proxy viewer status=%d, want 403", path, rec.Code)+ } else if role != "viewer" && (rec.Code == http.StatusUnauthorized || rec.Code == http.StatusForbidden) {+ t.Errorf("%s %s denied: status=%d %s", path, role, rec.Code, rec.Body.String())+ }+ }+ }+ })+ }+}++func TestAgentIngestRoutesRespectOrganizationSessionRoles(t *testing.T) {+ router, _ := agentAuthorityRouter(t, false)+ org := &models.Organization{ID: "org-a", OwnerUserID: "tenant-owner", Members: []models.OrganizationMember{+ {UserID: "tenant-viewer", Role: models.OrgRoleViewer},+ }}+ for _, identity := range []struct {+ user string+ allowed bool+ }{{"tenant-owner", true}, {"tenant-viewer", false}} {+ for _, path := range []string{"/api/agents/agent/report", "/api/agents/agent/host-1/config"} {+ method := http.MethodPost+ if strings.HasSuffix(path, "/config") {+ method = http.MethodGet+ }+ session := generateSessionToken()+ GetSessionStore().CreateSession(session, time.Hour, "browser", "127.0.0.1", identity.user)+ req := agentAuthorityRequest(t, method, path, "{", session, "")+ req = req.WithContext(context.WithValue(req.Context(), apicontext.OrgContextKey, org))+ rec := httptest.NewRecorder()+ // The tenant middleware normally installs this organization context.+ router.mux.ServeHTTP(rec, req)+ if identity.allowed && (rec.Code == http.StatusUnauthorized || rec.Code == http.StatusForbidden) {+ t.Errorf("%s %s denied: status=%d %s", identity.user, path, rec.Code, rec.Body.String())+ } else if !identity.allowed && rec.Code != http.StatusForbidden {+ t.Errorf("%s %s status=%d, want 403", identity.user, path, rec.Code)+ }+ }+ }+}