Pulse Documentation

Pulse models storage across four distinct layers to provide operator-centric visibility rather than just raw data. Understanding these layers helps in interpreting how storage health impacts your workloads:

1. Physical Disk (physical_disk): The actual block device. Identity is established via serial, WWN / EUI, or controller-specific IDs. Key metrics include temperature, wear indicators, and S.M.A.R.T. counters (media, pending, reallocated, etc.).
2. Storage Membership: The topology layer defining relationships, such as a disk being a member of an mdraid array, a ZFS vdev/pool, an Unraid parity/data assignment, or a Ceph OSD.
3. Logical Storage Object: Operator-facing objects like storage, datastore, ceph, filesystem, dataset, share, or backup repository. These track capacity, health, redundancy state, and rebuild/resilver status.
4. Consumer Impact: The layer mapping storage health to business impact, tracing degraded objects to specific VMs, LXCs, app containers / pods, or backup jobs.

Pulse implements several security layers to protect sensitive data and operations:

• Encryption at Rest: Sensitive configurations like passwords and API keys are encrypted using AES-GCM via internal/crypto. Support exists for per-tenant encryption keys.
• Scoped API Tokens: Access is controlled via explicit scopes. Common scopes include monitoring:read, settings:write, ai:chat, ai:execute, and docker:report. Endpoints validate these scopes before execution.
• RBAC (Role-Based Access Control): Managed via pkg/auth using file-backed persistence. Resources managed include users, settings, and monitoring.
• SSO Support: Supports OIDC and SAML providers with multi-provider configuration.
• Audit Trail: All mutations are logged to per-tenant SQLite databases, with optional cryptographic signatures.
• Rate Limiting: Configurable thresholds are applied per-endpoint and per-tenant.
• CSRF Protection: Mutation endpoints use token-based CSRF prevention.
• Recovery Mode: An emergency authentication recovery endpoint is available, restricted to localhost and using time-limited tokens.

Pulse uses a split-configuration model to separate secrets, encrypted data, and standard settings. Files are located in /etc/pulse/ (Systemd) or /data/ (Docker/Kubernetes) by default.

Configuration File Types

• Critical Secrets: .env (Authentication), .encryption.key (AES-256-GCM key).
• Encrypted Files: nodes.enc (Node credentials), email.enc (SMTP), webhooks.enc, oidc.enc, sso.enc, ai.enc, license.enc.
• Standard Settings: system.json (General settings), alerts.json (Alert rules), host_metadata.json, docker_metadata.json, guest_metadata.json.
• Databases: metrics.db (SQLite metrics history), audit.db (SQLite audit logs).

Path Overrides

• PULSE_DATA_DIR: Sets the base directory for system.json, encrypted files, and the bootstrap token.
• PULSE_METRICS_DB_PATH: Sets the path for the metrics SQLite database specifically. This is useful for placing metrics on a tmpfs while keeping secrets on persistent storage.

Pulse Patrol operates as an autonomous reliability loop divided into three distinct, independently qualified tracks. Understanding these tracks is essential for knowing the capabilities and limitations of the system at different stages of an incident:

1. Watch: The initial phase. It collects normal product state, uses read-only tools to investigate, and records finding verdicts. It can update Pulse finding states but cannot mutate infrastructure.
2. Investigate: Triggered by a finding. It performs a non-interactive, structurally read-only investigation. The model is permitted to emit at most one side-effect-free, typed action proposal.
3. Act and verify: The final phase. It converts a proposal into a canonical action plan. This track requires passing policy, scope, plan hash, approval (or auto-authorization), execution, and independent verification before an action is marked successful.

Pulse agents operate under a specific security and privilege model:

• Privilege Model: The Linux/systemd installer runs the agent as root by default to enable full host telemetry (SMART, RAID, sensors, Docker sockets). Running as a non-root user is supported but is not a 'full-telemetry' profile and will result in data gaps.
• Sandboxing: Generated systemd units use conservative sandboxing (NoNewPrivileges=true, PrivateTmp=true, kernel/cgroup write protection) to reduce blast radius.
• API Security: All communication requires a valid API token. TLS is enabled by default. The agent control plane can be isolated to a dedicated port via Split-Port Agent Ingest.
• Command Security: Commands are disabled by default. Even when enabled, they must pass through Pulse's command policy and approval surfaces. Agent command tokens must be bound to a host/agent identity before registration is accepted (except for Proxmox install-command tokens).

Pulse Patrol is a scheduled model workflow that builds a system-wide snapshot and uses an LLM with specialized tools to produce actionable findings. The workflow follows these stages:

1. Trigger: Scheduled or event-based.
2. Context Building: buildSeedContext() gathers infrastructure evidence and policy context.
3. LLM Analysis: The model uses tools like pulse_storage, pulse_metrics, and pulse_alerts to analyze the environment.
4. Finding Management: Findings are processed via patrol_report_finding(), patrol_assess_finding(), and patrol_resolve_finding() (which requires an explicit verdict).
5. Deterministic Extraction: DetectSignals() extracts concrete evidence from tool outputs.
6. Evaluation: A focused LLM review pass handles unmatched evidence.
7. Storage: Validated, deduplicated findings are stored.
8. Investigation (Optional): MaybeInvestigateFinding() triggers model investigation and governed fix planning/execution.