Skip to content

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

Add managed GCS forwarding for macOS

shukieshah9800d090e9b2
diff --git a/README.md b/README.md
index bc4724f9..6f616419 100644
--- a/README.md
+++ b/README.md
@@ -148,7 +148,7 @@ management (SIEM), log aggregation, and object storage destinations.
| Destination | Support path |
| --- | --- |
| [AWS S3](https://docs.asymptotelabs.ai/cli/siem-forwarding-s3) | Vector content pack over local runtime and inventory JSONL using customer-managed AWS credentials |
-| [Google Cloud Storage](https://docs.asymptotelabs.ai/cli/siem-forwarding-gcs) | Vector content pack over local JSONL using customer-managed Google credentials |
+| [Google Cloud Storage](https://docs.asymptotelabs.ai/cli/siem-forwarding-gcs) | Vector content pack and packaged macOS helpers over runtime and inventory JSONL using customer-managed Google credentials |
#### Local
@@ -170,6 +170,12 @@ remain available for CLI installs across supported macOS/Linux architectures.
| [Fleet](https://docs.asymptotelabs.ai/cli/fleet) | macOS package and user-context deployment helpers |
| [Jamf Pro](https://docs.asymptotelabs.ai/cli/jamf) | macOS package, policy scripts, validation, and Extension Attributes |
+The macOS package includes GCS forwarder helpers at
+`/opt/beacon/jamf/claude/gcs/{install-forwarder.sh,run-forwarder.sh,repair-hooks-and-forwarder.sh}`.
+They run bundled Vector as `com.beacon.endpoint.gcs-forwarder`, write runtime
+and inventory objects below one root prefix, and reference an externally
+delivered service-account JSON through `GOOGLE_APPLICATION_CREDENTIALS`.
+
## Dashboard and Local Detection
Beacon includes a local, read-only dashboard for validating endpoint activity
diff --git a/cli/beacon/README.md b/cli/beacon/README.md
index 87234ce9..ad9501bd 100644
--- a/cli/beacon/README.md
+++ b/cli/beacon/README.md
@@ -452,11 +452,19 @@ deployment tooling, not in Beacon endpoint configuration.
```
The GCS pack keeps Beacon as a local JSONL producer and documents forwarding
-`runtime.jsonl` into a Google Cloud Storage bucket with a customer-managed
-Vector host agent. Store Google credentials, service accounts, workload
-identity, bucket IAM, lifecycle rules, retention policies, and encryption
-settings in Google Cloud, Vector, or deployment tooling, not in Beacon endpoint
-configuration.
+`runtime.jsonl` and the sibling `inventory_state.jsonl` into separate
+`runtime/` and `inventory/` folders below one root GCS prefix.
+
+The macOS package includes
+`/opt/beacon/jamf/claude/gcs/{install-forwarder.sh,run-forwarder.sh,repair-hooks-and-forwarder.sh}`
+and runs bundled Vector as `com.beacon.endpoint.gcs-forwarder`. Vector `0.56`
+supports service-account JSON and GCE metadata credentials; on a normal Mac,
+deliver the JSON through MDM or secret tooling to a root-owned path outside
+Beacon-managed directories and reference it with
+`GOOGLE_APPLICATION_CREDENTIALS`. Do not rely on interactive `gcloud` ADC or
+Workload Identity Federation for the launchd service. An endpoint writer with
+`roles/storage.objectCreator` cannot list or read objects, so use a separate
+reader identity for validation.
## Microsoft Sentinel
diff --git a/cli/beacon/cmd/endpoint_destinations.go b/cli/beacon/cmd/endpoint_destinations.go
index e8c03a13..5f79503b 100644
--- a/cli/beacon/cmd/endpoint_destinations.go
+++ b/cli/beacon/cmd/endpoint_destinations.go
@@ -304,8 +304,8 @@ var siemDestinations = []siemDestination{
message: "Beacon endpoint GCS validation event",
print: func(cfg endpointconfig.Config) {
fmt.Println("Expected GCS fields: vendor=beacon product=endpoint-agent destination.type=gcs destination.mode=google_cloud_storage_jsonl")
- fmt.Println(`Confirm delivery with Google Cloud CLI: gcloud storage ls "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/**"`)
- fmt.Println(`Inspect an object with Google Cloud CLI: gcloud storage cat "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/date=<date>/<object>.jsonl.gz" | gzip -dc | grep "Beacon endpoint GCS validation event"`)
+ fmt.Println(`Confirm delivery with Google Cloud CLI: gcloud storage ls "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/runtime/**"`)
+ fmt.Println(`Inspect an object with Google Cloud CLI: gcloud storage cat "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/runtime/date=<date>/<object>.jsonl.gz" | gzip -dc | grep "Beacon endpoint GCS validation event"`)
},
},
},
diff --git a/cli/beacon/cmd/endpoint_destinations_characterization_test.go b/cli/beacon/cmd/endpoint_destinations_characterization_test.go
index 1fe3c868..e465b0c5 100644
--- a/cli/beacon/cmd/endpoint_destinations_characterization_test.go
+++ b/cli/beacon/cmd/endpoint_destinations_characterization_test.go
@@ -107,6 +107,7 @@ func destinationCharCases() []destinationCharCase {
"Expected GCS fields: vendor=beacon product=endpoint-agent destination.type=gcs destination.mode=google_cloud_storage_jsonl",
"gcloud storage ls",
"gcloud storage cat",
+ "${BEACON_GCS_PREFIX}/runtime/",
"Beacon endpoint GCS validation event",
},
},
diff --git a/cli/beacon/internal/endpoint/gcs/gcs_test.go b/cli/beacon/internal/endpoint/gcs/gcs_test.go
index 4a0bcab8..65e57874 100644
--- a/cli/beacon/internal/endpoint/gcs/gcs_test.go
+++ b/cli/beacon/internal/endpoint/gcs/gcs_test.go
@@ -18,6 +18,9 @@ func TestUploadSmokeTestUsesConfiguredPath(t *testing.T) {
if !strings.Contains(got, "/tmp/beacon/runtime.jsonl") {
t.Fatalf("script did not include configured path: %s", got)
}
+ if !strings.Contains(got, "/tmp/beacon/inventory_state.jsonl") {
+ t.Fatalf("script did not include derived inventory path: %s", got)
+ }
if strings.Contains(got, "{{LOG_PATH}}") {
t.Fatalf("script still contains template token: %s", got)
}
@@ -27,6 +30,10 @@ func TestUploadSmokeTestUsesConfiguredPath(t *testing.T) {
"gcloud storage cp",
"gsutil",
"--content-type=\"application/x-ndjson\"",
+ `prefix="${prefix%/runtime}"`,
+ `prefix="${prefix%/inventory}"`,
+ `/runtime/smoke-tests/beacon-runtime-`,
+ `/inventory/smoke-tests/beacon-inventory-`,
"Application Default Credentials",
"validation only",
} {
@@ -69,6 +76,9 @@ func TestInstallPackWritesExpectedFiles(t *testing.T) {
if !strings.Contains(string(vectorConfig), "/tmp/beacon/runtime.jsonl") {
t.Fatalf("generated vector config missing configured log path: %s", vectorConfig)
}
+ if !strings.Contains(string(vectorConfig), "/tmp/beacon/inventory_state.jsonl") {
+ t.Fatalf("generated vector config missing derived inventory log path: %s", vectorConfig)
+ }
info, err = os.Stat(vectorPath)
if err != nil {
t.Fatal(err)
@@ -82,11 +92,14 @@ func TestVectorConfigUsesGCSCloudStorageSinkAndPreservesJSONShape(t *testing.T)
got := mustRead("pack/vector.toml.tmpl")
for _, want := range []string{
`include = ["{{LOG_PATH}}"]`,
+ `include = ["{{INVENTORY_LOG_PATH}}"]`,
`read_from = "end"`,
+ `read_from = "beginning"`,
`. = parse_json!(.message)`,
`type = "gcp_cloud_storage"`,
`bucket = "${BEACON_GCS_BUCKET}"`,
- `key_prefix = "${BEACON_GCS_PREFIX:-beacon/runtime}/date=%F/"`,
+ `key_prefix = "${BEACON_GCS_PREFIX:-beacon}/runtime/date=%F/"`,
+ `key_prefix = "${BEACON_GCS_PREFIX:-beacon}/inventory/date=%F/"`,
`filename_time_format = "%s"`,
`filename_append_uuid = true`,
`filename_extension = "jsonl.gz"`,
@@ -98,11 +111,26 @@ func TestVectorConfigUsesGCSCloudStorageSinkAndPreservesJSONShape(t *testing.T)
`method = "newline_delimited"`,
`max_bytes = 10000000`,
`retry_attempts = 10`,
+ `[sinks.beacon_runtime_gcs.healthcheck]`,
+ `[sinks.beacon_inventory_gcs.healthcheck]`,
+ `enabled = false`,
} {
if !strings.Contains(got, want) {
t.Fatalf("vector config missing %q: %s", want, got)
}
}
+ for _, forbidden := range []string{
+ `.input_tokens =`,
+ `.output_tokens =`,
+ `.cache_read_input_tokens =`,
+ `.cache_creation_input_tokens =`,
+ `.reasoning_output_tokens =`,
+ `.cost_usd =`,
+ } {
+ if strings.Contains(got, forbidden) {
+ t.Fatalf("vector config must preserve canonical gen_ai.usage without parallel field %q", forbidden)
+ }
+ }
}
func TestSampleEventsCoverValidationHookAndOTelShapes(t *testing.T) {
@@ -142,6 +170,7 @@ func TestPackREADMEMentionsGCSSetupAndProductionForwarding(t *testing.T) {
"BEACON_GCS_PREFIX",
"gcloud storage ls",
"gcloud storage cat",
+ "inventory_state.jsonl",
"Beacon endpoint GCS validation event",
"vendor=beacon product=endpoint-agent destination.type=gcs destination.mode=google_cloud_storage_jsonl",
"vector.toml",
@@ -149,6 +178,7 @@ func TestPackREADMEMentionsGCSSetupAndProductionForwarding(t *testing.T) {
"without a Vector wrapper",
"Content Handling",
"/var/log/beacon-agent/runtime.jsonl",
+ "/var/log/beacon-agent/inventory_state.jsonl",
"Beacon does not store Google Cloud credentials",
"encryption",
} {
diff --git a/cli/beacon/internal/endpoint/gcs/pack/README.md b/cli/beacon/internal/endpoint/gcs/pack/README.md
index c10477a8..79a85944 100644
--- a/cli/beacon/internal/endpoint/gcs/pack/README.md
+++ b/cli/beacon/internal/endpoint/gcs/pack/README.md
@@ -1,22 +1,26 @@
# Beacon Endpoint Agent Google Cloud Storage Pack
This pack forwards Beacon endpoint JSONL events into a Google Cloud Storage
-bucket. Beacon still writes one local source of truth: `runtime.jsonl`. Google
-credentials, service accounts, workload identity, bucket IAM, object lifecycle
-rules, retention policies, and encryption stay in Google Cloud, Vector, or
-customer-managed deployment tooling, not in Beacon endpoint configuration.
+bucket. Beacon writes runtime activity to `runtime.jsonl` and configuration
+inventory telemetry to `inventory_state.jsonl`. Google credentials, service
+accounts, workload identity, bucket IAM, object lifecycle rules, retention
+policies, and encryption stay in Google Cloud, Vector, or customer-managed
+deployment tooling, not in Beacon endpoint configuration.
## Prerequisites
- Beacon endpoint installed and writing local JSONL.
-- A Google Cloud Storage bucket for Beacon runtime logs.
-- A service account or workload identity available through Application Default
- Credentials for the process running Vector, `gcloud`, or `gsutil`.
+- A Google Cloud Storage bucket for Beacon runtime and inventory logs.
+- Credentials supported by the process doing the upload. The packaged macOS
+ Vector 0.56 path requires service-account JSON through
+ `GOOGLE_APPLICATION_CREDENTIALS`; `gcloud`/`gsutil` smoke tests may use their
+ own active configuration.
Recommended GCS layout:
```text
gs://example-security-logs/beacon/runtime/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
+gs://example-security-logs/beacon/inventory/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
```
Grant the Vector service identity only the bucket/prefix permissions it needs.
@@ -26,6 +30,11 @@ them. Add viewer, retention, CMEK, or bucket-specific conditional IAM only if
your Google Cloud controls require them. Configure lifecycle, retention,
versioning, audit logs, and encryption in Google Cloud.
+Vector's GCS startup healthcheck requires `storage.objects.get`, which the
+write-only role intentionally lacks. The generated sinks disable that
+healthcheck and rely on upload errors plus remote validation by a separate
+reader identity; this preserves write-only endpoint credentials.
+
## Install
Generate this pack:
@@ -41,11 +50,19 @@ CLI:
- System mode: `/var/log/beacon-agent/runtime.jsonl`
- Custom mode: the value passed with `--log-path`
+The generated Vector config and smoke-test script also use the sibling inventory
+log:
+
+- User mode: `~/.beacon/endpoint/logs/inventory_state.jsonl`
+- System mode: `/var/log/beacon-agent/inventory_state.jsonl`
+- Custom mode: `inventory_state.jsonl` in the same directory as `--log-path`
+
For MDM or managed endpoint deployment, prefer Beacon system mode so your
customer-managed log shipper can tail `/var/log/beacon-agent/runtime.jsonl`
without per-user home directory ACLs.
-The generated `vector.toml` uses the same selected Beacon log path.
+The generated `vector.toml` uses the selected Beacon runtime log path and the
+derived sibling inventory log path.
## One-Shot Smoke Test
@@ -55,7 +72,7 @@ whole file every time.
```bash
export BEACON_GCS_BUCKET="example-security-logs"
-export BEACON_GCS_PREFIX="beacon/runtime"
+export BEACON_GCS_PREFIX="beacon"
./beacon-gcs-pack/gcs-upload-smoke-test.sh
```
@@ -70,46 +87,65 @@ generated runtime state.
Confirm the uploaded object:
```bash
-gcloud storage ls "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/smoke-tests/"
-gcloud storage cat "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/smoke-tests/<object>.jsonl" | grep "Beacon endpoint GCS validation event"
+gcloud storage ls "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/runtime/smoke-tests/"
+gcloud storage cat "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/runtime/smoke-tests/<object>.jsonl" | grep "Beacon endpoint GCS validation event"
```
## Production Forwarding
For production, use the generated Vector config as a customer-managed host-agent
forwarding template. Beacon remains the local JSONL producer; Vector tails
-`runtime.jsonl`, checkpoints file offsets in its `data_dir`, batches Beacon
-events, and writes gzip-compressed newline-delimited JSON objects into Google
-Cloud Storage.
+`runtime.jsonl` and `inventory_state.jsonl`, checkpoints file offsets in its
+`data_dir`, batches Beacon events, and writes gzip-compressed newline-delimited
+JSON objects into Google Cloud Storage.
Install Vector using your normal endpoint management tooling, then copy the
generated config into Vector's config directory. On a macOS system-mode Beacon
-deployment, the generated config tails `/var/log/beacon-agent/runtime.jsonl`:
+deployment, the generated config tails `/var/log/beacon-agent/runtime.jsonl` and
+`/var/log/beacon-agent/inventory_state.jsonl`:
```bash
sudo mkdir -p /etc/vector
sudo cp ./beacon-gcs-pack/vector.toml /etc/vector/beacon-gcs.toml
export BEACON_GCS_BUCKET="example-security-logs"
-export BEACON_GCS_PREFIX="beacon/runtime"
+export BEACON_GCS_PREFIX="beacon"
vector validate /etc/vector/beacon-gcs.toml
vector --config /etc/vector/beacon-gcs.toml
```
In managed deployments, provide `BEACON_GCS_BUCKET`, optional
-`BEACON_GCS_PREFIX`, optional `BEACON_GCS_STORAGE_CLASS`, and any Google
-Application Default Credentials or workload identity settings through the Vector
-service environment, host identity, MDM, or secret tooling. Do not store Google
-Cloud destination secrets in Beacon endpoint configuration.
+`BEACON_GCS_PREFIX`, optional `BEACON_GCS_STORAGE_CLASS`, and a
+`GOOGLE_APPLICATION_CREDENTIALS` path through the Vector service environment,
+MDM, or secret tooling. The signed macOS package pins Vector 0.56, whose GCS sink
+supports service-account JSON or GCE metadata but not external-account Workload
+Identity Federation. Interactive `gcloud auth application-default login`
+credentials are not a reliable root launchd contract. Do not store Google Cloud
+destination secrets in Beacon endpoint configuration.
+
+`BEACON_GCS_PREFIX` is the shared root prefix (for example, `beacon`), not the
+runtime path. The template appends `runtime/` and `inventory/`. For compatibility
+with older smoke-test settings, the generated smoke script normalizes one trailing
+`/runtime` or `/inventory` back to the shared root before uploading.
The Vector template is intentionally simple and expects a Vector version with
the `file` source, `remap` transform, and `gcp_cloud_storage` sink. It parses
each Beacon JSONL line and re-encodes the original Beacon event as NDJSON so GCS
-receives one Beacon event per line, without a Vector wrapper.
+receives one Beacon event per line, without a Vector wrapper. Runtime activity
+is written under `${BEACON_GCS_PREFIX}/runtime/date=.../`; inventory telemetry
+is written under `${BEACON_GCS_PREFIX}/inventory/date=.../`.
+
+When an event contains token or runtime-reported cost attribution, the Vector
+template preserves the canonical nested `gen_ai.usage` payload without adding
+parallel usage fields.
The template uses date-partitioned `key_prefix`, `filename_time_format = "%s"`,
and `filename_append_uuid = true` so production forwarding does not overwrite
previous GCS objects. It also sets `compression = "gzip"`,
`content_encoding = "gzip"`, and `content_type = "application/x-ndjson"`.
+Runtime log forwarding starts at the end of the active log to avoid backfilling
+historical session activity when Vector is first installed. Inventory forwarding
+starts at the beginning of `inventory_state.jsonl` so the first snapshot is not
+missed if the file was created before Vector began watching it.
If you adapt the config or use another forwarder, it should:
@@ -133,8 +169,8 @@ new line. Beacon can write the local validation event, but remote delivery must
be confirmed with Google Cloud tooling:
```bash
-gcloud storage ls "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/**"
-gcloud storage cat "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/date=<date>/<object>.jsonl.gz" | gzip -dc | grep "Beacon endpoint GCS validation event"
+gcloud storage ls "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/runtime/**"
+gcloud storage cat "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/runtime/date=<date>/<object>.jsonl.gz" | gzip -dc | grep "Beacon endpoint GCS validation event"
```
Expected validation fields:
diff --git a/cli/beacon/internal/endpoint/gcs/pack/gcs-upload-smoke-test.sh.tmpl b/cli/beacon/internal/endpoint/gcs/pack/gcs-upload-smoke-test.sh.tmpl
index d5d18511..ef6137af 100644
--- a/cli/beacon/internal/endpoint/gcs/pack/gcs-upload-smoke-test.sh.tmpl
+++ b/cli/beacon/internal/endpoint/gcs/pack/gcs-upload-smoke-test.sh.tmpl
@@ -2,7 +2,8 @@
set -eu
BEACON_LOG="${BEACON_LOG:-{{LOG_PATH}}}"
-BEACON_GCS_PREFIX="${BEACON_GCS_PREFIX:-beacon/runtime}"
+BEACON_INVENTORY_LOG="${BEACON_INVENTORY_LOG:-{{INVENTORY_LOG_PATH}}}"
+BEACON_GCS_PREFIX="${BEACON_GCS_PREFIX:-beacon}"
if [ -z "${BEACON_GCS_BUCKET:-}" ]; then
echo "BEACON_GCS_BUCKET is required." >&2
@@ -15,18 +16,40 @@ if [ ! -r "$BEACON_LOG" ]; then
fi
prefix="${BEACON_GCS_PREFIX%/}"
+case "$prefix" in
+ */runtime)
+ prefix="${prefix%/runtime}"
+ ;;
+ */inventory)
+ prefix="${prefix%/inventory}"
+ ;;
+esac
+[ -n "$prefix" ] || prefix="beacon"
timestamp="$(date -u +%Y%m%dT%H%M%SZ)"
-uri="gs://${BEACON_GCS_BUCKET}/${prefix}/smoke-tests/beacon-runtime-${timestamp}.jsonl"
+runtime_uri="gs://${BEACON_GCS_BUCKET}/${prefix}/runtime/smoke-tests/beacon-runtime-${timestamp}.jsonl"
if command -v gcloud >/dev/null 2>&1; then
- gcloud storage cp "$BEACON_LOG" "$uri" --content-type="application/x-ndjson"
+ gcloud storage cp "$BEACON_LOG" "$runtime_uri" --content-type="application/x-ndjson"
+ if [ -r "$BEACON_INVENTORY_LOG" ]; then
+ inventory_uri="gs://${BEACON_GCS_BUCKET}/${prefix}/inventory/smoke-tests/beacon-inventory-${timestamp}.jsonl"
+ gcloud storage cp "$BEACON_INVENTORY_LOG" "$inventory_uri" --content-type="application/x-ndjson"
+ fi
elif command -v gsutil >/dev/null 2>&1; then
- gsutil -h "Content-Type:application/x-ndjson" cp "$BEACON_LOG" "$uri"
+ gsutil -h "Content-Type:application/x-ndjson" cp "$BEACON_LOG" "$runtime_uri"
+ if [ -r "$BEACON_INVENTORY_LOG" ]; then
+ inventory_uri="gs://${BEACON_GCS_BUCKET}/${prefix}/inventory/smoke-tests/beacon-inventory-${timestamp}.jsonl"
+ gsutil -h "Content-Type:application/x-ndjson" cp "$BEACON_INVENTORY_LOG" "$inventory_uri"
+ fi
else
echo "gcloud or gsutil is required for this smoke test." >&2
exit 2
fi
-echo "Uploaded one-shot Beacon log copy to $uri"
+echo "Uploaded one-shot Beacon runtime log copy to $runtime_uri"
+if [ -n "${inventory_uri:-}" ]; then
+ echo "Uploaded one-shot Beacon inventory log copy to $inventory_uri"
+else
+ echo "Beacon inventory log is not readable yet, skipping optional upload: $BEACON_INVENTORY_LOG"
+fi
echo "Google credentials were resolved by Application Default Credentials or gcloud/gsutil configuration."
echo "This script is for validation only; use vector.toml for production forwarding."
diff --git a/cli/beacon/internal/endpoint/gcs/pack/vector.toml.tmpl b/cli/beacon/internal/endpoint/gcs/pack/vector.toml.tmpl
index efe1c5b0..0e002d6c 100644
--- a/cli/beacon/internal/endpoint/gcs/pack/vector.toml.tmpl
+++ b/cli/beacon/internal/endpoint/gcs/pack/vector.toml.tmpl
@@ -1,9 +1,10 @@
# Beacon Endpoint Agent -> Google Cloud Storage
#
# Run Vector as a customer-managed host agent. Keep Google credentials,
-# service-account bindings, workload identity, bucket IAM, lifecycle, retention,
-# and encryption in Google Cloud or deployment tooling, not in Beacon config.
-# This template relies on Google Application Default Credentials.
+# service-account bindings, bucket IAM, lifecycle, retention, and encryption in
+# Google Cloud or deployment tooling, not in Beacon config. Packaged Vector
+# 0.56 on macOS expects service-account JSON through
+# GOOGLE_APPLICATION_CREDENTIALS; it does not support external-account WIF.
data_dir = "/var/lib/vector/beacon-gcs"
@@ -12,18 +13,61 @@ type = "file"
include = ["{{LOG_PATH}}"]
read_from = "end"
-[transforms.beacon_json]
+[sources.beacon_inventory]
+type = "file"
+include = ["{{INVENTORY_LOG_PATH}}"]
+read_from = "beginning"
+
+[transforms.beacon_runtime_json]
type = "remap"
inputs = ["beacon_runtime"]
source = '''
. = parse_json!(.message)
'''
-[sinks.beacon_gcs]
+[transforms.beacon_inventory_json]
+type = "remap"
+inputs = ["beacon_inventory"]
+source = '''
+. = parse_json!(.message)
+'''
+
+[sinks.beacon_runtime_gcs]
+type = "gcp_cloud_storage"
+inputs = ["beacon_runtime_json"]
+bucket = "${BEACON_GCS_BUCKET}"
+key_prefix = "${BEACON_GCS_PREFIX:-beacon}/runtime/date=%F/"
+filename_time_format = "%s"
+filename_append_uuid = true
+filename_extension = "jsonl.gz"
+compression = "gzip"
+content_encoding = "gzip"
+content_type = "application/x-ndjson"
+storage_class = "${BEACON_GCS_STORAGE_CLASS:-STANDARD}"
+
+[sinks.beacon_runtime_gcs.encoding]
+codec = "json"
+
+[sinks.beacon_runtime_gcs.framing]
+method = "newline_delimited"
+
+[sinks.beacon_runtime_gcs.batch]
+max_bytes = 10000000
+timeout_secs = 300
+
+[sinks.beacon_runtime_gcs.request]
+retry_attempts = 10
+retry_initial_backoff_secs = 1
+retry_max_duration_secs = 300
+
+[sinks.beacon_runtime_gcs.healthcheck]
+enabled = false
+
+[sinks.beacon_inventory_gcs]
type = "gcp_cloud_storage"
-inputs = ["beacon_json"]
+inputs = ["beacon_inventory_json"]
bucket = "${BEACON_GCS_BUCKET}"
-key_prefix = "${BEACON_GCS_PREFIX:-beacon/runtime}/date=%F/"
+key_prefix = "${BEACON_GCS_PREFIX:-beacon}/inventory/date=%F/"
filename_time_format = "%s"
filename_append_uuid = true
filename_extension = "jsonl.gz"
@@ -32,17 +76,20 @@ content_encoding = "gzip"
content_type = "application/x-ndjson"
storage_class = "${BEACON_GCS_STORAGE_CLASS:-STANDARD}"
-[sinks.beacon_gcs.encoding]
+[sinks.beacon_inventory_gcs.encoding]
codec = "json"
-[sinks.beacon_gcs.framing]
+[sinks.beacon_inventory_gcs.framing]
method = "newline_delimited"
-[sinks.beacon_gcs.batch]
+[sinks.beacon_inventory_gcs.batch]
max_bytes = 10000000
timeout_secs = 300
-[sinks.beacon_gcs.request]
+[sinks.beacon_inventory_gcs.request]
retry_attempts = 10
retry_initial_backoff_secs = 1
retry_max_duration_secs = 300
+
+[sinks.beacon_inventory_gcs.healthcheck]
+enabled = false
diff --git a/docs/changelog/cli.mdx b/docs/changelog/cli.mdx
index 78274940..65c6ec6d 100644
--- a/docs/changelog/cli.mdx
+++ b/docs/changelog/cli.mdx
@@ -11,6 +11,12 @@ Stay up to date with the latest changes to the Agent Beacon CLI.
## July 2026
+### Unreleased
+
+- **Packaged GCS forwarding for managed Macs** · Added GCS Jamf helpers under `/opt/beacon/jamf/claude/gcs/` that run bundled Vector as `com.beacon.endpoint.gcs-forwarder` and forward runtime plus inventory JSONL below one root prefix.
+- **Explicit macOS GCS credential contract** · Documented externally delivered service-account JSON referenced by `GOOGLE_APPLICATION_CREDENTIALS`, Vector `0.56` authentication limits, write-only `roles/storage.objectCreator`, and separate reader identities for validation.
+- **Harness-neutral object storage guide** · Consolidated the Claude-specific single-Mac S3 and GCS walkthroughs into one system-mode guide for any configured harness, while keeping provider IAM, credential, and validation details in the dedicated destination references.
+
### v0.0.95 · July 10, 2026
- **Cursor telemetry docs polish** · Fixed punctuation and grammar in the Cursor telemetry support table so local and cloud hook coverage is easier to scan.
diff --git a/docs/cli/gcs.mdx b/docs/cli/gcs.mdx
index 91146221..64ff6918 100644
--- a/docs/cli/gcs.mdx
+++ b/docs/cli/gcs.mdx
@@ -5,7 +5,7 @@ description: "Generate Google Cloud Storage forwarding content and validation ev
## Forwarding Command
-Use `beacon endpoint gcs` to generate Google Cloud Storage forwarding content for Beacon endpoint events. The generated pack keeps Beacon as a local JSONL producer and helps your customer-managed Vector agent upload `runtime.jsonl` to a GCS bucket as gzip-compressed NDJSON.
+Use `beacon endpoint gcs` to generate Google Cloud Storage forwarding content for Beacon endpoint events. The generated pack keeps Beacon as a local JSONL producer and helps your customer-managed Vector agent upload runtime and inventory JSONL to a GCS bucket as gzip-compressed NDJSON.
Beacon does not store Google Cloud credentials, service accounts, workload identity settings, bucket IAM, lifecycle rules, retention policies, or encryption settings. Keep those values in Google Cloud, Vector, endpoint-management policy, or deployment tooling.
@@ -80,7 +80,10 @@ beacon endpoint gcs print-config --log-path /path/to/runtime.jsonl
beacon endpoint gcs install-pack --output ./beacon-gcs-pack
```
-The pack includes setup instructions, a one-shot GCS upload smoke-test script, a Vector `gcp_cloud_storage` forwarding template, and sample Beacon endpoint events.
+The pack includes setup instructions, a one-shot GCS upload smoke-test script,
+a Vector `gcp_cloud_storage` forwarding template, and sample Beacon endpoint
+events. Current templates keep a root prefix and write runtime activity and
+inventory snapshots below separate `runtime/` and `inventory/` folders.
### Examples
@@ -147,7 +150,7 @@ The validation command writes the local event only. Confirm remote delivery with
```text
gcloud storage ls "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/**"
-gcloud storage cat "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/date=<date>/<object>.jsonl.gz" | gzip -dc | grep "Beacon endpoint GCS validation event"
+gcloud storage cat "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/runtime/date=<date>/<object>.jsonl.gz" | gzip -dc | grep "Beacon endpoint GCS validation event"
```
Expected validation fields:
@@ -164,6 +167,37 @@ vendor=beacon product=endpoint-agent destination.type=gcs destination.mode=googl
| `--system` | Use system endpoint paths and launch daemon |
| `--log-path <path>` | Runtime JSONL log path |
+## Packaged macOS forwarding
+
+The signed macOS endpoint package includes:
+
+```text
+/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
+```
+
+The helper requires:
+
+- `BEACON_GCS_BUCKET`
+- optional root `BEACON_GCS_PREFIX`, default `beacon`
+- optional `BEACON_GCS_STORAGE_CLASS`, default `STANDARD`
+- `GOOGLE_APPLICATION_CREDENTIALS`, pointing to an externally delivered
+ service-account JSON file outside Beacon-managed directories
+
+It writes `gcs-vector.toml` and a root-owned `gcs-vector.env` below
+`/Library/Application Support/Beacon/Forwarders`, then starts
+`com.beacon.endpoint.gcs-forwarder`. The env file stores the credential path,
+not the credential JSON.
+
+Vector `0.56` supports service-account JSON and GCE metadata credentials. On
+managed Macs, do not depend on interactive `gcloud` Application Default
+Credentials or Workload Identity Federation for the launchd service.
+
+Use a write-only service account with `roles/storage.objectCreator` for the
+endpoint and a separate reader identity for validation. An object creator cannot
+list or read the objects it successfully uploads.
+
## Related
<Columns cols={2}>
diff --git a/docs/cli/s3.mdx b/docs/cli/s3.mdx
index e1ebf923..722e133a 100644
--- a/docs/cli/s3.mdx
+++ b/docs/cli/s3.mdx
@@ -153,7 +153,7 @@ The validation command writes the local event only. Confirm remote delivery with
```text
aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/" --recursive --region "$AWS_REGION"
-aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/date=<date>/<object>.jsonl.gz" - --region "$AWS_REGION" | gzip -dc | grep "Beacon endpoint S3 validation event"
+aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/date=<date>/<object>.jsonl.gz" - --region "$AWS_REGION" | gzip -dc | grep "Beacon endpoint S3 validation event"
```
Expected validation fields:
diff --git a/docs/concepts/core-concepts.mdx b/docs/concepts/core-concepts.mdx
index a79a32b0..8e0f8355 100644
--- a/docs/concepts/core-concepts.mdx
+++ b/docs/concepts/core-concepts.mdx
@@ -117,15 +117,15 @@ The **Rapid7 content pack** is Beacon's generated setup guidance, NDJSON upload
## AWS S3 Content Pack
-The **AWS S3 content pack** is Beacon's generated setup guidance, AWS CLI smoke-test script, Vector `aws_s3` forwarding template, and sample events for shipping local Beacon JSONL into an S3 bucket. The pack reads the runtime log; Beacon itself does not store AWS credentials, bucket policies, lifecycle rules, or encryption settings.
+The **AWS S3 content pack** is Beacon's generated setup guidance, AWS CLI smoke-test script, Vector `aws_s3` forwarding template, and sample events for shipping local Beacon JSONL into an S3 bucket. The current Vector path reads runtime and inventory JSONL and writes them below separate folders under one root prefix; Beacon itself does not store AWS credentials, bucket policies, lifecycle rules, or encryption settings.
## Google Cloud Storage Content Pack
-The **Google Cloud Storage content pack** is Beacon's generated setup guidance, GCS upload smoke-test script, Vector `gcp_cloud_storage` forwarding template, and sample events for shipping local Beacon JSONL into a GCS bucket. The pack reads the runtime log; Beacon itself does not store Google Cloud credentials, service accounts, workload identity settings, bucket IAM, lifecycle rules, retention policies, or encryption settings.
+The **Google Cloud Storage content pack** is Beacon's generated setup guidance, GCS upload smoke-test script, Vector `gcp_cloud_storage` forwarding template, and sample events for shipping local Beacon JSONL into a GCS bucket. The current Vector path reads runtime and inventory JSONL and writes them below separate folders under one root prefix; Beacon itself does not store Google Cloud credentials, service accounts, bucket IAM, lifecycle rules, retention policies, or encryption settings.
## Vector Forwarding
-**Vector forwarding** means a customer-managed Vector host agent tails Beacon's local `runtime.jsonl`, parses each JSON line, and delivers events to a downstream destination such as Sumo Logic, Rapid7 InsightIDR, Falcon LogScale, AWS CloudWatch Logs, AWS S3, or Google Cloud Storage. Vector owns checkpointing, batching, retries, credentials, and destination-specific settings.
+**Vector forwarding** means a customer-managed Vector host agent tails Beacon's local JSONL streams, parses each JSON line, and delivers events to a downstream destination such as Sumo Logic, Rapid7 InsightIDR, Falcon LogScale, AWS CloudWatch Logs, AWS S3, or Google Cloud Storage. Vector owns checkpointing, batching, retries, credentials, and destination-specific settings.
## Customer-Managed Forwarding
diff --git a/docs/concepts/vector-forwarding.mdx b/docs/concepts/vector-forwarding.mdx
index 42acab6b..0748a897 100644
--- a/docs/concepts/vector-forwarding.mdx
+++ b/docs/concepts/vector-forwarding.mdx
@@ -24,11 +24,15 @@ flowchart LR
Vector is a lightweight observability pipeline agent. A Vector configuration connects **sources** that collect events, **transforms** that parse or reshape them, and **sinks** that deliver them to downstream systems. In Beacon forwarding, Vector is the customer-managed shipper that tails Beacon's local JSONL audit log, parses each line into the original Beacon event, batches records, retries delivery, and writes them to destinations such as AWS S3, Google Cloud Storage, AWS CloudWatch Logs, Sumo Logic, Rapid7 InsightIDR, or CrowdStrike Falcon LogScale.
-Beacon uses Vector as a handoff pattern, not as a hosted dependency. Beacon continues to write one local source of truth at `runtime.jsonl`. Vector runs beside Beacon only when you choose to forward that file into your own storage, SIEM, data lake, or log platform.
+Beacon uses Vector as a handoff pattern, not as a hosted dependency. Beacon writes
+runtime activity to `runtime.jsonl` and metadata-only inventory snapshots to the
+sibling `inventory_state.jsonl`. Vector runs beside Beacon only when you choose
+to forward those local streams into your own storage, SIEM, data lake, or log
+platform.
## Open Source And Managed
-In **Asymptote Open Source**, Agent Beacon is local-first. It configures supported agent harnesses, receives OTLP or hook telemetry, normalizes events, writes the local [runtime JSONL log](/concepts/core-concepts#runtime-jsonl-log), and can generate forwarding content packs. Destination credentials, bucket policies, IAM roles, lifecycle rules, retention, encryption, and remote ingestion settings stay outside Beacon endpoint configuration.
+In **Asymptote Open Source**, Agent Beacon is local-first. It configures supported agent harnesses, receives OTLP or hook telemetry, normalizes events, writes local runtime and inventory JSONL, and can generate forwarding content packs. Destination credentials, bucket policies, IAM roles, lifecycle rules, retention, encryption, and remote ingestion settings stay outside Beacon endpoint configuration.
That is where Vector fits. For open-source deployments, Vector is an optional customer-managed forwarder. You install and operate Vector through MDM, endpoint management, launchd, systemd, Kubernetes, or your normal host-agent tooling. Beacon can generate a destination-specific `vector.toml`, but Vector owns:
@@ -44,7 +48,10 @@ In **Asymptote Managed**, the main path is different. Managed deployments use As
## Why The Handoff Is Local
-Beacon's local JSONL handoff keeps the endpoint posture simple and inspectable. The endpoint agent does not need S3 credentials to keep collecting telemetry. The local dashboard can read the same file that a forwarder tails. If your destination changes, Beacon can keep writing the same normalized event stream while you replace the downstream shipper or sink.
+Beacon's local JSONL handoff keeps the endpoint posture simple and inspectable.
+The endpoint agent does not need object-storage credentials to keep collecting
+telemetry. If your destination changes, Beacon can keep writing the same
+normalized streams while you replace the downstream shipper or sink.
This also creates a clear ownership boundary:
@@ -89,15 +96,19 @@ The source reads Beacon's local file. The transform replaces Vector's wrapper ev
## S3 In Depth
-AWS S3 forwarding is the clearest example of the pattern because it shows how Beacon's local event stream becomes durable object storage without Beacon storing AWS credentials.
+AWS S3 forwarding is one example of how Beacon's local runtime and inventory
+streams become durable object storage without Beacon storing AWS credentials.
-First, Beacon writes endpoint events locally. A managed system-mode deployment writes to:
+First, Beacon writes endpoint activity and inventory locally. A managed
+system-mode deployment writes to:
```text
/var/log/beacon-agent/runtime.jsonl
+/var/log/beacon-agent/inventory_state.jsonl
```
-Each line is one complete Beacon endpoint event. Beacon keeps the active path stable for dashboards and shippers, and rotates local archives when needed.
+Each line is one complete Beacon endpoint event. Beacon keeps the active paths
+stable for shippers and rotates local archives when needed.
Next, you generate the S3 content pack:
@@ -203,6 +214,26 @@ For a dedicated Beacon prefix, least privilege usually starts with `s3:PutObject
Add `s3:PutObjectTagging`, KMS permissions, bucket-owner controls, or condition keys only when your AWS environment requires them. Bucket lifecycle, retention, server-side encryption, replication, access logs, and object lock should be configured in AWS, not in Beacon.
+## GCS Authentication On macOS
+
+The packaged GCS flow mirrors the S3 runtime/inventory layout with
+`gcp_cloud_storage` sinks and a root `BEACON_GCS_PREFIX`. The signed package
+installs GCS helpers under `/opt/beacon/jamf/claude/gcs/` and runs Vector as
+`com.beacon.endpoint.gcs-forwarder`.
+
+The bundled Vector `0.56` supports service-account JSON and GCE metadata
+authentication. Normal Macs do not have GCE metadata, and interactive `gcloud`
+ADC or Workload Identity Federation is not a reliable launchd service contract
+for this version. Deliver a service-account JSON through MDM or secret tooling,
+store it outside Beacon-managed directories, and reference it with
+`GOOGLE_APPLICATION_CREDENTIALS`. Beacon's root-owned `gcs-vector.env` stores
+only that path.
+
+Use `roles/storage.objectCreator` for the endpoint writer. Because that role
+cannot list or read objects, validate with a distinct reader identity. See
+[Google Cloud Storage forwarding](/log-forwarding/gcs) for full setup and
+rotation steps.
+
## Validation
Beacon can write a known-good S3 validation event:
diff --git a/docs/docs.json b/docs/docs.json
index 70472a93..3378bf4d 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -211,6 +211,7 @@
"pages": [
"mdm/jamf/claude",
"guides/jamf-anthropic-openai-cursor-mdm",
+ "guides/jamf-gcs-mdm",
"guides/jamf-s3-mdm",
"guides/jamf-falcon-mdm"
]
@@ -246,7 +247,7 @@
{
"group": "Object Storage",
"pages": [
- "guides/claude-s3-system",
+ "guides/macos-object-storage-system",
"log-forwarding/s3",
"log-forwarding/gcs"
]
@@ -457,6 +458,7 @@
"pages": [
"mdm/jamf/claude",
"guides/jamf-anthropic-openai-cursor-mdm",
+ "guides/jamf-gcs-mdm",
"guides/jamf-s3-mdm",
"guides/jamf-falcon-mdm"
]
@@ -531,6 +533,14 @@
]
},
"redirects": [
+ {
+ "source": "/guides/claude-gcs-system",
+ "destination": "/guides/macos-object-storage-system"
+ },
+ {
+ "source": "/guides/claude-s3-system",
+ "destination": "/guides/macos-object-storage-system"
+ },
{
"source": "/product-changelog",
"destination": "/changelog/cli"
diff --git a/docs/guides/claude-s3-system.mdx b/docs/guides/claude-s3-system.mdx
deleted file mode 100644
index 187c46ef..00000000
--- a/docs/guides/claude-s3-system.mdx
+++ /dev/null
@@ -1,297 +0,0 @@
----
-title: "Claude System Mode with S3"
-description: "Install Beacon directly from GitHub Releases, configure Claude Code in system mode, and forward local JSONL logs to AWS S3 with bundled Vector."
----
-
-## Overview
-
-Use this guide for a single Mac where you want Beacon running in system mode, Claude Code telemetry enabled, and local Beacon JSONL logs forwarded to an S3 bucket. There is no MDM setup here.
-
-The end state is:
-
-- Beacon is installed under `/opt/beacon` from the signed and notarized GitHub Release package.
-- The system collector runs as `com.beacon.endpoint.collector`.
-- Claude Code hooks are installed for the logged-in user.
-- Runtime logs are written to `/var/log/beacon-agent/runtime.jsonl`.
-- Inventory logs are written to `/var/log/beacon-agent/inventory_state.jsonl`.
-- Bundled Vector forwards both streams to S3 under `runtime/` and `inventory/`.
-
-## 1. Prepare AWS
-
-Create or choose an S3 bucket and a root prefix such as `beacon-prod`. Do not include `runtime` or `inventory` in the prefix; Beacon adds those folders.
-
-### Create an S3 bucket
-
-Create the bucket that will receive Beacon endpoint logs. Replace the example bucket name and region with your values:
-
-```bash
-aws s3api create-bucket \
- --bucket example-security-logs \
- --region us-west-2 \
- --create-bucket-configuration LocationConstraint=us-west-2
-```
-
-If you already have a bucket, choose the root prefix Beacon should write under, for example `beacon-prod`.
-
-### Create an S3 policy
-
-Name the IAM policy `BeaconEndpointWriteOnly` and give the credentials used by Vector permission to write under the selected prefix. Save this JSON as `beacon-s3-write-only-policy.json`:
-
-```json
-{
- "Version": "2012-10-17",
- "Statement": [
- {
- "Effect": "Allow",
- "Action": ["s3:PutObject"],
- "Resource": "arn:aws:s3:::example-security-logs/beacon-prod/*"
- }
- ]
-}
-```
-
-Create the IAM policy:
-
-```bash
-aws iam create-policy \
- --policy-name BeaconEndpointWriteOnly \
- --policy-document file://beacon-s3-write-only-policy.json
-```
-
-If your bucket requires KMS or object tags, add the required `kms:*` or `s3:PutObjectTagging` permissions in AWS.
-
-### Create or choose IAM credentials
-
-You get the access key and secret key from AWS IAM, but ideally use temporary credentials instead of long-lived access keys.
-
-For a quick setup:
-
-1. Open the AWS Console.
-2. Go to IAM.
-3. Go to Users.
-4. Select the IAM user you want Vector to use, or create one named `beacon-endpoint-writer`.
-5. Attach the `BeaconEndpointWriteOnly` policy to that IAM user.
-6. Open the Security credentials tab.
-7. Under Access keys, click Create access key.
-8. Choose the use case, such as Command Line Interface (CLI).
-9. AWS will show `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
-
-AWS only shows the secret access key once. Copy it immediately or download the `.csv`.
-
-For a quick local setup, have these values ready:
-
-```bash
-export BEACON_S3_BUCKET="example-security-logs"
-export BEACON_S3_PREFIX="beacon-prod"
-export AWS_REGION="us-west-2"
-
-# Use temporary or managed credentials when possible.
-export AWS_ACCESS_KEY_ID="..."
-export AWS_SECRET_ACCESS_KEY="..."
-export AWS_SESSION_TOKEN="" # optional
-```
-
-Beacon does not store these secrets in endpoint configuration. The helper writes the AWS provider-chain values you pass to Vector's root-owned env file at `/Library/Application Support/Beacon/Forwarders/s3-vector.env` with mode `0600`.
-
-You can also use normal AWS provider-chain settings such as `AWS_PROFILE`, `AWS_SHARED_CREDENTIALS_FILE`, `AWS_CONFIG_FILE`, `AWS_WEB_IDENTITY_TOKEN_FILE`, or `AWS_ROLE_ARN` instead of raw access keys.
-
-## 2. Install The Package
-
-Download and install the latest Apple Silicon endpoint package from [GitHub Releases](https://github.com/Asymptote-Labs/agent-beacon/releases):
-
-```bash
-tmpdir="$(mktemp -d)"
-gh release download \
- --repo Asymptote-Labs/agent-beacon \
- --pattern 'BeaconEndpointAgent-*-arm64.pkg' \
- --dir "$tmpdir"
-
-sudo installer -pkg "$tmpdir"/BeaconEndpointAgent-*-arm64.pkg -target /
-/opt/beacon/bin/beacon version
-```
-
-If you do not use the GitHub CLI, download the latest `BeaconEndpointAgent-*-arm64.pkg` asset from the release page and run the same `sudo installer` command against that file.
-
-The package installs `/opt/beacon/bin/beacon`, `/opt/beacon/bin/beacon-otelcol`, `/opt/beacon/bin/vector`, and the S3 helper scripts.
-
-## 3. Configure Beacon And S3
-
-Run the packaged helper once from an interactive login session. Keep Claude Code closed while this runs.
-
-```bash
-sudo env \
- BEACON_S3_BUCKET="$BEACON_S3_BUCKET" \
- BEACON_S3_PREFIX="$BEACON_S3_PREFIX" \
- BEACON_S3_STORAGE_CLASS="STANDARD" \
- AWS_REGION="$AWS_REGION" \
- AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" \
- AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" \
- AWS_SESSION_TOKEN="${AWS_SESSION_TOKEN:-}" \
- /opt/beacon/jamf/claude/s3/repair-hooks-and-forwarder.sh
-```
-
-This starts the Beacon collector, installs Claude hooks for the current console user, writes the Vector S3 config, and starts `com.beacon.endpoint.s3-forwarder`.
-
-Restart Claude Code before testing a real Claude session.
-
-## 4. Verify Locally
-
-Check the two services:
-
-```bash
-sudo launchctl print system/com.beacon.endpoint.collector
-sudo launchctl print system/com.beacon.endpoint.s3-forwarder
-```
-
-Check Beacon status and local logs:
-
-```bash
-sudo /opt/beacon/bin/beacon endpoint status --system
-ls -l /var/log/beacon-agent/runtime.jsonl /var/log/beacon-agent/inventory_state.jsonl
-```
-
-Write a validation event:
-
-```bash
-sudo /opt/beacon/bin/beacon endpoint s3 validate --system
-sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \
- --system \
- --force \
- --trigger manual \
- --trigger-harness claude \
- --working-dir /Users/Shared \
- --log-path /var/log/beacon-agent/runtime.jsonl
-```
-
-Confirm events landed locally:
-
-```bash
-tail -n 5 /var/log/beacon-agent/runtime.jsonl
-tail -n 5 /var/log/beacon-agent/inventory_state.jsonl
-```
-
-## 5. Verify S3
-
-Vector batches uploads, so allow up to five minutes.
-
-```bash
-aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/" \
- --recursive \
- --region "$AWS_REGION"
-
-aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/inventory/" \
- --recursive \
- --region "$AWS_REGION"
-```
-
-Inspect a recent object:
-
-```bash
-aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/date=<YYYY-MM-DD>/<object>.jsonl.gz" - \
- --region "$AWS_REGION" | gzip -dc | grep "Beacon endpoint S3 validation event"
-```
-
-Expected layout:
-
-```text
-s3://example-security-logs/beacon-prod/runtime/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
-s3://example-security-logs/beacon-prod/inventory/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
-```
-
-## Troubleshooting
-
-### Vector Is Not Starting
-
-Check launchd and Vector stderr:
-
-```bash
-sudo launchctl print system/com.beacon.endpoint.s3-forwarder
-sudo tail -n 100 /tmp/com.beacon.endpoint.s3-forwarder.err
-```
-
-Run Vector in the foreground to see the real error:
-
-```bash
-sudo /opt/beacon/jamf/claude/s3/run-forwarder.sh
-```
-
-Common causes are a missing `/opt/beacon/bin/vector`, a malformed env file, missing AWS credentials, or an S3 bucket/prefix/IAM mismatch. Re-run the helper after fixing the environment.
-
-### Port 4137 Or 4317 Is Already In Use
-
-Beacon's default OTLP ports are `4317` for gRPC and `4318` for HTTP. If setup reports a port conflict, first retry the same command once. A transient launchd or collector startup race can briefly surface as "address already in use" and then succeed on the next run.
-
-If the retry fails, identify the process:
-
-```bash
-sudo lsof -nP -iTCP:4317 -sTCP:LISTEN
-sudo lsof -nP -iTCP:4318 -sTCP:LISTEN
-sudo lsof -nP -iTCP:4137 -sTCP:LISTEN # only if the error names 4137
-```
-
-Either stop the conflicting process or choose alternate Beacon ports and re-run setup:
-
-```bash
-sudo env \
- BEACON_OTLP_GRPC_PORT="44317" \
- BEACON_OTLP_HTTP_PORT="44318" \
- BEACON_S3_BUCKET="$BEACON_S3_BUCKET" \
- BEACON_S3_PREFIX="$BEACON_S3_PREFIX" \
- AWS_REGION="$AWS_REGION" \
- AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" \
- AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" \
- AWS_SESSION_TOKEN="${AWS_SESSION_TOKEN:-}" \
- /opt/beacon/jamf/claude/s3/repair-hooks-and-forwarder.sh
-```
-
-Restart Claude Code after changing ports.
-
-### No S3 Objects Appear
-
-First wait five minutes. Then check that Vector has the expected non-secret settings:
-
-```bash
-sudo sh -c 'sed -E "s/(AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|AWS_SESSION_TOKEN)=.*/\1=<redacted>/" "/Library/Application Support/Beacon/Forwarders/s3-vector.env"'
-sudo grep -E 'runtime.jsonl|inventory_state.jsonl|key_prefix|read_from' \
- "/Library/Application Support/Beacon/Forwarders/s3-vector.toml"
-```
-
-Then confirm IAM allows `s3:PutObject` for `s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/*`, the AWS region matches the bucket, and the validation event was written after Vector started. Runtime forwarding starts at the end of the file to avoid backfilling old runtime events.
-
-### Claude Hooks Are Missing
-
-Run the helper while an interactive user is logged in, then restart Claude Code. Check the user's Claude settings:
-
-```bash
-grep -n 'BEACON_ENDPOINT_CLI\|beacon-hooks' ~/.claude/settings.json
-```
-
-If nothing appears, re-run:
-
-```bash
-sudo env \
- BEACON_S3_BUCKET="$BEACON_S3_BUCKET" \
- BEACON_S3_PREFIX="$BEACON_S3_PREFIX" \
- AWS_REGION="$AWS_REGION" \
- AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" \
- AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" \
- AWS_SESSION_TOKEN="${AWS_SESSION_TOKEN:-}" \
- /opt/beacon/jamf/claude/s3/repair-hooks-and-forwarder.sh
-```
-
-### Launchd Says Bootstrap Failed: 5
-
-Verify the files exist and are executable/readable:
-
-```bash
-ls -l /opt/beacon/bin/beacon /opt/beacon/bin/beacon-otelcol /opt/beacon/bin/vector
-ls -l /Library/LaunchDaemons/com.beacon.endpoint.collector.plist
-ls -l /Library/LaunchDaemons/com.beacon.endpoint.s3-forwarder.plist
-```
-
-Clear stale launchd state and run the helper again:
-
-```bash
-sudo launchctl bootout system/com.beacon.endpoint.collector 2>/dev/null || true
-sudo launchctl bootout system/com.beacon.endpoint.s3-forwarder 2>/dev/null || true
-```
diff --git a/docs/guides/jamf-gcs-mdm.mdx b/docs/guides/jamf-gcs-mdm.mdx
new file mode 100644
index 00000000..a3723d3b
--- /dev/null
+++ b/docs/guides/jamf-gcs-mdm.mdx
@@ -0,0 +1,310 @@
+---
+title: "Claude with Jamf and GCS"
+description: "Self-serve Jamf Pro setup for Beacon endpoint telemetry, Claude Code hooks, inventory snapshots, and Google Cloud Storage forwarding"
+---
+
+## Overview
+
+Use this guide to install Beacon on managed Macs and forward Claude Code runtime
+and inventory telemetry to Google Cloud Storage without asking users to configure
+the endpoint.
+
+The deployed state is:
+
+- Beacon and Vector are installed under `/opt/beacon`.
+- `com.beacon.endpoint.collector` runs the system endpoint.
+- Claude Code hooks are installed for the logged-in console user.
+- Runtime and inventory events are written to
+ `/var/log/beacon-agent/runtime.jsonl` and
+ `/var/log/beacon-agent/inventory_state.jsonl`.
+- `com.beacon.endpoint.gcs-forwarder` uploads both streams under one root prefix:
+
+```text
+gs://<bucket>/<prefix>/runtime/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
+gs://<bucket>/<prefix>/inventory/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
+```
+
+Use a root prefix such as `beacon-prod`, not `beacon-prod/runtime` or
+`beacon-prod/inventory`. The installer normalizes those older suffixes, but new
+deployments should use the root layout.
+
+## 1. Prepare Google Cloud
+
+Set placeholders in an administrator shell:
+
+```bash
+export GCP_PROJECT="<project-id>"
+export GCP_REGION="<region>" # for example us-central1
+export BEACON_GCS_BUCKET="<globally-unique-bucket>"
+export BEACON_GCS_PREFIX="beacon-prod"
+export BEACON_GCS_WRITER="beacon-endpoint-writer"
+export BEACON_GCS_READER="beacon-endpoint-reader"
+```
+
+Create the bucket and writer service account:
+
+```bash
+gcloud services enable storage.googleapis.com iam.googleapis.com \
+ --project "$GCP_PROJECT"
+
+gcloud storage buckets create "gs://${BEACON_GCS_BUCKET}" \
+ --project "$GCP_PROJECT" \
+ --location "$GCP_REGION" \
+ --uniform-bucket-level-access
+
+gcloud iam service-accounts create "$BEACON_GCS_WRITER" \
+ --project "$GCP_PROJECT" \
+ --display-name "Beacon endpoint GCS writer"
+
+export BEACON_GCS_WRITER_EMAIL="${BEACON_GCS_WRITER}@${GCP_PROJECT}.iam.gserviceaccount.com"
+
+gcloud storage buckets add-iam-policy-binding "gs://${BEACON_GCS_BUCKET}" \
+ --member "serviceAccount:${BEACON_GCS_WRITER_EMAIL}" \
+ --role roles/storage.objectCreator
+```
+
+`roles/storage.objectCreator` can create objects but cannot list, read, overwrite,
+or delete them. A successful writer therefore cannot validate delivery by
+running `gcloud storage ls` or `cat`.
+
+Create a separate read-only identity for validation and downstream consumers:
+
+```bash
+gcloud iam service-accounts create "$BEACON_GCS_READER" \
+ --project "$GCP_PROJECT" \
+ --display-name "Beacon endpoint GCS reader"
+
+export BEACON_GCS_READER_EMAIL="${BEACON_GCS_READER}@${GCP_PROJECT}.iam.gserviceaccount.com"
+
+gcloud storage buckets add-iam-policy-binding "gs://${BEACON_GCS_BUCKET}" \
+ --member "serviceAccount:${BEACON_GCS_READER_EMAIL}" \
+ --role roles/storage.objectViewer
+```
+
+Apply lifecycle, retention, logging, and CMEK controls in Google Cloud according
+to your organization's policy.
+
+## 2. Deliver The Writer Credential
+
+Vector `0.56` supports a service-account JSON file through
+`GOOGLE_APPLICATION_CREDENTIALS` and GCE metadata credentials. Managed Macs do
+not normally have GCE metadata, and interactive `gcloud auth
+application-default login` credentials or Workload Identity Federation are not
+a reliable launchd authentication contract for this Vector version.
+
+Create a key only when your organization permits service-account keys:
+
+```bash
+umask 077
+gcloud iam service-accounts keys create "./${BEACON_GCS_WRITER}.json" \
+ --project "$GCP_PROJECT" \
+ --iam-account "$BEACON_GCS_WRITER_EMAIL"
+```
+
+Deliver that file with Jamf's managed-file or secret-delivery mechanism to a
+root-owned location outside Beacon's managed tree, for example:
+
+```text
+/Library/Application Support/Your Organization/Secrets/beacon-gcs-writer.json
+```
+
+Do not upload the JSON as an ordinary Jamf script parameter, print it in policy
+logs, commit it, or place it below `/opt/beacon` or
+`/Library/Application Support/Beacon`. Beacon upgrades, repair, and cleanup own
+those trees. On the Mac, enforce restrictive permissions:
+
+```bash
+sudo chown root:wheel \
+ "/Library/Application Support/Your Organization/Secrets/beacon-gcs-writer.json"
+sudo chmod 0600 \
+ "/Library/Application Support/Your Organization/Secrets/beacon-gcs-writer.json"
+```
+
+The packaged helper stores only the credential path in
+`/Library/Application Support/Beacon/Forwarders/gcs-vector.env`; the JSON stays
+in the externally managed location.
+
+## 3. Configure The Jamf Policy
+
+Upload the signed Beacon endpoint package, which includes:
+
+```text
+/opt/beacon/bin/vector
+/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
+```
+
+Use one policy to install the package and a second policy to deliver the
+credential and configure forwarding. Add this Jamf script to the second policy:
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+export BEACON_GCS_BUCKET="${4:-}"
+export BEACON_GCS_PREFIX="${5:-beacon}"
+export BEACON_GCS_STORAGE_CLASS="${6:-STANDARD}"
+export BEACON_VECTOR_READ_FROM="${7:-end}"
+export GOOGLE_APPLICATION_CREDENTIALS="${8:-}"
+
+test -r "$GOOGLE_APPLICATION_CREDENTIALS"
+/opt/beacon/jamf/claude/gcs/repair-hooks-and-forwarder.sh
+```
+
+Configure the Jamf parameter labels:
+
+| Parameter | Label | Example |
+| --- | --- | --- |
+| 4 | GCS bucket | `example-security-logs` |
+| 5 | GCS prefix root | `beacon-prod` |
+| 6 | GCS storage class | `STANDARD` |
+| 7 | Vector runtime read position | `end` |
+| 8 | Managed credential file path | `/Library/Application Support/Your Organization/Secrets/beacon-gcs-writer.json` |
+
+The helper writes:
+
+```text
+/Library/Application Support/Beacon/Forwarders/gcs-vector.toml
+/Library/Application Support/Beacon/Forwarders/gcs-vector.env
+/Library/Application Support/Beacon/Forwarders/vector-data/gcs/
+/Library/LaunchDaemons/com.beacon.endpoint.gcs-forwarder.plist
+```
+
+Runtime starts at `end` to avoid an unexpected historical upload. Inventory
+starts at `beginning` so an initial snapshot created before Vector starts is not
+missed.
+
+## 4. Validate A Managed Mac
+
+Check services, files, and the non-secret configuration:
+
+```bash
+sudo launchctl print system/com.beacon.endpoint.collector
+sudo launchctl print system/com.beacon.endpoint.gcs-forwarder
+
+ls -l /var/log/beacon-agent/runtime.jsonl \
+ /var/log/beacon-agent/inventory_state.jsonl
+
+sudo grep -E 'runtime.jsonl|inventory_state.jsonl|runtime/date|inventory/date|read_from' \
+ "/Library/Application Support/Beacon/Forwarders/gcs-vector.toml"
+
+sudo sh -c '. "/Library/Application Support/Beacon/Forwarders/gcs-vector.env"; test -r "$GOOGLE_APPLICATION_CREDENTIALS"'
+```
+
+Generate runtime and inventory events:
+
+```bash
+sudo /opt/beacon/bin/beacon endpoint gcs validate --system
+sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \
+ --system \
+ --force \
+ --trigger manual \
+ --trigger-harness claude \
+ --working-dir /Users/Shared \
+ --log-path /var/log/beacon-agent/runtime.jsonl
+```
+
+Allow up to five minutes for the default Vector batch timeout. Validate with the
+separate reader identity, not the write-only endpoint credential:
+
+```bash
+gcloud storage ls \
+ "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/runtime/**" \
+ --impersonate-service-account "$BEACON_GCS_READER_EMAIL"
+
+gcloud storage ls \
+ "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/inventory/**" \
+ --impersonate-service-account "$BEACON_GCS_READER_EMAIL"
+
+gcloud storage cat \
+ "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/runtime/date=<YYYY-MM-DD>/<object>.jsonl.gz" \
+ --impersonate-service-account "$BEACON_GCS_READER_EMAIL" |
+ gzip -dc | grep "Beacon endpoint GCS validation event"
+```
+
+The administrator running impersonation also needs
+`roles/iam.serviceAccountTokenCreator` on the reader account. Alternatively,
+validate with your existing security operations reader identity.
+
+Grant that role to a designated validator:
+
+```bash
+export BEACON_GCS_VALIDATOR="<[email protected]>"
+gcloud iam service-accounts add-iam-policy-binding \
+ "$BEACON_GCS_READER_EMAIL" \
+ --project "$GCP_PROJECT" \
+ --member "user:${BEACON_GCS_VALIDATOR}" \
+ --role roles/iam.serviceAccountTokenCreator
+```
+
+## Credential Rotation
+
+Create and deliver a new key before deleting the old one:
+
+```bash
+umask 077
+gcloud iam service-accounts keys create "./${BEACON_GCS_WRITER}-next.json" \
+ --project "$GCP_PROJECT" \
+ --iam-account "$BEACON_GCS_WRITER_EMAIL"
+```
+
+After securely transferring the new file to the Mac, replace the externally
+managed JSON atomically, preserve `root:wheel` and mode `0600`, then restart the
+forwarder:
+
+```bash
+export BEACON_GCS_CREDENTIAL_PATH="/Library/Application Support/Your Organization/Secrets/beacon-gcs-writer.json"
+sudo install -m 0600 -o root -g wheel \
+ "./${BEACON_GCS_WRITER}-next.json" \
+ "${BEACON_GCS_CREDENTIAL_PATH}.new"
+sudo mv -f "${BEACON_GCS_CREDENTIAL_PATH}.new" \
+ "$BEACON_GCS_CREDENTIAL_PATH"
+rm -f "./${BEACON_GCS_WRITER}-next.json"
+
+sudo launchctl kickstart -k system/com.beacon.endpoint.gcs-forwarder
+sudo launchctl print system/com.beacon.endpoint.gcs-forwarder
+```
+
+After new objects arrive, list keys and delete the retired key:
+
+```bash
+gcloud iam service-accounts keys list \
+ --project "$GCP_PROJECT" \
+ --iam-account "$BEACON_GCS_WRITER_EMAIL"
+
+gcloud iam service-accounts keys delete "<old-key-id>" \
+ --project "$GCP_PROJECT" \
+ --iam-account "$BEACON_GCS_WRITER_EMAIL"
+```
+
+## Troubleshooting
+
+Check launchd and Vector stderr:
+
+```bash
+sudo launchctl print system/com.beacon.endpoint.gcs-forwarder
+sudo tail -n 100 /tmp/com.beacon.endpoint.gcs-forwarder.err
+sudo /opt/beacon/jamf/claude/gcs/run-forwarder.sh
+```
+
+Common failures:
+
+- `GOOGLE_APPLICATION_CREDENTIALS is missing or unreadable`: confirm the path in
+ `gcs-vector.env`, the external file, and root read permission.
+- `403 Forbidden`: confirm the credential belongs to the expected service
+ account and that account has `roles/storage.objectCreator` on the target
+ bucket. Confirm any CMEK key also permits encryption.
+- Uploads succeed but `gcloud storage ls` fails under the writer: expected;
+ `objectCreator` cannot inspect objects. Use the reader identity.
+- No recent runtime objects: runtime starts at `end`; write a validation event
+ after the forwarder is running.
+- No inventory objects: force an inventory heartbeat and inspect
+ `/var/log/beacon-agent/inventory_state.jsonl`.
+
+For idempotent repair using the saved settings:
+
+```bash
+sudo sh -c '. "/Library/Application Support/Beacon/Forwarders/gcs-vector.env"; /opt/beacon/jamf/claude/gcs/install-forwarder.sh'
+```
+
diff --git a/docs/guides/macos-object-storage-system.mdx b/docs/guides/macos-object-storage-system.mdx
new file mode 100644
index 00000000..c12b367f
--- /dev/null
+++ b/docs/guides/macos-object-storage-system.mdx
@@ -0,0 +1,230 @@
+---
+title: "macOS System-Mode Object Storage Forwarding"
+description: "Install Beacon on one Mac and forward system runtime and inventory telemetry to AWS S3, Google Cloud Storage, or both."
+---
+
+## Overview
+
+Use this guide for a single Apple Silicon Mac without MDM. Beacon's object
+storage forwarders are harness-neutral: they tail the system endpoint logs, so
+Claude Code, Codex CLI, Cursor, VS Code, opencode, and other configured
+integrations can share the same S3 or GCS pipeline.
+
+The end state is:
+
+- Beacon and bundled Vector are installed under `/opt/beacon`.
+- `com.beacon.endpoint.collector` receives local OTLP telemetry.
+- Supported hooks and plugins write to the same system runtime log.
+- Runtime activity is stored in `/var/log/beacon-agent/runtime.jsonl`.
+- Inventory telemetry is stored in
+ `/var/log/beacon-agent/inventory_state.jsonl`.
+- Vector forwards both streams to S3, GCS, or both:
+
+```text
+<bucket>/<prefix>/runtime/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
+<bucket>/<prefix>/inventory/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
+```
+
+The scripts below use the destination-only `install-forwarder.sh` helpers.
+The `repair-hooks-and-forwarder.sh` scripts under the `claude/` package path are
+Claude convenience wrappers: they install the same forwarder and then repair
+Claude hooks. The forwarding services themselves do not inspect or depend on
+the producing harness.
+
+## 1. Install Beacon
+
+Download and install the latest signed Apple Silicon endpoint package from
+[GitHub Releases](https://github.com/Asymptote-Labs/agent-beacon/releases):
+
+```bash
+tmpdir="$(mktemp -d)"
+gh release download \
+ --repo Asymptote-Labs/agent-beacon \
+ --pattern 'BeaconEndpointAgent-*-arm64.pkg' \
+ --dir "$tmpdir"
+
+sudo installer -pkg "$tmpdir"/BeaconEndpointAgent-*-arm64.pkg -target /
+/opt/beacon/bin/beacon version
+```
+
+The package installs Beacon, the collector, bundled Vector, and the S3 and GCS
+forwarder helpers. Confirm the system endpoint is healthy:
+
+```bash
+sudo /opt/beacon/bin/beacon endpoint status --system
+sudo launchctl print system/com.beacon.endpoint.collector
+```
+
+## 2. Configure Runtime Harnesses
+
+Object storage forwarding begins after events reach Beacon's system logs.
+Configure the runtimes you use before troubleshooting the destination.
+
+The package configures the default native OTLP path for Claude Code and Codex
+CLI for the active console user. Other hook- or plugin-backed integrations use
+their normal endpoint installation commands. For example:
+
+```bash
+/opt/beacon/bin/beacon endpoint hooks install \
+ --harness cursor \
+ --level user \
+ --log-path /var/log/beacon-agent/runtime.jsonl
+
+/opt/beacon/bin/beacon endpoint hooks install \
+ --harness opencode \
+ --level user \
+ --log-path /var/log/beacon-agent/runtime.jsonl
+```
+
+Run hook installers as the interactive user, not root. Review
+[Agent Harness Integrations](/runtimes) and
+[Endpoint Hooks](/cli/hooks) for the supported setup method for each runtime.
+Restart the runtime after changing hooks or OTLP settings.
+
+Confirm recent local events before configuring a cloud destination:
+
+```bash
+sudo /opt/beacon/bin/beacon endpoint status --system --json
+ls -l \
+ /var/log/beacon-agent/runtime.jsonl \
+ /var/log/beacon-agent/inventory_state.jsonl
+```
+
+## 3. Choose A Destination
+
+Use a root prefix such as `beacon-prod`. Do not include `runtime` or
+`inventory`; Beacon appends those folders.
+
+### AWS S3
+
+Prepare the bucket, region, prefix, and a credential provider with
+`s3:PutObject` permission for the selected prefix. Review
+[AWS S3 Forwarding](/log-forwarding/s3) for the IAM policy, provider-chain
+options, storage classes, object layout, validation, and retention guidance.
+
+Then install only the S3 forwarder:
+
+```bash
+export BEACON_S3_BUCKET="<bucket>"
+export BEACON_S3_PREFIX="beacon-prod"
+export BEACON_S3_STORAGE_CLASS="STANDARD"
+export AWS_REGION="<region>"
+
+# Supply one supported AWS provider-chain pattern. These are examples only.
+export AWS_ACCESS_KEY_ID="<managed-or-temporary-access-key>"
+export AWS_SECRET_ACCESS_KEY="<managed-or-temporary-secret-key>"
+export AWS_SESSION_TOKEN="<optional-session-token>"
+
+sudo env \
+ BEACON_S3_BUCKET="$BEACON_S3_BUCKET" \
+ BEACON_S3_PREFIX="$BEACON_S3_PREFIX" \
+ BEACON_S3_STORAGE_CLASS="$BEACON_S3_STORAGE_CLASS" \
+ AWS_REGION="$AWS_REGION" \
+ AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" \
+ AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" \
+ AWS_SESSION_TOKEN="${AWS_SESSION_TOKEN:-}" \
+ /opt/beacon/jamf/claude/s3/install-forwarder.sh
+```
+
+For profiles or web identity, provide the corresponding variables documented in
+[AWS S3 Forwarding](/log-forwarding/s3) instead of raw access keys.
+
+### Google Cloud Storage
+
+Prepare a bucket and a dedicated writer with bucket-level
+`roles/storage.objectCreator`. The packaged Vector 0.56 path on macOS requires
+a service-account JSON file through `GOOGLE_APPLICATION_CREDENTIALS`; it does
+not support external-account Workload Identity Federation. Keep the JSON in an
+externally managed root-only location.
+
+Review [Google Cloud Storage Forwarding](/log-forwarding/gcs) for exact `gcloud`
+commands, the separate reader identity, key-delivery constraints, disabled
+write-only healthchecks, object layout, and rotation guidance.
+
+Then install only the GCS forwarder:
+
+```bash
+export BEACON_GCS_BUCKET="<bucket>"
+export BEACON_GCS_PREFIX="beacon-prod"
+export BEACON_GCS_STORAGE_CLASS="STANDARD"
+export GOOGLE_APPLICATION_CREDENTIALS="/Library/Application Support/Your Organization/Secrets/beacon-gcs-writer.json"
+
+sudo env \
+ BEACON_GCS_BUCKET="$BEACON_GCS_BUCKET" \
+ BEACON_GCS_PREFIX="$BEACON_GCS_PREFIX" \
+ BEACON_GCS_STORAGE_CLASS="$BEACON_GCS_STORAGE_CLASS" \
+ GOOGLE_APPLICATION_CREDENTIALS="$GOOGLE_APPLICATION_CREDENTIALS" \
+ /opt/beacon/jamf/claude/gcs/install-forwarder.sh
+```
+
+### Forward To Both
+
+The services have separate labels, configs, credentials, and checkpoint
+directories. Install both helpers to forward the same local events to S3 and
+GCS:
+
+```text
+com.beacon.endpoint.s3-forwarder
+com.beacon.endpoint.gcs-forwarder
+```
+
+## 4. Validate
+
+Check the configured services:
+
+```bash
+sudo launchctl print system/com.beacon.endpoint.collector
+sudo launchctl print system/com.beacon.endpoint.s3-forwarder # when configured
+sudo launchctl print system/com.beacon.endpoint.gcs-forwarder # when configured
+```
+
+Write destination and inventory validation events:
+
+```bash
+sudo /opt/beacon/bin/beacon endpoint s3 validate --system # when configured
+sudo /opt/beacon/bin/beacon endpoint gcs validate --system # when configured
+
+sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \
+ --system \
+ --force \
+ --trigger manual \
+ --trigger-harness manual \
+ --working-dir /Users/Shared \
+ --log-path /var/log/beacon-agent/runtime.jsonl
+```
+
+Vector batches for up to five minutes by default. Use an authorized reader to
+inspect the destination:
+
+- Follow [S3 validation](/log-forwarding/s3#validate-forwarding) for AWS CLI
+ commands and writer-versus-reader permissions.
+- Follow [GCS validation](/log-forwarding/gcs#validate-forwarding) for Google
+ Cloud CLI commands and the separate reader identity.
+
+Generate a real event from every configured harness and confirm its
+`harness.name` appears in a remote runtime object.
+
+## 5. Operate And Troubleshoot
+
+The forwarders persist checkpoints, so restarts and package upgrades resume from
+the last observed offsets. Runtime starts at the end on first install to avoid
+unexpected historical backfill; inventory starts at the beginning so the first
+snapshot is not missed.
+
+Check Vector errors:
+
+```bash
+sudo tail -n 100 /tmp/com.beacon.endpoint.s3-forwarder.err
+sudo tail -n 100 /tmp/com.beacon.endpoint.gcs-forwarder.err
+```
+
+Use the destination reference pages for provider-specific `403`, IAM, region,
+credential, encryption, retention, and reader-access troubleshooting:
+
+- [AWS S3 Forwarding](/log-forwarding/s3)
+- [Google Cloud Storage Forwarding](/log-forwarding/gcs)
+
+For managed fleets, use the dedicated [Jamf S3 guide](/guides/jamf-s3-mdm) or
+[Jamf GCS guide](/guides/jamf-gcs-mdm). Those guides show the optional
+Claude-oriented combined repair wrappers as well as policy parameters and
+managed credential delivery.
diff --git a/docs/log-forwarding/gcs.mdx b/docs/log-forwarding/gcs.mdx
index 6900f9f2..4bdbdda7 100644
--- a/docs/log-forwarding/gcs.mdx
+++ b/docs/log-forwarding/gcs.mdx
@@ -5,7 +5,7 @@ description: "Forward Beacon endpoint events into Google Cloud Storage with cust
## Forwarding Overview
-Beacon `v0.0.38` added the [Google Cloud Storage content pack](/concepts/core-concepts#google-cloud-storage-content-pack) for teams that want Beacon endpoint events stored in a GCS bucket for data lake, SIEM, archive, or downstream detection workflows. Beacon remains the local JSONL producer and writes one source of truth, the active [runtime JSONL log](/concepts/core-concepts#runtime-jsonl-log). Your customer-managed [Vector forwarding](/concepts/core-concepts#vector-forwarding) agent tails that file and uploads gzip-compressed NDJSON objects to GCS.
+Beacon `v0.0.38` added the [Google Cloud Storage content pack](/concepts/core-concepts#google-cloud-storage-content-pack) for teams that want Beacon endpoint events stored in a GCS bucket for data lake, SIEM, archive, or downstream detection workflows. Beacon remains the local JSONL producer. Customer-managed [Vector forwarding](/concepts/core-concepts#vector-forwarding) tails runtime activity and the sibling inventory stream and uploads gzip-compressed NDJSON objects to GCS.
Use this path when you want Beacon events forwarded to Google Cloud Storage without storing Google Cloud credentials, service accounts, workload identity settings, bucket IAM, lifecycle, retention, or encryption settings in Beacon endpoint configuration.
@@ -30,17 +30,30 @@ Use system mode for MDM deployments so Vector can tail `/var/log/beacon-agent/ru
## Prerequisites
- Beacon endpoint installed and writing local JSONL.
-- A Google Cloud Storage bucket for Beacon runtime logs.
+- A Google Cloud Storage bucket for Beacon runtime and inventory logs.
- Vector installed or deployable through your endpoint-management tooling.
-- A service account or workload identity available through Application Default Credentials for the process running Vector, `gcloud`, or `gsutil`.
+- A supported Google credential available to the process running Vector,
+ `gcloud`, or `gsutil`. For the packaged macOS Vector `0.56` service, use a
+ service-account JSON file referenced by `GOOGLE_APPLICATION_CREDENTIALS`.
Recommended object layout:
```text
gs://example-security-logs/beacon/runtime/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
+gs://example-security-logs/beacon/inventory/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
```
-For a dedicated Beacon bucket, `roles/storage.objectCreator` is usually enough for production uploads because it can create objects without listing or reading them. Add viewer, retention, CMEK, or bucket-specific conditional IAM only if your Google Cloud controls require them. Configure bucket lifecycle, retention, versioning, audit logs, and encryption in Google Cloud.
+For a dedicated Beacon bucket, `roles/storage.objectCreator` is usually enough
+for production uploads. It cannot list or read objects, so use a separate
+reader identity with `roles/storage.objectViewer` for validation and downstream
+consumers. Add retention, CMEK, or bucket-specific conditional IAM only if your
+Google Cloud controls require them. Configure bucket lifecycle, retention,
+versioning, audit logs, and encryption in Google Cloud.
+
+Vector's GCS startup healthcheck requires object-read permission. Beacon
+disables that healthcheck in the generated write-only sinks instead of widening
+the endpoint role; monitor Vector upload errors and validate remotely with the
+separate reader identity.
## Install the GCS pack
@@ -67,45 +80,59 @@ Use the generated smoke-test script to upload the current runtime log once. This
```bash title="Command example"
export BEACON_GCS_BUCKET="example-security-logs"
-export BEACON_GCS_PREFIX="beacon/runtime"
+export BEACON_GCS_PREFIX="beacon"
./beacon-gcs-pack/gcs-upload-smoke-test.sh
```
-The script uses `gcloud storage cp` when available and falls back to `gsutil cp`. Both rely on Application Default Credentials, workload identity, active `gcloud` configuration, or your managed endpoint secret tooling. Beacon does not store Google Cloud credentials.
+The script uses `gcloud storage cp` when available and falls back to `gsutil
+cp`. This one-shot CLI test may use the active `gcloud` identity. That does not
+prove the launchd-managed Vector service can authenticate.
Confirm the uploaded object:
```bash title="Confirm the uploaded object"
-gcloud storage ls "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/smoke-tests/"
-gcloud storage cat "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/smoke-tests/<object>.jsonl" | grep "Beacon endpoint GCS validation event"
+gcloud storage ls "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/runtime/smoke-tests/"
+gcloud storage cat "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/runtime/smoke-tests/<object>.jsonl" | grep "Beacon endpoint GCS validation event"
```
## Production forwarding
-For production, use the generated Vector config as a customer-managed host-agent forwarding template. Beacon remains the local JSONL producer; Vector tails `runtime.jsonl`, checkpoints file offsets in its `data_dir`, batches Beacon events, and writes gzip-compressed newline-delimited JSON objects into Google Cloud Storage.
+For production, use the generated Vector config as a customer-managed host-agent forwarding template. Beacon remains the local JSONL producer; Vector tails `runtime.jsonl` and `inventory_state.jsonl`, checkpoints file offsets in its `data_dir`, batches Beacon events, and writes gzip-compressed newline-delimited JSON objects into Google Cloud Storage.
```mermaid
flowchart LR
agentHarnesses["Agent harnesses"] -->|"OTLP or hooks"| beaconEndpoint["Beacon endpoint agent"]
- beaconEndpoint -->|"writes normalized events"| runtimeLog["runtime.jsonl"]
+ beaconEndpoint -->|"writes activity"| runtimeLog["runtime.jsonl"]
+ beaconEndpoint -->|"writes inventory"| inventoryLog["inventory_state.jsonl"]
runtimeLog -->|"file source tails active path"| vectorAgent["Vector host agent"]
+ inventoryLog -->|"file source tails active path"| vectorAgent
vectorAgent -->|"parse_json, gzip NDJSON"| gcsBucket["Google Cloud Storage bucket"]
gcsBucket -->|"partitioned objects"| downstreamSiem["SIEM, lake, or archive workflow"]
endpointMgmt["MDM or secret tooling"] -->|"bucket, prefix, Google credentials"| vectorAgent
```
-Install Vector using your normal endpoint management tooling, then copy the generated config into Vector's config directory. On a macOS system-mode Beacon deployment, the generated config tails `/var/log/beacon-agent/runtime.jsonl`:
+Install Vector using your normal endpoint management tooling, then copy the generated config into Vector's config directory. On a macOS system-mode Beacon deployment, the generated config tails `/var/log/beacon-agent/runtime.jsonl` and `/var/log/beacon-agent/inventory_state.jsonl`:
```bash title="Install Vector using your normal endpoint management tooling, then copy the generated config into Vector's config directory. On a macOS system-mode Beacon deployment, the generated config tails /var/log/beacon-agent/runtime.jsonl"
sudo mkdir -p /etc/vector
sudo cp ./beacon-gcs-pack/vector.toml /etc/vector/beacon-gcs.toml
export BEACON_GCS_BUCKET="example-security-logs"
-export BEACON_GCS_PREFIX="beacon/runtime"
+export BEACON_GCS_PREFIX="beacon"
vector validate /etc/vector/beacon-gcs.toml
vector --config /etc/vector/beacon-gcs.toml
```
-In managed deployments, provide `BEACON_GCS_BUCKET`, optional `BEACON_GCS_PREFIX`, optional `BEACON_GCS_STORAGE_CLASS`, and any Google Application Default Credentials or workload identity settings through the Vector service environment, host identity, MDM, or secret tooling. Do not store Google Cloud destination secrets in Beacon endpoint configuration.
+Use a root `BEACON_GCS_PREFIX`; Vector appends `runtime/` and `inventory/`.
+
+For packaged macOS deployments, the supported service contract uses Vector
+`0.56`, a service-account JSON file, and
+`GOOGLE_APPLICATION_CREDENTIALS`. Store the JSON in an externally managed,
+root-owned path outside `/opt/beacon` and `/Library/Application Support/Beacon`.
+The packaged helper records only its path in
+`/Library/Application Support/Beacon/Forwarders/gcs-vector.env` and starts
+`com.beacon.endpoint.gcs-forwarder`. Vector `0.56` also supports GCE metadata,
+but normal Macs do not expose it; interactive `gcloud` ADC and Workload Identity
+Federation are not reliable authentication paths for the launchd service.
## Cloud agent GCS upload
@@ -134,6 +161,8 @@ If you adapt the config or use another forwarder, it should:
- Checkpoint file offsets.
- Follow Beacon's local file rotation at the active `runtime.jsonl` path.
+- Forward the sibling `inventory_state.jsonl` under a separate `inventory/`
+ prefix when endpoint inventory is enabled.
- Keep each Beacon event as one JSON object per line.
- Batch newline-delimited JSON records.
- Use non-overwriting object keys.
@@ -159,7 +188,7 @@ Run the one-shot smoke test or wait for your production forwarder to ship the ne
```bash title="Run the one-shot smoke test or wait for your production forwarder to ship the new line. Beacon can write the local validation event, but remote delivery must be confirmed with Google Cloud tooling"
gcloud storage ls "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/**"
-gcloud storage cat "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/date=<date>/<object>.jsonl.gz" | gzip -dc | grep "Beacon endpoint GCS validation event"
+gcloud storage cat "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/runtime/date=<date>/<object>.jsonl.gz" | gzip -dc | grep "Beacon endpoint GCS validation event"
```
Expected validation fields:
@@ -168,15 +197,43 @@ Expected validation fields:
vendor=beacon product=endpoint-agent destination.type=gcs destination.mode=google_cloud_storage_jsonl
```
-If events do not appear, verify that Vector is reading the same runtime log path Beacon writes, that Application Default Credentials or workload identity are available to the Vector process, that the bucket and prefix match your environment variables, and that IAM allows object creation for the selected bucket or prefix.
+If events do not appear, verify that Vector reads the same local paths Beacon
+writes, that `GOOGLE_APPLICATION_CREDENTIALS` points to a root-readable
+service-account JSON file, that the bucket and root prefix match the service
+environment, and that IAM allows object creation. Do not use a writer-side
+`gcloud storage ls` failure as proof that upload failed:
+`roles/storage.objectCreator` cannot inspect objects.
+
+## Packaged macOS deployment
+
+The signed package includes:
+
+```text
+/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
+```
+
+Follow [macOS System-Mode Object Storage Forwarding](/guides/macos-object-storage-system)
+for a harness-neutral single-Mac deployment or
+[Claude with Jamf and GCS](/guides/jamf-gcs-mdm) for the Claude-oriented managed
+convenience workflow. The `/opt/beacon/jamf/claude/gcs/` package path is
+historical; `install-forwarder.sh` tails shared system logs and does not depend
+on Claude.
## Content Handling
-Beacon applies redaction, sanitization, truncation, and event-size limits before events are written to `runtime.jsonl` and forwarded to GCS. Review bucket access, lifecycle, retention, and downstream consumers so retained telemetry matches your approved collection policy.
+Beacon applies redaction, sanitization, truncation, and event-size limits before
+events are written to local runtime or inventory JSONL and forwarded to GCS.
+Review bucket access, lifecycle, retention, and downstream consumers so retained
+telemetry matches your approved collection policy.
## Related
<Columns cols={2}>
+ <Card title="macOS system-mode object storage" icon="desktop" href="/guides/macos-object-storage-system">
+ Install harness-neutral GCS or S3 forwarding on one Mac.
+ </Card>
<Card title="beacon endpoint gcs" icon="terminal" href="/cli/gcs">
Review Google Cloud Storage command syntax, flags, and examples.
</Card>
diff --git a/docs/log-forwarding/index.mdx b/docs/log-forwarding/index.mdx
index 42fb52dc..b4899ab7 100644
--- a/docs/log-forwarding/index.mdx
+++ b/docs/log-forwarding/index.mdx
@@ -77,11 +77,14 @@ Use these paths when Beacon JSONL feeds an observability store or customer-manag
Use these paths when Beacon JSONL should land in a customer-managed bucket for archive, lake, or downstream detection workflows.
<Columns cols={2}>
+ <Card title="macOS system-mode setup" icon="desktop" href="/guides/macos-object-storage-system">
+ Configure harness-neutral S3, GCS, or dual forwarding on one Mac.
+ </Card>
<Card title="AWS S3" icon="box-archive" href="/log-forwarding/s3">
Vector content pack over local JSONL using customer-managed AWS credentials.
</Card>
<Card title="Google Cloud Storage" icon="box-archive" href="/log-forwarding/gcs">
- Vector content pack over local JSONL using customer-managed Google credentials.
+ Vector content pack over runtime and inventory JSONL using customer-managed Google credentials.
</Card>
</Columns>
@@ -233,13 +236,21 @@ For Google Cloud Storage, generate Beacon's GCS content pack and configure a cus
beacon endpoint gcs install-pack --system --output ./beacon-gcs-pack
```
-The generated pack includes setup guidance, a Vector `gcp_cloud_storage` sink template, a one-shot `gcloud storage` or `gsutil` smoke-test script, and sample events. Google Cloud credentials, service accounts, workload identity, bucket IAM, lifecycle, retention, and encryption stay in Google Cloud, Vector, endpoint-management tooling, or your secret store rather than Beacon endpoint configuration.
+The generated pack includes setup guidance, a Vector `gcp_cloud_storage` sink
+template, a one-shot `gcloud storage` or `gsutil` smoke-test script, and sample
+events. Packaged macOS helpers forward runtime and inventory JSONL under
+separate folders below one root prefix and run as
+`com.beacon.endpoint.gcs-forwarder`. Deliver a service-account JSON externally,
+store it outside Beacon-managed directories, and reference it with
+`GOOGLE_APPLICATION_CREDENTIALS`.
-See [Google Cloud Storage forwarding](/log-forwarding/gcs) for IAM, object layout, Vector setup, smoke testing, and validation steps.
+See [Google Cloud Storage forwarding](/log-forwarding/gcs) for IAM, object
+layout, Vector `0.56` authentication limits, safe credential delivery and
+rotation, smoke testing, and validation with a separate reader identity.
### Vector log forwarding
-Beacon `v0.0.26` added generated Vector configs to the Sumo Logic and Rapid7 content packs, Beacon `v0.0.37` added a Vector [AWS S3 content pack](/concepts/core-concepts#aws-s3-content-pack), Beacon `v0.0.38` added a Vector [Google Cloud Storage content pack](/concepts/core-concepts#google-cloud-storage-content-pack), Beacon `v0.0.42` added a Vector [AWS CloudWatch Logs content pack](/concepts/core-concepts#aws-cloudwatch-logs-content-pack), and Beacon `v0.0.49` added a CrowdStrike Falcon Vector path. Use these templates when you want [Vector forwarding](/concepts/core-concepts#vector-forwarding) to tail Beacon's local `runtime.jsonl` and forward events without storing destination secrets in Beacon endpoint configuration.
+Beacon `v0.0.26` added generated Vector configs to the Sumo Logic and Rapid7 content packs, Beacon `v0.0.37` added a Vector [AWS S3 content pack](/concepts/core-concepts#aws-s3-content-pack), Beacon `v0.0.38` added a Vector [Google Cloud Storage content pack](/concepts/core-concepts#google-cloud-storage-content-pack), Beacon `v0.0.42` added a Vector [AWS CloudWatch Logs content pack](/concepts/core-concepts#aws-cloudwatch-logs-content-pack), and Beacon `v0.0.49` added a CrowdStrike Falcon Vector path. Use these templates when you want [Vector forwarding](/concepts/core-concepts#vector-forwarding) to tail Beacon's local JSONL streams and forward events without storing destination secrets in Beacon endpoint configuration.
```bash title="Generate the integration pack"
beacon endpoint sumo install-pack --system --output ./beacon-sumo-pack
diff --git a/docs/log-forwarding/s3.mdx b/docs/log-forwarding/s3.mdx
index e4d47357..fb0babf9 100644
--- a/docs/log-forwarding/s3.mdx
+++ b/docs/log-forwarding/s3.mdx
@@ -5,7 +5,7 @@ description: "Forward Beacon endpoint events into AWS S3 with customer-managed V
## Forwarding Overview
-Beacon `v0.0.37` added the [AWS S3 content pack](/concepts/core-concepts#aws-s3-content-pack) for teams that want Beacon endpoint events stored in an S3 bucket for data lake, SIEM, archive, or downstream detection workflows. Beacon remains the local JSONL producer and writes one source of truth, the active [runtime JSONL log](/concepts/core-concepts#runtime-jsonl-log). Your customer-managed [Vector forwarding](/concepts/core-concepts#vector-forwarding) agent tails that file and uploads gzip-compressed NDJSON objects to S3.
+Beacon `v0.0.37` added the [AWS S3 content pack](/concepts/core-concepts#aws-s3-content-pack) for teams that want Beacon endpoint events stored in an S3 bucket for data lake, SIEM, archive, or downstream detection workflows. Beacon remains the local JSONL producer. Your customer-managed [Vector forwarding](/concepts/core-concepts#vector-forwarding) agent tails runtime activity and the sibling inventory stream and uploads gzip-compressed NDJSON objects to S3.
Use this path when you want Beacon events forwarded to S3 without storing AWS credentials, bucket policy, lifecycle, retention, or encryption settings in Beacon endpoint configuration.
@@ -21,7 +21,7 @@ Use system mode for MDM deployments so Vector can tail `/var/log/beacon-agent/ru
## Prerequisites
- Beacon endpoint installed and writing local JSONL.
-- An AWS S3 bucket for Beacon runtime logs.
+- An AWS S3 bucket for Beacon runtime and inventory logs.
- Vector installed or deployable through your endpoint-management tooling.
- An IAM role or credentials available through the standard AWS credential provider chain for the process running Vector or the AWS CLI smoke test.
@@ -29,6 +29,7 @@ Recommended object layout:
```text
s3://example-security-logs/beacon/runtime/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
+s3://example-security-logs/beacon/inventory/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
```
Example least-privilege IAM policy for a dedicated Beacon prefix:
@@ -40,7 +41,7 @@ Example least-privilege IAM policy for a dedicated Beacon prefix:
{
"Effect": "Allow",
"Action": ["s3:PutObject"],
- "Resource": "arn:aws:s3:::example-security-logs/beacon/runtime/*"
+ "Resource": "arn:aws:s3:::example-security-logs/beacon/*"
}
]
}
@@ -73,7 +74,7 @@ Use the generated smoke-test script to upload the current runtime log once. This
```bash title="Command example"
export BEACON_S3_BUCKET="example-security-logs"
-export BEACON_S3_PREFIX="beacon/runtime"
+export BEACON_S3_PREFIX="beacon"
export AWS_REGION="us-east-1"
./beacon-s3-pack/s3-upload-smoke-test.sh
```
@@ -83,31 +84,33 @@ The script uses `aws s3 cp` and the standard AWS credential provider chain. You
Confirm the uploaded object:
```bash title="Confirm the uploaded object"
-aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/smoke-tests/" --region "$AWS_REGION"
-aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/smoke-tests/<object>.jsonl" - --region "$AWS_REGION" | grep "Beacon endpoint S3 validation event"
+aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/smoke-tests/" --region "$AWS_REGION"
+aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/smoke-tests/<object>.jsonl" - --region "$AWS_REGION" | grep "Beacon endpoint S3 validation event"
```
## Production forwarding
-For production, use the generated Vector config as a customer-managed host-agent forwarding template. Beacon remains the local JSONL producer; Vector tails `runtime.jsonl`, checkpoints file offsets in its `data_dir`, batches Beacon events, and writes gzip-compressed newline-delimited JSON objects into AWS S3.
+For production, use the generated Vector config as a customer-managed host-agent forwarding template. Beacon remains the local JSONL producer; Vector tails `runtime.jsonl` and `inventory_state.jsonl`, checkpoints file offsets in its `data_dir`, batches Beacon events, and writes gzip-compressed newline-delimited JSON objects into AWS S3.
```mermaid
flowchart LR
agentHarnesses["Agent harnesses"] -->|"OTLP or hooks"| beaconEndpoint["Beacon endpoint agent"]
- beaconEndpoint -->|"writes normalized events"| runtimeLog["runtime.jsonl"]
+ beaconEndpoint -->|"writes activity"| runtimeLog["runtime.jsonl"]
+ beaconEndpoint -->|"writes inventory"| inventoryLog["inventory_state.jsonl"]
runtimeLog -->|"file source tails active path"| vectorAgent["Vector host agent"]
+ inventoryLog -->|"file source tails active path"| vectorAgent
vectorAgent -->|"parse_json, gzip NDJSON"| s3Bucket["AWS S3 bucket"]
s3Bucket -->|"partitioned objects"| downstreamSiem["SIEM, lake, or archive workflow"]
endpointMgmt["MDM or secret tooling"] -->|"bucket, prefix, region, AWS credentials"| vectorAgent
```
-Install Vector using your normal endpoint management tooling, then copy the generated config into Vector's config directory. On a macOS system-mode Beacon deployment, the generated config tails `/var/log/beacon-agent/runtime.jsonl`:
+Install Vector using your normal endpoint management tooling, then copy the generated config into Vector's config directory. On a macOS system-mode Beacon deployment, the generated config tails `/var/log/beacon-agent/runtime.jsonl` and `/var/log/beacon-agent/inventory_state.jsonl`:
```bash title="Install Vector using your normal endpoint management tooling, then copy the generated config into Vector's config directory. On a macOS system-mode Beacon deployment, the generated config tails /var/log/beacon-agent/runtime.jsonl"
sudo mkdir -p /etc/vector
sudo cp ./beacon-s3-pack/vector.toml /etc/vector/beacon-s3.toml
export BEACON_S3_BUCKET="example-security-logs"
-export BEACON_S3_PREFIX="beacon/runtime"
+export BEACON_S3_PREFIX="beacon"
export AWS_REGION="us-east-1"
vector validate /etc/vector/beacon-s3.toml
vector --config /etc/vector/beacon-s3.toml
@@ -150,7 +153,7 @@ Run the one-shot smoke test or wait for your production forwarder to ship the ne
```bash title="Run the one-shot smoke test or wait for your production forwarder to ship the new line. Beacon can write the local validation event, but remote delivery must be confirmed with AWS tooling"
aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/" --recursive --region "$AWS_REGION"
-aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/date=<date>/<object>.jsonl.gz" - --region "$AWS_REGION" | gzip -dc | grep "Beacon endpoint S3 validation event"
+aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/date=<date>/<object>.jsonl.gz" - --region "$AWS_REGION" | gzip -dc | grep "Beacon endpoint S3 validation event"
```
Expected validation fields:
@@ -163,11 +166,17 @@ If events do not appear, verify that Vector is reading the same runtime log path
## Content Handling
-Beacon applies redaction, sanitization, truncation, and event-size limits before events are written to `runtime.jsonl` and forwarded to S3. Review bucket access, lifecycle, retention, and downstream consumers so retained telemetry matches your approved collection policy.
+Beacon applies redaction, sanitization, truncation, and event-size limits before
+events are written to local runtime or inventory JSONL and forwarded to S3.
+Review bucket access, lifecycle, retention, and downstream consumers so retained
+telemetry matches your approved collection policy.
## Related
<Columns cols={2}>
+ <Card title="macOS system-mode object storage" icon="desktop" href="/guides/macos-object-storage-system">
+ Install harness-neutral S3 or GCS forwarding on one Mac.
+ </Card>
<Card title="beacon endpoint s3" icon="terminal" href="/cli/s3">
Review AWS S3 command syntax, flags, and examples.
</Card>
diff --git a/docs/mdm/jamf.mdx b/docs/mdm/jamf.mdx
index 33b13887..4dc70b94 100644
--- a/docs/mdm/jamf.mdx
+++ b/docs/mdm/jamf.mdx
@@ -23,10 +23,12 @@ The macOS package includes Beacon binaries, endpoint helper scripts, and Jamf as
```text
/opt/beacon/bin/beacon
/opt/beacon/bin/beacon-otelcol
+/opt/beacon/bin/vector
/opt/beacon/scripts/install-endpoint.sh
/opt/beacon/scripts/uninstall-endpoint.sh
/opt/beacon/jamf/extension-attributes/*.sh
/opt/beacon/jamf/scripts/*.sh
+/opt/beacon/jamf/claude/gcs/*.sh
```
The package postinstall performs the default system install. That install creates system configuration and runtime state:
@@ -145,6 +147,15 @@ Suggested Smart Groups:
Use `/opt/beacon/jamf/scripts/install-cursor-hooks.sh` as a separate user-context policy for hook telemetry. Set `BEACON_HOOK_HARNESSES=antigravity,claude,cursor,devin-cli,devin-desktop,factory,grok,hermes,opencode` when you want Antigravity CLI, Claude Code, Cursor, Devin CLI, Devin Desktop, Factory, Grok Build, Hermes Agent, and OpenCode hook integrations. Hook configuration is per user and should run only when an interactive console user is present. Gemini CLI is configured through the endpoint harness list instead; add `gemini` to Jamf parameter 4, for example `claude,codex,gemini`. GitHub Copilot CLI is MDM-managed outside the Beacon harness list; configure `COPILOT_OTEL_ENABLED=true` and `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318` in Copilot's launch environment. OpenClaw Gateway is configured in OpenClaw, not through Jamf hook helpers.
+For Google Cloud Storage, the package includes
+`/opt/beacon/jamf/claude/gcs/{install-forwarder.sh,run-forwarder.sh,repair-hooks-and-forwarder.sh}`.
+The combined helper configures runtime and inventory forwarding under one root
+prefix and starts `com.beacon.endpoint.gcs-forwarder`. Deliver the required
+service-account JSON with Jamf secret/file tooling to a root-owned path outside
+Beacon-managed directories, then pass only its path through
+`GOOGLE_APPLICATION_CREDENTIALS`. Follow the
+[Jamf GCS guide](/guides/jamf-gcs-mdm) for exact Google Cloud and policy steps.
+
## Troubleshooting
<AccordionGroup>
@@ -278,6 +289,9 @@ Use `/opt/beacon/jamf/scripts/uninstall.sh` to remove endpoint service files. Se
## Related
<Columns cols={2}>
+ <Card title="Claude with Jamf and GCS" icon="bucket" href="/guides/jamf-gcs-mdm">
+ Deploy Beacon and forward runtime plus inventory telemetry to GCS.
+ </Card>
<Card title="Anthropic, OpenAI, and Cursor with Jamf and S3" icon="bucket" href="/guides/jamf-anthropic-openai-cursor-mdm">
Deploy Beacon with Jamf and forward Claude Code, Codex CLI, and Cursor telemetry to S3.
</Card>
diff --git a/docs/mdm/jamf/claude.mdx b/docs/mdm/jamf/claude.mdx
index 5f736c6e..4e05205a 100644
--- a/docs/mdm/jamf/claude.mdx
+++ b/docs/mdm/jamf/claude.mdx
@@ -6,6 +6,9 @@ description: "Deploy Claude Code endpoint telemetry with Jamf Pro and route Beac
Use this page as the Claude-specific Jamf entry point. For complete managed forwarding setup, follow the destination-specific self-serve guide:
<Columns cols={2}>
+ <Card title="Deploy Beacon With Jamf And GCS" icon="bucket" href="/guides/jamf-gcs-mdm">
+ Install Beacon with Jamf Pro, deliver a Google service-account JSON through managed secret tooling, and forward runtime plus inventory JSONL to GCS.
+ </Card>
<Card title="Deploy Beacon With Jamf And S3" icon="bucket" href="/guides/jamf-s3-mdm">
Install Beacon with Jamf Pro, inject AWS provider settings through MDM, configure Claude Code hooks, and forward runtime plus inventory JSONL to S3.
</Card>
@@ -32,6 +35,9 @@ The macOS package includes these Claude-specific helpers:
```text
/opt/beacon/jamf/claude/common/repair-hooks.sh
+/opt/beacon/jamf/claude/gcs/install-forwarder.sh
+/opt/beacon/jamf/claude/gcs/repair-hooks-and-forwarder.sh
+/opt/beacon/jamf/claude/gcs/run-forwarder.sh
/opt/beacon/jamf/claude/s3/install-forwarder.sh
/opt/beacon/jamf/claude/s3/repair-hooks-and-forwarder.sh
/opt/beacon/jamf/claude/s3/run-forwarder.sh
@@ -42,6 +48,10 @@ The macOS package includes these Claude-specific helpers:
Use `repair-hooks.sh` when you only need to repair the system endpoint and reinstall Claude hooks.
+Use `gcs/repair-hooks-and-forwarder.sh` when one Jamf policy should repair the
+endpoint, reinstall Claude hooks, and configure GCS runtime and inventory
+forwarding through `com.beacon.endpoint.gcs-forwarder`.
+
Use `s3/repair-hooks-and-forwarder.sh` when one Jamf policy should repair the endpoint, reinstall Claude hooks, and configure S3 forwarding.
Use `falcon/repair-hooks-and-forwarder.sh` when one Jamf policy should repair the endpoint, reinstall Claude hooks, and configure CrowdStrike Falcon LogScale HEC forwarding.
@@ -55,6 +65,9 @@ Use `falcon/repair-hooks-and-forwarder.sh` when one Jamf policy should repair th
<Card title="S3 Log Forwarding" icon="bucket" href="/log-forwarding/s3">
Review the generated S3 content pack and Vector forwarding behavior.
</Card>
+ <Card title="GCS Log Forwarding" icon="bucket" href="/log-forwarding/gcs">
+ Review GCS IAM, root-prefix layout, service-account delivery, and validation.
+ </Card>
<Card title="CrowdStrike Falcon LogScale" icon="shield-halved" href="/log-forwarding/falcon">
Review Falcon parser setup, HEC settings, and validation steps.
</Card>
diff --git a/packaging/macos/README.md b/packaging/macos/README.md
index 9d012896..fb00c268 100644
--- a/packaging/macos/README.md
+++ b/packaging/macos/README.md
@@ -21,6 +21,9 @@ 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/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/queries/*.sql
/opt/beacon/fleet/scripts/*.sh
```
@@ -188,6 +191,31 @@ helper persists set AWS provider-chain variables such as `AWS_ACCESS_KEY_ID`,
for the launchd-managed Vector process. Keep bucket policy, IAM, lifecycle, and
encryption in AWS.
+For Google Cloud Storage, the package includes a managed Vector path equivalent
+to S3. It tails `/var/log/beacon-agent/runtime.jsonl` and the sibling
+`inventory_state.jsonl`, then writes both below one root prefix:
+
+```text
+gs://<bucket>/<prefix>/runtime/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
+gs://<bucket>/<prefix>/inventory/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
+```
+
+Run `/opt/beacon/jamf/claude/gcs/install-forwarder.sh` for forwarding only, or
+`/opt/beacon/jamf/claude/gcs/repair-hooks-and-forwarder.sh` to repair the
+endpoint and Claude hooks too. The service label is
+`com.beacon.endpoint.gcs-forwarder`; its config, environment, and checkpoint
+state live below `/Library/Application Support/Beacon/Forwarders`.
+
+Provide `BEACON_GCS_BUCKET`, a root `BEACON_GCS_PREFIX`, optional
+`BEACON_GCS_STORAGE_CLASS`, and `GOOGLE_APPLICATION_CREDENTIALS`. The latter
+must reference a readable service-account JSON file delivered and rotated by
+MDM or secret tooling outside `/opt/beacon` and
+`/Library/Application Support/Beacon`. Vector `0.56` supports service-account
+JSON and GCE metadata credentials, but interactive `gcloud` ADC and Workload
+Identity Federation are not reliable launchd authentication contracts on
+macOS. Use `roles/storage.objectCreator` for the endpoint writer and a separate
+reader identity because the writer cannot list or inspect uploaded objects.
+
For CrowdStrike Falcon, use Beacon as the local JSONL producer and deploy Vector
to tail hook-written or OTLP-written `runtime.jsonl` events into the Falcon HEC
connector. Generate Beacon's Falcon content pack for setup guidance, a Vector
@@ -384,6 +412,15 @@ policy for hook telemetry. Set
integrations; the helper writes hook events to
`/var/log/beacon-agent/runtime.jsonl` by default.
+Use `/opt/beacon/jamf/scripts/full-cleanup.sh` only for destructive rollback or
+complete uninstall. It removes Beacon launch daemons, package files, system
+configuration, optional forwarder configuration, package receipts, and
+Beacon-managed active-user hook/OTLP settings. It backs up touched user config
+files before editing them and only removes Claude/Codex OTLP settings that point
+to local Beacon endpoints. Set `BEACON_KEEP_LOGS=1` to preserve
+`/var/log/beacon-agent`, or `BEACON_CLEAN_ALL_USERS=1` to scan all local user
+homes instead of only the active console user.
+
Use `/opt/beacon/jamf/claude/common/repair-hooks.sh` when a Jamf policy
needs only to repair the system endpoint, prepare
`/var/log/beacon-agent/runtime.jsonl`,
@@ -437,12 +474,28 @@ Set `BEACON_RUNTIME_LOG_PATHS` to override the tailed runtime logs. The S3
forwarder derives an `inventory_state.jsonl` path beside each runtime path and
ships those inventory files under the `inventory/` S3 folder.
+`gcs/install-forwarder.sh` Jamf script parameters:
+
+```text
+Parameter 4: GCS bucket
+Parameter 5: GCS prefix root, default beacon
+Parameter 6: GCS storage class, default STANDARD
+Parameter 7: Vector read_from, default end
+```
+
+Set `GOOGLE_APPLICATION_CREDENTIALS` in the root policy environment. The GCS
+forwarder derives an `inventory_state.jsonl` path beside each runtime path and
+ships those inventory files under the `inventory/` GCS folder.
+
The Jamf Claude helper source paths map into the package as:
- [`packaging/macos/jamf/claude/common/repair-hooks.sh`](https://github.com/Asymptote-Labs/agent-beacon/blob/main/packaging/macos/jamf/claude/common/repair-hooks.sh) -> `/opt/beacon/jamf/claude/common/repair-hooks.sh`
- [`packaging/macos/jamf/claude/falcon/install-forwarder.sh`](https://github.com/Asymptote-Labs/agent-beacon/blob/main/packaging/macos/jamf/claude/falcon/install-forwarder.sh) -> `/opt/beacon/jamf/claude/falcon/install-forwarder.sh`
- [`packaging/macos/jamf/claude/falcon/repair-hooks-and-forwarder.sh`](https://github.com/Asymptote-Labs/agent-beacon/blob/main/packaging/macos/jamf/claude/falcon/repair-hooks-and-forwarder.sh) -> `/opt/beacon/jamf/claude/falcon/repair-hooks-and-forwarder.sh`
- [`packaging/macos/jamf/claude/falcon/run-forwarder.sh`](https://github.com/Asymptote-Labs/agent-beacon/blob/main/packaging/macos/jamf/claude/falcon/run-forwarder.sh) -> `/opt/beacon/jamf/claude/falcon/run-forwarder.sh`
+- [`packaging/macos/jamf/claude/gcs/install-forwarder.sh`](https://github.com/Asymptote-Labs/agent-beacon/blob/main/packaging/macos/jamf/claude/gcs/install-forwarder.sh) -> `/opt/beacon/jamf/claude/gcs/install-forwarder.sh`
+- [`packaging/macos/jamf/claude/gcs/repair-hooks-and-forwarder.sh`](https://github.com/Asymptote-Labs/agent-beacon/blob/main/packaging/macos/jamf/claude/gcs/repair-hooks-and-forwarder.sh) -> `/opt/beacon/jamf/claude/gcs/repair-hooks-and-forwarder.sh`
+- [`packaging/macos/jamf/claude/gcs/run-forwarder.sh`](https://github.com/Asymptote-Labs/agent-beacon/blob/main/packaging/macos/jamf/claude/gcs/run-forwarder.sh) -> `/opt/beacon/jamf/claude/gcs/run-forwarder.sh`
- [`packaging/macos/jamf/claude/s3/install-forwarder.sh`](https://github.com/Asymptote-Labs/agent-beacon/blob/main/packaging/macos/jamf/claude/s3/install-forwarder.sh) -> `/opt/beacon/jamf/claude/s3/install-forwarder.sh`
- [`packaging/macos/jamf/claude/s3/repair-hooks-and-forwarder.sh`](https://github.com/Asymptote-Labs/agent-beacon/blob/main/packaging/macos/jamf/claude/s3/repair-hooks-and-forwarder.sh) -> `/opt/beacon/jamf/claude/s3/repair-hooks-and-forwarder.sh`
- [`packaging/macos/jamf/claude/s3/run-forwarder.sh`](https://github.com/Asymptote-Labs/agent-beacon/blob/main/packaging/macos/jamf/claude/s3/run-forwarder.sh) -> `/opt/beacon/jamf/claude/s3/run-forwarder.sh`
@@ -454,6 +507,10 @@ The managed forwarder writes:
/Library/Application Support/Beacon/Forwarders/falcon-vector.env
/Library/Application Support/Beacon/Forwarders/vector-data/falcon
/Library/LaunchDaemons/com.beacon.endpoint.falcon-forwarder.plist
+/Library/Application Support/Beacon/Forwarders/gcs-vector.toml
+/Library/Application Support/Beacon/Forwarders/gcs-vector.env
+/Library/Application Support/Beacon/Forwarders/vector-data/gcs
+/Library/LaunchDaemons/com.beacon.endpoint.gcs-forwarder.plist
```
Validate hook-only forwarding by generating a unique Claude prompt and searching
diff --git a/packaging/macos/jamf/claude/gcs/install-forwarder.sh b/packaging/macos/jamf/claude/gcs/install-forwarder.sh
new file mode 100755
index 00000000..01ef5170
--- /dev/null
+++ b/packaging/macos/jamf/claude/gcs/install-forwarder.sh
@@ -0,0 +1,358 @@
+#!/bin/sh
+set -eu
+
+LABEL="${BEACON_GCS_FORWARDER_LABEL:-com.beacon.endpoint.gcs-forwarder}"
+VECTOR_BIN="${BEACON_VECTOR_BIN:-/opt/beacon/bin/vector}"
+WRAPPER="${BEACON_GCS_FORWARDER_WRAPPER:-/opt/beacon/jamf/claude/gcs/run-forwarder.sh}"
+BASE_DIR="${BEACON_FORWARDER_BASE_DIR:-/Library/Application Support/Beacon/Forwarders}"
+LAUNCHDAEMONS_DIR="${BEACON_LAUNCHDAEMONS_DIR:-/Library/LaunchDaemons}"
+CONFIG_PATH="${BEACON_GCS_VECTOR_CONFIG:-$BASE_DIR/gcs-vector.toml}"
+ENV_PATH="${BEACON_GCS_VECTOR_ENV:-$BASE_DIR/gcs-vector.env}"
+DATA_DIR="${BEACON_GCS_VECTOR_DATA_DIR:-$BASE_DIR/vector-data/gcs}"
+PLIST_PATH="$LAUNCHDAEMONS_DIR/$LABEL.plist"
+CONFIG_TMP="${CONFIG_PATH}.tmp.$$.toml"
+ENV_TMP="${ENV_PATH}.tmp.$$"
+PLIST_TMP="${PLIST_PATH}.tmp.$$"
+
+GCS_BUCKET="${BEACON_GCS_BUCKET:-${4:-}}"
+GCS_PREFIX="${BEACON_GCS_PREFIX:-${5:-beacon}}"
+GCS_STORAGE_CLASS="${BEACON_GCS_STORAGE_CLASS:-${6:-STANDARD}}"
+VECTOR_READ_FROM="${BEACON_VECTOR_READ_FROM:-${7:-end}}"
+RUNTIME_LOG_PATHS="${BEACON_RUNTIME_LOG_PATHS:-/var/log/beacon-agent/runtime.jsonl}"
+CREDENTIALS_PATH="${GOOGLE_APPLICATION_CREDENTIALS:-}"
+NO_START="${BEACON_NO_START:-0}"
+STOP_ATTEMPTS="${BEACON_FORWARDER_STOP_ATTEMPTS:-65}"
+START_ATTEMPTS="${BEACON_FORWARDER_START_ATTEMPTS:-15}"
+
+GCS_PREFIX="${GCS_PREFIX%/}"
+case "$GCS_PREFIX" in
+ */runtime)
+ GCS_PREFIX="${GCS_PREFIX%/runtime}"
+ ;;
+ */inventory)
+ GCS_PREFIX="${GCS_PREFIX%/inventory}"
+ ;;
+esac
+GCS_PREFIX="${GCS_PREFIX%/}"
+if [ -z "$GCS_PREFIX" ]; then
+ GCS_PREFIX="beacon"
+fi
+
+if [ -z "$GCS_BUCKET" ]; then
+ echo "GCS bucket is required (BEACON_GCS_BUCKET or Jamf parameter 4)" >&2
+ exit 1
+fi
+
+if [ -z "$CREDENTIALS_PATH" ]; then
+ echo "GOOGLE_APPLICATION_CREDENTIALS must point to a service-account JSON file" >&2
+ exit 1
+fi
+case "$CREDENTIALS_PATH" in
+ /*) ;;
+ *)
+ echo "GOOGLE_APPLICATION_CREDENTIALS must be an absolute path for launchd" >&2
+ exit 1
+ ;;
+esac
+if [ ! -r "$CREDENTIALS_PATH" ]; then
+ echo "Google credentials file is not readable at $CREDENTIALS_PATH" >&2
+ exit 1
+fi
+if [ "$(uname -s)" = "Darwin" ] && [ "$(id -u)" -eq 0 ]; then
+ credentials_owner="$(stat -f '%Su' "$CREDENTIALS_PATH")"
+ credentials_mode="$(stat -f '%Lp' "$CREDENTIALS_PATH")"
+ if [ "$credentials_owner" != "root" ]; then
+ echo "Google credentials file must be owned by root: $CREDENTIALS_PATH" >&2
+ exit 1
+ fi
+ case "$credentials_mode" in
+ 400|600) ;;
+ *)
+ echo "Google credentials file must have mode 0400 or 0600: $CREDENTIALS_PATH" >&2
+ exit 1
+ ;;
+ esac
+fi
+
+if [ ! -x "$VECTOR_BIN" ]; then
+ echo "Vector binary not found or not executable at $VECTOR_BIN" >&2
+ exit 1
+fi
+if [ ! -x "$WRAPPER" ]; then
+ echo "GCS forwarder wrapper not found or not executable at $WRAPPER" >&2
+ exit 1
+fi
+
+"$VECTOR_BIN" --version >/dev/null
+
+shell_quote() {
+ printf "'%s'" "$(printf '%s' "$1" | sed "s/'/'\\\\''/g")"
+}
+
+write_env_if_set() {
+ name="$1"
+ eval "value=\${$name:-}"
+ if [ -n "$value" ]; then
+ printf 'export %s=%s\n' "$name" "$(shell_quote "$value")"
+ fi
+}
+
+toml_quote() {
+ printf '"%s"' "$(printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+}
+
+xml_escape() {
+ printf '%s' "$1" | sed 's/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g; s/"/\&quot;/g'
+}
+
+include_array() {
+ paths="$1"
+ old_ifs="$IFS"
+ IFS=,
+ first=1
+ printf '['
+ for raw in $paths; do
+ path="$(printf '%s' "$raw" | sed 's/^ *//; s/ *$//')"
+ [ -n "$path" ] || continue
+ if [ "$first" -eq 0 ]; then
+ printf ', '
+ fi
+ toml_quote "$path"
+ first=0
+ case "$path" in
+ *'*'*|*'?'*|*'['*) ;;
+ *)
+ mkdir -p "$(dirname "$path")"
+ touch "$path"
+ chmod 0644 "$path" || true
+ ;;
+ esac
+ done
+ printf ']'
+ IFS="$old_ifs"
+}
+
+inventory_paths() {
+ old_ifs="$IFS"
+ IFS=,
+ first=1
+ for raw in $RUNTIME_LOG_PATHS; do
+ path="$(printf '%s' "$raw" | sed 's/^ *//; s/ *$//')"
+ [ -n "$path" ] || continue
+ if [ "$first" -eq 0 ]; then
+ printf ','
+ fi
+ printf '%s/inventory_state.jsonl' "$(dirname "$path")"
+ first=0
+ done
+ IFS="$old_ifs"
+}
+
+cleanup_temp_files() {
+ rm -f "$CONFIG_TMP" "$ENV_TMP" "$PLIST_TMP"
+}
+trap cleanup_temp_files EXIT
+trap 'exit 1' INT TERM
+
+mkdir -p "$BASE_DIR" "$DATA_DIR" "$LAUNCHDAEMONS_DIR"
+chmod 0755 "$BASE_DIR" "$DATA_DIR" "$LAUNCHDAEMONS_DIR" 2>/dev/null || true
+
+RUNTIME_INCLUDES="$(include_array "$RUNTIME_LOG_PATHS")"
+INVENTORY_LOG_PATHS="$(inventory_paths)"
+INVENTORY_INCLUDES="$(include_array "$INVENTORY_LOG_PATHS")"
+
+cat >"$CONFIG_TMP" <<EOF
+# Managed by Beacon. Do not edit by hand.
+# Google credentials are resolved from GOOGLE_APPLICATION_CREDENTIALS.
+data_dir = "$(printf '%s' "$DATA_DIR" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+
+[sources.beacon_runtime]
+type = "file"
+include = $RUNTIME_INCLUDES
+read_from = "\${BEACON_VECTOR_READ_FROM:-end}"
+
+[sources.beacon_inventory]
+type = "file"
+include = $INVENTORY_INCLUDES
+read_from = "beginning"
+
+[transforms.beacon_runtime_json]
+type = "remap"
+inputs = ["beacon_runtime"]
+source = '''
+. = parse_json!(.message)
+'''
+
+[transforms.beacon_inventory_json]
+type = "remap"
+inputs = ["beacon_inventory"]
+source = '''
+. = parse_json!(.message)
+'''
+
+[sinks.beacon_runtime_gcs]
+type = "gcp_cloud_storage"
+inputs = ["beacon_runtime_json"]
+bucket = "\${BEACON_GCS_BUCKET}"
+key_prefix = "\${BEACON_GCS_PREFIX:-beacon}/runtime/date=%F/"
+filename_time_format = "%s"
+filename_append_uuid = true
+filename_extension = "jsonl.gz"
+compression = "gzip"
+content_encoding = "gzip"
+content_type = "application/x-ndjson"
+storage_class = "\${BEACON_GCS_STORAGE_CLASS:-STANDARD}"
+
+[sinks.beacon_runtime_gcs.encoding]
+codec = "json"
+
+[sinks.beacon_runtime_gcs.framing]
+method = "newline_delimited"
+
+[sinks.beacon_runtime_gcs.batch]
+max_bytes = 10000000
+timeout_secs = 300
+
+[sinks.beacon_runtime_gcs.request]
+retry_attempts = 10
+retry_initial_backoff_secs = 1
+retry_max_duration_secs = 300
+
+[sinks.beacon_runtime_gcs.healthcheck]
+enabled = false
+
+[sinks.beacon_inventory_gcs]
+type = "gcp_cloud_storage"
+inputs = ["beacon_inventory_json"]
+bucket = "\${BEACON_GCS_BUCKET}"
+key_prefix = "\${BEACON_GCS_PREFIX:-beacon}/inventory/date=%F/"
+filename_time_format = "%s"
+filename_append_uuid = true
+filename_extension = "jsonl.gz"
+compression = "gzip"
+content_encoding = "gzip"
+content_type = "application/x-ndjson"
+storage_class = "\${BEACON_GCS_STORAGE_CLASS:-STANDARD}"
+
+[sinks.beacon_inventory_gcs.encoding]
+codec = "json"
+
+[sinks.beacon_inventory_gcs.framing]
+method = "newline_delimited"
+
+[sinks.beacon_inventory_gcs.batch]
+max_bytes = 10000000
+timeout_secs = 300
+
+[sinks.beacon_inventory_gcs.request]
+retry_attempts = 10
+retry_initial_backoff_secs = 1
+retry_max_duration_secs = 300
+
+[sinks.beacon_inventory_gcs.healthcheck]
+enabled = false
+EOF
+chmod 0644 "$CONFIG_TMP"
+
+{
+ printf 'export BEACON_GCS_BUCKET=%s\n' "$(shell_quote "$GCS_BUCKET")"
+ printf 'export BEACON_GCS_PREFIX=%s\n' "$(shell_quote "$GCS_PREFIX")"
+ printf 'export BEACON_GCS_STORAGE_CLASS=%s\n' "$(shell_quote "$GCS_STORAGE_CLASS")"
+ printf 'export BEACON_VECTOR_READ_FROM=%s\n' "$(shell_quote "$VECTOR_READ_FROM")"
+ printf 'export GOOGLE_APPLICATION_CREDENTIALS=%s\n' "$(shell_quote "$CREDENTIALS_PATH")"
+ write_env_if_set GOOGLE_CLOUD_PROJECT
+ write_env_if_set CLOUDSDK_CORE_PROJECT
+} >"$ENV_TMP"
+chmod 0600 "$ENV_TMP"
+
+# Validate syntax with the same environment the launch daemon will receive.
+BEACON_GCS_BUCKET="$GCS_BUCKET" \
+BEACON_GCS_PREFIX="$GCS_PREFIX" \
+BEACON_GCS_STORAGE_CLASS="$GCS_STORAGE_CLASS" \
+BEACON_VECTOR_READ_FROM="$VECTOR_READ_FROM" \
+GOOGLE_APPLICATION_CREDENTIALS="$CREDENTIALS_PATH" \
+ "$VECTOR_BIN" validate --skip-healthchecks "$CONFIG_TMP" >/dev/null
+
+cat >"$PLIST_TMP" <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+ <key>Label</key>
+ <string>$(xml_escape "$LABEL")</string>
+ <key>ProgramArguments</key>
+ <array>
+ <string>$(xml_escape "$WRAPPER")</string>
+ </array>
+ <key>RunAtLoad</key>
+ <true/>
+ <key>KeepAlive</key>
+ <true/>
+ <key>StandardOutPath</key>
+ <string>/tmp/$LABEL.out</string>
+ <key>StandardErrorPath</key>
+ <string>/tmp/$LABEL.err</string>
+</dict>
+</plist>
+EOF
+chmod 0644 "$PLIST_TMP"
+
+mv -f "$CONFIG_TMP" "$CONFIG_PATH"
+mv -f "$ENV_TMP" "$ENV_PATH"
+mv -f "$PLIST_TMP" "$PLIST_PATH"
+trap - EXIT INT TERM
+
+echo "GCS Vector config: $CONFIG_PATH"
+echo "GCS Vector env: $ENV_PATH"
+echo "GCS Vector LaunchDaemon: $PLIST_PATH"
+
+case "$NO_START" in
+ 1|true|TRUE|yes|YES)
+ echo "BEACON_NO_START is set; not loading $LABEL"
+ exit 0
+ ;;
+esac
+
+if command -v launchctl >/dev/null 2>&1; then
+ target="system/$LABEL"
+ launchctl bootout "$target" >/dev/null 2>&1 || true
+ attempts=0
+ while launchctl print "$target" >/dev/null 2>&1; do
+ attempts=$((attempts + 1))
+ if [ "$attempts" -ge "$STOP_ATTEMPTS" ]; then
+ echo "Timed out waiting for $LABEL to stop" >&2
+ exit 1
+ fi
+ sleep 1
+ done
+ launchctl bootstrap system "$PLIST_PATH" >/dev/null 2>&1 || {
+ echo "Could not bootstrap $LABEL" >&2
+ exit 1
+ }
+ attempts=0
+ consecutive_running=0
+ while [ "$attempts" -lt "$START_ATTEMPTS" ] && [ "$consecutive_running" -lt 3 ]; do
+ attempts=$((attempts + 1))
+ if launchctl print "$target" 2>/dev/null | grep -Eq 'state = running|pid ='; then
+ consecutive_running=$((consecutive_running + 1))
+ else
+ consecutive_running=0
+ fi
+ if [ "$consecutive_running" -lt 3 ]; then
+ sleep 1
+ fi
+ done
+ if [ "$consecutive_running" -lt 3 ]; then
+ launchctl print "$target" 2>&1 || true
+ echo "$LABEL did not remain running" >&2
+ exit 1
+ fi
+ launchctl print "$target" || true
+else
+ echo "launchctl unavailable; wrote config but did not start $LABEL" >&2
+fi
+
+if [ -f "/tmp/$LABEL.err" ]; then
+ echo "Last GCS Vector stderr lines:"
+ tail -n 20 "/tmp/$LABEL.err" || true
+fi
diff --git a/packaging/macos/jamf/claude/gcs/repair-hooks-and-forwarder.sh b/packaging/macos/jamf/claude/gcs/repair-hooks-and-forwarder.sh
new file mode 100755
index 00000000..e3d4593e
--- /dev/null
+++ b/packaging/macos/jamf/claude/gcs/repair-hooks-and-forwarder.sh
@@ -0,0 +1,27 @@
+#!/bin/sh
+set -eu
+
+REPAIR_SCRIPT="${BEACON_REPAIR_HOOKS_SCRIPT:-/opt/beacon/jamf/claude/common/repair-hooks.sh}"
+FORWARDER_SCRIPT="${BEACON_GCS_VECTOR_SCRIPT:-/opt/beacon/jamf/claude/gcs/install-forwarder.sh}"
+
+GCS_BUCKET="${BEACON_GCS_BUCKET:-${4:-}}"
+GCS_PREFIX="${BEACON_GCS_PREFIX:-${5:-beacon}}"
+GCS_STORAGE_CLASS="${BEACON_GCS_STORAGE_CLASS:-${6:-STANDARD}}"
+VECTOR_READ_FROM="${BEACON_VECTOR_READ_FROM:-${7:-end}}"
+OTLP_GRPC_PORT="${BEACON_OTLP_GRPC_PORT:-${8:-4317}}"
+OTLP_HTTP_PORT="${BEACON_OTLP_HTTP_PORT:-${9:-4318}}"
+
+if [ ! -x "$REPAIR_SCRIPT" ]; then
+ echo "Repair script not found or not executable at $REPAIR_SCRIPT" >&2
+ exit 1
+fi
+if [ ! -x "$FORWARDER_SCRIPT" ]; then
+ echo "GCS Vector forwarder script not found or not executable at $FORWARDER_SCRIPT" >&2
+ exit 1
+fi
+
+echo "Installing GCS Vector runtime and inventory forwarder..."
+"$FORWARDER_SCRIPT" _ _ _ "$GCS_BUCKET" "$GCS_PREFIX" "$GCS_STORAGE_CLASS" "$VECTOR_READ_FROM"
+
+echo "Repairing endpoint and Claude hooks..."
+"$REPAIR_SCRIPT" _ _ _ "$OTLP_GRPC_PORT" "$OTLP_HTTP_PORT"
diff --git a/packaging/macos/jamf/claude/gcs/run-forwarder.sh b/packaging/macos/jamf/claude/gcs/run-forwarder.sh
new file mode 100755
index 00000000..d921f1f1
--- /dev/null
+++ b/packaging/macos/jamf/claude/gcs/run-forwarder.sh
@@ -0,0 +1,26 @@
+#!/bin/sh
+set -eu
+
+VECTOR_BIN="${BEACON_VECTOR_BIN:-/opt/beacon/bin/vector}"
+CONFIG_PATH="${BEACON_GCS_VECTOR_CONFIG:-/Library/Application Support/Beacon/Forwarders/gcs-vector.toml}"
+ENV_PATH="${BEACON_GCS_VECTOR_ENV:-/Library/Application Support/Beacon/Forwarders/gcs-vector.env}"
+
+if [ -f "$ENV_PATH" ]; then
+ # shellcheck disable=SC1090
+ . "$ENV_PATH"
+fi
+
+if [ ! -x "$VECTOR_BIN" ]; then
+ echo "Vector binary not found or not executable at $VECTOR_BIN" >&2
+ exit 1
+fi
+if [ ! -f "$CONFIG_PATH" ]; then
+ echo "Vector config not found at $CONFIG_PATH" >&2
+ exit 1
+fi
+if [ -z "${GOOGLE_APPLICATION_CREDENTIALS:-}" ] || [ ! -r "$GOOGLE_APPLICATION_CREDENTIALS" ]; then
+ echo "GOOGLE_APPLICATION_CREDENTIALS is missing or unreadable" >&2
+ exit 1
+fi
+
+exec "$VECTOR_BIN" --config "$CONFIG_PATH"
diff --git a/packaging/macos/jamf/claude/s3/install-forwarder.sh b/packaging/macos/jamf/claude/s3/install-forwarder.sh
index 962b0579..d82c0e9a 100755
--- a/packaging/macos/jamf/claude/s3/install-forwarder.sh
+++ b/packaging/macos/jamf/claude/s3/install-forwarder.sh
@@ -18,7 +18,10 @@ S3_STORAGE_CLASS="${BEACON_S3_STORAGE_CLASS:-${7:-STANDARD}}"
VECTOR_READ_FROM="${BEACON_VECTOR_READ_FROM:-${8:-end}}"
RUNTIME_LOG_PATHS="${BEACON_RUNTIME_LOG_PATHS:-/var/log/beacon-agent/runtime.jsonl}"
NO_START="${BEACON_NO_START:-0}"
+STOP_ATTEMPTS="${BEACON_FORWARDER_STOP_ATTEMPTS:-65}"
+START_ATTEMPTS="${BEACON_FORWARDER_START_ATTEMPTS:-15}"
+S3_PREFIX="${S3_PREFIX%/}"
case "$S3_PREFIX" in
*/runtime)
S3_PREFIX="${S3_PREFIX%/runtime}"
@@ -268,11 +271,40 @@ case "$NO_START" in
esac
if command -v launchctl >/dev/null 2>&1; then
- launchctl bootout "system/$LABEL" >/dev/null 2>&1 || true
+ target="system/$LABEL"
+ launchctl bootout "$target" >/dev/null 2>&1 || true
+ attempts=0
+ while launchctl print "$target" >/dev/null 2>&1; do
+ attempts=$((attempts + 1))
+ if [ "$attempts" -ge "$STOP_ATTEMPTS" ]; then
+ echo "Timed out waiting for $LABEL to stop" >&2
+ exit 1
+ fi
+ sleep 1
+ done
launchctl bootstrap system "$PLIST_PATH" >/dev/null 2>&1 || {
- launchctl print "system/$LABEL" >/dev/null 2>&1 || exit 1
+ echo "Could not bootstrap $LABEL" >&2
+ exit 1
}
- launchctl print "system/$LABEL" || true
+ attempts=0
+ consecutive_running=0
+ while [ "$attempts" -lt "$START_ATTEMPTS" ] && [ "$consecutive_running" -lt 3 ]; do
+ attempts=$((attempts + 1))
+ if launchctl print "$target" 2>/dev/null | grep -Eq 'state = running|pid ='; then
+ consecutive_running=$((consecutive_running + 1))
+ else
+ consecutive_running=0
+ fi
+ if [ "$consecutive_running" -lt 3 ]; then
+ sleep 1
+ fi
+ done
+ if [ "$consecutive_running" -lt 3 ]; then
+ launchctl print "$target" 2>&1 || true
+ echo "$LABEL did not remain running" >&2
+ exit 1
+ fi
+ launchctl print "$target" || true
else
echo "launchctl unavailable; wrote config but did not start $LABEL" >&2
fi
diff --git a/packaging/macos/jamf/scripts/full-cleanup.sh b/packaging/macos/jamf/scripts/full-cleanup.sh
new file mode 100755
index 00000000..73b48960
--- /dev/null
+++ b/packaging/macos/jamf/scripts/full-cleanup.sh
@@ -0,0 +1,600 @@
+#!/bin/sh
+set -u
+
+# Fully remove Beacon endpoint services, forwarding configuration, logs/state,
+# package files, package receipts, and Beacon-managed active-user hooks/config.
+#
+# This script is intentionally destructive. By default it cleans only the active
+# console user's runtime configs. Set BEACON_CLEAN_ALL_USERS=1 to scan /Users/*.
+
+BEACON_BIN="${BEACON_BIN:-/opt/beacon/bin/beacon}"
+BEACON_KEEP_LOGS="${BEACON_KEEP_LOGS:-0}"
+BEACON_CLEAN_ALL_USERS="${BEACON_CLEAN_ALL_USERS:-0}"
+
+COLLECTOR_LABEL="${COLLECTOR_LABEL:-com.beacon.endpoint.collector}"
+UPDATER_LABEL="${UPDATER_LABEL:-com.beacon.endpoint.updater}"
+S3_FORWARDER_LABEL="${S3_FORWARDER_LABEL:-com.beacon.endpoint.s3-forwarder}"
+GCS_FORWARDER_LABEL="${GCS_FORWARDER_LABEL:-com.beacon.endpoint.gcs-forwarder}"
+FALCON_FORWARDER_LABEL="${FALCON_FORWARDER_LABEL:-com.beacon.endpoint.falcon-forwarder}"
+
+RUNTIME_DIR="${RUNTIME_DIR:-/var/log/beacon-agent}"
+SYSTEM_CONFIG_DIR="${SYSTEM_CONFIG_DIR:-/Library/Application Support/Beacon}"
+BEACON_CONFIG_PATH="${BEACON_CONFIG_PATH:-$SYSTEM_CONFIG_DIR/Endpoint/config.json}"
+OPT_BEACON_DIR="${OPT_BEACON_DIR:-/opt/beacon}"
+
+warn() {
+ echo "WARNING: $*" >&2
+}
+
+ok() {
+ echo "OK: $*"
+}
+
+backup_file() {
+ path="$1"
+ [ -e "$path" ] || return 0
+ if ! python3_available; then
+ warn "python3 is unavailable; refusing to back up $path unsafely"
+ return 1
+ fi
+
+ python3 - "$path" <<'PY'
+import datetime
+import os
+import stat
+import sys
+
+path = sys.argv[1]
+try:
+ before = os.lstat(path)
+ if not stat.S_ISREG(before.st_mode):
+ raise ValueError("not a regular file")
+ source_fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW)
+ current = os.fstat(source_fd)
+ if (before.st_dev, before.st_ino) != (current.st_dev, current.st_ino):
+ raise ValueError("file changed while opening")
+ stamp = datetime.datetime.now(datetime.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+ backup = f"{path}.beacon-uninstall.{stamp}.{os.getpid()}.bak"
+ backup_fd = os.open(
+ backup,
+ os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+ stat.S_IMODE(current.st_mode),
+ )
+ try:
+ os.fchmod(backup_fd, stat.S_IMODE(current.st_mode))
+ os.fchown(backup_fd, current.st_uid, current.st_gid)
+ while True:
+ chunk = os.read(source_fd, 1024 * 1024)
+ if not chunk:
+ break
+ remaining = memoryview(chunk)
+ while remaining:
+ written = os.write(backup_fd, remaining)
+ remaining = remaining[written:]
+ os.fsync(backup_fd)
+ finally:
+ os.close(backup_fd)
+ os.close(source_fd)
+except Exception as exc:
+ print(f"WARNING: refusing unsafe backup of {path}: {exc}", file=sys.stderr)
+ sys.exit(1)
+PY
+}
+
+bootout_label() {
+ label="$1"
+ plist="/Library/LaunchDaemons/$label.plist"
+
+ echo "Stopping launch daemon: $label"
+ launchctl bootout "system/$label" >/dev/null 2>&1 || true
+ launchctl remove "$label" >/dev/null 2>&1 || true
+
+ if [ -f "$plist" ]; then
+ rm -f "$plist" || warn "Could not remove $plist"
+ fi
+}
+
+python3_available() {
+ command -v python3 >/dev/null 2>&1
+}
+
+beacon_local_otlp_endpoints() {
+ if ! python3_available || [ ! -f "$BEACON_CONFIG_PATH" ]; then
+ return 0
+ fi
+
+ python3 - "$BEACON_CONFIG_PATH" <<'PY'
+import json
+import pathlib
+import sys
+
+try:
+ config = json.loads(pathlib.Path(sys.argv[1]).read_text())
+ collector = config.get("collector") or {}
+ ports = {
+ int(collector.get("grpc_port") or 0),
+ int(collector.get("http_port") or 0),
+ }
+except Exception:
+ sys.exit(0)
+
+endpoints = []
+for port in sorted(port for port in ports if port > 0):
+ endpoints.extend([
+ f"http://127.0.0.1:{port}",
+ f"http://localhost:{port}",
+ ])
+print(",".join(endpoints))
+PY
+}
+
+BEACON_LOCAL_OTLP_ENDPOINTS="$(beacon_local_otlp_endpoints)"
+if [ -z "$BEACON_LOCAL_OTLP_ENDPOINTS" ]; then
+ warn "Could not determine installed Beacon OTLP ports; preserving user OTLP settings"
+fi
+
+remove_beacon_hooks_from_json() {
+ path="$1"
+ [ -f "$path" ] || return 0
+
+ if ! python3_available; then
+ warn "python3 is unavailable; skipping Beacon hook cleanup in $path"
+ return 0
+ fi
+
+ backup_file "$path" || return 0
+
+ python3 - "$path" <<'PY'
+import json
+import os
+import pathlib
+import stat
+import sys
+import tempfile
+
+path = pathlib.Path(sys.argv[1])
+
+def read_verified_text(target):
+ before = os.lstat(target)
+ if not stat.S_ISREG(before.st_mode):
+ raise ValueError("not a regular file")
+ fd = os.open(target, os.O_RDONLY | os.O_NOFOLLOW)
+ current = os.fstat(fd)
+ if (before.st_dev, before.st_ino) != (current.st_dev, current.st_ino):
+ os.close(fd)
+ raise ValueError("file changed while opening")
+ with os.fdopen(fd, encoding="utf-8") as handle:
+ return handle.read(), current
+
+def replace_verified_text(target, content, original):
+ fd, temporary = tempfile.mkstemp(prefix=".beacon-cleanup-", dir=target.parent)
+ try:
+ os.fchmod(fd, stat.S_IMODE(original.st_mode))
+ os.fchown(fd, original.st_uid, original.st_gid)
+ with os.fdopen(fd, "w", encoding="utf-8") as handle:
+ handle.write(content)
+ handle.flush()
+ os.fsync(handle.fileno())
+ current = os.lstat(target)
+ if (current.st_dev, current.st_ino) != (original.st_dev, original.st_ino):
+ raise ValueError("file changed before replacement")
+ os.replace(temporary, target)
+ except Exception:
+ try:
+ os.close(fd)
+ except OSError:
+ pass
+ try:
+ os.unlink(temporary)
+ except FileNotFoundError:
+ pass
+ raise
+
+try:
+ text, original = read_verified_text(path)
+ data = json.loads(text)
+except Exception as exc:
+ print(f"WARNING: could not parse {path}: {exc}", file=sys.stderr)
+ sys.exit(0)
+
+hooks = data.get("hooks")
+if isinstance(hooks, dict):
+ for event_name in list(hooks.keys()):
+ groups = hooks.get(event_name)
+ if not isinstance(groups, list):
+ continue
+
+ # Cursor stores hooks as direct refs under each event:
+ # {"hooks": {"preToolUse": [{"command": "..."}]}}
+ # Claude-style settings store groups with a nested hooks array:
+ # {"hooks": {"PreToolUse": [{"hooks": [{"command": "..."}]}]}}
+ if all(not (isinstance(group, dict) and isinstance(group.get("hooks"), list)) for group in groups):
+ kept_refs = []
+ for ref in groups:
+ command = ""
+ if isinstance(ref, dict):
+ command = str(ref.get("command") or "")
+ if "BEACON_ENDPOINT_MODE=1" in command or "beacon-hooks" in command:
+ continue
+ kept_refs.append(ref)
+ if kept_refs:
+ hooks[event_name] = kept_refs
+ else:
+ hooks.pop(event_name, None)
+ continue
+
+ kept_groups = []
+ for group in groups:
+ if not isinstance(group, dict):
+ kept_groups.append(group)
+ continue
+
+ refs = group.get("hooks")
+ if not isinstance(refs, list):
+ kept_groups.append(group)
+ continue
+
+ kept_refs = []
+ for ref in refs:
+ command = ""
+ if isinstance(ref, dict):
+ command = str(ref.get("command") or "")
+ if "BEACON_ENDPOINT_MODE=1" in command or "beacon-hooks" in command:
+ continue
+ kept_refs.append(ref)
+
+ if kept_refs:
+ next_group = dict(group)
+ next_group["hooks"] = kept_refs
+ kept_groups.append(next_group)
+
+ if kept_groups:
+ hooks[event_name] = kept_groups
+ else:
+ hooks.pop(event_name, None)
+
+if hooks == {}:
+ data.pop("hooks", None)
+
+try:
+ replace_verified_text(
+ path,
+ json.dumps(data, indent=2, sort_keys=True) + "\n",
+ original,
+ )
+except Exception as exc:
+ print(f"WARNING: could not safely update {path}: {exc}", file=sys.stderr)
+PY
+}
+
+remove_claude_beacon_otel_env() {
+ path="$1"
+ [ -f "$path" ] || return 0
+
+ if ! python3_available; then
+ warn "python3 is unavailable; skipping Claude OTLP cleanup in $path"
+ return 0
+ fi
+
+ backup_file "$path" || return 0
+
+ python3 - "$path" "$BEACON_LOCAL_OTLP_ENDPOINTS" <<'PY'
+import json
+import os
+import pathlib
+import stat
+import sys
+import tempfile
+
+path = pathlib.Path(sys.argv[1])
+
+def read_verified_text(target):
+ before = os.lstat(target)
+ if not stat.S_ISREG(before.st_mode):
+ raise ValueError("not a regular file")
+ fd = os.open(target, os.O_RDONLY | os.O_NOFOLLOW)
+ current = os.fstat(fd)
+ if (before.st_dev, before.st_ino) != (current.st_dev, current.st_ino):
+ os.close(fd)
+ raise ValueError("file changed while opening")
+ with os.fdopen(fd, encoding="utf-8") as handle:
+ return handle.read(), current
+
+def replace_verified_text(target, content, original):
+ fd, temporary = tempfile.mkstemp(prefix=".beacon-cleanup-", dir=target.parent)
+ try:
+ os.fchmod(fd, stat.S_IMODE(original.st_mode))
+ os.fchown(fd, original.st_uid, original.st_gid)
+ with os.fdopen(fd, "w", encoding="utf-8") as handle:
+ handle.write(content)
+ handle.flush()
+ os.fsync(handle.fileno())
+ current = os.lstat(target)
+ if (current.st_dev, current.st_ino) != (original.st_dev, original.st_ino):
+ raise ValueError("file changed before replacement")
+ os.replace(temporary, target)
+ except Exception:
+ try:
+ os.close(fd)
+ except OSError:
+ pass
+ try:
+ os.unlink(temporary)
+ except FileNotFoundError:
+ pass
+ raise
+
+try:
+ text, original = read_verified_text(path)
+ data = json.loads(text)
+except Exception as exc:
+ print(f"WARNING: could not parse {path}: {exc}", file=sys.stderr)
+ sys.exit(0)
+
+env = data.get("env")
+if not isinstance(env, dict):
+ sys.exit(0)
+
+endpoint = str(env.get("OTEL_EXPORTER_OTLP_ENDPOINT") or "")
+enabled = str(env.get("CLAUDE_CODE_ENABLE_TELEMETRY") or "")
+beacon_endpoints = {
+ value.rstrip("/")
+ for value in sys.argv[2].split(",")
+ if value
+}
+looks_beacon = (
+ enabled == "1"
+ and endpoint.rstrip("/") in beacon_endpoints
+)
+if not looks_beacon:
+ sys.exit(0)
+
+for key in [
+ "CLAUDE_CODE_ENABLE_TELEMETRY",
+ "OTEL_EXPORTER_OTLP_ENDPOINT",
+ "OTEL_EXPORTER_OTLP_PROTOCOL",
+ "OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE",
+ "OTEL_LOGS_EXPORTER",
+ "OTEL_METRICS_EXPORTER",
+ "OTEL_LOG_USER_PROMPTS",
+]:
+ env.pop(key, None)
+
+data["env"] = env
+try:
+ replace_verified_text(
+ path,
+ json.dumps(data, indent=2, sort_keys=True) + "\n",
+ original,
+ )
+except Exception as exc:
+ print(f"WARNING: could not safely update {path}: {exc}", file=sys.stderr)
+PY
+}
+
+remove_codex_beacon_otel_blocks() {
+ path="$1"
+ [ -f "$path" ] || return 0
+
+ if ! python3_available; then
+ warn "python3 is unavailable; skipping Codex OTLP cleanup in $path"
+ return 0
+ fi
+
+ backup_file "$path" || return 0
+
+ python3 - "$path" "$BEACON_LOCAL_OTLP_ENDPOINTS" <<'PY'
+import os
+import pathlib
+import re
+import stat
+import sys
+import tempfile
+
+path = pathlib.Path(sys.argv[1])
+beacon_endpoints = {
+ value.rstrip("/")
+ for value in sys.argv[2].split(",")
+ if value
+}
+
+def read_verified_text(target):
+ before = os.lstat(target)
+ if not stat.S_ISREG(before.st_mode):
+ raise ValueError("not a regular file")
+ fd = os.open(target, os.O_RDONLY | os.O_NOFOLLOW)
+ current = os.fstat(fd)
+ if (before.st_dev, before.st_ino) != (current.st_dev, current.st_ino):
+ os.close(fd)
+ raise ValueError("file changed while opening")
+ with os.fdopen(fd, encoding="utf-8") as handle:
+ return handle.read(), current
+
+def replace_verified_text(target, content, original):
+ fd, temporary = tempfile.mkstemp(prefix=".beacon-cleanup-", dir=target.parent)
+ try:
+ os.fchmod(fd, stat.S_IMODE(original.st_mode))
+ os.fchown(fd, original.st_uid, original.st_gid)
+ with os.fdopen(fd, "w", encoding="utf-8") as handle:
+ handle.write(content)
+ handle.flush()
+ os.fsync(handle.fileno())
+ current = os.lstat(target)
+ if (current.st_dev, current.st_ino) != (original.st_dev, original.st_ino):
+ raise ValueError("file changed before replacement")
+ os.replace(temporary, target)
+ except Exception:
+ try:
+ os.close(fd)
+ except OSError:
+ pass
+ try:
+ os.unlink(temporary)
+ except FileNotFoundError:
+ pass
+ raise
+
+try:
+ text, original = read_verified_text(path)
+except Exception as exc:
+ print(f"WARNING: could not safely read {path}: {exc}", file=sys.stderr)
+ sys.exit(0)
+
+lines = text.splitlines()
+sections = []
+current = []
+
+for line in lines:
+ stripped = line.strip()
+ if stripped.startswith("[") and stripped.endswith("]") and current:
+ sections.append(current)
+ current = [line]
+ else:
+ current.append(line)
+if current:
+ sections.append(current)
+
+out = []
+for section in sections:
+ header = section[0].strip() if section else ""
+ is_otel = bool(re.match(r"^\[otel(\.|])", header))
+ body = "\n".join(section)
+ beacon_endpoint = any(endpoint in body for endpoint in beacon_endpoints)
+ if is_otel and beacon_endpoint:
+ continue
+ out.extend(section)
+
+try:
+ replace_verified_text(path, "\n".join(out).rstrip() + "\n", original)
+except Exception as exc:
+ print(f"WARNING: could not safely update {path}: {exc}", file=sys.stderr)
+PY
+}
+
+remove_user_beacon_artifacts() {
+ user="$1"
+ home="$2"
+
+ echo "Cleaning Beacon user artifacts for $user ($home)"
+
+ remove_beacon_hooks_from_json "$home/.claude/settings.json"
+ remove_claude_beacon_otel_env "$home/.claude/settings.json"
+ remove_beacon_hooks_from_json "$home/.codex/hooks.json"
+ remove_codex_beacon_otel_blocks "$home/.codex/config.toml"
+ remove_beacon_hooks_from_json "$home/.cursor/hooks.json"
+
+ rm -rf "$home/.beacon/endpoint" ||
+ warn "Could not remove $home/.beacon/endpoint"
+}
+
+cleanup_console_user() {
+ console_user="$(stat -f '%Su' /dev/console 2>/dev/null || true)"
+ if [ -z "$console_user" ] || [ "$console_user" = "root" ] || [ "$console_user" = "loginwindow" ]; then
+ warn "No active console user; skipping active user cleanup"
+ return 0
+ fi
+
+ home_dir="$(dscl . -read "/Users/$console_user" NFSHomeDirectory 2>/dev/null | awk '{print $2}')"
+ if [ -z "$home_dir" ] || [ ! -d "$home_dir" ]; then
+ warn "Could not resolve home directory for console user $console_user"
+ return 0
+ fi
+
+ remove_user_beacon_artifacts "$console_user" "$home_dir"
+}
+
+cleanup_all_users() {
+ for home_dir in /Users/*; do
+ [ -d "$home_dir" ] || continue
+ user="$(basename "$home_dir")"
+ case "$user" in
+ Shared|Guest|.localized)
+ continue
+ ;;
+ esac
+ if id "$user" >/dev/null 2>&1; then
+ remove_user_beacon_artifacts "$user" "$home_dir"
+ fi
+ done
+}
+
+echo "=== Beacon Full Cleanup / Rollback ==="
+date -u +"time_utc=%Y-%m-%dT%H:%M:%SZ"
+
+echo
+echo "Installed Beacon version before cleanup:"
+if [ -x "$BEACON_BIN" ]; then
+ "$BEACON_BIN" version || true
+else
+ warn "Beacon binary not found at $BEACON_BIN"
+fi
+
+echo
+echo "Running Beacon endpoint uninstall if available..."
+if [ -x "$BEACON_BIN" ]; then
+ case "$BEACON_KEEP_LOGS" in
+ 1|true|TRUE|yes|YES)
+ "$BEACON_BIN" endpoint uninstall --system --keep-logs ||
+ warn "Beacon endpoint uninstall failed or endpoint was already removed"
+ ;;
+ *)
+ "$BEACON_BIN" endpoint uninstall --system ||
+ warn "Beacon endpoint uninstall failed or endpoint was already removed"
+ ;;
+ esac
+fi
+
+echo
+echo "Stopping/removing leftover Beacon launch daemons..."
+bootout_label "$COLLECTOR_LABEL"
+bootout_label "$UPDATER_LABEL"
+bootout_label "$S3_FORWARDER_LABEL"
+bootout_label "$GCS_FORWARDER_LABEL"
+bootout_label "$FALCON_FORWARDER_LABEL"
+
+echo
+echo "Cleaning user-level Beacon config..."
+case "$BEACON_CLEAN_ALL_USERS" in
+ 1|true|TRUE|yes|YES)
+ cleanup_all_users
+ ;;
+ *)
+ cleanup_console_user
+ ;;
+esac
+
+echo
+echo "Removing system Beacon files..."
+rm -rf "$SYSTEM_CONFIG_DIR" || warn "Could not remove $SYSTEM_CONFIG_DIR"
+rm -rf "$OPT_BEACON_DIR" || warn "Could not remove $OPT_BEACON_DIR"
+case "$BEACON_KEEP_LOGS" in
+ 1|true|TRUE|yes|YES)
+ ok "Keeping Beacon logs because BEACON_KEEP_LOGS=$BEACON_KEEP_LOGS"
+ ;;
+ *)
+ rm -rf "$RUNTIME_DIR" || warn "Could not remove $RUNTIME_DIR"
+ ;;
+esac
+
+echo
+echo "Removing Beacon package receipts..."
+for pkgid in ai.asymptote.beacon.endpoint; do
+ pkgutil --pkg-info "$pkgid" >/dev/null 2>&1 || continue
+ echo "Forgetting package receipt: $pkgid"
+ pkgutil --forget "$pkgid" >/dev/null 2>&1 ||
+ warn "Could not forget receipt $pkgid"
+done
+
+echo
+echo "Post-cleanup launchd state:"
+for label in "$COLLECTOR_LABEL" "$UPDATER_LABEL" "$S3_FORWARDER_LABEL" "$GCS_FORWARDER_LABEL" "$FALCON_FORWARDER_LABEL"; do
+ if launchctl print "system/$label" >/dev/null 2>&1; then
+ warn "$label still exists"
+ else
+ ok "$label removed"
+ fi
+done
+
+echo
+echo "Beacon cleanup completed. A reboot is recommended if any launchd state appears stale."
+exit 0
diff --git a/packaging/macos/scripts/postinstall b/packaging/macos/scripts/postinstall
index 0e2108fa..23618dd9 100755
--- a/packaging/macos/scripts/postinstall
+++ b/packaging/macos/scripts/postinstall
@@ -29,6 +29,34 @@ forwarder_running() {
launchctl print "system/$label" 2>/dev/null | grep -Eq 'state = running|pid ='
}
+forwarder_stably_running() {
+ label="$1"
+ observations=0
+
+ while [ "$observations" -lt 3 ]; do
+ if ! forwarder_running "$label"; then
+ return 1
+ fi
+ observations=$((observations + 1))
+ if [ "$observations" -lt 3 ]; then
+ sleep 1
+ fi
+ done
+}
+
+wait_for_forwarder_bootout() {
+ target="$1"
+ attempts=0
+
+ while launchctl print "$target" >/dev/null 2>&1; do
+ attempts=$((attempts + 1))
+ if [ "$attempts" -ge 65 ]; then
+ return 1
+ fi
+ sleep 1
+ done
+}
+
restore_existing_forwarder() {
label="$1"
plist_path="$2"
@@ -43,7 +71,7 @@ restore_existing_forwarder() {
out="$(launchctl kickstart -k "$target" 2>&1)" || {
echo "Warning: launchctl kickstart failed for $label: $out" >&2
}
- if forwarder_running "$label"; then
+ if forwarder_stably_running "$label"; then
return 0
fi
fi
@@ -52,24 +80,28 @@ restore_existing_forwarder() {
out="$(launchctl bootstrap system "$plist_path" 2>&1)" || {
echo "Warning: launchctl bootstrap failed for $label: $out" >&2
}
- if forwarder_running "$label"; then
+ if forwarder_stably_running "$label"; then
return 0
fi
out="$(launchctl bootout "$target" 2>&1)" || {
echo "Warning: launchctl bootout retry failed for $label: $out" >&2
}
+ if ! wait_for_forwarder_bootout "$target"; then
+ echo "Warning: timed out waiting for launchctl bootout for $label" >&2
+ continue
+ fi
out="$(launchctl bootstrap system "$plist_path" 2>&1)" || {
echo "Warning: launchctl bootstrap after bootout failed for $label: $out" >&2
}
- if forwarder_running "$label"; then
+ if forwarder_stably_running "$label"; then
return 0
fi
out="$(launchctl kickstart -k "$target" 2>&1)" || {
echo "Warning: launchctl kickstart retry failed for $label: $out" >&2
}
- if forwarder_running "$label"; then
+ if forwarder_stably_running "$label"; then
return 0
fi
sleep "$delay"
@@ -87,6 +119,7 @@ if command -v launchctl >/dev/null 2>&1; then
}
restore_existing_forwarder "com.beacon.endpoint.falcon-forwarder" "/Library/LaunchDaemons/com.beacon.endpoint.falcon-forwarder.plist"
restore_existing_forwarder "com.beacon.endpoint.s3-forwarder" "/Library/LaunchDaemons/com.beacon.endpoint.s3-forwarder.plist"
+ restore_existing_forwarder "com.beacon.endpoint.gcs-forwarder" "/Library/LaunchDaemons/com.beacon.endpoint.gcs-forwarder.plist"
"${BEACON_BIN:-/opt/beacon/bin/beacon}" endpoint update install-daemon || {
echo "Error: could not reconcile Beacon endpoint updater daemon" >&2
exit 1
diff --git a/packaging/macos/scripts/preinstall b/packaging/macos/scripts/preinstall
index 8a0e0994..0a8fffac 100755
--- a/packaging/macos/scripts/preinstall
+++ b/packaging/macos/scripts/preinstall
@@ -6,6 +6,8 @@ set -eu
if command -v launchctl >/dev/null 2>&1; then
launchctl bootout system/com.beacon.endpoint.collector >/dev/null 2>&1 || true
launchctl bootout system/com.beacon.endpoint.falcon-forwarder >/dev/null 2>&1 || true
+ launchctl bootout system/com.beacon.endpoint.s3-forwarder >/dev/null 2>&1 || true
+ launchctl bootout system/com.beacon.endpoint.gcs-forwarder >/dev/null 2>&1 || true
fi
exit 0
diff --git a/packaging/macos/test-endpoint-scripts.sh b/packaging/macos/test-endpoint-scripts.sh
index 31120c24..03b5d59f 100644
--- a/packaging/macos/test-endpoint-scripts.sh
+++ b/packaging/macos/test-endpoint-scripts.sh
@@ -7,6 +7,7 @@ UNINSTALL_SCRIPT="$ROOT_DIR/packaging/macos/uninstall-endpoint.sh"
PKG_BUILD_SCRIPT="$ROOT_DIR/packaging/macos/build-pkg.sh"
PKG_SIGN_NOTARIZE_SCRIPT="$ROOT_DIR/packaging/macos/build-signed-notarized-pkg.sh"
REPAIR_SCRIPT="$ROOT_DIR/packaging/macos/jamf/scripts/repair.sh"
+FULL_CLEANUP_SCRIPT="$ROOT_DIR/packaging/macos/jamf/scripts/full-cleanup.sh"
FLEET_REPAIR_SCRIPT="$ROOT_DIR/packaging/macos/fleet/scripts/repair.sh"
TMP_DIR="$(mktemp -d)"
trap 'rm -rf "$TMP_DIR"' EXIT INT TERM
@@ -53,6 +54,212 @@ if ! grep -q 'launchctl bootstrap failed' "$ROOT_DIR/packaging/macos/scripts/pos
echo "postinstall should preserve launchctl bootstrap diagnostics" >&2
exit 1
fi
+if ! grep -q 'forwarder_stably_running' "$ROOT_DIR/packaging/macos/scripts/postinstall" ||
+ ! grep -q 'wait_for_forwarder_bootout' "$ROOT_DIR/packaging/macos/scripts/postinstall"; then
+ echo "postinstall should wait for bootout and verify stable forwarder startup" >&2
+ exit 1
+fi
+if ! grep -q 'com.beacon.endpoint.gcs-forwarder' "$ROOT_DIR/packaging/macos/scripts/postinstall"; then
+ echo "postinstall should restore the optional GCS forwarder" >&2
+ exit 1
+fi
+for installer in \
+ "$ROOT_DIR/packaging/macos/jamf/claude/s3/install-forwarder.sh" \
+ "$ROOT_DIR/packaging/macos/jamf/claude/gcs/install-forwarder.sh"
+do
+ if ! grep -q 'Timed out waiting for.*to stop' "$installer"; then
+ echo "forwarder installer should wait for launchd bootout: $installer" >&2
+ exit 1
+ fi
+ if ! grep -q 'did not remain running' "$installer"; then
+ echo "forwarder installer should verify sustained launchd startup: $installer" >&2
+ exit 1
+ fi
+done
+if ! grep -q 'BEACON_KEEP_LOGS' "$FULL_CLEANUP_SCRIPT"; then
+ echo "full cleanup should support preserving logs" >&2
+ exit 1
+fi
+if ! grep -q 'BEACON_CLEAN_ALL_USERS' "$FULL_CLEANUP_SCRIPT"; then
+ echo "full cleanup should support all-user cleanup opt-in" >&2
+ exit 1
+fi
+if ! grep -q 'endpoint uninstall --system' "$FULL_CLEANUP_SCRIPT"; then
+ echo "full cleanup should run Beacon uninstall before force removal" >&2
+ exit 1
+fi
+if ! grep -q 'endpoint uninstall --system --keep-logs' "$FULL_CLEANUP_SCRIPT"; then
+ echo "full cleanup should preserve logs during the Beacon uninstall step" >&2
+ exit 1
+fi
+if ! grep -q 'OTEL_EXPORTER_OTLP_ENDPOINT' "$FULL_CLEANUP_SCRIPT"; then
+ echo "full cleanup should remove Beacon-managed Claude OTLP env" >&2
+ exit 1
+fi
+if ! grep -q 'http://127.0.0.1:' "$FULL_CLEANUP_SCRIPT"; then
+ echo "full cleanup should preserve non-local OTLP settings" >&2
+ exit 1
+fi
+if grep -q 'or enabled == "1"' "$FULL_CLEANUP_SCRIPT"; then
+ echo "full cleanup must not remove remote Claude OTLP settings solely because telemetry is enabled" >&2
+ exit 1
+fi
+if ! grep -q 'BEACON_LOCAL_OTLP_ENDPOINTS' "$FULL_CLEANUP_SCRIPT"; then
+ echo "full cleanup should match user OTLP settings to the installed Beacon ports" >&2
+ exit 1
+fi
+if ! grep -q 'ai.asymptote.beacon.endpoint' "$FULL_CLEANUP_SCRIPT" ||
+ grep -q 'pkgutil --pkgs' "$FULL_CLEANUP_SCRIPT"; then
+ echo "full cleanup should forget only the known Beacon package receipt" >&2
+ exit 1
+fi
+if ! grep -q 'GCS_FORWARDER_LABEL' "$FULL_CLEANUP_SCRIPT"; then
+ echo "full cleanup should remove the GCS forwarder" >&2
+ exit 1
+fi
+
+FULL_CLEANUP_BIN="$TMP_DIR/full-cleanup-bin"
+FULL_CLEANUP_BEACON="$TMP_DIR/full-cleanup-beacon"
+FULL_CLEANUP_ARGS="$TMP_DIR/full-cleanup-args"
+FULL_CLEANUP_RECEIPT="$TMP_DIR/full-cleanup-receipt"
+FULL_CLEANUP_RUNTIME="$TMP_DIR/full-cleanup-runtime"
+FULL_CLEANUP_CONFIG="$TMP_DIR/full-cleanup-config"
+FULL_CLEANUP_OPT="$TMP_DIR/full-cleanup-opt"
+mkdir -p "$FULL_CLEANUP_BIN" "$FULL_CLEANUP_RUNTIME" "$FULL_CLEANUP_CONFIG" "$FULL_CLEANUP_OPT"
+printf '%s\n' preserved >"$FULL_CLEANUP_RUNTIME/runtime.jsonl"
+cat >"$FULL_CLEANUP_BEACON" <<'STUB'
+#!/bin/sh
+case "$1" in
+ version) echo "beacon test" ;;
+ endpoint) printf '%s\n' "$*" >"$FULL_CLEANUP_ARGS" ;;
+ *) exit 1 ;;
+esac
+STUB
+cat >"$FULL_CLEANUP_BIN/launchctl" <<'STUB'
+#!/bin/sh
+exit 1
+STUB
+cat >"$FULL_CLEANUP_BIN/stat" <<'STUB'
+#!/bin/sh
+case "$*" in
+ *"/dev/console"*) echo loginwindow ;;
+ *) /usr/bin/stat "$@" ;;
+esac
+STUB
+cat >"$FULL_CLEANUP_BIN/pkgutil" <<'STUB'
+#!/bin/sh
+case "$1" in
+ --pkg-info) [ "$2" = "ai.asymptote.beacon.endpoint" ] ;;
+ --forget) printf '%s\n' "$2" >"$FULL_CLEANUP_RECEIPT" ;;
+ *) exit 1 ;;
+esac
+STUB
+chmod +x "$FULL_CLEANUP_BEACON" "$FULL_CLEANUP_BIN/launchctl" "$FULL_CLEANUP_BIN/stat" "$FULL_CLEANUP_BIN/pkgutil"
+
+PATH="$FULL_CLEANUP_BIN:$PATH" \
+FULL_CLEANUP_ARGS="$FULL_CLEANUP_ARGS" \
+FULL_CLEANUP_RECEIPT="$FULL_CLEANUP_RECEIPT" \
+BEACON_BIN="$FULL_CLEANUP_BEACON" \
+BEACON_KEEP_LOGS=1 \
+COLLECTOR_LABEL=com.test.beacon.collector \
+UPDATER_LABEL=com.test.beacon.updater \
+S3_FORWARDER_LABEL=com.test.beacon.s3 \
+GCS_FORWARDER_LABEL=com.test.beacon.gcs \
+FALCON_FORWARDER_LABEL=com.test.beacon.falcon \
+RUNTIME_DIR="$FULL_CLEANUP_RUNTIME" \
+SYSTEM_CONFIG_DIR="$FULL_CLEANUP_CONFIG" \
+OPT_BEACON_DIR="$FULL_CLEANUP_OPT" \
+"$FULL_CLEANUP_SCRIPT" >/dev/null 2>&1
+if ! grep -q -- '--keep-logs' "$FULL_CLEANUP_ARGS"; then
+ echo "full cleanup should pass --keep-logs to endpoint uninstall" >&2
+ exit 1
+fi
+if [ ! -f "$FULL_CLEANUP_RUNTIME/runtime.jsonl" ]; then
+ echo "full cleanup should preserve the runtime directory when requested" >&2
+ exit 1
+fi
+if [ "$(cat "$FULL_CLEANUP_RECEIPT")" != "ai.asymptote.beacon.endpoint" ]; then
+ echo "full cleanup should forget only the known Beacon package receipt" >&2
+ exit 1
+fi
+
+if ! grep -q 'O_NOFOLLOW' "$FULL_CLEANUP_SCRIPT" || grep -q 'chown -R' "$FULL_CLEANUP_SCRIPT"; then
+ echo "full cleanup should reject symlinks and avoid recursive ownership changes" >&2
+ exit 1
+fi
+
+FULL_CLEANUP_USER_BIN="$TMP_DIR/full-cleanup-user-bin"
+FULL_CLEANUP_HOME="$TMP_DIR/full-cleanup-home"
+FULL_CLEANUP_USER_CONFIG="$TMP_DIR/full-cleanup-user-config"
+FULL_CLEANUP_USER_OPT="$TMP_DIR/full-cleanup-user-opt"
+FULL_CLEANUP_SENTINEL="$TMP_DIR/full-cleanup-symlink-target"
+mkdir -p \
+ "$FULL_CLEANUP_USER_BIN" \
+ "$FULL_CLEANUP_HOME/.claude" \
+ "$FULL_CLEANUP_HOME/.codex" \
+ "$FULL_CLEANUP_HOME/.cursor" \
+ "$FULL_CLEANUP_USER_CONFIG/Endpoint" \
+ "$FULL_CLEANUP_USER_OPT"
+printf '%s\n' '{"collector":{"grpc_port":54317,"http_port":54318}}' \
+ >"$FULL_CLEANUP_USER_CONFIG/Endpoint/config.json"
+printf '%s\n' '{"env":{"CLAUDE_CODE_ENABLE_TELEMETRY":"1","OTEL_EXPORTER_OTLP_ENDPOINT":"https://otel.example.com"}}' \
+ >"$FULL_CLEANUP_HOME/.claude/settings.json"
+cat >"$FULL_CLEANUP_HOME/.codex/config.toml" <<'EOF'
+[otel]
+endpoint = "http://127.0.0.1:54317"
+
+[otel.other]
+endpoint = "http://127.0.0.1:59999"
+EOF
+printf '%s\n' do-not-touch >"$FULL_CLEANUP_SENTINEL"
+ln -s "$FULL_CLEANUP_SENTINEL" "$FULL_CLEANUP_HOME/.cursor/hooks.json"
+cat >"$FULL_CLEANUP_USER_BIN/stat" <<'STUB'
+#!/bin/sh
+case "$*" in
+ *"/dev/console"*) echo cleanupuser ;;
+ *) /usr/bin/stat "$@" ;;
+esac
+STUB
+cat >"$FULL_CLEANUP_USER_BIN/dscl" <<'STUB'
+#!/bin/sh
+printf 'NFSHomeDirectory: %s\n' "$FULL_CLEANUP_HOME"
+STUB
+cat >"$FULL_CLEANUP_USER_BIN/id" <<'STUB'
+#!/bin/sh
+case "$1" in
+ -gn) echo staff ;;
+ *) exit 0 ;;
+esac
+STUB
+chmod +x "$FULL_CLEANUP_USER_BIN/stat" "$FULL_CLEANUP_USER_BIN/dscl" "$FULL_CLEANUP_USER_BIN/id"
+
+PATH="$FULL_CLEANUP_USER_BIN:$FULL_CLEANUP_BIN:$PATH" \
+FULL_CLEANUP_HOME="$FULL_CLEANUP_HOME" \
+FULL_CLEANUP_ARGS="$FULL_CLEANUP_ARGS" \
+FULL_CLEANUP_RECEIPT="$FULL_CLEANUP_RECEIPT" \
+BEACON_BIN="$FULL_CLEANUP_BEACON" \
+COLLECTOR_LABEL=com.test.user.beacon.collector \
+UPDATER_LABEL=com.test.user.beacon.updater \
+S3_FORWARDER_LABEL=com.test.user.beacon.s3 \
+GCS_FORWARDER_LABEL=com.test.user.beacon.gcs \
+FALCON_FORWARDER_LABEL=com.test.user.beacon.falcon \
+RUNTIME_DIR="$TMP_DIR/full-cleanup-user-runtime" \
+SYSTEM_CONFIG_DIR="$FULL_CLEANUP_USER_CONFIG" \
+OPT_BEACON_DIR="$FULL_CLEANUP_USER_OPT" \
+"$FULL_CLEANUP_SCRIPT" >/dev/null 2>&1
+if ! grep -q 'https://otel.example.com' "$FULL_CLEANUP_HOME/.claude/settings.json"; then
+ echo "full cleanup should preserve non-Beacon Claude OTLP settings" >&2
+ exit 1
+fi
+if [ "$(cat "$FULL_CLEANUP_SENTINEL")" != "do-not-touch" ]; then
+ echo "full cleanup should never follow user-controlled config symlinks" >&2
+ exit 1
+fi
+if grep -q '54317' "$FULL_CLEANUP_HOME/.codex/config.toml" ||
+ ! grep -q '59999' "$FULL_CLEANUP_HOME/.codex/config.toml"; then
+ echo "full cleanup should remove only Codex OTLP blocks matching installed Beacon ports" >&2
+ exit 1
+fi
PKG_TEST_BIN="$TMP_DIR/pkg-bin"
PKG_TEST_ROOT="$TMP_DIR/pkg-root"
@@ -388,6 +595,9 @@ case "$1" in
--version)
echo "vector 0.56.0"
;;
+ validate)
+ exit 0
+ ;;
*)
echo "unexpected vector args: $*" >&2
exit 1
@@ -488,7 +698,7 @@ AWS_SHARED_CREDENTIALS_FILE="/tmp/test-aws-credentials" \
AWS_CONFIG_FILE="/tmp/test-aws-config" \
AWS_WEB_IDENTITY_TOKEN_FILE="/tmp/test-web-identity-token" \
AWS_ROLE_ARN="arn:aws:iam::123456789012:role/beacon-demo" \
-"$ROOT_DIR/packaging/macos/jamf/claude/s3/install-forwarder.sh" _ _ _ "beacon-test-bucket" "us-west-2" "beacon/claude/runtime" "STANDARD_IA" "end" >/dev/null
+"$ROOT_DIR/packaging/macos/jamf/claude/s3/install-forwarder.sh" _ _ _ "beacon-test-bucket" "us-west-2" "beacon/claude/runtime/" "STANDARD_IA" "end" >/dev/null
if [ ! -f "$S3_FORWARDER_BASE/s3-vector.toml" ]; then
echo "S3 Vector config was not written" >&2
@@ -611,3 +821,261 @@ if [ ! -f "$S3_FORWARDER_MARKER" ]; then
echo "combined S3 Vector repair should run forwarder before failing repair" >&2
exit 1
fi
+
+GCS_FORWARDER_BASE="$TMP_DIR/gcs-forwarders"
+GCS_LAUNCHDAEMONS_DIR="$TMP_DIR/gcs-launchdaemons"
+GCS_CREDENTIALS="$TMP_DIR/gcs-service-account.json"
+mkdir -p "$GCS_LAUNCHDAEMONS_DIR"
+printf '%s\n' '{"type":"service_account","project_id":"beacon-test"}' >"$GCS_CREDENTIALS"
+chmod 0600 "$GCS_CREDENTIALS"
+
+BEACON_VECTOR_BIN="$FAKE_VECTOR" \
+BEACON_GCS_FORWARDER_WRAPPER="$ROOT_DIR/packaging/macos/jamf/claude/gcs/run-forwarder.sh" \
+BEACON_FORWARDER_BASE_DIR="$GCS_FORWARDER_BASE" \
+BEACON_LAUNCHDAEMONS_DIR="$GCS_LAUNCHDAEMONS_DIR" \
+BEACON_RUNTIME_LOG_PATHS="$TMP_DIR/gcs-runtime.jsonl" \
+BEACON_NO_START="1" \
+GOOGLE_APPLICATION_CREDENTIALS="$GCS_CREDENTIALS" \
+GOOGLE_CLOUD_PROJECT="beacon-test" \
+"$ROOT_DIR/packaging/macos/jamf/claude/gcs/install-forwarder.sh" _ _ _ "beacon-gcs-test-bucket" "beacon/claude/runtime/" "NEARLINE" "end" >/dev/null
+
+for path in \
+ "$GCS_FORWARDER_BASE/gcs-vector.toml" \
+ "$GCS_FORWARDER_BASE/gcs-vector.env" \
+ "$GCS_LAUNCHDAEMONS_DIR/com.beacon.endpoint.gcs-forwarder.plist"
+do
+ if [ ! -f "$path" ]; then
+ echo "GCS forwarder output missing: $path" >&2
+ exit 1
+ fi
+done
+
+for expected in \
+ 'sinks.beacon_runtime_gcs' \
+ 'sinks.beacon_inventory_gcs' \
+ "$TMP_DIR/gcs-runtime.jsonl" \
+ "$TMP_DIR/inventory_state.jsonl" \
+ 'key_prefix = "${BEACON_GCS_PREFIX:-beacon}/runtime/date=%F/"' \
+ 'key_prefix = "${BEACON_GCS_PREFIX:-beacon}/inventory/date=%F/"' \
+ 'read_from = "beginning"' \
+ 'compression = "gzip"' \
+ 'filename_append_uuid = true' \
+ '[sinks.beacon_runtime_gcs.healthcheck]' \
+ '[sinks.beacon_inventory_gcs.healthcheck]' \
+ 'enabled = false'
+do
+ if ! grep -Fq "$expected" "$GCS_FORWARDER_BASE/gcs-vector.toml"; then
+ echo "GCS Vector config missing: $expected" >&2
+ exit 1
+ fi
+done
+
+if grep -q 'beacon-gcs-test-bucket\|service_account\|private_key\|\.input_tokens =\|\.output_tokens =\|\.cost_usd =' "$GCS_FORWARDER_BASE/gcs-vector.toml"; then
+ echo "GCS Vector config should not contain destination values, credentials, or parallel usage fields" >&2
+ exit 1
+fi
+for expected in \
+ "BEACON_GCS_BUCKET='beacon-gcs-test-bucket'" \
+ "BEACON_GCS_PREFIX='beacon/claude'" \
+ "BEACON_GCS_STORAGE_CLASS='NEARLINE'" \
+ "GOOGLE_APPLICATION_CREDENTIALS='$GCS_CREDENTIALS'" \
+ "GOOGLE_CLOUD_PROJECT='beacon-test'"
+do
+ if ! grep -Fq "$expected" "$GCS_FORWARDER_BASE/gcs-vector.env"; then
+ echo "GCS Vector env missing: $expected" >&2
+ exit 1
+ fi
+done
+case "$(ls -l "$GCS_FORWARDER_BASE/gcs-vector.env" | awk '{print $1}')" in
+ -rw-------*) ;;
+ *)
+ echo "GCS Vector env should be 0600" >&2
+ exit 1
+ ;;
+esac
+if ! grep -q 'RunAtLoad' "$GCS_LAUNCHDAEMONS_DIR/com.beacon.endpoint.gcs-forwarder.plist"; then
+ echo "GCS Vector plist missing RunAtLoad" >&2
+ exit 1
+fi
+
+RELATIVE_CREDENTIALS_OUTPUT="$TMP_DIR/gcs-relative-credentials.out"
+if BEACON_VECTOR_BIN="$FAKE_VECTOR" \
+ BEACON_GCS_FORWARDER_WRAPPER="$ROOT_DIR/packaging/macos/jamf/claude/gcs/run-forwarder.sh" \
+ BEACON_FORWARDER_BASE_DIR="$TMP_DIR/gcs-relative-forwarders" \
+ BEACON_LAUNCHDAEMONS_DIR="$TMP_DIR/gcs-relative-launchdaemons" \
+ BEACON_NO_START="1" \
+ GOOGLE_APPLICATION_CREDENTIALS="relative-service-account.json" \
+ "$ROOT_DIR/packaging/macos/jamf/claude/gcs/install-forwarder.sh" _ _ _ "beacon-gcs-test-bucket" >"$RELATIVE_CREDENTIALS_OUTPUT" 2>&1
+then
+ echo "GCS installer should reject a relative credential path" >&2
+ exit 1
+fi
+if ! grep -q 'must be an absolute path' "$RELATIVE_CREDENTIALS_OUTPUT"; then
+ echo "GCS installer should explain launchd credential path requirements" >&2
+ exit 1
+fi
+
+GCS_ATOMIC_BASE="$TMP_DIR/gcs-atomic-forwarders"
+GCS_ATOMIC_PLISTS="$TMP_DIR/gcs-atomic-launchdaemons"
+GCS_FAIL_VECTOR="$TMP_DIR/gcs-vector-validation-fails"
+mkdir -p "$GCS_ATOMIC_BASE" "$GCS_ATOMIC_PLISTS"
+printf '%s\n' original-config >"$GCS_ATOMIC_BASE/gcs-vector.toml"
+printf '%s\n' original-env >"$GCS_ATOMIC_BASE/gcs-vector.env"
+printf '%s\n' original-plist >"$GCS_ATOMIC_PLISTS/com.beacon.endpoint.gcs-forwarder.plist"
+cat >"$GCS_FAIL_VECTOR" <<'STUB'
+#!/bin/sh
+case "$1" in
+ --version) exit 0 ;;
+ validate) exit 12 ;;
+ *) exit 1 ;;
+esac
+STUB
+chmod +x "$GCS_FAIL_VECTOR"
+if BEACON_VECTOR_BIN="$GCS_FAIL_VECTOR" \
+ BEACON_GCS_FORWARDER_WRAPPER="$ROOT_DIR/packaging/macos/jamf/claude/gcs/run-forwarder.sh" \
+ BEACON_FORWARDER_BASE_DIR="$GCS_ATOMIC_BASE" \
+ BEACON_LAUNCHDAEMONS_DIR="$GCS_ATOMIC_PLISTS" \
+ BEACON_RUNTIME_LOG_PATHS="$TMP_DIR/gcs-atomic-runtime.jsonl" \
+ BEACON_NO_START="1" \
+ GOOGLE_APPLICATION_CREDENTIALS="$GCS_CREDENTIALS" \
+ "$ROOT_DIR/packaging/macos/jamf/claude/gcs/install-forwarder.sh" _ _ _ "beacon-gcs-test-bucket" >/dev/null 2>&1
+then
+ echo "GCS installer should fail when Vector rejects generated config" >&2
+ exit 1
+fi
+if [ "$(cat "$GCS_ATOMIC_BASE/gcs-vector.toml")" != "original-config" ] ||
+ [ "$(cat "$GCS_ATOMIC_BASE/gcs-vector.env")" != "original-env" ] ||
+ [ "$(cat "$GCS_ATOMIC_PLISTS/com.beacon.endpoint.gcs-forwarder.plist")" != "original-plist" ]; then
+ echo "GCS validation failure should preserve the last installed configuration" >&2
+ exit 1
+fi
+for path in "$GCS_ATOMIC_BASE"/*.tmp.* "$GCS_ATOMIC_PLISTS"/*.tmp.*; do
+ if [ -e "$path" ]; then
+ echo "GCS validation failure should remove temporary file: $path" >&2
+ exit 1
+ fi
+done
+
+GCS_RUNNER="$TMP_DIR/gcs-vector-runner"
+GCS_RUN_MARKER="$TMP_DIR/gcs-vector-run-args"
+cat >"$GCS_RUNNER" <<'STUB'
+#!/bin/sh
+printf '%s\n' "$*" > "$GCS_RUN_MARKER"
+STUB
+chmod +x "$GCS_RUNNER"
+BEACON_VECTOR_BIN="$GCS_RUNNER" \
+BEACON_GCS_VECTOR_CONFIG="$GCS_FORWARDER_BASE/gcs-vector.toml" \
+BEACON_GCS_VECTOR_ENV="$GCS_FORWARDER_BASE/gcs-vector.env" \
+GCS_RUN_MARKER="$GCS_RUN_MARKER" \
+"$ROOT_DIR/packaging/macos/jamf/claude/gcs/run-forwarder.sh"
+if ! grep -Fq -- "--config $GCS_FORWARDER_BASE/gcs-vector.toml" "$GCS_RUN_MARKER"; then
+ echo "GCS wrapper should exec Vector with the generated config" >&2
+ exit 1
+fi
+
+FAKE_LAUNCHCTL_BIN="$TMP_DIR/fake-launchctl-bin"
+FAKE_LAUNCHCTL_STATE="$TMP_DIR/fake-launchctl-state"
+GCS_LIFECYCLE_BASE="$TMP_DIR/gcs-lifecycle-forwarders"
+GCS_LIFECYCLE_PLISTS="$TMP_DIR/gcs-lifecycle-launchdaemons"
+mkdir -p "$FAKE_LAUNCHCTL_BIN" "$GCS_LIFECYCLE_PLISTS"
+printf '%s\n' old >"$FAKE_LAUNCHCTL_STATE"
+cat >"$FAKE_LAUNCHCTL_BIN/launchctl" <<'STUB'
+#!/bin/sh
+case "$1" in
+ bootout)
+ printf '%s\n' stopping >"$FAKE_LAUNCHCTL_STATE"
+ ;;
+ bootstrap)
+ printf '%s\n' running >"$FAKE_LAUNCHCTL_STATE"
+ ;;
+ print)
+ [ -f "$FAKE_LAUNCHCTL_STATE" ] || exit 113
+ state="$(cat "$FAKE_LAUNCHCTL_STATE")"
+ if [ "$state" = "stopping" ]; then
+ echo "state = stopping"
+ rm -f "$FAKE_LAUNCHCTL_STATE"
+ exit 0
+ fi
+ if [ "${FAKE_LAUNCHCTL_CRASH_LOOP:-0}" = "1" ]; then
+ count_file="$FAKE_LAUNCHCTL_STATE.count"
+ count=0
+ [ ! -f "$count_file" ] || count="$(cat "$count_file")"
+ count=$((count + 1))
+ printf '%s\n' "$count" >"$count_file"
+ if [ $((count % 2)) -eq 0 ]; then
+ echo "state = exited"
+ exit 0
+ fi
+ fi
+ echo "state = running"
+ echo "pid = 1234"
+ ;;
+ *)
+ echo "unexpected launchctl args: $*" >&2
+ exit 1
+ ;;
+esac
+STUB
+chmod +x "$FAKE_LAUNCHCTL_BIN/launchctl"
+
+PATH="$FAKE_LAUNCHCTL_BIN:$PATH" \
+FAKE_LAUNCHCTL_STATE="$FAKE_LAUNCHCTL_STATE" \
+BEACON_VECTOR_BIN="$FAKE_VECTOR" \
+BEACON_GCS_FORWARDER_WRAPPER="$ROOT_DIR/packaging/macos/jamf/claude/gcs/run-forwarder.sh" \
+BEACON_FORWARDER_BASE_DIR="$GCS_LIFECYCLE_BASE" \
+BEACON_LAUNCHDAEMONS_DIR="$GCS_LIFECYCLE_PLISTS" \
+BEACON_RUNTIME_LOG_PATHS="$TMP_DIR/gcs-lifecycle-runtime.jsonl" \
+GOOGLE_APPLICATION_CREDENTIALS="$GCS_CREDENTIALS" \
+"$ROOT_DIR/packaging/macos/jamf/claude/gcs/install-forwarder.sh" _ _ _ "beacon-gcs-test-bucket" "beacon" "STANDARD" "end" >/dev/null
+if [ "$(cat "$FAKE_LAUNCHCTL_STATE")" != "running" ]; then
+ echo "GCS installer should wait for bootout and bootstrap a running service" >&2
+ exit 1
+fi
+
+GCS_CRASH_BASE="$TMP_DIR/gcs-crash-forwarders"
+GCS_CRASH_PLISTS="$TMP_DIR/gcs-crash-launchdaemons"
+mkdir -p "$GCS_CRASH_PLISTS"
+printf '%s\n' old >"$FAKE_LAUNCHCTL_STATE"
+rm -f "$FAKE_LAUNCHCTL_STATE.count"
+if PATH="$FAKE_LAUNCHCTL_BIN:$PATH" \
+ FAKE_LAUNCHCTL_STATE="$FAKE_LAUNCHCTL_STATE" \
+ FAKE_LAUNCHCTL_CRASH_LOOP=1 \
+ BEACON_FORWARDER_START_ATTEMPTS=4 \
+ BEACON_VECTOR_BIN="$FAKE_VECTOR" \
+ BEACON_GCS_FORWARDER_WRAPPER="$ROOT_DIR/packaging/macos/jamf/claude/gcs/run-forwarder.sh" \
+ BEACON_FORWARDER_BASE_DIR="$GCS_CRASH_BASE" \
+ BEACON_LAUNCHDAEMONS_DIR="$GCS_CRASH_PLISTS" \
+ BEACON_RUNTIME_LOG_PATHS="$TMP_DIR/gcs-crash-runtime.jsonl" \
+ GOOGLE_APPLICATION_CREDENTIALS="$GCS_CREDENTIALS" \
+ "$ROOT_DIR/packaging/macos/jamf/claude/gcs/install-forwarder.sh" _ _ _ "beacon-gcs-test-bucket" "beacon" "STANDARD" "end" >/dev/null 2>&1
+then
+ echo "GCS installer should reject a crash-looping launchd job" >&2
+ exit 1
+fi
+
+GCS_FAKE_REPAIR="$TMP_DIR/fake-gcs-repair-fails.sh"
+GCS_FAKE_FORWARDER="$TMP_DIR/fake-gcs-forwarder-runs.sh"
+GCS_FORWARDER_MARKER="$TMP_DIR/gcs-forwarder-ran"
+cat >"$GCS_FAKE_REPAIR" <<'STUB'
+#!/bin/sh
+exit 11
+STUB
+cat >"$GCS_FAKE_FORWARDER" <<'STUB'
+#!/bin/sh
+printf '%s\n' "$*" > "$GCS_FORWARDER_MARKER"
+STUB
+chmod +x "$GCS_FAKE_REPAIR" "$GCS_FAKE_FORWARDER"
+
+BEACON_REPAIR_HOOKS_SCRIPT="$GCS_FAKE_REPAIR" \
+BEACON_GCS_VECTOR_SCRIPT="$GCS_FAKE_FORWARDER" \
+BEACON_GCS_BUCKET="beacon-gcs-test-bucket" \
+GOOGLE_APPLICATION_CREDENTIALS="$GCS_CREDENTIALS" \
+GCS_FORWARDER_MARKER="$GCS_FORWARDER_MARKER" \
+"$ROOT_DIR/packaging/macos/jamf/claude/gcs/repair-hooks-and-forwarder.sh" >/dev/null 2>&1 && {
+ echo "combined GCS Vector repair should return the failing repair status" >&2
+ exit 1
+}
+if [ ! -f "$GCS_FORWARDER_MARKER" ]; then
+ echo "combined GCS Vector repair should run forwarder before failing repair" >&2
+ exit 1
+fi