Pulse/docs/SECURITY_REVIEW.md

Security Review Scope

Pulse does not currently claim an independent security certification or a third-party penetration-test attestation. This page gives reviewers a concrete, reproducible starting point and makes the intended trust boundaries explicit.

Before reviewing the code, read:

• Production Deployment and Security for the least-privilege deployment model and operational checklist.
• The canonical Security Policy for reporting and hardening.
• Agent Security for root privilege, command execution, guest access, and update verification.
• Installation for the signed, version-pinned server installer.

First focused review packet

The Authentication and Credential Storage Review Packet defines a narrow first assessment with explicit attacker capabilities, security properties, source boundaries, manual review steps, and a reusable finding template. Its baseline can be run with:

./scripts/security_review_auth_credentials.sh

Suggested review boundaries

1. Authentication, authorization, and tenant isolation

Review browser sessions, API-token scopes, organization binding, proxy authentication, and denial behavior. Confirm that a credential valid for one route or organization cannot acquire management, agent, or cross-tenant authority elsewhere.

Starting points:

• internal/api/auth.go
• internal/api/authorization.go
• internal/api/middleware.go
• internal/api/api_token_scope_transport_integration_test.go
• internal/api/middleware_tenant_authorization_test.go
• pkg/auth/
• docs/security-review/AUTH_CREDENTIAL_REVIEW.md

2. Credential storage and configuration transfer

Review encryption-key creation and permissions, AES-GCM use, encrypted configuration persistence, backup/restore behavior, and export/import authorization. Confirm that missing or unsafe key material fails closed rather than silently replacing a key and orphaning encrypted data.

Starting points:

• internal/crypto/crypto.go
• internal/crypto/crypto_test.go
• internal/config/persistence.go
• internal/config/persistence_fail_test.go
• internal/api/config_transfer_authorization.go
• internal/api/config_transfer_authorization_test.go

3. Agent privilege and command authority

Review the Linux agent's default root profile as a privileged monitoring boundary. Confirm that command execution remains disabled by default, enabling it does not bypass policy and approval, report-only credentials cannot acquire execution authority, and agent health endpoints remain loopback-bound unless explicitly changed.

Starting points:

• cmd/pulse-agent/main.go
• internal/agentexec/
• internal/api/agent_command_authorization.go
• internal/api/agent_command_authorization_test.go
• scripts/install.sh
• docs/AGENT_SECURITY.md

4. Installer and update supply chain

Review the server installer's release pinning and Ed25519 verification, agent checksum and signature enforcement, executable validation, self-test, and atomic replacement behavior. Include the documented first automatic v5-to-v6 agent update limitation in the threat model.

Starting points:

• install.sh
• docs/INSTALL.md
• internal/agentupdate/update.go
• internal/agentupdate/update_http_test.go
• .github/workflows/create-release.yml
• docs/CODE_SIGNING_POLICY.md

5. Discovery and outbound network boundaries

Confirm that network discovery is disabled by default, probes only the documented Proxmox ports, honors subnet allowlists and blocklists, and applies host, concurrency, and timeout bounds. Review outbound URL validation and SSRF protections for integrations and probes.

Starting points:

• internal/config/config.go
• internal/discovery/
• pkg/discovery/
• internal/securityutil/outbound_http.go
• pkg/securityutil/outbound_http.go

6. Container and host separation

Review the block on storing host SSH private keys inside Pulse containers, Docker/Podman socket handling, Proxmox guest inventory opt-ins, and data-volume permissions. Confirm that API-only Proxmox monitoring does not require Pulse software on the hypervisor.

Starting points:

• SECURITY.md
• docs/AGENT_SECURITY.md
• internal/hostagent/proxmox_lxc_filesystems.go
• internal/monitoring/docker_detection.go
• internal/api/contract_test.go
• internal/dockeragent/

7. Production-scale failure behavior

Review behavior under concurrent reads and writes, stale data, partial platform responses, retention, and large resource sets. Pulse includes simulated 500-node API and metrics-store regression coverage. Treat that as reproducible engineering evidence, not as a production certification.

Starting points:

• internal/api/load_test.go
• pkg/metrics/store_loadtest_test.go
• pkg/metrics/store_slo_test.go

Reproducible baseline

From a clean checkout with the documented Go and Node versions installed:

go test ./internal/crypto ./pkg/auth ./internal/agentupdate \
  ./internal/agentexec ./internal/discovery ./pkg/discovery \
  ./internal/securityutil ./pkg/securityutil

go test ./internal/api \
  -run '^TestLoad_500Node_(ConcurrentResources|ConcurrentMetricsHistory|MixedEndpoints)$' \
  -count=1

go test ./pkg/metrics \
  -run '^TestLoadTest500Nodes_WriteAndQueryIntegration$' \
  -count=1

python3 scripts/check_public_docs.py

These commands are a baseline, not a substitute for manual review, dependency analysis, fuzzing, deployment-specific testing, or an independent threat model.

Reporting findings

Please report suspected vulnerabilities privately to security@pulseapp.io. Include the affected version or commit, deployment model, required privileges, reproduction steps, expected impact, and any suggested containment. Do not include live credentials or customer data.

General defects and hardening suggestions that do not disclose an exploitable weakness can use the public issue tracker. The canonical disclosure contact and current security guidance remain in the Security Policy.