Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

14.1 KB
Raw Blame
package diagnostics

import (
	"fmt"
	"os"
	"os/user"
	"path/filepath"
	"runtime"
	"strings"

	"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/collector"
	endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
	"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/service"
	"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/writer"
	"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/localingest"
)

type Check struct {
	Name     string `json:"name"`
	Target   string `json:"target,omitempty"`
	Status   string `json:"status"`
	Severity string `json:"severity"`
	Message  string `json:"message,omitempty"`
	Evidence string `json:"evidence,omitempty"`
	Action   string `json:"action,omitempty"`
}

const (
	StatusOK   = "ok"
	StatusWarn = "warn"
	StatusFail = "fail"

	SeverityInfo   = "info"
	SeverityLow    = "low"
	SeverityMedium = "medium"
	SeverityHigh   = "high"
)

func Run(cfg endpointconfig.Config) []Check {
	checks := []Check{
		checkFile("config", endpointconfig.ConfigPath(cfg.UserMode), true),
		checkFile("collector_config", cfg.Collector.ConfigPath, true),
		checkFile("runtime_log", cfg.LogPath, false),
		checkLogPermissionsFor(cfg),
		checkCollectorHealth(cfg),
	}
	if !cfg.UserMode {
		checks = append(checks, checkLogAccess(cfg, localingest.Deliverer{}))
	}
	// The service definition check is named after whichever manager is actually in use, so
	// the output is interpretable on a mixed fleet and a Linux host is not told to look for a
	// launchd plist. Supervised mode has no unit file to check -- its pidfile is runtime
	// state, not configuration, so a missing one just means "not started".
	mgr := service.Manager{UserMode: cfg.UserMode}
	switch mgr.ResolvedKind() {
	case service.KindLaunchd:
		if path, err := mgr.UnitPath(); err == nil {
			checks = append(checks, checkFile("launchd_plist", path, true))
			// A home directory on an external volume is the one layout where the plist being
			// present says nothing about whether launchd will load it (#639).
			if cfg.UserMode {
				checks = append(checks, launchAgentVolumeCheck(service.InspectLaunchAgentVolume(path)))
			}
		}
	case service.KindSystemd:
		if path, err := mgr.UnitPath(); err == nil {
			checks = append(checks, checkFile("systemd_unit", path, true))
		}
		// A --user unit stops at logout unless linger is set, and that failure is invisible
		// until the user next logs out and telemetry quietly stops. Surfaced as a warning
		// rather than a failure: collecting until logout is degraded, not broken.
		if cfg.UserMode {
			checks = append(checks, lingerCheck())
		}
	}
	return checks
}

// launchAgentVolumeCheck reports a LaunchAgents directory off the startup volume. launchd refuses to
// bootstrap plists from there ("Bootstrap failed: 5: Input/output error"), so Beacon bootstraps a
// staged copy on the startup volume instead. That works for the running session, but it is a
// layout worth naming: whether launchd's own login scan loads the canonical plist is not something
// Beacon can see, and a collector missing after a restart is fixed by a repair, which restages it.
func launchAgentVolumeCheck(vol service.LaunchAgentVolume) Check {
	if !vol.External {
		return Check{Name: "launch_agents_volume", Target: vol.PlistDir, Status: StatusOK, Severity: SeverityInfo,
			Message: "LaunchAgents is on the startup volume", Evidence: "launch_agents_startup_volume"}
	}
	if vol.StagingDir == "" {
		detail := "no private directory on the startup volume was usable"
		if vol.StagingError != "" {
			detail += ": " + vol.StagingError
		}
		return Check{Name: "launch_agents_volume", Target: vol.PlistDir, Status: StatusFail, Severity: SeverityHigh,
			Message:  vol.Reason + ", so launchd refuses to bootstrap Beacon's LaunchAgents from it, and " + detail,
			Evidence: "launch_agents_external_volume_unstaged",
			Action: "install with --no-start, copy the plists from " + vol.PlistDir + " into a private directory on the " +
				"startup volume, and run `launchctl bootstrap gui/$(id -u) <copied plist>` for each"}
	}
	return Check{Name: "launch_agents_volume", Target: vol.PlistDir, Status: StatusWarn, Severity: SeverityMedium,
		Message: vol.Reason + ", which launchd will not bootstrap LaunchAgents from; Beacon bootstraps copies staged in " +
			vol.StagingDir + " instead for this login session. Automatic loading after logout or restart is not guaranteed; " +
			"if the collector is not running, repair the install to restage the jobs",
		Evidence: "launch_agents_external_volume_staged",
		Action:   "beacon endpoint repair --user"}
}

func lingerCheck() Check {
	u, err := user.Current()
	if err != nil || u.Username == "" {
		return Check{Name: "systemd_user_linger", Status: StatusWarn,
			Message:  "could not determine the current user, so logout persistence is unverified",
			Evidence: "linger_unknown"}
	}
	if service.LingerEnabled(u.Username) {
		return Check{Name: "systemd_user_linger", Status: StatusOK, Target: u.Username,
			Message: "user unit will survive logout"}
	}
	return Check{Name: "systemd_user_linger", Status: StatusWarn, Target: u.Username,
		Message:  "linger is not enabled, so the collector stops when this user logs out",
		Evidence: "linger_disabled",
		Action:   service.LingerRemediation(u.Username)}
}

func checkCollectorHealth(cfg endpointconfig.Config) Check {
	status := collector.CheckStatus(cfg)
	if status.HealthReady {
		return Check{Name: "collector_health", Target: fmt.Sprintf("127.0.0.1:%d", status.HealthPort), Status: StatusOK, Severity: SeverityInfo, Message: "collector health check is ready", Evidence: "health_check_ready"}
	}
	message := status.Message
	if message == "" {
		message = "collector health check is not ready"
	}
	return Check{Name: "collector_health", Target: fmt.Sprintf("127.0.0.1:%d", status.HealthPort), Status: StatusWarn, Severity: SeverityMedium, Message: message, Evidence: "health_check_unavailable"}
}

func HasFailures(checks []Check) bool {
	for _, check := range checks {
		if check.Status == StatusFail {
			return true
		}
	}
	return false
}

func checkFile(name, path string, required bool) Check {
	info, err := os.Stat(path)
	if err != nil {
		if os.IsNotExist(err) && !required {
			return Check{Name: name, Target: path, Status: StatusWarn, Severity: SeverityLow, Message: fmt.Sprintf("%s does not exist yet", path), Evidence: "missing_optional_file"}
		}
		return Check{Name: name, Target: path, Status: StatusFail, Severity: SeverityMedium, Message: err.Error(), Evidence: "stat_failed"}
	}
	if info.IsDir() {
		return Check{Name: name, Target: path, Status: StatusFail, Severity: SeverityMedium, Message: path + " is a directory", Evidence: "target_is_directory"}
	}
	return Check{Name: name, Target: path, Status: StatusOK, Severity: SeverityInfo, Message: path, Evidence: "file_exists"}
}

func checkLogPermissions(path string, userMode bool) Check {
	info, err := os.Stat(path)
	if err != nil {
		return Check{Name: "runtime_log_permissions", Target: path, Status: StatusWarn, Severity: SeverityLow, Message: "runtime log not created yet", Evidence: "runtime_log_missing"}
	}
	if runtime.GOOS == "windows" {
		// The two scopes fail differently there, so they are asked different questions. Only a
		// system-mode install has a privileged writer and unprivileged hooks; a user-mode log lives
		// in that user's own profile and is written by processes running as them.
		if userMode {
			return checkLogWritableByThisUser(path)
		}
		return checkLogACL(path)
	}
	mode := info.Mode().Perm()
	if mode&0222 == 0 {
		return Check{Name: "runtime_log_permissions", Target: path, Status: StatusFail, Severity: SeverityHigh, Message: fmt.Sprintf("runtime log is not writable: %o", mode), Evidence: "not_writable"}
	}
	// System mode asks a sharper question than "is this writable by somebody".
	//
	// The collector runs as root and hooks run as the logged-in user, so the check that matters is
	// whether a *non-root* process can write here. mode&0222 cannot answer that: it is satisfied by
	// the owner's write bit, so a root-owned 0600 log -- which no hook can write -- passed as OK.
	// The Windows branch above was added for exactly this reason; the POSIX branch had the same
	// hole and nobody had looked.
	//
	// Both parts have to hold. The file needs a world-write bit, and the directory needs to be
	// traversable, because a hook that cannot enter the directory never gets as far as the file.
	if !userMode {
		if mode&0002 == 0 {
			return Check{Name: "runtime_log_permissions", Target: path, Status: StatusFail, Severity: SeverityHigh,
				Message:  fmt.Sprintf("runtime log is mode %o, so hooks running as the logged-in user cannot append to it and their events are lost", mode),
				Evidence: "not_writable_by_hooks", Action: "sudo chmod 0666 " + path}
		}
		if dir := filepath.Dir(path); dir != "" {
			if dirInfo, dirErr := os.Stat(dir); dirErr == nil {
				if dirMode := dirInfo.Mode().Perm(); dirMode&0001 == 0 || dirMode&0004 == 0 {
					return Check{Name: "runtime_log_permissions", Target: dir, Status: StatusFail, Severity: SeverityHigh,
						Message:  fmt.Sprintf("log directory is mode %o, so hooks running as the logged-in user cannot reach the runtime log inside it", dirMode),
						Evidence: "log_dir_not_traversable", Action: "sudo chmod 0755 " + dir}
				}
			}
		}
	}
	// A user-mode log is private on purpose: Beacon creates it 0600, since it holds that user's
	// prompts and command output and every process that writes it runs as them. Owner-only is the
	// healthy state there, not a readability problem.
	if userMode && mode&0200 != 0 {
		return Check{Name: "runtime_log_permissions", Target: path, Status: StatusOK, Severity: SeverityInfo, Message: fmt.Sprintf("mode %o", mode), Evidence: fmt.Sprintf("mode_%o", mode)}
	}
	if mode&0044 == 0 {
		return Check{Name: "runtime_log_permissions", Target: path, Status: StatusWarn, Severity: SeverityLow, Message: fmt.Sprintf("runtime log may not be readable by Wazuh: %o", mode), Evidence: "not_group_or_world_readable"}
	}
	return Check{Name: "runtime_log_permissions", Target: path, Status: StatusOK, Severity: SeverityInfo, Message: fmt.Sprintf("mode %o", mode), Evidence: fmt.Sprintf("mode_%o", mode)}
}

// checkLogWritableByThisUser is the user-mode Windows form of the question.
//
// The INTERACTIVE grant that system mode installs is deliberately absent here: a user-mode log
// holds that person's prompt text, and widening its ACL to every interactive account would hand it
// to anyone else who logs on. Running the system-mode check anyway would report a high-severity
// failure on every correctly configured user-mode endpoint -- a doctor that cries wolf on the
// normal case is one nobody reads when it finally has something to say.
//
// A test write is the right instrument in this scope, and only in this scope. The trap it falls
// into in system mode -- doctor runs elevated, so it proves access for a user whose access was
// never in question -- does not apply when the hooks run as the same person doctor does.
func checkLogWritableByThisUser(path string) Check {
	f, err := os.OpenFile(path, os.O_APPEND|os.O_WRONLY, 0)
	if err != nil {
		return Check{Name: "runtime_log_permissions", Target: path, Status: StatusFail,
			Severity: SeverityHigh,
			Message:  "the runtime log is not writable by this user: " + err.Error(),
			// Distinct from the POSIX not_writable on purpose. Evidence strings are what decide the
			// remediation doctor prints and what fleet tooling keys on, and the two have nothing in
			// common but the symptom: one is fixed by chmod, which does not exist here.
			Evidence: "acl_not_writable_by_user"}
	}
	_ = f.Close()
	return Check{Name: "runtime_log_permissions", Target: path, Status: StatusOK,
		Severity: SeverityInfo, Message: "the runtime log is writable by this user",
		Evidence: "writable_by_owner"}
}

// checkLogACL is the system-mode Windows form of the same question: can the people whose sessions
// this endpoint captures append to its log -- and can they do anything more?
//
// The mode-bit check above cannot answer it there. Windows reports 0666 for any ordinary file
// regardless of its ACL, so `mode&0222 == 0` is never true and the check would report OK for
// exactly the configuration it exists to catch -- a %ProgramData% log that only administrators can
// write, with every hook write failing silently.
//
// The second half matters as much. An endpoint installed before the log ACL was narrowed gives
// interactive users Modify on the directory, which lets any of them delete or rename the log and
// plant links a SYSTEM write follows. That endpoint captures everything, so nothing else would
// ever flag it; this does, and doctor --fix applies the same ACL a fresh install does.
//
// Read from the ACL rather than by attempting a write, because doctor usually runs elevated: a
// test write would succeed for the very user whose access is not in question.
func checkLogACL(path string) Check {
	dir := filepath.Dir(path)
	state, err := writer.CheckSystemLogACL(path)
	switch {
	case err != nil:
		// Unknown is reported as unknown. Claiming either answer here would be worse than saying
		// the check could not run.
		return Check{Name: "runtime_log_permissions", Target: dir, Status: StatusWarn,
			Severity: SeverityLow, Message: "could not read the log directory ACL: " + err.Error(),
			Evidence: "acl_unreadable"}
	case len(state.Problems) > 0:
		return Check{Name: "runtime_log_permissions", Target: dir, Status: StatusFail,
			Severity: SeverityHigh,
			Message: "the log directory ACL lets ordinary users do more than append, so one could " +
				"redirect a SYSTEM write: " + strings.Join(state.Problems, "; "),
			Evidence: "acl_too_broad"}
	case !state.HooksCanAppend:
		return Check{Name: "runtime_log_permissions", Target: dir, Status: StatusFail,
			Severity: SeverityHigh,
			Message: "interactive users cannot append to the runtime log, so agent hooks will " +
				"fail silently while the collector reports healthy",
			Evidence: "acl_missing_interactive_write"}
	default:
		return Check{Name: "runtime_log_permissions", Target: dir, Status: StatusOK,
			Severity: SeverityInfo, Message: "interactive users may append to the runtime log, and " +
				"only SYSTEM and Administrators may change the log directory",
			Evidence: "acl_interactive_write"}
	}
}