Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

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.md
index 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 must
not accept agent-report credentials as image authority or reinterpret release
screenshots 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-token
bootstrap path succeeds, lifecycle clients must complete registration with
diff --git a/docs/release-control/v6/internal/subsystems/api-contracts.md b/docs/release-control/v6/internal/subsystems/api-contracts.md
index 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 legacy
aliases only. Deletion and manual allowance require an authenticated admin
credential 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 API
returns. Journal persistence failure returns `500 agent_removal_failed` and
diff --git a/docs/release-control/v6/internal/subsystems/registry.json b/docs/release-control/v6/internal/subsystems/registry.json
index 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.md
index 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 navigation
aliases.
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 or
performance diagnostics remains connection-readiness context only; storage
and recovery must not reinterpret that warning as datastore protection
diff --git a/internal/api/router_routes_registration.go b/internal/api/router_routes_registration.go
index 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.go
new file mode 100644
index 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)
+ }
+ }
+ }
+}