The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
Add Jamf Falcon forwarding guide
shukieshah166764e70611
diff --git a/docs/docs.json b/docs/docs.jsonindex 8c517d56..b3cf7c75 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -198,6 +198,7 @@"mdm/jamf","mdm/jamf/claude","guides/jamf-s3-mdm",+ "guides/jamf-falcon-mdm","mdm/fleet"]},@@ -407,7 +408,8 @@"root": "guides/use-cases","pages": ["guides/agent-runtime-telemetry",- "guides/jamf-s3-mdm"+ "guides/jamf-s3-mdm",+ "guides/jamf-falcon-mdm"]},{diff --git a/docs/guides/jamf-falcon-mdm.mdx b/docs/guides/jamf-falcon-mdm.mdxnew file mode 100644index 00000000..e25a47ae--- /dev/null+++ b/docs/guides/jamf-falcon-mdm.mdx@@ -0,0 +1,320 @@+---+title: "Deploy Beacon With Jamf And CrowdStrike Falcon"+description: "Self-serve Jamf Pro setup for Beacon endpoint telemetry, Claude Code hooks, and CrowdStrike Falcon LogScale HEC forwarding"+---++## Overview++Use this guide when you want a Jamf Pro policy to install Beacon for macOS users, configure Claude Code hooks, and forward Beacon runtime telemetry to CrowdStrike Falcon LogScale through HEC.++The end state is:++- Beacon is installed under `/opt/beacon`.+- The system endpoint collector runs as a LaunchDaemon.+- Claude Code hooks are installed for the logged-in console user.+- Runtime activity is written to `/var/log/beacon-agent/runtime.jsonl`.+- Vector tails the runtime JSONL log and forwards events to CrowdStrike Falcon HEC.+- The Falcon Vector forwarder runs as `com.beacon.endpoint.falcon-forwarder`.++```mermaid+flowchart LR+ JamfPolicy[Jamf policy] --> Package[Beacon pkg]+ JamfPolicy --> Helper[repair-hooks-and-forwarder.sh]+ Package --> Beacon["/opt/beacon"]+ Helper --> Collector[Endpoint collector]+ Helper --> Hooks[Claude Code hooks]+ Hooks --> RuntimeLog["runtime.jsonl"]+ RuntimeLog --> Vector[Vector LaunchDaemon]+ Vector --> Falcon[CrowdStrike Falcon HEC]+```++## Prerequisites++Before creating the Jamf policy, prepare:++- A signed and notarized Beacon endpoint `.pkg` that includes `/opt/beacon/bin/vector`.+- Claude Code installed on the target Mac.+- A CrowdStrike Falcon LogScale data connection for Beacon JSONL events.+- The Falcon HEC endpoint URL from the data connection.+- The Falcon HEC token or API key generated for that data connection.+- A parser or sourcetype value, usually `json` or your custom Beacon parser name.++For CrowdStrike data onboarding, parser setup, screenshots, and a direct HEC smoke test, see [CrowdStrike Falcon LogScale](/log-forwarding/falcon).++## Falcon HEC Settings++CrowdStrike HEC values normally look like:++```bash+FALCON_HEC_ENDPOINT="https://<your-tenant>.ingest.<region>.crowdstrike.com/services/collector"+FALCON_HEC_TOKEN="<your-token>"+FALCON_SOURCE="beacon-endpoint-agent"+FALCON_SOURCETYPE="json"+```++Use the exact endpoint URL and token generated by your Falcon LogScale data connection. If your connection requires a repository or index, pass it as the optional repository parameter.++Beacon stores the Falcon token only in the root-owned Vector environment file:++```text+/Library/Application Support/Beacon/Forwarders/falcon-vector.env+```++That file is mode `0600` and is sourced by the Vector LaunchDaemon wrapper.++## Jamf Policy Setup++Jamf Pro separates package installation from script execution. Use the Packages payload to install the Beacon `.pkg`, then use a Scripts payload to run a wrapper that calls Beacon's packaged Jamf helper.++For the most reliable rollout, use two policies:++- **Policy 1: Install Beacon package.** Installs the signed `.pkg`.+- **Policy 2: Configure Beacon Falcon forwarding.** Runs after the package is installed and calls the packaged helper.++You can combine the package and script payloads in one policy if your Jamf workflow guarantees the package is installed before the script runs.++### 1. Upload The Beacon Package++Upload the signed Beacon endpoint package to Jamf Pro and add it to a policy using the Packages payload with the install action.++The package installs:++```text+/opt/beacon/bin/beacon+/opt/beacon/bin/beacon-otelcol+/opt/beacon/bin/vector+/opt/beacon/jamf/claude/common/repair-hooks.sh+/opt/beacon/jamf/claude/falcon/install-forwarder.sh+/opt/beacon/jamf/claude/falcon/repair-hooks-and-forwarder.sh+/opt/beacon/jamf/claude/falcon/run-forwarder.sh+```++Current packages use `/opt/beacon/jamf/claude/falcon/repair-hooks-and-forwarder.sh`. Older internal smoke-test instructions may refer to a legacy helper path under `/opt/beacon/jamf/scripts`; use the path that exists in the package installed on the target Mac.++### 2. Add A Jamf Script Wrapper++Add a script to Jamf Pro that invokes Beacon's packaged helper. The script must exist in Jamf Pro before it can be added to a policy.++```bash+#!/bin/bash+set -euo pipefail++FALCON_HEC_ENDPOINT="${4:-}"+FALCON_HEC_TOKEN="${5:-}"+FALCON_SOURCE="${6:-beacon-endpoint-agent}"+FALCON_SOURCETYPE="${7:-json}"+OTLP_GRPC_PORT="${8:-4317}"+OTLP_HTTP_PORT="${9:-4318}"+FALCON_REPOSITORY="${10:-}"++/opt/beacon/jamf/claude/falcon/repair-hooks-and-forwarder.sh \+ _ _ _ \+ "$FALCON_HEC_ENDPOINT" \+ "$FALCON_HEC_TOKEN" \+ "$FALCON_SOURCE" \+ "$FALCON_SOURCETYPE" \+ "$OTLP_GRPC_PORT" \+ "$OTLP_HTTP_PORT" \+ "$FALCON_REPOSITORY"+```++Use Jamf script parameter labels so policy editors know what each value means:++| Parameter | Label | Example |+| --- | --- | --- |+| 4 | Falcon HEC endpoint | `https://<tenant>.ingest.<region>.crowdstrike.com/services/collector` |+| 5 | Falcon HEC token | `********` |+| 6 | Falcon source | `beacon-endpoint-agent` |+| 7 | Falcon sourcetype/parser | `json` |+| 8 | OTLP gRPC port | `4317` |+| 9 | OTLP HTTP port | `4318` |+| 10 | Falcon repository/index | `beacon` |++Jamf script parameters are convenient for non-secret values such as endpoint, source, sourcetype, and repository. For the HEC token, prefer your Jamf secret injection mechanism when available. Avoid putting long-lived tokens directly in ordinary policy parameter fields or policy logs.++## What The Helper Does++The combined helper performs all endpoint and forwarding setup:++- Installs the Falcon Vector runtime-log forwarder.+- Repairs the Beacon system endpoint.+- Starts `com.beacon.endpoint.collector`.+- Prepares:+ - `/var/log/beacon-agent/runtime.jsonl`+ - `/var/log/beacon-agent/inventory_state.jsonl`+ - `/var/log/beacon-agent/inventory-state.json`+- Grants the console user append access for hook-written logs.+- Installs Claude Code hooks for the interactive console user.+- Writes:+ - `/Library/Application Support/Beacon/Forwarders/falcon-vector.toml`+ - `/Library/Application Support/Beacon/Forwarders/falcon-vector.env`+ - `/Library/LaunchDaemons/com.beacon.endpoint.falcon-forwarder.plist`+- Starts `com.beacon.endpoint.falcon-forwarder`.++End users do not need to run any Beacon command or edit any local config.++## Manual Smoke Test++To simulate the Jamf policy on one Mac, install the Beacon package, then run the packaged helper manually.++If the package downloaded to `~/Downloads`, install it first:++```bash+cd ~/Downloads+sudo installer -pkg ./BeaconEndpointAgent-*.pkg -target /+```++If the filename is different, replace `./BeaconEndpointAgent-*.pkg` with the exact package filename.++Then set your Falcon values and run the helper. Jamf reserves script arguments 1-3, so pass `_ _ _` before the custom parameters:++```bash+export FALCON_HEC_ENDPOINT="https://<your-tenant>.ingest.<region>.crowdstrike.com/services/collector"+export FALCON_HEC_TOKEN="<your-token>"++sudo /opt/beacon/jamf/claude/falcon/repair-hooks-and-forwarder.sh \+ _ _ _ \+ "$FALCON_HEC_ENDPOINT" \+ "$FALCON_HEC_TOKEN" \+ "beacon-endpoint-agent" \+ "json"+```++## Validate A Deployed Mac++Run these commands on a target Mac after the Jamf policy completes.++### Check Services++```bash+sudo launchctl print system/com.beacon.endpoint.collector+sudo launchctl print system/com.beacon.endpoint.falcon-forwarder+```++Both services should report `state = running`.++### Check Forwarder Logs++```bash+sudo tail -n 50 /tmp/com.beacon.endpoint.falcon-forwarder.err+```++Expected:++```text+no repeated auth, TLS, DNS, or HTTP errors in stderr+```++### Check Local Files++```bash+ls -l /var/log/beacon-agent/runtime.jsonl+ls -l /var/log/beacon-agent/inventory_state.jsonl+```++### Check Vector Config++```bash+sudo grep -E 'runtime.jsonl|read_from|BEACON_FALCON_HEC_ENDPOINT|Authorization' \+ "/Library/Application Support/Beacon/Forwarders/falcon-vector.toml"+```++Expected:++```text+include = ["/var/log/beacon-agent/runtime.jsonl", "/Users/*/.beacon/endpoint/logs/runtime.jsonl"]+read_from = "${BEACON_VECTOR_READ_FROM:-end}"+uri = "${BEACON_FALCON_HEC_ENDPOINT}"+Authorization = "Bearer ${BEACON_FALCON_HEC_TOKEN}"+```++Runtime forwarding starts at the end of the runtime log so historical session activity is not backfilled when Vector is first installed.++## Generate A Claude Hook Event++Generate a unique Claude prompt in headless mode or in a normal Claude Code session:++```bash+MARKER="beacon crowdstrike hook test $(date +%s)"+claude -p "$MARKER"+```++Confirm the event was written locally:++```bash+sudo grep "$MARKER" /var/log/beacon-agent/runtime.jsonl+```++Then search for the same marker in CrowdStrike Falcon LogScale. Example search:++```text+source = "beacon-endpoint-agent" "beacon crowdstrike hook test"+```++If you use a custom source, repository, or parser, adjust the query to match your data connection.++## Troubleshooting++### Forwarder Is Not Running++Check launchd and stderr:++```bash+sudo launchctl print system/com.beacon.endpoint.falcon-forwarder+sudo tail -n 100 /tmp/com.beacon.endpoint.falcon-forwarder.err+```++Load it manually:++```bash+sudo launchctl bootstrap system /Library/LaunchDaemons/com.beacon.endpoint.falcon-forwarder.plist+```++If launchd remains opaque, run Vector in the foreground:++```bash+sudo /opt/beacon/jamf/claude/falcon/run-forwarder.sh+```++Keep that terminal open while generating a Claude hook event.++### Token Or Endpoint Is Wrong++Check the env file without exposing secrets:++```bash+sudo sh -c 'sed -E "s/(BEACON_FALCON_HEC_ENDPOINT|BEACON_FALCON_HEC_TOKEN|BEACON_FALCON_SOURCE|BEACON_FALCON_SOURCETYPE|BEACON_FALCON_INDEX)=.*/\1=<redacted>/" "/Library/Application Support/Beacon/Forwarders/falcon-vector.env"'+```++If Vector reports `401`, `403`, or repository errors, regenerate the API key in Falcon and verify that the repository/index parameter matches the token scope.++### Claude Hooks Are Missing++Fully restart Claude Code after the Jamf policy runs. Then inspect the user's Claude settings:++```bash+grep -n 'BEACON_ENDPOINT_CLI\|beacon-hooks' ~/.claude/settings.json+```++You should see commands that call the packaged Beacon hook binary.++### Local Event Exists But Falcon Search Is Empty++Confirm the event appears in `/var/log/beacon-agent/runtime.jsonl`, then check Vector stderr for batching, TLS, DNS, or HTTP errors. Falcon searches can lag behind ingestion; wait a minute and search for the exact marker string.++## Related++<Columns cols={2}>+ <Card title="CrowdStrike Falcon LogScale" icon="shield-halved" href="/log-forwarding/falcon">+ Create the Falcon parser and data connection, then validate direct HEC ingestion.+ </Card>+ <Card title="Claude with Jamf" icon="laptop" href="/mdm/jamf/claude">+ Review the Claude-specific Jamf helper layout.+ </Card>+ <Card title="Endpoint event schema" icon="code" href="/telemetry-schema/event-schema">+ Review normalized Beacon JSONL fields and example events.+ </Card>+ <Card title="Vector forwarding" icon="route" href="/concepts/vector-forwarding">+ Understand how Beacon uses Vector for customer-managed forwarding.+ </Card>+</Columns>diff --git a/docs/log-forwarding/falcon.mdx b/docs/log-forwarding/falcon.mdxindex 7c33ccdb..716c34fd 100644--- a/docs/log-forwarding/falcon.mdx+++ b/docs/log-forwarding/falcon.mdx@@ -311,6 +311,9 @@ Beacon applies redaction, sanitization, truncation, and event-size limits before<Card title="Log forwarding" icon="tower-broadcast" href="/log-forwarding">Review forwarding patterns and validation steps.</Card>+ <Card title="Deploy Beacon With Jamf And CrowdStrike Falcon" icon="laptop" href="/guides/jamf-falcon-mdm">+ Roll out Claude hooks and Falcon runtime-log forwarding with Jamf Pro.+ </Card><Card title="Endpoint install" icon="download" href="/cli/endpoint-install">Configure Falcon HEC forwarding during endpoint install.</Card>diff --git a/docs/mdm/jamf/claude.mdx b/docs/mdm/jamf/claude.mdxindex 1b4c4e17..5f736c6e 100644--- a/docs/mdm/jamf/claude.mdx+++ b/docs/mdm/jamf/claude.mdx@@ -3,11 +3,16 @@ title: "Claude with Jamf"description: "Deploy Claude Code endpoint telemetry with Jamf Pro and route Beacon logs to managed destinations."----Use this page as the Claude-specific Jamf entry point. For the complete AWS S3 forwarding setup, follow the canonical self-serve guide:+Use this page as the Claude-specific Jamf entry point. For complete managed forwarding setup, follow the destination-specific self-serve guide:-<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>+<Columns cols={2}>+ <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>+ <Card title="Deploy Beacon With Jamf And CrowdStrike Falcon" icon="shield-halved" href="/guides/jamf-falcon-mdm">+ Install Beacon with Jamf Pro, configure Claude Code hooks, and forward runtime JSONL to CrowdStrike Falcon LogScale HEC.+ </Card>+</Columns>## What The Jamf Claude Flow Installs@@ -30,12 +35,17 @@ The macOS package includes these Claude-specific helpers:/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+/opt/beacon/jamf/claude/falcon/install-forwarder.sh+/opt/beacon/jamf/claude/falcon/repair-hooks-and-forwarder.sh+/opt/beacon/jamf/claude/falcon/run-forwarder.sh```Use `repair-hooks.sh` when you only need to repair the system endpoint and reinstall Claude hooks.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.+## Related<Columns cols={2}>@@ -45,4 +55,7 @@ Use `s3/repair-hooks-and-forwarder.sh` when one Jamf policy should repair the en<Card title="S3 Log Forwarding" icon="bucket" href="/log-forwarding/s3">Review the generated S3 content pack and Vector forwarding behavior.</Card>+ <Card title="CrowdStrike Falcon LogScale" icon="shield-halved" href="/log-forwarding/falcon">+ Review Falcon parser setup, HEC settings, and validation steps.+ </Card></Columns>