Skip to content

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

mdm scripts

Justin D'Souza9ee4a634bf5f
diff --git a/README.md b/README.md
index 02beba52..72f098b3 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,137 @@
-# Beacon Endpoint Agent
+<p align="center">
+ <img src="images/beacon-hero.png" alt="Beacon" width="860">
+</p>
+
+<h1 align="center">Asymptote Lab's Beacon</h1>
+
+<p align="center">
+ <strong>Unified endpoint telemetry for AI agents.</strong>
+</p>
+
+<p align="center">
+ <a href="https://docs.asymptotelabs.ai/cli">Docs</a>
+ ·
+ <a href="#for-security-and-it-teams">For Security and IT Teams</a>
+ ·
+ <a href="#quick-start">Quick Start</a>
+ ·
+ <a href="#command-reference">Commands</a>
+</p>
+
+<p align="center">
+ <img src="images/beacon-architecture.png" alt="Beacon endpoint architecture" width="860">
+</p>
+
+AI agents now take action directly on developer endpoints, but security teams
+often have little unified visibility into prompts, tools, approvals, commands,
+and file changes across local agent harnesses.
+
+Beacon runs locally on the endpoint, captures supported activity from Claude
+Code, Codex CLI, Claude Cowork, and Cursor, and normalizes it into
+Wazuh-compatible JSONL for existing localfile/Wazuh or customer-managed
+pipelines.
+
+### Why Teams Use Beacon
+
+- **Local-only by default:** no hosted account, remote policy fetch, or external
+ network dependency during normal endpoint collection.
+- **Built for AI runtimes:** captures supported Claude Code, Codex CLI, Cursor,
+ and Claude Cowork activity where those runtimes expose telemetry.
+- **Security-team friendly:** ships macOS package assets for Jamf Pro and Fleet
+ deployment, validation, repair, and inventory.
+- **SIEM-ready output:** writes Wazuh-compatible JSONL for local or
+ customer-managed forwarding.
-Local endpoint telemetry for AI agent runtimes.
+## Table Of Contents
-Beacon Endpoint Agent configures local telemetry for tools like Claude Code,
-Codex CLI, Claude Cowork, and Cursor, then writes Wazuh-compatible JSONL logs.
-It runs local-only and does not require a Beacon account.
+- [For Security and IT Teams](#for-security-and-it-teams)
+- [Product Vision](#product-vision)
+- [What Beacon Does](#what-beacon-does)
+- [Privacy And Retention](#privacy-and-retention)
+- [What Beacon Does Not Do](#what-beacon-does-not-do)
+- [Documentation](#documentation)
+- [Quick Start](#quick-start)
+- [Optional Integrations](#optional-integrations)
+- [Claude Cowork Durable Collector](#claude-cowork-durable-collector)
+- [Dashboard](#dashboard)
+- [Command Reference](#command-reference)
+- [Repository Layout](#repository-layout)
+- [Release Readiness](#release-readiness)
+- [Testing](#testing)
-Read the [Beacon CLI documentation](https://docs.asymptotelabs.ai/cli) for setup
-guides and command details.
+## For Security and IT Teams
-Beacon is visibility-first. The current public build focuses on observing local
-agent runtime activity, normalizing it into endpoint events, and leaving
-forwarding to existing localfile/Wazuh or customer-managed pipelines.
+Beacon can be deployed with macOS MDM using a signed and notarized `.pkg`. The
+package installs Beacon under `/opt/beacon`, creates system endpoint
+configuration, loads the local collector LaunchDaemon, and writes runtime JSONL
+to `/var/log/beacon-agent/runtime.jsonl`.
+
+The full Jamf and Fleet runbook lives in
+[`packaging/macos/README.md`](packaging/macos/README.md).
+
+### Jamf Pro
+
+1. Upload the `.pkg` from `dist/macos/` to Jamf Pro.
+2. Create a Policy scoped to a pilot Smart Group.
+3. Install the package. No script is required for the default install path.
+4. Upload Extension Attributes from
+ `packaging/macos/jamf/extension-attributes/`.
+5. Scope repair to unhealthy devices with `/opt/beacon/jamf/scripts/repair.sh`.
+
+Optional explicit install policy script:
+
+```bash
+/opt/beacon/jamf/scripts/install.sh "$@"
+```
+
+Jamf parameters:
+
+```text
+Parameter 4: harnesses, default claude,codex
+Parameter 5: content retention, default full
+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, accepts 1/true/yes
+```
+
+Validate a deployed Mac:
+
+```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
+```
+
+### Fleet
+
+1. Upload the signed/notarized `.pkg` as Fleet software.
+2. Scope it to a pilot team or label.
+3. Install the package. No post-install script is required for the default path.
+4. Add queries from `packaging/macos/fleet/queries/` as Fleet policies or
+ labels.
+5. Use scripts from `/opt/beacon/fleet/scripts/` for validation, repair, or
+ uninstall workflows.
+
+Fleet install arguments:
+
+```text
+1: harnesses, default claude,codex
+2: content retention, default full
+3: OTLP gRPC port, default 4317
+4: OTLP HTTP port, default 4318
+5: collector path, default /opt/beacon/bin/beacon-otelcol
+6: no-start flag, accepts 1/true/yes
+```
+
+Validate with:
+
+```bash
+/opt/beacon/fleet/scripts/validate.sh
+```
+
+Cursor telemetry is deployed separately in the logged-in user's context; do not
+configure Cursor hooks from the base system package install.
## Product Vision
@@ -30,23 +150,6 @@ endpoint.
Read more in
[Introducing Beacon: Endpoint Telemetry for AI Agents](https://justindsouza.substack.com/p/introducing-beacon-endpoint-telemetry).
-## Table Of Contents
-
-- [Product Vision](#product-vision)
-- [What Beacon Does](#what-beacon-does)
-- [Privacy And Retention](#privacy-and-retention)
-- [What Beacon Does Not Do](#what-beacon-does-not-do)
-- [Documentation](#documentation)
-- [Quick Start](#quick-start)
-- [Install With Homebrew](#install-with-homebrew)
-- [Optional Integrations](#optional-integrations)
-- [Claude Cowork Durable Collector](#claude-cowork-durable-collector)
-- [Dashboard](#dashboard)
-- [Command Reference](#command-reference)
-- [Repository Layout](#repository-layout)
-- [Release Readiness](#release-readiness)
-- [Testing](#testing)
-
## What Beacon Does
Beacon can currently:
diff --git a/images/beacon-architecture.png b/images/beacon-architecture.png
new file mode 100644
index 00000000..42e5312a
Binary files /dev/null and b/images/beacon-architecture.png differ
diff --git a/images/beacon-hero.png b/images/beacon-hero.png
new file mode 100644
index 00000000..99db8a33
Binary files /dev/null and b/images/beacon-hero.png differ
diff --git a/packaging/macos/README.md b/packaging/macos/README.md
index deaed9d3..bf35341d 100644
--- a/packaging/macos/README.md
+++ b/packaging/macos/README.md
@@ -1,11 +1,13 @@
# macOS Deployment
This directory contains macOS deployment assets for the Beacon Endpoint Agent,
-including Jamf-ready package scripts, policy helpers, and Extension Attributes.
+including Jamf- and Fleet-ready package scripts, policy helpers, inventory
+queries, and Jamf Extension Attributes.
-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.
+Beacon's MDM support is deployment-native: Jamf or Fleet installs and
+inventories a local-only endpoint agent, while Beacon continues to write local
+JSONL telemetry without requiring a hosted account, remote policy fetch, or MDM
+API credentials.
## Package Layout
@@ -18,6 +20,8 @@ The package builder assembles this payload:
/opt/beacon/scripts/uninstall-endpoint.sh
/opt/beacon/jamf/extension-attributes/*.sh
/opt/beacon/jamf/scripts/*.sh
+/opt/beacon/fleet/queries/*.sql
+/opt/beacon/fleet/scripts/*.sh
```
The endpoint install creates system configuration and runtime state:
@@ -72,43 +76,71 @@ The smoke test builds a temporary Beacon binary, uses a temporary `HOME`, runs a
user-mode install with `--no-start`, validates status/Wazuh output, installs
Cursor hooks, and uninstalls while preserving the runtime log for assertions.
-## MDM Install Script
+## MDM Deployment Model
-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`.
+Use the signed and notarized `.pkg` as the base deployment artifact. The package
+installs Beacon under `/opt/beacon`, writes system endpoint configuration, and
+loads the local collector LaunchDaemon. The shared endpoint wrapper installs
+system-level configuration and writes logs to
+`/var/log/beacon-agent/runtime.jsonl`.
-Environment variables take precedence, followed by Jamf script parameters:
+Environment variables take precedence, followed by MDM script parameters:
```text
-Parameter 4: harnesses, default claude,codex
-Parameter 5: content retention, default full
-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
+BEACON_ENDPOINT_HARNESSES: default claude,codex
+BEACON_CONTENT_RETENTION: default full
+BEACON_OTLP_GRPC_PORT: default 4317
+BEACON_OTLP_HTTP_PORT: default 4318
+BEACON_COLLECTOR: default /opt/beacon/bin/beacon-otelcol when present
+BEACON_NO_START: accepts 1/true/yes
```
-Example Jamf policy script configuration:
+Recommended rollout:
+
+1. Upload the signed/notarized package to a pilot group.
+2. Confirm the LaunchDaemon is running and `beacon endpoint wazuh validate`
+ writes a validation event.
+3. Add inventory signals for version, service health, log freshness, retention,
+ harnesses, and log writability.
+4. Scope repair/remediation to unhealthy devices.
+5. Broaden deployment in stages after inventory and validation stay healthy.
+
+Cursor hook installation is separate from the base system package because Cursor
+configuration is per user. Run the Cursor hook helper only when an interactive
+console user is present.
+
+## Jamf Pro
+
+Upload the generated `.pkg` to Jamf Pro and create a Policy scoped to a pilot
+Smart Group. The package postinstall performs the default system install, so no
+script is required for the common path.
+
+Use `/opt/beacon/jamf/scripts/install.sh` when a policy needs explicit
+parameters or a reinstall action:
```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.
+Jamf script parameters:
-## MDM Uninstall Script
+```text
+Parameter 4: harnesses, default claude,codex
+Parameter 5: content retention, default full
+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
+```
-Use `uninstall-endpoint.sh` to remove endpoint service files. Set
-`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.
+Use `/opt/beacon/jamf/scripts/repair.sh` as a remediation policy for Macs where
+Extension Attributes report a stale or unhealthy install. Use
+`/opt/beacon/jamf/scripts/install-cursor-hooks.sh` as a separate user-context
+policy for Cursor telemetry.
-## Jamf Extension Attributes
+### Jamf Extension Attributes
-Upload scripts from `packaging/macos/jamf/extension-attributes` to Jamf Pro to
-inventory:
+Upload scripts from `packaging/macos/jamf/extension-attributes` to inventory:
- Beacon version
- Collector service health
@@ -125,7 +157,7 @@ Suggested Smart Groups:
- Content retention is not `full`
- Runtime log writability is not `writable` or `creatable`
-## Jamf Validation
+### Jamf Validation
After deploying the package, run:
@@ -135,3 +167,83 @@ sudo /opt/beacon/bin/beacon endpoint wazuh validate
sudo launchctl print system/com.beacon.endpoint.collector
```
+## Fleet
+
+Upload the signed/notarized `.pkg` as Fleet software and scope it to a pilot
+team or label. The package postinstall performs the default system install.
+
+Fleet scripts are installed under `/opt/beacon/fleet/scripts`:
+
+```text
+install.sh: reinstall or install with optional arguments
+validate.sh: status JSON, Wazuh validation, and LaunchDaemon check
+repair.sh: preserve logs/config while repairing collector and harness config
+uninstall.sh: remove endpoint service files
+```
+
+Fleet install script positional arguments:
+
+```text
+install.sh argument 1: harnesses, default claude,codex
+install.sh argument 2: content retention, default full
+install.sh argument 3: OTLP gRPC port, default 4317
+install.sh argument 4: OTLP HTTP port, default 4318
+install.sh argument 5: collector path, default /opt/beacon/bin/beacon-otelcol
+install.sh argument 6: no-start flag, accepts 1/true/yes
+```
+
+Fleet repair script positional arguments:
+
+```text
+repair.sh argument 1: harnesses, default claude,codex
+repair.sh argument 2: content retention, default full
+repair.sh argument 3: OTLP gRPC port, default 4317
+repair.sh argument 4: OTLP HTTP port, default 4318
+```
+
+Add queries from `packaging/macos/fleet/queries` as Fleet policies or labels.
+They cover package/service/log/config presence and freshness; run
+`/opt/beacon/fleet/scripts/validate.sh` for full CLI-level validation of status,
+content retention, harness configuration, Wazuh validation, and launchd health.
+
+- `beacon-version.sql`
+- `collector-service-health.sql`
+- `last-event-age-seconds.sql`
+- `content-retention.sql`
+- `configured-harnesses.sql`
+- `runtime-log-writable.sql`
+
+Recommended Fleet policies:
+
+- Beacon install state is not `not_installed`
+- Collector service health is `running`
+- Last runtime event age is less than `86400`
+- Endpoint config state is `present`
+- Runtime log state is `present`
+
+## Uninstall And Rollback
+
+Use the vendor uninstall helper to remove endpoint service files. Set
+`BEACON_KEEP_LOGS=1` or the first uninstall argument to preserve runtime logs
+during removal. Set `BEACON_KEEP_CONFIG=1` or the second uninstall argument to
+preserve harness telemetry configuration.
+
+```bash
+/opt/beacon/jamf/scripts/uninstall.sh "$@"
+/opt/beacon/fleet/scripts/uninstall.sh "$@"
+```
+
+The endpoint uninstall removes service/configuration state. Package payload
+removal remains under the MDM/package receipt lifecycle.
+
+## Troubleshooting
+
+- `launchctl print system/com.beacon.endpoint.collector` fails: run the repair
+ helper and check `/Library/LaunchDaemons/com.beacon.endpoint.collector.plist`.
+- `endpoint wazuh validate` fails: confirm `/var/log/beacon-agent` exists and is
+ writable by the collector.
+- No recent runtime events: confirm supported harnesses are configured and the
+ local OTLP ports are not in use by another process.
+- Cursor hooks are missing: run the Cursor hook helper while a non-root console
+ user is logged in.
+
diff --git a/packaging/macos/build-pkg.sh b/packaging/macos/build-pkg.sh
index 4fd7565c..493df4e4 100755
--- a/packaging/macos/build-pkg.sh
+++ b/packaging/macos/build-pkg.sh
@@ -30,19 +30,30 @@ if [ ! -x "$COLLECTOR_BIN" ]; then
fi
mkdir -p "$OUT_DIR" "$PKG_ROOT/opt/beacon/bin" "$PKG_ROOT/opt/beacon/scripts" \
- "$PKG_ROOT/opt/beacon/jamf" "$PKG_SCRIPTS"
+ "$PKG_ROOT/opt/beacon/jamf" "$PKG_ROOT/opt/beacon/fleet" "$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 command -v ditto >/dev/null 2>&1; then
+ ditto --norsrc "$ROOT_DIR/packaging/macos/jamf" "$PKG_ROOT/opt/beacon/jamf"
+ ditto --norsrc "$ROOT_DIR/packaging/macos/fleet" "$PKG_ROOT/opt/beacon/fleet"
+else
+ cp -R "$ROOT_DIR/packaging/macos/jamf/." "$PKG_ROOT/opt/beacon/jamf/"
+ cp -R "$ROOT_DIR/packaging/macos/fleet/." "$PKG_ROOT/opt/beacon/fleet/"
+fi
+
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/"
+ if command -v ditto >/dev/null 2>&1; then
+ ditto --norsrc "$ROOT_DIR/cli/beacon/internal/endpoint/wazuh/pack" "$PKG_ROOT/opt/beacon/wazuh"
+ else
+ cp -R "$ROOT_DIR/cli/beacon/internal/endpoint/wazuh/pack/." "$PKG_ROOT/opt/beacon/wazuh/"
+ fi
fi
find "$PKG_ROOT" -name '._*' -delete
@@ -50,6 +61,7 @@ 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 {} \;
+find "$PKG_ROOT/opt/beacon/fleet" -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
@@ -67,7 +79,7 @@ if [ -n "${PKG_SIGN_IDENTITY:-}" ]; then
--identifier "$PKG_IDENTIFIER" \
--version "$VERSION" \
--install-location / \
- --filter '/\._[^/]*$' \
+ --filter '(^|/)\._[^/]*$' \
--filter '/\.DS_Store$' \
--filter '(^|/)CVS($|/)' \
--filter '(^|/)\.svn($|/)' \
@@ -80,7 +92,7 @@ else
--identifier "$PKG_IDENTIFIER" \
--version "$VERSION" \
--install-location / \
- --filter '/\._[^/]*$' \
+ --filter '(^|/)\._[^/]*$' \
--filter '/\.DS_Store$' \
--filter '(^|/)CVS($|/)' \
--filter '(^|/)\.svn($|/)' \
diff --git a/packaging/macos/fleet/queries/beacon-version.sql b/packaging/macos/fleet/queries/beacon-version.sql
new file mode 100644
index 00000000..1540f5e9
--- /dev/null
+++ b/packaging/macos/fleet/queries/beacon-version.sql
@@ -0,0 +1,7 @@
+SELECT
+ CASE
+ WHEN COUNT(*) = 0 THEN 'not_installed'
+ ELSE 'installed'
+ END AS beacon_install_state
+FROM file
+WHERE path = '/opt/beacon/bin/beacon';
diff --git a/packaging/macos/fleet/queries/collector-service-health.sql b/packaging/macos/fleet/queries/collector-service-health.sql
new file mode 100644
index 00000000..b236f97c
--- /dev/null
+++ b/packaging/macos/fleet/queries/collector-service-health.sql
@@ -0,0 +1,8 @@
+SELECT
+ CASE
+ WHEN COUNT(*) = 0 THEN 'not_loaded'
+ WHEN SUM(CASE WHEN pid > 0 THEN 1 ELSE 0 END) > 0 THEN 'running'
+ ELSE 'loaded_not_running'
+ END AS collector_service_health
+FROM launchd
+WHERE label = 'com.beacon.endpoint.collector';
diff --git a/packaging/macos/fleet/queries/configured-harnesses.sql b/packaging/macos/fleet/queries/configured-harnesses.sql
new file mode 100644
index 00000000..0c100b2b
--- /dev/null
+++ b/packaging/macos/fleet/queries/configured-harnesses.sql
@@ -0,0 +1,7 @@
+SELECT
+ CASE
+ WHEN COUNT(*) = 0 THEN 'missing'
+ ELSE 'present'
+ END AS endpoint_config_state
+FROM file
+WHERE path = '/Library/Application Support/Beacon/Endpoint/config.json';
diff --git a/packaging/macos/fleet/queries/content-retention.sql b/packaging/macos/fleet/queries/content-retention.sql
new file mode 100644
index 00000000..0c100b2b
--- /dev/null
+++ b/packaging/macos/fleet/queries/content-retention.sql
@@ -0,0 +1,7 @@
+SELECT
+ CASE
+ WHEN COUNT(*) = 0 THEN 'missing'
+ ELSE 'present'
+ END AS endpoint_config_state
+FROM file
+WHERE path = '/Library/Application Support/Beacon/Endpoint/config.json';
diff --git a/packaging/macos/fleet/queries/last-event-age-seconds.sql b/packaging/macos/fleet/queries/last-event-age-seconds.sql
new file mode 100644
index 00000000..cbe02dd4
--- /dev/null
+++ b/packaging/macos/fleet/queries/last-event-age-seconds.sql
@@ -0,0 +1,9 @@
+SELECT
+ CASE
+ WHEN COUNT(*) = 0 THEN 'no_events'
+ WHEN MAX(mtime) <= 0 THEN 'unknown'
+ ELSE CAST((strftime('%s', 'now') - MAX(mtime)) AS TEXT)
+ END AS last_event_age_seconds
+FROM file
+WHERE path = '/var/log/beacon-agent/runtime.jsonl'
+ AND size > 0;
diff --git a/packaging/macos/fleet/queries/runtime-log-writable.sql b/packaging/macos/fleet/queries/runtime-log-writable.sql
new file mode 100644
index 00000000..ebc1c4ad
--- /dev/null
+++ b/packaging/macos/fleet/queries/runtime-log-writable.sql
@@ -0,0 +1,7 @@
+SELECT
+ CASE
+ WHEN COUNT(*) = 0 THEN 'missing'
+ ELSE 'present'
+ END AS runtime_log_state
+FROM file
+WHERE path = '/var/log/beacon-agent/runtime.jsonl';
diff --git a/packaging/macos/fleet/scripts/install.sh b/packaging/macos/fleet/scripts/install.sh
new file mode 100755
index 00000000..47b96e2c
--- /dev/null
+++ b/packaging/macos/fleet/scripts/install.sh
@@ -0,0 +1,15 @@
+#!/bin/sh
+set -eu
+
+BEACON_BIN="${BEACON_BIN:-/opt/beacon/bin/beacon}"
+BEACON_COLLECTOR="${BEACON_COLLECTOR:-${5:-/opt/beacon/bin/beacon-otelcol}}"
+BEACON_INSTALL_SCRIPT="${BEACON_INSTALL_SCRIPT:-/opt/beacon/scripts/install-endpoint.sh}"
+
+BEACON_BIN="$BEACON_BIN" \
+BEACON_ENDPOINT_HARNESSES="${BEACON_ENDPOINT_HARNESSES:-${1:-claude,codex}}" \
+BEACON_CONTENT_RETENTION="${BEACON_CONTENT_RETENTION:-${2:-full}}" \
+BEACON_OTLP_GRPC_PORT="${BEACON_OTLP_GRPC_PORT:-${3:-4317}}" \
+BEACON_OTLP_HTTP_PORT="${BEACON_OTLP_HTTP_PORT:-${4:-4318}}" \
+BEACON_COLLECTOR="$BEACON_COLLECTOR" \
+BEACON_NO_START="${BEACON_NO_START:-${6:-0}}" \
+ "$BEACON_INSTALL_SCRIPT"
diff --git a/packaging/macos/fleet/scripts/repair.sh b/packaging/macos/fleet/scripts/repair.sh
new file mode 100755
index 00000000..08de93c4
--- /dev/null
+++ b/packaging/macos/fleet/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:-${1:-claude,codex}}"
+BEACON_CONTENT_RETENTION="${BEACON_CONTENT_RETENTION:-${2:-full}}"
+BEACON_OTLP_GRPC_PORT="${BEACON_OTLP_GRPC_PORT:-${3:-4317}}"
+BEACON_OTLP_HTTP_PORT="${BEACON_OTLP_HTTP_PORT:-${4:-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/fleet/scripts/uninstall.sh b/packaging/macos/fleet/scripts/uninstall.sh
new file mode 100755
index 00000000..63ffb604
--- /dev/null
+++ b/packaging/macos/fleet/scripts/uninstall.sh
@@ -0,0 +1,9 @@
+#!/bin/sh
+set -eu
+
+BEACON_UNINSTALL_SCRIPT="${BEACON_UNINSTALL_SCRIPT:-/opt/beacon/scripts/uninstall-endpoint.sh}"
+
+BEACON_BIN="${BEACON_BIN:-/opt/beacon/bin/beacon}" \
+BEACON_KEEP_LOGS="${BEACON_KEEP_LOGS:-${1:-0}}" \
+BEACON_KEEP_CONFIG="${BEACON_KEEP_CONFIG:-${2:-0}}" \
+ "$BEACON_UNINSTALL_SCRIPT"
diff --git a/packaging/macos/fleet/scripts/validate.sh b/packaging/macos/fleet/scripts/validate.sh
new file mode 100755
index 00000000..62bf41e1
--- /dev/null
+++ b/packaging/macos/fleet/scripts/validate.sh
@@ -0,0 +1,11 @@
+#!/bin/sh
+set -eu
+
+BEACON_BIN="${BEACON_BIN:-/opt/beacon/bin/beacon}"
+
+"$BEACON_BIN" endpoint status --json
+"$BEACON_BIN" endpoint wazuh validate
+
+if command -v launchctl >/dev/null 2>&1; then
+ launchctl print system/com.beacon.endpoint.collector >/dev/null
+fi
diff --git a/packaging/macos/pkgbuild.md b/packaging/macos/pkgbuild.md
index 58a785d2..745942e3 100644
--- a/packaging/macos/pkgbuild.md
+++ b/packaging/macos/pkgbuild.md
@@ -6,12 +6,13 @@ installs:
- `beacon`
- `beacon-otelcol`
- Jamf policy scripts and Extension Attributes
+- Fleet scripts and osquery policy/label examples
- Wazuh content pack files for admins that want to import examples/rules
`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.
+`install-cursor-hooks.sh` helper or an equivalent Fleet user-context script so
+the command runs in the target user's context.
## Build Inputs
@@ -72,7 +73,8 @@ NOTARYTOOL_PROFILE="beacon-notary-profile" \
The package installs files under `/opt/beacon` and runs
`/opt/beacon/scripts/install-endpoint.sh` in `postinstall` with explicit
-collector and retention settings.
+collector and retention settings. The default packaged content retention is
+`full`, matching the shared MDM install wrapper.
## Jamf Deployment
@@ -96,6 +98,19 @@ Upload Extension Attributes from
unhealthy, stale, or misconfigured endpoints. Scope `repair.sh` to those Smart
Groups for automated remediation.
+## Fleet Deployment
+
+Upload the generated `.pkg` as Fleet software and scope it to a pilot team or
+label. For default deployment, no post-install script is required because the
+package postinstall performs the system install.
+
+Fleet remediation and validation scripts are packaged under
+`/opt/beacon/fleet/scripts`, and osquery examples are packaged under
+`/opt/beacon/fleet/queries`. Use the queries as Fleet policies or labels for
+missing, unhealthy, stale, or misconfigured endpoints. Scope `repair.sh` to
+hosts that fail the collector health, log freshness, retention, or log
+writability policies.
+
Release gates:
- `sh packaging/macos/test-endpoint-scripts.sh` passes
@@ -107,4 +122,5 @@ Release gates:
- `sudo launchctl print system/com.beacon.endpoint.collector` reports the
collector service as loaded/running
- Jamf Extension Attributes report expected values after a recon
+- Fleet queries report expected values after host detail refresh
diff --git a/packaging/macos/scripts/postinstall b/packaging/macos/scripts/postinstall
index 8ba6f65b..bf209500 100755
--- a/packaging/macos/scripts/postinstall
+++ b/packaging/macos/scripts/postinstall
@@ -4,14 +4,16 @@ 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_CONTENT_RETENTION="${BEACON_CONTENT_RETENTION:-full}" \
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
+ launchctl bootstrap system /Library/LaunchDaemons/com.beacon.endpoint.collector.plist >/dev/null 2>&1 || {
+ launchctl print system/com.beacon.endpoint.collector >/dev/null 2>&1 || exit 1
+ }
fi
exit 0
diff --git a/packaging/macos/test-endpoint-scripts.sh b/packaging/macos/test-endpoint-scripts.sh
index fdb61f6d..2d7fa151 100644
--- a/packaging/macos/test-endpoint-scripts.sh
+++ b/packaging/macos/test-endpoint-scripts.sh
@@ -6,13 +6,14 @@ 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"
REPAIR_SCRIPT="$ROOT_DIR/packaging/macos/jamf/scripts/repair.sh"
+FLEET_REPAIR_SCRIPT="$ROOT_DIR/packaging/macos/fleet/scripts/repair.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
+for script in "$ROOT_DIR"/packaging/macos/scripts/* "$ROOT_DIR"/packaging/macos/jamf/scripts/*.sh "$ROOT_DIR"/packaging/macos/jamf/extension-attributes/*.sh "$ROOT_DIR"/packaging/macos/fleet/scripts/*.sh; do
sh -n "$script"
done
@@ -96,6 +97,50 @@ case "$UNINSTALL_ARGS" in
;;
esac
+BEACON_BIN="$STUB_BIN" \
+BEACON_INSTALL_SCRIPT="$INSTALL_SCRIPT" \
+STUB_LOG="$STUB_LOG" \
+"$ROOT_DIR/packaging/macos/fleet/scripts/install.sh" "cursor" "redacted" "7317" "7318" "/tmp/fleet-otelcol" "1"
+
+INSTALL_ARGS="$(cat "$STUB_LOG")"
+case "$INSTALL_ARGS" in
+ "endpoint install --system --harness cursor --content-retention redacted --otlp-grpc-port 7317 --otlp-http-port 7318 --collector /tmp/fleet-otelcol --no-start") ;;
+ *)
+ echo "unexpected Fleet positional install args: $INSTALL_ARGS" >&2
+ exit 1
+ ;;
+esac
+
+BEACON_BIN="$STUB_BIN" \
+BEACON_COLLECTOR="/tmp/beacon-otelcol" \
+STUB_LOG="$STUB_LOG" \
+"$FLEET_REPAIR_SCRIPT" "claude,cursor" "metadata" "8317" "8318"
+
+REPAIR_ARGS="$(cat "$STUB_LOG")"
+case "$REPAIR_ARGS" in
+ "endpoint repair --collector /tmp/beacon-otelcol --harness claude,cursor --content-retention metadata --otlp-grpc-port 8317 --otlp-http-port 8318") ;;
+ *)
+ echo "unexpected Fleet positional repair args: $REPAIR_ARGS" >&2
+ exit 1
+ ;;
+esac
+
+BEACON_BIN="$STUB_BIN" \
+BEACON_KEEP_LOGS="1" \
+BEACON_KEEP_CONFIG="1" \
+BEACON_UNINSTALL_SCRIPT="$UNINSTALL_SCRIPT" \
+STUB_LOG="$STUB_LOG" \
+"$ROOT_DIR/packaging/macos/fleet/scripts/uninstall.sh"
+
+UNINSTALL_ARGS="$(cat "$STUB_LOG")"
+case "$UNINSTALL_ARGS" in
+ "endpoint uninstall --system --keep-logs --keep-config") ;;
+ *)
+ echo "unexpected Fleet uninstall args with keep logs: $UNINSTALL_ARGS" >&2
+ exit 1
+ ;;
+esac
+
CONFIG_PATH="$TMP_DIR/config.json"
cat >"$CONFIG_PATH" <<'JSON'
{