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
add Jamf-ready macOS packaging
Justin D'Souza8bfdf3fc68bd
diff --git a/.gitignore b/.gitignoreindex 3b46dcfb..a8cdf08b 100644--- a/.gitignore+++ b/.gitignore@@ -20,6 +20,7 @@ coverage.htmlcli/beacon/beaconcli/beacon/beacon-*cli/beacon/dist/+dist/# Hook helper binariescli/beacon-hooks/beacon-hooksdiff --git a/cli/beacon/internal/endpoint/collector/collector.go b/cli/beacon/internal/endpoint/collector/collector.goindex f326def8..795d03a5 100644--- a/cli/beacon/internal/endpoint/collector/collector.go+++ b/cli/beacon/internal/endpoint/collector/collector.go@@ -75,6 +75,9 @@ extensions:endpoint: 127.0.0.1:13133service:+ telemetry:+ metrics:+ level: noneextensions: [health_check]pipelines:logs:diff --git a/cli/beacon/internal/endpoint/collector/collector_test.go b/cli/beacon/internal/endpoint/collector/collector_test.goindex aacc0b9f..2f81f201 100644--- a/cli/beacon/internal/endpoint/collector/collector_test.go+++ b/cli/beacon/internal/endpoint/collector/collector_test.go@@ -39,6 +39,7 @@ func TestConfigYAMLIncludesReleaseContractFields(t *testing.T) {"max_event_bytes: 65536","rotate_bytes: 10485760","redact_secrets: true",+ "level: none","receivers: [otlp]","exporters: [beaconjson]",} {diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle.goindex c8782c5c..9d7acac6 100644--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go@@ -68,7 +68,7 @@ type Manifest struct {func Install(opts InstallOptions) (InstallResult, error) {cfg := buildConfig(opts)- if err := preflight(cfg); err != nil {+ if err := preflight(cfg, opts.StartService); err != nil {return InstallResult{}, err}manager := service.Manager{UserMode: cfg.UserMode}@@ -222,7 +222,7 @@ func loadOrDefault(userMode bool, logPath string) endpointconfig.Config {return endpointconfig.Default(userMode, logPath)}-func preflight(cfg endpointconfig.Config) error {+func preflight(cfg endpointconfig.Config, startService bool) error {if err := endpointconfig.ValidateContentRetention(cfg.ContentRetention); err != nil {return err}@@ -232,6 +232,9 @@ func preflight(cfg endpointconfig.Config) error {if !cfg.UserMode && os.Geteuid() != 0 {return fmt.Errorf("system install requires root; rerun with sudo or use --user")}+ if !startService {+ return nil+ }if !endpointcollector.PortAvailable(cfg.Collector.GRPCPort) {return fmt.Errorf("OTLP gRPC port %d is already in use", cfg.Collector.GRPCPort)}diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.goindex 16a2d8f7..a8a441d7 100644--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.go+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.go@@ -155,12 +155,32 @@ func TestPreflightRejectsPortInUse(t *testing.T) {cfg.Collector.GRPCPort = portcfg.Collector.HTTPPort = freePort(t)- err = preflight(cfg)+ err = preflight(cfg, true)if err == nil || !strings.Contains(err.Error(), "OTLP gRPC port") {t.Fatalf("preflight error = %v, want gRPC port in use", err)}}+func TestPreflightAllowsPortInUseWhenServiceWillNotStart(t *testing.T) {+ if runtime.GOOS != "darwin" {+ t.Skip("preflight is macOS-only")+ }+ ln, err := net.Listen("tcp", "127.0.0.1:0")+ if err != nil {+ t.Fatalf("listen: %v", err)+ }+ defer ln.Close()+ port := ln.Addr().(*net.TCPAddr).Port++ cfg := endpointconfig.Default(true, filepath.Join(t.TempDir(), "runtime.jsonl"))+ cfg.Collector.GRPCPort = port+ cfg.Collector.HTTPPort = freePort(t)++ if err := preflight(cfg, false); err != nil {+ t.Fatalf("preflight returned error for no-start install: %v", err)+ }+}+func TestUninstallFallbackRemovesKnownFiles(t *testing.T) {if runtime.GOOS != "darwin" {t.Skip("launchd paths are macOS-only")diff --git a/collector-builder/builder.yaml b/collector-builder/builder.yamlindex dfe03e08..affc6b8b 100644--- a/collector-builder/builder.yaml+++ b/collector-builder/builder.yaml@@ -15,5 +15,5 @@ exporters:path: ./exporter/beaconjsonexporterextensions:- - gomod: go.opentelemetry.io/collector/extension/healthcheckextension v0.121.0+ - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/healthcheckextension v0.121.0diff --git a/packaging/macos/README.md b/packaging/macos/README.mdindex d7855c64..d021fe02 100644--- a/packaging/macos/README.md+++ b/packaging/macos/README.md@@ -1,10 +1,53 @@# macOS Deployment-This directory contains lightweight deployment scaffolding for the Beacon-Endpoint Agent MVP.+This directory contains macOS deployment assets for the Beacon Endpoint Agent,+including Jamf-ready package scripts, policy helpers, and Extension Attributes.-The alpha install path assumes the `beacon` binary is already available on the-endpoint through Homebrew, a direct download, or an MDM-managed package.+Beacon's Jamf support is deployment-native: Jamf installs and inventories a+local-only endpoint agent, while Beacon continues to write local JSONL telemetry+without requiring a hosted account or Jamf Pro API credentials.++## Package Layout++The package builder assembles this payload:++```text+/opt/beacon/bin/beacon+/opt/beacon/bin/beacon-otelcol+/opt/beacon/scripts/install-endpoint.sh+/opt/beacon/scripts/uninstall-endpoint.sh+/opt/beacon/jamf/extension-attributes/*.sh+/opt/beacon/jamf/scripts/*.sh+```++The endpoint install creates system configuration and runtime state:++```text+/Library/Application Support/Beacon/Endpoint/config.json+/Library/Application Support/Beacon/Endpoint/otelcol.yaml+/Library/LaunchDaemons/com.beacon.endpoint.collector.plist+/var/log/beacon-agent/runtime.jsonl+```++## Build A Test Package++Build Beacon and `beacon-otelcol`, then assemble the macOS package:++```bash+cd cli/beacon+make build+cd ../..++cd collector-builder+ocb --config builder.yaml+cd ..++sh packaging/macos/build-pkg.sh+```++Set `PKG_SIGN_IDENTITY` to sign with `pkgbuild`, and set+`NOTARYTOOL_PROFILE` to submit and staple the package with Apple's notary+service.## Manual Install@@ -32,11 +75,60 @@ Use `install-endpoint.sh` from Jamf, Kandji, or a generic macOS MDM commandrunner. The script installs system-level endpoint configuration and writes logsto `/var/log/beacon-agent/runtime.jsonl`.-Set `BEACON_ENDPOINT_HARNESSES` to override the default `claude,codex` harness-list.+Environment variables take precedence, followed by Jamf script parameters:++```text+Parameter 4: harnesses, default claude,codex+Parameter 5: content retention, default metadata+Parameter 6: OTLP gRPC port, default 4317+Parameter 7: OTLP HTTP port, default 4318+Parameter 8: collector path, default /opt/beacon/bin/beacon-otelcol when present+Parameter 9: no-start flag, accepts 1/true/yes+```++Example Jamf policy script configuration:++```bash+/opt/beacon/jamf/scripts/install.sh "$@"+```++Use `packaging/macos/jamf/scripts/repair.sh` as a remediation policy for Macs+where Extension Attributes report a stale or unhealthy install.## MDM Uninstall ScriptUse `uninstall-endpoint.sh` to remove endpoint service files. Set-`BEACON_KEEP_LOGS=1` to preserve runtime logs during removal.+`BEACON_KEEP_LOGS=1` or Jamf parameter 4 to preserve runtime logs during+removal. Set `BEACON_KEEP_CONFIG=1` or Jamf parameter 5 to preserve harness+telemetry configuration.++## Jamf Extension Attributes++Upload scripts from `packaging/macos/jamf/extension-attributes` to Jamf Pro to+inventory:++- Beacon version+- Collector service health+- Last runtime event age in seconds+- Content retention mode+- Configured harnesses+- Runtime log writability++Suggested Smart Groups:++- Beacon version is `not_installed`+- Collector service health is not `running`+- Last runtime event age is greater than `86400`+- Content retention is not `metadata`+- Runtime log writability is not `writable` or `creatable`++## Jamf Validation++After deploying the package, run:++```bash+sudo /opt/beacon/bin/beacon endpoint status --json+sudo /opt/beacon/bin/beacon endpoint wazuh validate+sudo launchctl print system/com.beacon.endpoint.collector+```diff --git a/packaging/macos/build-pkg.sh b/packaging/macos/build-pkg.shnew file mode 100755index 00000000..88ec9b4c--- /dev/null+++ b/packaging/macos/build-pkg.sh@@ -0,0 +1,95 @@+#!/bin/sh+set -eu+export COPYFILE_DISABLE=1++ROOT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)"+OUT_DIR="${OUT_DIR:-$ROOT_DIR/dist/macos}"+WORK_DIR="$(mktemp -d)"+trap 'rm -rf "$WORK_DIR"' EXIT INT TERM++VERSION="${BEACON_VERSION:-$(cd "$ROOT_DIR" && git describe --tags --always --dirty 2>/dev/null || echo dev)}"+PKG_IDENTIFIER="${PKG_IDENTIFIER:-ai.asymptote.beacon.endpoint}"+PKG_NAME="${PKG_NAME:-BeaconEndpointAgent}"+BEACON_BIN="${BEACON_BIN:-$ROOT_DIR/cli/beacon/beacon}"+COLLECTOR_BIN="${BEACON_COLLECTOR:-$ROOT_DIR/collector-builder/dist/beacon-otelcol/beacon-otelcol}"+PKG_ROOT="$WORK_DIR/pkgroot"+PKG_SCRIPTS="$WORK_DIR/scripts"+PKG_PATH="$OUT_DIR/$PKG_NAME-$VERSION.pkg"++if [ ! -x "$BEACON_BIN" ]; then+ echo "beacon binary not found or not executable: $BEACON_BIN" >&2+ echo "Build it first, for example: (cd cli/beacon && make build)" >&2+ exit 1+fi++if [ ! -x "$COLLECTOR_BIN" ]; then+ echo "beacon-otelcol binary not found or not executable: $COLLECTOR_BIN" >&2+ echo "Build it first with the OpenTelemetry Collector Builder using collector-builder/builder.yaml." >&2+ exit 1+fi++mkdir -p "$OUT_DIR" "$PKG_ROOT/opt/beacon/bin" "$PKG_ROOT/opt/beacon/scripts" \+ "$PKG_ROOT/opt/beacon/jamf" "$PKG_SCRIPTS"++cp "$BEACON_BIN" "$PKG_ROOT/opt/beacon/bin/beacon"+cp "$COLLECTOR_BIN" "$PKG_ROOT/opt/beacon/bin/beacon-otelcol"+cp "$ROOT_DIR/packaging/macos/install-endpoint.sh" "$PKG_ROOT/opt/beacon/scripts/install-endpoint.sh"+cp "$ROOT_DIR/packaging/macos/uninstall-endpoint.sh" "$PKG_ROOT/opt/beacon/scripts/uninstall-endpoint.sh"+cp -R "$ROOT_DIR/packaging/macos/jamf/." "$PKG_ROOT/opt/beacon/jamf/"+cp "$ROOT_DIR/packaging/macos/scripts/postinstall" "$PKG_SCRIPTS/postinstall"+cp "$ROOT_DIR/packaging/macos/scripts/preinstall" "$PKG_SCRIPTS/preinstall"++if [ -d "$ROOT_DIR/cli/beacon/internal/endpoint/wazuh/pack" ]; then+ mkdir -p "$PKG_ROOT/opt/beacon/wazuh"+ cp -R "$ROOT_DIR/cli/beacon/internal/endpoint/wazuh/pack/." "$PKG_ROOT/opt/beacon/wazuh/"+fi++find "$PKG_ROOT" -name '._*' -delete++chmod 755 "$PKG_ROOT/opt/beacon/bin/beacon" "$PKG_ROOT/opt/beacon/bin/beacon-otelcol"+chmod 755 "$PKG_ROOT/opt/beacon/scripts/install-endpoint.sh" "$PKG_ROOT/opt/beacon/scripts/uninstall-endpoint.sh"+find "$PKG_ROOT/opt/beacon/jamf" -type f -name '*.sh' -exec chmod 755 {} \;+chmod 755 "$PKG_SCRIPTS/postinstall" "$PKG_SCRIPTS/preinstall"+find "$PKG_ROOT" -name '._*' -delete+if command -v xattr >/dev/null 2>&1; then+ xattr -cr "$PKG_ROOT" "$PKG_SCRIPTS" 2>/dev/null || true+fi+if command -v dot_clean >/dev/null 2>&1; then+ dot_clean -m "$PKG_ROOT" "$PKG_SCRIPTS" 2>/dev/null || true+fi+find "$PKG_ROOT" -name '._*' -delete++if [ -n "${PKG_SIGN_IDENTITY:-}" ]; then+ pkgbuild \+ --root "$PKG_ROOT" \+ --scripts "$PKG_SCRIPTS" \+ --identifier "$PKG_IDENTIFIER" \+ --version "$VERSION" \+ --install-location / \+ --filter '/\._[^/]*$' \+ --filter '/\.DS_Store$' \+ --filter '(^|/)CVS($|/)' \+ --filter '(^|/)\.svn($|/)' \+ --sign "$PKG_SIGN_IDENTITY" \+ "$PKG_PATH"+else+ pkgbuild \+ --root "$PKG_ROOT" \+ --scripts "$PKG_SCRIPTS" \+ --identifier "$PKG_IDENTIFIER" \+ --version "$VERSION" \+ --install-location / \+ --filter '/\._[^/]*$' \+ --filter '/\.DS_Store$' \+ --filter '(^|/)CVS($|/)' \+ --filter '(^|/)\.svn($|/)' \+ "$PKG_PATH"+fi++if [ -n "${NOTARYTOOL_PROFILE:-}" ]; then+ xcrun notarytool submit "$PKG_PATH" --keychain-profile "$NOTARYTOOL_PROFILE" --wait+ xcrun stapler staple "$PKG_PATH"+fi++shasum -a 256 "$PKG_PATH" > "$PKG_PATH.sha256"+echo "$PKG_PATH"diff --git a/packaging/macos/install-endpoint.sh b/packaging/macos/install-endpoint.shindex 348b5e53..fcdc0aea 100755--- a/packaging/macos/install-endpoint.sh+++ b/packaging/macos/install-endpoint.sh@@ -1,13 +1,40 @@#!/bin/shset -eu-BEACON_BIN="${BEACON_BIN:-beacon}"-BEACON_ENDPOINT_HARNESSES="${BEACON_ENDPOINT_HARNESSES:-claude,codex}"-BEACON_OTLP_GRPC_PORT="${BEACON_OTLP_GRPC_PORT:-4317}"-BEACON_OTLP_HTTP_PORT="${BEACON_OTLP_HTTP_PORT:-4318}"+if [ -z "${BEACON_BIN:-}" ]; then+ if [ -x "/opt/beacon/bin/beacon" ]; then+ BEACON_BIN="/opt/beacon/bin/beacon"+ else+ BEACON_BIN="beacon"+ fi+fi-exec "$BEACON_BIN" endpoint install \+BEACON_ENDPOINT_HARNESSES="${BEACON_ENDPOINT_HARNESSES:-${4:-claude,codex}}"+BEACON_CONTENT_RETENTION="${BEACON_CONTENT_RETENTION:-${5:-metadata}}"+BEACON_OTLP_GRPC_PORT="${BEACON_OTLP_GRPC_PORT:-${6:-4317}}"+BEACON_OTLP_HTTP_PORT="${BEACON_OTLP_HTTP_PORT:-${7:-4318}}"+BEACON_COLLECTOR="${BEACON_COLLECTOR:-${8:-}}"+BEACON_NO_START="${BEACON_NO_START:-${9:-0}}"++if [ -z "$BEACON_COLLECTOR" ] && [ -x "/opt/beacon/bin/beacon-otelcol" ]; then+ BEACON_COLLECTOR="/opt/beacon/bin/beacon-otelcol"+fi++set -- endpoint install \--harness "$BEACON_ENDPOINT_HARNESSES" \+ --content-retention "$BEACON_CONTENT_RETENTION" \--otlp-grpc-port "$BEACON_OTLP_GRPC_PORT" \--otlp-http-port "$BEACON_OTLP_HTTP_PORT"+if [ -n "$BEACON_COLLECTOR" ]; then+ set -- "$@" --collector "$BEACON_COLLECTOR"+fi++case "$BEACON_NO_START" in+ 1|true|TRUE|yes|YES)+ set -- "$@" --no-start+ ;;+esac++exec "$BEACON_BIN" "$@"+diff --git a/packaging/macos/jamf/extension-attributes/beacon-version.sh b/packaging/macos/jamf/extension-attributes/beacon-version.shnew file mode 100755index 00000000..f66b173d--- /dev/null+++ b/packaging/macos/jamf/extension-attributes/beacon-version.sh@@ -0,0 +1,16 @@+#!/bin/sh+set -eu++BEACON_BIN="${BEACON_BIN:-/opt/beacon/bin/beacon}"++if [ ! -x "$BEACON_BIN" ]; then+ echo "<result>not_installed</result>"+ exit 0+fi++VERSION="$("$BEACON_BIN" version 2>/dev/null || true)"+if [ -z "$VERSION" ]; then+ VERSION="unknown"+fi++echo "<result>$VERSION</result>"diff --git a/packaging/macos/jamf/extension-attributes/collector-service-health.sh b/packaging/macos/jamf/extension-attributes/collector-service-health.shnew file mode 100755index 00000000..3535e11b--- /dev/null+++ b/packaging/macos/jamf/extension-attributes/collector-service-health.sh@@ -0,0 +1,22 @@+#!/bin/sh+set -eu++LABEL="${BEACON_SERVICE_LABEL:-com.beacon.endpoint.collector}"++if ! command -v launchctl >/dev/null 2>&1; then+ echo "<result>launchctl_unavailable</result>"+ exit 0+fi++STATUS="$(launchctl print "system/$LABEL" 2>&1 || true)"+case "$STATUS" in+ *"state = running"*|*"pid ="*)+ echo "<result>running</result>"+ ;;+ *"Could not find service"*|*"No such process"*)+ echo "<result>not_loaded</result>"+ ;;+ *)+ echo "<result>loaded_not_running</result>"+ ;;+esacdiff --git a/packaging/macos/jamf/extension-attributes/configured-harnesses.sh b/packaging/macos/jamf/extension-attributes/configured-harnesses.shnew file mode 100755index 00000000..b127834d--- /dev/null+++ b/packaging/macos/jamf/extension-attributes/configured-harnesses.sh@@ -0,0 +1,32 @@+#!/bin/sh+set -eu++CONFIG_PATH="${BEACON_ENDPOINT_CONFIG:-/Library/Application Support/Beacon/Endpoint/config.json}"++if [ ! -f "$CONFIG_PATH" ]; then+ echo "<result>missing</result>"+ exit 0+fi++HARNESSES="$(awk '+ /"harnesses"[[:space:]]*:/ { in_array = 1; next }+ in_array && /\]/ { exit }+ in_array {+ gsub(/[",]/, "")+ gsub(/^[[:space:]]+|[[:space:]]+$/, "")+ if ($0 != "") {+ if (out != "") {+ out = out "," $0+ } else {+ out = $0+ }+ }+ }+ END { print out }+' "$CONFIG_PATH")"++if [ -z "$HARNESSES" ]; then+ HARNESSES="unknown"+fi++echo "<result>$HARNESSES</result>"diff --git a/packaging/macos/jamf/extension-attributes/content-retention.sh b/packaging/macos/jamf/extension-attributes/content-retention.shnew file mode 100755index 00000000..7ac11620--- /dev/null+++ b/packaging/macos/jamf/extension-attributes/content-retention.sh@@ -0,0 +1,16 @@+#!/bin/sh+set -eu++CONFIG_PATH="${BEACON_ENDPOINT_CONFIG:-/Library/Application Support/Beacon/Endpoint/config.json}"++if [ ! -f "$CONFIG_PATH" ]; then+ echo "<result>missing</result>"+ exit 0+fi++RETENTION="$(awk -F'"' '/"content_retention"[[:space:]]*:/ {print $4; exit}' "$CONFIG_PATH")"+if [ -z "$RETENTION" ]; then+ RETENTION="unknown"+fi++echo "<result>$RETENTION</result>"diff --git a/packaging/macos/jamf/extension-attributes/last-event-age-seconds.sh b/packaging/macos/jamf/extension-attributes/last-event-age-seconds.shnew file mode 100755index 00000000..f9619010--- /dev/null+++ b/packaging/macos/jamf/extension-attributes/last-event-age-seconds.sh@@ -0,0 +1,19 @@+#!/bin/sh+set -eu++LOG_PATH="${BEACON_ENDPOINT_LOG:-/var/log/beacon-agent/runtime.jsonl}"++if [ ! -s "$LOG_PATH" ]; then+ echo "<result>no_events</result>"+ exit 0+fi++MODIFIED_AT="$(stat -f %m "$LOG_PATH" 2>/dev/null || echo 0)"+NOW="$(date +%s)"++if [ "$MODIFIED_AT" -le 0 ]; then+ echo "<result>unknown</result>"+ exit 0+fi++echo "<result>$((NOW - MODIFIED_AT))</result>"diff --git a/packaging/macos/jamf/extension-attributes/runtime-log-writable.sh b/packaging/macos/jamf/extension-attributes/runtime-log-writable.shnew file mode 100755index 00000000..8c1027a3--- /dev/null+++ b/packaging/macos/jamf/extension-attributes/runtime-log-writable.sh@@ -0,0 +1,17 @@+#!/bin/sh+set -eu++LOG_PATH="${BEACON_ENDPOINT_LOG:-/var/log/beacon-agent/runtime.jsonl}"+LOG_DIR="$(dirname "$LOG_PATH")"++if [ -f "$LOG_PATH" ] && [ -w "$LOG_PATH" ]; then+ echo "<result>writable</result>"+ exit 0+fi++if [ ! -f "$LOG_PATH" ] && [ -d "$LOG_DIR" ] && [ -w "$LOG_DIR" ]; then+ echo "<result>creatable</result>"+ exit 0+fi++echo "<result>not_writable</result>"diff --git a/packaging/macos/jamf/scripts/install-cursor-hooks.sh b/packaging/macos/jamf/scripts/install-cursor-hooks.shnew file mode 100755index 00000000..35f338c3--- /dev/null+++ b/packaging/macos/jamf/scripts/install-cursor-hooks.sh@@ -0,0 +1,22 @@+#!/bin/sh+set -eu++BEACON_BIN="${BEACON_BIN:-/opt/beacon/bin/beacon}"+HOOK_HARNESSES="${BEACON_HOOK_HARNESSES:-${4:-cursor}}"+HOOK_LEVEL="${BEACON_HOOK_LEVEL:-${5:-user}}"+CONSOLE_USER="$(stat -f %Su /dev/console 2>/dev/null || echo "")"++if [ -z "$CONSOLE_USER" ] || [ "$CONSOLE_USER" = "root" ] || [ "$CONSOLE_USER" = "loginwindow" ]; then+ echo "No interactive console user found for Cursor hook installation." >&2+ exit 1+fi++HOME_DIR="$(dscl . -read "/Users/$CONSOLE_USER" NFSHomeDirectory 2>/dev/null | awk '{print $2}')"+if [ -z "$HOME_DIR" ] || [ ! -d "$HOME_DIR" ]; then+ echo "Unable to resolve home directory for $CONSOLE_USER." >&2+ exit 1+fi++exec sudo -u "$CONSOLE_USER" HOME="$HOME_DIR" "$BEACON_BIN" endpoint hooks install \+ --harness "$HOOK_HARNESSES" \+ --level "$HOOK_LEVEL"diff --git a/packaging/macos/jamf/scripts/install.sh b/packaging/macos/jamf/scripts/install.shnew file mode 100755index 00000000..ac419bcb--- /dev/null+++ b/packaging/macos/jamf/scripts/install.sh@@ -0,0 +1,6 @@+#!/bin/sh+set -eu++BEACON_BIN="${BEACON_BIN:-/opt/beacon/bin/beacon}" \+BEACON_COLLECTOR="${BEACON_COLLECTOR:-/opt/beacon/bin/beacon-otelcol}" \+ /opt/beacon/scripts/install-endpoint.sh "$@"diff --git a/packaging/macos/jamf/scripts/repair.sh b/packaging/macos/jamf/scripts/repair.shnew file mode 100755index 00000000..dd76c287--- /dev/null+++ b/packaging/macos/jamf/scripts/repair.sh@@ -0,0 +1,16 @@+#!/bin/sh+set -eu++BEACON_BIN="${BEACON_BIN:-/opt/beacon/bin/beacon}"+BEACON_COLLECTOR="${BEACON_COLLECTOR:-/opt/beacon/bin/beacon-otelcol}"+BEACON_ENDPOINT_HARNESSES="${BEACON_ENDPOINT_HARNESSES:-${4:-claude,codex}}"+BEACON_CONTENT_RETENTION="${BEACON_CONTENT_RETENTION:-${5:-metadata}}"+BEACON_OTLP_GRPC_PORT="${BEACON_OTLP_GRPC_PORT:-${6:-4317}}"+BEACON_OTLP_HTTP_PORT="${BEACON_OTLP_HTTP_PORT:-${7:-4318}}"++exec "$BEACON_BIN" endpoint repair \+ --collector "$BEACON_COLLECTOR" \+ --harness "$BEACON_ENDPOINT_HARNESSES" \+ --content-retention "$BEACON_CONTENT_RETENTION" \+ --otlp-grpc-port "$BEACON_OTLP_GRPC_PORT" \+ --otlp-http-port "$BEACON_OTLP_HTTP_PORT"diff --git a/packaging/macos/jamf/scripts/uninstall.sh b/packaging/macos/jamf/scripts/uninstall.shnew file mode 100755index 00000000..19e698ec--- /dev/null+++ b/packaging/macos/jamf/scripts/uninstall.sh@@ -0,0 +1,5 @@+#!/bin/sh+set -eu++BEACON_BIN="${BEACON_BIN:-/opt/beacon/bin/beacon}" \+ /opt/beacon/scripts/uninstall-endpoint.sh "$@"diff --git a/packaging/macos/jamf/scripts/validate.sh b/packaging/macos/jamf/scripts/validate.shnew file mode 100755index 00000000..93c25d1c--- /dev/null+++ b/packaging/macos/jamf/scripts/validate.sh@@ -0,0 +1,7 @@+#!/bin/sh+set -eu++BEACON_BIN="${BEACON_BIN:-/opt/beacon/bin/beacon}"++"$BEACON_BIN" endpoint status --json+"$BEACON_BIN" endpoint wazuh validatediff --git a/packaging/macos/pkgbuild.md b/packaging/macos/pkgbuild.mdindex c809a7e8..785b6af2 100644--- a/packaging/macos/pkgbuild.md+++ b/packaging/macos/pkgbuild.md@@ -4,20 +4,102 @@ Production releases should ship a signed and notarized macOS package thatinstalls:- `beacon`-- `beacon-hooks` when hook integrations are enabled- `beacon-otelcol`-- launchd plist templates-- Wazuh content pack files+- Jamf policy scripts and Extension Attributes+- Wazuh content pack files for admins that want to import examples/rules-The package should run `beacon endpoint install --no-start` in a-postinstall script, then bootstrap the launchd service once files and configs-are present.+`beacon-hooks` is embedded in the `beacon` binary for Cursor hook installation.+Do not configure Cursor hooks during the base package install; use the Jamf+`install-cursor-hooks.sh` helper so the command runs in the target user's+context.++## Build Inputs++Build the Beacon CLI first:++```bash+cd cli/beacon+make build+cd ../..+```++Build the custom OpenTelemetry Collector distribution with the Collector+Builder:++```bash+cd collector-builder+ocb --config builder.yaml+cd ..+```++The package builder expects:++```text+cli/beacon/beacon+collector-builder/dist/beacon-otelcol/beacon-otelcol+```++Override those paths with `BEACON_BIN` and `BEACON_COLLECTOR` if release+automation builds into a different directory.++## Package Build++Create an unsigned local test package:++```bash+sh packaging/macos/build-pkg.sh+```++Create a signed package:++```bash+PKG_SIGN_IDENTITY="Developer ID Installer: Example Corp (TEAMID)" \+ sh packaging/macos/build-pkg.sh+```++Create, submit, and staple a signed/notarized package:++```bash+PKG_SIGN_IDENTITY="Developer ID Installer: Example Corp (TEAMID)" \+NOTARYTOOL_PROFILE="beacon-notary-profile" \+ sh packaging/macos/build-pkg.sh+```++The package installs files under `/opt/beacon` and runs+`/opt/beacon/scripts/install-endpoint.sh` in `postinstall` with explicit+collector and retention settings.++## Jamf Deployment++Upload the generated `.pkg` to Jamf Pro and create a Policy scoped to a pilot+Smart Group. For default deployment, no script parameters are required.++Use these optional Jamf policy parameters when calling+`/opt/beacon/jamf/scripts/install.sh` or `repair.sh`:++```text+Parameter 4: harnesses, default claude,codex+Parameter 5: content retention, default metadata+Parameter 6: OTLP gRPC port, default 4317+Parameter 7: OTLP HTTP port, default 4318+Parameter 8: collector path, default /opt/beacon/bin/beacon-otelcol+Parameter 9: no-start flag for install.sh only+```++Upload Extension Attributes from+`packaging/macos/jamf/extension-attributes` and build Smart Groups for missing,+unhealthy, stale, or misconfigured endpoints. Scope `repair.sh` to those Smart+Groups for automated remediation.Release gates:+- `sh packaging/macos/test-endpoint-scripts.sh` passes+- `sh packaging/macos/smoke-endpoint.sh` passes on a clean macOS runner or VM- package signature verified with `pkgutil --check-signature`- notarization accepted by Apple- install/uninstall tested on a clean macOS runner or VM-- `sh packaging/macos/smoke-endpoint.sh` passes on a clean macOS runner or VM- Wazuh validation event successfully written after install+- `sudo launchctl print system/com.beacon.endpoint.collector` reports the+ collector service as loaded/running+- Jamf Extension Attributes report expected values after a recondiff --git a/packaging/macos/scripts/postinstall b/packaging/macos/scripts/postinstallnew file mode 100755index 00000000..8ba6f65b--- /dev/null+++ b/packaging/macos/scripts/postinstall@@ -0,0 +1,17 @@+#!/bin/sh+set -eu++BEACON_BIN="${BEACON_BIN:-/opt/beacon/bin/beacon}" \+BEACON_COLLECTOR="${BEACON_COLLECTOR:-/opt/beacon/bin/beacon-otelcol}" \+BEACON_ENDPOINT_HARNESSES="${BEACON_ENDPOINT_HARNESSES:-claude,codex}" \+BEACON_CONTENT_RETENTION="${BEACON_CONTENT_RETENTION:-metadata}" \+BEACON_OTLP_GRPC_PORT="${BEACON_OTLP_GRPC_PORT:-4317}" \+BEACON_OTLP_HTTP_PORT="${BEACON_OTLP_HTTP_PORT:-4318}" \+BEACON_NO_START=1 \+ /opt/beacon/scripts/install-endpoint.sh++if command -v launchctl >/dev/null 2>&1; then+ launchctl bootstrap system /Library/LaunchDaemons/com.beacon.endpoint.collector.plist >/dev/null 2>&1 || true+fi++exit 0diff --git a/packaging/macos/scripts/preinstall b/packaging/macos/scripts/preinstallnew file mode 100755index 00000000..7e305d56--- /dev/null+++ b/packaging/macos/scripts/preinstall@@ -0,0 +1,10 @@+#!/bin/sh+set -eu++# Stop an existing collector before package payload replacement so install/repair+# can bind the local OTLP ports during postinstall.+if command -v launchctl >/dev/null 2>&1; then+ launchctl bootout system/com.beacon.endpoint.collector >/dev/null 2>&1 || true+fi++exit 0diff --git a/packaging/macos/test-endpoint-scripts.sh b/packaging/macos/test-endpoint-scripts.shindex 9c5a81b4..0bee545b 100644--- a/packaging/macos/test-endpoint-scripts.sh+++ b/packaging/macos/test-endpoint-scripts.sh@@ -4,11 +4,16 @@ set -euROOT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)"INSTALL_SCRIPT="$ROOT_DIR/packaging/macos/install-endpoint.sh"UNINSTALL_SCRIPT="$ROOT_DIR/packaging/macos/uninstall-endpoint.sh"+PKG_BUILD_SCRIPT="$ROOT_DIR/packaging/macos/build-pkg.sh"TMP_DIR="$(mktemp -d)"trap 'rm -rf "$TMP_DIR"' EXIT INT TERMsh -n "$INSTALL_SCRIPT"sh -n "$UNINSTALL_SCRIPT"+sh -n "$PKG_BUILD_SCRIPT"+for script in "$ROOT_DIR"/packaging/macos/scripts/* "$ROOT_DIR"/packaging/macos/jamf/scripts/*.sh "$ROOT_DIR"/packaging/macos/jamf/extension-attributes/*.sh; do+ sh -n "$script"+doneSTUB_BIN="$TMP_DIR/beacon-stub"STUB_LOG="$TMP_DIR/argv.log"@@ -20,34 +25,92 @@ chmod +x "$STUB_BIN"BEACON_BIN="$STUB_BIN" \BEACON_ENDPOINT_HARNESSES="claude,codex,cursor" \+BEACON_CONTENT_RETENTION="redacted" \BEACON_OTLP_GRPC_PORT="5317" \BEACON_OTLP_HTTP_PORT="5318" \+BEACON_COLLECTOR="/tmp/beacon-otelcol" \STUB_LOG="$STUB_LOG" \"$INSTALL_SCRIPT"INSTALL_ARGS="$(cat "$STUB_LOG")"case "$INSTALL_ARGS" in- "endpoint install --harness claude,codex,cursor --otlp-grpc-port 5317 --otlp-http-port 5318") ;;+ "endpoint install --harness claude,codex,cursor --content-retention redacted --otlp-grpc-port 5317 --otlp-http-port 5318 --collector /tmp/beacon-otelcol") ;;*)echo "unexpected install args: $INSTALL_ARGS" >&2exit 1;;esac+BEACON_BIN="$STUB_BIN" \+STUB_LOG="$STUB_LOG" \+"$INSTALL_SCRIPT" _ _ _ "claude" "metadata" "6317" "6318" "/tmp/jamf-otelcol" "1"++INSTALL_ARGS="$(cat "$STUB_LOG")"+case "$INSTALL_ARGS" in+ "endpoint install --harness claude --content-retention metadata --otlp-grpc-port 6317 --otlp-http-port 6318 --collector /tmp/jamf-otelcol --no-start") ;;+ *)+ echo "unexpected Jamf positional install args: $INSTALL_ARGS" >&2+ exit 1+ ;;+esac+BEACON_BIN="$STUB_BIN" \BEACON_KEEP_LOGS="1" \+BEACON_KEEP_CONFIG="1" \STUB_LOG="$STUB_LOG" \"$UNINSTALL_SCRIPT"UNINSTALL_ARGS="$(cat "$STUB_LOG")"case "$UNINSTALL_ARGS" in- "endpoint uninstall --keep-logs") ;;+ "endpoint uninstall --keep-logs --keep-config") ;;*)echo "unexpected uninstall args with keep logs: $UNINSTALL_ARGS" >&2exit 1;;esac+BEACON_BIN="$STUB_BIN" \+STUB_LOG="$STUB_LOG" \+"$UNINSTALL_SCRIPT" _ _ _ "true" "true"++UNINSTALL_ARGS="$(cat "$STUB_LOG")"+case "$UNINSTALL_ARGS" in+ "endpoint uninstall --keep-logs --keep-config") ;;+ *)+ echo "unexpected Jamf positional uninstall args: $UNINSTALL_ARGS" >&2+ exit 1+ ;;+esac++CONFIG_PATH="$TMP_DIR/config.json"+cat >"$CONFIG_PATH" <<'JSON'+{+ "harnesses": [+ "claude",+ "codex"+ ],+ "content_retention": "metadata"+}+JSON++RETENTION="$(BEACON_ENDPOINT_CONFIG="$CONFIG_PATH" "$ROOT_DIR/packaging/macos/jamf/extension-attributes/content-retention.sh")"+case "$RETENTION" in+ "<result>metadata</result>") ;;+ *)+ echo "unexpected retention extension attribute result: $RETENTION" >&2+ exit 1+ ;;+esac++HARNESSES="$(BEACON_ENDPOINT_CONFIG="$CONFIG_PATH" "$ROOT_DIR/packaging/macos/jamf/extension-attributes/configured-harnesses.sh")"+case "$HARNESSES" in+ "<result>claude,codex</result>") ;;+ *)+ echo "unexpected harness extension attribute result: $HARNESSES" >&2+ exit 1+ ;;+esac+BEACON_BIN="$STUB_BIN" \STUB_LOG="$STUB_LOG" \"$UNINSTALL_SCRIPT"diff --git a/packaging/macos/uninstall-endpoint.sh b/packaging/macos/uninstall-endpoint.shindex cbbb48cb..ae787878 100755--- a/packaging/macos/uninstall-endpoint.sh+++ b/packaging/macos/uninstall-endpoint.sh@@ -1,12 +1,30 @@#!/bin/shset -eu-BEACON_BIN="${BEACON_BIN:-beacon}"-KEEP_LOGS_FLAG=""--if [ "${BEACON_KEEP_LOGS:-0}" = "1" ]; then- KEEP_LOGS_FLAG="--keep-logs"+if [ -z "${BEACON_BIN:-}" ]; then+ if [ -x "/opt/beacon/bin/beacon" ]; then+ BEACON_BIN="/opt/beacon/bin/beacon"+ else+ BEACON_BIN="beacon"+ fifi-exec "$BEACON_BIN" endpoint uninstall $KEEP_LOGS_FLAG+BEACON_KEEP_LOGS="${BEACON_KEEP_LOGS:-${4:-0}}"+BEACON_KEEP_CONFIG="${BEACON_KEEP_CONFIG:-${5:-0}}"++set -- endpoint uninstall++case "$BEACON_KEEP_LOGS" in+ 1|true|TRUE|yes|YES)+ set -- "$@" --keep-logs+ ;;+esac++case "$BEACON_KEEP_CONFIG" in+ 1|true|TRUE|yes|YES)+ set -- "$@" --keep-config+ ;;+esac++exec "$BEACON_BIN" "$@"