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 unifiedresources
import (
"fmt"
"sort"
"strings"
)
// ResourceSensitivity classifies how carefully Pulse should handle resource data.
type ResourceSensitivity string
const (
ResourceSensitivityPublic ResourceSensitivity = "public"
ResourceSensitivityInternal ResourceSensitivity = "internal"
ResourceSensitivitySensitive ResourceSensitivity = "sensitive"
ResourceSensitivityRestricted ResourceSensitivity = "restricted"
)
// ResourceRoutingScope expresses the default local-vs-cloud decision for a resource.
type ResourceRoutingScope string
const (
ResourceRoutingScopeCloudSummary ResourceRoutingScope = "cloud-summary"
ResourceRoutingScopeLocalFirst ResourceRoutingScope = "local-first"
ResourceRoutingScopeLocalOnly ResourceRoutingScope = "local-only"
)
// ResourceRedactionHint describes identifiers that should be removed before cloud use.
type ResourceRedactionHint string
const (
ResourceRedactionHostname ResourceRedactionHint = "hostname"
ResourceRedactionIPAddress ResourceRedactionHint = "ip-address"
ResourceRedactionPlatformID ResourceRedactionHint = "platform-id"
ResourceRedactionAlias ResourceRedactionHint = "alias"
ResourceRedactionPath ResourceRedactionHint = "path"
)
// ResourcePolicy captures the canonical policy posture for a resource.
type ResourcePolicy struct {
Sensitivity ResourceSensitivity `json:"sensitivity"`
Routing ResourceRoutingPolicy `json:"routing"`
}
// ResourceRoutingPolicy captures the current routing posture for AI-safe handling.
type ResourceRoutingPolicy struct {
Scope ResourceRoutingScope `json:"scope"`
Redact []ResourceRedactionHint `json:"redact,omitempty"`
}
// CloneResourcePolicy returns a deep copy of the canonical resource policy.
func CloneResourcePolicy(policy *ResourcePolicy) *ResourcePolicy {
if policy == nil {
return nil
}
copyPolicy := *policy
copyPolicy.Routing.Redact = append([]ResourceRedactionHint(nil), policy.Routing.Redact...)
return ©Policy
}
// CanonicalGovernanceMetadata returns cloned policy metadata and AI-safe
// summary for a resolved resource, tolerating callers that only have routing
// location data when a full Resource record is not available.
func CanonicalGovernanceMetadata(resource *Resource) (*ResourcePolicy, string) {
if resource == nil {
return nil, ""
}
resourceCopy := *resource
RefreshPolicyMetadata(&resourceCopy)
return CloneResourcePolicy(resourceCopy.Policy), strings.TrimSpace(resourceCopy.AISafeSummary)
}
// RefreshPolicyMetadata derives canonical sensitivity, routing, and AI-safe summary data.
func RefreshPolicyMetadata(resource *Resource) {
if resource == nil {
return
}
sensitivity := classifyResourceSensitivity(resource)
resource.Policy = &ResourcePolicy{
Sensitivity: sensitivity,
Routing: buildResourceRoutingPolicy(*resource, sensitivity),
}
resource.AISafeSummary = buildAISafeSummary(*resource, sensitivity)
}
// RefreshCanonicalMetadata derives the canonical identity and policy metadata
// for a resource in one pass.
func RefreshCanonicalMetadata(resource *Resource) {
if resource == nil {
return
}
RefreshCanonicalIdentity(resource)
RefreshPlatformScopes(resource)
RefreshPolicyMetadata(resource)
}
// RefreshCanonicalMetadataSlice returns a cloned slice with canonical identity
// and policy metadata refreshed for each resource.
func RefreshCanonicalMetadataSlice(resources []Resource) []Resource {
if len(resources) == 0 {
return resources
}
out := make([]Resource, len(resources))
for i, resource := range resources {
out[i] = resource
RefreshCanonicalMetadata(&out[i])
}
return out
}
// Borrow the detached resource for this read-only scan. A full value copy on
// every registry read is unnecessary, including when tag precedence returns
// before any of the resource's other fields are read.
func classifyResourceSensitivity(resource *Resource) ResourceSensitivity {
// Clones classify every registry read. Scan once without building a tag
// map, preserving public > restricted > sensitive precedence independently
// of tag order, and normalising each tag only once.
tagSensitivity := ResourceSensitivityInternal
for _, tag := range resource.Tags {
switch strings.ToLower(strings.TrimSpace(tag)) {
case "public":
return ResourceSensitivityPublic
case "restricted", "customer-data", "customer_data", "pii", "phi", "pci", "regulated", "secret", "secrets":
tagSensitivity = ResourceSensitivityRestricted
case "sensitive", "backup", "mail", "storage", "database", "dataset":
if tagSensitivity != ResourceSensitivityRestricted {
tagSensitivity = ResourceSensitivitySensitive
}
}
}
if tagSensitivity != ResourceSensitivityInternal {
return tagSensitivity
}
if resource.PMG != nil {
return ResourceSensitivityRestricted
}
if CanonicalResourceType(resource.Type) == ResourceTypeK8sSecret ||
CanonicalResourceType(resource.Type) == ResourceTypeDockerSecret {
return ResourceSensitivityRestricted
}
// Sensitivity is calibrated for Pulse's audience (homelab / SMB). Ordinary
// compute workloads — VMs, containers, pods, k8s deployments/services, docker
// services — are NOT sensitive by default: a workload's name and private LAN
// IP are not secrets, and redacting them on cloud models cripples the
// Assistant ("redacted by policy" everywhere). They classify as Internal
// (cloud-summary, no redaction) and only escalate via the tag checks above
// (database, backup, customer-data, secret, ...) or the explicit
// secret/PMG/RBAC types below. Data-at-rest, configuration, RBAC, and storage
// resources stay Sensitive because they can carry secret material or expose
// the contents/locations of protected data.
switch CanonicalResourceType(resource.Type) {
case ResourceTypeK8sPV,
ResourceTypeK8sPVC,
ResourceTypeK8sStorageClass,
ResourceTypeK8sConfigMap,
ResourceTypeK8sServiceAccount,
ResourceTypeK8sRole,
ResourceTypeK8sClusterRole,
ResourceTypeK8sRoleBinding,
ResourceTypeK8sClusterRoleBinding,
ResourceTypeDockerConfig,
ResourceTypeStorage,
ResourceTypeNetwork,
ResourceTypePBS,
ResourceTypePhysicalDisk,
ResourceTypeCeph,
ResourceTypeNetworkShare:
return ResourceSensitivitySensitive
}
if resource.TrueNAS != nil {
return ResourceSensitivitySensitive
}
if resource.Agent != nil && (resource.Agent.Unraid != nil || resource.Agent.StorageRisk != nil) {
return ResourceSensitivitySensitive
}
return ResourceSensitivityInternal
}
func buildResourceRoutingPolicy(resource Resource, sensitivity ResourceSensitivity) ResourceRoutingPolicy {
policy := ResourceRoutingPolicy{}
switch sensitivity {
case ResourceSensitivityPublic, ResourceSensitivityInternal:
policy.Scope = ResourceRoutingScopeCloudSummary
case ResourceSensitivitySensitive:
policy.Scope = ResourceRoutingScopeLocalFirst
case ResourceSensitivityRestricted:
policy.Scope = ResourceRoutingScopeLocalOnly
default:
policy.Scope = ResourceRoutingScopeLocalFirst
}
if sensitivity == ResourceSensitivitySensitive || sensitivity == ResourceSensitivityRestricted {
if resourceHasHostname(resource) {
policy.Redact = append(policy.Redact, ResourceRedactionHostname)
}
if len(resource.Identity.IPAddresses) > 0 {
policy.Redact = append(policy.Redact, ResourceRedactionIPAddress)
}
if resourceHasPlatformIdentity(resource) {
policy.Redact = append(policy.Redact, ResourceRedactionPlatformID, ResourceRedactionAlias)
}
}
if resourceHasFilesystemPath(resource) {
policy.Redact = append(policy.Redact, ResourceRedactionPath)
}
policy.Redact = uniqueRedactionHints(policy.Redact)
return policy
}
func buildAISafeSummary(resource Resource, sensitivity ResourceSensitivity) string {
parts := []string{
fmt.Sprintf("%s resource", resourceSummaryType(resource)),
}
if status := strings.TrimSpace(string(resource.Status)); status != "" {
parts = append(parts, "status "+status)
}
if len(resource.Sources) > 0 {
sources := make([]string, 0, len(resource.Sources))
for _, source := range resource.Sources {
if trimmed := strings.TrimSpace(string(source)); trimmed != "" {
sources = append(sources, trimmed)
}
}
sort.Strings(sources)
sources = uniqueTrimmed(sources...)
if len(sources) > 0 {
parts = append(parts, "sources "+strings.Join(sources, "+"))
}
}
if resource.ParentID != nil && strings.TrimSpace(*resource.ParentID) != "" {
parts = append(parts, "linked to parent resource")
}
if resource.ChildCount > 0 {
parts = append(parts, fmt.Sprintf("%d child resources", resource.ChildCount))
}
if resource.IncidentCount > 0 {
incidentText := fmt.Sprintf("%d incident", resource.IncidentCount)
if resource.IncidentCount != 1 {
incidentText += "s"
}
if severity := strings.TrimSpace(string(resource.IncidentSeverity)); severity != "" {
incidentText += ", " + severity + " severity"
}
parts = append(parts, incidentText)
}
switch sensitivity {
case ResourceSensitivitySensitive:
parts = append(parts, resourceAISafeSummaryPolicySuffix(sensitivity))
case ResourceSensitivityRestricted:
parts = append(parts, resourceAISafeSummaryPolicySuffix(sensitivity))
}
return strings.Join(parts, "; ")
}
func resourceAISafeSummaryPolicySuffix(sensitivity ResourceSensitivity) string {
switch sensitivity {
case ResourceSensitivitySensitive:
return "redacted for cloud summary"
case ResourceSensitivityRestricted:
return "local-only context"
default:
return ""
}
}
func resourceSummaryType(resource Resource) string {
switch CanonicalResourceType(resource.Type) {
case ResourceTypeAgent:
return "agent"
case ResourceTypeVM:
return "virtual machine"
case ResourceTypeSystemContainer:
return "system container"
case ResourceTypeAppContainer:
return "application container"
case ResourceTypeDockerService:
return "docker service"
case ResourceTypeDockerSwarmNode:
return "docker swarm node"
case ResourceTypeDockerSecret:
return "docker swarm secret"
case ResourceTypeDockerConfig:
return "docker swarm config"
case ResourceTypeK8sCluster:
return "kubernetes cluster"
case ResourceTypeK8sNode:
return "kubernetes node"
case ResourceTypePod:
return "kubernetes pod"
case ResourceTypeK8sDeployment:
return "kubernetes deployment"
case ResourceTypeK8sReplicaSet:
return "kubernetes replicaset"
case ResourceTypeK8sNamespace:
return "kubernetes namespace"
case ResourceTypeK8sService:
return "kubernetes service"
case ResourceTypeK8sStatefulSet:
return "kubernetes statefulset"
case ResourceTypeK8sDaemonSet:
return "kubernetes daemonset"
case ResourceTypeK8sJob:
return "kubernetes job"
case ResourceTypeK8sCronJob:
return "kubernetes cronjob"
case ResourceTypeK8sIngress:
return "kubernetes ingress"
case ResourceTypeK8sEndpointSlice:
return "kubernetes endpointslice"
case ResourceTypeK8sNetworkPolicy:
return "kubernetes network policy"
case ResourceTypeK8sPV:
return "kubernetes persistent volume"
case ResourceTypeK8sPVC:
return "kubernetes persistent volume claim"
case ResourceTypeK8sStorageClass:
return "kubernetes storage class"
case ResourceTypeK8sConfigMap:
return "kubernetes configmap"
case ResourceTypeK8sSecret:
return "kubernetes secret"
case ResourceTypeK8sServiceAccount:
return "kubernetes serviceaccount"
case ResourceTypeK8sRole:
return "kubernetes role"
case ResourceTypeK8sClusterRole:
return "kubernetes clusterrole"
case ResourceTypeK8sRoleBinding:
return "kubernetes rolebinding"
case ResourceTypeK8sClusterRoleBinding:
return "kubernetes clusterrolebinding"
case ResourceTypeK8sResourceQuota:
return "kubernetes resource quota"
case ResourceTypeK8sLimitRange:
return "kubernetes limit range"
case ResourceTypeK8sPDB:
return "kubernetes pod disruption budget"
case ResourceTypeK8sHPA:
return "kubernetes horizontal pod autoscaler"
case ResourceTypeK8sEvent:
return "kubernetes event"
case ResourceTypeStorage:
return "storage"
case ResourceTypeNetwork:
return "network"
case ResourceTypePBS:
return "backup server"
case ResourceTypePMG:
return "mail gateway"
case ResourceTypeCeph:
return "ceph cluster"
case ResourceTypePhysicalDisk:
return "physical disk"
case ResourceTypeNetworkShare:
return "network share"
default:
if trimmed := strings.TrimSpace(string(CanonicalResourceType(resource.Type))); trimmed != "" {
return trimmed
}
return "resource"
}
}
func resourceHasHostname(resource Resource) bool {
if canonicalHostname(resource) != "" {
return true
}
return strings.TrimSpace(resource.Name) != ""
}
func resourceHasPlatformIdentity(resource Resource) bool {
if resource.Canonical == nil {
return false
}
if strings.TrimSpace(resource.Canonical.PlatformID) != "" || strings.TrimSpace(resource.Canonical.PrimaryID) != "" {
return true
}
return len(resource.Canonical.Aliases) > 0
}
func resourceHasFilesystemPath(resource Resource) bool {
if resource.Storage != nil && strings.TrimSpace(resource.Storage.Path) != "" {
return true
}
if resource.TrueNAS != nil && resource.TrueNAS.Share != nil && strings.TrimSpace(resource.TrueNAS.Share.Path) != "" {
return true
}
return false
}
func uniqueRedactionHints(in []ResourceRedactionHint) []ResourceRedactionHint {
if len(in) == 0 {
return nil
}
seen := make(map[ResourceRedactionHint]struct{}, len(in))
out := make([]ResourceRedactionHint, 0, len(in))
for _, hint := range in {
if _, ok := seen[hint]; ok {
continue
}
seen[hint] = struct{}{}
out = append(out, hint)
}
return out
}