The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
Harden external-volume launchd diagnostics
Justin D'Souza112d9e1542d5
diff --git a/cli/beacon/internal/endpoint/diagnostics/diagnostics.go b/cli/beacon/internal/endpoint/diagnostics/diagnostics.goindex 718d49dc..0c86fb4e 100644--- a/cli/beacon/internal/endpoint/diagnostics/diagnostics.go+++ b/cli/beacon/internal/endpoint/diagnostics/diagnostics.go@@ -82,16 +82,20 @@ func launchAgentVolumeCheck(vol service.LaunchAgentVolume) Check {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 no private " +- "directory on the startup volume was found to bootstrap a copy from",+ 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: SeverityLow,+ 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. If the collector is not running after a restart or login, repair the install to restage them",+ 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"}}diff --git a/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go b/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.goindex 3a1c3f76..ab26cae5 100644--- a/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go+++ b/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go@@ -203,19 +203,23 @@ func TestLaunchAgentVolumeCheck(t *testing.T) {StagingDir: "/var/folders/xx/T/beacon-launchd-502",Reason: "/Volumes/Ext/Library/LaunchAgents is on a different volume than /Users",})- if staged.Status != StatusWarn || staged.Evidence != "launch_agents_external_volume_staged" ||+ if staged.Status != StatusWarn || staged.Severity != SeverityMedium ||+ staged.Evidence != "launch_agents_external_volume_staged" ||staged.Action != "beacon endpoint repair --user" ||- !strings.Contains(staged.Message, "/var/folders/xx/T/beacon-launchd-502") {+ !strings.Contains(staged.Message, "/var/folders/xx/T/beacon-launchd-502") ||+ !strings.Contains(staged.Message, "not guaranteed") {t.Fatalf("staged external-volume check = %#v", staged)}unstaged := launchAgentVolumeCheck(service.LaunchAgentVolume{- PlistDir: "/Volumes/Ext/Library/LaunchAgents",- External: true,- Reason: "/Volumes/Ext/Library/LaunchAgents is under /Volumes",+ PlistDir: "/Volumes/Ext/Library/LaunchAgents",+ External: true,+ StagingError: "/private/tmp/beacon-launchd-502 is mode 770",+ Reason: "/Volumes/Ext/Library/LaunchAgents is under /Volumes",})if unstaged.Status != StatusFail || unstaged.Evidence != "launch_agents_external_volume_unstaged" ||- !strings.Contains(unstaged.Action, "--no-start") || !strings.Contains(unstaged.Action, "launchctl bootstrap gui/") {+ !strings.Contains(unstaged.Action, "--no-start") || !strings.Contains(unstaged.Action, "launchctl bootstrap gui/") ||+ !strings.Contains(unstaged.Message, "mode 770") {t.Fatalf("unstaged external-volume check = %#v", unstaged)}}diff --git a/cli/beacon/internal/endpoint/service/launchd_volume.go b/cli/beacon/internal/endpoint/service/launchd_volume.goindex 496c4286..452eef1d 100644--- a/cli/beacon/internal/endpoint/service/launchd_volume.go+++ b/cli/beacon/internal/endpoint/service/launchd_volume.go@@ -44,6 +44,8 @@ type LaunchAgentVolume struct {// StagingDir is the private startup-volume directory the plist is bootstrapped from when// External is true. Empty when External is false, or when no usable location was found.StagingDir string `json:"staging_dir,omitempty"`+ // StagingError explains why none of the candidate startup-volume directories was usable.+ StagingError string `json:"staging_error,omitempty"`// Reason says how External was decided, for diagnostics.Reason string `json:"reason,omitempty"`}@@ -70,20 +72,35 @@ func InspectLaunchAgentVolume(plistPath string) LaunchAgentVolume {if !vol.External {return vol}+ var stagingErrors []stringfor _, base := range launchdStagingBases() {if strings.TrimSpace(base) == "" {continue}if bootErr == nil {if id, err := launchdVolumeID(base); err != nil || id != bootID {+ if err != nil {+ stagingErrors = append(stagingErrors, fmt.Sprintf("%s: cannot inspect volume: %v", base, err))+ } else {+ stagingErrors = append(stagingErrors, fmt.Sprintf("%s: not on the startup volume", base))+ }continue}} else if underVolumes(base) {+ stagingErrors = append(stagingErrors, fmt.Sprintf("%s: under /Volumes", base))continue}- vol.StagingDir = filepath.Join(base, launchdStagingDirName())+ candidate := filepath.Join(base, launchdStagingDirName())+ if err := probeLaunchdStagingDir(candidate); err != nil {+ stagingErrors = append(stagingErrors, fmt.Sprintf("%s: %v", candidate, err))+ continue+ }+ vol.StagingDir = candidatebreak}+ if vol.StagingDir == "" {+ vol.StagingError = strings.Join(stagingErrors, "; ")+ }return vol}@@ -113,7 +130,11 @@ func launchdBootstrapPath(domain, plistPath string) (string, string) {return plistPath, ""}if vol.StagingDir == "" {- return plistPath, externalVolumeNote(domain, vol, "", errors.New("no private directory on the startup volume was found"))+ err := errors.New("no usable private directory on the startup volume was found")+ if vol.StagingError != "" {+ err = errors.New(vol.StagingError)+ }+ return plistPath, externalVolumeNote(domain, vol, "", err)}staged, err := stageLaunchdPlist(plistPath, vol.StagingDir)if err != nil {@@ -132,10 +153,35 @@ func externalVolumeNote(domain string, vol LaunchAgentVolume, staged string, sta} else {fmt.Fprintf(&b, " Beacon bootstrapped a copy staged at %s, and launchd refused that too.", staged)}- fmt.Fprintf(&b, " To load it by hand: install with --no-start, copy the plist from %s into a private directory on the startup volume (mkdir -p -m 700 \"$TMPDIR/beacon-launchd\"), then run `launchctl bootstrap %s <copied plist>`.", vol.PlistDir, domain)+ fmt.Fprintf(&b, " To load it by hand: install with --no-start, copy the plist from %s into a private directory on the startup volume (`mkdir -p \"$TMPDIR/beacon-launchd\" && chmod 700 \"$TMPDIR/beacon-launchd\"`), then run `launchctl bootstrap %s <copied plist>`.", vol.PlistDir, domain)return b.String()}+// probeLaunchdStagingDir verifies the same ownership, mode and write requirements used by staging.+// It removes an empty directory it created so inspection does not leave state behind.+func probeLaunchdStagingDir(dir string) error {+ if err := os.Mkdir(dir, 0o700); err != nil {+ if !os.IsExist(err) {+ return err+ }+ } else {+ defer os.Remove(dir)+ }+ if err := checkPrivateStagingDir(dir); err != nil {+ return err+ }+ probe, err := os.CreateTemp(dir, ".probe-*")+ if err != nil {+ return err+ }+ probePath := probe.Name()+ if err := probe.Close(); err != nil {+ _ = os.Remove(probePath)+ return err+ }+ return os.Remove(probePath)+}+// stageLaunchdPlist copies plistPath into stagingDir under the same name and returns the copy's path.//// The directory is a fixed name in a temp directory, so it has to be one this user owns and nobodydiff --git a/cli/beacon/internal/endpoint/service/launchd_volume_test.go b/cli/beacon/internal/endpoint/service/launchd_volume_test.goindex d2d7c523..5b84c590 100644--- a/cli/beacon/internal/endpoint/service/launchd_volume_test.go+++ b/cli/beacon/internal/endpoint/service/launchd_volume_test.go@@ -122,6 +122,12 @@ func TestInspectLaunchAgentVolumeFlagsPlistOffTheStartupVolume(t *testing.T) {if !vol.External {t.Fatalf("plist on the external volume was not flagged: %#v", vol)}+ if !testenv.HasPOSIXFileModes() {+ if vol.StagingDir != "" || vol.StagingError == "" {+ t.Fatalf("host without POSIX modes should reject private staging: %#v", vol)+ }+ return+ }if vol.StagingDir != f.staging {t.Fatalf("staging dir = %q, want %q on the startup volume", vol.StagingDir, f.staging)}@@ -130,6 +136,44 @@ func TestInspectLaunchAgentVolumeFlagsPlistOffTheStartupVolume(t *testing.T) {}}+func TestInspectLaunchAgentVolumeRejectsAnUnsafeStagingDirectory(t *testing.T) {+ testenv.RequirePOSIXFileModes(t)+ f := newVolumeFixture(t)+ if err := os.Mkdir(f.staging, 0o770); err != nil {+ t.Fatal(err)+ }++ vol := InspectLaunchAgentVolume(f.externalPlist(t, UserLabel))+ if !vol.External || vol.StagingDir != "" {+ t.Fatalf("unsafe staging directory reported usable: %#v", vol)+ }+ if !strings.Contains(vol.StagingError, "must not be accessible to other users") {+ t.Fatalf("staging error does not explain unsafe permissions: %#v", vol)+ }+}++func TestInspectLaunchAgentVolumeFallsBackFromAnUnsafeStagingDirectory(t *testing.T) {+ testenv.RequirePOSIXFileModes(t)+ f := newVolumeFixture(t)+ if err := os.Mkdir(f.staging, 0o770); err != nil {+ t.Fatal(err)+ }+ fallbackBase := filepath.Join(f.boot, "private-tmp")+ if err := os.Mkdir(fallbackBase, 0o777); err != nil {+ t.Fatal(err)+ }+ primaryBase := filepath.Dir(f.staging)+ oldBases := launchdStagingBases+ launchdStagingBases = func() []string { return []string{primaryBase, fallbackBase} }+ t.Cleanup(func() { launchdStagingBases = oldBases })++ vol := InspectLaunchAgentVolume(f.externalPlist(t, UserLabel))+ want := filepath.Join(fallbackBase, launchdStagingDirName())+ if vol.StagingDir != want || vol.StagingError != "" {+ t.Fatalf("fallback staging directory = %#v, want %s", vol, want)+ }+}+func TestInspectLaunchAgentVolumeLeavesStartupVolumeHomesAlone(t *testing.T) {f := newVolumeFixture(t)vol := InspectLaunchAgentVolume(f.bootPlist(t, UserLabel))diff --git a/docs/cli/endpoint-paths.mdx b/docs/cli/endpoint-paths.mdxindex 1ef006de..b4ac0cf7 100644--- a/docs/cli/endpoint-paths.mdx+++ b/docs/cli/endpoint-paths.mdx@@ -40,7 +40,7 @@ The Beacon forwarder started by `beacon endpoint connect` is a second, residentThe scheduled inventory job is a third, one-shot unit that `beacon endpoint install` writes in both modes and the package postinstall reconciles on every upgrade: `/Library/LaunchDaemons/com.beacon.endpoint.inventory.plist` or `~/Library/LaunchAgents/com.beacon.endpoint.inventory.plist` on macOS, `beacon-inventory.timer` plus `beacon-inventory.service` under `/etc/systemd/system` or `~/.config/systemd/user` on Linux. It writes `inventory_state.jsonl` and its `inventory-state.json` state file beside the runtime log. Like the forwarder it is not offered in supervised mode; run `beacon endpoint inventory heartbeat --scheduled` from your own scheduler there.-On macOS, when `~/Library/LaunchAgents` is on a volume other than the startup volume, such as a home directory on an external disk, launchd refuses to bootstrap plists from it. Beacon then bootstraps each user LaunchAgent from a copy staged in `$TMPDIR/beacon-launchd-<uid>`, falling back to `/private/tmp/beacon-launchd-<uid>`. The canonical plist stays in `~/Library/LaunchAgents`. See [Home directory on an external volume](/platforms/macos#home-directory-on-an-external-volume).+On macOS, when `~/Library/LaunchAgents` is on a volume other than the startup volume, such as a home directory on an external disk, launchd refuses to bootstrap plists from it. Beacon then bootstraps each user LaunchAgent for the current login session from a copy staged in `$TMPDIR/beacon-launchd-<uid>`, falling back to `/private/tmp/beacon-launchd-<uid>`. The canonical plist stays in `~/Library/LaunchAgents`; automatic loading after logout or restart is not guaranteed for this layout. See [Home directory on an external volume](/platforms/macos#home-directory-on-an-external-volume).Windows has no unit file to point at: the service definition lives in the registry, so that is what `beacon endpoint status` reports where the other platforms report a path. And there is no counterpart to `systemctl --user` or launchd's per-user domain, so a Windows user-mode install always gets the supervised collector. See [Windows install](/platforms/windows#user-mode-install).diff --git a/docs/platforms/macos.mdx b/docs/platforms/macos.mdxindex e41f5d4e..2abe7617 100644--- a/docs/platforms/macos.mdx+++ b/docs/platforms/macos.mdx@@ -72,13 +72,14 @@ beacon endpoint doctor --fixlaunchd will not bootstrap a LaunchAgent whose plist is on a volume other than the startup volume. When your home directory is on an external disk (`/Volumes/<disk>`), `launchctl bootstrap gui/<uid> ~/Library/LaunchAgents/<label>.plist` fails with `Bootstrap failed: 5: Input/output error`, even with ownership enabled on the volume.-A user-mode install handles this itself. Beacon still writes the canonical plists to `~/Library/LaunchAgents`, but when that directory is on a different volume from `/Users`, it copies each plist into a private directory on the startup volume and bootstraps the copy instead. That directory is `$TMPDIR/beacon-launchd-<uid>`, with `/private/tmp/beacon-launchd-<uid>` as a fallback, and it must be owned by you with mode `0700`. This applies to the collector, the scheduled inventory job, and the managed forwarder. The program, its config, and the logs stay where they are, and a home on the startup volume is bootstrapped in place as before. `launchctl print "gui/$(id -u)/com.beacon.endpoint.collector.user"` shows the staged path.+A user-mode install handles the current login session itself. Beacon still writes the canonical plists to `~/Library/LaunchAgents`, but when that directory is on a different volume from `/Users`, it copies each plist into a private directory on the startup volume and bootstraps the copy instead. That directory is `$TMPDIR/beacon-launchd-<uid>`, with `/private/tmp/beacon-launchd-<uid>` as a fallback, and it must be owned by you with mode `0700`. This applies to the collector, the scheduled inventory job, and the managed forwarder. The program, its config, and the logs stay where they are, and a home on the startup volume is bootstrapped in place as before. `launchctl print "gui/$(id -u)/com.beacon.endpoint.collector.user"` shows the staged path.-`beacon endpoint doctor` reports this layout as `launch_agents_volume`. If the collector is not running after a restart or login, run `beacon endpoint repair --user`, which stages fresh copies and bootstraps them again. If Beacon cannot stage the copies, doctor reports a failure. In that case, bootstrap them by hand:+The explicit bootstrap registration belongs to the current launchd login domain. Beacon cannot guarantee that launchd will reload the canonical external-volume plists automatically after logout or restart. `beacon endpoint doctor` therefore reports this layout as a medium-severity `launch_agents_volume` warning even when staging works. If the collector is not running after a restart or login, run `beacon endpoint repair --user`, which stages fresh copies and bootstraps them again. If Beacon cannot safely create and write the staging directory, doctor reports a failure with the rejected path and reason. In that case, bootstrap the plists by hand:```bash title="Manual bootstrap from the startup volume"beacon endpoint install --user --no-start-mkdir -p -m 700 "$TMPDIR/beacon-launchd"+mkdir -p "$TMPDIR/beacon-launchd"+chmod 700 "$TMPDIR/beacon-launchd"for label in com.beacon.endpoint.collector.user com.beacon.endpoint.inventory; docp "$HOME/Library/LaunchAgents/$label.plist" "$TMPDIR/beacon-launchd/"launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true