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
mdm scripts
Justin D'Souza9ee4a634bf5f
diff --git a/README.md b/README.mdindex 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 DoesBeacon can currently:diff --git a/images/beacon-architecture.png b/images/beacon-architecture.pngnew file mode 100644index 00000000..42e5312aBinary files /dev/null and b/images/beacon-architecture.png differdiff --git a/images/beacon-hero.png b/images/beacon-hero.pngnew file mode 100644index 00000000..99db8a33Binary files /dev/null and b/images/beacon-hero.png differdiff --git a/packaging/macos/README.md b/packaging/macos/README.mdindex deaed9d3..bf35341d 100644--- a/packaging/macos/README.md+++ b/packaging/macos/README.md@@ -1,11 +1,13 @@# macOS DeploymentThis 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 auser-mode install with `--no-start`, validates status/Wazuh output, installsCursor 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 ValidationAfter deploying the package, run:@@ -135,3 +167,83 @@ sudo /opt/beacon/bin/beacon endpoint wazuh validatesudo 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.shindex 4fd7565c..493df4e4 100755--- a/packaging/macos/build-pkg.sh+++ b/packaging/macos/build-pkg.sh@@ -30,19 +30,30 @@ if [ ! -x "$COLLECTOR_BIN" ]; thenfimkdir -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" ]; thenmkdir -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/"+ fififind "$PKG_ROOT" -name '._*' -delete@@ -50,6 +61,7 @@ find "$PKG_ROOT" -name '._*' -deletechmod 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 '._*' -deleteif 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.sqlnew file mode 100644index 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.sqlnew file mode 100644index 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.sqlnew file mode 100644index 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.sqlnew file mode 100644index 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.sqlnew file mode 100644index 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.sqlnew file mode 100644index 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.shnew file mode 100755index 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.shnew file mode 100755index 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.shnew file mode 100755index 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.shnew file mode 100755index 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+fidiff --git a/packaging/macos/pkgbuild.md b/packaging/macos/pkgbuild.mdindex 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 fromunhealthy, stale, or misconfigured endpoints. Scope `repair.sh` to those SmartGroups 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 thecollector service as loaded/running- Jamf Extension Attributes report expected values after a recon+- Fleet queries report expected values after host detail refreshdiff --git a/packaging/macos/scripts/postinstall b/packaging/macos/scripts/postinstallindex 8ba6f65b..bf209500 100755--- a/packaging/macos/scripts/postinstall+++ b/packaging/macos/scripts/postinstall@@ -4,14 +4,16 @@ set -euBEACON_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.shif 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+ }fiexit 0diff --git a/packaging/macos/test-endpoint-scripts.sh b/packaging/macos/test-endpoint-scripts.shindex 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 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+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; dosh -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'{