Skip to content

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

add Jamf-ready macOS packaging

Justin D'Souza8bfdf3fc68bd
diff --git a/.gitignore b/.gitignore
index 3b46dcfb..a8cdf08b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,6 +20,7 @@ coverage.html
cli/beacon/beacon
cli/beacon/beacon-*
cli/beacon/dist/
+dist/
# Hook helper binaries
cli/beacon-hooks/beacon-hooks
diff --git a/cli/beacon/internal/endpoint/collector/collector.go b/cli/beacon/internal/endpoint/collector/collector.go
index 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:13133
service:
+ telemetry:
+ metrics:
+ level: none
extensions: [health_check]
pipelines:
logs:
diff --git a/cli/beacon/internal/endpoint/collector/collector_test.go b/cli/beacon/internal/endpoint/collector/collector_test.go
index 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.go
index 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.go
index 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 = port
cfg.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.yaml
index dfe03e08..affc6b8b 100644
--- a/collector-builder/builder.yaml
+++ b/collector-builder/builder.yaml
@@ -15,5 +15,5 @@ exporters:
path: ./exporter/beaconjsonexporter
extensions:
- - gomod: go.opentelemetry.io/collector/extension/healthcheckextension v0.121.0
+ - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/healthcheckextension v0.121.0
diff --git a/packaging/macos/README.md b/packaging/macos/README.md
index 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 command
runner. The script installs system-level endpoint configuration and writes logs
to `/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 Script
Use `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.sh
new file mode 100755
index 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.sh
index 348b5e53..fcdc0aea 100755
--- a/packaging/macos/install-endpoint.sh
+++ b/packaging/macos/install-endpoint.sh
@@ -1,13 +1,40 @@
#!/bin/sh
set -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.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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>"
+ ;;
+esac
diff --git a/packaging/macos/jamf/extension-attributes/configured-harnesses.sh b/packaging/macos/jamf/extension-attributes/configured-harnesses.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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 validate
diff --git a/packaging/macos/pkgbuild.md b/packaging/macos/pkgbuild.md
index 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 that
installs:
- `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 recon
diff --git a/packaging/macos/scripts/postinstall b/packaging/macos/scripts/postinstall
new file mode 100755
index 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 0
diff --git a/packaging/macos/scripts/preinstall b/packaging/macos/scripts/preinstall
new file mode 100755
index 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 0
diff --git a/packaging/macos/test-endpoint-scripts.sh b/packaging/macos/test-endpoint-scripts.sh
index 9c5a81b4..0bee545b 100644
--- a/packaging/macos/test-endpoint-scripts.sh
+++ b/packaging/macos/test-endpoint-scripts.sh
@@ -4,11 +4,16 @@ set -eu
ROOT_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 TERM
sh -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"
+done
STUB_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" >&2
exit 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" >&2
exit 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.sh
index cbbb48cb..ae787878 100755
--- a/packaging/macos/uninstall-endpoint.sh
+++ b/packaging/macos/uninstall-endpoint.sh
@@ -1,12 +1,30 @@
#!/bin/sh
set -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"
+ fi
fi
-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" "$@"