Skip to content

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

Fix the Fleet S3 helper's reruns, automatic install, and credential checks

shukieshahf447a0e16810
diff --git a/examples/fleet/configure-beacon-macos-s3.sh b/examples/fleet/configure-beacon-macos-s3.sh
index 636244ec..544ecb60 100755
--- a/examples/fleet/configure-beacon-macos-s3.sh
+++ b/examples/fleet/configure-beacon-macos-s3.sh
@@ -10,6 +10,10 @@
# "All teams". A failing Fleet post-install script uninstalls the package, so
# this helper does not put S3 or self-update enablement in post-install.
#
+# Fleet 4.82 renamed teams to fleets and queries to reports. This helper sends
+# the older names (team_id, /teams, /queries), which every Fleet version from
+# 4.62 on accepts; newer servers treat them as aliases.
+#
# Usage:
# ./configure-beacon-macos-s3.sh
# FLEET_URL=https://fleet.example FLEET_TOKEN=... FLEET_TEAM_ID=1 ./configure-beacon-macos-s3.sh --yes
@@ -23,20 +27,29 @@ set -euo pipefail
SCRIPT_NAME="$(basename "$0")"
MANIFEST_URL="${BEACON_UPDATE_MANIFEST_URL:-https://github.com/asymptote-labs/agent-beacon/releases/latest/download/update-manifest.json}"
PKG_IDENTIFIER="${BEACON_PKG_IDENTIFIER:-ai.asymptote.beacon.endpoint}"
-SOFTWARE_QUERY="${BEACON_FLEET_SOFTWARE_QUERY:-Beacon}"
+# The one place the team parameter is named. Fleet accepts team_id before and
+# after its 4.82 rename; switch this to fleet_id if Fleet drops the alias.
+FLEET_TEAM_PARAM="${BEACON_FLEET_TEAM_PARAM:-team_id}"
+SOFTWARE_DISPLAY_NAME="Beacon Endpoint Agent"
+# The package is Apple Silicon only. osquery reports arm64e on Apple Silicon.
+PRE_INSTALL_QUERY="SELECT 1 FROM system_info WHERE cpu_type LIKE 'arm64%';"
ENABLE_UPDATES_SCRIPT_NAME="beacon-enable-self-updates.sh"
CONFIGURE_S3_SCRIPT_NAME="beacon-configure-s3-forwarding.sh"
VALIDATE_SCRIPT_NAME="beacon-validate.sh"
SECRET_ACCESS_KEY_NAME="FLEET_SECRET_BEACON_AWS_ACCESS_KEY_ID"
SECRET_SECRET_KEY_NAME="FLEET_SECRET_BEACON_AWS_SECRET_ACCESS_KEY"
SECRET_SESSION_TOKEN_NAME="FLEET_SECRET_BEACON_AWS_SESSION_TOKEN"
+INSTALLED_POLICY_NAME="Beacon: installed"
+PAGE_SIZE=100
+MAX_PAGES=50
ASSUME_YES=0
DRY_RUN=0
SKIP_DOWNLOAD=0
SKIP_SOFTWARE=0
SKIP_SCRIPTS=0
-SKIP_QUERIES=0
+SKIP_POLICIES=0
+SKIP_REPORTS=0
LOCAL_PKG=""
UPDATE_MODE="auto"
@@ -49,12 +62,14 @@ Usage: $SCRIPT_NAME [options]
Options:
-y, --yes Use environment variables; only prompt for missing values
- --dry-run Print the plan and generated host scripts; do not call Fleet
+ --dry-run Print the plan and generated host scripts; make no network calls
--pkg PATH Use an already-downloaded Beacon .pkg instead of GitHub
--skip-download Alias for --pkg when BEACON_PKG is set
- --skip-software Do not upload the .pkg (scripts/secrets/queries only)
- --skip-scripts Do not create Fleet host scripts
- --skip-queries Do not create Fleet saved queries
+ --skip-software Do not upload the .pkg (scripts/secrets/policies/reports only)
+ --skip-scripts Do not create Fleet host scripts or secret variables
+ --skip-policies Do not create Beacon health policies
+ --skip-reports Do not create Beacon saved queries (reports)
+ --skip-queries Alias for --skip-reports
--check-only Enable Beacon self-update in check-only mode
-h, --help Show this help
@@ -62,8 +77,13 @@ Environment:
FLEET_URL, FLEET_TOKEN, FLEET_TEAM_ID
BEACON_S3_BUCKET, AWS_REGION, BEACON_S3_PREFIX, BEACON_S3_STORAGE_CLASS
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
+ BEACON_AWS_CREDENTIAL_MODE=keys|none none: deliver AWS credentials another way
BEACON_PKG, BEACON_UPDATE_MANIFEST_URL
FLEET_AUTOMATIC_INSTALL=true|false default false (pilot first)
+
+The API token needs an admin or maintainer role on the team. Storing AWS keys
+as Fleet secret variables needs a global admin or maintainer; team roles cannot
+write them.
EOF
}
@@ -79,7 +99,8 @@ while [ "$#" -gt 0 ]; do
--skip-download) SKIP_DOWNLOAD=1 ;;
--skip-software) SKIP_SOFTWARE=1 ;;
--skip-scripts) SKIP_SCRIPTS=1 ;;
- --skip-queries) SKIP_QUERIES=1 ;;
+ --skip-policies) SKIP_POLICIES=1 ;;
+ --skip-reports|--skip-queries) SKIP_REPORTS=1 ;;
--check-only) UPDATE_MODE="check-only" ;;
-h|--help)
usage
@@ -245,6 +266,145 @@ yes_no() {
esac
}
+# SQL for the Beacon policies and reports. These are exact copies of
+# packaging/macos/fleet/{policies,queries}/*.sql, embedded because this helper is
+# downloaded on its own; a test fails if they drift.
+beacon_sql() {
+ case "$1" in
+ policies/beacon-installed)
+ cat <<'EOF'
+SELECT 1 WHERE
+ NOT EXISTS (SELECT 1 FROM system_info WHERE cpu_type LIKE 'arm64%')
+ OR (
+ EXISTS (SELECT 1 FROM package_receipts WHERE package_id = 'ai.asymptote.beacon.endpoint')
+ AND EXISTS (SELECT 1 FROM file WHERE path = '/opt/beacon/bin/beacon')
+ );
+EOF
+ ;;
+ policies/collector-running)
+ cat <<'EOF'
+SELECT 1 WHERE
+ NOT EXISTS (SELECT 1 FROM system_info WHERE cpu_type LIKE 'arm64%')
+ OR EXISTS (SELECT 1 FROM processes WHERE path = '/opt/beacon/bin/beacon-otelcol' AND uid = 0);
+EOF
+ ;;
+ policies/s3-forwarder-running)
+ cat <<'EOF'
+SELECT 1 WHERE
+ NOT EXISTS (SELECT 1 FROM system_info WHERE cpu_type LIKE 'arm64%')
+ OR EXISTS (
+ SELECT 1 FROM processes
+ WHERE path = '/opt/beacon/bin/vector'
+ AND cmdline LIKE '%/Beacon/Forwarders/s3-vector.toml%'
+ );
+EOF
+ ;;
+ policies/s3-forwarding-configured)
+ cat <<'EOF'
+SELECT 1 WHERE
+ NOT EXISTS (SELECT 1 FROM system_info WHERE cpu_type LIKE 'arm64%')
+ OR (
+ EXISTS (SELECT 1 FROM file WHERE path = '/Library/Application Support/Beacon/Forwarders/s3-vector.env' AND size > 0)
+ AND EXISTS (SELECT 1 FROM file WHERE path = '/Library/Application Support/Beacon/Forwarders/s3-vector.toml')
+ AND EXISTS (SELECT 1 FROM file WHERE path = '/Library/LaunchDaemons/com.beacon.endpoint.s3-forwarder.plist')
+ );
+EOF
+ ;;
+ policies/inventory-heartbeat-recent)
+ cat <<'EOF'
+SELECT 1 WHERE
+ NOT EXISTS (SELECT 1 FROM system_info WHERE cpu_type LIKE 'arm64%')
+ OR EXISTS (
+ SELECT 1 FROM file
+ WHERE path = '/var/log/beacon-agent/inventory_state.jsonl'
+ AND mtime >= CAST(strftime('%s', 'now') AS INTEGER) - 345600
+ );
+EOF
+ ;;
+ queries/beacon-version)
+ cat <<'EOF'
+SELECT COALESCE(
+ (SELECT version FROM package_receipts WHERE package_id = 'ai.asymptote.beacon.endpoint'),
+ CASE
+ WHEN EXISTS (SELECT 1 FROM file WHERE path = '/opt/beacon/bin/beacon') THEN 'installed_without_receipt'
+ ELSE 'not_installed'
+ END
+) AS beacon_version;
+EOF
+ ;;
+ queries/collector-service-health)
+ cat <<'EOF'
+SELECT
+ CASE
+ WHEN EXISTS (SELECT 1 FROM processes WHERE path = '/opt/beacon/bin/beacon-otelcol' AND uid = 0) THEN 'running'
+ WHEN EXISTS (SELECT 1 FROM file WHERE path = '/Library/LaunchDaemons/com.beacon.endpoint.collector.plist') THEN 'not_running'
+ ELSE 'not_installed'
+ END AS collector_service_health;
+EOF
+ ;;
+ queries/s3-vector-forwarder-health)
+ cat <<'EOF'
+SELECT
+ CASE
+ WHEN EXISTS (
+ SELECT 1 FROM processes
+ WHERE path = '/opt/beacon/bin/vector'
+ AND cmdline LIKE '%/Beacon/Forwarders/s3-vector.toml%'
+ ) THEN 'running'
+ WHEN EXISTS (SELECT 1 FROM file WHERE path = '/Library/LaunchDaemons/com.beacon.endpoint.s3-forwarder.plist') THEN 'not_running'
+ ELSE 'not_configured'
+ END AS s3_vector_forwarder_health;
+EOF
+ ;;
+ queries/s3-vector-forwarding-configured)
+ cat <<'EOF'
+SELECT
+ CASE
+ WHEN COUNT(*) = 0 THEN 'not_configured'
+ ELSE 'configured'
+ END AS s3_vector_forwarding_state
+FROM file
+WHERE path = '/Library/Application Support/Beacon/Forwarders/s3-vector.env';
+EOF
+ ;;
+ queries/inventory-heartbeat-age-seconds)
+ cat <<'EOF'
+SELECT COALESCE(
+ (SELECT CAST(CAST(strftime('%s', 'now') AS INTEGER) - mtime AS TEXT)
+ FROM file
+ WHERE path = '/var/log/beacon-agent/inventory_state.jsonl'),
+ 'missing'
+) AS inventory_heartbeat_age_seconds;
+EOF
+ ;;
+ *)
+ echo "Unknown Beacon SQL: $1" >&2
+ return 1
+ ;;
+ esac
+}
+
+# Policies: name|sql|description|resolution. Each returns a row only when the
+# host is healthy, and passes on Intel Macs, where the package does not apply.
+BEACON_POLICIES=(
+ "${INSTALLED_POLICY_NAME}|policies/beacon-installed|The Beacon package receipt and /opt/beacon/bin/beacon are present.|Install the Beacon Endpoint Agent software package on this host."
+ "Beacon: collector running|policies/collector-running|The Beacon collector (beacon-otelcol) is running as root.|Run /opt/beacon/fleet/scripts/repair.sh, or reinstall the Beacon package."
+ "Beacon: S3 forwarder running|policies/s3-forwarder-running|The Vector S3 forwarder is running with the Beacon S3 config.|Run the ${CONFIGURE_S3_SCRIPT_NAME} script, then check /tmp/com.beacon.endpoint.s3-forwarder.err."
+ "Beacon: S3 forwarding configured|policies/s3-forwarding-configured|The S3 forwarder env file, Vector config, and LaunchDaemon are present.|Run the ${CONFIGURE_S3_SCRIPT_NAME} script on this host."
+ "Beacon: inventory heartbeat within 4 days|policies/inventory-heartbeat-recent|The scheduled inventory job wrote a heartbeat in the last 96 hours. It runs every 6 hours while the Mac is awake.|Run sudo launchctl kickstart system/com.beacon.endpoint.inventory, then check sudo /opt/beacon/bin/beacon endpoint status --system."
+)
+
+# Reports (saved queries): name|sql|description. Each returns one row per host.
+BEACON_REPORTS=(
+ "Beacon install state|queries/beacon-version|Installed Beacon package version, or not_installed."
+ "Beacon collector health|queries/collector-service-health|Whether the Beacon collector process is running."
+ "Beacon S3 forwarder health|queries/s3-vector-forwarder-health|Whether the Vector S3 forwarder process is running."
+ "Beacon S3 forwarding configured|queries/s3-vector-forwarding-configured|Whether the Vector S3 environment file exists."
+ "Beacon inventory heartbeat age|queries/inventory-heartbeat-age-seconds|Seconds since the scheduled inventory job last wrote a heartbeat."
+)
+
+# fleet_request also records the status in a file, because callers often run it
+# inside $(...), where a variable set in the subshell never reaches the caller.
FLEET_HTTP_STATUS=""
fleet_request() {
local method="$1"
@@ -263,9 +423,14 @@ fleet_request() {
"${FLEET_URL}${path}"
)"
FLEET_HTTP_STATUS="$code"
+ printf '%s' "$code" >"$WORK_DIR/http-status"
cat "$body"
}
+last_status() {
+ FLEET_HTTP_STATUS="$(cat "$WORK_DIR/http-status" 2>/dev/null || true)"
+}
+
fleet_json() {
local method="$1"
local path="$2"
@@ -273,12 +438,7 @@ fleet_json() {
fleet_request "$method" "$path" -H "Content-Type: application/json" "$@"
}
-require_ok() {
- local action="$1"
- case "$FLEET_HTTP_STATUS" in
- 2*) return 0 ;;
- esac
- echo "$action failed (HTTP $FLEET_HTTP_STATUS)" >&2
+print_fleet_error_body() {
if [ -s "$WORK_DIR/http-body" ]; then
python3 -c '
import json,sys
@@ -296,22 +456,93 @@ else:
print(msg)
' <"$WORK_DIR/http-body" >&2 || cat "$WORK_DIR/http-body" >&2
fi
+}
+
+# require_ok ACTION [HINT]: exit unless the last Fleet call succeeded. HINT is
+# printed for 402/403, where the cause depends on which call was refused.
+require_ok() {
+ local action="$1"
+ local hint="${2:-}"
+ last_status
+ case "$FLEET_HTTP_STATUS" in
+ 2*) return 0 ;;
+ esac
+ echo "$action failed (HTTP $FLEET_HTTP_STATUS)" >&2
+ print_fleet_error_body
case "$FLEET_HTTP_STATUS" in
+ 401)
+ echo "Fleet rejected the API token. Check that it is correct and has not expired." >&2
+ ;;
402|403)
- echo "Custom software packages require Fleet Premium, a specific team (not All teams), and a token that can manage that team." >&2
+ if [ -n "$hint" ]; then
+ echo "$hint" >&2
+ fi
;;
esac
exit 1
}
+team_query() {
+ printf '%s=%s' "$FLEET_TEAM_PARAM" "$FLEET_TEAM_ID"
+}
+
+# fleet_list_all PATH KEYS HINT: fetch every page of a Fleet list endpoint and
+# print the combined items as one JSON array. KEYS is a |-separated list of
+# response keys to read items from (Fleet 4.82 renamed some of them). Paging
+# stops at meta.has_next_results, or at a short page when there is no meta.
+fleet_list_all() {
+ local path="$1"
+ local keys="$2"
+ local hint="${3:-}"
+ local page=0 sep="?" next=""
+ local acc="$WORK_DIR/list-acc.json"
+ case "$path" in
+ *\?*) sep="&" ;;
+ esac
+ printf '[]' >"$acc"
+ while [ "$page" -lt "$MAX_PAGES" ]; do
+ fleet_json GET "${path}${sep}page=${page}&per_page=${PAGE_SIZE}" >"$WORK_DIR/list-page.json"
+ require_ok "Listing ${path%%\?*}" "$hint"
+ next="$(
+ python3 -c '
+import json, sys
+keys = sys.argv[1].split("|")
+page_size = int(sys.argv[2])
+acc_path, page_path = sys.argv[3], sys.argv[4]
+data = json.loads(open(page_path).read() or "{}")
+items = []
+for key in keys:
+ if isinstance(data.get(key), list):
+ items = data[key]
+ break
+acc = json.load(open(acc_path))
+acc.extend(items)
+json.dump(acc, open(acc_path, "w"))
+meta = data.get("meta")
+if isinstance(meta, dict) and "has_next_results" in meta:
+ print("yes" if meta.get("has_next_results") else "no")
+else:
+ print("yes" if len(items) >= page_size else "no")
+' "$keys" "$PAGE_SIZE" "$acc" "$WORK_DIR/list-page.json"
+ )"
+ [ "$next" = "yes" ] || break
+ page=$((page + 1))
+ done
+ cat "$acc"
+}
+
echo
echo "Beacon Fleet + S3 setup"
echo "======================="
echo "This helper uploads the latest Apple Silicon Beacon .pkg to one Fleet"
-echo "team, stores S3 credentials as Fleet secret variables, and creates host"
-echo "scripts that enable self-updates and Vector forwarding after install."
+echo "team, stores S3 credentials as Fleet secret variables, creates host"
+echo "scripts that enable self-updates and Vector forwarding after install, and"
+echo "adds Beacon health policies and reports."
echo
+# Everything up to the plan is local: prompts and validation only. No Fleet or
+# GitHub call happens until every input is known to be usable.
+
if [ "$DRY_RUN" -eq 0 ] || [ -n "${FLEET_URL:-}" ]; then
prompt_value FLEET_URL "Fleet URL (https://fleet.example.com)"
fi
@@ -331,52 +562,37 @@ if [ "$DRY_RUN" -eq 0 ]; then
echo "A Fleet API token is required" >&2
exit 1
fi
- echo "Checking Fleet credentials..."
- me="$(fleet_json GET /api/latest/fleet/me)"
- require_ok "Fleet authentication"
- me_name="$(printf '%s' "$me" | json_get user name)"
- me_email="$(printf '%s' "$me" | json_get user email)"
- echo "Authenticated as ${me_name:-unknown}${me_email:+ <$me_email>}"
else
FLEET_TOKEN="${FLEET_TOKEN:-dry-run}"
fi
if [ -z "${FLEET_TEAM_ID:-}" ]; then
if [ "$DRY_RUN" -eq 1 ]; then
- FLEET_TEAM_ID="${FLEET_TEAM_ID:-1}"
+ FLEET_TEAM_ID="1"
elif [ "$ASSUME_YES" -eq 1 ]; then
echo "FLEET_TEAM_ID is required. Custom packages cannot be added to All teams." >&2
exit 1
- else
- echo
- echo "Available Fleet teams:"
- teams_json="$(fleet_json GET /api/latest/fleet/teams)"
- require_ok "Listing Fleet teams"
- python3 -c '
-import json,sys
-data=json.loads(sys.stdin.read() or "{}")
-teams=data.get("teams") or []
-if not teams:
- print(" (none returned; you still need a team ID, not All teams)")
- raise SystemExit
-for t in teams:
- print(" {id:>6} {name}".format(id=t.get("id"), name=t.get("name")))
-' <<<"$teams_json"
- prompt_value FLEET_TEAM_ID "Fleet team ID to deploy into"
fi
fi
-if ! printf '%s' "$FLEET_TEAM_ID" | grep -Eq '^[0-9]+$'; then
+if [ -n "${FLEET_TEAM_ID:-}" ] && ! printf '%s' "$FLEET_TEAM_ID" | grep -Eq '^[0-9]+$'; then
echo "FLEET_TEAM_ID must be a number. Fleet cannot add custom packages to All teams." >&2
exit 1
fi
-if [ -z "${FLEET_AUTOMATIC_INSTALL:-}" ]; then
- if yes_no "Create a Fleet automatic-install policy for this package? Start with a pilot team" n; then
- FLEET_AUTOMATIC_INSTALL="true"
- else
- FLEET_AUTOMATIC_INSTALL="false"
- fi
-fi
+case "${FLEET_AUTOMATIC_INSTALL:-}" in
+ true|false) ;;
+ "")
+ if yes_no "Install Beacon automatically on every Apple Silicon Mac in this team? Start with a pilot team" n; then
+ FLEET_AUTOMATIC_INSTALL="true"
+ else
+ FLEET_AUTOMATIC_INSTALL="false"
+ fi
+ ;;
+ *)
+ echo "FLEET_AUTOMATIC_INSTALL must be true or false (got '$FLEET_AUTOMATIC_INSTALL')" >&2
+ exit 2
+ ;;
+esac
echo
prompt_value BEACON_S3_BUCKET "S3 bucket name"
@@ -403,27 +619,46 @@ echo "stored as Fleet secret variables (\$FLEET_SECRET_*) and substituted only"
echo "when Fleet sends the script to a host. Fleet still prints script output,"
echo "so the host script never echoes credentials."
echo
-CREDENTIAL_MODE="${BEACON_AWS_CREDENTIAL_MODE:-}"
-if [ -z "$CREDENTIAL_MODE" ]; then
- if [ -n "${AWS_ACCESS_KEY_ID:-}" ] && [ -n "${AWS_SECRET_ACCESS_KEY:-}" ]; then
- CREDENTIAL_MODE="keys"
- elif [ "$ASSUME_YES" -eq 1 ]; then
- CREDENTIAL_MODE="none"
- else
- printf 'AWS credentials: [k]ey pair (recommended) / [n]one, I will deliver them another way [k]: ' >&2
- IFS= read -r CREDENTIAL_MODE
- case "${CREDENTIAL_MODE:-k}" in
- n|N|none) CREDENTIAL_MODE="none" ;;
- *) CREDENTIAL_MODE="keys" ;;
- esac
- fi
-fi
+CREDENTIAL_MODE=""
+case "${BEACON_AWS_CREDENTIAL_MODE:-}" in
+ keys|none)
+ CREDENTIAL_MODE="$BEACON_AWS_CREDENTIAL_MODE"
+ ;;
+ "")
+ if [ -n "${AWS_ACCESS_KEY_ID:-}" ] && [ -n "${AWS_SECRET_ACCESS_KEY:-}" ]; then
+ CREDENTIAL_MODE="keys"
+ elif [ "$DRY_RUN" -eq 1 ]; then
+ # The preview shows the $FLEET_SECRET_* placeholders; no key is needed.
+ CREDENTIAL_MODE="keys"
+ elif [ "$ASSUME_YES" -eq 1 ]; then
+ echo "AWS credentials are missing. Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY," >&2
+ echo "or set BEACON_AWS_CREDENTIAL_MODE=none if you deliver credentials to the Macs another way." >&2
+ exit 1
+ else
+ printf 'AWS credentials: [k]ey pair (recommended) / [n]one, I will deliver them another way [k]: ' >&2
+ IFS= read -r CREDENTIAL_MODE || true
+ case "${CREDENTIAL_MODE:-k}" in
+ k|K|keys) CREDENTIAL_MODE="keys" ;;
+ n|N|none) CREDENTIAL_MODE="none" ;;
+ *)
+ echo "Answer k or n" >&2
+ exit 2
+ ;;
+ esac
+ fi
+ ;;
+ *)
+ echo "BEACON_AWS_CREDENTIAL_MODE must be 'keys' or 'none' (got '$BEACON_AWS_CREDENTIAL_MODE')" >&2
+ exit 2
+ ;;
+esac
-if [ "$CREDENTIAL_MODE" = "keys" ]; then
+CREDENTIAL_LABEL="$CREDENTIAL_MODE"
+if [ "$CREDENTIAL_MODE" = "keys" ] && [ "$DRY_RUN" -eq 0 ]; then
prompt_value AWS_ACCESS_KEY_ID "AWS access key ID"
prompt_secret_confirm AWS_SECRET_ACCESS_KEY "AWS secret access key"
if [ -z "${AWS_SESSION_TOKEN:-}" ] && [ "$ASSUME_YES" -eq 0 ]; then
- printf 'AWS session token (optional, Enter to skip): ' >&2
+ printf 'AWS session token (only for temporary credentials; Enter to skip): ' >&2
IFS= read -r -s AWS_SESSION_TOKEN || true
printf '\n' >&2
fi
@@ -431,11 +666,42 @@ if [ "$CREDENTIAL_MODE" = "keys" ]; then
echo "AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are required for key-pair mode" >&2
exit 1
fi
+ case "$AWS_ACCESS_KEY_ID" in
+ ASIA*)
+ if [ -z "${AWS_SESSION_TOKEN:-}" ]; then
+ echo "AWS_ACCESS_KEY_ID starts with ASIA, so it is a temporary key and needs AWS_SESSION_TOKEN." >&2
+ echo "Use a long-lived IAM user key (AKIA...) for the S3 writer instead." >&2
+ exit 1
+ fi
+ ;;
+ AKIA*)
+ if [ -n "${AWS_SESSION_TOKEN:-}" ]; then
+ echo "Warning: AWS_SESSION_TOKEN is set but AWS_ACCESS_KEY_ID is a long-lived key (AKIA...)." >&2
+ echo "Long-lived keys do not use a session token; check that the values belong together." >&2
+ fi
+ ;;
+ esac
+ if [ -n "${AWS_SESSION_TOKEN:-}" ]; then
+ CREDENTIAL_LABEL="keys (temporary, expires)"
+ echo >&2
+ echo "Warning: these are temporary AWS credentials. Each Mac stores them once, when the" >&2
+ echo "S3 script runs. When the session token expires, S3 rejects the uploads and Vector" >&2
+ echo "drops those batches until you rerun this helper and the S3 script with new values." >&2
+ echo "Use a long-lived IAM user key limited to s3:PutObject for the writer, or set" >&2
+ echo "BEACON_AWS_CREDENTIAL_MODE=none and give the Macs credentials that refresh themselves." >&2
+ echo >&2
+ if [ "$ASSUME_YES" -eq 0 ] && ! yes_no "Continue with temporary credentials?" n; then
+ exit 1
+ fi
+ fi
+elif [ "$CREDENTIAL_MODE" = "keys" ] && [ -n "${AWS_SESSION_TOKEN:-}" ]; then
+ CREDENTIAL_LABEL="keys (temporary, expires)"
fi
PKG_PATH=""
PKG_VERSION=""
PKG_SHA=""
+PKG_PLAN="skipped"
if [ "$SKIP_SOFTWARE" -eq 0 ]; then
if [ "$SKIP_DOWNLOAD" -eq 1 ]; then
PKG_PATH="${LOCAL_PKG:-}"
@@ -443,31 +709,11 @@ if [ "$SKIP_SOFTWARE" -eq 0 ]; then
echo " --pkg / BEACON_PKG must point at an existing .pkg" >&2
exit 1
fi
- PKG_VERSION="$(basename "$PKG_PATH")"
+ PKG_SHA="$(sha256_file "$PKG_PATH")"
+ PKG_VERSION="$(basename "$PKG_PATH" | sed -n 's/^BeaconEndpointAgent-\(.*\)-arm64\.pkg$/\1/p')"
+ PKG_PLAN="$PKG_PATH"
else
- echo
- echo "Fetching latest Beacon release manifest..."
- curl -fsSL --max-time 60 "$MANIFEST_URL" >"$WORK_DIR/update-manifest.json"
- PKG_VERSION="$(json_get version <"$WORK_DIR/update-manifest.json")"
- PKG_URL="$(json_get artifacts darwin_arm64 url <"$WORK_DIR/update-manifest.json")"
- PKG_SHA="$(json_get artifacts darwin_arm64 sha256 <"$WORK_DIR/update-manifest.json")"
- if [ -z "$PKG_VERSION" ] || [ -z "$PKG_URL" ] || [ -z "$PKG_SHA" ]; then
- echo "update-manifest.json did not include a darwin_arm64 package" >&2
- cat "$WORK_DIR/update-manifest.json" >&2
- exit 1
- fi
- echo "Latest package: Beacon $PKG_VERSION (Apple Silicon)"
- PKG_PATH="$WORK_DIR/$(basename "$PKG_URL")"
- echo "Downloading $(basename "$PKG_URL")..."
- curl -fL --max-time 600 -o "$PKG_PATH" "$PKG_URL"
- actual_sha="$(sha256_file "$PKG_PATH")"
- if [ "$actual_sha" != "$PKG_SHA" ]; then
- echo "SHA-256 mismatch for $PKG_PATH" >&2
- echo " expected: $PKG_SHA" >&2
- echo " actual: $actual_sha" >&2
- exit 1
- fi
- echo "Checksum OK"
+ PKG_PLAN="latest darwin_arm64 package from $MANIFEST_URL"
fi
fi
@@ -586,19 +832,25 @@ echo
echo "Plan"
echo "----"
echo " Fleet: $FLEET_URL"
-echo " Team ID: $FLEET_TEAM_ID"
-echo " Package: ${PKG_PATH:-skipped}"
-echo " Version: ${PKG_VERSION:-unknown}"
+echo " Team ID: ${FLEET_TEAM_ID:-choose from the list}"
+echo " Package: $PKG_PLAN"
+echo " Version: ${PKG_VERSION:-latest}"
echo " Automatic install: $FLEET_AUTOMATIC_INSTALL"
echo " Self-update mode: $UPDATE_MODE"
echo " S3 bucket: $BEACON_S3_BUCKET"
echo " S3 prefix: $BEACON_S3_PREFIX/{runtime,inventory}/date=YYYY-MM-DD/"
echo " AWS region: $AWS_REGION"
-echo " AWS credentials: $CREDENTIAL_MODE"
+echo " AWS credentials: $CREDENTIAL_LABEL"
echo " Host scripts: $ENABLE_UPDATES_SCRIPT_NAME, $CONFIGURE_S3_SCRIPT_NAME, $VALIDATE_SCRIPT_NAME"
+if [ "$SKIP_POLICIES" -eq 0 ]; then
+ echo " Policies: ${#BEACON_POLICIES[@]} Beacon health policies"
+fi
+if [ "$SKIP_REPORTS" -eq 0 ]; then
+ echo " Reports: ${#BEACON_REPORTS[@]} Beacon saved queries"
+fi
if [ "$DRY_RUN" -eq 1 ]; then
echo
- echo "Dry run: not calling Fleet. Generated host scripts are in:"
+ echo "Dry run: no Fleet or GitHub calls were made. Generated host scripts are in:"
echo " $WORK_DIR"
echo
echo "----- $CONFIGURE_S3_SCRIPT_NAME -----"
@@ -608,6 +860,124 @@ if [ "$DRY_RUN" -eq 1 ]; then
exit 0
fi
+echo
+echo "Checking Fleet..."
+fleet_json GET /api/latest/fleet/version >"$WORK_DIR/version.json" || true
+if [ "$FLEET_HTTP_STATUS" = "200" ]; then
+ FLEET_VERSION="$(json_get version <"$WORK_DIR/version.json")"
+ echo "Fleet version: ${FLEET_VERSION:-unknown}"
+ if [ -n "$FLEET_VERSION" ] && python3 -c '
+import re, sys
+m = re.match(r"v?(\d+)\.(\d+)", sys.argv[1])
+sys.exit(0 if m and (int(m.group(1)), int(m.group(2))) < (4, 62) else 1)
+' "$FLEET_VERSION"; then
+ echo "Warning: Fleet $FLEET_VERSION is older than 4.62, which added secret variables. Upgrade Fleet before storing AWS keys." >&2
+ fi
+fi
+
+me="$(fleet_json GET /api/latest/fleet/me)"
+require_ok "Fleet authentication"
+me_name="$(printf '%s' "$me" | json_get user name)"
+me_email="$(printf '%s' "$me" | json_get user email)"
+echo "Authenticated as ${me_name:-unknown}${me_email:+ <$me_email>}"
+
+if [ -z "${FLEET_TEAM_ID:-}" ]; then
+ echo
+ echo "Available Fleet teams:"
+ teams_json="$(fleet_list_all /api/latest/fleet/teams "teams|fleets" "Listing teams needs a role that can read them.")"
+ python3 -c '
+import json,sys
+teams=json.loads(sys.stdin.read() or "[]")
+if not teams:
+ print(" (none returned; you still need a team ID, not All teams)")
+ raise SystemExit
+for t in teams:
+ print(" {id:>6} {name}".format(id=t.get("id"), name=t.get("name")))
+' <<<"$teams_json"
+ prompt_value FLEET_TEAM_ID "Fleet team ID to deploy into"
+ if ! printf '%s' "$FLEET_TEAM_ID" | grep -Eq '^[0-9]+$'; then
+ echo "FLEET_TEAM_ID must be a number. Fleet cannot add custom packages to All teams." >&2
+ exit 1
+ fi
+fi
+
+# Check the token's roles before writing anything. Only global admins,
+# maintainers, and GitOps users can write secret variables; team roles cannot.
+SECRETS_NEEDED="none"
+if [ "$CREDENTIAL_MODE" = "keys" ] && [ "$SKIP_SCRIPTS" -eq 0 ]; then
+ SECRETS_NEEDED="keys"
+fi
+role_check="$(
+ printf '%s' "$me" | python3 -c '
+import json, sys
+team = int(sys.argv[1])
+need_secrets = sys.argv[2] == "keys"
+user = (json.loads(sys.stdin.read() or "{}") or {}).get("user") or {}
+if "global_role" not in user and not (user.get("teams") or user.get("fleets")):
+ print("unknown")
+ raise SystemExit
+global_role = user.get("global_role")
+team_role = None
+for t in user.get("teams") or user.get("fleets") or []:
+ if t.get("id") == team:
+ team_role = t.get("role")
+write = {"admin", "maintainer"}
+if global_role not in write and team_role not in write:
+ print("team")
+elif need_secrets and global_role not in {"admin", "maintainer", "gitops"}:
+ print("secrets")
+else:
+ print("ok")
+' "$FLEET_TEAM_ID" "$SECRETS_NEEDED"
+)"
+case "$role_check" in
+ ok) ;;
+ unknown)
+ echo "Warning: Fleet did not report this token's roles; continuing without the role check." >&2
+ ;;
+ team)
+ echo "This API token cannot manage team $FLEET_TEAM_ID. It needs an admin or maintainer role on that team, or globally." >&2
+ exit 1
+ ;;
+ secrets)
+ echo "This API token cannot write Fleet secret variables. Only a global admin, maintainer, or GitOps user can; team roles cannot." >&2
+ echo "Use an API-only user with the global maintainer role, or rerun with BEACON_AWS_CREDENTIAL_MODE=none" >&2
+ echo "and add the BEACON_AWS_* variables under Controls > Variables yourself." >&2
+ exit 1
+ ;;
+esac
+
+if [ "$SKIP_SOFTWARE" -eq 0 ] && [ "$SKIP_DOWNLOAD" -eq 0 ]; then
+ echo
+ echo "Fetching latest Beacon release manifest..."
+ curl -fsSL --max-time 60 "$MANIFEST_URL" >"$WORK_DIR/update-manifest.json"
+ PKG_VERSION="$(json_get version <"$WORK_DIR/update-manifest.json")"
+ PKG_URL="$(json_get artifacts darwin_arm64 url <"$WORK_DIR/update-manifest.json")"
+ PKG_SHA="$(json_get artifacts darwin_arm64 sha256 <"$WORK_DIR/update-manifest.json")"
+ if [ -z "$PKG_VERSION" ] || [ -z "$PKG_URL" ] || [ -z "$PKG_SHA" ]; then
+ echo "update-manifest.json did not include a darwin_arm64 package" >&2
+ cat "$WORK_DIR/update-manifest.json" >&2
+ exit 1
+ fi
+ echo "Latest package: Beacon $PKG_VERSION (Apple Silicon)"
+ PKG_PATH="$WORK_DIR/$(basename "$PKG_URL")"
+ echo "Downloading $(basename "$PKG_URL")..."
+ curl -fL --max-time 600 -o "$PKG_PATH" "$PKG_URL"
+ actual_sha="$(sha256_file "$PKG_PATH")"
+ if [ "$actual_sha" != "$PKG_SHA" ]; then
+ echo "SHA-256 mismatch for $PKG_PATH" >&2
+ echo " expected: $PKG_SHA" >&2
+ echo " actual: $actual_sha" >&2
+ exit 1
+ fi
+ echo "Checksum OK"
+fi
+
+SECRETS_HINT="Fleet secret variables can only be written by a global admin, maintainer, or GitOps user; team roles cannot. Use an API-only user with the global maintainer role, or rerun with BEACON_AWS_CREDENTIAL_MODE=none and add the BEACON_AWS_* variables under Controls > Variables yourself."
+SCRIPTS_HINT="Managing scripts on team $FLEET_TEAM_ID needs an admin or maintainer role on that team, or globally. GitOps users can upload scripts but cannot list them, so this helper cannot use a GitOps token."
+SOFTWARE_HINT="Custom software packages need Fleet Premium, a specific team (not All teams), and an admin or maintainer role on that team."
+POLICIES_HINT="Team policies need an admin or maintainer role on team $FLEET_TEAM_ID, or globally."
+
if [ "$CREDENTIAL_MODE" = "keys" ] && [ "$SKIP_SCRIPTS" -eq 0 ]; then
echo
echo "Storing AWS credentials as Fleet secret variables..."
@@ -629,191 +999,349 @@ if token:
json.dump({"secrets": secrets}, sys.stdout)
' >"$WORK_DIR/secrets.json"
fleet_json PUT /api/latest/fleet/spec/secret_variables --data @"$WORK_DIR/secrets.json" >/dev/null
+ rm -f "$WORK_DIR/secrets.json"
if [ "$FLEET_HTTP_STATUS" = "404" ]; then
- echo "spec/secret_variables not found; trying custom_variables..."
- while IFS= read -r secret_item; do
- printf '%s\n' "$secret_item" >"$WORK_DIR/one-secret.json"
- fleet_json POST /api/latest/fleet/custom_variables --data @"$WORK_DIR/one-secret.json" >/dev/null
- require_ok "Creating Fleet custom variable"
- done < <(python3 -c '
-import json, pathlib, sys
-src = json.loads(pathlib.Path(sys.argv[1]).read_text())
-prefix = "FLEET_SECRET_"
-for item in src["secrets"]:
- name = item["name"]
- if name.startswith(prefix):
- name = name[len(prefix):]
- print(json.dumps({"name": name, "value": item["value"]}))
-' "$WORK_DIR/secrets.json")
- else
- require_ok "Storing Fleet secret variables"
+ echo "This Fleet server has no secret variables API. Fleet added it in 4.62." >&2
+ echo "Upgrade Fleet, or rerun with BEACON_AWS_CREDENTIAL_MODE=none and deliver AWS credentials to the Macs another way." >&2
+ exit 1
fi
- rm -f "$WORK_DIR/secrets.json"
+ require_ok "Storing Fleet secret variables" "$SECRETS_HINT"
echo "Fleet secret variables stored (values are hidden in the Fleet UI)."
fi
-upload_or_replace_script() {
- local name="$1"
- local file="$2"
- local scripts_json existing_id
- scripts_json="$(fleet_json GET "/api/latest/fleet/scripts?team_id=${FLEET_TEAM_ID}")"
- require_ok "Listing Fleet scripts"
- existing_id="$(
- python3 -c '
+if [ "$SKIP_SCRIPTS" -eq 0 ]; then
+ echo
+ scripts_json="$(fleet_list_all "/api/latest/fleet/scripts?$(team_query)" "scripts" "$SCRIPTS_HINT")"
+ for pair in \
+ "$ENABLE_UPDATES_SCRIPT_NAME|$ENABLE_UPDATES_SCRIPT" \
+ "$CONFIGURE_S3_SCRIPT_NAME|$S3_SCRIPT" \
+ "$VALIDATE_SCRIPT_NAME|$VALIDATE_SCRIPT"; do
+ name="${pair%%|*}"
+ file="${pair#*|}"
+ existing_id="$(
+ python3 -c '
import json,sys
name=sys.argv[1]
-data=json.loads(sys.stdin.read() or "{}")
-scripts=data.get("scripts") or []
-for s in scripts:
+for s in json.loads(sys.stdin.read() or "[]"):
if s.get("name")==name:
print(s.get("id") or "")
break
' "$name" <<<"$scripts_json"
- )"
- if [ -n "$existing_id" ]; then
- echo "Updating Fleet script $name (id $existing_id)..."
- fleet_request PATCH "/api/latest/fleet/scripts/${existing_id}" \
- -F "script=@${file};filename=${name}" >/dev/null
- require_ok "Updating $name"
- else
- echo "Creating Fleet script $name..."
- fleet_request POST /api/latest/fleet/scripts \
- -F "team_id=${FLEET_TEAM_ID}" \
- -F "script=@${file};filename=${name}" >/dev/null
- require_ok "Creating $name"
- fi
-}
-
-if [ "$SKIP_SCRIPTS" -eq 0 ]; then
- echo
- upload_or_replace_script "$ENABLE_UPDATES_SCRIPT_NAME" "$ENABLE_UPDATES_SCRIPT"
- upload_or_replace_script "$CONFIGURE_S3_SCRIPT_NAME" "$S3_SCRIPT"
- upload_or_replace_script "$VALIDATE_SCRIPT_NAME" "$VALIDATE_SCRIPT"
+ )"
+ if [ -n "$existing_id" ]; then
+ echo "Updating Fleet script $name (id $existing_id)..."
+ fleet_request PATCH "/api/latest/fleet/scripts/${existing_id}" \
+ -F "script=@${file};filename=${name}" >/dev/null
+ require_ok "Updating $name" "$SCRIPTS_HINT"
+ else
+ echo "Creating Fleet script $name..."
+ fleet_request POST /api/latest/fleet/scripts \
+ -F "${FLEET_TEAM_PARAM}=${FLEET_TEAM_ID}" \
+ -F "script=@${file};filename=${name}" >/dev/null
+ require_ok "Creating $name" "$SCRIPTS_HINT"
+ fi
+ done
fi
+# find_beacon_title prints the id of this team's Beacon software title, or
+# nothing. Fleet names the title after the last part of the package identifier
+# ("endpoint"), so match on the bundle identifier or the package file name.
+find_beacon_title() {
+ local titles_json
+ titles_json="$(fleet_list_all "/api/latest/fleet/software/titles?$(team_query)&available_for_install=true&packages_only=true" "software_titles" "$SOFTWARE_HINT")"
+ python3 -c '
+import json, re, sys
+pkg_id = sys.argv[1]
+matches = []
+for t in json.loads(sys.stdin.read() or "[]"):
+ pkgs = list(t.get("packages") or [])
+ if t.get("software_package"):
+ pkgs.append(t["software_package"])
+ if t.get("bundle_identifier") == pkg_id or any(
+ re.fullmatch(r"BeaconEndpointAgent-.+\.pkg", p.get("name") or "") for p in pkgs
+ ):
+ matches.append(t.get("id"))
+if len(matches) > 1:
+ sys.stderr.write("More than one software title on this team looks like Beacon: ids %s.\n" % ", ".join(str(m) for m in matches))
+ sys.stderr.write("Delete the extra titles in Fleet, then rerun this helper.\n")
+ sys.exit(3)
+if matches:
+ print(matches[0])
+' "$PKG_IDENTIFIER" <<<"$titles_json"
+}
+
+title_id=""
if [ "$SKIP_SOFTWARE" -eq 0 ]; then
echo
echo "Looking for an existing Beacon software title on this team..."
- titles_json="$(fleet_json GET "/api/latest/fleet/software/titles?team_id=${FLEET_TEAM_ID}&available_for_install=true&query=${SOFTWARE_QUERY}")"
- require_ok "Listing software titles"
- title_id="$(
- python3 -c '
-import json,sys
-data=json.loads(sys.stdin.read() or "{}")
-titles=data.get("software_titles") or []
-needles=("beacon", "asymptote")
-for t in titles:
- blob=" ".join(str(t.get(k) or "") for k in ("name","display_name")).lower()
- if any(n in blob for n in needles):
- print(t.get("id") or "")
- break
-' <<<"$titles_json"
- )"
-
- form=(
- -F "team_id=${FLEET_TEAM_ID}"
- -F "software=@${PKG_PATH}"
- -F "install_script=<${INSTALL_SCRIPT}"
- -F "uninstall_script=<${UNINSTALL_SCRIPT}"
- -F "self_service=false"
- -F "automatic_install=${FLEET_AUTOMATIC_INSTALL}"
- )
+ title_id="$(find_beacon_title)"
- if [ -n "$title_id" ]; then
- echo "Replacing package on software title $title_id..."
- fleet_request PATCH "/api/latest/fleet/software/titles/${title_id}/package" "${form[@]}" >/dev/null
- require_ok "Updating Beacon software package"
- else
+ if [ -z "$title_id" ]; then
echo "Uploading ${PKG_PATH##*/} as a custom package (this can take several minutes)..."
echo "If you self-host Fleet, the server stores packages in S3 and load-balancer timeouts should be at least 5 minutes."
- fleet_request POST /api/latest/fleet/software/package "${form[@]}" >/dev/null
- require_ok "Uploading Beacon software package"
- title_id="$(json_get software_package title_id <"$WORK_DIR/http-body")"
+ fleet_request POST /api/latest/fleet/software/package \
+ -F "${FLEET_TEAM_PARAM}=${FLEET_TEAM_ID}" \
+ -F "software=@${PKG_PATH}" \
+ -F "install_script=<${INSTALL_SCRIPT}" \
+ -F "uninstall_script=<${UNINSTALL_SCRIPT}" \
+ --form-string "pre_install_query=${PRE_INSTALL_QUERY}" \
+ -F "self_service=false" >/dev/null
+ if [ "$FLEET_HTTP_STATUS" = "409" ]; then
+ # Fleet before 4.90 allows one package per title; another run got there first.
+ echo "Fleet already has a Beacon package on this team; updating it instead."
+ title_id="$(find_beacon_title)"
+ if [ -z "$title_id" ]; then
+ require_ok "Uploading Beacon software package" "$SOFTWARE_HINT"
+ fi
+ else
+ require_ok "Uploading Beacon software package" "$SOFTWARE_HINT"
+ title_id="$(json_get software_package title_id <"$WORK_DIR/http-body")"
+ if [ -z "$title_id" ]; then
+ title_id="$(find_beacon_title)"
+ fi
+ if [ -n "$title_id" ]; then
+ # Fleet only accepts display_name when updating a package (4.77 and later).
+ fleet_request PATCH "/api/latest/fleet/software/titles/${title_id}/package" \
+ -F "${FLEET_TEAM_PARAM}=${FLEET_TEAM_ID}" \
+ --form-string "display_name=${SOFTWARE_DISPLAY_NAME}" >/dev/null
+ case "$FLEET_HTTP_STATUS" in
+ 2*) ;;
+ *) echo "Warning: could not set the display name (HTTP $FLEET_HTTP_STATUS); Fleet will list the package as \"endpoint\"." >&2 ;;
+ esac
+ fi
+ echo "Beacon software title id: ${title_id:-uploaded}"
+ PKG_UPLOADED=1
+ fi
+ fi
+
+ if [ -n "$title_id" ] && [ -z "${PKG_UPLOADED:-}" ]; then
+ fleet_json GET "/api/latest/fleet/software/titles/${title_id}?$(team_query)" >"$WORK_DIR/title.json"
+ require_ok "Reading Beacon software title $title_id" "$SOFTWARE_HINT"
+ # Print the fields that differ, one per line. A PATCH that changes anything
+ # other than self_service cancels pending installs, so send only changes.
+ changed="$(
+ python3 -c '
+import json, sys
+title_path, pkg_sha, install_path, uninstall_path, pre_query, display = sys.argv[1:7]
+title = (json.load(open(title_path)) or {}).get("software_title") or {}
+pkgs = title.get("packages") or []
+if len(pkgs) > 1:
+ sys.stderr.write("Software title %s has %d packages. Delete all but one in Fleet (Software > the Beacon title), then rerun this helper.\n" % (title.get("id"), len(pkgs)))
+ sys.exit(3)
+pkg = title.get("software_package") or (pkgs[0] if pkgs else {})
+def same(a, b):
+ return (a or "").strip() == (b or "").strip()
+if (pkg.get("hash_sha256") or "") != pkg_sha:
+ print("software")
+if not same(pkg.get("install_script"), open(install_path).read()):
+ print("install_script")
+if not same(pkg.get("uninstall_script"), open(uninstall_path).read()):
+ print("uninstall_script")
+if not same(pkg.get("pre_install_query"), pre_query):
+ print("pre_install_query")
+if "display_name" in pkg and not same(pkg.get("display_name"), display):
+ print("display_name")
+if pkg.get("self_service"):
+ print("self_service")
+' "$WORK_DIR/title.json" "$PKG_SHA" "$INSTALL_SCRIPT" "$UNINSTALL_SCRIPT" "$PRE_INSTALL_QUERY" "$SOFTWARE_DISPLAY_NAME"
+ )"
+ if [ -z "$changed" ]; then
+ echo "Beacon software title $title_id is already up to date."
+ else
+ form=(-F "${FLEET_TEAM_PARAM}=${FLEET_TEAM_ID}")
+ while IFS= read -r field; do
+ case "$field" in
+ software) form+=(-F "software=@${PKG_PATH}") ;;
+ install_script) form+=(-F "install_script=<${INSTALL_SCRIPT}") ;;
+ uninstall_script) form+=(-F "uninstall_script=<${UNINSTALL_SCRIPT}") ;;
+ pre_install_query) form+=(--form-string "pre_install_query=${PRE_INSTALL_QUERY}") ;;
+ display_name) form+=(--form-string "display_name=${SOFTWARE_DISPLAY_NAME}") ;;
+ self_service) form+=(-F "self_service=false") ;;
+ esac
+ done <<<"$changed"
+ echo "Updating software title $title_id: $(printf '%s' "$changed" | tr '\n' ' ')"
+ fleet_request PATCH "/api/latest/fleet/software/titles/${title_id}/package" "${form[@]}" >/dev/null
+ require_ok "Updating Beacon software package" "$SOFTWARE_HINT"
+ fi
+ echo "Beacon software title id: $title_id"
fi
- echo "Beacon software title id: ${title_id:-uploaded}"
fi
-create_query() {
- local name="$1"
- local description="$2"
- local sql="$3"
- local existing
- local queries_json
- queries_json="$(fleet_json GET "/api/latest/fleet/queries?team_id=${FLEET_TEAM_ID}")"
- if [ "$FLEET_HTTP_STATUS" != "200" ]; then
- echo "Skipping query '$name' (could not list queries; HTTP $FLEET_HTTP_STATUS)"
- return 0
+if [ "$SKIP_POLICIES" -eq 0 ]; then
+ echo
+ if [ -z "$title_id" ]; then
+ title_id="$(find_beacon_title)"
fi
- existing="$(
- python3 -c '
+ policies_json="$(fleet_list_all "/api/latest/fleet/teams/${FLEET_TEAM_ID}/policies" "policies" "$POLICIES_HINT")"
+
+ # Fleet's own automatic-install policy for a .pkg checks the apps table for a
+ # bundle identifier. Beacon installs no .app, so that policy never passes.
+ legacy_ids=""
+ if [ -n "$title_id" ]; then
+ legacy_ids="$(
+ python3 -c '
+import json, sys
+title_id, pkg_id = int(sys.argv[1]), sys.argv[2]
+legacy_query = "SELECT 1 FROM apps WHERE bundle_identifier = %s;" % ("\x27" + pkg_id + "\x27")
+for p in json.loads(sys.stdin.read() or "[]"):
+ install = p.get("install_software") or {}
+ if install.get("software_title_id") == title_id and (p.get("query") or "").strip() == legacy_query:
+ print("%s\t%s" % (p.get("id"), p.get("name")))
+' "$title_id" "$PKG_IDENTIFIER" <<<"$policies_json"
+ )"
+ fi
+
+ want_automation="$FLEET_AUTOMATIC_INSTALL"
+ if [ -n "$legacy_ids" ]; then
+ echo "Fleet's automatic-install policy for Beacon checks for an app bundle that Beacon"
+ echo "does not install, so it never passes:"
+ printf '%s\n' "$legacy_ids" | sed 's/^/ /'
+ echo "\"$INSTALLED_POLICY_NAME\" checks the package receipt instead and will carry the automatic install."
+ want_automation="true"
+ fi
+ if [ "$want_automation" = "true" ] && [ -z "$title_id" ]; then
+ echo "Warning: no Beacon software title on this team, so automatic install cannot be attached to \"$INSTALLED_POLICY_NAME\"." >&2
+ want_automation="false"
+ fi
+
+ for entry in "${BEACON_POLICIES[@]}"; do
+ IFS='|' read -r pname psql pdesc presolution <<<"$entry"
+ ptitle=""
+ if [ "$pname" = "$INSTALLED_POLICY_NAME" ] && [ "$want_automation" = "true" ]; then
+ ptitle="$title_id"
+ fi
+ beacon_sql "$psql" >"$WORK_DIR/policy.sql"
+ # Print "create", "same", or "update <id>", and write the request body. A
+ # policy edit clears its results and re-arms its automation, so an
+ # unchanged policy is left alone.
+ action="$(
+ NAME="$pname" DESC="$pdesc" RESOLUTION="$presolution" TITLE="$ptitle" \
+ python3 -c '
+import json, os, sys
+policies = json.loads(sys.stdin.read() or "[]")
+body_path, sql_path = sys.argv[1], sys.argv[2]
+want = {
+ "name": os.environ["NAME"],
+ "query": open(sql_path).read().strip(),
+ "description": os.environ["DESC"],
+ "resolution": os.environ["RESOLUTION"],
+ "platform": "darwin",
+ "critical": False,
+}
+title = os.environ.get("TITLE") or ""
+existing = next((p for p in policies if p.get("name") == want["name"]), None)
+body = dict(want)
+if title:
+ body["software_title_id"] = int(title)
+if existing is None:
+ json.dump(body, open(body_path, "w"))
+ print("create")
+ raise SystemExit
+differs = any((existing.get(k) or "").strip() != v for k, v in want.items() if isinstance(v, str))
+differs = differs or bool(existing.get("critical")) != want["critical"]
+current_title = (existing.get("install_software") or {}).get("software_title_id")
+if title and current_title != int(title):
+ differs = True
+elif not title:
+ # Never remove an automation someone attached; leave the field unset.
+ body.pop("software_title_id", None)
+ if current_title:
+ sys.stderr.write("Note: \"%s\" already installs software title %s automatically; leaving that in place.\n" % (want["name"], current_title))
+json.dump(body, open(body_path, "w"))
+print("update %s" % existing.get("id") if differs else "same")
+' "$WORK_DIR/policy.json" "$WORK_DIR/policy.sql" <<<"$policies_json"
+ )"
+ case "$action" in
+ create)
+ echo "Creating policy \"$pname\"..."
+ fleet_json POST "/api/latest/fleet/teams/${FLEET_TEAM_ID}/policies" --data @"$WORK_DIR/policy.json" >/dev/null
+ require_ok "Creating policy $pname" "$POLICIES_HINT"
+ ;;
+ update\ *)
+ echo "Updating policy \"$pname\" (id ${action#update })..."
+ fleet_json PATCH "/api/latest/fleet/teams/${FLEET_TEAM_ID}/policies/${action#update }" --data @"$WORK_DIR/policy.json" >/dev/null
+ require_ok "Updating policy $pname" "$POLICIES_HINT"
+ ;;
+ same)
+ echo "Policy \"$pname\" is already up to date."
+ ;;
+ esac
+ done
+
+ if [ -n "$legacy_ids" ]; then
+ if yes_no "Delete the old automatic-install policy now that \"$INSTALLED_POLICY_NAME\" replaces it?" y; then
+ ids_json="$(printf '%s\n' "$legacy_ids" | cut -f1 | python3 -c 'import json,sys; print(json.dumps({"ids": [int(l) for l in sys.stdin.read().split()]}))')"
+ fleet_json POST "/api/latest/fleet/teams/${FLEET_TEAM_ID}/policies/delete" --data "$ids_json" >/dev/null
+ require_ok "Deleting the old automatic-install policy" "$POLICIES_HINT"
+ echo "Deleted: $(printf '%s\n' "$legacy_ids" | cut -f2 | tr '\n' ' ')"
+ fi
+ fi
+fi
+
+if [ "$SKIP_REPORTS" -eq 0 ]; then
+ echo
+ fleet_json GET "/api/latest/fleet/queries?$(team_query)&page=0&per_page=1" >/dev/null
+ if [ "$FLEET_HTTP_STATUS" != "200" ]; then
+ echo "Skipping reports (could not list saved queries; HTTP $FLEET_HTTP_STATUS)"
+ else
+ queries_json="$(fleet_list_all "/api/latest/fleet/queries?$(team_query)" "queries|reports")"
+ for entry in "${BEACON_REPORTS[@]}"; do
+ IFS='|' read -r qname qsql qdesc <<<"$entry"
+ existing="$(
+ python3 -c '
import json,sys
name=sys.argv[1]
-data=json.loads(sys.stdin.read() or "{}")
-for q in data.get("queries") or []:
+for q in json.loads(sys.stdin.read() or "[]"):
if q.get("name")==name:
print(q.get("id") or "")
break
-' "$name" <<<"$queries_json"
- )"
- NAME="$name" DESC="$description" SQL="$sql" TEAM="$FLEET_TEAM_ID" \
- python3 -c '
+' "$qname" <<<"$queries_json"
+ )"
+ beacon_sql "$qsql" >"$WORK_DIR/query.sql"
+ NAME="$qname" DESC="$qdesc" TEAM="$FLEET_TEAM_ID" TEAM_PARAM="$FLEET_TEAM_PARAM" \
+ python3 -c '
import json,os,sys
json.dump({
"name": os.environ["NAME"],
"description": os.environ["DESC"],
- "query": os.environ["SQL"],
+ "query": open(sys.argv[1]).read().strip(),
"platform": "darwin",
"observer_can_run": True,
- "team_id": int(os.environ["TEAM"]),
+ os.environ["TEAM_PARAM"]: int(os.environ["TEAM"]),
}, sys.stdout)
-' >"$WORK_DIR/query.json"
- if [ -n "$existing" ]; then
- echo "Updating query $name (id $existing)..."
- fleet_json PATCH "/api/latest/fleet/queries/${existing}" --data @"$WORK_DIR/query.json" >/dev/null
- require_ok "Updating query $name"
- else
- echo "Creating query $name..."
- fleet_json POST /api/latest/fleet/queries --data @"$WORK_DIR/query.json" >/dev/null
- require_ok "Creating query $name"
+' "$WORK_DIR/query.sql" >"$WORK_DIR/query.json"
+ if [ -n "$existing" ]; then
+ echo "Updating report $qname (id $existing)..."
+ fleet_json PATCH "/api/latest/fleet/queries/${existing}" --data @"$WORK_DIR/query.json" >/dev/null
+ require_ok "Updating report $qname"
+ else
+ echo "Creating report $qname..."
+ fleet_json POST /api/latest/fleet/queries --data @"$WORK_DIR/query.json" >/dev/null
+ require_ok "Creating report $qname"
+ fi
+ done
fi
-}
-
-if [ "$SKIP_QUERIES" -eq 0 ]; then
- echo
- create_query "Beacon install state" \
- "Whether /opt/beacon/bin/beacon is present." \
- "SELECT CASE WHEN COUNT(*) = 0 THEN 'not_installed' ELSE 'installed' END AS beacon_install_state FROM file WHERE path = '/opt/beacon/bin/beacon';"
- create_query "Beacon collector health" \
- "launchd state for the Beacon endpoint collector." \
- "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';"
- create_query "Beacon S3 forwarder health" \
- "launchd state for the Vector S3 forwarder." \
- "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 s3_vector_forwarder_health FROM launchd WHERE label = 'com.beacon.endpoint.s3-forwarder';"
- create_query "Beacon S3 forwarding configured" \
- "Whether the Vector S3 environment file exists." \
- "SELECT CASE WHEN COUNT(*) = 0 THEN 'not_configured' ELSE 'configured' END AS s3_vector_forwarding_state FROM file WHERE path = '/Library/Application Support/Beacon/Forwarders/s3-vector.env';"
fi
cat <<EOF
Done. Next steps in Fleet
-------------------------
-1. Scope the Beacon software package to a pilot label of Apple Silicon Macs.
- Custom packages cannot target "All teams".
+1. Scope the Beacon Endpoint Agent package to a pilot label of Apple Silicon
+ Macs. Custom packages cannot target "All teams". The package's pre-install
+ query skips Intel Macs.
2. Confirm fleetd was deployed with scripts enabled (default when using Fleet
MDM; otherwise --enable-scripts).
-3. Install Beacon from Host details > Software, or wait for automatic install
- if you enabled it.
+3. Install Beacon from Host > Software > Library, or let the "$INSTALLED_POLICY_NAME"
+ policy install it if you turned on automatic install.
4. After the package is installed, run these scripts on the same hosts, in order:
$ENABLE_UPDATES_SCRIPT_NAME
$CONFIGURE_S3_SCRIPT_NAME
$VALIDATE_SCRIPT_NAME
Do not attach S3 setup as the package post-install script: Fleet uninstalls
the package if post-install fails.
-5. On a Mac, confirm:
- sudo launchctl print system/com.beacon.endpoint.collector
- sudo launchctl print system/com.beacon.endpoint.updater
- sudo launchctl print system/com.beacon.endpoint.s3-forwarder
+5. Watch the "Beacon:" policies. Each one passes only when that part of Beacon is
+ healthy on the host.
6. S3 objects appear under:
s3://$BEACON_S3_BUCKET/$BEACON_S3_PREFIX/runtime/date=YYYY-MM-DD/
s3://$BEACON_S3_BUCKET/$BEACON_S3_PREFIX/inventory/date=YYYY-MM-DD/
@@ -821,5 +1349,5 @@ Done. Next steps in Fleet
IAM for the writer: s3:PutObject on arn:aws:s3:::$BEACON_S3_BUCKET/$BEACON_S3_PREFIX/*
If you use GitOps, re-apply this helper after the next GitOps run or fold the
-package, scripts, and \$FLEET_SECRET_* variables into your GitOps repo.
+package, scripts, policies, and \$FLEET_SECRET_* variables into your GitOps repo.
EOF
diff --git a/examples/fleet/test/fake_fleet.py b/examples/fleet/test/fake_fleet.py
new file mode 100755
index 00000000..ebc4cc01
--- /dev/null
+++ b/examples/fleet/test/fake_fleet.py
@@ -0,0 +1,328 @@
+#!/usr/bin/env python3
+"""A small stateful stand-in for the Fleet REST API, for testing
+configure-beacon-macos-s3.sh without a Fleet server.
+
+It implements only the endpoints the helper calls, keeps state across requests
+so a second helper run sees what the first one created, and appends one JSON
+line per request to --log so a test can assert on exactly what was sent.
+
+Scenario files (--fixture) seed the state and can force responses:
+
+ {
+ "version": "4.92.0",
+ "me": {"user": {...}},
+ "teams": [...],
+ "titles": [{"id": 42, "name": "endpoint", "bundle_identifier": "...",
+ "software_package": {...}, "packages": [...]}],
+ "title_page_size": 1, # force small title pages to exercise paging
+ "policies": [...],
+ "scripts": [...],
+ "queries": [...],
+ "conflict_on_upload": false, # answer POST /software/package with 409
+ "overrides": {"PUT /api/latest/fleet/spec/secret_variables": [403, {"message": "forbidden"}]}
+ }
+
+Like Fleet 4.82+, a request that names both team_id and fleet_id gets a 400.
+"""
+
+import argparse
+import email.parser
+import email.policy
+import hashlib
+import json
+import os
+import re
+import sys
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+PKG_ID = "ai.asymptote.beacon.endpoint"
+
+
+class State:
+ def __init__(self, fixture, pkg_path):
+ self.lock = threading.Lock()
+ self.fixture = fixture
+ self.version = fixture.get("version", "4.92.0")
+ self.me = fixture.get("me") or {
+ "user": {"name": "Admin", "email": "[email protected]", "global_role": "admin", "teams": []}
+ }
+ self.teams = fixture.get("teams") or [{"id": 7, "name": "Pilot"}]
+ self.titles = fixture.get("titles") or []
+ self.title_page_size = fixture.get("title_page_size")
+ self.policies = fixture.get("policies") or []
+ self.scripts = fixture.get("scripts") or []
+ self.queries = fixture.get("queries") or []
+ self.overrides = fixture.get("overrides") or {}
+ self.conflict_on_upload = bool(fixture.get("conflict_on_upload"))
+ self.secrets = {}
+ self.next_id = 1000
+ self.pkg_path = pkg_path
+
+ def new_id(self):
+ self.next_id += 1
+ return self.next_id
+
+
+def parse_multipart(content_type, body):
+ raw = b"Content-Type: " + content_type.encode() + b"\r\n\r\n" + body
+ msg = email.parser.BytesParser(policy=email.policy.HTTP).parsebytes(raw)
+ fields = {}
+ for part in msg.iter_parts():
+ name = part.get_param("name", header="content-disposition")
+ filename = part.get_param("filename", header="content-disposition")
+ data = part.get_payload(decode=True) or b""
+ if filename is not None:
+ entry = {"filename": filename, "sha256": hashlib.sha256(data).hexdigest(), "size": len(data)}
+ if len(data) < 65536:
+ try:
+ entry["content"] = data.decode("utf-8")
+ except UnicodeDecodeError:
+ pass
+ fields[name] = entry
+ else:
+ fields[name] = data.decode("utf-8")
+ return fields
+
+
+def page(items, query, forced_size=None):
+ p = int((query.get("page") or ["0"])[0])
+ size = forced_size or int((query.get("per_page") or ["100"])[0])
+ chunk = items[p * size:(p + 1) * size]
+ return chunk, {"has_next_results": (p + 1) * size < len(items), "has_previous_results": p > 0}
+
+
+def title_summary(t):
+ out = {k: v for k, v in t.items() if k not in ("detail_packages",)}
+ return out
+
+
+class Handler(BaseHTTPRequestHandler):
+ server_version = "fake-fleet"
+
+ def log_message(self, *args):
+ pass
+
+ def reply(self, status, obj=None, raw=None, content_type="application/json"):
+ body = raw if raw is not None else json.dumps(obj if obj is not None else {}).encode()
+ self.send_response(status)
+ self.send_header("Content-Type", content_type)
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ def handle_any(self, method):
+ st = self.server.state
+ url = urlparse(self.path)
+ path = url.path
+ query = parse_qs(url.query)
+ length = int(self.headers.get("Content-Length") or 0)
+ body = self.rfile.read(length) if length else b""
+ ctype = self.headers.get("Content-Type") or ""
+ record = {"method": method, "path": path, "query": query}
+ form = None
+ js = None
+ if ctype.startswith("multipart/form-data"):
+ form = parse_multipart(ctype, body)
+ record["form"] = form
+ elif body:
+ try:
+ js = json.loads(body)
+ except ValueError:
+ js = None
+ record["json"] = js
+ with open(self.server.log_path, "a") as fh:
+ fh.write(json.dumps(record) + "\n")
+
+ names = set(query) | set(form or {}) | (set(js) if isinstance(js, dict) else set())
+ if "team_id" in names and "fleet_id" in names:
+ return self.reply(400, {"message": "Specify only one of team_id or fleet_id"})
+
+ key = "%s %s" % (method, path)
+ if key in st.overrides:
+ status, obj = st.overrides[key]
+ return self.reply(status, obj)
+
+ with st.lock:
+ return self.route(st, method, path, query, form, js)
+
+ def route(self, st, method, path, query, form, js):
+ if method == "GET" and path == "/manifest.json":
+ data = open(st.pkg_path, "rb").read()
+ name = os.path.basename(st.pkg_path)
+ version = re.sub(r"^BeaconEndpointAgent-(.*)-arm64\.pkg$", r"\1", name)
+ base = "http://%s:%d" % self.server.server_address[:2]
+ return self.reply(200, {
+ "version": version,
+ "artifacts": {"darwin_arm64": {"url": "%s/%s" % (base, name), "sha256": hashlib.sha256(data).hexdigest()}},
+ })
+ if method == "GET" and path == "/" + os.path.basename(st.pkg_path):
+ return self.reply(200, raw=open(st.pkg_path, "rb").read(), content_type="application/octet-stream")
+
+ if not path.startswith("/api/latest/fleet/"):
+ return self.reply(404, {"message": "not found"})
+ rest = path[len("/api/latest/fleet/"):]
+
+ if method == "GET" and rest == "version":
+ return self.reply(200, {"version": st.version})
+ if method == "GET" and rest == "me":
+ return self.reply(200, st.me)
+ if method == "GET" and rest == "teams":
+ items, _ = page(st.teams, query)
+ return self.reply(200, {"teams": items})
+
+ if method == "PUT" and rest == "spec/secret_variables":
+ for s in (js or {}).get("secrets") or []:
+ st.secrets[s["name"]] = s["value"]
+ return self.reply(200, {})
+
+ if method == "GET" and rest == "scripts":
+ items, meta = page(st.scripts, query)
+ return self.reply(200, {"scripts": items, "meta": meta})
+ if method == "POST" and rest == "scripts":
+ script = form["script"]
+ sid = st.new_id()
+ st.scripts.append({"id": sid, "name": script["filename"], "content": script.get("content", "")})
+ return self.reply(200, {"script_id": sid})
+ m = re.fullmatch(r"scripts/(\d+)", rest)
+ if method == "PATCH" and m:
+ for s in st.scripts:
+ if s["id"] == int(m.group(1)):
+ s["content"] = form["script"].get("content", "")
+ return self.reply(200, {"script_id": s["id"]})
+ return self.reply(404, {"message": "script not found"})
+
+ if method == "GET" and rest == "software/titles":
+ items, meta = page(st.titles, query, st.title_page_size)
+ return self.reply(200, {"software_titles": [title_summary(t) for t in items], "count": len(st.titles), "meta": meta})
+ m = re.fullmatch(r"software/titles/(\d+)", rest)
+ if method == "GET" and m:
+ for t in st.titles:
+ if t["id"] == int(m.group(1)):
+ detail = dict(t)
+ detail["packages"] = t.get("detail_packages") or t.get("packages") or []
+ return self.reply(200, {"software_title": detail})
+ return self.reply(404, {"message": "title not found"})
+ if method == "POST" and rest == "software/package":
+ if st.conflict_on_upload:
+ return self.reply(409, {"message": "already has an installer available"})
+ software = form["software"]
+ tid = st.new_id()
+ pkg = {
+ "name": software["filename"],
+ "hash_sha256": software["sha256"],
+ "install_script": form.get("install_script", ""),
+ "uninstall_script": form.get("uninstall_script", ""),
+ "pre_install_query": form.get("pre_install_query", ""),
+ "display_name": "",
+ "self_service": form.get("self_service") == "true",
+ "title_id": tid,
+ }
+ st.titles.append({"id": tid, "name": "endpoint", "bundle_identifier": PKG_ID, "software_package": pkg})
+ return self.reply(200, {"software_package": {"title_id": tid, "installer_id": st.new_id()}})
+ m = re.fullmatch(r"software/titles/(\d+)/package", rest)
+ if method == "PATCH" and m:
+ for t in st.titles:
+ if t["id"] == int(m.group(1)):
+ if len(t.get("detail_packages") or []) > 1 and "installer_id" not in form:
+ return self.reply(400, {"message": "installer_id is required when the title has multiple packages"})
+ pkg = t.setdefault("software_package", {})
+ for k in ("install_script", "uninstall_script", "pre_install_query", "display_name"):
+ if k in form:
+ pkg[k] = form[k]
+ if "self_service" in form:
+ pkg["self_service"] = form["self_service"] == "true"
+ if "software" in form:
+ pkg["name"] = form["software"]["filename"]
+ pkg["hash_sha256"] = form["software"]["sha256"]
+ return self.reply(200, {"software_package": pkg})
+ return self.reply(404, {"message": "title not found"})
+
+ m = re.fullmatch(r"teams/(\d+)/policies", rest)
+ if method == "GET" and m:
+ items, _ = page(st.policies, query)
+ return self.reply(200, {"policies": items})
+ if method == "POST" and m:
+ pol = {k: v for k, v in (js or {}).items() if k != "software_title_id"}
+ pol["id"] = st.new_id()
+ if (js or {}).get("software_title_id"):
+ pol["install_software"] = {"software_title_id": js["software_title_id"], "name": "endpoint"}
+ st.policies.append(pol)
+ return self.reply(200, {"policy": pol})
+ m = re.fullmatch(r"teams/(\d+)/policies/(\d+)", rest)
+ if method == "PATCH" and m:
+ for pol in st.policies:
+ if pol["id"] == int(m.group(2)):
+ for k, v in (js or {}).items():
+ if k == "software_title_id":
+ if v is None:
+ pol.pop("install_software", None)
+ else:
+ pol["install_software"] = {"software_title_id": v, "name": "endpoint"}
+ else:
+ pol[k] = v
+ return self.reply(200, {"policy": pol})
+ return self.reply(404, {"message": "policy not found"})
+ m = re.fullmatch(r"teams/(\d+)/policies/delete", rest)
+ if method == "POST" and m:
+ ids = set((js or {}).get("ids") or [])
+ before = len(st.policies)
+ st.policies[:] = [p for p in st.policies if p["id"] not in ids]
+ return self.reply(200, {"deleted": before - len(st.policies)})
+
+ if method == "GET" and rest == "queries":
+ items, meta = page(st.queries, query)
+ return self.reply(200, {"queries": items, "meta": meta})
+ if method == "POST" and rest == "queries":
+ q = dict(js or {})
+ q["id"] = st.new_id()
+ st.queries.append(q)
+ return self.reply(200, {"query": q})
+ m = re.fullmatch(r"queries/(\d+)", rest)
+ if method == "PATCH" and m:
+ for q in st.queries:
+ if q["id"] == int(m.group(1)):
+ q.update(js or {})
+ return self.reply(200, {"query": q})
+ return self.reply(404, {"message": "query not found"})
+
+ return self.reply(404, {"message": "not found: %s %s" % (method, path)})
+
+ def do_GET(self):
+ self.handle_any("GET")
+
+ def do_POST(self):
+ self.handle_any("POST")
+
+ def do_PUT(self):
+ self.handle_any("PUT")
+
+ def do_PATCH(self):
+ self.handle_any("PATCH")
+
+
+def main():
+ ap = argparse.ArgumentParser()
+ ap.add_argument("--fixture", required=True)
+ ap.add_argument("--log", required=True)
+ ap.add_argument("--port-file", required=True)
+ ap.add_argument("--pkg", required=True)
+ args = ap.parse_args()
+ fixture = json.load(open(args.fixture))
+ server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+ server.state = State(fixture, args.pkg)
+ server.log_path = args.log
+ open(args.log, "a").close()
+ tmp = args.port_file + ".tmp"
+ with open(tmp, "w") as fh:
+ fh.write(str(server.server_address[1]))
+ os.replace(tmp, args.port_file)
+ try:
+ server.serve_forever()
+ except KeyboardInterrupt:
+ pass
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/examples/fleet/test/test-configure-beacon-macos-s3.sh b/examples/fleet/test/test-configure-beacon-macos-s3.sh
new file mode 100755
index 00000000..ca2e7b0d
--- /dev/null
+++ b/examples/fleet/test/test-configure-beacon-macos-s3.sh
@@ -0,0 +1,337 @@
+#!/bin/sh
+# Tests for examples/fleet/configure-beacon-macos-s3.sh. Each case starts
+# fake_fleet.py on a free local port, runs the real helper against it with real
+# curl, and checks the requests the fake recorded. No Fleet server, GitHub, or
+# AWS is involved; the package is a small stand-in file.
+set -eu
+
+ROOT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")/../../.." && pwd)"
+HELPER="$ROOT_DIR/examples/fleet/configure-beacon-macos-s3.sh"
+FAKE="$ROOT_DIR/examples/fleet/test/fake_fleet.py"
+SQL_DIR="$ROOT_DIR/packaging/macos/fleet"
+TMP_DIR="$(mktemp -d)"
+FAKE_PID=""
+
+cleanup() {
+ if [ -n "$FAKE_PID" ]; then
+ kill "$FAKE_PID" 2>/dev/null || true
+ fi
+ rm -rf "$TMP_DIR"
+}
+trap cleanup EXIT INT TERM
+
+command -v python3 >/dev/null 2>&1 || { echo "python3 is required for the Fleet helper tests" >&2; exit 1; }
+command -v bash >/dev/null 2>&1 || { echo "bash is required for the Fleet helper tests" >&2; exit 1; }
+
+fail() {
+ echo "FAIL: $*" >&2
+ if [ -n "${CASE_DIR:-}" ] && [ -f "$CASE_DIR/err" ]; then
+ echo "--- helper stderr ---" >&2
+ tail -n 20 "$CASE_DIR/err" >&2
+ fi
+ exit 1
+}
+
+PKG="$TMP_DIR/BeaconEndpointAgent-9.9.9-arm64.pkg"
+printf 'stand-in beacon package 9.9.9\n' >"$PKG"
+PKG_NEW="$TMP_DIR/BeaconEndpointAgent-9.9.10-arm64.pkg"
+printf 'stand-in beacon package 9.9.10\n' >"$PKG_NEW"
+KEYS="AWS_ACCESS_KEY_ID=AKIAEXAMPLEKEY0000000 AWS_SECRET_ACCESS_KEY=example-secret-value"
+
+# start_fake NAME FIXTURE_JSON
+start_fake() {
+ CASE_DIR="$TMP_DIR/$1"
+ mkdir -p "$CASE_DIR"
+ printf '%s\n' "$2" >"$CASE_DIR/fixture.json"
+ LOG="$CASE_DIR/requests.jsonl"
+ MARK=0
+ python3 "$FAKE" --fixture "$CASE_DIR/fixture.json" --log "$LOG" --port-file "$CASE_DIR/port" --pkg "$PKG" &
+ FAKE_PID=$!
+ tries=0
+ while [ ! -s "$CASE_DIR/port" ]; do
+ tries=$((tries + 1))
+ [ "$tries" -lt 50 ] || fail "fake Fleet did not start"
+ sleep 0.1
+ done
+ PORT="$(cat "$CASE_DIR/port")"
+}
+
+stop_fake() {
+ kill "$FAKE_PID" 2>/dev/null || true
+ wait "$FAKE_PID" 2>/dev/null || true
+ FAKE_PID=""
+}
+
+# run_helper [NAME=VALUE...] -- [helper args...]: run the helper non-interactively
+# against the current fake, with stdout and stderr captured. Sets STATUS.
+run_helper() {
+ set -- "$@"
+ envs=""
+ while [ "$#" -gt 0 ] && [ "$1" != "--" ]; do
+ envs="$envs $1"
+ shift
+ done
+ [ "$#" -gt 0 ] && shift
+ set +e
+ # shellcheck disable=SC2086
+ env -i PATH="$PATH" HOME="$CASE_DIR" TMPDIR="$CASE_DIR" \
+ FLEET_URL="http://127.0.0.1:$PORT" FLEET_TOKEN=test-token FLEET_TEAM_ID=7 \
+ BEACON_S3_BUCKET=example-security-logs AWS_REGION=us-west-2 BEACON_S3_PREFIX=beacon-prod \
+ BEACON_UPDATE_MANIFEST_URL="http://127.0.0.1:$PORT/manifest.json" \
+ $envs bash "$HELPER" --yes "$@" </dev/null >"$CASE_DIR/out" 2>"$CASE_DIR/err"
+ STATUS=$?
+ set -e
+}
+
+mark() {
+ MARK="$(wc -l <"$LOG" | tr -d ' ')"
+}
+
+# logq EXPR: evaluate a Python expression over the requests recorded since the
+# last mark. R is the list of requests; see the helpers below.
+logq() {
+ python3 - "$LOG" "${MARK:-0}" "$SQL_DIR" "$1" <<'PY'
+import json, os, sys
+log, mark, sql_dir, expr = sys.argv[1], int(sys.argv[2]), sys.argv[3], sys.argv[4]
+R = [json.loads(line) for line in open(log).read().splitlines()[mark:]]
+def sql(name):
+ return open(os.path.join(sql_dir, name + ".sql")).read().strip()
+def req(method, path):
+ return [r for r in R if r["method"] == method and r["path"] == path]
+def writes():
+ return [r for r in R if r["method"] != "GET"]
+def form(r):
+ return r.get("form") or {}
+def body(r):
+ return r.get("json") or {}
+def keys(r):
+ return set(form(r)) | set(body(r) if isinstance(body(r), dict) else {})
+sys.exit(0 if eval(expr) else 1)
+PY
+}
+
+expect() {
+ logq "$1" || fail "$2"
+}
+
+expect_status() {
+ case "$1" in
+ ok) [ "$STATUS" -eq 0 ] || fail "$2 (exit $STATUS)" ;;
+ fail) [ "$STATUS" -ne 0 ] || fail "$2 (exit 0)" ;;
+ *) [ "$STATUS" -eq "$1" ] || fail "$2 (exit $STATUS, want $1)" ;;
+ esac
+}
+
+expect_err() {
+ grep -q -- "$1" "$CASE_DIR/err" || fail "$2"
+}
+
+POLICY_FILES="
+Beacon: installed=policies/beacon-installed
+Beacon: collector running=policies/collector-running
+Beacon: S3 forwarder running=policies/s3-forwarder-running
+Beacon: S3 forwarding configured=policies/s3-forwarding-configured
+Beacon: inventory heartbeat within 4 days=policies/inventory-heartbeat-recent"
+
+# The helper embeds the SQL because it is downloaded on its own; it must match
+# the shipped files exactly.
+awk '/^beacon_sql\(\) \{/{p=1} p{print} p&&/^\}/{exit}' "$HELPER" >"$TMP_DIR/beacon_sql.sh"
+for name in policies/beacon-installed policies/collector-running policies/s3-forwarder-running \
+ policies/s3-forwarding-configured policies/inventory-heartbeat-recent queries/beacon-version \
+ queries/collector-service-health queries/s3-vector-forwarder-health \
+ queries/s3-vector-forwarding-configured queries/inventory-heartbeat-age-seconds; do
+ bash -c '. "$1"; beacon_sql "$2"' _ "$TMP_DIR/beacon_sql.sh" "$name" | cmp -s - "$SQL_DIR/$name.sql" ||
+ fail "SQL embedded in the helper for $name differs from packaging/macos/fleet/$name.sql"
+done
+for policy in "$SQL_DIR"/policies/*.sql; do
+ name="policies/$(basename "$policy" .sql)"
+ printf '%s\n' "$POLICY_FILES" | grep -q "=$name\$" || fail "$name is not created by the helper"
+done
+
+# --- Fresh team: upload, display name, policies, reports -------------------
+start_fake fresh '{}'
+run_helper $KEYS --
+expect_status ok "fresh run should succeed"
+expect 'len(req("GET", "/manifest.json")) == 1 and len(req("GET", "/BeaconEndpointAgent-9.9.9-arm64.pkg")) == 1' \
+ "fresh run should download the package named by the manifest"
+expect 'len(req("POST", "/api/latest/fleet/software/package")) == 1' "fresh run should upload the package"
+expect 'all(form(r)["software"]["filename"] == "BeaconEndpointAgent-9.9.9-arm64.pkg" and form(r)["team_id"] == "7" and form(r)["self_service"] == "false" and "cpu_type LIKE '"'"'arm64%'"'"'" in form(r)["pre_install_query"] and "display_name" not in form(r) for r in req("POST", "/api/latest/fleet/software/package"))' \
+ "upload should carry the Apple Silicon pre-install query and leave display_name for the update"
+expect 'any(form(r).get("display_name") == "Beacon Endpoint Agent" and "software" not in form(r) for r in R if r["method"] == "PATCH" and r["path"].endswith("/package"))' \
+ "fresh run should set the display name with a PATCH that sends no file"
+expect 'not any("automatic_install" in keys(r) for r in R)' "no request should send automatic_install"
+expect 'not any("fleet_id" in keys(r) or "fleet_id" in r["query"] for r in R)' "requests should name the team as team_id only"
+expect 'len(req("POST", "/api/latest/fleet/teams/7/policies")) == 5' "fresh run should create five policies"
+while IFS='=' read -r pname pfile; do
+ [ -n "$pname" ] || continue
+ expect "any(body(r).get(\"name\") == \"$pname\" and body(r).get(\"query\") == sql(\"$pfile\") and body(r).get(\"platform\") == \"darwin\" for r in req(\"POST\", \"/api/latest/fleet/teams/7/policies\"))" \
+ "policy '$pname' should be created from $pfile.sql"
+done <<EOF
+$POLICY_FILES
+EOF
+expect 'not any("software_title_id" in body(r) for r in req("POST", "/api/latest/fleet/teams/7/policies"))' \
+ "without automatic install no policy should install software"
+expect 'any(body(r).get("query") == sql("queries/collector-service-health") for r in req("POST", "/api/latest/fleet/queries"))' \
+ "reports should use the fixed collector health query"
+expect 'len(req("POST", "/api/latest/fleet/queries")) == 5' "fresh run should create five reports"
+expect 'sorted(s["name"] for s in body(req("PUT", "/api/latest/fleet/spec/secret_variables")[0])["secrets"]) == ["FLEET_SECRET_BEACON_AWS_ACCESS_KEY_ID", "FLEET_SECRET_BEACON_AWS_SECRET_ACCESS_KEY"]' \
+ "fresh run should store the access key pair as secret variables"
+expect 'any(form(r)["script"]["filename"] == "beacon-configure-s3-forwarding.sh" and "$FLEET_SECRET_BEACON_AWS_ACCESS_KEY_ID" in form(r)["script"]["content"] and "example-secret-value" not in form(r)["script"]["content"] for r in req("POST", "/api/latest/fleet/scripts"))' \
+ "the S3 script should reference the secret variables, never the key itself"
+
+# Rerun against the same server: nothing about the package or policies changed.
+mark
+run_helper $KEYS --
+expect_status ok "rerun should succeed"
+expect 'not any(r["path"].startswith("/api/latest/fleet/software/") for r in writes())' \
+ "rerun with the same package should not touch the software title"
+expect 'not any("/policies" in r["path"] for r in writes())' "rerun should leave unchanged policies alone"
+
+# A new build replaces only the package file.
+mark
+run_helper $KEYS -- --pkg "$PKG_NEW"
+expect_status ok "rerun with a new package should succeed"
+expect 'len([r for r in writes() if r["path"].startswith("/api/latest/fleet/software/")]) == 1' \
+ "a new build should be a single package update"
+expect 'any(sorted(form(r)) == ["software", "team_id"] and form(r)["software"]["filename"] == "BeaconEndpointAgent-9.9.10-arm64.pkg" for r in writes() if r["path"].endswith("/package"))' \
+ "a new build should send only the file"
+expect 'not req("POST", "/api/latest/fleet/software/package")' "a new build should not add a second package"
+
+# Turning on automatic install attaches the title to the receipt policy.
+mark
+run_helper $KEYS FLEET_AUTOMATIC_INSTALL=true -- --pkg "$PKG_NEW"
+expect_status ok "automatic install run should succeed"
+expect 'len([r for r in writes() if "/policies" in r["path"]]) == 1' "only the installed policy should change"
+expect 'any(body(r).get("name") == "Beacon: installed" and isinstance(body(r).get("software_title_id"), int) for r in writes() if r["method"] == "PATCH" and "/policies/" in r["path"])' \
+ "automatic install should attach software_title_id to 'Beacon: installed'"
+stop_fake
+
+# --- Existing title on a second page, plus Fleet's old auto-install policy ---
+start_fake legacy '{
+ "title_page_size": 1,
+ "titles": [
+ {"id": 41, "name": "Other", "bundle_identifier": "com.example.other", "software_package": {"name": "Other.pkg"}},
+ {"id": 42, "name": "endpoint", "bundle_identifier": "ai.asymptote.beacon.endpoint",
+ "software_package": {"name": "BeaconEndpointAgent-1.0.0-arm64.pkg", "hash_sha256": "old", "install_script": "",
+ "uninstall_script": "", "pre_install_query": "", "display_name": "", "self_service": false}}
+ ],
+ "policies": [
+ {"id": 5, "name": "Beacon: installed", "query": "SELECT 1;", "platform": "darwin"},
+ {"id": 6, "name": "endpoint (pkg) automatic install", "query": "SELECT 1 FROM apps WHERE bundle_identifier = '"'"'ai.asymptote.beacon.endpoint'"'"';",
+ "install_software": {"software_title_id": 42}}
+ ]
+}'
+run_helper $KEYS -- --pkg "$PKG"
+expect_status ok "update of an existing title should succeed"
+expect 'len([r for r in req("GET", "/api/latest/fleet/software/titles") if r["query"].get("page") == ["1"]]) >= 1' \
+ "title lookup should read the second page"
+expect 'not req("POST", "/api/latest/fleet/software/package")' "an existing title should not get a second package"
+expect 'any(set(form(r)) == {"team_id", "software", "install_script", "uninstall_script", "pre_install_query", "display_name"} for r in req("PATCH", "/api/latest/fleet/software/titles/42/package"))' \
+ "an outdated title should get every differing field in one update"
+expect 'any(body(r).get("software_title_id") == 42 for r in req("PATCH", "/api/latest/fleet/teams/7/policies/5"))' \
+ "the old automatic install should move to 'Beacon: installed'"
+expect 'any(body(r).get("ids") == [6] for r in req("POST", "/api/latest/fleet/teams/7/policies/delete"))' \
+ "Fleet's never-passing automatic-install policy should be deleted"
+stop_fake
+
+# --- Credential handling -----------------------------------------------------
+start_fake credentials '{}'
+run_helper --
+expect_status fail "--yes without AWS keys should fail"
+expect_err 'BEACON_AWS_CREDENTIAL_MODE=none' "the error should name the none mode"
+expect 'len(R) == 0' "a missing-key run should make no requests"
+
+mark
+run_helper BEACON_AWS_CREDENTIAL_MODE=none -- --pkg "$PKG"
+expect_status ok "credential mode none should succeed"
+expect 'not req("PUT", "/api/latest/fleet/spec/secret_variables")' "mode none should store no secrets"
+expect 'any(form(r)["script"]["filename"] == "beacon-configure-s3-forwarding.sh" and "export AWS_ACCESS_KEY_ID" not in form(r)["script"]["content"] for r in req("POST", "/api/latest/fleet/scripts"))' \
+ "mode none should upload an S3 script that sets no AWS keys"
+
+mark
+run_helper BEACON_AWS_CREDENTIAL_MODE=bogus --
+expect_status 2 "an unknown credential mode should exit 2"
+expect_err "must be 'keys' or 'none'" "the error should list the valid modes"
+expect 'len(R) == 0' "an unknown mode should make no requests"
+
+mark
+run_helper $KEYS FLEET_AUTOMATIC_INSTALL=yes --
+expect_status 2 "an invalid FLEET_AUTOMATIC_INSTALL should exit 2"
+expect 'len(R) == 0' "an invalid FLEET_AUTOMATIC_INSTALL should make no requests"
+
+mark
+run_helper AWS_ACCESS_KEY_ID=ASIAEXAMPLEKEY000000 AWS_SECRET_ACCESS_KEY=example-secret-value --
+expect_status fail "a temporary key without a session token should fail"
+expect_err 'needs AWS_SESSION_TOKEN' "the error should ask for the session token"
+expect 'len(R) == 0' "a temporary key without a token should make no requests"
+
+mark
+run_helper AWS_ACCESS_KEY_ID=ASIAEXAMPLEKEY000000 AWS_SECRET_ACCESS_KEY=example-secret-value AWS_SESSION_TOKEN=example-token -- --pkg "$PKG" --skip-policies --skip-reports
+expect_status ok "a temporary key with a session token should succeed"
+expect_err 'expires' "temporary credentials should come with an expiry warning"
+expect 'any("FLEET_SECRET_BEACON_AWS_SESSION_TOKEN" in [s["name"] for s in body(r)["secrets"]] for r in req("PUT", "/api/latest/fleet/spec/secret_variables"))' \
+ "the session token should be stored as a secret variable"
+stop_fake
+
+# --- Dry runs make no network calls ------------------------------------------
+start_fake dryrun '{}'
+run_helper -- --dry-run
+expect_status ok "dry run should succeed without keys or a package"
+grep -q 'FLEET_SECRET_BEACON_AWS_ACCESS_KEY_ID' "$CASE_DIR/out" || fail "dry run should preview the secret placeholders"
+run_helper -- --dry-run --skip-software
+expect_status ok "the documented dry run should succeed"
+expect 'len(R) == 0' "dry runs should not call Fleet or download the package"
+stop_fake
+
+# --- Roles and errors ----------------------------------------------------------
+# /version answers 200 first, so this also checks that a refused call made inside
+# $(...) is seen as refused rather than inheriting the earlier status.
+start_fake badtoken '{"overrides": {"GET /api/latest/fleet/me": [401, {"message": "Authentication required"}]}}'
+run_helper $KEYS -- --pkg "$PKG"
+expect_status fail "a rejected token should stop the helper"
+expect_err 'rejected the API token' "a 401 should say the token was rejected"
+expect 'len(writes()) == 0' "a rejected token should stop before any write"
+stop_fake
+
+start_fake secrets403 '{
+ "me": {"user": {"name": "M", "email": "[email protected]", "global_role": "maintainer", "teams": []}},
+ "overrides": {"PUT /api/latest/fleet/spec/secret_variables": [403, {"message": "forbidden"}]}
+}'
+run_helper $KEYS -- --pkg "$PKG"
+expect_status fail "a refused secret write should fail"
+expect_err 'global admin, maintainer, or GitOps' "a refused secret write should explain the global role"
+if grep -q 'Custom software packages' "$CASE_DIR/err"; then
+ fail "a refused secret write should not blame software packages"
+fi
+stop_fake
+
+start_fake teamrole '{"me": {"user": {"name": "T", "email": "[email protected]", "global_role": null, "teams": [{"id": 7, "role": "maintainer"}]}}}'
+run_helper $KEYS -- --pkg "$PKG"
+expect_status fail "a team maintainer token cannot store secrets"
+expect_err 'cannot write Fleet secret variables' "the preflight should name the secret-variable limit"
+expect 'len(writes()) == 0' "the role preflight should stop before any write"
+mark
+run_helper BEACON_AWS_CREDENTIAL_MODE=none -- --pkg "$PKG" --skip-reports
+expect_status ok "a team maintainer can run the helper when it stores no secrets"
+stop_fake
+
+start_fake norole '{"me": {"user": {"name": "O", "email": "[email protected]", "global_role": "observer", "teams": []}}}'
+run_helper BEACON_AWS_CREDENTIAL_MODE=none -- --pkg "$PKG"
+expect_status fail "an observer token should be refused"
+expect_err 'cannot manage team 7' "the preflight should name the team"
+expect 'len(writes()) == 0' "the team preflight should stop before any write"
+stop_fake
+
+start_fake multipkg '{
+ "titles": [{"id": 42, "name": "endpoint", "bundle_identifier": "ai.asymptote.beacon.endpoint",
+ "software_package": {"name": "BeaconEndpointAgent-1.0.0-arm64.pkg", "hash_sha256": "a"},
+ "detail_packages": [{"name": "BeaconEndpointAgent-1.0.0-arm64.pkg"}, {"name": "BeaconEndpointAgent-1.1.0-arm64.pkg"}]}]
+}'
+run_helper $KEYS -- --pkg "$PKG" --skip-scripts
+expect_status fail "a title with two packages should stop the helper"
+expect_err 'has 2 packages' "the error should say how many packages the title has"
+expect 'not any(r["path"].startswith("/api/latest/fleet/software/") for r in writes())' \
+ "the helper should not guess which package to update"
+stop_fake
+
+echo "Fleet helper checks passed"
diff --git a/packaging/macos/README.md b/packaging/macos/README.md
index 499d5e4d..96f3ef76 100644
--- a/packaging/macos/README.md
+++ b/packaging/macos/README.md
@@ -24,6 +24,7 @@ The package builder assembles this payload:
/opt/beacon/jamf/claude/gcs/install-forwarder.sh
/opt/beacon/jamf/claude/gcs/run-forwarder.sh
/opt/beacon/jamf/claude/gcs/repair-hooks-and-forwarder.sh
+/opt/beacon/fleet/policies/*.sql
/opt/beacon/fleet/queries/*.sql
/opt/beacon/fleet/scripts/*.sh
```
@@ -586,6 +587,33 @@ The customer-facing walkthrough is
Do not put S3 or self-update enablement in the Fleet package post-install
script: a non-zero post-install causes Fleet to uninstall the package.
+What the helper sets up on the team:
+
+- The package, named "Beacon Endpoint Agent", with a pre-install query that
+ skips Intel Macs. Fleet otherwise names the title "endpoint", after the last
+ part of the package identifier. On a rerun the helper finds the title by its
+ bundle identifier and updates only what changed, so a new release replaces
+ the package instead of adding a second one.
+- The AWS keys as Fleet secret variables. Only a global admin, maintainer, or
+ GitOps user can write those, so the API token needs a global admin or
+ maintainer role. With `BEACON_AWS_CREDENTIAL_MODE=none` the helper stores no
+ keys and a team admin or maintainer token is enough.
+- The host scripts for self-updates, S3 forwarding, and validation.
+- The five policies from `policies/` and five reports from `queries/`.
+- Automatic install, when `FLEET_AUTOMATIC_INSTALL=true`, as an install-software
+ automation on the "Beacon: installed" policy. Fleet's own automatic install
+ for a `.pkg` checks the `apps` table for a bundle identifier, and Beacon
+ installs no `.app`, so that policy never passes. The helper replaces one it
+ finds.
+
+The helper stops before writing anything when the token lacks a needed role,
+when AWS keys are missing under `--yes` (set `BEACON_AWS_CREDENTIAL_MODE=none`
+to deliver them another way), or when a key starting with `ASIA` has no session
+token. Temporary credentials work but stop uploads when they expire, so use a
+long-lived IAM user key for the writer. `--dry-run` makes no network calls.
+Run `sh examples/fleet/test/test-configure-beacon-macos-s3.sh` to exercise the
+helper against a local stand-in for the Fleet API.
+
Fleet scripts are installed under `/opt/beacon/fleet/scripts`:
```text
@@ -612,6 +640,10 @@ install.sh argument 11: Splunk insecure TLS skip verify
install.sh argument 12: Splunk CA file
```
+Fleet runs scripts without arguments. To change these values, upload a short
+wrapper script that sets the matching `BEACON_*` variables, for example
+`BEACON_ENDPOINT_HARNESSES=claude,codex,gemini /opt/beacon/fleet/scripts/install.sh`.
+
Fleet repair script positional arguments:
```text
@@ -635,13 +667,36 @@ For GitHub Copilot CLI, deploy the same `COPILOT_OTEL_ENABLED=true` and
Beacon package. Copilot is not part of the default Fleet harness argument and
Beacon does not write Copilot shell profiles or `~/.copilot/config.json`.
-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,
-harness configuration, Wazuh validation, and launchd health.
+Fleet osquery files come in two kinds:
+
+- `packaging/macos/fleet/policies/*.sql` are Fleet policies. Each returns a row
+ only when that part of Beacon is healthy, so the policy fails on a host where
+ it is not. Each also passes on Intel Macs, where the Apple Silicon package
+ does not apply.
+- `packaging/macos/fleet/queries/*.sql` are reports (saved queries). Each
+ returns one row per host with a status value. Do not use them as policies:
+ they return a row on every host, and Fleet passes a policy whenever its query
+ returns a row.
+
+Policies built from the `queries/` files before this change always passed,
+and three of them read a `pid` column that osquery's `launchd` table does not
+have. Replace them with the files in `policies/`.
+
+Policies:
+
+- `beacon-installed.sql`: package receipt and `/opt/beacon/bin/beacon` present
+- `collector-running.sql`: `beacon-otelcol` running as root
+- `s3-forwarder-running.sql`: Vector running with the Beacon S3 config
+- `s3-forwarding-configured.sql`: S3 env file, Vector config, and LaunchDaemon present
+- `inventory-heartbeat-recent.sql`: inventory heartbeat written in the last 96
+ hours. The job runs every 6 hours but skips runs while the Mac sleeps, so a
+ shorter window fails laptops after a weekend.
+
+Reports:
- `beacon-version.sql`
- `collector-service-health.sql`
+- `inventory-heartbeat-age-seconds.sql`
- `last-event-age-seconds.sql`
- `configured-harnesses.sql`
- `runtime-log-writable.sql`
@@ -650,14 +705,8 @@ harness configuration, Wazuh validation, and launchd health.
- `s3-vector-forwarder-health.sql`
- `s3-vector-forwarding-configured.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`
-- S3 Vector forwarder health is `running` when S3 forwarding is required
+Run `/opt/beacon/fleet/scripts/validate.sh` for full CLI-level validation of
+status, harness configuration, Wazuh validation, and launchd health.
## Uninstall And Rollback
diff --git a/packaging/macos/pkgbuild.md b/packaging/macos/pkgbuild.md
index 6e6c7912..bc0ad7a8 100644
--- a/packaging/macos/pkgbuild.md
+++ b/packaging/macos/pkgbuild.md
@@ -179,11 +179,12 @@ 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.
+`/opt/beacon/fleet/scripts`. Fleet policies are packaged under
+`/opt/beacon/fleet/policies`: each returns a row only when the host is healthy,
+so it fails on a missing, stopped, stale, or unconfigured endpoint. Reports
+(saved queries) are under `/opt/beacon/fleet/queries` and return one row per
+host; do not use them as policies. Scope `repair.sh` to hosts that fail the
+installed, collector, or heartbeat policies.
Splunk HEC forwarding can be configured with:
@@ -214,5 +215,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
+- Fleet policies pass and Fleet reports show expected values after host detail refresh
diff --git a/packaging/macos/test-endpoint-scripts.sh b/packaging/macos/test-endpoint-scripts.sh
index 3e7e0d66..962a791d 100644
--- a/packaging/macos/test-endpoint-scripts.sh
+++ b/packaging/macos/test-endpoint-scripts.sh
@@ -1083,3 +1083,39 @@ fi
# Safari app-wrapper helper and MDM declaration (packaging/macos/safari). Runs on
# Linux too: the packager and uname are faked.
sh "$ROOT_DIR/packaging/macos/safari/test-safari-packaging.sh"
+
+# Fleet osquery files (packaging/macos/fleet) and the Fleet admin helper
+# (examples/fleet). A Fleet policy passes whenever its query returns a row, so a
+# policy must return nothing on an unhealthy host and must not aggregate.
+FLEET_HELPER="$ROOT_DIR/examples/fleet/configure-beacon-macos-s3.sh"
+bash -n "$FLEET_HELPER"
+for sql in "$ROOT_DIR"/packaging/macos/fleet/queries/*.sql "$ROOT_DIR"/packaging/macos/fleet/policies/*.sql; do
+ if grep -Eiq '(^|[^a-z_])pid([^a-z_]|$)' "$sql"; then
+ echo "$sql reads pid; osquery's launchd table has no pid column" >&2
+ exit 1
+ fi
+done
+for sql in "$ROOT_DIR"/packaging/macos/fleet/policies/*.sql; do
+ if grep -Eiq 'count[[:space:]]*\(' "$sql"; then
+ echo "$sql aggregates, so it returns a row on every host and the policy always passes" >&2
+ exit 1
+ fi
+ if ! head -n 1 "$sql" | grep -q '^SELECT 1'; then
+ echo "$sql should start with SELECT 1 and return a row only when the host is healthy" >&2
+ exit 1
+ fi
+ if ! grep -q "cpu_type LIKE 'arm64%'" "$sql"; then
+ echo "$sql should pass on Intel Macs, where the Apple Silicon package does not apply" >&2
+ exit 1
+ fi
+done
+if grep -q 'automatic_install=' "$FLEET_HELPER"; then
+ echo "the Fleet helper should not use Fleet's automatic install; its .pkg policy never passes" >&2
+ exit 1
+fi
+if grep -q 'query=${SOFTWARE_QUERY}' "$FLEET_HELPER"; then
+ echo "the Fleet helper should find the Beacon title by bundle identifier, not by name" >&2
+ exit 1
+fi
+sh "$ROOT_DIR/examples/fleet/test/test-fleet-sql.sh"
+sh "$ROOT_DIR/examples/fleet/test/test-configure-beacon-macos-s3.sh"