Skip to content

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

Add Jamf Falcon forwarding guide

shukieshah166764e70611
diff --git a/docs/docs.json b/docs/docs.json
index 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.mdx
new file mode 100644
index 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.mdx
index 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.mdx
index 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>