Skip to content

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

11.1 KB
Raw Blame
package diagnostics

import (
	"errors"
	"fmt"
	"io/fs"
	"os"
	"path/filepath"
	"runtime"
	"strings"

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

// repairSystemAction repairs a system install with the privilege it needs on this platform.
var repairSystemAction = func() string {
	if runtime.GOOS == "windows" {
		return "beacon endpoint repair --system (from an elevated shell)"
	}
	return "sudo beacon endpoint repair --system"
}()

// repairSystemWith is repairSystemAction with more flags.
func repairSystemWith(flags string) string {
	if runtime.GOOS == "windows" {
		return "beacon endpoint repair --system " + flags + " (from an elevated shell)"
	}
	return "sudo beacon endpoint repair --system " + flags
}

// elevated says how to run doctor with the privilege a restricted log needs on this platform.
func elevated() string {
	if runtime.GOOS == "windows" {
		return "from an elevated shell"
	}
	return "with sudo"
}

// privilegedWriters names who writes a restricted log: root, or SYSTEM and Administrators.
func privilegedWriters() string {
	if runtime.GOOS == "windows" {
		return "SYSTEM and Administrators"
	}
	return "root"
}

// restrictedLogProblems reads a restricted log's ACL on Windows (writer.CheckRestrictedSystemLogACL);
// a variable for tests.
var restrictedLogProblems = writer.CheckRestrictedSystemLogACL

// logMarkedRestricted reads the log's restricted marker. A variable because only a marker root owns
// counts, and tests cannot be root.
var logMarkedRestricted = asymptoteobserve.RuntimeLogAccessRestricted

// checkLogPermissionsFor asks the question that fits the log's access mode. A shared log must be
// appendable by every hook; a restricted one must be appendable by none, which is the point of it.
func checkLogPermissionsFor(cfg endpointconfig.Config) Check {
	if cfg.RestrictedLogAccess() {
		return checkRestrictedLogPermissions(cfg.LogPath)
	}
	return checkLogPermissions(cfg.LogPath, cfg.UserMode)
}

// checkRestrictedLogPermissions reports a restricted log any account but root and the readers group
// can reach. Doctor usually runs with sudo; run without it, it cannot look inside the directory,
// which is itself the restricted mode working, and says so instead of guessing.
func checkRestrictedLogPermissions(path string) Check {
	if runtime.GOOS == "windows" {
		return checkRestrictedLogACL(path)
	}
	dir := filepath.Dir(path)
	dirInfo, err := os.Stat(dir)
	if err != nil {
		return Check{Name: "runtime_log_permissions", Target: dir, Status: StatusFail, Severity: SeverityMedium,
			Message: "the log directory is missing: " + err.Error(), Evidence: "log_dir_missing", Action: repairSystemAction}
	}
	if mode := dirInfo.Mode(); mode.Perm()&0o007 != 0 || mode.Perm()&0o020 != 0 {
		return Check{Name: "runtime_log_permissions", Target: dir, Status: StatusFail, Severity: SeverityHigh,
			Message:  fmt.Sprintf("the restricted log's directory is mode %o, which lets other accounts reach or change it", mode.Perm()),
			Evidence: "restricted_log_dir_too_open", Action: repairSystemAction}
	}
	info, err := os.Stat(path)
	switch {
	case errors.Is(err, fs.ErrPermission):
		return Check{Name: "runtime_log_permissions", Target: path, Status: StatusOK, Severity: SeverityInfo,
			Message:  "this account cannot open the restricted log, as intended; run doctor " + elevated() + " to inspect it",
			Evidence: "restricted_log_not_readable_by_caller"}
	case 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 mode := info.Mode().Perm(); mode&0o007 != 0 || mode&0o020 != 0 {
		return Check{Name: "runtime_log_permissions", Target: path, Status: StatusFail, Severity: SeverityHigh,
			Message:  fmt.Sprintf("the restricted log is mode %o, so accounts outside root and the %s group can read or change it", mode, loggroup.Name),
			Evidence: "restricted_log_too_open", Action: repairSystemAction}
	}
	return Check{Name: "runtime_log_permissions", Target: path, Status: StatusOK, Severity: SeverityInfo,
		Message: fmt.Sprintf("mode %o, restricted", info.Mode().Perm()), Evidence: fmt.Sprintf("mode_%o", info.Mode().Perm())}
}

// checkLogAccess reports the system log's access mode and whether everything the mode depends on
// is in place: in the restricted mode, the marker that keeps the root writers from widening the
// log again, and the collector's ingest socket, without which every hook spools its events instead
// of recording them.
func checkLogAccess(cfg endpointconfig.Config, ingest localingest.Deliverer) Check {
	path := cfg.LogPath
	const name = "runtime_log_access"
	markerReadable := true
	if _, err := os.Stat(filepath.Dir(path)); errors.Is(err, fs.ErrPermission) {
		markerReadable = false
	} else if _, err := os.Stat(asymptoteobserve.LogAccessMarkerPath(path)); errors.Is(err, fs.ErrPermission) {
		markerReadable = false
	}
	marked := logMarkedRestricted(path)

	if !cfg.RestrictedLogAccess() {
		if marked {
			return Check{Name: name, Target: path, Status: StatusWarn, Severity: SeverityMedium,
				Message:  "the log is marked restricted but the endpoint config says shared, so hooks cannot append to it",
				Evidence: "log_access_mismatch", Action: repairSystemWith("--log-access shared")}
		}
		if pending, err := ingest.Pending(path); err == nil && pending > 0 {
			// Left from a time the log was restricted, or refused this account; the account's
			// next event appends them.
			return Check{Name: name, Target: localingest.DefaultSpoolDir(), Status: StatusWarn, Severity: SeverityLow,
				Message:  fmt.Sprintf("shared; %d events from this account are waiting in its spool and go to the log with its next event", pending),
				Evidence: "ingest_spool_pending"}
		}
		return Check{Name: name, Target: path, Status: StatusOK, Severity: SeverityInfo,
			Message:  "shared: hooks append directly, and any local account can modify or read the log; `--log-access restricted` narrows it",
			Evidence: "log_access_shared"}
	}

	if markerReadable && !marked {
		return Check{Name: name, Target: path, Status: StatusFail, Severity: SeverityHigh,
			Message:  "the endpoint config says restricted but the log is not marked, so the collector will make it writable by every account again at its next write",
			Evidence: "log_access_marker_missing", Action: repairSystemAction}
	}
	// A probe, not a look at the socket file: a collector that was killed leaves its socket behind,
	// and only a connection tells a live collector from that.
	probe := ingest.Client
	probe.LogPath = path
	switch err := probe.Probe(); {
	case errors.Is(err, localingest.ErrNoSocket):
		return Check{Name: name, Target: ingestSocketPath(ingest), Status: StatusFail, Severity: SeverityHigh,
			Message:  "the collector is not serving the ingest socket, so hooks cannot record events and are spooling them; start the collector",
			Evidence: "ingest_socket_missing", Action: repairSystemAction}
	case errors.Is(err, localingest.ErrUntrustedSocket):
		return Check{Name: name, Target: ingestSocketPath(ingest), Status: StatusFail, Severity: SeverityHigh,
			Message: "hooks will not send to the ingest socket: " + err.Error(), Evidence: "ingest_socket_untrusted", Action: repairSystemAction}
	case errors.Is(err, localingest.ErrLogMismatch):
		return Check{Name: name, Target: ingestSocketPath(ingest), Status: StatusFail, Severity: SeverityHigh,
			Message:  "the collector behind the ingest socket writes a different runtime log, so hooks writing " + path + " are spooling their events",
			Evidence: "ingest_log_mismatch", Action: repairSystemAction}
	case err != nil:
		return Check{Name: name, Target: ingestSocketPath(ingest), Status: StatusFail, Severity: SeverityHigh,
			Message:  "the ingest socket is there but the collector does not answer (" + err.Error() + "), so hooks are spooling their events; restart the collector",
			Evidence: "ingest_socket_unresponsive", Action: repairSystemAction}
	}
	if pending, err := ingest.Pending(path); err == nil && pending > 0 {
		return Check{Name: name, Target: localingest.DefaultSpoolDir(), Status: StatusWarn, Severity: SeverityLow,
			Message:  fmt.Sprintf("restricted; %d events from this account are waiting in its spool and go to the collector with the next event", pending),
			Evidence: "ingest_spool_pending"}
	}
	message := fmt.Sprintf("restricted: only the collector writes the log; %s and the %s group read it", privilegedWriters(), loggroup.Name)
	if !markerReadable {
		message += " (run doctor " + elevated() + " to inspect the log itself)"
	}
	return Check{Name: name, Target: path, Status: StatusOK, Severity: SeverityInfo, Message: message, Evidence: "log_access_restricted"}
}

func ingestSocketPath(ingest localingest.Deliverer) string {
	if ingest.Client.SocketPath != "" {
		return ingest.Client.SocketPath
	}
	return localingest.DefaultSocketPath
}

// checkRestrictedLogACL is checkRestrictedLogPermissions on Windows, where file modes say nothing:
// the directory and every file of the log family must grant nobody but SYSTEM, Administrators and
// the readers group (who may only read) anything at all. Run unelevated it cannot open the
// directory, which is the restricted mode working, unless it found a problem before it was refused.
func checkRestrictedLogACL(path string) Check {
	dir := filepath.Dir(path)
	problems, err := restrictedLogProblems(path)
	switch {
	// Before the errors: an account that can read the directory's ACL but not open what is in it
	// still found a directory too open, and that is the answer, not "as intended".
	case len(problems) > 0:
		return Check{Name: "runtime_log_permissions", Target: dir, Status: StatusFail, Severity: SeverityHigh,
			Message:  "the restricted log lets accounts outside SYSTEM, Administrators and the " + loggroup.Name + " group reach it: " + strings.Join(problems, "; "),
			Evidence: "restricted_log_too_open", Action: repairSystemAction}
	case errors.Is(err, fs.ErrPermission):
		return Check{Name: "runtime_log_permissions", Target: dir, Status: StatusOK, Severity: SeverityInfo,
			Message:  "this account cannot open the restricted log, as intended; run doctor " + elevated() + " to inspect it",
			Evidence: "restricted_log_not_readable_by_caller"}
	case errors.Is(err, fs.ErrNotExist):
		return Check{Name: "runtime_log_permissions", Target: dir, Status: StatusFail, Severity: SeverityMedium,
			Message: "the log directory is missing: " + err.Error(), Evidence: "log_dir_missing", Action: repairSystemAction}
	case err != nil:
		return Check{Name: "runtime_log_permissions", Target: dir, Status: StatusWarn, Severity: SeverityLow,
			Message: "could not read the restricted log's ACL: " + err.Error(), Evidence: "acl_unreadable"}
	}
	return Check{Name: "runtime_log_permissions", Target: dir, Status: StatusOK, Severity: SeverityInfo,
		Message: "restricted: only SYSTEM, Administrators and the " + loggroup.Name + " group can reach the log", Evidence: "restricted_acl"}
}