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
package api
import (
"context"
"crypto/ed25519"
"encoding/json"
"errors"
"fmt"
"net/http"
"strings"
"sync"
"time"
"github.com/rcourtman/pulse-go-rewrite/internal/api/agentbinding"
"github.com/rcourtman/pulse-go-rewrite/internal/api/agenttokens"
"github.com/rcourtman/pulse-go-rewrite/internal/config"
"github.com/rcourtman/pulse-go-rewrite/internal/models"
"github.com/rcourtman/pulse-go-rewrite/internal/monitoring"
"github.com/rcourtman/pulse-go-rewrite/internal/remoteconfig"
"github.com/rcourtman/pulse-go-rewrite/internal/utils"
"github.com/rcourtman/pulse-go-rewrite/internal/websocket"
agentshost "github.com/rcourtman/pulse-go-rewrite/pkg/agents/host"
"github.com/rcourtman/pulse-go-rewrite/pkg/auth"
"github.com/rs/zerolog/log"
)
const (
configSignatureTTL = 15 * time.Minute
agentRoutePrefix = "/api/agents/agent/"
legacyHostRoutePrefix = "/api/agents/host/"
)
var configSigningState struct {
once sync.Once
key ed25519.PrivateKey
err error
}
// UnifiedAgentHandlers manages ingest from the runtime-side Unified Agent module of pulse-agent.
type UnifiedAgentHandlers struct {
baseAgentHandlers
// serverVersion is echoed on report acknowledgements so agents can spot a
// server upgrade on their next report instead of their next hourly update
// check. Empty (the default) omits it from acks.
serverVersion string
// recordReportedIdentity records a report's server-resolved identity on
// its hostname-bound token. Nil (the default) records nothing.
recordReportedIdentity func(organizationID, tokenID, presentedID, hostID, hostname string)
configFetchAudits *agentConfigFetchAuditTracker
}
// SetServerVersion supplies the running server version to include on report
// acknowledgements. Call once at wiring time; an empty version keeps acks
// version-free.
func (h *UnifiedAgentHandlers) SetServerVersion(version string) {
h.serverVersion = strings.TrimSpace(version)
}
// SetReportedIdentityRecorder supplies the canonical token-store binding that
// records the agent identity a report resolves to. Call once at wiring time.
func (h *UnifiedAgentHandlers) SetReportedIdentityRecorder(record func(organizationID, tokenID, presentedID, hostID, hostname string)) {
h.recordReportedIdentity = record
}
func trimUnifiedAgentRoutePath(path string) string {
for _, prefix := range []string{agentRoutePrefix, legacyHostRoutePrefix} {
if strings.HasPrefix(path, prefix) {
return strings.TrimPrefix(path, prefix)
}
}
return path
}
// NewUnifiedAgentHandlers constructs a new handler set for Pulse Unified Agent ingest.
func NewUnifiedAgentHandlers(mtm *monitoring.MultiTenantMonitor, m *monitoring.Monitor, hub *websocket.Hub) *UnifiedAgentHandlers {
return &UnifiedAgentHandlers{
baseAgentHandlers: newBaseAgentHandlers(mtm, m, hub),
configFetchAudits: newAgentConfigFetchAuditTracker(),
}
}
// HandleReport ingests Pulse Unified Agent reports.
func (h *UnifiedAgentHandlers) HandleReport(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
writeErrorResponse(w, http.StatusMethodNotAllowed, "method_not_allowed", "Only POST is allowed", nil)
return
}
var report agentshost.Report
// Support gzip-compressed reports from agents (backward compatible with
// uncompressed), with independent encoded and decoded size limits.
if !decodeCompressedAgentReport(w, r, 256*1024, 1536*1024, &report) {
return
}
if report.Timestamp.IsZero() {
report.Timestamp = time.Now().UTC()
}
monitor := h.requireMonitor(w, r)
if monitor == nil {
return
}
tokenRecord := getAPITokenRecordFromRequest(r)
host, err := monitor.ApplyHostReport(report, tokenRecord)
if err != nil {
writeErrorResponse(w, http.StatusBadRequest, "invalid_report", err.Error(), nil)
return
}
// Name the agent on a token bound only to its hostname, so the token
// carries an identity even if this agent never registers a command channel.
// Only a host the monitor resolved and holds under this token carries its
// token ID; mock mode's discard acknowledgement echoes the presented ID
// unresolved and carries none, whenever mock mode flips. The hostname is
// the report's own, which is what the agent's command registration
// presents: a report the ordering watermark rejects returns the stored
// host, whose hostname may come from a different report. The request's
// token snapshot screens out tokens that are already bound or do not
// qualify without taking the exclusive token lock on every report; the
// recorder decides again on the live record.
reportedHostname := strings.TrimSpace(report.Host.Hostname)
if h.recordReportedIdentity != nil && tokenRecord != nil && host.TokenID == tokenRecord.ID &&
agentbinding.EvaluateReportedIdentity(tokenRecord, report.Agent.ID, host.ID, reportedHostname) {
h.recordReportedIdentity(GetOrgID(r.Context()), tokenRecord.ID, report.Agent.ID, host.ID, reportedHostname)
}
// A freshly generated install token is the server's durable record of the
// operator's command-policy choice. Project that choice onto the stable host
// identity before returning remote config, otherwise an old false override
// survives remove/reinstall and immediately shuts down an agent launched
// with --enable-commands (#1728).
if err := reconcileInstallTokenCommandPolicy(monitor, tokenRecord, host); err != nil {
log.Error().Err(err).
Str("agent_id", host.ID).
Str("token_id", tokenID(tokenRecord)).
Msg("Failed to reconcile install-token command policy")
}
log.Debug().
Str("agentId", host.ID).
Str("hostname", host.Hostname).
Str("platform", host.Platform).
Msg("Agent report processed")
h.broadcastState(r.Context())
// Include any server-side config overrides in the response
serverConfig := monitor.GetHostAgentConfig(host.ID)
serverConfig = sanitizeHostAgentConfigForToken(serverConfig, tokenRecord, host)
resp := map[string]any{
"success": true,
"agentId": host.ID,
"lastSeen": host.LastSeen,
"platform": host.Platform,
"osName": host.OSName,
"osVersion": host.OSVersion,
}
if h.serverVersion != "" {
resp["serverVersion"] = h.serverVersion
}
// Name the identity this agent's command channel must register under, for
// a host the monitor resolved and holds under this token, judged for the
// hostname this report presents, as its registration will. Mock mode's
// discard acknowledgement carries no token ID, so it names nothing.
if tokenRecord != nil && host.TokenID == tokenRecord.ID {
commandHost := host
commandHost.Hostname = reportedHostname
if commandAgentID := commandIdentityForToken(tokenRecord, commandHost); commandAgentID != "" {
resp["commandAgentId"] = commandAgentID
}
}
// Only include config if there are actual overrides
if serverConfig.CommandsEnabled != nil {
resp["config"] = map[string]any{
"commandsEnabled": serverConfig.CommandsEnabled,
}
}
if err := utils.WriteJSONResponse(w, resp); err != nil {
log.Error().Err(err).Msg("Failed to serialize agent response")
}
}
func reconcileInstallTokenCommandPolicy(monitor *monitoring.Monitor, requestRecord *config.APITokenRecord, host models.Host) error {
if monitor == nil || requestRecord == nil || strings.TrimSpace(requestRecord.ID) == "" || strings.TrimSpace(host.ID) == "" {
return nil
}
// Authentication stores a clone in the request context. Re-read the live
// record so concurrent scope changes and an already-consumed intent marker
// are authoritative. A tenant org's install tokens live in the instance
// inventory, so search every inventory the monitor's agents use.
inventories := monitor.APITokenInventories()
var record *config.APITokenRecord
config.Mu.RLock()
if live, _, found := monitoring.FindAPITokenLocked(inventories, requestRecord.ID); found {
clone := live.Clone()
record = &clone
}
config.Mu.RUnlock()
if record == nil {
return nil
}
requestedEnabled, hasIntent := agenttokens.ParseCommandPolicyIntent(record)
if !hasIntent || strings.TrimSpace(record.Metadata[agenttokens.CommandPolicyAppliedAgentIDMetadataKey]) != "" {
return nil
}
if !evaluateAgentExecBinding(record, host.ID, host.Hostname).admit {
// Intent metadata is useful only on a Pulse-minted install token whose
// binding policy admits this identity. Hand-created API tokens remain
// unable to turn themselves into command credentials.
return nil
}
// Scope removal always wins over the original enabled intent. Conversely,
// adding agent:exec later does not rewrite a deliberately disabled install
// intent; the explicit token-scope editor and desired policy remain separate
// controls.
effectiveEnabled := requestedEnabled && record.HasScope(config.ScopeAgentExec)
if err := monitor.UpdateHostAgentConfig(host.ID, &effectiveEnabled); err != nil {
return fmt.Errorf("persist desired command policy: %w", err)
}
config.Mu.Lock()
defer config.Mu.Unlock()
if live, inventory, found := monitoring.FindAPITokenLocked(inventories, requestRecord.ID); found {
if strings.TrimSpace(live.Metadata[agenttokens.CommandPolicyAppliedAgentIDMetadataKey]) != "" {
return nil
}
if live.Metadata == nil {
live.Metadata = make(map[string]string)
}
live.Metadata[agenttokens.CommandPolicyAppliedAgentIDMetadataKey] = host.ID
if inventory.Persistence != nil {
if err := inventory.Persistence.SaveAPITokens(inventory.Config.APITokens); err != nil {
delete(live.Metadata, agenttokens.CommandPolicyAppliedAgentIDMetadataKey)
return fmt.Errorf("persist install-token command-policy marker: %w", err)
}
}
log.Info().
Str("agent_id", host.ID).
Str("hostname", host.Hostname).
Str("token_id", live.ID).
Bool("commands_enabled", effectiveEnabled).
Msg("Applied install-token command policy to host")
return nil
}
return nil
}
// HandleLookup returns agent registration details for installer validation.
func (h *UnifiedAgentHandlers) HandleLookup(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodGet {
writeErrorResponse(w, http.StatusMethodNotAllowed, "method_not_allowed", "Only GET is allowed", nil)
return
}
lookupID := strings.TrimSpace(r.URL.Query().Get("id"))
hostname := strings.TrimSpace(r.URL.Query().Get("hostname"))
if lookupID == "" && hostname == "" {
writeErrorResponse(w, http.StatusBadRequest, "missing_lookup_param", "Provide either id or hostname to look up an agent", nil)
return
}
// Use the live host snapshot (not the global mock snapshot) so agent
// registrations can still be validated while Pulse is in mock/demo mode.
monitor := h.requireMonitor(w, r)
if monitor == nil {
return
}
hosts := monitor.GetLiveHostsSnapshot()
var (
host models.Host
found bool
)
if lookupID != "" {
for _, candidate := range hosts {
if candidate.ID == lookupID {
host = candidate
found = true
break
}
}
}
if !found && hostname != "" {
// First pass: exact hostname match (case-insensitive) when unique.
var exactMatch *models.Host
for i := range hosts {
candidate := &hosts[i]
if strings.EqualFold(candidate.Hostname, hostname) {
if exactMatch != nil {
exactMatch = nil
break
}
exactMatch = candidate
}
}
if exactMatch != nil {
host = *exactMatch
found = true
}
// Second pass: display-name match, but only when unambiguous.
if !found {
var displayMatch *models.Host
for i := range hosts {
candidate := &hosts[i]
if strings.EqualFold(candidate.DisplayName, hostname) {
if displayMatch != nil {
displayMatch = nil
break
}
displayMatch = candidate
}
}
if displayMatch != nil {
host = *displayMatch
found = true
}
}
// Third pass: short hostname match, but only when unique.
if !found {
// Helper to get short hostname (before first dot)
getShortName := func(h string) string {
if idx := strings.Index(h, "."); idx != -1 {
return h[:idx]
}
return h
}
shortLookup := getShortName(hostname)
var shortMatch *models.Host
for i := range hosts {
candidate := &hosts[i]
if strings.EqualFold(getShortName(candidate.Hostname), shortLookup) {
if shortMatch != nil {
shortMatch = nil
break
}
shortMatch = candidate
}
}
if shortMatch != nil {
host = *shortMatch
found = true
}
}
}
if !found {
writeErrorResponse(w, http.StatusNotFound, "agent_not_found", "Agent has not registered with Pulse yet", nil)
return
}
// Ensure the querying token matches the agent (when applicable).
if record := getAPITokenRecordFromRequest(r); record != nil && host.TokenID != "" && host.TokenID != record.ID {
writeErrorResponse(w, http.StatusForbidden, "agent_lookup_forbidden", "Agent does not belong to this API token", nil)
return
}
connected := strings.EqualFold(host.Status, "online") ||
strings.EqualFold(host.Status, "running") ||
strings.EqualFold(host.Status, "healthy")
agentInfo := map[string]any{
"id": host.ID,
"hostname": host.Hostname,
"displayName": host.DisplayName,
"status": host.Status,
"connected": connected,
"lastSeen": host.LastSeen,
"agentVersion": host.AgentVersion,
}
resp := map[string]any{
"success": true,
"agent": agentInfo,
}
if err := utils.WriteJSONResponse(w, resp); err != nil {
log.Error().Err(err).Msg("Failed to serialize agent lookup response")
}
}
// HandleDeleteHost removes an agent from the shared state.
func (h *UnifiedAgentHandlers) HandleDeleteHost(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodDelete {
writeErrorResponse(w, http.StatusMethodNotAllowed, "method_not_allowed", "Only DELETE is allowed", nil)
return
}
// Extract agent ID from URL path.
// Expected format: /api/agents/agent/{agentId} or legacy /api/agents/host/{agentId}
trimmedPath := trimUnifiedAgentRoutePath(r.URL.Path)
agentID := strings.TrimSpace(trimmedPath)
if agentID == "" {
writeErrorResponse(w, http.StatusBadRequest, "missing_agent_id", "agentId is required", nil)
return
}
// Remove the agent from state.
monitor := h.requireMonitor(w, r)
if monitor == nil {
return
}
host, err := monitor.RemoveHostAgent(agentID)
if err != nil {
writeErrorResponse(w, http.StatusInternalServerError, "agent_removal_failed", err.Error(), nil)
return
}
h.broadcastState(r.Context())
if err := utils.WriteJSONResponse(w, map[string]any{
"success": true,
"agentId": host.ID,
"message": "Agent removed",
}); err != nil {
log.Error().Err(err).Msg("Failed to serialize agent removal response")
}
}
// HandleAllowReenroll clears the removal block for a host agent to permit future reports.
func (h *UnifiedAgentHandlers) HandleAllowReenroll(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
writeErrorResponse(w, http.StatusMethodNotAllowed, "method_not_allowed", "Only POST is allowed", nil)
return
}
trimmedPath := trimUnifiedAgentRoutePath(r.URL.Path)
trimmedPath = strings.TrimSuffix(trimmedPath, "/allow-reenroll")
agentID := strings.TrimSpace(trimmedPath)
if agentID == "" {
writeErrorResponse(w, http.StatusBadRequest, "missing_agent_id", "agentId is required", nil)
return
}
monitor := h.requireMonitor(w, r)
if monitor == nil {
return
}
if err := monitor.AllowHostAgentReenroll(agentID); err != nil {
writeErrorResponse(w, http.StatusBadRequest, "agent_reenroll_failed", err.Error(), nil)
return
}
h.broadcastState(r.Context())
if err := utils.WriteJSONResponse(w, map[string]any{
"success": true,
"agentId": agentID,
}); err != nil {
log.Error().Err(err).Msg("Failed to serialize host-agent allow reenroll response")
}
}
// HandleConfig handles GET (fetch config) and PATCH (update config) for agents.
// GET /api/agents/agent/{agentId}/config - Agent fetches its server-side config.
// PATCH /api/agents/agent/{agentId}/config - UI updates agent config (e.g., commandsEnabled).
// Legacy clients may also use /api/agents/host/{agentId}/config.
func (h *UnifiedAgentHandlers) HandleConfig(w http.ResponseWriter, r *http.Request) {
// Extract agent ID from URL path.
// Expected format: /api/agents/agent/{agentId}/config or legacy /api/agents/host/{agentId}/config
trimmedPath := trimUnifiedAgentRoutePath(r.URL.Path)
trimmedPath = strings.TrimSuffix(trimmedPath, "/config")
agentID := strings.TrimSpace(trimmedPath)
if agentID == "" {
writeErrorResponse(w, http.StatusBadRequest, "missing_agent_id", "agentId is required", nil)
return
}
switch r.Method {
case http.MethodGet:
h.handleGetConfig(w, r, agentID)
case http.MethodPatch:
h.handlePatchConfig(w, r, agentID)
default:
writeErrorResponse(w, http.StatusMethodNotAllowed, "method_not_allowed", "Only GET and PATCH are allowed", nil)
}
}
func (h *UnifiedAgentHandlers) canReadConfig(record *config.APITokenRecord) bool {
if record == nil {
return true
}
return record.HasScope(config.ScopeAgentConfigRead) ||
// Older host/docker-agent tokens may only carry agent:report (legacy
// host-agent:report). Allow them to keep fetching their own config via
// token binding — resolveConfigAgent below restricts a report-only token
// to the host it is bound to.
record.HasScope(config.ScopeAgentReport) ||
record.HasScope(config.ScopeAgentManage) ||
record.HasScope(config.ScopeSettingsWrite)
}
func (h *UnifiedAgentHandlers) resolveConfigAgent(ctx context.Context, agentID string, record *config.APITokenRecord) (models.Host, bool) {
// Use the live host snapshot so agents can still fetch config while
// Pulse is running in mock/demo mode.
monitor := h.getMonitor(ctx)
if monitor == nil {
return models.Host{}, false
}
hosts := monitor.GetLiveHostsSnapshot()
if record == nil || record.HasScope(config.ScopeSettingsWrite) || record.HasScope(config.ScopeAgentManage) {
for _, candidate := range hosts {
if candidate.ID == agentID {
return candidate, true
}
}
// Live state loses agent-reported hosts across monitor reloads and
// restarts until the next report lands; fall back to the persisted
// continuity store so config fetches in that window do not 404 (#1570).
return monitor.MatchHostConfigContinuity(agentID, "")
}
for _, candidate := range hosts {
if candidate.TokenID != "" && candidate.TokenID == record.ID {
return candidate, true
}
}
return monitor.MatchHostConfigContinuity(agentID, record.ID)
}
func (h *UnifiedAgentHandlers) signAgentConfig(agentID string, cfg monitoring.HostAgentConfig) (monitoring.HostAgentConfig, error) {
var err error
cfg, err = ensureDesiredAgentConfigMetadata(cfg)
if err != nil {
return cfg, err
}
signatureRequired := isConfigSignatureRequired()
key, err := getConfigSigningKey()
if err != nil {
if signatureRequired {
return cfg, fmt.Errorf("failed to load config signing key: %w", err)
}
log.Warn().Err(err).Msg("Failed to load config signing key")
return cfg, nil
}
if len(key) == 0 {
if signatureRequired {
return cfg, fmt.Errorf("config signing required but PULSE_AGENT_CONFIG_SIGNING_KEY is not set")
}
return cfg, nil
}
issuedAt := time.Now().UTC()
expiresAt := issuedAt.Add(configSignatureTTL)
payload := remoteconfig.SignedConfigPayload{
AgentID: agentID,
IssuedAt: issuedAt,
ExpiresAt: expiresAt,
CommandsEnabled: cfg.CommandsEnabled,
Settings: cfg.Settings,
}
signature, err := remoteconfig.SignConfigPayload(payload, key)
if err != nil {
if signatureRequired {
return cfg, fmt.Errorf("failed to sign agent config payload: %w", err)
}
log.Warn().Err(err).Msg("Failed to sign agent config payload")
return cfg, nil
}
cfg.IssuedAt = &issuedAt
cfg.ExpiresAt = &expiresAt
cfg.Signature = signature
return cfg, nil
}
func ensureDesiredAgentConfigMetadata(cfg monitoring.HostAgentConfig) (monitoring.HostAgentConfig, error) {
metadata, err := remoteconfig.BuildDesiredConfigMetadata(cfg.CommandsEnabled, cfg.Settings)
if err != nil {
return cfg, fmt.Errorf("failed to build desired config metadata: %w", err)
}
cfg.DesiredConfig = &metadata
return cfg, nil
}
func getConfigSigningKey() (ed25519.PrivateKey, error) {
configSigningState.once.Do(func() {
raw := utils.GetenvTrim("PULSE_AGENT_CONFIG_SIGNING_KEY")
if raw == "" {
return
}
key, err := remoteconfig.DecodeEd25519PrivateKey(raw)
if err != nil {
configSigningState.err = err
return
}
configSigningState.key = key
})
return configSigningState.key, configSigningState.err
}
func isConfigSignatureRequired() bool {
return utils.ParseBool(utils.GetenvTrim("PULSE_AGENT_CONFIG_SIGNATURE_REQUIRED"))
}
// handleGetConfig returns the server-side config for an agent to apply.
func (h *UnifiedAgentHandlers) handleGetConfig(w http.ResponseWriter, r *http.Request, agentID string) {
record := getAPITokenRecordFromRequest(r)
if !h.canReadConfig(record) {
respondMissingScope(w, config.ScopeAgentConfigRead)
LogAuditEventForTenant(GetOrgID(r.Context()), "agent_config_fetch", auth.GetUser(r.Context()), GetClientIP(r), r.URL.Path, false,
fmt.Sprintf("agent_id=%s token_id=%s", agentID, tokenID(record)))
return
}
monitor := h.requireMonitor(w, r)
if monitor == nil {
return
}
host, ok := h.resolveConfigAgent(r.Context(), agentID, record)
if !ok {
writeErrorResponse(w, http.StatusNotFound, "agent_not_found", "Agent has not registered with Pulse yet", nil)
LogAuditEventForTenant(GetOrgID(r.Context()), "agent_config_fetch", auth.GetUser(r.Context()), GetClientIP(r), r.URL.Path, false,
fmt.Sprintf("agent_id=%s token_id=%s", agentID, tokenID(record)))
return
}
agentID = host.ID
config := monitor.GetHostAgentConfig(agentID)
config = sanitizeHostAgentConfigForToken(config, record, host)
signedConfig, err := h.signAgentConfig(agentID, config)
if err != nil {
log.Error().Err(err).Msg("Failed to sign agent config payload")
writeErrorResponse(w, http.StatusInternalServerError, "config_signing_failed", "Failed to sign agent config", nil)
LogAuditEventForTenant(GetOrgID(r.Context()), "agent_config_fetch", auth.GetUser(r.Context()), GetClientIP(r), r.URL.Path, false,
fmt.Sprintf("agent_id=%s token_id=%s", agentID, tokenID(record)))
return
}
resp := map[string]any{
"success": true,
"agentId": agentID,
"config": signedConfig,
}
if err := utils.WriteJSONResponse(w, resp); err != nil {
log.Error().Err(err).Msg("Failed to serialize agent config response")
LogAuditEventForTenant(GetOrgID(r.Context()), "agent_config_fetch", auth.GetUser(r.Context()), GetClientIP(r), r.URL.Path, false,
fmt.Sprintf("agent_id=%s token_id=%s", agentID, tokenID(record)))
return
}
configHash := ""
if signedConfig.DesiredConfig != nil {
configHash = signedConfig.DesiredConfig.Hash
}
orgID := GetOrgID(r.Context())
if reason, audit := h.configFetchAudits.observe(orgID, agentID, tokenID(record), configHash, time.Now()); audit {
details := fmt.Sprintf("agent_id=%s token_id=%s config=%s", agentID, tokenID(record), configHash)
if reason != "" {
details += " reason=" + reason
}
LogAuditEventForTenant(orgID, "agent_config_fetch", auth.GetUser(r.Context()), GetClientIP(r), r.URL.Path, true, details)
}
}
func tokenID(record *config.APITokenRecord) string {
if record == nil {
return ""
}
return record.ID
}
func sanitizeHostAgentConfigForToken(cfg monitoring.HostAgentConfig, record *config.APITokenRecord, host models.Host) monitoring.HostAgentConfig {
if cfg.CommandsEnabled == nil || !*cfg.CommandsEnabled || commandConfigAllowedForToken(record, host) {
return cfg
}
disabled := false
cfg.CommandsEnabled = &disabled
return cfg
}
func commandConfigAllowedForToken(record *config.APITokenRecord, host models.Host) bool {
if record == nil {
return true
}
if !record.HasScope(config.ScopeAgentExec) {
log.Warn().
Str("token_id", record.ID).
Str("agent_id", host.ID).
Str("hostname", host.Hostname).
Msg("Suppressing enabled remote commands for agent: token missing required scope agent:exec")
return false
}
// Mirror the command-channel admission decision exactly. Telling an agent
// commands are enabled when its channel registration would be rejected
// strands the host on "Remote control blocked" (the agent reports
// CommandsEnabled=true forever while no channel can be admitted).
if commandIdentityForToken(record, host) == "" {
// This gate runs before the agent ever attempts command-channel
// registration, so without a log here a refused binding leaves no
// trace anywhere: the agent never learns commands were requested and
// the channel rejection warnings never fire (#1728).
log.Warn().
Str("token_id", record.ID).
Str("agent_id", host.ID).
Str("hostname", host.Hostname).
Str("bound_agent_id", strings.TrimSpace(record.Metadata["bound_agent_id"])).
Str("bound_hostname", strings.TrimSpace(record.Metadata["bound_hostname"])).
Str("install_type", strings.TrimSpace(record.Metadata["install_type"])).
Str("issued_via", strings.TrimSpace(record.Metadata["issued_via"])).
Msg("Suppressing enabled remote commands for agent: exec binding would reject this token and agent identity")
return false
}
return true
}
// commandIdentityForToken names the identity a host agent's command channel
// must register under for its token to admit it: the host ID Pulse resolved
// for the agent's report, which the ack returns as agentId and the agent
// persists and presents after a restart. A token binds the first ID its
// channel presents, so an agent that registered a configured --agent-id, or
// an ID Pulse forked or kept from an earlier enrollment, was refused on every
// restart while the config gate judged the resolved ID.
//
// The ID is named only for a credential that command admission would take on
// its legacy path (agent:exec, at most one organization, no runner,
// collector, or unsupported runtime role), and only when the shared binding
// decision admits it: the token already holds it, or a registration
// presenting it would take the first bind, backfill, legacy migration,
// hostname rebind, or one-time deploy repair it would get anyway. Naming it
// grants nothing beyond that registration. An established binding to any
// other ID is never moved by report contents, which can be steered onto
// another host's continuity record; the result is empty and the agent keeps
// registering under the ID it presents. The config gate consumes the same
// decision, so commands are never reported enabled for an identity the
// channel would refuse.
func commandIdentityForToken(record *config.APITokenRecord, host models.Host) string {
hostID := strings.TrimSpace(host.ID)
if record == nil || hostID == "" || !record.HasScope(config.ScopeAgentExec) || len(record.GetBoundOrgs()) > 1 {
return ""
}
switch strings.TrimSpace(record.Metadata[agenttokens.RuntimeRoleMetadataKey]) {
case "", agenttokens.CredentialKindLegacyFullTrust:
default:
return ""
}
if !evaluateAgentExecBinding(record, hostID, host.Hostname).admit {
return ""
}
return hostID
}
func (h *UnifiedAgentHandlers) ensureAgentTokenMatch(w http.ResponseWriter, r *http.Request, agentID string) bool {
record := getAPITokenRecordFromRequest(r)
if record == nil {
return true
}
if record.HasScope(config.ScopeSettingsWrite) || record.HasScope(config.ScopeWildcard) {
return true
}
// Use the live host snapshot so mock/demo mode doesn't block agent auth checks.
monitor := h.requireMonitor(w, r)
if monitor == nil {
return false
}
hosts := monitor.GetLiveHostsSnapshot()
for _, host := range hosts {
if host.ID != agentID {
continue
}
if host.TokenID == record.ID {
return true
}
writeErrorResponse(w, http.StatusForbidden, "agent_lookup_forbidden", "Agent does not belong to this API token", nil)
return false
}
writeErrorResponse(w, http.StatusNotFound, "agent_not_found", "Agent has not registered with Pulse yet", nil)
return false
}
// handlePatchConfig updates the server-side config for an agent.
func (h *UnifiedAgentHandlers) handlePatchConfig(w http.ResponseWriter, r *http.Request, agentID string) {
if !h.ensureAgentTokenMatch(w, r, agentID) {
return
}
r.Body = http.MaxBytesReader(w, r.Body, 16*1024)
defer r.Body.Close()
var req struct {
CommandsEnabled *bool `json:"commandsEnabled"`
}
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
writeErrorResponse(w, http.StatusBadRequest, "invalid_json", "Failed to decode request body", map[string]string{"error": err.Error()})
return
}
monitor := h.requireMonitor(w, r)
if monitor == nil {
return
}
if err := monitor.UpdateHostAgentConfig(agentID, req.CommandsEnabled); err != nil {
writeErrorResponse(w, http.StatusInternalServerError, "update_failed", err.Error(), nil)
return
}
h.broadcastState(r.Context())
log.Info().
Str("agentId", agentID).
Interface("commandsEnabled", req.CommandsEnabled).
Msg("Agent config updated")
resp := map[string]any{
"success": true,
"agentId": agentID,
"config": map[string]any{
"commandsEnabled": req.CommandsEnabled,
},
}
if err := utils.WriteJSONResponse(w, resp); err != nil {
log.Error().Err(err).Msg("Failed to serialize agent config update response")
}
}
// HandleUninstall allows an agent to unregister itself during uninstallation.
// Requires ScopeAgentReport and a valid agentId in the request body.
func (h *UnifiedAgentHandlers) HandleUninstall(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
writeErrorResponse(w, http.StatusMethodNotAllowed, "method_not_allowed", "Only POST is allowed", nil)
return
}
r.Body = http.MaxBytesReader(w, r.Body, 16*1024)
defer r.Body.Close()
var req struct {
AgentID string `json:"agentId"`
}
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
writeErrorResponse(w, http.StatusBadRequest, "invalid_json", "Failed to decode request body", map[string]string{"error": err.Error()})
return
}
agentID := strings.TrimSpace(req.AgentID)
if agentID == "" {
writeErrorResponse(w, http.StatusBadRequest, "missing_agent_id", "agentId is required", nil)
return
}
log.Info().Str("agentId", agentID).Msg("Received unregistration request from agent uninstaller")
monitor := h.requireMonitor(w, r)
if monitor == nil {
return
}
record := getAPITokenRecordFromRequest(r)
var err error
if record != nil {
_, err = monitor.UninstallHostAgent(agentID, record.ID)
} else {
// Preserve the existing administrative/session removal surface. Collector
// self-uninstall always takes the exact-token durable path above.
_, err = monitor.RemoveHostAgent(agentID)
}
if err != nil {
switch {
case errors.Is(err, monitoring.ErrHostAgentTokenMismatch):
writeErrorResponse(w, http.StatusForbidden, "agent_lookup_forbidden", "Agent does not belong to this API token", nil)
case errors.Is(err, monitoring.ErrHostAgentNotFound):
writeErrorResponse(w, http.StatusNotFound, "agent_not_found", "Agent has not registered with Pulse yet", nil)
default:
log.Error().Err(err).Str("agentId", agentID).Msg("Collector uninstall transaction failed")
writeErrorResponse(w, http.StatusInternalServerError, "agent_uninstall_failed", "Pulse could not durably remove the agent", nil)
}
return
}
h.broadcastState(r.Context())
if err := utils.WriteJSONResponse(w, map[string]any{
"success": true,
"agentId": agentID,
"message": "Agent unregistered successfully",
}); err != nil {
log.Error().Err(err).Msg("Failed to serialize agent unregistration response")
}
}
// HandleLink manually links an agent to a specific PVE node.
// This is used when auto-linking can't disambiguate (e.g., multiple nodes with hostname "pve").
func (h *UnifiedAgentHandlers) HandleLink(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
writeErrorResponse(w, http.StatusMethodNotAllowed, "method_not_allowed", "Only POST is allowed", nil)
return
}
r.Body = http.MaxBytesReader(w, r.Body, 16*1024)
defer r.Body.Close()
var req struct {
AgentID string `json:"agentId"`
NodeID string `json:"nodeId"`
}
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
writeErrorResponse(w, http.StatusBadRequest, "invalid_json", "Failed to decode request body", map[string]string{"error": err.Error()})
return
}
agentID := strings.TrimSpace(req.AgentID)
if agentID == "" {
writeErrorResponse(w, http.StatusBadRequest, "missing_agent_id", "agentId is required", nil)
return
}
nodeID := strings.TrimSpace(req.NodeID)
if nodeID == "" {
writeErrorResponse(w, http.StatusBadRequest, "missing_node_id", "Node ID is required", nil)
return
}
monitor := h.requireMonitor(w, r)
if monitor == nil {
return
}
if err := monitor.LinkHostAgent(agentID, nodeID); err != nil {
writeErrorResponse(w, http.StatusBadRequest, "link_failed", err.Error(), nil)
return
}
h.broadcastState(r.Context())
if err := utils.WriteJSONResponse(w, map[string]any{
"success": true,
"agentId": agentID,
"nodeId": nodeID,
"message": "Agent linked to PVE node",
}); err != nil {
log.Error().Err(err).Msg("Failed to serialize agent link response")
}
}
// HandleUnlink removes the link between an agent and its PVE node.
// The agent continues to report but appears in the Managed Agents table.
func (h *UnifiedAgentHandlers) HandleUnlink(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
writeErrorResponse(w, http.StatusMethodNotAllowed, "method_not_allowed", "Only POST is allowed", nil)
return
}
r.Body = http.MaxBytesReader(w, r.Body, 16*1024)
defer r.Body.Close()
var req struct {
AgentID string `json:"agentId"`
}
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
writeErrorResponse(w, http.StatusBadRequest, "invalid_json", "Failed to decode request body", map[string]string{"error": err.Error()})
return
}
agentID := strings.TrimSpace(req.AgentID)
if agentID == "" {
writeErrorResponse(w, http.StatusBadRequest, "missing_agent_id", "agentId is required", nil)
return
}
monitor := h.requireMonitor(w, r)
if monitor == nil {
return
}
if err := monitor.UnlinkHostAgent(agentID); err != nil {
writeErrorResponse(w, http.StatusNotFound, "unlink_failed", err.Error(), nil)
return
}
h.broadcastState(r.Context())
if err := utils.WriteJSONResponse(w, map[string]any{
"success": true,
"agentId": agentID,
"message": "Agent unlinked from PVE node",
}); err != nil {
log.Error().Err(err).Msg("Failed to serialize agent unlink response")
}
}