Skip to content

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

add falcon hec support

Justin D'Souzabdc021c0692b
diff --git a/README.md b/README.md
index 1bc21e06..c7e87a52 100644
--- a/README.md
+++ b/README.md
@@ -101,6 +101,7 @@ enterprise-grade SIEMs.
| [Sumo Logic](https://docs.asymptotelabs.ai/cli/siem-forwarding-sumo) | HTTP Logs & Metrics Source content pack over local JSONL |
| [Rapid7 InsightIDR](https://docs.asymptotelabs.ai/cli/siem-forwarding-rapid7) | Custom Logs webhook content pack over local JSONL |
| [Splunk HEC](https://docs.asymptotelabs.ai/cli/siem-forwarding-splunk) | Optional endpoint forwarding during install or repair |
+| CrowdStrike Falcon LogScale HEC | Optional endpoint forwarding with LogScale ingest tokens during install or repair |
| [Customer-managed SIEM pipelines](https://docs.asymptotelabs.ai/cli/siem-forwarding) | Forwarding from local Beacon JSONL under customer control |
### MDM Deployment
diff --git a/cli/beacon/README.md b/cli/beacon/README.md
index ca3ee8ce..f98f2420 100644
--- a/cli/beacon/README.md
+++ b/cli/beacon/README.md
@@ -35,6 +35,23 @@ Add optional Splunk HEC forwarding during install or repair:
The local JSONL runtime log remains enabled when Splunk forwarding is
configured.
+Add optional Falcon LogScale HEC forwarding during install or repair:
+
+```bash
+./beacon endpoint repair \
+ --falcon-hec-endpoint "$LOGSCALE_URL/api/v1/ingest/hec" \
+ --falcon-hec-token "$LOGSCALE_INGEST_TOKEN" \
+ --falcon-source beacon-endpoint-agent \
+ --falcon-sourcetype json
+```
+
+Beacon sends LogScale HEC requests with `Authorization: Bearer <ingest token>`.
+The HEC `event` value is the normalized Beacon event object with an ISO
+`@timestamp` nested inside it for LogScale's built-in JSON parser. The optional
+`--falcon-index` flag maps to a LogScale repository and is usually only needed
+with organization or system multi-repository ingest tokens; repository-scoped
+ingest tokens already select the target repository.
+
## Dashboard
```bash
diff --git a/cli/beacon/cmd/endpoint.go b/cli/beacon/cmd/endpoint.go
index aa9316e2..435950b2 100644
--- a/cli/beacon/cmd/endpoint.go
+++ b/cli/beacon/cmd/endpoint.go
@@ -66,6 +66,13 @@ var endpointOpts struct {
splunkSourcetype string
splunkInsecureSkipVerify bool
splunkCAFile string
+ falconHECEndpoint string
+ falconHECToken string
+ falconIndex string
+ falconSource string
+ falconSourcetype string
+ falconInsecureSkipVerify bool
+ falconCAFile string
dashboardAddr string
dashboardOpen bool
includeEventSummaries bool
@@ -576,6 +583,7 @@ func init() {
endpointInstallCmd.Flags().BoolVar(&endpointOpts.dryRun, "dry-run", false, "Print planned actions without changing endpoint files or services")
endpointInstallCmd.Flags().StringVar(&endpointOpts.contentRetention, "content-retention", "full", "Content retention mode: metadata, redacted, or full")
registerSplunkFlags(endpointInstallCmd)
+ registerFalconFlags(endpointInstallCmd)
endpointRepairCmd.Flags().StringVar(&endpointOpts.harnesses, "harness", "claude,codex", "Comma-separated harnesses to configure")
endpointRepairCmd.Flags().IntVar(&endpointOpts.grpcPort, "otlp-grpc-port", endpointconfig.DefaultGRPCPort, "Local OTLP gRPC port")
endpointRepairCmd.Flags().IntVar(&endpointOpts.httpPort, "otlp-http-port", endpointconfig.DefaultHTTPPort, "Local OTLP HTTP port")
@@ -586,6 +594,7 @@ func init() {
endpointRepairCmd.Flags().BoolVar(&endpointOpts.dryRun, "dry-run", false, "Print planned actions without changing endpoint files or services")
endpointRepairCmd.Flags().StringVar(&endpointOpts.contentRetention, "content-retention", "full", "Content retention mode: metadata, redacted, or full")
registerSplunkFlags(endpointRepairCmd)
+ registerFalconFlags(endpointRepairCmd)
endpointDashboardCmd.Flags().BoolVar(&endpointOpts.userMode, "user", true, "Use per-user endpoint paths")
endpointDashboardCmd.Flags().BoolVar(&endpointOpts.systemMode, "system", false, "Use system endpoint paths and launch daemon")
endpointDashboardCmd.Flags().StringVar(&endpointOpts.logPath, "log-path", "", "Runtime JSONL log path")
@@ -1193,6 +1202,7 @@ func runEndpointInstall(cmd *cobra.Command, args []string) error {
IncludeRuntimeMetrics: endpointOpts.includeRuntimeMetrics,
IncludeCodexSpans: endpointOpts.includeCodexSpans,
SplunkHEC: splunkHECOptions(),
+ FalconHEC: falconHECOptions(),
})
if err != nil {
return err
@@ -1325,6 +1335,7 @@ func runEndpointRepair(cmd *cobra.Command, args []string) error {
IncludeRuntimeMetrics: endpointOpts.includeRuntimeMetrics,
IncludeCodexSpans: endpointOpts.includeCodexSpans,
SplunkHEC: splunkHECOptions(),
+ FalconHEC: falconHECOptions(),
})
if err != nil {
return err
@@ -1387,6 +1398,16 @@ func registerSplunkFlags(cmd *cobra.Command) {
cmd.Flags().StringVar(&endpointOpts.splunkCAFile, "splunk-ca-file", "", "Optional CA certificate path for Splunk HEC TLS verification")
}
+func registerFalconFlags(cmd *cobra.Command) {
+ cmd.Flags().StringVar(&endpointOpts.falconHECEndpoint, "falcon-hec-endpoint", "", "Falcon LogScale HEC endpoint URL")
+ cmd.Flags().StringVar(&endpointOpts.falconHECToken, "falcon-hec-token", "", "Falcon LogScale ingest token")
+ cmd.Flags().StringVar(&endpointOpts.falconIndex, "falcon-index", "", "Optional Falcon LogScale repository for multi-repository tokens")
+ cmd.Flags().StringVar(&endpointOpts.falconSource, "falcon-source", endpointconfig.DefaultFalconSource, "Optional Falcon LogScale source")
+ cmd.Flags().StringVar(&endpointOpts.falconSourcetype, "falcon-sourcetype", endpointconfig.DefaultFalconSourcetype, "Optional Falcon LogScale parser or sourcetype")
+ cmd.Flags().BoolVar(&endpointOpts.falconInsecureSkipVerify, "falcon-insecure-skip-verify", false, "Skip Falcon LogScale HEC TLS certificate verification")
+ cmd.Flags().StringVar(&endpointOpts.falconCAFile, "falcon-ca-file", "", "Optional CA certificate path for Falcon LogScale HEC TLS verification")
+}
+
func splunkHECOptions() *endpointconfig.SplunkHEC {
if endpointOpts.splunkHECEndpoint == "" &&
endpointOpts.splunkHECToken == "" &&
@@ -1407,3 +1428,24 @@ func splunkHECOptions() *endpointconfig.SplunkHEC {
CAFile: endpointOpts.splunkCAFile,
}
}
+
+func falconHECOptions() *endpointconfig.FalconHEC {
+ if endpointOpts.falconHECEndpoint == "" &&
+ endpointOpts.falconHECToken == "" &&
+ endpointOpts.falconIndex == "" &&
+ endpointOpts.falconSource == endpointconfig.DefaultFalconSource &&
+ endpointOpts.falconSourcetype == endpointconfig.DefaultFalconSourcetype &&
+ !endpointOpts.falconInsecureSkipVerify &&
+ endpointOpts.falconCAFile == "" {
+ return nil
+ }
+ return &endpointconfig.FalconHEC{
+ Endpoint: endpointOpts.falconHECEndpoint,
+ Token: endpointOpts.falconHECToken,
+ Index: endpointOpts.falconIndex,
+ Source: endpointOpts.falconSource,
+ Sourcetype: endpointOpts.falconSourcetype,
+ InsecureSkipVerify: endpointOpts.falconInsecureSkipVerify,
+ CAFile: endpointOpts.falconCAFile,
+ }
+}
diff --git a/cli/beacon/cmd/endpoint_diagnostics.go b/cli/beacon/cmd/endpoint_diagnostics.go
index 33bec8ea..e3437b4e 100644
--- a/cli/beacon/cmd/endpoint_diagnostics.go
+++ b/cli/beacon/cmd/endpoint_diagnostics.go
@@ -480,11 +480,24 @@ func redactLastEvent(raw string) string {
}
func redactConfig(cfg endpointconfig.Config) endpointconfig.Config {
- if cfg.Destinations != nil && cfg.Destinations.SplunkHEC != nil && cfg.Destinations.SplunkHEC.Token != "" {
- destinations := *cfg.Destinations
+ if cfg.Destinations == nil {
+ return cfg
+ }
+ destinations := *cfg.Destinations
+ changed := false
+ if cfg.Destinations.SplunkHEC != nil && cfg.Destinations.SplunkHEC.Token != "" {
splunk := *cfg.Destinations.SplunkHEC
splunk.Token = "[REDACTED]"
destinations.SplunkHEC = &splunk
+ changed = true
+ }
+ if cfg.Destinations.FalconHEC != nil && cfg.Destinations.FalconHEC.Token != "" {
+ falcon := *cfg.Destinations.FalconHEC
+ falcon.Token = "[REDACTED]"
+ destinations.FalconHEC = &falcon
+ changed = true
+ }
+ if changed {
cfg.Destinations = &destinations
}
return cfg
diff --git a/cli/beacon/cmd/endpoint_test.go b/cli/beacon/cmd/endpoint_test.go
index a36a5287..24082df7 100644
--- a/cli/beacon/cmd/endpoint_test.go
+++ b/cli/beacon/cmd/endpoint_test.go
@@ -44,6 +44,34 @@ func TestEndpointDashboardCommandRegistered(t *testing.T) {
}
}
+func TestEndpointInstallAndRepairRegisterFalconFlags(t *testing.T) {
+ for _, cmd := range []*cobra.Command{endpointInstallCmd, endpointRepairCmd} {
+ for _, name := range []string{
+ "falcon-hec-endpoint",
+ "falcon-hec-token",
+ "falcon-index",
+ "falcon-source",
+ "falcon-sourcetype",
+ "falcon-insecure-skip-verify",
+ "falcon-ca-file",
+ } {
+ if cmd.Flags().Lookup(name) == nil {
+ t.Fatalf("%s missing --%s flag", cmd.Use, name)
+ }
+ }
+ }
+}
+
+func TestFalconHECOptionsDefaultIsNil(t *testing.T) {
+ old := endpointOpts
+ t.Cleanup(func() { endpointOpts = old })
+ endpointOpts.falconSource = endpointconfig.DefaultFalconSource
+ endpointOpts.falconSourcetype = endpointconfig.DefaultFalconSourcetype
+ if got := falconHECOptions(); got != nil {
+ t.Fatalf("falconHECOptions() = %#v, want nil", got)
+ }
+}
+
func TestEndpointCoworkSetupCommandRegistered(t *testing.T) {
cmd, _, err := endpointCmd.Find([]string{"integrations", "claude-cowork", "setup"})
if err != nil {
@@ -407,6 +435,21 @@ func TestRedactConfigScrubsSplunkToken(t *testing.T) {
}
}
+func TestRedactConfigScrubsFalconToken(t *testing.T) {
+ cfg := endpointconfig.Default(true, "/tmp/runtime.jsonl")
+ cfg.Destinations = &endpointconfig.Destinations{FalconHEC: &endpointconfig.FalconHEC{
+ Endpoint: "https://cloud.us.humio.com/api/v1/ingest/hec",
+ Token: "secret-token",
+ }}
+ redacted := redactConfig(cfg)
+ if redacted.Destinations.FalconHEC.Token != "[REDACTED]" {
+ t.Fatalf("token was not redacted: %#v", redacted.Destinations.FalconHEC)
+ }
+ if cfg.Destinations.FalconHEC.Token != "secret-token" {
+ t.Fatal("redactConfig mutated input config")
+ }
+}
+
func TestAggregateCheckStatus(t *testing.T) {
if got := aggregateCheckStatus([]diagnostics.Check{{Status: "ok"}}); got != "ok" {
t.Fatalf("ok aggregate = %q", got)
diff --git a/cli/beacon/internal/endpoint/collector/collector.go b/cli/beacon/internal/endpoint/collector/collector.go
index cd56c77e..23a70163 100644
--- a/cli/beacon/internal/endpoint/collector/collector.go
+++ b/cli/beacon/internal/endpoint/collector/collector.go
@@ -110,11 +110,16 @@ func WriteConfig(cfg endpointconfig.Config) error {
func ConfigYAML(cfg endpointconfig.Config) string {
endpointconfig.NormalizeDestinations(&cfg)
- exporters := "[beaconjson]"
+ exporterNames := []string{"beaconjson"}
splunkExporter := splunkHECYAML(cfg)
if splunkExporter != "" {
- exporters = "[beaconjson, splunk_hec]"
+ exporterNames = append(exporterNames, "splunk_hec")
}
+ falconExporter := falconHECYAML(cfg)
+ if falconExporter != "" {
+ exporterNames = append(exporterNames, "falcon_hec")
+ }
+ exporters := "[" + strings.Join(exporterNames, ", ") + "]"
runtimeMetricsYAML := ""
if cfg.Collector.IncludeRuntimeMetrics {
runtimeMetricsYAML = " include_runtime_metrics: true\n"
@@ -170,7 +175,7 @@ service:
receivers: [otlp]
processors: [memory_limiter, batch]
exporters: %s
-`, cfg.Collector.GRPCPort, cfg.Collector.HTTPPort, cfg.LogPath, cfg.ContentRetention, runtimeMetricsYAML+codexSpansYAML+splunkExporter, exporters, exporters, exporters)
+`, cfg.Collector.GRPCPort, cfg.Collector.HTTPPort, cfg.LogPath, cfg.ContentRetention, runtimeMetricsYAML+codexSpansYAML+splunkExporter+falconExporter, exporters, exporters, exporters)
}
func splunkHECYAML(cfg endpointconfig.Config) string {
@@ -203,6 +208,40 @@ func splunkHECYAML(cfg endpointconfig.Config) string {
return b.String()
}
+func falconHECYAML(cfg endpointconfig.Config) string {
+ if cfg.Destinations == nil || cfg.Destinations.FalconHEC == nil || !cfg.Destinations.FalconHEC.Enabled {
+ return ""
+ }
+ falcon := cfg.Destinations.FalconHEC
+ var b strings.Builder
+ fmt.Fprintf(&b, " falcon_hec:\n")
+ fmt.Fprintf(&b, " token: %q\n", falcon.Token)
+ fmt.Fprintf(&b, " endpoint: %q\n", falcon.Endpoint)
+ fmt.Fprintf(&b, " content_retention: %q\n", cfg.ContentRetention)
+ if cfg.Collector.IncludeRuntimeMetrics {
+ fmt.Fprintf(&b, " include_runtime_metrics: true\n")
+ }
+ if cfg.Collector.IncludeCodexSpans {
+ fmt.Fprintf(&b, " include_codex_spans: true\n")
+ }
+ if falcon.Source != "" {
+ fmt.Fprintf(&b, " source: %q\n", falcon.Source)
+ }
+ if falcon.Sourcetype != "" {
+ fmt.Fprintf(&b, " sourcetype: %q\n", falcon.Sourcetype)
+ }
+ if falcon.Index != "" {
+ fmt.Fprintf(&b, " index: %q\n", falcon.Index)
+ }
+ if falcon.InsecureSkipVerify {
+ fmt.Fprintf(&b, " insecure_skip_verify: true\n")
+ }
+ if falcon.CAFile != "" {
+ fmt.Fprintf(&b, " ca_file: %q\n", falcon.CAFile)
+ }
+ return b.String()
+}
+
func CheckStatus(cfg endpointconfig.Config) Status {
binary := DiscoverBinary(cfg.Collector.BinaryPath)
status := Status{
diff --git a/cli/beacon/internal/endpoint/collector/collector_test.go b/cli/beacon/internal/endpoint/collector/collector_test.go
index 7f6cc330..fbeef2ec 100644
--- a/cli/beacon/internal/endpoint/collector/collector_test.go
+++ b/cli/beacon/internal/endpoint/collector/collector_test.go
@@ -110,6 +110,62 @@ func TestConfigYAMLIncludesSplunkHECWhenConfigured(t *testing.T) {
}
}
+func TestConfigYAMLIncludesFalconHECWhenConfigured(t *testing.T) {
+ cfg := testConfig(t)
+ cfg.ContentRetention = endpointconfig.ContentRetentionRedacted
+ cfg.Collector.IncludeRuntimeMetrics = true
+ cfg.Collector.IncludeCodexSpans = true
+ cfg.Destinations = &endpointconfig.Destinations{FalconHEC: &endpointconfig.FalconHEC{
+ Endpoint: "https://cloud.us.humio.com/api/v1/ingest/hec",
+ Token: "ingest-token",
+ Index: "beacon-repo",
+ Source: "beacon-endpoint-agent",
+ Sourcetype: "json",
+ InsecureSkipVerify: true,
+ CAFile: "/tmp/logscale-ca.pem",
+ }}
+
+ yaml := ConfigYAML(cfg)
+
+ for _, want := range []string{
+ "falcon_hec:",
+ `token: "ingest-token"`,
+ `endpoint: "https://cloud.us.humio.com/api/v1/ingest/hec"`,
+ `content_retention: "redacted"`,
+ "include_runtime_metrics: true",
+ "include_codex_spans: true",
+ `index: "beacon-repo"`,
+ `source: "beacon-endpoint-agent"`,
+ `sourcetype: "json"`,
+ "insecure_skip_verify: true",
+ `ca_file: "/tmp/logscale-ca.pem"`,
+ "exporters: [beaconjson, falcon_hec]",
+ } {
+ if !strings.Contains(yaml, want) {
+ t.Fatalf("ConfigYAML missing %q:\n%s", want, yaml)
+ }
+ }
+}
+
+func TestConfigYAMLIncludesSplunkAndFalconHECWhenConfigured(t *testing.T) {
+ cfg := testConfig(t)
+ cfg.Destinations = &endpointconfig.Destinations{
+ SplunkHEC: &endpointconfig.SplunkHEC{
+ Endpoint: "https://splunk.example:8088/services/collector",
+ Token: "hec-token",
+ },
+ FalconHEC: &endpointconfig.FalconHEC{
+ Endpoint: "https://cloud.us.humio.com/api/v1/ingest/hec",
+ Token: "ingest-token",
+ },
+ }
+
+ yaml := ConfigYAML(cfg)
+ if !strings.Contains(yaml, "exporters: [beaconjson, splunk_hec, falcon_hec]") {
+ t.Fatalf("ConfigYAML missing combined exporters:\n%s", yaml)
+ }
+}
+
func TestWriteConfigCreatesConfigAndSpoolDirectory(t *testing.T) {
cfg := testConfig(t)
@@ -143,6 +199,25 @@ func TestWriteConfigUsesPrivatePermissionsWithSplunkToken(t *testing.T) {
}
}
+func TestWriteConfigUsesPrivatePermissionsWithFalconToken(t *testing.T) {
+ cfg := testConfig(t)
+ cfg.Destinations = &endpointconfig.Destinations{FalconHEC: &endpointconfig.FalconHEC{
+ Endpoint: "https://cloud.us.humio.com/api/v1/ingest/hec",
+ Token: "ingest-token",
+ }}
+
+ if err := WriteConfig(cfg); err != nil {
+ t.Fatalf("WriteConfig returned error: %v", err)
+ }
+ info, err := os.Stat(cfg.Collector.ConfigPath)
+ if err != nil {
+ t.Fatalf("stat collector config: %v", err)
+ }
+ if got, want := info.Mode().Perm(), os.FileMode(0600); got != want {
+ t.Fatalf("collector config permissions = %o, want %o", got, want)
+ }
+}
+
func TestDiscoverBinaryPrefersConfiguredExistingPath(t *testing.T) {
bin := filepath.Join(t.TempDir(), BinaryName)
if err := os.WriteFile(bin, []byte("#!/bin/sh\n"), 0755); err != nil {
diff --git a/cli/beacon/internal/endpoint/config/config.go b/cli/beacon/internal/endpoint/config/config.go
index 8127e837..c1cdc844 100644
--- a/cli/beacon/internal/endpoint/config/config.go
+++ b/cli/beacon/internal/endpoint/config/config.go
@@ -17,6 +17,8 @@ const (
const (
DefaultSplunkSource = "beacon-endpoint-agent"
DefaultSplunkSourcetype = "beacon:endpoint"
+ DefaultFalconSource = "beacon-endpoint-agent"
+ DefaultFalconSourcetype = "json"
)
type ContentRetention string
@@ -49,6 +51,7 @@ type Collector struct {
type Destinations struct {
SplunkHEC *SplunkHEC `json:"splunk_hec,omitempty"`
+ FalconHEC *FalconHEC `json:"falcon_hec,omitempty"`
}
type SplunkHEC struct {
@@ -62,6 +65,17 @@ type SplunkHEC struct {
CAFile string `json:"ca_file,omitempty"`
}
+type FalconHEC struct {
+ Enabled bool `json:"enabled,omitempty"`
+ Endpoint string `json:"endpoint,omitempty"`
+ Token string `json:"token,omitempty"`
+ Index string `json:"index,omitempty"`
+ Source string `json:"source,omitempty"`
+ Sourcetype string `json:"sourcetype,omitempty"`
+ InsecureSkipVerify bool `json:"insecure_skip_verify,omitempty"`
+ CAFile string `json:"ca_file,omitempty"`
+}
+
func Default(userMode bool, logPath string) Config {
base := BaseDir(userMode)
return Config{
@@ -165,51 +179,84 @@ func ValidateContentRetention(mode ContentRetention) error {
}
func NormalizeDestinations(cfg *Config) {
- if cfg == nil || cfg.Destinations == nil || cfg.Destinations.SplunkHEC == nil {
+ if cfg == nil || cfg.Destinations == nil {
return
}
- splunk := cfg.Destinations.SplunkHEC
- if splunk.Endpoint != "" || splunk.Token != "" {
- splunk.Enabled = true
- }
- if !splunk.Enabled {
- return
- }
- if splunk.Source == "" {
- splunk.Source = DefaultSplunkSource
+ if splunk := cfg.Destinations.SplunkHEC; splunk != nil {
+ if splunk.Endpoint != "" || splunk.Token != "" {
+ splunk.Enabled = true
+ }
+ if splunk.Enabled {
+ if splunk.Source == "" {
+ splunk.Source = DefaultSplunkSource
+ }
+ if splunk.Sourcetype == "" {
+ splunk.Sourcetype = DefaultSplunkSourcetype
+ }
+ }
}
- if splunk.Sourcetype == "" {
- splunk.Sourcetype = DefaultSplunkSourcetype
+ if falcon := cfg.Destinations.FalconHEC; falcon != nil {
+ if falcon.Endpoint != "" || falcon.Token != "" {
+ falcon.Enabled = true
+ }
+ if falcon.Enabled {
+ if falcon.Source == "" {
+ falcon.Source = DefaultFalconSource
+ }
+ if falcon.Sourcetype == "" {
+ falcon.Sourcetype = DefaultFalconSourcetype
+ }
+ }
}
}
func ValidateDestinations(destinations *Destinations) error {
- if destinations == nil || destinations.SplunkHEC == nil {
- return nil
- }
- splunk := destinations.SplunkHEC
- configured := splunk.Enabled ||
- splunk.Endpoint != "" ||
- splunk.Token != "" ||
- splunk.Index != "" ||
- splunk.Source != "" ||
- splunk.Sourcetype != "" ||
- splunk.InsecureSkipVerify ||
- splunk.CAFile != ""
- if !configured {
+ if destinations == nil {
return nil
}
- if splunk.Endpoint == "" {
- return fmt.Errorf("splunk HEC endpoint is required when Splunk forwarding is configured")
+ if destinations.SplunkHEC != nil {
+ splunk := destinations.SplunkHEC
+ configured := splunk.Enabled ||
+ splunk.Endpoint != "" ||
+ splunk.Token != "" ||
+ splunk.Index != "" ||
+ splunk.Source != "" ||
+ splunk.Sourcetype != "" ||
+ splunk.InsecureSkipVerify ||
+ splunk.CAFile != ""
+ if configured {
+ if splunk.Endpoint == "" {
+ return fmt.Errorf("splunk HEC endpoint is required when Splunk forwarding is configured")
+ }
+ if splunk.Token == "" {
+ return fmt.Errorf("splunk HEC token is required when Splunk forwarding is configured")
+ }
+ }
}
- if splunk.Token == "" {
- return fmt.Errorf("splunk HEC token is required when Splunk forwarding is configured")
+ if destinations.FalconHEC != nil {
+ falcon := destinations.FalconHEC
+ configured := falcon.Enabled ||
+ falcon.Endpoint != "" ||
+ falcon.Token != "" ||
+ falcon.Index != "" ||
+ falcon.Source != "" ||
+ falcon.Sourcetype != "" ||
+ falcon.InsecureSkipVerify ||
+ falcon.CAFile != ""
+ if configured {
+ if falcon.Endpoint == "" {
+ return fmt.Errorf("falcon HEC endpoint is required when Falcon forwarding is configured")
+ }
+ if falcon.Token == "" {
+ return fmt.Errorf("falcon HEC token is required when Falcon forwarding is configured")
+ }
+ }
}
return nil
}
func HasSecretDestinations(cfg Config) bool {
return cfg.Destinations != nil &&
- cfg.Destinations.SplunkHEC != nil &&
- cfg.Destinations.SplunkHEC.Token != ""
+ ((cfg.Destinations.SplunkHEC != nil && cfg.Destinations.SplunkHEC.Token != "") ||
+ (cfg.Destinations.FalconHEC != nil && cfg.Destinations.FalconHEC.Token != ""))
}
diff --git a/cli/beacon/internal/endpoint/config/config_test.go b/cli/beacon/internal/endpoint/config/config_test.go
index 15d81575..76f337fd 100644
--- a/cli/beacon/internal/endpoint/config/config_test.go
+++ b/cli/beacon/internal/endpoint/config/config_test.go
@@ -125,6 +125,55 @@ func TestSaveRejectsIncompleteSplunkHEC(t *testing.T) {
}
}
+func TestSaveLoadFalconHECRoundTripAndPrivatePermissions(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ cfg := Default(true, filepath.Join(home, "logs", "runtime.jsonl"))
+ cfg.Destinations = &Destinations{FalconHEC: &FalconHEC{
+ Endpoint: "https://cloud.us.humio.com/api/v1/ingest/hec",
+ Token: "ingest-token",
+ Index: "beacon-repo",
+ }}
+
+ path, err := Save(cfg)
+ if err != nil {
+ t.Fatalf("Save returned error: %v", err)
+ }
+ info, err := os.Stat(path)
+ if err != nil {
+ t.Fatalf("stat config: %v", err)
+ }
+ if got, want := info.Mode().Perm(), os.FileMode(0600); got != want {
+ t.Fatalf("config permissions = %o, want %o", got, want)
+ }
+
+ loaded, err := Load(true)
+ if err != nil {
+ t.Fatalf("Load returned error: %v", err)
+ }
+ falcon := loaded.Destinations.FalconHEC
+ if !falcon.Enabled {
+ t.Fatal("FalconHEC.Enabled = false, want true")
+ }
+ if falcon.Source != DefaultFalconSource || falcon.Sourcetype != DefaultFalconSourcetype {
+ t.Fatalf("Falcon defaults = source %q sourcetype %q", falcon.Source, falcon.Sourcetype)
+ }
+ if falcon.Token != "ingest-token" || falcon.Index != "beacon-repo" {
+ t.Fatalf("Falcon config did not round-trip: %#v", falcon)
+ }
+}
+
+func TestSaveRejectsIncompleteFalconHEC(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ cfg := Default(true, filepath.Join(home, "runtime.jsonl"))
+ cfg.Destinations = &Destinations{FalconHEC: &FalconHEC{Endpoint: "https://cloud.us.humio.com/api/v1/ingest/hec"}}
+
+ if _, err := Save(cfg); err == nil {
+ t.Fatal("expected missing Falcon token error")
+ }
+}
+
func TestLoadDefaultsMissingContentRetentionToFull(t *testing.T) {
home := t.TempDir()
t.Setenv("HOME", home)
diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
index 4e2a1106..e195780c 100644
--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
@@ -30,6 +30,7 @@ type InstallOptions struct {
IncludeRuntimeMetrics bool
IncludeCodexSpans bool
SplunkHEC *endpointconfig.SplunkHEC
+ FalconHEC *endpointconfig.FalconHEC
}
type UninstallOptions struct {
@@ -63,6 +64,7 @@ type Status struct {
type DestinationStatus struct {
SplunkHEC ConfiguredStatus `json:"splunk_hec"`
+ FalconHEC ConfiguredStatus `json:"falcon_hec"`
}
type ConfiguredStatus struct {
@@ -287,7 +289,18 @@ func buildConfig(opts InstallOptions) endpointconfig.Config {
cfg.ContentRetention = opts.ContentRetention
}
if opts.SplunkHEC != nil {
- cfg.Destinations = &endpointconfig.Destinations{SplunkHEC: opts.SplunkHEC}
+ if cfg.Destinations == nil {
+ cfg.Destinations = &endpointconfig.Destinations{}
+ }
+ cfg.Destinations.SplunkHEC = opts.SplunkHEC
+ }
+ if opts.FalconHEC != nil {
+ if cfg.Destinations == nil {
+ cfg.Destinations = &endpointconfig.Destinations{}
+ }
+ cfg.Destinations.FalconHEC = opts.FalconHEC
+ }
+ if cfg.Destinations != nil {
endpointconfig.NormalizeDestinations(&cfg)
}
return cfg
@@ -296,24 +309,40 @@ func buildConfig(opts InstallOptions) endpointconfig.Config {
func installDestination(cfg endpointconfig.Config) *schema.DestinationInfo {
destination := &schema.DestinationInfo{Type: "local_jsonl", Mode: "file", Status: "configured"}
if cfg.Destinations != nil && cfg.Destinations.SplunkHEC != nil && cfg.Destinations.SplunkHEC.Enabled {
- destination.Type = "local_jsonl,splunk_hec"
- destination.Mode = "file,hec"
+ destination.Type += ",splunk_hec"
+ destination.Mode += ",hec"
+ }
+ if cfg.Destinations != nil && cfg.Destinations.FalconHEC != nil && cfg.Destinations.FalconHEC.Enabled {
+ destination.Type += ",falcon_hec"
+ destination.Mode += ",hec"
}
return destination
}
func destinationStatus(cfg endpointconfig.Config) DestinationStatus {
status := DestinationStatus{}
- if cfg.Destinations == nil || cfg.Destinations.SplunkHEC == nil || !cfg.Destinations.SplunkHEC.Enabled {
+ if cfg.Destinations == nil {
return status
}
- splunk := cfg.Destinations.SplunkHEC
- status.SplunkHEC = ConfiguredStatus{
- Configured: true,
- Endpoint: splunk.Endpoint,
- Index: splunk.Index,
- Source: splunk.Source,
- Sourcetype: splunk.Sourcetype,
+ if cfg.Destinations.SplunkHEC != nil && cfg.Destinations.SplunkHEC.Enabled {
+ splunk := cfg.Destinations.SplunkHEC
+ status.SplunkHEC = ConfiguredStatus{
+ Configured: true,
+ Endpoint: splunk.Endpoint,
+ Index: splunk.Index,
+ Source: splunk.Source,
+ Sourcetype: splunk.Sourcetype,
+ }
+ }
+ if cfg.Destinations.FalconHEC != nil && cfg.Destinations.FalconHEC.Enabled {
+ falcon := cfg.Destinations.FalconHEC
+ status.FalconHEC = ConfiguredStatus{
+ Configured: true,
+ Endpoint: falcon.Endpoint,
+ Index: falcon.Index,
+ Source: falcon.Source,
+ Sourcetype: falcon.Sourcetype,
+ }
}
return status
}
diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.go
index 770838fe..febcd160 100644
--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.go
+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.go
@@ -46,6 +46,11 @@ func TestBuildConfigAppliesInstallOptions(t *testing.T) {
Token: "hec-token",
Index: "beacon",
},
+ FalconHEC: &endpointconfig.FalconHEC{
+ Endpoint: "https://cloud.us.humio.com/api/v1/ingest/hec",
+ Token: "ingest-token",
+ Index: "beacon-repo",
+ },
})
if !cfg.UserMode || cfg.LogPath != logPath {
@@ -66,6 +71,12 @@ func TestBuildConfigAppliesInstallOptions(t *testing.T) {
if got := cfg.Destinations.SplunkHEC.Source; got != endpointconfig.DefaultSplunkSource {
t.Fatalf("Splunk source = %q, want default", got)
}
+ if cfg.Destinations.FalconHEC == nil || !cfg.Destinations.FalconHEC.Enabled {
+ t.Fatalf("Falcon destination not configured: %#v", cfg.Destinations)
+ }
+ if got := cfg.Destinations.FalconHEC.Sourcetype; got != endpointconfig.DefaultFalconSourcetype {
+ t.Fatalf("Falcon sourcetype = %q, want default", got)
+ }
}
func TestSelectRuntimeLogWarnsWhenSystemCollectorConflictsWithUserMode(t *testing.T) {
diff --git a/collector-builder/builder.yaml b/collector-builder/builder.yaml
index 737d1dd7..4655f9ca 100644
--- a/collector-builder/builder.yaml
+++ b/collector-builder/builder.yaml
@@ -13,6 +13,8 @@ processors:
exporters:
- gomod: github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter v0.0.0
path: ./exporter/beaconjsonexporter
+ - gomod: github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter/falconhecexporter v0.0.0
+ path: ./exporter/beaconjsonexporter/falconhecexporter
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/exporter/splunkhecexporter v0.121.0
extensions:
diff --git a/collector-builder/exporter/beaconjsonexporter/event.go b/collector-builder/exporter/beaconjsonexporter/event.go
index 7052c240..59260343 100644
--- a/collector-builder/exporter/beaconjsonexporter/event.go
+++ b/collector-builder/exporter/beaconjsonexporter/event.go
@@ -1,141 +1,31 @@
package beaconjsonexporter
import (
- "os"
- "runtime"
"time"
+
+ "github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter/internal/beaconevent"
)
const (
- vendor = "beacon"
- product = "endpoint-agent"
- schemaVersion = "1.0"
+ vendor = beaconevent.Vendor
+ product = beaconevent.Product
+ schemaVersion = beaconevent.SchemaVersion
)
-type eventInfo struct {
- Kind string `json:"kind"`
- Action string `json:"action"`
- Category string `json:"category,omitempty"`
-}
-
-type endpointInfo struct {
- Hostname string `json:"hostname,omitempty"`
- OS string `json:"os"`
-}
-
-type userInfo struct {
- Name string `json:"name,omitempty"`
-}
-
-type harnessInfo struct {
- Name string `json:"name"`
- Version string `json:"version,omitempty"`
- ExecutablePath string `json:"executable_path,omitempty"`
- ConfigPath string `json:"config_path,omitempty"`
-}
-
-type sessionInfo struct {
- ID string `json:"id,omitempty"`
- WorkingDirectory string `json:"working_directory,omitempty"`
-}
-
-type toolInfo struct {
- Name string `json:"name,omitempty"`
- Command string `json:"command,omitempty"`
- Path string `json:"path,omitempty"`
-}
-
-type fileInfo struct {
- Path string `json:"path,omitempty"`
- Operation string `json:"operation,omitempty"`
- Language string `json:"language,omitempty"`
- DiffHash string `json:"diff_hash,omitempty"`
- DiffBytes int `json:"diff_bytes,omitempty"`
-}
-
-type commandInfo struct {
- Command string `json:"command,omitempty"`
- ExitCode *int `json:"exit_code,omitempty"`
- DurationMS int64 `json:"duration_ms,omitempty"`
-}
-
-type mcpInfo struct {
- Server string `json:"server,omitempty"`
- Tool string `json:"tool,omitempty"`
-}
-
-type approvalInfo struct {
- Required bool `json:"required,omitempty"`
- Decision string `json:"decision,omitempty"`
- Reason string `json:"reason,omitempty"`
-}
-
-type promptInfo struct {
- Text string `json:"text,omitempty"`
-}
-
-type contentInfo struct {
- Retention string `json:"retention"`
- Included bool `json:"included"`
- Redacted bool `json:"redacted,omitempty"`
- Truncated bool `json:"truncated,omitempty"`
-}
-
-type beaconEvent struct {
- Timestamp string `json:"timestamp"`
- Vendor string `json:"vendor"`
- Product string `json:"product"`
- SchemaVersion string `json:"schema_version"`
- Event eventInfo `json:"event"`
- Severity string `json:"severity"`
- Endpoint endpointInfo `json:"endpoint"`
- User userInfo `json:"user,omitempty"`
- Harness harnessInfo `json:"harness"`
- Session *sessionInfo `json:"session,omitempty"`
- Tool *toolInfo `json:"tool,omitempty"`
- File *fileInfo `json:"file,omitempty"`
- Command *commandInfo `json:"command,omitempty"`
- MCP *mcpInfo `json:"mcp,omitempty"`
- Approval *approvalInfo `json:"approval,omitempty"`
- Prompt *promptInfo `json:"prompt,omitempty"`
- Content *contentInfo `json:"content,omitempty"`
- Model string `json:"model,omitempty"`
- Repository string `json:"repository,omitempty"`
- Branch string `json:"branch,omitempty"`
- Message string `json:"message,omitempty"`
- Raw map[string]interface{} `json:"raw,omitempty"`
- Truncated bool `json:"field_truncated,omitempty"`
-}
+type eventInfo = beaconevent.EventInfo
+type endpointInfo = beaconevent.EndpointInfo
+type userInfo = beaconevent.UserInfo
+type harnessInfo = beaconevent.HarnessInfo
+type sessionInfo = beaconevent.SessionInfo
+type toolInfo = beaconevent.ToolInfo
+type fileInfo = beaconevent.FileInfo
+type commandInfo = beaconevent.CommandInfo
+type mcpInfo = beaconevent.MCPInfo
+type approvalInfo = beaconevent.ApprovalInfo
+type promptInfo = beaconevent.PromptInfo
+type contentInfo = beaconevent.ContentInfo
+type beaconEvent = beaconevent.Event
func newBeaconEvent(action, category, severity, harnessName string, ts time.Time) beaconEvent {
- if ts.IsZero() {
- ts = time.Now().UTC()
- }
- if severity == "" {
- severity = "info"
- }
- if harnessName == "" {
- harnessName = "unknown"
- }
- hostname, _ := os.Hostname()
- return beaconEvent{
- Timestamp: ts.UTC().Format(time.RFC3339),
- Vendor: vendor,
- Product: product,
- SchemaVersion: schemaVersion,
- Event: eventInfo{
- Kind: "agent_runtime",
- Action: action,
- Category: category,
- },
- Severity: severity,
- Endpoint: endpointInfo{
- Hostname: hostname,
- OS: runtime.GOOS,
- },
- User: userInfo{
- Name: os.Getenv("USER"),
- },
- Harness: harnessInfo{Name: harnessName},
- }
+ return beaconevent.NewEvent(action, category, severity, harnessName, ts)
}
diff --git a/collector-builder/exporter/beaconjsonexporter/exporter.go b/collector-builder/exporter/beaconjsonexporter/exporter.go
index 9e3bb64d..65bbe16b 100644
--- a/collector-builder/exporter/beaconjsonexporter/exporter.go
+++ b/collector-builder/exporter/beaconjsonexporter/exporter.go
@@ -2,9 +2,7 @@ package beaconjsonexporter
import (
"context"
- "encoding/json"
"fmt"
- "strings"
"time"
"go.opentelemetry.io/collector/component"
@@ -14,33 +12,24 @@ import (
"go.opentelemetry.io/collector/pdata/pmetric"
"go.opentelemetry.io/collector/pdata/ptrace"
"go.uber.org/zap"
+
+ "github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter/internal/beaconevent"
)
type beaconExporter struct {
- cfg *Config
- writer jsonlWriter
- logger *zap.Logger
+ cfg *Config
+ writer jsonlWriter
+ logger *zap.Logger
+ converter beaconevent.Converter
}
const (
- codexConversationStarts = "codex.conversation_starts"
- codexUserPrompt = "codex.user_prompt"
- codexToolDecision = "codex.tool_decision"
- codexToolResult = "codex.tool_result"
+ codexConversationStarts = beaconevent.CodexConversationStarts
+ codexUserPrompt = beaconevent.CodexUserPrompt
+ codexToolDecision = beaconevent.CodexToolDecision
+ codexToolResult = beaconevent.CodexToolResult
)
-var allowedCodexLogEvents = map[string]struct{}{
- codexConversationStarts: {},
- codexUserPrompt: {},
- codexToolDecision: {},
- codexToolResult: {},
-}
-
-var noisyCodexLogMessages = []string{
- "runtime metrics reset skipped",
- "flushing otel metrics",
-}
-
func newExporter(raw component.Config, set exporter.Settings) (*beaconExporter, error) {
cfg, ok := raw.(*Config)
if !ok {
@@ -71,27 +60,20 @@ func newExporter(raw component.Config, set exporter.Settings) (*beaconExporter,
redactSecrets: cfg.RedactSecrets,
},
logger: set.Logger,
+ converter: beaconevent.NewConverter(beaconevent.Options{
+ ContentRetention: cfg.ContentRetention,
+ IncludeRuntimeMetrics: cfg.IncludeRuntimeMetrics,
+ IncludeCodexSpans: cfg.IncludeCodexSpans,
+ }),
}, nil
}
func (e *beaconExporter) consumeLogs(ctx context.Context, logs plog.Logs) error {
_ = ctx
var firstErr error
- for i := 0; i < logs.ResourceLogs().Len(); i++ {
- resourceLogs := logs.ResourceLogs().At(i)
- resourceAttrs := attrsToMap(resourceLogs.Resource().Attributes())
- for j := 0; j < resourceLogs.ScopeLogs().Len(); j++ {
- scopeLogs := resourceLogs.ScopeLogs().At(j)
- for k := 0; k < scopeLogs.LogRecords().Len(); k++ {
- record := scopeLogs.LogRecords().At(k)
- if shouldDropLog(resourceAttrs, record) {
- continue
- }
- event := e.eventFromLog(resourceAttrs, record)
- if err := e.writer.append(event); err != nil && firstErr == nil {
- firstErr = err
- }
- }
+ for _, event := range e.eventConverter().EventsFromLogs(logs) {
+ if err := e.writer.append(event); err != nil && firstErr == nil {
+ firstErr = err
}
}
return firstErr
@@ -100,21 +82,9 @@ func (e *beaconExporter) consumeLogs(ctx context.Context, logs plog.Logs) error
func (e *beaconExporter) consumeTraces(ctx context.Context, traces ptrace.Traces) error {
_ = ctx
var firstErr error
- for i := 0; i < traces.ResourceSpans().Len(); i++ {
- resourceSpans := traces.ResourceSpans().At(i)
- resourceAttrs := attrsToMap(resourceSpans.Resource().Attributes())
- for j := 0; j < resourceSpans.ScopeSpans().Len(); j++ {
- scopeSpans := resourceSpans.ScopeSpans().At(j)
- for k := 0; k < scopeSpans.Spans().Len(); k++ {
- span := scopeSpans.Spans().At(k)
- if e.shouldDropSpan(resourceAttrs, span) {
- continue
- }
- event := e.eventFromSpan(resourceAttrs, span)
- if err := e.writer.append(event); err != nil && firstErr == nil {
- firstErr = err
- }
- }
+ for _, event := range e.eventConverter().EventsFromTraces(traces) {
+ if err := e.writer.append(event); err != nil && firstErr == nil {
+ firstErr = err
}
}
return firstErr
@@ -123,559 +93,129 @@ func (e *beaconExporter) consumeTraces(ctx context.Context, traces ptrace.Traces
func (e *beaconExporter) consumeMetrics(ctx context.Context, metrics pmetric.Metrics) error {
_ = ctx
var firstErr error
- for i := 0; i < metrics.ResourceMetrics().Len(); i++ {
- resourceMetrics := metrics.ResourceMetrics().At(i)
- resourceAttrs := attrsToMap(resourceMetrics.Resource().Attributes())
- for j := 0; j < resourceMetrics.ScopeMetrics().Len(); j++ {
- scopeMetrics := resourceMetrics.ScopeMetrics().At(j)
- for k := 0; k < scopeMetrics.Metrics().Len(); k++ {
- metric := scopeMetrics.Metrics().At(k)
- if shouldDropMetric(resourceAttrs, metric.Name(), e.cfg.IncludeRuntimeMetrics) {
- continue
- }
- event := e.eventFromMetric(resourceAttrs, metric)
- if err := e.writer.append(event); err != nil && firstErr == nil {
- firstErr = err
- }
- }
+ for _, event := range e.eventConverter().EventsFromMetrics(metrics) {
+ if err := e.writer.append(event); err != nil && firstErr == nil {
+ firstErr = err
}
}
return firstErr
}
func shouldDropLog(resourceAttrs map[string]interface{}, record plog.LogRecord) bool {
- attrs := mergeMaps(resourceAttrs, attrsToMap(record.Attributes()))
- if harnessName(attrs, record.Body().AsString()) != "codex_cli" {
- return false
- }
- return isNoisyCodexLog(attrs, record.Body().AsString())
-}
-
-func isNoisyCodexLog(attrs map[string]interface{}, body string) bool {
- eventName := codexLogEventName(attrs)
- if eventName == "" {
- message := strings.ToLower(firstNonEmpty(body, firstString(attrs, "message", "log.message")))
- for _, noisy := range noisyCodexLogMessages {
- if strings.Contains(message, noisy) {
- return true
- }
- }
- return false
- }
- if _, ok := allowedCodexLogEvents[eventName]; ok {
- return false
- }
- // Codex adds new observability events over time. Keep endpoint activity quiet
- // unless a Codex log event is explicitly mapped into Beacon's stable schema.
- return strings.HasPrefix(eventName, "codex.")
+ return beaconevent.ShouldDropLog(resourceAttrs, record)
}
func shouldDropMetric(resourceAttrs map[string]interface{}, name string, includeRuntimeMetrics bool) bool {
- if shouldDropCodexMetric(resourceAttrs, name) {
- return true
- }
- if shouldDropOpenClawMetric(resourceAttrs, name, includeRuntimeMetrics) {
- return true
- }
- if shouldDropCopilotMetric(resourceAttrs, name, includeRuntimeMetrics) {
- return true
- }
- if !includeRuntimeMetrics && shouldDropRuntimeMetric(name) {
- return true
- }
- return false
-}
-
-func shouldDropRuntimeMetric(name string) bool {
- normalized := strings.ToLower(strings.TrimSpace(name))
- if normalized == "" {
- return false
- }
- dropPrefixes := []string{
- "process.",
- "nodejs.",
- "runtime.nodejs.",
- "v8js.",
- }
- for _, prefix := range dropPrefixes {
- if strings.HasPrefix(normalized, prefix) {
- return true
- }
- }
- return false
-}
-
-func shouldDropCodexMetric(resourceAttrs map[string]interface{}, name string) bool {
- if harnessName(resourceAttrs, name) != "codex_cli" {
- return false
- }
- normalized := strings.ToLower(strings.TrimSpace(name))
- return strings.HasPrefix(normalized, "codex.")
-}
-
-func shouldDropOpenClawMetric(resourceAttrs map[string]interface{}, name string, includeRuntimeMetrics bool) bool {
- if includeRuntimeMetrics {
- return false
- }
- normalized := strings.ToLower(strings.TrimSpace(name))
- if normalized == "" {
- return false
- }
- if harnessName(resourceAttrs, name) != "openclaw_gateway" {
- return false
- }
- return true
-}
-
-func shouldDropCopilotMetric(resourceAttrs map[string]interface{}, name string, includeRuntimeMetrics bool) bool {
- if includeRuntimeMetrics {
- return false
- }
- if harnessName(resourceAttrs, name) != "copilot_cli" {
- return false
- }
- normalized := strings.ToLower(strings.TrimSpace(name))
- if normalized == "" {
- return false
- }
- return true
+ return beaconevent.ShouldDropMetric(resourceAttrs, name, includeRuntimeMetrics)
}
func (e *beaconExporter) eventFromLog(resourceAttrs map[string]interface{}, record plog.LogRecord) beaconEvent {
- attrs := mergeMaps(resourceAttrs, attrsToMap(record.Attributes()))
- ts := timestamp(record.Timestamp().AsTime())
- action := firstString(attrs, "beacon.event.action", "event.action", "gen_ai.agent.action", "ai.agent.action")
- if action == "" {
- action = inferAction(attrs, record.Body().AsString())
- }
- message := firstNonEmpty(record.Body().AsString(), firstString(attrs, "message", "log.message", "event.name"))
- event := newBeaconEvent(action, eventCategory(action, firstString(attrs, "beacon.event.category", "event.category", "category")), severity(record.SeverityText(), record.SeverityNumber().String()), harnessName(attrs, message), ts)
- event.Message = message
- e.populateCommon(&event, attrs)
- event.Raw = e.rawPayload(attrs, map[string]interface{}{
- "otel_signal": "logs",
- "severity": record.SeverityText(),
- })
- e.normalizeCodexLogEvent(&event, attrs)
- return event
+ return e.eventConverter().EventFromLog(resourceAttrs, record)
}
func (e *beaconExporter) eventFromSpan(resourceAttrs map[string]interface{}, span ptrace.Span) beaconEvent {
- attrs := mergeMaps(resourceAttrs, attrsToMap(span.Attributes()))
- action := firstString(attrs, "beacon.event.action", "event.action", "gen_ai.agent.action", "ai.agent.action")
- if action == "" {
- action = inferAction(attrs, span.Name())
- }
- message := firstNonEmpty(firstString(attrs, "message", "gen_ai.prompt", "gen_ai.response"), span.Name())
- event := newBeaconEvent(action, eventCategory(action, firstString(attrs, "beacon.event.category", "event.category", "tool")), spanSeverity(span.Status().Code().String()), harnessName(attrs, message, span.Name()), timestamp(span.StartTimestamp().AsTime()))
- event.Message = message
- e.populateCommon(&event, attrs)
- event.Raw = e.rawPayload(attrs, map[string]interface{}{
- "otel_signal": "traces",
- "span_name": span.Name(),
- "span_kind": span.Kind().String(),
- "status": span.Status().Code().String(),
- })
- return event
+ return e.eventConverter().EventFromSpan(resourceAttrs, span)
}
func (e *beaconExporter) shouldDropSpan(resourceAttrs map[string]interface{}, span ptrace.Span) bool {
- attrs := mergeMaps(resourceAttrs, attrsToMap(span.Attributes()))
- if harnessName(attrs, span.Name()) != "codex_cli" {
- return false
- }
- // Codex spans are high-volume internals that duplicate the semantic Codex log
- // events Beacon uses for session, prompt, approval, and tool activity. Keep
- // them disabled by default, but allow opt-in troubleshooting capture.
- return !e.cfg.IncludeCodexSpans
+ return e.eventConverter().ShouldDropSpan(resourceAttrs, span)
}
func (e *beaconExporter) normalizeCodexLogEvent(event *beaconEvent, attrs map[string]interface{}) {
- if event == nil || event.Harness.Name != "codex_cli" {
- return
- }
- switch codexLogEventName(attrs) {
- case codexConversationStarts:
- event.Event.Action = "session.started"
- event.Event.Category = "session"
- event.Message = "Codex session started"
- case codexUserPrompt:
- event.Event.Action = "prompt.submitted"
- event.Event.Category = "prompt"
- event.Message = "Codex prompt submitted"
- case codexToolDecision:
- decision := firstString(attrs, "decision")
- if strings.EqualFold(decision, "denied") || strings.EqualFold(decision, "deny") {
- event.Event.Action = "approval.denied"
- } else {
- event.Event.Action = "approval.requested"
- }
- event.Event.Category = "approval"
- event.Message = "Codex tool decision"
- if event.Approval == nil {
- event.Approval = &approvalInfo{}
- }
- event.Approval.Required = true
- event.Approval.Decision = decision
- event.Approval.Reason = firstString(attrs, "source", "approval_mode", "active_approval_mode")
- case codexToolResult:
- normalizeCodexToolResult(event, attrs)
- }
+ e.eventConverter().NormalizeCodexLogEvent(event, attrs)
}
func codexLogEventName(attrs map[string]interface{}) string {
- return strings.ToLower(firstString(attrs, "event.name"))
+ return beaconevent.CodexLogEventName(attrs)
}
func normalizeCodexToolResult(event *beaconEvent, attrs map[string]interface{}) {
- toolName := firstString(attrs, "tool.name", "tool_name", "function_name", "tool", "mcp_server")
- args := firstString(attrs, "arguments", "function_args", "tool.command", "command")
- event.Event.Action = "tool.invoked"
- event.Event.Category = "tool"
- if event.Tool == nil {
- event.Tool = &toolInfo{}
- }
- event.Tool.Name = toolName
- event.Tool.Command = args
- if command := codexShellCommand(toolName, args); command != "" {
- event.Event.Action = "command.executed"
- event.Event.Category = "command"
- event.Command = &commandInfo{Command: command}
- }
- event.Message = firstNonEmpty(toolName, "Codex tool result")
-}
-
-func codexShellCommand(toolName, args string) string {
- if strings.EqualFold(toolName, "shell") {
- if cmd := codexArgumentCommand(args); cmd != "" {
- return cmd
- }
- return args
- }
- return codexArgumentCommand(args)
-}
-
-func codexArgumentCommand(args string) string {
- var payload struct {
- Cmd string `json:"cmd"`
- }
- if err := json.Unmarshal([]byte(args), &payload); err != nil {
- return ""
- }
- return strings.TrimSpace(payload.Cmd)
+ beaconevent.NormalizeCodexToolResult(event, attrs)
}
func (e *beaconExporter) eventFromMetric(resourceAttrs map[string]interface{}, metric pmetric.Metric) beaconEvent {
- attrs := mergeMaps(resourceAttrs, map[string]interface{}{})
- action := firstString(attrs, "beacon.event.action", "event.action")
- if action == "" {
- action = "metric.observed"
- }
- event := newBeaconEvent(action, "metric", "info", harnessName(attrs, metric.Name()), time.Now().UTC())
- event.Message = metric.Name()
- e.populateCommon(&event, attrs)
- event.Raw = e.rawPayload(attrs, map[string]interface{}{
- "otel_signal": "metrics",
- "metric_name": metric.Name(),
- "metric_description": metric.Description(),
- "metric_unit": metric.Unit(),
- })
- return event
+ return e.eventConverter().EventFromMetric(resourceAttrs, metric)
}
func (e *beaconExporter) populateCommon(event *beaconEvent, attrs map[string]interface{}) {
- event.Model = firstString(attrs, "gen_ai.request.model", "gen_ai.response.model", "model", "ai.model")
- event.Repository = firstString(attrs, "vcs.repository.url", "repository", "repo.path", "workspace.repository")
- event.Branch = firstString(attrs, "vcs.branch.name", "git.branch", "branch")
- if id := firstString(attrs, "session.id", "conversation.id", "conversation_id", "gen_ai.conversation.id"); id != "" || firstString(attrs, "cwd", "working_directory", "workspace") != "" {
- event.Session = &sessionInfo{
- ID: id,
- WorkingDirectory: firstString(attrs, "cwd", "working_directory", "process.command_args.cwd", "workspace"),
- }
- }
- if name := firstString(attrs, "tool.name", "gen_ai.tool.name", "mcp.tool.name", "function_name", "tool_name"); name != "" || firstString(attrs, "tool.command", "command", "function_args") != "" {
- event.Tool = &toolInfo{
- Name: name,
- Command: firstString(attrs, "tool.command", "command", "process.command_line", "function_args"),
- Path: firstString(attrs, "tool.path", "file.path", "file_path"),
- }
- }
- if path := firstString(attrs, "file.path", "file_path", "code.filepath"); path != "" {
- event.File = &fileInfo{
- Path: path,
- Operation: firstString(attrs, "file.operation", "operation"),
- Language: firstString(attrs, "code.language", "language"),
- }
- }
- if command := firstString(attrs, "command", "process.command_line", "shell.command"); command != "" {
- event.Command = &commandInfo{Command: command}
- if exitCode, ok := intAttr(attrs, "exit_code", "process.exit_code", "command.exit_code"); ok {
- event.Command.ExitCode = &exitCode
- }
- if duration, ok := int64Attr(attrs, "duration_ms", "command.duration_ms"); ok {
- event.Command.DurationMS = duration
- }
- }
- if server := firstString(attrs, "mcp.server.name", "mcp.server", "gen_ai.mcp.server", "mcp_server_name"); server != "" || firstString(attrs, "mcp.tool.name") != "" || firstString(attrs, "tool_type") == "mcp" {
- event.MCP = &mcpInfo{
- Server: server,
- Tool: firstString(attrs, "mcp.tool.name", "tool.name", "function_name"),
- }
- }
- if decision := firstString(attrs, "approval.decision", "policy.decision", "decision"); decision != "" {
- event.Approval = &approvalInfo{
- Required: true,
- Decision: decision,
- Reason: firstString(attrs, "approval.reason", "policy.reason", "approval_mode", "active_approval_mode"),
- }
- }
- if e.cfg.ContentRetention != "metadata" && event.Event.Category == "prompt" {
- if text := firstString(attrs, "gen_ai.prompt", "prompt", "user_prompt", "input.prompt"); text != "" {
- event.Prompt = &promptInfo{Text: text}
- }
- }
- event.Content = &contentInfo{Retention: e.cfg.ContentRetention, Included: e.cfg.ContentRetention != "metadata", Redacted: e.cfg.ContentRetention == "redacted"}
+ e.eventConverter().PopulateCommon(event, attrs)
}
func (e *beaconExporter) rawPayload(attrs map[string]interface{}, extra map[string]interface{}) map[string]interface{} {
- raw := map[string]interface{}{}
- for k, v := range extra {
- raw[k] = v
- }
- if e.cfg.ContentRetention == "metadata" {
- raw["attribute_count"] = len(attrs)
- return raw
+ return e.eventConverter().RawPayload(attrs, extra)
+}
+
+func (e *beaconExporter) eventConverter() beaconevent.Converter {
+ if e == nil || e.cfg == nil {
+ return beaconevent.NewConverter(beaconevent.Options{})
}
- raw["attributes"] = attrs
- return raw
+ return beaconevent.NewConverter(beaconevent.Options{
+ ContentRetention: e.cfg.ContentRetention,
+ IncludeRuntimeMetrics: e.cfg.IncludeRuntimeMetrics,
+ IncludeCodexSpans: e.cfg.IncludeCodexSpans,
+ })
}
func attrsToMap(attrs pcommon.Map) map[string]interface{} {
- out := make(map[string]interface{}, attrs.Len())
- attrs.Range(func(k string, v pcommon.Value) bool {
- out[k] = v.AsRaw()
- return true
- })
- return out
+ return beaconevent.AttrsToMap(attrs)
}
func mergeMaps(a, b map[string]interface{}) map[string]interface{} {
- out := make(map[string]interface{}, len(a)+len(b))
- for k, v := range a {
- out[k] = v
- }
- for k, v := range b {
- out[k] = v
- }
- return out
+ return beaconevent.MergeMaps(a, b)
}
func firstString(attrs map[string]interface{}, keys ...string) string {
- for _, key := range keys {
- if value, ok := attrs[key]; ok {
- if str := strings.TrimSpace(fmt.Sprint(value)); str != "" && str != "<nil>" {
- return str
- }
- }
- }
- return ""
+ return beaconevent.FirstString(attrs, keys...)
}
func firstNonEmpty(values ...string) string {
- for _, value := range values {
- if strings.TrimSpace(value) != "" {
- return value
- }
- }
- return ""
+ return beaconevent.FirstNonEmpty(values...)
}
func intAttr(attrs map[string]interface{}, keys ...string) (int, bool) {
- value, ok := int64Attr(attrs, keys...)
- return int(value), ok
+ return beaconevent.IntAttr(attrs, keys...)
}
func int64Attr(attrs map[string]interface{}, keys ...string) (int64, bool) {
- for _, key := range keys {
- switch typed := attrs[key].(type) {
- case int:
- return int64(typed), true
- case int64:
- return typed, true
- case float64:
- return int64(typed), true
- }
- }
- return 0, false
+ return beaconevent.Int64Attr(attrs, keys...)
}
func timestamp(ts time.Time) time.Time {
- if ts.IsZero() || ts.UnixNano() == 0 {
- return time.Now().UTC()
- }
- return ts
+ return beaconevent.Timestamp(ts)
}
func severity(text, number string) string {
- lower := strings.ToLower(text + " " + number)
- switch {
- case strings.Contains(lower, "fatal") || strings.Contains(lower, "critical"):
- return "critical"
- case strings.Contains(lower, "error"):
- return "high"
- case strings.Contains(lower, "warn"):
- return "medium"
- default:
- return "info"
- }
+ return beaconevent.Severity(text, number)
}
func spanSeverity(status string) string {
- if strings.Contains(strings.ToLower(status), "error") {
- return "high"
- }
- return "info"
+ return beaconevent.SpanSeverity(status)
}
func harnessName(attrs map[string]interface{}, hints ...string) string {
- name := firstString(attrs, "beacon.harness.name", "harness.name", "service.name", "telemetry.sdk.name")
- if explicit := firstString(attrs, "beacon.harness.name", "harness.name"); explicit != "" {
- return normalizeHarnessName(explicit)
- }
- candidates := append([]string{name}, hints...)
- for _, candidate := range candidates {
- if normalized := normalizeHarnessName(candidate); normalized != "" {
- return normalized
- }
- }
- if name != "" {
- return name
- }
- return "otel"
+ return beaconevent.HarnessName(attrs, hints...)
}
func normalizeHarnessName(name string) string {
- lower := strings.ToLower(strings.TrimSpace(name))
- switch {
- case lower == "":
- return ""
- case strings.Contains(lower, "cowork") || strings.Contains(lower, "co-work"):
- return "claude_cowork"
- case strings.Contains(lower, "claude_code") || strings.Contains(lower, "claude-code") || strings.Contains(lower, "claude code") || strings.HasPrefix(lower, "claude_code."):
- return "claude_code"
- case lower == "claude" || strings.Contains(lower, "claude"):
- return "claude_code"
- case strings.Contains(lower, "openclaw") || strings.Contains(lower, "open-claw"):
- return "openclaw_gateway"
- case strings.Contains(lower, "codex"):
- return "codex_cli"
- case strings.Contains(lower, "gemini"):
- return "gemini_cli"
- case strings.Contains(lower, "github-copilot") || strings.Contains(lower, "copilot-chat") || strings.Contains(lower, "copilot_cli") || strings.Contains(lower, "copilot"):
- return "copilot_cli"
- case name != "":
- return name
- default:
- return ""
- }
+ return beaconevent.NormalizeHarnessName(name)
}
func inferAction(attrs map[string]interface{}, fallback string) string {
- tool := strings.ToLower(firstString(attrs, "tool.name", "gen_ai.tool.name", "mcp.tool.name", "function_name", "tool_name"))
- operation := strings.ToLower(firstString(attrs, "gen_ai.operation.name"))
- harness := harnessName(attrs, fallback)
- text := strings.ToLower(strings.Join([]string{
- fallback,
- tool,
- operation,
- firstString(attrs, "event.name", "codex.op", "rpc.method"),
- }, " "))
- switch {
- case harness == "copilot_cli":
- return copilotAction(attrs, operation, text)
- case strings.Contains(text, "gemini_cli.user_prompt"):
- return "prompt.submitted"
- case strings.Contains(text, "gemini_cli.tool_call"):
- return geminiToolAction(attrs)
- case strings.Contains(text, "gemini_cli.file_operation"):
- return geminiFileAction(attrs)
- case strings.Contains(text, "approval_mode_switch") || strings.Contains(text, "approval_mode_duration") || strings.Contains(text, "plan_execution"):
- return "approval.requested"
- case strings.Contains(text, "prompt") || strings.Contains(text, "user_input"):
- return "prompt.submitted"
- case strings.Contains(text, "mcp"):
- return "mcp.tool_invoked"
- case strings.Contains(text, "command") || strings.Contains(text, "shell") || strings.Contains(text, "exec"):
- return "command.executed"
- case strings.Contains(text, "file") || strings.Contains(text, "write") || strings.Contains(text, "edit"):
- return "file.modified"
- case strings.Contains(text, "approval"):
- return "approval.requested"
- default:
- return "tool.invoked"
- }
+ return beaconevent.InferAction(attrs, fallback)
}
func copilotAction(attrs map[string]interface{}, operation, text string) string {
- switch {
- case operation == "invoke_agent":
- return "session.activity"
- case operation == "chat":
- initiator := strings.ToLower(firstString(attrs, "github.copilot.initiator"))
- turnID := firstString(attrs, "github.copilot.turn_id")
- if initiator == "agent" || (turnID != "" && turnID != "0") {
- return "session.activity"
- }
- return "prompt.submitted"
- case operation == "execute_tool":
- return "tool.invoked"
- case strings.Contains(text, "permission"):
- return "approval.requested"
- default:
- return "tool.invoked"
- }
+ return beaconevent.CopilotAction(attrs, operation, text)
}
func geminiToolAction(attrs map[string]interface{}) string {
- if firstString(attrs, "tool_type") == "mcp" || firstString(attrs, "mcp_server_name") != "" {
- return "mcp.tool_invoked"
- }
- return "tool.invoked"
+ return beaconevent.GeminiToolAction(attrs)
}
func geminiFileAction(attrs map[string]interface{}) string {
- switch strings.ToLower(firstString(attrs, "operation")) {
- case "read":
- return "file.read"
- case "create":
- return "file.created"
- default:
- return "file.modified"
- }
+ return beaconevent.GeminiFileAction(attrs)
}
func eventCategory(action, explicit string) string {
- if explicit != "" {
- return explicit
- }
- switch {
- case strings.HasPrefix(action, "prompt."):
- return "prompt"
- case strings.HasPrefix(action, "command."):
- return "command"
- case strings.HasPrefix(action, "file."):
- return "file"
- case strings.HasPrefix(action, "mcp."):
- return "mcp"
- case strings.HasPrefix(action, "approval.") || strings.HasPrefix(action, "policy."):
- return "approval"
- case strings.HasPrefix(action, "session."):
- return "session"
- case strings.HasPrefix(action, "metric."):
- return "metric"
- case strings.HasPrefix(action, "tool."):
- return "tool"
- default:
- return ""
- }
+ return beaconevent.EventCategory(action, explicit)
}
diff --git a/collector-builder/exporter/beaconjsonexporter/falconhecexporter/config.go b/collector-builder/exporter/beaconjsonexporter/falconhecexporter/config.go
new file mode 100644
index 00000000..92f24e8e
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/falconhecexporter/config.go
@@ -0,0 +1,66 @@
+package falconhecexporter
+
+import (
+ "fmt"
+ "net/url"
+ "time"
+
+ "go.opentelemetry.io/collector/config/configretry"
+ "go.opentelemetry.io/collector/exporter/exporterhelper"
+)
+
+const defaultTimeout = 10 * time.Second
+
+type Config struct {
+ Endpoint string `mapstructure:"endpoint"`
+ Token string `mapstructure:"token"`
+ Source string `mapstructure:"source"`
+ Sourcetype string `mapstructure:"sourcetype"`
+ Index string `mapstructure:"index"`
+ InsecureSkipVerify bool `mapstructure:"insecure_skip_verify"`
+ CAFile string `mapstructure:"ca_file"`
+ Timeout time.Duration `mapstructure:"timeout"`
+ QueueSettings exporterhelper.QueueConfig `mapstructure:"sending_queue"`
+ RetrySettings configretry.BackOffConfig `mapstructure:"retry_on_failure"`
+ ContentRetention string `mapstructure:"content_retention"`
+ IncludeRuntimeMetrics bool `mapstructure:"include_runtime_metrics"`
+ IncludeCodexSpans bool `mapstructure:"include_codex_spans"`
+}
+
+func createDefaultConfig() *Config {
+ queue := exporterhelper.NewDefaultQueueConfig()
+ queue.QueueSize = 256
+ return &Config{
+ Timeout: defaultTimeout,
+ QueueSettings: queue,
+ RetrySettings: configretry.NewDefaultBackOffConfig(),
+ ContentRetention: "full",
+ }
+}
+
+func (c *Config) Validate() error {
+ if c.Endpoint == "" {
+ return fmt.Errorf("endpoint is required")
+ }
+ if _, err := url.ParseRequestURI(c.Endpoint); err != nil {
+ return fmt.Errorf("endpoint must be a full URL: %w", err)
+ }
+ if c.Token == "" {
+ return fmt.Errorf("token is required")
+ }
+ if c.Timeout < 0 {
+ return fmt.Errorf("timeout must be non-negative")
+ }
+ if err := c.QueueSettings.Validate(); err != nil {
+ return err
+ }
+ if err := c.RetrySettings.Validate(); err != nil {
+ return err
+ }
+ switch c.ContentRetention {
+ case "", "metadata", "redacted", "full":
+ return nil
+ default:
+ return fmt.Errorf("content_retention must be metadata, redacted, or full")
+ }
+}
diff --git a/collector-builder/exporter/beaconjsonexporter/falconhecexporter/exporter.go b/collector-builder/exporter/beaconjsonexporter/falconhecexporter/exporter.go
new file mode 100644
index 00000000..ab864a5f
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/falconhecexporter/exporter.go
@@ -0,0 +1,209 @@
+package falconhecexporter
+
+import (
+ "bytes"
+ "context"
+ "crypto/tls"
+ "crypto/x509"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "os"
+ "strings"
+ "time"
+
+ "go.opentelemetry.io/collector/component"
+ "go.opentelemetry.io/collector/consumer"
+ "go.opentelemetry.io/collector/exporter"
+ "go.opentelemetry.io/collector/pdata/plog"
+ "go.opentelemetry.io/collector/pdata/pmetric"
+ "go.opentelemetry.io/collector/pdata/ptrace"
+ "go.uber.org/zap"
+
+ "github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter/internal/beaconevent"
+)
+
+type falconExporter struct {
+ cfg *Config
+ client *http.Client
+ logger *zap.Logger
+ converter beaconevent.Converter
+}
+
+type hecPayload struct {
+ Time float64 `json:"time,omitempty"`
+ Event map[string]interface{} `json:"event"`
+ Source string `json:"source,omitempty"`
+ Sourcetype string `json:"sourcetype,omitempty"`
+ Index string `json:"index,omitempty"`
+}
+
+func newExporter(raw component.Config, set exporter.Settings) (*falconExporter, error) {
+ cfg, ok := raw.(*Config)
+ if !ok {
+ return nil, fmt.Errorf("unexpected config type %T", raw)
+ }
+ if cfg.Timeout == 0 {
+ cfg.Timeout = defaultTimeout
+ }
+ if cfg.ContentRetention == "" {
+ cfg.ContentRetention = "full"
+ }
+ if err := cfg.Validate(); err != nil {
+ return nil, err
+ }
+ client, err := httpClient(cfg)
+ if err != nil {
+ return nil, err
+ }
+ return &falconExporter{
+ cfg: cfg,
+ client: client,
+ logger: set.Logger,
+ converter: beaconevent.NewConverter(beaconevent.Options{
+ ContentRetention: cfg.ContentRetention,
+ IncludeRuntimeMetrics: cfg.IncludeRuntimeMetrics,
+ IncludeCodexSpans: cfg.IncludeCodexSpans,
+ }),
+ }, nil
+}
+
+func httpClient(cfg *Config) (*http.Client, error) {
+ transport := http.DefaultTransport.(*http.Transport).Clone()
+ if cfg.InsecureSkipVerify || cfg.CAFile != "" {
+ tlsConfig := &tls.Config{InsecureSkipVerify: cfg.InsecureSkipVerify} //nolint:gosec // User opt-in for private/self-signed LogScale endpoints.
+ if cfg.CAFile != "" {
+ pem, err := os.ReadFile(cfg.CAFile)
+ if err != nil {
+ return nil, err
+ }
+ pool, err := x509.SystemCertPool()
+ if err != nil || pool == nil {
+ pool = x509.NewCertPool()
+ }
+ if ok := pool.AppendCertsFromPEM(pem); !ok {
+ return nil, fmt.Errorf("failed to parse CA file %q", cfg.CAFile)
+ }
+ tlsConfig.RootCAs = pool
+ }
+ transport.TLSClientConfig = tlsConfig
+ }
+ return &http.Client{Transport: transport, Timeout: cfg.Timeout}, nil
+}
+
+func (e *falconExporter) consumeLogs(ctx context.Context, logs plog.Logs) error {
+ return e.sendEvents(ctx, e.converter.EventsFromLogs(logs))
+}
+
+func (e *falconExporter) consumeTraces(ctx context.Context, traces ptrace.Traces) error {
+ return e.sendEvents(ctx, e.converter.EventsFromTraces(traces))
+}
+
+func (e *falconExporter) consumeMetrics(ctx context.Context, metrics pmetric.Metrics) error {
+ return e.sendEvents(ctx, e.converter.EventsFromMetrics(metrics))
+}
+
+func (e *falconExporter) sendEvents(ctx context.Context, events []beaconevent.Event) error {
+ if len(events) == 0 {
+ return nil
+ }
+ var body bytes.Buffer
+ for _, event := range events {
+ payload, err := e.hecPayload(event)
+ if err != nil {
+ return err
+ }
+ if err := json.NewEncoder(&body).Encode(payload); err != nil {
+ return err
+ }
+ }
+ req, err := http.NewRequestWithContext(ctx, http.MethodPost, e.cfg.Endpoint, &body)
+ if err != nil {
+ return err
+ }
+ req.Header.Set("Authorization", "Bearer "+e.cfg.Token)
+ req.Header.Set("Content-Type", "text/plain; charset=utf-8")
+ resp, err := e.client.Do(req)
+ if err != nil {
+ return err
+ }
+ defer resp.Body.Close()
+ if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+ text, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+ return fmt.Errorf("falcon HEC returned status %d: %s", resp.StatusCode, strings.TrimSpace(string(text)))
+ }
+ return nil
+}
+
+func (e *falconExporter) hecPayload(event beaconevent.Event) (hecPayload, error) {
+ eventObject, err := eventObject(event)
+ if err != nil {
+ return hecPayload{}, err
+ }
+ ts, err := eventTime(event)
+ if err != nil {
+ return hecPayload{}, err
+ }
+ eventObject["@timestamp"] = ts.UTC().Format(time.RFC3339Nano)
+ return hecPayload{
+ Time: float64(ts.UnixNano()) / float64(time.Second),
+ Event: eventObject,
+ Source: e.cfg.Source,
+ Sourcetype: e.cfg.Sourcetype,
+ Index: e.cfg.Index,
+ }, nil
+}
+
+func eventObject(event beaconevent.Event) (map[string]interface{}, error) {
+ data, err := json.Marshal(event)
+ if err != nil {
+ return nil, err
+ }
+ var out map[string]interface{}
+ if err := json.Unmarshal(data, &out); err != nil {
+ return nil, err
+ }
+ return out, nil
+}
+
+func eventTime(event beaconevent.Event) (time.Time, error) {
+ if !event.ObservedAt.IsZero() {
+ return event.ObservedAt.UTC(), nil
+ }
+ if event.Timestamp == "" {
+ return time.Now().UTC(), nil
+ }
+ ts, err := time.Parse(time.RFC3339Nano, event.Timestamp)
+ if err != nil {
+ return time.Time{}, err
+ }
+ return ts.UTC(), nil
+}
+
+func createLogsExporter(ctx context.Context, set exporter.Settings, cfg component.Config) (exporter.Logs, error) {
+ exp, err := newExporter(cfg, set)
+ if err != nil {
+ return nil, err
+ }
+ fcfg := cfg.(*Config)
+ return exporterhelperNewLogs(ctx, set, cfg, consumer.ConsumeLogsFunc(exp.consumeLogs), fcfg)
+}
+
+func createTracesExporter(ctx context.Context, set exporter.Settings, cfg component.Config) (exporter.Traces, error) {
+ exp, err := newExporter(cfg, set)
+ if err != nil {
+ return nil, err
+ }
+ fcfg := cfg.(*Config)
+ return exporterhelperNewTraces(ctx, set, cfg, consumer.ConsumeTracesFunc(exp.consumeTraces), fcfg)
+}
+
+func createMetricsExporter(ctx context.Context, set exporter.Settings, cfg component.Config) (exporter.Metrics, error) {
+ exp, err := newExporter(cfg, set)
+ if err != nil {
+ return nil, err
+ }
+ fcfg := cfg.(*Config)
+ return exporterhelperNewMetrics(ctx, set, cfg, consumer.ConsumeMetricsFunc(exp.consumeMetrics), fcfg)
+}
diff --git a/collector-builder/exporter/beaconjsonexporter/falconhecexporter/exporter_test.go b/collector-builder/exporter/beaconjsonexporter/falconhecexporter/exporter_test.go
new file mode 100644
index 00000000..04219b81
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/falconhecexporter/exporter_test.go
@@ -0,0 +1,187 @@
+package falconhecexporter
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+
+ "go.opentelemetry.io/collector/config/configretry"
+ "go.opentelemetry.io/collector/exporter"
+ "go.opentelemetry.io/collector/pdata/pcommon"
+ "go.opentelemetry.io/collector/pdata/plog"
+
+ "github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter/internal/beaconevent"
+)
+
+func TestConfigValidateRequiresEndpointAndToken(t *testing.T) {
+ cfg := createDefaultConfig()
+ if err := cfg.Validate(); err == nil {
+ t.Fatal("expected missing endpoint error")
+ }
+ cfg.Endpoint = "https://logscale.example/api/v1/ingest/hec"
+ if err := cfg.Validate(); err == nil {
+ t.Fatal("expected missing token error")
+ }
+ cfg.Token = "ingest-token"
+ if err := cfg.Validate(); err != nil {
+ t.Fatalf("Validate returned error: %v", err)
+ }
+}
+
+func TestConsumeLogsSendsBearerHECPayload(t *testing.T) {
+ var gotAuth string
+ var gotContentType string
+ var payload hecPayload
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotAuth = r.Header.Get("Authorization")
+ gotContentType = r.Header.Get("Content-Type")
+ decoder := json.NewDecoder(r.Body)
+ if err := decoder.Decode(&payload); err != nil {
+ t.Fatalf("decode payload: %v", err)
+ }
+ w.WriteHeader(http.StatusOK)
+ }))
+ defer server.Close()
+
+ exp, err := newExporter(&Config{
+ Endpoint: server.URL,
+ Token: "ingest-token",
+ Source: "beacon-endpoint-agent",
+ Sourcetype: "json",
+ Index: "beacon-repo",
+ Timeout: time.Second,
+ QueueSettings: createDefaultConfig().QueueSettings,
+ RetrySettings: createDefaultConfig().RetrySettings,
+ ContentRetention: "full",
+ }, exporter.Settings{})
+ if err != nil {
+ t.Fatalf("newExporter returned error: %v", err)
+ }
+
+ logs := plog.NewLogs()
+ rec := logs.ResourceLogs().AppendEmpty().ScopeLogs().AppendEmpty().LogRecords().AppendEmpty()
+ ts := time.Date(2024, 11, 18, 12, 31, 40, 251000000, time.UTC)
+ rec.SetTimestamp(pcommon.Timestamp(ts.UnixNano()))
+ rec.Body().SetStr("prompt submitted")
+ rec.Attributes().PutStr("beacon.event.action", "prompt.submitted")
+ rec.Attributes().PutStr("gen_ai.prompt", "summarize this")
+ rec.Attributes().PutStr("service.name", "claude-code")
+
+ if err := exp.consumeLogs(context.Background(), logs); err != nil {
+ t.Fatalf("consumeLogs returned error: %v", err)
+ }
+
+ if gotAuth != "Bearer ingest-token" {
+ t.Fatalf("Authorization = %q, want Bearer token", gotAuth)
+ }
+ if !strings.HasPrefix(gotContentType, "text/plain") {
+ t.Fatalf("Content-Type = %q, want text/plain", gotContentType)
+ }
+ if payload.Source != "beacon-endpoint-agent" || payload.Sourcetype != "json" || payload.Index != "beacon-repo" {
+ t.Fatalf("wrapper metadata missing: %#v", payload)
+ }
+ if payload.Event == nil {
+ t.Fatal("payload event is nil")
+ }
+ if payload.Event["@timestamp"] != "2024-11-18T12:31:40.251Z" {
+ t.Fatalf("@timestamp = %#v", payload.Event["@timestamp"])
+ }
+ if payload.Event["vendor"] != "beacon" || payload.Event["product"] != "endpoint-agent" {
+ t.Fatalf("Beacon fields were not nested in event object: %#v", payload.Event)
+ }
+ if _, ok := payload.Event["@timestamp"].(string); !ok {
+ t.Fatalf("@timestamp should be a string: %#v", payload.Event["@timestamp"])
+ }
+ if payload.Time != float64(ts.UnixNano())/float64(time.Second) {
+ t.Fatalf("time = %.9f, want %.9f", payload.Time, float64(ts.UnixNano())/float64(time.Second))
+ }
+}
+
+func TestHECPayloadUsesObservedAtForSubsecondTimestamp(t *testing.T) {
+ exp := &falconExporter{cfg: createDefaultConfig()}
+ ts := time.Date(2024, 11, 18, 12, 31, 40, 251000000, time.UTC)
+ event := testEvent(ts.Format(time.RFC3339))
+ event.ObservedAt = ts
+ payload, err := exp.hecPayload(event)
+ if err != nil {
+ t.Fatalf("hecPayload returned error: %v", err)
+ }
+ if payload.Event["@timestamp"] != "2024-11-18T12:31:40.251Z" {
+ t.Fatalf("@timestamp = %#v", payload.Event["@timestamp"])
+ }
+ if payload.Time != float64(ts.UnixNano())/float64(time.Second) {
+ t.Fatalf("time = %.9f, want %.9f", payload.Time, float64(ts.UnixNano())/float64(time.Second))
+ }
+}
+
+func TestConsumeLogsReturnsErrorForNonSuccess(t *testing.T) {
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ http.Error(w, "nope", http.StatusUnauthorized)
+ }))
+ defer server.Close()
+ exp, err := newExporter(&Config{
+ Endpoint: server.URL,
+ Token: "bad-token",
+ Timeout: time.Second,
+ QueueSettings: createDefaultConfig().QueueSettings,
+ RetrySettings: configNoRetry(),
+ ContentRetention: "metadata",
+ }, exporter.Settings{})
+ if err != nil {
+ t.Fatalf("newExporter returned error: %v", err)
+ }
+ logs := plog.NewLogs()
+ logs.ResourceLogs().AppendEmpty().ScopeLogs().AppendEmpty().LogRecords().AppendEmpty().Body().SetStr("hello")
+ err = exp.consumeLogs(context.Background(), logs)
+ if err == nil || !strings.Contains(err.Error(), "status 401") {
+ t.Fatalf("consumeLogs error = %v, want status 401", err)
+ }
+}
+
+func TestHECPayloadDoesNotMutateCanonicalEvent(t *testing.T) {
+ exp := &falconExporter{cfg: createDefaultConfig()}
+ event := testEvent("2024-11-18T12:31:40.251Z")
+ payload, err := exp.hecPayload(event)
+ if err != nil {
+ t.Fatalf("hecPayload returned error: %v", err)
+ }
+ if _, ok := payload.Event["@timestamp"]; !ok {
+ t.Fatal("payload missing @timestamp")
+ }
+ if data, err := json.Marshal(event); err != nil {
+ t.Fatal(err)
+ } else if strings.Contains(string(data), "@timestamp") {
+ t.Fatalf("canonical event mutated with @timestamp: %s", string(data))
+ }
+}
+
+func testEvent(timestamp string) beaconevent.Event {
+ return beaconevent.Event{
+ ObservedAt: mustParseTime(timestamp),
+ Timestamp: timestamp,
+ Vendor: "beacon",
+ Product: "endpoint-agent",
+ SchemaVersion: "1.0",
+ Event: beaconevent.EventInfo{Kind: "agent_runtime", Action: "tool.invoked"},
+ Severity: "info",
+ Harness: beaconevent.HarnessInfo{Name: "test"},
+ }
+}
+
+func mustParseTime(value string) time.Time {
+ ts, err := time.Parse(time.RFC3339Nano, value)
+ if err != nil {
+ panic(err)
+ }
+ return ts
+}
+
+func configNoRetry() configretry.BackOffConfig {
+ cfg := createDefaultConfig().RetrySettings
+ cfg.Enabled = false
+ return cfg
+}
diff --git a/collector-builder/exporter/beaconjsonexporter/falconhecexporter/factory.go b/collector-builder/exporter/beaconjsonexporter/falconhecexporter/factory.go
new file mode 100644
index 00000000..5b02c5e6
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/falconhecexporter/factory.go
@@ -0,0 +1,42 @@
+package falconhecexporter
+
+import (
+ "context"
+
+ "go.opentelemetry.io/collector/component"
+ "go.opentelemetry.io/collector/consumer"
+ "go.opentelemetry.io/collector/exporter"
+ "go.opentelemetry.io/collector/exporter/exporterhelper"
+)
+
+var componentType = component.MustNewType("falcon_hec")
+
+func NewFactory() exporter.Factory {
+ return exporter.NewFactory(
+ componentType,
+ func() component.Config { return createDefaultConfig() },
+ exporter.WithLogs(createLogsExporter, component.StabilityLevelBeta),
+ exporter.WithTraces(createTracesExporter, component.StabilityLevelBeta),
+ exporter.WithMetrics(createMetricsExporter, component.StabilityLevelBeta),
+ )
+}
+
+func exporterOptions(cfg *Config) []exporterhelper.Option {
+ return []exporterhelper.Option{
+ exporterhelper.WithQueue(cfg.QueueSettings),
+ exporterhelper.WithRetry(cfg.RetrySettings),
+ exporterhelper.WithTimeout(exporterhelper.TimeoutConfig{Timeout: cfg.Timeout}),
+ }
+}
+
+func exporterhelperNewLogs(ctx context.Context, set exporter.Settings, cfg component.Config, pusher consumer.ConsumeLogsFunc, fcfg *Config) (exporter.Logs, error) {
+ return exporterhelper.NewLogs(ctx, set, cfg, pusher, exporterOptions(fcfg)...)
+}
+
+func exporterhelperNewTraces(ctx context.Context, set exporter.Settings, cfg component.Config, pusher consumer.ConsumeTracesFunc, fcfg *Config) (exporter.Traces, error) {
+ return exporterhelper.NewTraces(ctx, set, cfg, pusher, exporterOptions(fcfg)...)
+}
+
+func exporterhelperNewMetrics(ctx context.Context, set exporter.Settings, cfg component.Config, pusher consumer.ConsumeMetricsFunc, fcfg *Config) (exporter.Metrics, error) {
+ return exporterhelper.NewMetrics(ctx, set, cfg, pusher, exporterOptions(fcfg)...)
+}
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
new file mode 100644
index 00000000..42061729
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
@@ -0,0 +1,633 @@
+package beaconevent
+
+import (
+ "encoding/json"
+ "fmt"
+ "strings"
+ "time"
+
+ "go.opentelemetry.io/collector/pdata/pcommon"
+ "go.opentelemetry.io/collector/pdata/plog"
+ "go.opentelemetry.io/collector/pdata/pmetric"
+ "go.opentelemetry.io/collector/pdata/ptrace"
+)
+
+const (
+ CodexConversationStarts = "codex.conversation_starts"
+ CodexUserPrompt = "codex.user_prompt"
+ CodexToolDecision = "codex.tool_decision"
+ CodexToolResult = "codex.tool_result"
+)
+
+var allowedCodexLogEvents = map[string]struct{}{
+ CodexConversationStarts: {},
+ CodexUserPrompt: {},
+ CodexToolDecision: {},
+ CodexToolResult: {},
+}
+
+var noisyCodexLogMessages = []string{
+ "runtime metrics reset skipped",
+ "flushing otel metrics",
+}
+
+type Options struct {
+ ContentRetention string
+ IncludeRuntimeMetrics bool
+ IncludeCodexSpans bool
+}
+
+type Converter struct {
+ opts Options
+}
+
+func NewConverter(opts Options) Converter {
+ if opts.ContentRetention == "" {
+ opts.ContentRetention = "full"
+ }
+ return Converter{opts: opts}
+}
+
+func (c Converter) EventsFromLogs(logs plog.Logs) []Event {
+ var events []Event
+ for i := 0; i < logs.ResourceLogs().Len(); i++ {
+ resourceLogs := logs.ResourceLogs().At(i)
+ resourceAttrs := AttrsToMap(resourceLogs.Resource().Attributes())
+ for j := 0; j < resourceLogs.ScopeLogs().Len(); j++ {
+ scopeLogs := resourceLogs.ScopeLogs().At(j)
+ for k := 0; k < scopeLogs.LogRecords().Len(); k++ {
+ record := scopeLogs.LogRecords().At(k)
+ if ShouldDropLog(resourceAttrs, record) {
+ continue
+ }
+ events = append(events, c.EventFromLog(resourceAttrs, record))
+ }
+ }
+ }
+ return events
+}
+
+func (c Converter) EventsFromTraces(traces ptrace.Traces) []Event {
+ var events []Event
+ for i := 0; i < traces.ResourceSpans().Len(); i++ {
+ resourceSpans := traces.ResourceSpans().At(i)
+ resourceAttrs := AttrsToMap(resourceSpans.Resource().Attributes())
+ for j := 0; j < resourceSpans.ScopeSpans().Len(); j++ {
+ scopeSpans := resourceSpans.ScopeSpans().At(j)
+ for k := 0; k < scopeSpans.Spans().Len(); k++ {
+ span := scopeSpans.Spans().At(k)
+ if c.ShouldDropSpan(resourceAttrs, span) {
+ continue
+ }
+ events = append(events, c.EventFromSpan(resourceAttrs, span))
+ }
+ }
+ }
+ return events
+}
+
+func (c Converter) EventsFromMetrics(metrics pmetric.Metrics) []Event {
+ var events []Event
+ for i := 0; i < metrics.ResourceMetrics().Len(); i++ {
+ resourceMetrics := metrics.ResourceMetrics().At(i)
+ resourceAttrs := AttrsToMap(resourceMetrics.Resource().Attributes())
+ for j := 0; j < resourceMetrics.ScopeMetrics().Len(); j++ {
+ scopeMetrics := resourceMetrics.ScopeMetrics().At(j)
+ for k := 0; k < scopeMetrics.Metrics().Len(); k++ {
+ metric := scopeMetrics.Metrics().At(k)
+ if ShouldDropMetric(resourceAttrs, metric.Name(), c.opts.IncludeRuntimeMetrics) {
+ continue
+ }
+ events = append(events, c.EventFromMetric(resourceAttrs, metric))
+ }
+ }
+ }
+ return events
+}
+
+func ShouldDropLog(resourceAttrs map[string]interface{}, record plog.LogRecord) bool {
+ attrs := MergeMaps(resourceAttrs, AttrsToMap(record.Attributes()))
+ if HarnessName(attrs, record.Body().AsString()) != "codex_cli" {
+ return false
+ }
+ return isNoisyCodexLog(attrs, record.Body().AsString())
+}
+
+func isNoisyCodexLog(attrs map[string]interface{}, body string) bool {
+ eventName := CodexLogEventName(attrs)
+ if eventName == "" {
+ message := strings.ToLower(FirstNonEmpty(body, FirstString(attrs, "message", "log.message")))
+ for _, noisy := range noisyCodexLogMessages {
+ if strings.Contains(message, noisy) {
+ return true
+ }
+ }
+ return false
+ }
+ if _, ok := allowedCodexLogEvents[eventName]; ok {
+ return false
+ }
+ return strings.HasPrefix(eventName, "codex.")
+}
+
+func ShouldDropMetric(resourceAttrs map[string]interface{}, name string, includeRuntimeMetrics bool) bool {
+ if shouldDropCodexMetric(resourceAttrs, name) {
+ return true
+ }
+ if shouldDropOpenClawMetric(resourceAttrs, name, includeRuntimeMetrics) {
+ return true
+ }
+ if shouldDropCopilotMetric(resourceAttrs, name, includeRuntimeMetrics) {
+ return true
+ }
+ if !includeRuntimeMetrics && shouldDropRuntimeMetric(name) {
+ return true
+ }
+ return false
+}
+
+func shouldDropRuntimeMetric(name string) bool {
+ normalized := strings.ToLower(strings.TrimSpace(name))
+ if normalized == "" {
+ return false
+ }
+ dropPrefixes := []string{"process.", "nodejs.", "runtime.nodejs.", "v8js."}
+ for _, prefix := range dropPrefixes {
+ if strings.HasPrefix(normalized, prefix) {
+ return true
+ }
+ }
+ return false
+}
+
+func shouldDropCodexMetric(resourceAttrs map[string]interface{}, name string) bool {
+ if HarnessName(resourceAttrs, name) != "codex_cli" {
+ return false
+ }
+ normalized := strings.ToLower(strings.TrimSpace(name))
+ return strings.HasPrefix(normalized, "codex.")
+}
+
+func shouldDropOpenClawMetric(resourceAttrs map[string]interface{}, name string, includeRuntimeMetrics bool) bool {
+ if includeRuntimeMetrics {
+ return false
+ }
+ normalized := strings.ToLower(strings.TrimSpace(name))
+ if normalized == "" {
+ return false
+ }
+ if HarnessName(resourceAttrs, name) != "openclaw_gateway" {
+ return false
+ }
+ return true
+}
+
+func shouldDropCopilotMetric(resourceAttrs map[string]interface{}, name string, includeRuntimeMetrics bool) bool {
+ if includeRuntimeMetrics {
+ return false
+ }
+ if HarnessName(resourceAttrs, name) != "copilot_cli" {
+ return false
+ }
+ normalized := strings.ToLower(strings.TrimSpace(name))
+ if normalized == "" {
+ return false
+ }
+ return true
+}
+
+func (c Converter) EventFromLog(resourceAttrs map[string]interface{}, record plog.LogRecord) Event {
+ attrs := MergeMaps(resourceAttrs, AttrsToMap(record.Attributes()))
+ ts := Timestamp(record.Timestamp().AsTime())
+ action := FirstString(attrs, "beacon.event.action", "event.action", "gen_ai.agent.action", "ai.agent.action")
+ if action == "" {
+ action = InferAction(attrs, record.Body().AsString())
+ }
+ message := FirstNonEmpty(record.Body().AsString(), FirstString(attrs, "message", "log.message", "event.name"))
+ event := NewEvent(action, EventCategory(action, FirstString(attrs, "beacon.event.category", "event.category", "category")), Severity(record.SeverityText(), record.SeverityNumber().String()), HarnessName(attrs, message), ts)
+ event.Message = message
+ c.PopulateCommon(&event, attrs)
+ event.Raw = c.RawPayload(attrs, map[string]interface{}{
+ "otel_signal": "logs",
+ "severity": record.SeverityText(),
+ })
+ c.NormalizeCodexLogEvent(&event, attrs)
+ return event
+}
+
+func (c Converter) EventFromSpan(resourceAttrs map[string]interface{}, span ptrace.Span) Event {
+ attrs := MergeMaps(resourceAttrs, AttrsToMap(span.Attributes()))
+ action := FirstString(attrs, "beacon.event.action", "event.action", "gen_ai.agent.action", "ai.agent.action")
+ if action == "" {
+ action = InferAction(attrs, span.Name())
+ }
+ message := FirstNonEmpty(FirstString(attrs, "message", "gen_ai.prompt", "gen_ai.response"), span.Name())
+ event := NewEvent(action, EventCategory(action, FirstString(attrs, "beacon.event.category", "event.category", "tool")), SpanSeverity(span.Status().Code().String()), HarnessName(attrs, message, span.Name()), Timestamp(span.StartTimestamp().AsTime()))
+ event.Message = message
+ c.PopulateCommon(&event, attrs)
+ event.Raw = c.RawPayload(attrs, map[string]interface{}{
+ "otel_signal": "traces",
+ "span_name": span.Name(),
+ "span_kind": span.Kind().String(),
+ "status": span.Status().Code().String(),
+ })
+ return event
+}
+
+func (c Converter) ShouldDropSpan(resourceAttrs map[string]interface{}, span ptrace.Span) bool {
+ attrs := MergeMaps(resourceAttrs, AttrsToMap(span.Attributes()))
+ if HarnessName(attrs, span.Name()) != "codex_cli" {
+ return false
+ }
+ return !c.opts.IncludeCodexSpans
+}
+
+func (c Converter) NormalizeCodexLogEvent(event *Event, attrs map[string]interface{}) {
+ if event == nil || event.Harness.Name != "codex_cli" {
+ return
+ }
+ switch CodexLogEventName(attrs) {
+ case CodexConversationStarts:
+ event.Event.Action = "session.started"
+ event.Event.Category = "session"
+ event.Message = "Codex session started"
+ case CodexUserPrompt:
+ event.Event.Action = "prompt.submitted"
+ event.Event.Category = "prompt"
+ event.Message = "Codex prompt submitted"
+ case CodexToolDecision:
+ decision := FirstString(attrs, "decision")
+ if strings.EqualFold(decision, "denied") || strings.EqualFold(decision, "deny") {
+ event.Event.Action = "approval.denied"
+ } else {
+ event.Event.Action = "approval.requested"
+ }
+ event.Event.Category = "approval"
+ event.Message = "Codex tool decision"
+ if event.Approval == nil {
+ event.Approval = &ApprovalInfo{}
+ }
+ event.Approval.Required = true
+ event.Approval.Decision = decision
+ event.Approval.Reason = FirstString(attrs, "source", "approval_mode", "active_approval_mode")
+ case CodexToolResult:
+ NormalizeCodexToolResult(event, attrs)
+ }
+}
+
+func CodexLogEventName(attrs map[string]interface{}) string {
+ return strings.ToLower(FirstString(attrs, "event.name"))
+}
+
+func NormalizeCodexToolResult(event *Event, attrs map[string]interface{}) {
+ toolName := FirstString(attrs, "tool.name", "tool_name", "function_name", "tool", "mcp_server")
+ args := FirstString(attrs, "arguments", "function_args", "tool.command", "command")
+ event.Event.Action = "tool.invoked"
+ event.Event.Category = "tool"
+ if event.Tool == nil {
+ event.Tool = &ToolInfo{}
+ }
+ event.Tool.Name = toolName
+ event.Tool.Command = args
+ if command := codexShellCommand(toolName, args); command != "" {
+ event.Event.Action = "command.executed"
+ event.Event.Category = "command"
+ event.Command = &CommandInfo{Command: command}
+ }
+ event.Message = FirstNonEmpty(toolName, "Codex tool result")
+}
+
+func codexShellCommand(toolName, args string) string {
+ if strings.EqualFold(toolName, "shell") {
+ if cmd := codexArgumentCommand(args); cmd != "" {
+ return cmd
+ }
+ return args
+ }
+ return codexArgumentCommand(args)
+}
+
+func codexArgumentCommand(args string) string {
+ var payload struct {
+ Cmd string `json:"cmd"`
+ }
+ if err := json.Unmarshal([]byte(args), &payload); err != nil {
+ return ""
+ }
+ return strings.TrimSpace(payload.Cmd)
+}
+
+func (c Converter) EventFromMetric(resourceAttrs map[string]interface{}, metric pmetric.Metric) Event {
+ attrs := MergeMaps(resourceAttrs, map[string]interface{}{})
+ action := FirstString(attrs, "beacon.event.action", "event.action")
+ if action == "" {
+ action = "metric.observed"
+ }
+ event := NewEvent(action, "metric", "info", HarnessName(attrs, metric.Name()), time.Now().UTC())
+ event.Message = metric.Name()
+ c.PopulateCommon(&event, attrs)
+ event.Raw = c.RawPayload(attrs, map[string]interface{}{
+ "otel_signal": "metrics",
+ "metric_name": metric.Name(),
+ "metric_description": metric.Description(),
+ "metric_unit": metric.Unit(),
+ })
+ return event
+}
+
+func (c Converter) PopulateCommon(event *Event, attrs map[string]interface{}) {
+ event.Model = FirstString(attrs, "gen_ai.request.model", "gen_ai.response.model", "model", "ai.model")
+ event.Repository = FirstString(attrs, "vcs.repository.url", "repository", "repo.path", "workspace.repository")
+ event.Branch = FirstString(attrs, "vcs.branch.name", "git.branch", "branch")
+ if id := FirstString(attrs, "session.id", "conversation.id", "conversation_id", "gen_ai.conversation.id"); id != "" || FirstString(attrs, "cwd", "working_directory", "workspace") != "" {
+ event.Session = &SessionInfo{
+ ID: id,
+ WorkingDirectory: FirstString(attrs, "cwd", "working_directory", "process.command_args.cwd", "workspace"),
+ }
+ }
+ if name := FirstString(attrs, "tool.name", "gen_ai.tool.name", "mcp.tool.name", "function_name", "tool_name"); name != "" || FirstString(attrs, "tool.command", "command", "function_args") != "" {
+ event.Tool = &ToolInfo{
+ Name: name,
+ Command: FirstString(attrs, "tool.command", "command", "process.command_line", "function_args"),
+ Path: FirstString(attrs, "tool.path", "file.path", "file_path"),
+ }
+ }
+ if path := FirstString(attrs, "file.path", "file_path", "code.filepath"); path != "" {
+ event.File = &FileInfo{
+ Path: path,
+ Operation: FirstString(attrs, "file.operation", "operation"),
+ Language: FirstString(attrs, "code.language", "language"),
+ }
+ }
+ if command := FirstString(attrs, "command", "process.command_line", "shell.command"); command != "" {
+ event.Command = &CommandInfo{Command: command}
+ if exitCode, ok := IntAttr(attrs, "exit_code", "process.exit_code", "command.exit_code"); ok {
+ event.Command.ExitCode = &exitCode
+ }
+ if duration, ok := Int64Attr(attrs, "duration_ms", "command.duration_ms"); ok {
+ event.Command.DurationMS = duration
+ }
+ }
+ if server := FirstString(attrs, "mcp.server.name", "mcp.server", "gen_ai.mcp.server", "mcp_server_name"); server != "" || FirstString(attrs, "mcp.tool.name") != "" || FirstString(attrs, "tool_type") == "mcp" {
+ event.MCP = &MCPInfo{
+ Server: server,
+ Tool: FirstString(attrs, "mcp.tool.name", "tool.name", "function_name"),
+ }
+ }
+ if decision := FirstString(attrs, "approval.decision", "policy.decision", "decision"); decision != "" {
+ event.Approval = &ApprovalInfo{
+ Required: true,
+ Decision: decision,
+ Reason: FirstString(attrs, "approval.reason", "policy.reason", "approval_mode", "active_approval_mode"),
+ }
+ }
+ if c.opts.ContentRetention != "metadata" && event.Event.Category == "prompt" {
+ if text := FirstString(attrs, "gen_ai.prompt", "prompt", "user_prompt", "input.prompt"); text != "" {
+ event.Prompt = &PromptInfo{Text: text}
+ }
+ }
+ event.Content = &ContentInfo{Retention: c.opts.ContentRetention, Included: c.opts.ContentRetention != "metadata", Redacted: c.opts.ContentRetention == "redacted"}
+}
+
+func (c Converter) RawPayload(attrs map[string]interface{}, extra map[string]interface{}) map[string]interface{} {
+ raw := map[string]interface{}{}
+ for k, v := range extra {
+ raw[k] = v
+ }
+ if c.opts.ContentRetention == "metadata" {
+ raw["attribute_count"] = len(attrs)
+ return raw
+ }
+ raw["attributes"] = attrs
+ return raw
+}
+
+func AttrsToMap(attrs pcommon.Map) map[string]interface{} {
+ out := make(map[string]interface{}, attrs.Len())
+ attrs.Range(func(k string, v pcommon.Value) bool {
+ out[k] = v.AsRaw()
+ return true
+ })
+ return out
+}
+
+func MergeMaps(a, b map[string]interface{}) map[string]interface{} {
+ out := make(map[string]interface{}, len(a)+len(b))
+ for k, v := range a {
+ out[k] = v
+ }
+ for k, v := range b {
+ out[k] = v
+ }
+ return out
+}
+
+func FirstString(attrs map[string]interface{}, keys ...string) string {
+ for _, key := range keys {
+ if value, ok := attrs[key]; ok {
+ if str := strings.TrimSpace(fmt.Sprint(value)); str != "" && str != "<nil>" {
+ return str
+ }
+ }
+ }
+ return ""
+}
+
+func FirstNonEmpty(values ...string) string {
+ for _, value := range values {
+ if strings.TrimSpace(value) != "" {
+ return value
+ }
+ }
+ return ""
+}
+
+func IntAttr(attrs map[string]interface{}, keys ...string) (int, bool) {
+ value, ok := Int64Attr(attrs, keys...)
+ return int(value), ok
+}
+
+func Int64Attr(attrs map[string]interface{}, keys ...string) (int64, bool) {
+ for _, key := range keys {
+ switch typed := attrs[key].(type) {
+ case int:
+ return int64(typed), true
+ case int64:
+ return typed, true
+ case float64:
+ return int64(typed), true
+ }
+ }
+ return 0, false
+}
+
+func Timestamp(ts time.Time) time.Time {
+ if ts.IsZero() || ts.UnixNano() == 0 {
+ return time.Now().UTC()
+ }
+ return ts
+}
+
+func Severity(text, number string) string {
+ lower := strings.ToLower(text + " " + number)
+ switch {
+ case strings.Contains(lower, "fatal") || strings.Contains(lower, "critical"):
+ return "critical"
+ case strings.Contains(lower, "error"):
+ return "high"
+ case strings.Contains(lower, "warn"):
+ return "medium"
+ default:
+ return "info"
+ }
+}
+
+func SpanSeverity(status string) string {
+ if strings.Contains(strings.ToLower(status), "error") {
+ return "high"
+ }
+ return "info"
+}
+
+func HarnessName(attrs map[string]interface{}, hints ...string) string {
+ name := FirstString(attrs, "beacon.harness.name", "harness.name", "service.name", "telemetry.sdk.name")
+ if explicit := FirstString(attrs, "beacon.harness.name", "harness.name"); explicit != "" {
+ return NormalizeHarnessName(explicit)
+ }
+ candidates := append([]string{name}, hints...)
+ for _, candidate := range candidates {
+ if normalized := NormalizeHarnessName(candidate); normalized != "" {
+ return normalized
+ }
+ }
+ if name != "" {
+ return name
+ }
+ return "otel"
+}
+
+func NormalizeHarnessName(name string) string {
+ lower := strings.ToLower(strings.TrimSpace(name))
+ switch {
+ case lower == "":
+ return ""
+ case strings.Contains(lower, "cowork") || strings.Contains(lower, "co-work"):
+ return "claude_cowork"
+ case strings.Contains(lower, "claude_code") || strings.Contains(lower, "claude-code") || strings.Contains(lower, "claude code") || strings.HasPrefix(lower, "claude_code."):
+ return "claude_code"
+ case lower == "claude" || strings.Contains(lower, "claude"):
+ return "claude_code"
+ case strings.Contains(lower, "openclaw") || strings.Contains(lower, "open-claw"):
+ return "openclaw_gateway"
+ case strings.Contains(lower, "codex"):
+ return "codex_cli"
+ case strings.Contains(lower, "gemini"):
+ return "gemini_cli"
+ case strings.Contains(lower, "github-copilot") || strings.Contains(lower, "copilot-chat") || strings.Contains(lower, "copilot_cli") || strings.Contains(lower, "copilot"):
+ return "copilot_cli"
+ case name != "":
+ return name
+ default:
+ return ""
+ }
+}
+
+func InferAction(attrs map[string]interface{}, fallback string) string {
+ tool := strings.ToLower(FirstString(attrs, "tool.name", "gen_ai.tool.name", "mcp.tool.name", "function_name", "tool_name"))
+ operation := strings.ToLower(FirstString(attrs, "gen_ai.operation.name"))
+ harness := HarnessName(attrs, fallback)
+ text := strings.ToLower(strings.Join([]string{
+ fallback,
+ tool,
+ operation,
+ FirstString(attrs, "event.name", "codex.op", "rpc.method"),
+ }, " "))
+ switch {
+ case harness == "copilot_cli":
+ return CopilotAction(attrs, operation, text)
+ case strings.Contains(text, "gemini_cli.user_prompt"):
+ return "prompt.submitted"
+ case strings.Contains(text, "gemini_cli.tool_call"):
+ return GeminiToolAction(attrs)
+ case strings.Contains(text, "gemini_cli.file_operation"):
+ return GeminiFileAction(attrs)
+ case strings.Contains(text, "approval_mode_switch") || strings.Contains(text, "approval_mode_duration") || strings.Contains(text, "plan_execution"):
+ return "approval.requested"
+ case strings.Contains(text, "prompt") || strings.Contains(text, "user_input"):
+ return "prompt.submitted"
+ case strings.Contains(text, "mcp"):
+ return "mcp.tool_invoked"
+ case strings.Contains(text, "command") || strings.Contains(text, "shell") || strings.Contains(text, "exec"):
+ return "command.executed"
+ case strings.Contains(text, "file") || strings.Contains(text, "write") || strings.Contains(text, "edit"):
+ return "file.modified"
+ case strings.Contains(text, "approval"):
+ return "approval.requested"
+ default:
+ return "tool.invoked"
+ }
+}
+
+func CopilotAction(attrs map[string]interface{}, operation, text string) string {
+ switch {
+ case operation == "invoke_agent":
+ return "session.activity"
+ case operation == "chat":
+ initiator := strings.ToLower(FirstString(attrs, "github.copilot.initiator"))
+ turnID := FirstString(attrs, "github.copilot.turn_id")
+ if initiator == "agent" || (turnID != "" && turnID != "0") {
+ return "session.activity"
+ }
+ return "prompt.submitted"
+ case operation == "execute_tool":
+ return "tool.invoked"
+ case strings.Contains(text, "permission"):
+ return "approval.requested"
+ default:
+ return "tool.invoked"
+ }
+}
+
+func GeminiToolAction(attrs map[string]interface{}) string {
+ if FirstString(attrs, "tool_type") == "mcp" || FirstString(attrs, "mcp_server_name") != "" {
+ return "mcp.tool_invoked"
+ }
+ return "tool.invoked"
+}
+
+func GeminiFileAction(attrs map[string]interface{}) string {
+ switch strings.ToLower(FirstString(attrs, "operation")) {
+ case "read":
+ return "file.read"
+ case "create":
+ return "file.created"
+ default:
+ return "file.modified"
+ }
+}
+
+func EventCategory(action, explicit string) string {
+ if explicit != "" {
+ return explicit
+ }
+ switch {
+ case strings.HasPrefix(action, "prompt."):
+ return "prompt"
+ case strings.HasPrefix(action, "command."):
+ return "command"
+ case strings.HasPrefix(action, "file."):
+ return "file"
+ case strings.HasPrefix(action, "mcp."):
+ return "mcp"
+ case strings.HasPrefix(action, "approval.") || strings.HasPrefix(action, "policy."):
+ return "approval"
+ case strings.HasPrefix(action, "session."):
+ return "session"
+ case strings.HasPrefix(action, "metric."):
+ return "metric"
+ case strings.HasPrefix(action, "tool."):
+ return "tool"
+ default:
+ return ""
+ }
+}
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go
new file mode 100644
index 00000000..4bdfd0eb
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go
@@ -0,0 +1,141 @@
+package beaconevent
+
+import (
+ "os"
+ "runtime"
+ "time"
+)
+
+const (
+ Vendor = "beacon"
+ Product = "endpoint-agent"
+ SchemaVersion = "1.0"
+)
+
+type EventInfo struct {
+ Kind string `json:"kind"`
+ Action string `json:"action"`
+ Category string `json:"category,omitempty"`
+}
+
+type EndpointInfo struct {
+ Hostname string `json:"hostname,omitempty"`
+ OS string `json:"os"`
+}
+
+type UserInfo struct {
+ Name string `json:"name,omitempty"`
+}
+
+type HarnessInfo struct {
+ Name string `json:"name"`
+ Version string `json:"version,omitempty"`
+ ExecutablePath string `json:"executable_path,omitempty"`
+ ConfigPath string `json:"config_path,omitempty"`
+}
+
+type SessionInfo struct {
+ ID string `json:"id,omitempty"`
+ WorkingDirectory string `json:"working_directory,omitempty"`
+}
+
+type ToolInfo struct {
+ Name string `json:"name,omitempty"`
+ Command string `json:"command,omitempty"`
+ Path string `json:"path,omitempty"`
+}
+
+type FileInfo struct {
+ Path string `json:"path,omitempty"`
+ Operation string `json:"operation,omitempty"`
+ Language string `json:"language,omitempty"`
+ DiffHash string `json:"diff_hash,omitempty"`
+ DiffBytes int `json:"diff_bytes,omitempty"`
+}
+
+type CommandInfo struct {
+ Command string `json:"command,omitempty"`
+ ExitCode *int `json:"exit_code,omitempty"`
+ DurationMS int64 `json:"duration_ms,omitempty"`
+}
+
+type MCPInfo struct {
+ Server string `json:"server,omitempty"`
+ Tool string `json:"tool,omitempty"`
+}
+
+type ApprovalInfo struct {
+ Required bool `json:"required,omitempty"`
+ Decision string `json:"decision,omitempty"`
+ Reason string `json:"reason,omitempty"`
+}
+
+type PromptInfo struct {
+ Text string `json:"text,omitempty"`
+}
+
+type ContentInfo struct {
+ Retention string `json:"retention"`
+ Included bool `json:"included"`
+ Redacted bool `json:"redacted,omitempty"`
+ Truncated bool `json:"truncated,omitempty"`
+}
+
+type Event struct {
+ ObservedAt time.Time `json:"-"`
+ Timestamp string `json:"timestamp"`
+ Vendor string `json:"vendor"`
+ Product string `json:"product"`
+ SchemaVersion string `json:"schema_version"`
+ Event EventInfo `json:"event"`
+ Severity string `json:"severity"`
+ Endpoint EndpointInfo `json:"endpoint"`
+ User UserInfo `json:"user,omitempty"`
+ Harness HarnessInfo `json:"harness"`
+ Session *SessionInfo `json:"session,omitempty"`
+ Tool *ToolInfo `json:"tool,omitempty"`
+ File *FileInfo `json:"file,omitempty"`
+ Command *CommandInfo `json:"command,omitempty"`
+ MCP *MCPInfo `json:"mcp,omitempty"`
+ Approval *ApprovalInfo `json:"approval,omitempty"`
+ Prompt *PromptInfo `json:"prompt,omitempty"`
+ Content *ContentInfo `json:"content,omitempty"`
+ Model string `json:"model,omitempty"`
+ Repository string `json:"repository,omitempty"`
+ Branch string `json:"branch,omitempty"`
+ Message string `json:"message,omitempty"`
+ Raw map[string]interface{} `json:"raw,omitempty"`
+ Truncated bool `json:"field_truncated,omitempty"`
+}
+
+func NewEvent(action, category, severity, harnessName string, ts time.Time) Event {
+ if ts.IsZero() {
+ ts = time.Now().UTC()
+ }
+ if severity == "" {
+ severity = "info"
+ }
+ if harnessName == "" {
+ harnessName = "unknown"
+ }
+ hostname, _ := os.Hostname()
+ return Event{
+ ObservedAt: ts.UTC(),
+ Timestamp: ts.UTC().Format(time.RFC3339),
+ Vendor: Vendor,
+ Product: Product,
+ SchemaVersion: SchemaVersion,
+ Event: EventInfo{
+ Kind: "agent_runtime",
+ Action: action,
+ Category: category,
+ },
+ Severity: severity,
+ Endpoint: EndpointInfo{
+ Hostname: hostname,
+ OS: runtime.GOOS,
+ },
+ User: UserInfo{Name: os.Getenv("USER")},
+ Harness: HarnessInfo{Name: harnessName},
+ }
+}
diff --git a/packaging/macos/fleet/scripts/install.sh b/packaging/macos/fleet/scripts/install.sh
index 12c26696..01136e06 100755
--- a/packaging/macos/fleet/scripts/install.sh
+++ b/packaging/macos/fleet/scripts/install.sh
@@ -19,4 +19,11 @@ BEACON_SPLUNK_SOURCE="${BEACON_SPLUNK_SOURCE:-${10:-}}" \
BEACON_SPLUNK_SOURCETYPE="${BEACON_SPLUNK_SOURCETYPE:-${11:-}}" \
BEACON_SPLUNK_INSECURE_SKIP_VERIFY="${BEACON_SPLUNK_INSECURE_SKIP_VERIFY:-${12:-0}}" \
BEACON_SPLUNK_CA_FILE="${BEACON_SPLUNK_CA_FILE:-${13:-}}" \
+BEACON_FALCON_HEC_ENDPOINT="${BEACON_FALCON_HEC_ENDPOINT:-}" \
+BEACON_FALCON_HEC_TOKEN="${BEACON_FALCON_HEC_TOKEN:-}" \
+BEACON_FALCON_INDEX="${BEACON_FALCON_INDEX:-}" \
+BEACON_FALCON_SOURCE="${BEACON_FALCON_SOURCE:-}" \
+BEACON_FALCON_SOURCETYPE="${BEACON_FALCON_SOURCETYPE:-}" \
+BEACON_FALCON_INSECURE_SKIP_VERIFY="${BEACON_FALCON_INSECURE_SKIP_VERIFY:-0}" \
+BEACON_FALCON_CA_FILE="${BEACON_FALCON_CA_FILE:-}" \
"$BEACON_INSTALL_SCRIPT"
diff --git a/packaging/macos/fleet/scripts/repair.sh b/packaging/macos/fleet/scripts/repair.sh
index a311f728..fb23093e 100755
--- a/packaging/macos/fleet/scripts/repair.sh
+++ b/packaging/macos/fleet/scripts/repair.sh
@@ -14,6 +14,13 @@ BEACON_SPLUNK_SOURCE="${BEACON_SPLUNK_SOURCE:-${8:-}}"
BEACON_SPLUNK_SOURCETYPE="${BEACON_SPLUNK_SOURCETYPE:-${9:-}}"
BEACON_SPLUNK_INSECURE_SKIP_VERIFY="${BEACON_SPLUNK_INSECURE_SKIP_VERIFY:-${10:-0}}"
BEACON_SPLUNK_CA_FILE="${BEACON_SPLUNK_CA_FILE:-${11:-}}"
+BEACON_FALCON_HEC_ENDPOINT="${BEACON_FALCON_HEC_ENDPOINT:-}"
+BEACON_FALCON_HEC_TOKEN="${BEACON_FALCON_HEC_TOKEN:-}"
+BEACON_FALCON_INDEX="${BEACON_FALCON_INDEX:-}"
+BEACON_FALCON_SOURCE="${BEACON_FALCON_SOURCE:-}"
+BEACON_FALCON_SOURCETYPE="${BEACON_FALCON_SOURCETYPE:-}"
+BEACON_FALCON_INSECURE_SKIP_VERIFY="${BEACON_FALCON_INSECURE_SKIP_VERIFY:-0}"
+BEACON_FALCON_CA_FILE="${BEACON_FALCON_CA_FILE:-}"
set -- endpoint repair \
--collector "$BEACON_COLLECTOR" \
@@ -46,4 +53,28 @@ if [ -n "$BEACON_SPLUNK_CA_FILE" ]; then
set -- "$@" --splunk-ca-file "$BEACON_SPLUNK_CA_FILE"
fi
+if [ -n "$BEACON_FALCON_HEC_ENDPOINT" ]; then
+ set -- "$@" --falcon-hec-endpoint "$BEACON_FALCON_HEC_ENDPOINT"
+fi
+if [ -n "$BEACON_FALCON_HEC_TOKEN" ]; then
+ set -- "$@" --falcon-hec-token "$BEACON_FALCON_HEC_TOKEN"
+fi
+if [ -n "$BEACON_FALCON_INDEX" ]; then
+ set -- "$@" --falcon-index "$BEACON_FALCON_INDEX"
+fi
+if [ -n "$BEACON_FALCON_SOURCE" ]; then
+ set -- "$@" --falcon-source "$BEACON_FALCON_SOURCE"
+fi
+if [ -n "$BEACON_FALCON_SOURCETYPE" ]; then
+ set -- "$@" --falcon-sourcetype "$BEACON_FALCON_SOURCETYPE"
+fi
+case "$BEACON_FALCON_INSECURE_SKIP_VERIFY" in
+ 1|true|TRUE|yes|YES)
+ set -- "$@" --falcon-insecure-skip-verify
+ ;;
+esac
+if [ -n "$BEACON_FALCON_CA_FILE" ]; then
+ set -- "$@" --falcon-ca-file "$BEACON_FALCON_CA_FILE"
+fi
+
exec "$BEACON_BIN" "$@"
diff --git a/packaging/macos/install-endpoint.sh b/packaging/macos/install-endpoint.sh
index e2f70e77..d37d20e3 100755
--- a/packaging/macos/install-endpoint.sh
+++ b/packaging/macos/install-endpoint.sh
@@ -22,6 +22,13 @@ BEACON_SPLUNK_SOURCE="${BEACON_SPLUNK_SOURCE:-${13:-}}"
BEACON_SPLUNK_SOURCETYPE="${BEACON_SPLUNK_SOURCETYPE:-${14:-}}"
BEACON_SPLUNK_INSECURE_SKIP_VERIFY="${BEACON_SPLUNK_INSECURE_SKIP_VERIFY:-${15:-0}}"
BEACON_SPLUNK_CA_FILE="${BEACON_SPLUNK_CA_FILE:-${16:-}}"
+BEACON_FALCON_HEC_ENDPOINT="${BEACON_FALCON_HEC_ENDPOINT:-}"
+BEACON_FALCON_HEC_TOKEN="${BEACON_FALCON_HEC_TOKEN:-}"
+BEACON_FALCON_INDEX="${BEACON_FALCON_INDEX:-}"
+BEACON_FALCON_SOURCE="${BEACON_FALCON_SOURCE:-}"
+BEACON_FALCON_SOURCETYPE="${BEACON_FALCON_SOURCETYPE:-}"
+BEACON_FALCON_INSECURE_SKIP_VERIFY="${BEACON_FALCON_INSECURE_SKIP_VERIFY:-0}"
+BEACON_FALCON_CA_FILE="${BEACON_FALCON_CA_FILE:-}"
if [ -z "$BEACON_COLLECTOR" ] && [ -x "/opt/beacon/bin/beacon-otelcol" ]; then
BEACON_COLLECTOR="/opt/beacon/bin/beacon-otelcol"
@@ -62,6 +69,30 @@ if [ -n "$BEACON_SPLUNK_CA_FILE" ]; then
set -- "$@" --splunk-ca-file "$BEACON_SPLUNK_CA_FILE"
fi
+if [ -n "$BEACON_FALCON_HEC_ENDPOINT" ]; then
+ set -- "$@" --falcon-hec-endpoint "$BEACON_FALCON_HEC_ENDPOINT"
+fi
+if [ -n "$BEACON_FALCON_HEC_TOKEN" ]; then
+ set -- "$@" --falcon-hec-token "$BEACON_FALCON_HEC_TOKEN"
+fi
+if [ -n "$BEACON_FALCON_INDEX" ]; then
+ set -- "$@" --falcon-index "$BEACON_FALCON_INDEX"
+fi
+if [ -n "$BEACON_FALCON_SOURCE" ]; then
+ set -- "$@" --falcon-source "$BEACON_FALCON_SOURCE"
+fi
+if [ -n "$BEACON_FALCON_SOURCETYPE" ]; then
+ set -- "$@" --falcon-sourcetype "$BEACON_FALCON_SOURCETYPE"
+fi
+case "$BEACON_FALCON_INSECURE_SKIP_VERIFY" in
+ 1|true|TRUE|yes|YES)
+ set -- "$@" --falcon-insecure-skip-verify
+ ;;
+esac
+if [ -n "$BEACON_FALCON_CA_FILE" ]; then
+ set -- "$@" --falcon-ca-file "$BEACON_FALCON_CA_FILE"
+fi
+
case "$BEACON_NO_START" in
1|true|TRUE|yes|YES)
set -- "$@" --no-start
diff --git a/packaging/macos/jamf/scripts/repair.sh b/packaging/macos/jamf/scripts/repair.sh
index fd018b3d..19593f0c 100755
--- a/packaging/macos/jamf/scripts/repair.sh
+++ b/packaging/macos/jamf/scripts/repair.sh
@@ -14,6 +14,13 @@ BEACON_SPLUNK_SOURCE="${BEACON_SPLUNK_SOURCE:-${11:-}}"
BEACON_SPLUNK_SOURCETYPE="${BEACON_SPLUNK_SOURCETYPE:-${12:-}}"
BEACON_SPLUNK_INSECURE_SKIP_VERIFY="${BEACON_SPLUNK_INSECURE_SKIP_VERIFY:-${13:-0}}"
BEACON_SPLUNK_CA_FILE="${BEACON_SPLUNK_CA_FILE:-${14:-}}"
+BEACON_FALCON_HEC_ENDPOINT="${BEACON_FALCON_HEC_ENDPOINT:-}"
+BEACON_FALCON_HEC_TOKEN="${BEACON_FALCON_HEC_TOKEN:-}"
+BEACON_FALCON_INDEX="${BEACON_FALCON_INDEX:-}"
+BEACON_FALCON_SOURCE="${BEACON_FALCON_SOURCE:-}"
+BEACON_FALCON_SOURCETYPE="${BEACON_FALCON_SOURCETYPE:-}"
+BEACON_FALCON_INSECURE_SKIP_VERIFY="${BEACON_FALCON_INSECURE_SKIP_VERIFY:-0}"
+BEACON_FALCON_CA_FILE="${BEACON_FALCON_CA_FILE:-}"
set -- endpoint repair \
--collector "$BEACON_COLLECTOR" \
@@ -46,4 +53,28 @@ if [ -n "$BEACON_SPLUNK_CA_FILE" ]; then
set -- "$@" --splunk-ca-file "$BEACON_SPLUNK_CA_FILE"
fi
+if [ -n "$BEACON_FALCON_HEC_ENDPOINT" ]; then
+ set -- "$@" --falcon-hec-endpoint "$BEACON_FALCON_HEC_ENDPOINT"
+fi
+if [ -n "$BEACON_FALCON_HEC_TOKEN" ]; then
+ set -- "$@" --falcon-hec-token "$BEACON_FALCON_HEC_TOKEN"
+fi
+if [ -n "$BEACON_FALCON_INDEX" ]; then
+ set -- "$@" --falcon-index "$BEACON_FALCON_INDEX"
+fi
+if [ -n "$BEACON_FALCON_SOURCE" ]; then
+ set -- "$@" --falcon-source "$BEACON_FALCON_SOURCE"
+fi
+if [ -n "$BEACON_FALCON_SOURCETYPE" ]; then
+ set -- "$@" --falcon-sourcetype "$BEACON_FALCON_SOURCETYPE"
+fi
+case "$BEACON_FALCON_INSECURE_SKIP_VERIFY" in
+ 1|true|TRUE|yes|YES)
+ set -- "$@" --falcon-insecure-skip-verify
+ ;;
+esac
+if [ -n "$BEACON_FALCON_CA_FILE" ]; then
+ set -- "$@" --falcon-ca-file "$BEACON_FALCON_CA_FILE"
+fi
+
exec "$BEACON_BIN" "$@"
diff --git a/packaging/macos/pkgbuild.md b/packaging/macos/pkgbuild.md
index 8eb2730f..cefc8d06 100644
--- a/packaging/macos/pkgbuild.md
+++ b/packaging/macos/pkgbuild.md
@@ -130,6 +130,20 @@ local OpenTelemetry settings.
For repair workflows, pass Splunk settings with `BEACON_SPLUNK_*` environment
variables when possible so HEC tokens are not exposed as script parameters.
+Falcon LogScale HEC settings are environment-only and are not exposed as package
+positional parameters:
+
+```bash
+BEACON_FALCON_HEC_ENDPOINT="https://cloud.us.humio.com/api/v1/ingest/hec" \
+BEACON_FALCON_HEC_TOKEN="$LOGSCALE_INGEST_TOKEN" \
+BEACON_FALCON_SOURCE="beacon-endpoint-agent" \
+BEACON_FALCON_SOURCETYPE="json" \
+ /opt/beacon/scripts/install-endpoint.sh
+```
+
+Use `BEACON_FALCON_INDEX` only with LogScale organization or system
+multi-repository ingest tokens. Repository-scoped ingest tokens already choose
+the target repository.
Upload Extension Attributes from
`packaging/macos/jamf/extension-attributes` and build Smart Groups for missing,
@@ -158,6 +172,15 @@ BEACON_SPLUNK_INDEX="beacon" \
/opt/beacon/scripts/install-endpoint.sh
```
+Falcon LogScale HEC forwarding can be configured with:
+
+```bash
+BEACON_FALCON_HEC_ENDPOINT="https://cloud.us.humio.com/api/v1/ingest/hec" \
+BEACON_FALCON_HEC_TOKEN="$LOGSCALE_INGEST_TOKEN" \
+BEACON_FALCON_SOURCETYPE="json" \
+ /opt/beacon/scripts/install-endpoint.sh
+```
+
Release gates:
- `sh packaging/macos/test-endpoint-scripts.sh` passes
diff --git a/packaging/macos/test-endpoint-scripts.sh b/packaging/macos/test-endpoint-scripts.sh
index 264fc29c..2a9e899d 100644
--- a/packaging/macos/test-endpoint-scripts.sh
+++ b/packaging/macos/test-endpoint-scripts.sh
@@ -37,12 +37,19 @@ BEACON_SPLUNK_SOURCE="beacon-source" \
BEACON_SPLUNK_SOURCETYPE="beacon:sourcetype" \
BEACON_SPLUNK_INSECURE_SKIP_VERIFY="1" \
BEACON_SPLUNK_CA_FILE="/tmp/splunk-ca.pem" \
+BEACON_FALCON_HEC_ENDPOINT="https://cloud.us.humio.com/api/v1/ingest/hec" \
+BEACON_FALCON_HEC_TOKEN="falcon-token" \
+BEACON_FALCON_INDEX="beacon-repo" \
+BEACON_FALCON_SOURCE="falcon-source" \
+BEACON_FALCON_SOURCETYPE="json" \
+BEACON_FALCON_INSECURE_SKIP_VERIFY="1" \
+BEACON_FALCON_CA_FILE="/tmp/falcon-ca.pem" \
STUB_LOG="$STUB_LOG" \
"$INSTALL_SCRIPT"
INSTALL_ARGS="$(cat "$STUB_LOG")"
case "$INSTALL_ARGS" in
- "endpoint install --system --harness claude,codex,cursor --content-retention full --otlp-grpc-port 5317 --otlp-http-port 5318 --collector /tmp/beacon-otelcol --splunk-hec-endpoint https://splunk.example:8088/services/collector --splunk-hec-token hec-token --splunk-index beacon --splunk-source beacon-source --splunk-sourcetype beacon:sourcetype --splunk-insecure-skip-verify --splunk-ca-file /tmp/splunk-ca.pem") ;;
+ "endpoint install --system --harness claude,codex,cursor --content-retention full --otlp-grpc-port 5317 --otlp-http-port 5318 --collector /tmp/beacon-otelcol --splunk-hec-endpoint https://splunk.example:8088/services/collector --splunk-hec-token hec-token --splunk-index beacon --splunk-source beacon-source --splunk-sourcetype beacon:sourcetype --splunk-insecure-skip-verify --splunk-ca-file /tmp/splunk-ca.pem --falcon-hec-endpoint https://cloud.us.humio.com/api/v1/ingest/hec --falcon-hec-token falcon-token --falcon-index beacon-repo --falcon-source falcon-source --falcon-sourcetype json --falcon-insecure-skip-verify --falcon-ca-file /tmp/falcon-ca.pem") ;;
*)
echo "unexpected install args: $INSTALL_ARGS" >&2
exit 1
@@ -53,12 +60,14 @@ BEACON_BIN="$STUB_BIN" \
BEACON_COLLECTOR="/tmp/beacon-otelcol" \
BEACON_SPLUNK_HEC_ENDPOINT="https://splunk.example:8088/services/collector" \
BEACON_SPLUNK_HEC_TOKEN="hec-token" \
+BEACON_FALCON_HEC_ENDPOINT="https://cloud.us.humio.com/api/v1/ingest/hec" \
+BEACON_FALCON_HEC_TOKEN="falcon-token" \
STUB_LOG="$STUB_LOG" \
"$REPAIR_SCRIPT"
REPAIR_ARGS="$(cat "$STUB_LOG")"
case "$REPAIR_ARGS" in
- "endpoint repair --collector /tmp/beacon-otelcol --harness claude,codex --content-retention full --otlp-grpc-port 4317 --otlp-http-port 4318 --splunk-hec-endpoint https://splunk.example:8088/services/collector --splunk-hec-token hec-token") ;;
+ "endpoint repair --collector /tmp/beacon-otelcol --harness claude,codex --content-retention full --otlp-grpc-port 4317 --otlp-http-port 4318 --splunk-hec-endpoint https://splunk.example:8088/services/collector --splunk-hec-token hec-token --falcon-hec-endpoint https://cloud.us.humio.com/api/v1/ingest/hec --falcon-hec-token falcon-token") ;;
*)
echo "unexpected repair args: $REPAIR_ARGS" >&2
exit 1
@@ -171,12 +180,15 @@ BEACON_COLLECTOR="/tmp/beacon-otelcol" \
BEACON_SPLUNK_HEC_ENDPOINT="https://splunk.example:8088/services/collector" \
BEACON_SPLUNK_HEC_TOKEN="hec-token" \
BEACON_SPLUNK_INDEX="beacon" \
+BEACON_FALCON_HEC_ENDPOINT="https://cloud.us.humio.com/api/v1/ingest/hec" \
+BEACON_FALCON_HEC_TOKEN="falcon-token" \
+BEACON_FALCON_INDEX="beacon-repo" \
STUB_LOG="$STUB_LOG" \
"$FLEET_REPAIR_SCRIPT" "claude,cursor" "metadata" "8317" "8318"
REPAIR_ARGS="$(cat "$STUB_LOG")"
case "$REPAIR_ARGS" in
- "endpoint repair --collector /tmp/beacon-otelcol --harness claude,cursor --content-retention metadata --otlp-grpc-port 8317 --otlp-http-port 8318 --splunk-hec-endpoint https://splunk.example:8088/services/collector --splunk-hec-token hec-token --splunk-index beacon") ;;
+ "endpoint repair --collector /tmp/beacon-otelcol --harness claude,cursor --content-retention metadata --otlp-grpc-port 8317 --otlp-http-port 8318 --splunk-hec-endpoint https://splunk.example:8088/services/collector --splunk-hec-token hec-token --splunk-index beacon --falcon-hec-endpoint https://cloud.us.humio.com/api/v1/ingest/hec --falcon-hec-token falcon-token --falcon-index beacon-repo") ;;
*)
echo "unexpected Fleet positional repair args: $REPAIR_ARGS" >&2
exit 1