Skip to content

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

Add Vector-based Falcon log forwarding

shukieshaha7076f5e23dd
diff --git a/.gitignore b/.gitignore
index 851abc9a..9fce2313 100644
--- a/.gitignore
+++ b/.gitignore
@@ -37,6 +37,7 @@ cli/beacon-hooks/*.exe
!cli/beacon/internal/endpoint/cloudwatch/pack/sample-event.jsonl
!cli/beacon/internal/endpoint/gcs/pack/sample-event.jsonl
!cli/beacon/internal/endpoint/sentinel/pack/sample-event.jsonl
+!cli/beacon/internal/endpoint/falcon/pack/sample-event.jsonl
!cli/beacon/internal/endpoint/gcs/pack/sample-event.jsonl
*.log
diff --git a/cli/beacon/cmd/endpoint_destinations.go b/cli/beacon/cmd/endpoint_destinations.go
index 57e39622..e8c03a13 100644
--- a/cli/beacon/cmd/endpoint_destinations.go
+++ b/cli/beacon/cmd/endpoint_destinations.go
@@ -9,6 +9,7 @@ import (
endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/datadog"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/elastic"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/falcon"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/gcs"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/rapid7"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/s3"
@@ -73,6 +74,31 @@ type destValidate struct {
// affect help or generated docs (cobra sorts commands), but is kept stable for
// readability.
var siemDestinations = []siemDestination{
+ {
+ name: "falcon",
+ short: "Manage CrowdStrike Falcon forwarding content",
+ printConfig: &destPrintConfig{
+ short: "Print a Vector config for CrowdStrike Falcon forwarding",
+ render: func(cfg endpointconfig.Config) (string, error) { return falcon.ConfigSnippet(cfg.LogPath) },
+ },
+ installPack: &destInstallPack{
+ short: "Write CrowdStrike Falcon Vector forwarding content to a directory",
+ defaultOutputDir: falcon.DefaultOutputDir,
+ successLabel: "CrowdStrike Falcon content pack written to ",
+ outputFlagHelp: "Output directory for CrowdStrike Falcon content pack",
+ install: falcon.InstallPack,
+ },
+ validate: &destValidate{
+ short: "Write and describe a CrowdStrike Falcon validation event",
+ mode: "crowdstrike_hec",
+ message: "Beacon endpoint Falcon validation event",
+ print: func(cfg endpointconfig.Config) {
+ fmt.Println("Expected Falcon fields: vendor=beacon product=endpoint-agent destination.type=falcon destination.mode=crowdstrike_hec")
+ fmt.Println(`Expected validation query: source = "beacon-endpoint-agent" "Beacon endpoint Falcon validation event"`)
+ fmt.Println(`Hook-only query: source = "beacon-endpoint-agent" "hook-only unique marker"`)
+ },
+ },
+ },
{
name: "wazuh",
short: "Manage Wazuh integration content",
diff --git a/cli/beacon/cmd/endpoint_destinations_characterization_test.go b/cli/beacon/cmd/endpoint_destinations_characterization_test.go
index 365edea6..1fe3c868 100644
--- a/cli/beacon/cmd/endpoint_destinations_characterization_test.go
+++ b/cli/beacon/cmd/endpoint_destinations_characterization_test.go
@@ -33,6 +33,15 @@ type destinationCharCase struct {
func destinationCharCases() []destinationCharCase {
return []destinationCharCase{
+ {
+ group: "falcon",
+ installLabel: "CrowdStrike Falcon content pack written to ",
+ validateWant: []string{
+ "Expected Falcon fields: vendor=beacon product=endpoint-agent destination.type=falcon destination.mode=crowdstrike_hec",
+ `Expected validation query: source = "beacon-endpoint-agent" "Beacon endpoint Falcon validation event"`,
+ `Hook-only query: source = "beacon-endpoint-agent" "hook-only unique marker"`,
+ },
+ },
{
group: "wazuh",
installLabel: "Wazuh content pack written to ",
diff --git a/cli/beacon/internal/endpoint/falcon/falcon.go b/cli/beacon/internal/endpoint/falcon/falcon.go
new file mode 100644
index 00000000..93bac613
--- /dev/null
+++ b/cli/beacon/internal/endpoint/falcon/falcon.go
@@ -0,0 +1,66 @@
+package falcon
+
+import (
+ "embed"
+ "io/fs"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/siempack"
+)
+
+//go:embed pack/*
+var packFS embed.FS
+
+const (
+ DefaultLogPath = "/var/log/beacon-agent/runtime.jsonl"
+ DefaultOutputDir = "beacon-falcon-pack"
+)
+
+const (
+ configAsset = "pack/vector.toml.tmpl"
+ smokeTestAsset = "pack/falcon-hec-smoke-test.sh.tmpl"
+)
+
+// File is the installable pack-file type, shared with siempack.
+type File = siempack.File
+
+var pack = siempack.Pack{
+ Label: "falcon",
+ FS: packFS,
+ DefaultLogPath: DefaultLogPath,
+ DefaultOutputDir: DefaultOutputDir,
+ Assets: []siempack.Asset{
+ {Source: "pack/README.md", Name: "README.md"},
+ {Source: smokeTestAsset, Name: "falcon-hec-smoke-test.sh", TemplateLogPath: true},
+ {Source: "pack/sample-event.jsonl", Name: "sample-event.jsonl"},
+ {Source: configAsset, Name: "vector.toml", TemplateLogPath: true},
+ },
+}
+
+// mustRead returns the embedded asset at path or panics. Retained for test use.
+func mustRead(path string) string { return pack.MustRead(path) }
+
+// filesFromFS builds the file list from the supplied FS; tests use it to inject
+// read-error conditions.
+func filesFromFS(fsys fs.FS) ([]File, error) { return pack.WithFS(fsys).Files() }
+
+// configSnippetFromFS renders the Vector config using the supplied FS.
+func configSnippetFromFS(fsys fs.FS, logPath string) (string, error) {
+ return pack.WithFS(fsys).Render(configAsset, logPath)
+}
+
+// smokeTestFromFS renders the Falcon HEC smoke-test script using the supplied FS.
+func smokeTestFromFS(fsys fs.FS, logPath string) (string, error) {
+ return pack.WithFS(fsys).Render(smokeTestAsset, logPath)
+}
+
+// ConfigSnippet returns a rendered Vector configuration for Falcon HEC forwarding.
+func ConfigSnippet(logPath string) (string, error) { return pack.Render(configAsset, logPath) }
+
+// SmokeTest returns the Falcon HEC smoke-test script with logPath substituted.
+func SmokeTest(logPath string) (string, error) { return pack.Render(smokeTestAsset, logPath) }
+
+// Files returns all pack files, propagating any embedded asset read error.
+func Files() ([]File, error) { return pack.Files() }
+
+// InstallPack writes the Falcon pack files to outputDir with logPath substituted.
+func InstallPack(outputDir, logPath string) error { return pack.Install(outputDir, logPath) }
diff --git a/cli/beacon/internal/endpoint/falcon/falcon_test.go b/cli/beacon/internal/endpoint/falcon/falcon_test.go
new file mode 100644
index 00000000..4df128a4
--- /dev/null
+++ b/cli/beacon/internal/endpoint/falcon/falcon_test.go
@@ -0,0 +1,245 @@
+package falcon
+
+import (
+ "bufio"
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "testing/fstest"
+)
+
+func TestConfigSnippetUsesConfiguredPath(t *testing.T) {
+ got, err := ConfigSnippet("/tmp/beacon/runtime.jsonl")
+ if err != nil {
+ t.Fatalf("ConfigSnippet returned unexpected error: %v", err)
+ }
+ if !strings.Contains(got, "/tmp/beacon/runtime.jsonl") {
+ t.Fatalf("config did not include configured path: %s", got)
+ }
+ if strings.Contains(got, "{{LOG_PATH}}") {
+ t.Fatalf("config still contains template token: %s", got)
+ }
+ for _, want := range []string{
+ `type = "file"`,
+ `type = "remap"`,
+ `type = "http"`,
+ `BEACON_FALCON_HEC_ENDPOINT`,
+ `BEACON_FALCON_HEC_TOKEN`,
+ `Authorization = "Bearer ${BEACON_FALCON_HEC_TOKEN}"`,
+ `Content-Type = "text/plain; charset=utf-8"`,
+ `data_dir = "/Library/Application Support/Beacon/Forwarders/vector-data/falcon"`,
+ `retry_attempts = 10`,
+ } {
+ if !strings.Contains(got, want) {
+ t.Fatalf("config missing %q: %s", want, got)
+ }
+ }
+}
+
+func TestInstallPackWritesExpectedFiles(t *testing.T) {
+ dir := t.TempDir()
+ if err := InstallPack(dir, "/tmp/beacon/runtime.jsonl"); err != nil {
+ t.Fatalf("InstallPack returned error: %v", err)
+ }
+ for _, name := range []string{"README.md", "falcon-hec-smoke-test.sh", "sample-event.jsonl", "vector.toml"} {
+ if _, err := os.Stat(filepath.Join(dir, name)); err != nil {
+ t.Fatalf("expected %s: %v", name, err)
+ }
+ }
+ vectorConfig, err := os.ReadFile(filepath.Join(dir, "vector.toml"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(string(vectorConfig), "/tmp/beacon/runtime.jsonl") {
+ t.Fatalf("generated vector config missing configured log path: %s", vectorConfig)
+ }
+ info, err := os.Stat(filepath.Join(dir, "falcon-hec-smoke-test.sh"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ if info.Mode().Perm() != 0755 {
+ t.Fatalf("generated smoke-test script should be 0755, mode=%s", info.Mode().Perm())
+ }
+}
+
+func TestVectorConfigWrapsBeaconEventsForFalconHEC(t *testing.T) {
+ got := mustRead("pack/vector.toml.tmpl")
+ for _, want := range []string{
+ `include = ["{{LOG_PATH}}"]`,
+ `read_from = "${BEACON_VECTOR_READ_FROM:-end}"`,
+ `event = parse_json!(.message)`,
+ `event."@timestamp" = format_timestamp!(ts, format: "%+")`,
+ `"time": to_unix_timestamp(ts)`,
+ `"event": event`,
+ `"source": get_env_var("BEACON_FALCON_SOURCE") ?? "beacon-endpoint-agent"`,
+ `"sourcetype": get_env_var("BEACON_FALCON_SOURCETYPE") ?? "json"`,
+ `payload.index = index`,
+ `uri = "${BEACON_FALCON_HEC_ENDPOINT}"`,
+ `method = "newline_delimited"`,
+ `max_events = 500`,
+ `retry_max_duration_secs = 300`,
+ } {
+ if !strings.Contains(got, want) {
+ t.Fatalf("vector config missing %q: %s", want, got)
+ }
+ }
+}
+
+func TestSmokeTestAvoidsPrintingTokenAndUsesHECHeaders(t *testing.T) {
+ got, err := SmokeTest("/tmp/runtime.jsonl")
+ if err != nil {
+ t.Fatalf("SmokeTest returned error: %v", err)
+ }
+ for _, want := range []string{
+ `BEACON_FALCON_HEC_ENDPOINT is required`,
+ `BEACON_FALCON_HEC_TOKEN is required`,
+ `Authorization: Bearer $BEACON_FALCON_HEC_TOKEN`,
+ `Content-Type: text/plain; charset=utf-8`,
+ `Falcon HEC status:`,
+ `/tmp/runtime.jsonl`,
+ } {
+ if !strings.Contains(got, want) {
+ t.Fatalf("smoke test missing %q: %s", want, got)
+ }
+ }
+ if strings.Contains(got, "echo $BEACON_FALCON_HEC_TOKEN") {
+ t.Fatalf("smoke test should not print token: %s", got)
+ }
+}
+
+func TestSampleEventsCoverValidationHookAndOTelShapes(t *testing.T) {
+ scanner := bufio.NewScanner(strings.NewReader(mustRead("pack/sample-event.jsonl")))
+ var sawValidation, sawHook, sawOTel bool
+ for scanner.Scan() {
+ var doc map[string]interface{}
+ if err := json.Unmarshal(scanner.Bytes(), &doc); err != nil {
+ t.Fatalf("sample-event.jsonl is not valid JSONL: %v", err)
+ }
+ if destination, ok := doc["destination"].(map[string]interface{}); ok && destination["type"] == "falcon" {
+ sawValidation = true
+ }
+ if harness, ok := doc["harness"].(map[string]interface{}); ok && harness["name"] == "claude" {
+ sawHook = true
+ }
+ if raw, ok := doc["raw"].(map[string]interface{}); ok && raw["otel_signal"] != nil {
+ sawOTel = true
+ }
+ }
+ if err := scanner.Err(); err != nil {
+ t.Fatal(err)
+ }
+ if !sawValidation || !sawHook || !sawOTel {
+ t.Fatalf("sample events should include validation, hook, and OTel shapes; validation=%t hook=%t otel=%t", sawValidation, sawHook, sawOTel)
+ }
+}
+
+func TestPackREADMEMentionsCrowdStrikeSetupAndHookOnlyValidation(t *testing.T) {
+ readme := mustRead("pack/README.md")
+ for _, want := range []string{
+ "beacon endpoint falcon validate",
+ "CrowdStrike Falcon",
+ "BEACON_FALCON_HEC_ENDPOINT",
+ "BEACON_FALCON_HEC_TOKEN",
+ "/services/collector",
+ "/api/v1/ingest/hec",
+ "hook-only unique marker",
+ "source = \"beacon-endpoint-agent\"",
+ "vector.toml",
+ "runtime.jsonl",
+ "Content Handling",
+ } {
+ if !strings.Contains(readme, want) {
+ t.Fatalf("pack README missing %q", want)
+ }
+ }
+}
+
+func TestFiles_NoError(t *testing.T) {
+ files, err := Files()
+ if err != nil {
+ t.Fatalf("Files() returned unexpected error: %v", err)
+ }
+ if len(files) == 0 {
+ t.Fatal("Files() returned no files")
+ }
+}
+
+func TestFiles_ContainsAllRequiredNames(t *testing.T) {
+ files, err := Files()
+ if err != nil {
+ t.Fatal(err)
+ }
+ names := make(map[string]bool)
+ for _, f := range files {
+ names[f.Name] = true
+ }
+ for _, required := range []string{
+ "README.md", "falcon-hec-smoke-test.sh", "sample-event.jsonl", "vector.toml",
+ } {
+ if !names[required] {
+ t.Errorf("Files() missing required file %q", required)
+ }
+ }
+}
+
+func TestFilesFromFS_PropagatesReadError(t *testing.T) {
+ emptyFS := fstest.MapFS{}
+ _, err := filesFromFS(emptyFS)
+ if err == nil {
+ t.Fatal("filesFromFS with empty FS should return an error")
+ }
+ if !strings.Contains(err.Error(), "falcon pack asset") {
+ t.Fatalf("error should identify the pack source, got: %v", err)
+ }
+}
+
+func TestConfigSnippetFromFS_ErrorOnMissingAsset(t *testing.T) {
+ emptyFS := fstest.MapFS{}
+ _, err := configSnippetFromFS(emptyFS, "/some/path.jsonl")
+ if err == nil {
+ t.Fatal("configSnippetFromFS with empty FS should return error")
+ }
+ if !strings.Contains(err.Error(), "falcon pack asset") {
+ t.Fatalf("error should identify the pack source, got: %v", err)
+ }
+}
+
+func TestSmokeTestFromFS_ErrorOnMissingAsset(t *testing.T) {
+ emptyFS := fstest.MapFS{}
+ _, err := smokeTestFromFS(emptyFS, "/some/path.jsonl")
+ if err == nil {
+ t.Fatal("smokeTestFromFS with empty FS should return error")
+ }
+ if !strings.Contains(err.Error(), "falcon pack asset") {
+ t.Fatalf("error should identify the pack source, got: %v", err)
+ }
+}
+
+func TestInstallPack_ErrorOnWriteFailure(t *testing.T) {
+ if os.Getuid() == 0 {
+ t.Skip("running as root: filesystem permission restrictions do not apply")
+ }
+ dir := t.TempDir()
+ if err := os.Chmod(dir, 0555); err != nil {
+ t.Skip("cannot set directory permissions:", err)
+ }
+ defer os.Chmod(dir, 0755)
+
+ subdir := filepath.Join(dir, "output")
+ err := InstallPack(subdir, DefaultLogPath)
+ if err == nil {
+ t.Fatal("InstallPack into read-only directory should return error")
+ }
+}
+
+func TestConfigSnippet_DefaultLogPath(t *testing.T) {
+ got, err := ConfigSnippet("")
+ if err != nil {
+ t.Fatalf("ConfigSnippet with empty path returned error: %v", err)
+ }
+ if !strings.Contains(got, DefaultLogPath) {
+ t.Fatalf("ConfigSnippet with empty logPath should use DefaultLogPath %q, got: %s", DefaultLogPath, got)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/falcon/pack/README.md b/cli/beacon/internal/endpoint/falcon/pack/README.md
new file mode 100644
index 00000000..b3989121
--- /dev/null
+++ b/cli/beacon/internal/endpoint/falcon/pack/README.md
@@ -0,0 +1,138 @@
+# Beacon Endpoint Agent Falcon Pack
+
+This pack forwards Beacon endpoint JSONL events into CrowdStrike Falcon through
+an HTTP Event Collector compatible endpoint. Beacon still writes one local source
+of truth: `runtime.jsonl`. CrowdStrike endpoint URLs and tokens stay in Vector
+service environment, Jamf parameters, or secret tooling, not in Beacon endpoint
+configuration.
+
+## Prerequisites
+
+- Beacon endpoint installed and writing local JSONL.
+- A CrowdStrike Falcon HEC or Next-Gen SIEM connector endpoint.
+- The connector token stored securely as `BEACON_FALCON_HEC_TOKEN`.
+- Vector installed on the endpoint, or Beacon's managed macOS package with
+ `/opt/beacon/bin/vector`.
+
+CrowdStrike connector URL formats vary. Use the exact URL shown by the
+connector. Common examples are:
+
+```text
+https://<tenant>.ingest.<region>.crowdstrike.com/services/collector
+https://<tenant>.ingest.<region>.crowdstrike.com/api/v1/ingest/hec
+```
+
+## Install
+
+Generate this pack:
+
+```bash
+beacon endpoint falcon install-pack --output ./beacon-falcon-pack
+```
+
+The generated smoke-test script and `vector.toml` point at the Beacon log path
+selected by the CLI:
+
+- User mode: `~/.beacon/endpoint/logs/runtime.jsonl`
+- System mode: `/var/log/beacon-agent/runtime.jsonl`
+- Custom mode: the value passed with `--log-path`
+
+For MDM or managed endpoint deployment, prefer Beacon system mode so the
+forwarder can tail `/var/log/beacon-agent/runtime.jsonl` without per-user home
+directory ACLs. When Claude telemetry is hook-only, make sure the interactive
+user's hooks write to the system log path.
+
+## One-Shot Smoke Test
+
+Use the generated script to POST a synthetic Beacon-shaped HEC event. This tests
+the CrowdStrike URL and token without relying on Vector or Claude.
+
+```bash
+export BEACON_FALCON_HEC_ENDPOINT="https://..."
+export BEACON_FALCON_HEC_TOKEN="..."
+export BEACON_FALCON_SOURCE="beacon-endpoint-agent"
+export BEACON_FALCON_SOURCETYPE="json"
+./beacon-falcon-pack/falcon-hec-smoke-test.sh
+```
+
+The script does not print the token. A successful connector returns a 2xx HTTP
+status, often with a body similar to:
+
+```json
+{"text":"Success","code":0}
+```
+
+## Production Forwarding
+
+For production, run Vector as a managed host agent. Beacon remains the local
+JSONL producer; Vector tails `runtime.jsonl`, checkpoints file offsets in its
+`data_dir`, batches Beacon events, wraps them as HEC payloads, and POSTs them to
+CrowdStrike.
+
+Vector topologies follow Vector's source/transform/sink model:
+
+- `sources.beacon_runtime`: tails Beacon JSONL.
+- `transforms.beacon_json`: parses Beacon JSON and wraps it in HEC shape.
+- `sinks.falcon_hec`: sends newline-delimited JSON to CrowdStrike.
+
+Install Vector using your normal endpoint management tooling, then copy the
+generated config into Vector's config directory:
+
+```bash
+sudo mkdir -p /etc/vector
+sudo cp ./beacon-falcon-pack/vector.toml /etc/vector/beacon-falcon.toml
+export BEACON_FALCON_HEC_ENDPOINT="https://..."
+export BEACON_FALCON_HEC_TOKEN="..."
+vector validate /etc/vector/beacon-falcon.toml
+vector --config /etc/vector/beacon-falcon.toml
+```
+
+In Jamf deployments using the Beacon managed package, run the packaged Falcon
+Vector forwarder script instead of starting Vector manually. Provide the
+endpoint and token as Jamf parameters or environment variables.
+
+## Validate
+
+Write a fresh Beacon validation event:
+
+```bash
+beacon endpoint falcon validate
+```
+
+Wait for Vector to ship the new line. In Falcon Event Search, start with:
+
+```text
+source = "beacon-endpoint-agent" "Beacon endpoint Falcon validation event"
+```
+
+You can also confirm normalized Beacon fields are present:
+
+```text
+vendor = "beacon" product = "endpoint-agent"
+harness.name = "claude" OR harness.name = "claude_code"
+```
+
+For hook-only validation, generate a unique Claude prompt after the forwarder is
+running and search for that exact marker:
+
+```text
+source = "beacon-endpoint-agent" "hook-only unique marker"
+```
+
+## Troubleshooting
+
+- If local `runtime.jsonl` contains events but Falcon does not, check the Vector
+ service stderr log for HTTP status, TLS, or auth failures.
+- If `curl` to `/api/v1/ingest/hec` returns an empty reply but
+ `/services/collector` returns `403` without auth, the connector likely expects
+ `/services/collector`.
+- Successful Vector sends are usually quiet; absence of stderr errors after new
+ events can mean delivery is working.
+- Use `read_from = "beginning"` only for controlled diagnostics. Production
+ defaults to `end` to avoid re-uploading historical logs on first start.
+
+## Content Handling
+
+Beacon forwards retained prompt text, command output, raw tool inputs, raw OTLP
+attributes, and related local telemetry to CrowdStrike subject to Beacon's local
+redaction, sanitization, truncation, and event-size limits.
diff --git a/cli/beacon/internal/endpoint/falcon/pack/falcon-hec-smoke-test.sh.tmpl b/cli/beacon/internal/endpoint/falcon/pack/falcon-hec-smoke-test.sh.tmpl
new file mode 100644
index 00000000..3b489415
--- /dev/null
+++ b/cli/beacon/internal/endpoint/falcon/pack/falcon-hec-smoke-test.sh.tmpl
@@ -0,0 +1,46 @@
+#!/bin/sh
+set -eu
+
+BEACON_LOG="${BEACON_LOG:-{{LOG_PATH}}}"
+BEACON_FALCON_SOURCE="${BEACON_FALCON_SOURCE:-beacon-endpoint-agent}"
+BEACON_FALCON_SOURCETYPE="${BEACON_FALCON_SOURCETYPE:-json}"
+
+if [ -z "${BEACON_FALCON_HEC_ENDPOINT:-}" ]; then
+ echo "BEACON_FALCON_HEC_ENDPOINT is required" >&2
+ exit 1
+fi
+
+if [ -z "${BEACON_FALCON_HEC_TOKEN:-}" ]; then
+ echo "BEACON_FALCON_HEC_TOKEN is required" >&2
+ exit 1
+fi
+
+if [ ! -e "$BEACON_LOG" ]; then
+ echo "warning: Beacon runtime log does not exist yet: $BEACON_LOG" >&2
+fi
+
+payload="$(mktemp)"
+response="$(mktemp)"
+trap 'rm -f "$payload" "$response"' EXIT INT TERM
+
+now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+cat >"$payload" <<EOF
+{"time":$(date +%s),"event":{"timestamp":"$now","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"telemetry.enabled","category":"telemetry"},"severity":"info","destination":{"type":"falcon","mode":"crowdstrike_hec","status":"configured"},"message":"Beacon endpoint Falcon smoke-test event","@timestamp":"$now"},"source":"$BEACON_FALCON_SOURCE","sourcetype":"$BEACON_FALCON_SOURCETYPE"}
+EOF
+
+status="$(curl -sS -o "$response" -w '%{http_code}' \
+ -X POST "$BEACON_FALCON_HEC_ENDPOINT" \
+ -H "Authorization: Bearer $BEACON_FALCON_HEC_TOKEN" \
+ -H "Content-Type: text/plain; charset=utf-8" \
+ --data-binary @"$payload")"
+
+echo "Falcon HEC status: $status"
+sed -n '1,10p' "$response"
+
+case "$status" in
+ 2*) ;;
+ *)
+ echo "Falcon HEC smoke test failed" >&2
+ exit 1
+ ;;
+esac
diff --git a/cli/beacon/internal/endpoint/falcon/pack/sample-event.jsonl b/cli/beacon/internal/endpoint/falcon/pack/sample-event.jsonl
new file mode 100644
index 00000000..b67c43b1
--- /dev/null
+++ b/cli/beacon/internal/endpoint/falcon/pack/sample-event.jsonl
@@ -0,0 +1,3 @@
+{"timestamp":"2026-06-08T19:29:42Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"telemetry.enabled","category":"telemetry"},"severity":"info","endpoint":{"hostname":"host.local","os":"darwin","agent_version":"0.0.48"},"user":{"name":"alice"},"harness":{"name":"endpoint"},"destination":{"type":"falcon","mode":"crowdstrike_hec","status":"configured"},"message":"Beacon endpoint Falcon validation event"}
+{"timestamp":"2026-06-08T19:34:05Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"prompt.submitted","category":"prompt"},"severity":"info","endpoint":{"hostname":"host.local","os":"darwin"},"user":{"name":"alice"},"harness":{"name":"claude"},"session":{"id":"hook-only-demo","working_directory":"/Users/alice/project"},"prompt":{"text":"hook-only unique marker"},"content":{"retention":"full","included":true},"message":"Prompt submitted to agent"}
+{"timestamp":"2026-06-08T19:34:06Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"tool.invoked","category":"tool"},"severity":"info","endpoint":{"hostname":"host.local","os":"darwin"},"user":{"name":"alice"},"harness":{"name":"claude_code"},"session":{"id":"otel-demo"},"model":"claude-opus-4-6","message":"claude_code.api_request","raw":{"attributes":{"event.name":"api_request","service.name":"claude-code","service.version":"2.1.37","otel_signal":"logs"},"otel_signal":"logs","severity":""}}
diff --git a/cli/beacon/internal/endpoint/falcon/pack/vector.toml.tmpl b/cli/beacon/internal/endpoint/falcon/pack/vector.toml.tmpl
new file mode 100644
index 00000000..3911c742
--- /dev/null
+++ b/cli/beacon/internal/endpoint/falcon/pack/vector.toml.tmpl
@@ -0,0 +1,60 @@
+# Beacon Endpoint Agent -> CrowdStrike Falcon HEC
+#
+# Run Vector as a managed host agent. Keep the CrowdStrike endpoint and token in
+# the Vector service environment or MDM secret tooling, not in Beacon endpoint
+# configuration.
+
+data_dir = "/Library/Application Support/Beacon/Forwarders/vector-data/falcon"
+
+[sources.beacon_runtime]
+type = "file"
+include = ["{{LOG_PATH}}"]
+read_from = "${BEACON_VECTOR_READ_FROM:-end}"
+
+[transforms.beacon_json]
+type = "remap"
+inputs = ["beacon_runtime"]
+source = '''
+event = parse_json!(.message)
+ts = parse_timestamp(event.timestamp, format: "%+") ?? now()
+event."@timestamp" = format_timestamp!(ts, format: "%+")
+
+payload = {
+ "time": to_unix_timestamp(ts),
+ "event": event,
+ "source": get_env_var("BEACON_FALCON_SOURCE") ?? "beacon-endpoint-agent",
+ "sourcetype": get_env_var("BEACON_FALCON_SOURCETYPE") ?? "json",
+}
+
+index = get_env_var("BEACON_FALCON_INDEX") ?? ""
+if index != "" {
+ payload.index = index
+}
+
+. = payload
+'''
+
+[sinks.falcon_hec]
+type = "http"
+inputs = ["beacon_json"]
+uri = "${BEACON_FALCON_HEC_ENDPOINT}"
+method = "post"
+
+[sinks.falcon_hec.encoding]
+codec = "json"
+
+[sinks.falcon_hec.framing]
+method = "newline_delimited"
+
+[sinks.falcon_hec.batch]
+max_events = 500
+timeout_secs = 5
+
+[sinks.falcon_hec.request]
+retry_attempts = 10
+retry_initial_backoff_secs = 1
+retry_max_duration_secs = 300
+
+[sinks.falcon_hec.request.headers]
+Authorization = "Bearer ${BEACON_FALCON_HEC_TOKEN}"
+Content-Type = "text/plain; charset=utf-8"
diff --git a/packaging/macos/README.md b/packaging/macos/README.md
index f09ff568..1ba05aee 100644
--- a/packaging/macos/README.md
+++ b/packaging/macos/README.md
@@ -132,6 +132,25 @@ credential-provider settings through the Vector service environment, host
identity, MDM, or secret tooling. Keep AWS credentials, IAM roles, log group
retention, and encryption outside Beacon endpoint configuration.
+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
+config, a direct HEC smoke test, sample events, and validation search guidance:
+
+```bash
+/opt/beacon/bin/beacon endpoint falcon install-pack --system --output ./beacon-falcon-pack
+/opt/beacon/bin/beacon endpoint falcon validate --system
+```
+
+For Jamf-managed hook-only Claude deployments, the Beacon package can include a
+Vector binary at `/opt/beacon/bin/vector` and run
+`/opt/beacon/jamf/scripts/install-falcon-vector-forwarder.sh`. Provide the exact
+CrowdStrike connector URL shown by Falcon, for example
+`https://<tenant>.ingest.<region>.crowdstrike.com/services/collector` for
+Next-Gen SIEM HEC connectors or `/api/v1/ingest/hec` for LogScale-style HEC
+endpoints. The script stores the token in a root-owned forwarder environment
+file and starts `com.beacon.endpoint.falcon-forwarder`.
+
Environment variables take precedence, followed by MDM script parameters:
```text
@@ -321,6 +340,44 @@ Parameter 9: OTLP HTTP port, default 4318
Parameter 10: Falcon repository/index
```
+Use `/opt/beacon/jamf/scripts/install-falcon-vector-forwarder.sh` when a Jamf
+policy should install only the Vector runtime-log forwarder. This is the
+recommended path when Claude events are produced by user-level hooks and the
+customer's managed Claude OTLP settings bypass Beacon's local collector.
+
+`install-falcon-vector-forwarder.sh` Jamf script parameters:
+
+```text
+Parameter 4: Falcon HEC endpoint, exact connector URL
+Parameter 5: Falcon HEC token
+Parameter 6: Falcon source, default beacon-endpoint-agent
+Parameter 7: Falcon sourcetype, default json
+Parameter 8: Falcon repository/index
+Parameter 9: Runtime log paths, default /var/log/beacon-agent/runtime.jsonl,/Users/*/.beacon/endpoint/logs/runtime.jsonl
+Parameter 10: Vector read_from, default end
+```
+
+Use `/opt/beacon/jamf/scripts/repair-falcon-claude-hooks-vector.sh` when one
+policy should repair Beacon, prepare `/var/log/beacon-agent/runtime.jsonl`,
+install Claude hooks for the console user, and install the Falcon Vector
+forwarder without relying on collector-based Falcon forwarding.
+
+The managed forwarder writes:
+
+```text
+/Library/Application Support/Beacon/Forwarders/falcon-vector.toml
+/Library/Application Support/Beacon/Forwarders/falcon-vector.env
+/Library/Application Support/Beacon/Forwarders/vector-data/falcon
+/Library/LaunchDaemons/com.beacon.endpoint.falcon-forwarder.plist
+```
+
+Validate hook-only forwarding by generating a unique Claude prompt and searching
+Falcon for:
+
+```text
+source = "beacon-endpoint-agent" "hook-only unique marker"
+```
+
### Jamf Extension Attributes
Upload scripts from `packaging/macos/jamf/extension-attributes` to inventory:
@@ -331,6 +388,8 @@ Upload scripts from `packaging/macos/jamf/extension-attributes` to inventory:
- Configured harnesses
- Runtime log writability
- Splunk HEC forwarding state
+- Falcon Vector forwarder health
+- Falcon Vector forwarding configured state
Suggested Smart Groups:
diff --git a/packaging/macos/build-pkg.sh b/packaging/macos/build-pkg.sh
index b80e5fab..bab1dc44 100755
--- a/packaging/macos/build-pkg.sh
+++ b/packaging/macos/build-pkg.sh
@@ -13,6 +13,7 @@ PKG_NAME="${PKG_NAME:-BeaconEndpointAgent}"
BEACON_BIN="${BEACON_BIN:-$ROOT_DIR/cli/beacon/beacon}"
COLLECTOR_TARGET="${BEACON_COLLECTOR_TARGET:-$(go env GOOS)_$(go env GOARCH)}"
COLLECTOR_BIN="${BEACON_COLLECTOR:-$ROOT_DIR/collector-builder/dist/beacon-otelcol/$COLLECTOR_TARGET/beacon-otelcol}"
+VECTOR_BIN="${BEACON_VECTOR_BIN:-${VECTOR_BIN:-}}"
PKG_ROOT="$WORK_DIR/pkgroot"
PKG_SCRIPTS="$WORK_DIR/scripts"
PKG_PATH="$OUT_DIR/$PKG_NAME-$VERSION.pkg"
@@ -43,9 +44,18 @@ copy_file "$BEACON_BIN" "$PKG_ROOT/opt/beacon/bin/beacon"
copy_file "$COLLECTOR_BIN" "$PKG_ROOT/opt/beacon/bin/beacon-otelcol"
copy_file "$ROOT_DIR/packaging/macos/install-endpoint.sh" "$PKG_ROOT/opt/beacon/scripts/install-endpoint.sh"
copy_file "$ROOT_DIR/packaging/macos/uninstall-endpoint.sh" "$PKG_ROOT/opt/beacon/scripts/uninstall-endpoint.sh"
+copy_file "$ROOT_DIR/packaging/macos/run-falcon-forwarder.sh" "$PKG_ROOT/opt/beacon/scripts/run-falcon-forwarder.sh"
copy_file "$ROOT_DIR/packaging/macos/scripts/postinstall" "$PKG_SCRIPTS/postinstall"
copy_file "$ROOT_DIR/packaging/macos/scripts/preinstall" "$PKG_SCRIPTS/preinstall"
+if [ -n "$VECTOR_BIN" ]; then
+ if [ ! -x "$VECTOR_BIN" ]; then
+ echo "Vector binary not found or not executable: $VECTOR_BIN" >&2
+ exit 1
+ fi
+ copy_file "$VECTOR_BIN" "$PKG_ROOT/opt/beacon/bin/vector"
+fi
+
if command -v ditto >/dev/null 2>&1; then
ditto --norsrc --noextattr --noqtn "$ROOT_DIR/packaging/macos/jamf" "$PKG_ROOT/opt/beacon/jamf"
ditto --norsrc --noextattr --noqtn "$ROOT_DIR/packaging/macos/fleet" "$PKG_ROOT/opt/beacon/fleet"
@@ -66,13 +76,16 @@ fi
find "$PKG_ROOT" -name '._*' -delete
chmod 755 "$PKG_ROOT/opt/beacon/bin/beacon" "$PKG_ROOT/opt/beacon/bin/beacon-otelcol"
-chmod 755 "$PKG_ROOT/opt/beacon/scripts/install-endpoint.sh" "$PKG_ROOT/opt/beacon/scripts/uninstall-endpoint.sh"
+if [ -n "$VECTOR_BIN" ]; then
+ chmod 755 "$PKG_ROOT/opt/beacon/bin/vector"
+fi
+chmod 755 "$PKG_ROOT/opt/beacon/scripts/install-endpoint.sh" "$PKG_ROOT/opt/beacon/scripts/uninstall-endpoint.sh" "$PKG_ROOT/opt/beacon/scripts/run-falcon-forwarder.sh"
find "$PKG_ROOT/opt/beacon/jamf" -type f -name '*.sh' -exec chmod 755 {} \;
find "$PKG_ROOT/opt/beacon/fleet" -type f -name '*.sh' -exec chmod 755 {} \;
chmod 755 "$PKG_SCRIPTS/postinstall" "$PKG_SCRIPTS/preinstall"
find "$PKG_ROOT" -name '._*' -delete
if command -v xattr >/dev/null 2>&1; then
- xattr -cr "$PKG_ROOT" "$PKG_SCRIPTS" 2>/dev/null || true
+ find "$PKG_ROOT" "$PKG_SCRIPTS" -exec xattr -c {} \; 2>/dev/null || true
fi
if command -v dot_clean >/dev/null 2>&1; then
dot_clean -m "$PKG_ROOT" "$PKG_SCRIPTS" 2>/dev/null || true
diff --git a/packaging/macos/fleet/queries/falcon-vector-forwarder-health.sql b/packaging/macos/fleet/queries/falcon-vector-forwarder-health.sql
new file mode 100644
index 00000000..3dc86047
--- /dev/null
+++ b/packaging/macos/fleet/queries/falcon-vector-forwarder-health.sql
@@ -0,0 +1,8 @@
+SELECT
+ CASE
+ WHEN COUNT(*) = 0 THEN 'not_loaded'
+ WHEN SUM(CASE WHEN disabled = 0 THEN 1 ELSE 0 END) > 0 THEN 'loaded'
+ ELSE 'disabled'
+ END AS falcon_vector_forwarder_health
+FROM launchd
+WHERE name = 'com.beacon.endpoint.falcon-forwarder';
diff --git a/packaging/macos/jamf/extension-attributes/falcon-vector-forwarder-health.sh b/packaging/macos/jamf/extension-attributes/falcon-vector-forwarder-health.sh
new file mode 100755
index 00000000..c14f424a
--- /dev/null
+++ b/packaging/macos/jamf/extension-attributes/falcon-vector-forwarder-health.sh
@@ -0,0 +1,22 @@
+#!/bin/sh
+set -eu
+
+LABEL="${BEACON_FALCON_FORWARDER_LABEL:-com.beacon.endpoint.falcon-forwarder}"
+
+if ! command -v launchctl >/dev/null 2>&1; then
+ echo "<result>launchctl_unavailable</result>"
+ exit 0
+fi
+
+STATUS="$(launchctl print "system/$LABEL" 2>&1 || true)"
+case "$STATUS" in
+ *"state = running"*|*"pid ="*)
+ echo "<result>running</result>"
+ ;;
+ *"Could not find service"*|*"No such process"*)
+ echo "<result>not_loaded</result>"
+ ;;
+ *)
+ echo "<result>loaded_not_running</result>"
+ ;;
+esac
diff --git a/packaging/macos/jamf/extension-attributes/falcon-vector-forwarding-configured.sh b/packaging/macos/jamf/extension-attributes/falcon-vector-forwarding-configured.sh
new file mode 100755
index 00000000..ff3a2107
--- /dev/null
+++ b/packaging/macos/jamf/extension-attributes/falcon-vector-forwarding-configured.sh
@@ -0,0 +1,41 @@
+#!/bin/sh
+set -eu
+
+BASE_DIR="${BEACON_FORWARDER_BASE_DIR:-/Library/Application Support/Beacon/Forwarders}"
+LAUNCHDAEMONS_DIR="${BEACON_LAUNCHDAEMONS_DIR:-/Library/LaunchDaemons}"
+LABEL="${BEACON_FALCON_FORWARDER_LABEL:-com.beacon.endpoint.falcon-forwarder}"
+CONFIG_PATH="${BEACON_FALCON_VECTOR_CONFIG:-$BASE_DIR/falcon-vector.toml}"
+ENV_PATH="${BEACON_FALCON_VECTOR_ENV:-$BASE_DIR/falcon-vector.env}"
+PLIST_PATH="$LAUNCHDAEMONS_DIR/$LABEL.plist"
+
+if [ ! -f "$CONFIG_PATH" ]; then
+ echo "<result>missing_config</result>"
+ exit 0
+fi
+
+if [ ! -f "$ENV_PATH" ]; then
+ echo "<result>missing_env</result>"
+ exit 0
+fi
+
+if [ ! -f "$PLIST_PATH" ]; then
+ echo "<result>missing_plist</result>"
+ exit 0
+fi
+
+if ! grep -q '^export BEACON_FALCON_HEC_ENDPOINT=' "$ENV_PATH"; then
+ echo "<result>missing_endpoint</result>"
+ exit 0
+fi
+
+if ! grep -q '^export BEACON_FALCON_HEC_TOKEN=' "$ENV_PATH"; then
+ echo "<result>missing_token</result>"
+ exit 0
+fi
+
+if ! grep -q 'sinks.falcon_hec' "$CONFIG_PATH"; then
+ echo "<result>missing_sink</result>"
+ exit 0
+fi
+
+echo "<result>configured</result>"
diff --git a/packaging/macos/jamf/scripts/install-falcon-vector-forwarder.sh b/packaging/macos/jamf/scripts/install-falcon-vector-forwarder.sh
new file mode 100755
index 00000000..ba603516
--- /dev/null
+++ b/packaging/macos/jamf/scripts/install-falcon-vector-forwarder.sh
@@ -0,0 +1,206 @@
+#!/bin/sh
+set -eu
+
+LABEL="${BEACON_FALCON_FORWARDER_LABEL:-com.beacon.endpoint.falcon-forwarder}"
+VECTOR_BIN="${BEACON_VECTOR_BIN:-/opt/beacon/bin/vector}"
+WRAPPER="${BEACON_FALCON_FORWARDER_WRAPPER:-/opt/beacon/scripts/run-falcon-forwarder.sh}"
+BASE_DIR="${BEACON_FORWARDER_BASE_DIR:-/Library/Application Support/Beacon/Forwarders}"
+LAUNCHDAEMONS_DIR="${BEACON_LAUNCHDAEMONS_DIR:-/Library/LaunchDaemons}"
+CONFIG_PATH="${BEACON_FALCON_VECTOR_CONFIG:-$BASE_DIR/falcon-vector.toml}"
+ENV_PATH="${BEACON_FALCON_VECTOR_ENV:-$BASE_DIR/falcon-vector.env}"
+DATA_DIR="${BEACON_FALCON_VECTOR_DATA_DIR:-$BASE_DIR/vector-data/falcon}"
+PLIST_PATH="$LAUNCHDAEMONS_DIR/$LABEL.plist"
+
+FALCON_HEC_ENDPOINT="${BEACON_FALCON_HEC_ENDPOINT:-${4:-}}"
+FALCON_HEC_TOKEN="${BEACON_FALCON_HEC_TOKEN:-${5:-}}"
+FALCON_SOURCE="${BEACON_FALCON_SOURCE:-${6:-beacon-endpoint-agent}}"
+FALCON_SOURCETYPE="${BEACON_FALCON_SOURCETYPE:-${7:-json}}"
+FALCON_INDEX="${BEACON_FALCON_INDEX:-${8:-}}"
+RUNTIME_LOG_PATHS="${BEACON_RUNTIME_LOG_PATHS:-${9:-/var/log/beacon-agent/runtime.jsonl,/Users/*/.beacon/endpoint/logs/runtime.jsonl}}"
+VECTOR_READ_FROM="${BEACON_VECTOR_READ_FROM:-${10:-end}}"
+NO_START="${BEACON_NO_START:-0}"
+
+if [ -z "$FALCON_HEC_ENDPOINT" ]; then
+ echo "Falcon HEC endpoint is required (BEACON_FALCON_HEC_ENDPOINT or Jamf parameter 4)" >&2
+ exit 1
+fi
+
+if [ -z "$FALCON_HEC_TOKEN" ]; then
+ echo "Falcon HEC token is required (BEACON_FALCON_HEC_TOKEN or Jamf parameter 5)" >&2
+ exit 1
+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 "Falcon 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")"
+}
+
+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() {
+ old_ifs="$IFS"
+ IFS=,
+ first=1
+ printf '['
+ for raw in $RUNTIME_LOG_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"
+}
+
+mkdir -p "$BASE_DIR" "$DATA_DIR" "$LAUNCHDAEMONS_DIR"
+chmod 0755 "$BASE_DIR" "$DATA_DIR" "$LAUNCHDAEMONS_DIR" 2>/dev/null || true
+
+INCLUDES="$(include_array)"
+
+cat >"$CONFIG_PATH" <<EOF
+# Managed by Beacon. Do not edit by hand.
+data_dir = "$(printf '%s' "$DATA_DIR" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+
+[sources.beacon_runtime]
+type = "file"
+include = $INCLUDES
+read_from = "\${BEACON_VECTOR_READ_FROM:-end}"
+
+[transforms.beacon_json]
+type = "remap"
+inputs = ["beacon_runtime"]
+source = '''
+event = parse_json!(.message)
+ts = parse_timestamp(event.timestamp, format: "%+") ?? now()
+event."@timestamp" = format_timestamp!(ts, format: "%+")
+
+payload = {
+ "time": to_unix_timestamp(ts),
+ "event": event,
+ "source": get_env_var("BEACON_FALCON_SOURCE") ?? "beacon-endpoint-agent",
+ "sourcetype": get_env_var("BEACON_FALCON_SOURCETYPE") ?? "json",
+}
+
+index = get_env_var("BEACON_FALCON_INDEX") ?? ""
+if index != "" {
+ payload.index = index
+}
+
+. = payload
+'''
+
+[sinks.falcon_hec]
+type = "http"
+inputs = ["beacon_json"]
+uri = "\${BEACON_FALCON_HEC_ENDPOINT}"
+method = "post"
+
+[sinks.falcon_hec.encoding]
+codec = "json"
+
+[sinks.falcon_hec.framing]
+method = "newline_delimited"
+
+[sinks.falcon_hec.batch]
+max_events = 500
+timeout_secs = 5
+
+[sinks.falcon_hec.request]
+retry_attempts = 10
+retry_initial_backoff_secs = 1
+retry_max_duration_secs = 300
+
+[sinks.falcon_hec.request.headers]
+Authorization = "Bearer \${BEACON_FALCON_HEC_TOKEN}"
+Content-Type = "text/plain; charset=utf-8"
+EOF
+
+chmod 0644 "$CONFIG_PATH"
+
+{
+ printf 'export BEACON_FALCON_HEC_ENDPOINT=%s\n' "$(shell_quote "$FALCON_HEC_ENDPOINT")"
+ printf 'export BEACON_FALCON_HEC_TOKEN=%s\n' "$(shell_quote "$FALCON_HEC_TOKEN")"
+ printf 'export BEACON_FALCON_SOURCE=%s\n' "$(shell_quote "$FALCON_SOURCE")"
+ printf 'export BEACON_FALCON_SOURCETYPE=%s\n' "$(shell_quote "$FALCON_SOURCETYPE")"
+ printf 'export BEACON_FALCON_INDEX=%s\n' "$(shell_quote "$FALCON_INDEX")"
+ printf 'export BEACON_VECTOR_READ_FROM=%s\n' "$(shell_quote "$VECTOR_READ_FROM")"
+} >"$ENV_PATH"
+chmod 0600 "$ENV_PATH"
+
+cat >"$PLIST_PATH" <<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_PATH"
+
+echo "Falcon Vector config: $CONFIG_PATH"
+echo "Falcon Vector env: $ENV_PATH"
+echo "Falcon 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
+ launchctl bootout "system/$LABEL" >/dev/null 2>&1 || true
+ launchctl bootstrap system "$PLIST_PATH" >/dev/null 2>&1 || {
+ launchctl print "system/$LABEL" >/dev/null 2>&1 || exit 1
+ }
+ launchctl print "system/$LABEL" || true
+else
+ echo "launchctl unavailable; wrote config but did not start $LABEL" >&2
+fi
+
+if [ -f "/tmp/$LABEL.err" ]; then
+ echo "Last Falcon Vector stderr lines:"
+ tail -n 20 "/tmp/$LABEL.err" || true
+fi
diff --git a/packaging/macos/jamf/scripts/repair-falcon-claude-hooks-vector.sh b/packaging/macos/jamf/scripts/repair-falcon-claude-hooks-vector.sh
new file mode 100755
index 00000000..5010d6ef
--- /dev/null
+++ b/packaging/macos/jamf/scripts/repair-falcon-claude-hooks-vector.sh
@@ -0,0 +1,29 @@
+#!/bin/sh
+set -eu
+
+REPAIR_SCRIPT="${BEACON_REPAIR_HOOKS_SCRIPT:-/opt/beacon/jamf/scripts/repair-falcon-claude-hooks.sh}"
+FORWARDER_SCRIPT="${BEACON_FALCON_VECTOR_SCRIPT:-/opt/beacon/jamf/scripts/install-falcon-vector-forwarder.sh}"
+
+FALCON_HEC_ENDPOINT="${BEACON_FALCON_HEC_ENDPOINT:-${4:-}}"
+FALCON_HEC_TOKEN="${BEACON_FALCON_HEC_TOKEN:-${5:-}}"
+FALCON_SOURCE="${BEACON_FALCON_SOURCE:-${6:-beacon-endpoint-agent}}"
+FALCON_SOURCETYPE="${BEACON_FALCON_SOURCETYPE:-${7:-json}}"
+OTLP_GRPC_PORT="${BEACON_OTLP_GRPC_PORT:-${8:-4317}}"
+OTLP_HTTP_PORT="${BEACON_OTLP_HTTP_PORT:-${9:-4318}}"
+FALCON_INDEX="${BEACON_FALCON_INDEX:-${10:-}}"
+
+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 "Falcon Vector forwarder script not found or not executable at $FORWARDER_SCRIPT" >&2
+ exit 1
+fi
+
+echo "Repairing endpoint and Claude hooks without collector-based Falcon forwarding..."
+"$REPAIR_SCRIPT" _ _ _ "" "" "" "" "$OTLP_GRPC_PORT" "$OTLP_HTTP_PORT" ""
+
+echo "Installing Falcon Vector runtime-log forwarder..."
+"$FORWARDER_SCRIPT" _ _ _ "$FALCON_HEC_ENDPOINT" "$FALCON_HEC_TOKEN" "$FALCON_SOURCE" "$FALCON_SOURCETYPE" "$FALCON_INDEX"
diff --git a/packaging/macos/jamf/scripts/repair-falcon-claude-hooks.sh b/packaging/macos/jamf/scripts/repair-falcon-claude-hooks.sh
index b7a585bb..b97fd251 100755
--- a/packaging/macos/jamf/scripts/repair-falcon-claude-hooks.sh
+++ b/packaging/macos/jamf/scripts/repair-falcon-claude-hooks.sh
@@ -44,15 +44,17 @@ if [ -n "$FALCON_HEC_TOKEN" ]; then
ARGS+=(--falcon-hec-token "$FALCON_HEC_TOKEN")
fi
-ARGS+=(
- --falcon-source "$FALCON_SOURCE"
- --falcon-sourcetype "$FALCON_SOURCETYPE"
-)
-
if [ -n "$FALCON_INDEX" ]; then
ARGS+=(--falcon-index "$FALCON_INDEX")
fi
+if [ -n "$FALCON_HEC_ENDPOINT" ] || [ -n "$FALCON_HEC_TOKEN" ] || [ -n "$FALCON_INDEX" ]; then
+ ARGS+=(
+ --falcon-source "$FALCON_SOURCE"
+ --falcon-sourcetype "$FALCON_SOURCETYPE"
+ )
+fi
+
echo "Repairing Beacon system endpoint..."
"$BEACON_BIN" "${ARGS[@]}"
diff --git a/packaging/macos/run-falcon-forwarder.sh b/packaging/macos/run-falcon-forwarder.sh
new file mode 100755
index 00000000..3206d621
--- /dev/null
+++ b/packaging/macos/run-falcon-forwarder.sh
@@ -0,0 +1,23 @@
+#!/bin/sh
+set -eu
+
+VECTOR_BIN="${BEACON_VECTOR_BIN:-/opt/beacon/bin/vector}"
+CONFIG_PATH="${BEACON_FALCON_VECTOR_CONFIG:-/Library/Application Support/Beacon/Forwarders/falcon-vector.toml}"
+ENV_PATH="${BEACON_FALCON_VECTOR_ENV:-/Library/Application Support/Beacon/Forwarders/falcon-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
+
+exec "$VECTOR_BIN" --config "$CONFIG_PATH"
diff --git a/packaging/macos/scripts/postinstall b/packaging/macos/scripts/postinstall
index 8ceb129f..6e86c453 100755
--- a/packaging/macos/scripts/postinstall
+++ b/packaging/macos/scripts/postinstall
@@ -22,6 +22,12 @@ if command -v launchctl >/dev/null 2>&1; then
launchctl bootstrap system /Library/LaunchDaemons/com.beacon.endpoint.collector.plist >/dev/null 2>&1 || {
launchctl print system/com.beacon.endpoint.collector >/dev/null 2>&1 || exit 1
}
+ if [ -f /Library/LaunchDaemons/com.beacon.endpoint.falcon-forwarder.plist ]; then
+ launchctl bootout system/com.beacon.endpoint.falcon-forwarder >/dev/null 2>&1 || true
+ launchctl bootstrap system /Library/LaunchDaemons/com.beacon.endpoint.falcon-forwarder.plist >/dev/null 2>&1 || {
+ launchctl print system/com.beacon.endpoint.falcon-forwarder >/dev/null 2>&1 || exit 1
+ }
+ fi
fi
exit 0
diff --git a/packaging/macos/scripts/preinstall b/packaging/macos/scripts/preinstall
index 7e305d56..8a0e0994 100755
--- a/packaging/macos/scripts/preinstall
+++ b/packaging/macos/scripts/preinstall
@@ -5,6 +5,7 @@ set -eu
# can bind the local OTLP ports during postinstall.
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
fi
exit 0
diff --git a/packaging/macos/test-endpoint-scripts.sh b/packaging/macos/test-endpoint-scripts.sh
index c5500751..20f0055a 100644
--- a/packaging/macos/test-endpoint-scripts.sh
+++ b/packaging/macos/test-endpoint-scripts.sh
@@ -265,3 +265,66 @@ case "$UNINSTALL_ARGS" in
exit 1
;;
esac
+
+FAKE_VECTOR="$TMP_DIR/vector"
+cat >"$FAKE_VECTOR" <<'STUB'
+#!/bin/sh
+case "$1" in
+ --version)
+ echo "vector 0.56.0"
+ ;;
+ *)
+ echo "unexpected vector args: $*" >&2
+ exit 1
+ ;;
+esac
+STUB
+chmod +x "$FAKE_VECTOR"
+
+FORWARDER_BASE="$TMP_DIR/forwarders"
+LAUNCHDAEMONS_DIR="$TMP_DIR/launchdaemons"
+mkdir -p "$LAUNCHDAEMONS_DIR"
+BEACON_VECTOR_BIN="$FAKE_VECTOR" \
+BEACON_FALCON_FORWARDER_WRAPPER="$ROOT_DIR/packaging/macos/run-falcon-forwarder.sh" \
+BEACON_FORWARDER_BASE_DIR="$FORWARDER_BASE" \
+BEACON_LAUNCHDAEMONS_DIR="$LAUNCHDAEMONS_DIR" \
+BEACON_NO_START="1" \
+"$ROOT_DIR/packaging/macos/jamf/scripts/install-falcon-vector-forwarder.sh" _ _ _ "https://falcon.example/services/collector" "falcon-token" "beacon-source" "json" "beacon-index" "$TMP_DIR/runtime.jsonl,/Users/*/.beacon/endpoint/logs/runtime.jsonl" "end" >/dev/null
+
+if [ ! -f "$FORWARDER_BASE/falcon-vector.toml" ]; then
+ echo "Falcon Vector config was not written" >&2
+ exit 1
+fi
+if [ ! -f "$FORWARDER_BASE/falcon-vector.env" ]; then
+ echo "Falcon Vector env was not written" >&2
+ exit 1
+fi
+if [ ! -f "$LAUNCHDAEMONS_DIR/com.beacon.endpoint.falcon-forwarder.plist" ]; then
+ echo "Falcon Vector plist was not written" >&2
+ exit 1
+fi
+if ! grep -q 'https://falcon.example/services/collector' "$FORWARDER_BASE/falcon-vector.env"; then
+ echo "Falcon Vector env missing endpoint" >&2
+ exit 1
+fi
+if grep -q 'falcon-token' "$FORWARDER_BASE/falcon-vector.toml"; then
+ echo "Falcon Vector config should not contain token" >&2
+ exit 1
+fi
+if ! grep -q 'sinks.falcon_hec' "$FORWARDER_BASE/falcon-vector.toml"; then
+ echo "Falcon Vector config missing sink" >&2
+ exit 1
+fi
+if ! grep -q 'RunAtLoad' "$LAUNCHDAEMONS_DIR/com.beacon.endpoint.falcon-forwarder.plist"; then
+ echo "Falcon Vector plist missing RunAtLoad" >&2
+ exit 1
+fi
+
+FALCON_VECTOR_STATE="$(BEACON_FORWARDER_BASE_DIR="$FORWARDER_BASE" BEACON_LAUNCHDAEMONS_DIR="$LAUNCHDAEMONS_DIR" "$ROOT_DIR/packaging/macos/jamf/extension-attributes/falcon-vector-forwarding-configured.sh")"
+case "$FALCON_VECTOR_STATE" in
+ "<result>configured</result>") ;;
+ *)
+ echo "unexpected Falcon Vector configured extension attribute result: $FALCON_VECTOR_STATE" >&2
+ exit 1
+ ;;
+esac