The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
Forward OTLP to a second backend, and a Kandji guide for it
Claudefd500a5881d8
diff --git a/CLAUDE.md b/CLAUDE.mdindex 20d4b920..7f2ce7ee 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -65,6 +65,7 @@ Supported runtime surfaces today:- Runtimes that ride shared hook/OTLP paths without a special contract worth expanding here include Antigravity CLI, Devin CLI, Devin Desktop, Factory Droid, Gemini CLI, Grok Build, Hermes Agent, Qwen Code, and VS Code. Installed hook/endpoint support is governed by `cli/beacon/cmd/endpoint_targets.go` plus the install/status switches in `cli/beacon/cmd/endpoint_hooks.go`; discovery rows live in `cli/beacon/internal/endpoint/harness`.- Browser chat telemetry through an optional MV3 extension (`browser-extension/`; Chrome, with a beta Firefox build) covering claude.ai and chatgpt.com. A main-world interceptor tees the streamed response, a per-site adapter parses it into a normalized turn, and the service worker POSTs OTLP GenAI logs to the local collector on `127.0.0.1:4318`; the extension never writes files and never contacts a remote endpoint. `harness.name` resolves to `claude_web` or `chatgpt_web` (already handled by `NormalizeHarnessName` in `pkg/asymptoteobserve/harness.go`, where the browser cases must stay above the generic `claude` rule) and `harness.collection_method` is `otlp`. The one build serves every Chromium browser; each event names the browser it came from in the typed `user_agent.name`/`user_agent.version` fields (OTel semconv, promoted by the exporter so Metadata-only forwarding keeps them), resolved in `browser-extension/src/shared/browser-identity.ts` from UA Client Hints brands, with a UA-string fallback that also names Firefox. Scope is deliberately narrow: only those origins' chat streams, never other tabs or general browsing. Retention defaults to `full`, so prompt and response text is retained by default; this is documented rather than defaulted down, because browser chat telemetry without content has no investigative value. Treat the adapters as experimental, since both sites' stream formats are private and undocumented. Per-browser differences live only in `browser-extension/tools/targets.mjs` (one entry per target, deriving its manifest from `src/manifest.json`; Chrome ships that file verbatim to `dist/`, Firefox gets `dist-firefox/`), and every extension API call goes through the `src/shared/browser.ts` shim (a unit test fails on direct `chrome.*` use). The Firefox Gecko ID `[email protected]` is pinned and must never change.- `beaconjson` OpenTelemetry Collector exporter that converts OTLP logs, traces, metrics, and resource attributes into Beacon endpoint JSONL.+- OTLP forward (`beacon endpoint install|repair --otlp-forward-endpoint`, `--otlp-forward-protocol grpc|http/protobuf`, repeatable `--otlp-forward-header`, `--no-otlp-forward`; `config.json` `destinations.otlp_forward`): for machines whose runtimes already exported OTLP to another backend before Beacon pointed them at its collector. The collector renders an `otlp/forward` or `otlphttp/forward` exporter (both in `collector-builder/builder.yaml`) on `logs/forward`, `traces/forward` and `metrics/forward` pipelines fed by the same receiver with only `memory_limiter` and `batch`, so the backend gets exactly what the runtimes sent and Beacon's processors never touch it. It is a customer-chosen destination like the HEC exporters, not a Beacon network channel, and hooks never use it. Install and repair carry it over (`buildConfig`) until `--no-otlp-forward` removes it; header values make the configs root-only and are shown by name only in status, doctor and `config show`. Guide: `docs/guides/kandji-otlp-forward-mdm.mdx`.- Endpoint inventory (`inventory.heartbeat` / `inventory.snapshot` in `inventory_state.jsonl`) is written by a scheduled job, `com.beacon.endpoint.inventory` (`service.InventoryManager`, user LaunchAgent or system LaunchDaemon, `beacon-inventory.timer` on systemd), every six hours and once at load, on by default and reconciled by `lifecycle.ReconcileInventoryJob` on every install, repair and package upgrade (`beacon endpoint inventory install-daemon`). Agent hooks do not trigger inventory any more; the hook binary's `--cli` flag and `inventory-heartbeat` subcommand survive only as no-ops for hook commands written by older versions, and `beacon endpoint inventory heartbeat --trigger hook` is likewise retired. A system-mode run inventories the active console user's home and still writes the liveness heartbeat when nobody is logged in; the scheduled scan has no working directory, so project-scoped config is only in `beacon endpoint inventory`.- Beacon Cloud forwarding, the one Beacon-hosted network channel for endpoint telemetry: user-mode `beacon endpoint connect` authorizes device enrollment with the signed-in CLI account; system mode uses browser PKCE at `/cli/enroll`. Both store only the per-device key in `<BaseDir>/asymptote/vector-secrets.json` (0600, 0700 dir), render the selected privacy mode into `vector.toml` (re-rendered in place by install, repair and package upgrades, see above), validate it, and run Vector as `com.beacon.endpoint.asymptote-forwarder` / `beacon-asymptote-forwarder.service` through `service.ForwarderManager` (refused in supervised mode). `enrollment.json` and `config.json`'s `managed_ingest` block carry only non-secret identity and privacy mode; `beacon endpoint status` reports forwarder state and a live credential check (`GET /v1/ingest/health`, 3 s timeout); `disconnect` and `uninstall` remove the forwarder and credentials but never revoke server-side.- Asymptote Observe TypeScript SDK instrumentation for cloud applications, starting from OpenTelemetry/OpenLLMetry patterns and `observe()` wrappers.diff --git a/cli/beacon/cmd/endpoint.go b/cli/beacon/cmd/endpoint.goindex 10ac1e67..d3db592c 100644--- a/cli/beacon/cmd/endpoint.go+++ b/cli/beacon/cmd/endpoint.go@@ -74,6 +74,13 @@ var endpointOpts struct {falconSourcetype stringfalconInsecureSkipVerify boolfalconCAFile string+ otlpForwardEndpoint string+ otlpForwardProtocol string+ otlpForwardHeaders []string+ otlpForwardInsecure bool+ otlpForwardSkipVerify bool+ otlpForwardCAFile string+ noOTLPForward booldashboardAddr stringdashboardOpen boolincludeEventSummaries bool@@ -449,6 +456,7 @@ func init() {endpointInstallCmd.Flags().StringVar(&endpointOpts.logAccess, "log-access", "", logAccessUsage)registerSplunkFlags(endpointInstallCmd)registerFalconFlags(endpointInstallCmd)+ registerOTLPForwardFlags(endpointInstallCmd)endpointRepairCmd.Flags().StringVar(&endpointOpts.harnesses, "harness", endpointHarnessAuto, "Harnesses to configure: auto (detected runtimes), all, or a comma-separated list")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")@@ -466,6 +474,7 @@ func init() {endpointRepairCmd.Flags().StringVar(&endpointOpts.logAccess, "log-access", "", logAccessUsage)registerSplunkFlags(endpointRepairCmd)registerFalconFlags(endpointRepairCmd)+ registerOTLPForwardFlags(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 the system collector service")endpointDashboardCmd.Flags().StringVar(&endpointOpts.logPath, "log-path", "", "Runtime JSONL log path")@@ -785,6 +794,58 @@ func registerFalconFlags(cmd *cobra.Command) {cmd.Flags().StringVar(&endpointOpts.falconCAFile, "falcon-ca-file", "", "Optional CA certificate path for Falcon LogScale HEC TLS verification")}+func registerOTLPForwardFlags(cmd *cobra.Command) {+ cmd.Flags().StringVar(&endpointOpts.otlpForwardEndpoint, "otlp-forward-endpoint", "", "Also forward the OTLP the local collector receives, unchanged, to this OTLP endpoint (host:port or URL for grpc, base URL for http/protobuf)")+ cmd.Flags().StringVar(&endpointOpts.otlpForwardProtocol, "otlp-forward-protocol", endpointconfig.OTLPForwardProtocolGRPC, "OTLP forward protocol: grpc or http/protobuf")+ cmd.Flags().StringArrayVar(&endpointOpts.otlpForwardHeaders, "otlp-forward-header", nil, "Header sent with every OTLP forward export, as name=value (repeatable)")+ cmd.Flags().BoolVar(&endpointOpts.otlpForwardInsecure, "otlp-forward-insecure", false, "Send the OTLP forward without TLS (gRPC plaintext)")+ cmd.Flags().BoolVar(&endpointOpts.otlpForwardSkipVerify, "otlp-forward-insecure-skip-verify", false, "Skip TLS certificate verification for the OTLP forward")+ cmd.Flags().StringVar(&endpointOpts.otlpForwardCAFile, "otlp-forward-ca-file", "", "Optional CA certificate path for OTLP forward TLS verification")+ cmd.Flags().BoolVar(&endpointOpts.noOTLPForward, "no-otlp-forward", false, "Remove a configured OTLP forward")+}++// otlpForwardOptions returns nil when no OTLP forward flag was given, so install and repair keep+// what the existing config has; --no-otlp-forward returns an empty forward, which removes it.+func otlpForwardOptions() (*endpointconfig.OTLPForward, error) {+ if endpointOpts.noOTLPForward {+ if endpointOpts.otlpForwardEndpoint != "" {+ return nil, fmt.Errorf("--no-otlp-forward cannot be combined with --otlp-forward-endpoint")+ }+ return &endpointconfig.OTLPForward{}, nil+ }+ if endpointOpts.otlpForwardEndpoint == "" &&+ len(endpointOpts.otlpForwardHeaders) == 0 &&+ (endpointOpts.otlpForwardProtocol == "" || endpointOpts.otlpForwardProtocol == endpointconfig.OTLPForwardProtocolGRPC) &&+ !endpointOpts.otlpForwardInsecure &&+ !endpointOpts.otlpForwardSkipVerify &&+ endpointOpts.otlpForwardCAFile == "" {+ return nil, nil+ }+ if strings.TrimSpace(endpointOpts.otlpForwardEndpoint) == "" {+ return nil, fmt.Errorf("--otlp-forward-endpoint is required with the other --otlp-forward flags")+ }+ headers := map[string]string{}+ for _, header := range endpointOpts.otlpForwardHeaders {+ name, value, ok := strings.Cut(header, "=")+ name = strings.TrimSpace(name)+ if !ok || name == "" {+ return nil, fmt.Errorf("--otlp-forward-header %q must be name=value", header)+ }+ headers[name] = value+ }+ if len(headers) == 0 {+ headers = nil+ }+ return &endpointconfig.OTLPForward{+ Endpoint: endpointOpts.otlpForwardEndpoint,+ Protocol: endpointOpts.otlpForwardProtocol,+ Headers: headers,+ Insecure: endpointOpts.otlpForwardInsecure,+ InsecureSkipVerify: endpointOpts.otlpForwardSkipVerify,+ CAFile: endpointOpts.otlpForwardCAFile,+ }, nil+}+func splunkHECOptions() *endpointconfig.SplunkHEC {if endpointOpts.splunkHECEndpoint == "" &&endpointOpts.splunkHECToken == "" &&diff --git a/cli/beacon/cmd/endpoint_cli_regression_test.go b/cli/beacon/cmd/endpoint_cli_regression_test.goindex 0ac34a74..2372fcbf 100644--- a/cli/beacon/cmd/endpoint_cli_regression_test.go+++ b/cli/beacon/cmd/endpoint_cli_regression_test.go@@ -28,7 +28,12 @@ func runBeaconCLI(t *testing.T, args ...string) (string, error) {}reset := func(c *cobra.Command) {c.Flags().VisitAll(func(f *pflag.Flag) {- _ = f.Value.Set(f.DefValue)+ // Set appends to a slice flag, and its DefValue "[]" would become one element.+ if slice, ok := f.Value.(pflag.SliceValue); ok {+ _ = slice.Replace(nil)+ } else {+ _ = f.Value.Set(f.DefValue)+ }f.Changed = false})}diff --git a/cli/beacon/cmd/endpoint_diagnostics.go b/cli/beacon/cmd/endpoint_diagnostics.goindex 1a8e385a..cce02bdc 100644--- a/cli/beacon/cmd/endpoint_diagnostics.go+++ b/cli/beacon/cmd/endpoint_diagnostics.go@@ -1828,6 +1828,15 @@ func redactConfig(cfg endpointconfig.Config) endpointconfig.Config {destinations.FalconHEC = &falconchanged = true}+ if cfg.Destinations.OTLPForward != nil && len(cfg.Destinations.OTLPForward.Headers) > 0 {+ forward := *cfg.Destinations.OTLPForward+ forward.Headers = make(map[string]string, len(cfg.Destinations.OTLPForward.Headers))+ for name := range cfg.Destinations.OTLPForward.Headers {+ forward.Headers[name] = "[REDACTED]"+ }+ destinations.OTLPForward = &forward+ changed = true+ }if changed {cfg.Destinations = &destinations}diff --git a/cli/beacon/cmd/endpoint_install.go b/cli/beacon/cmd/endpoint_install.goindex ddc14b02..1e4b2a54 100644--- a/cli/beacon/cmd/endpoint_install.go+++ b/cli/beacon/cmd/endpoint_install.go@@ -118,6 +118,8 @@ var (// install and repair (#640). So the list is always handed over non-nil.func endpointInstallOptions(selection endpointTargetSelection, serviceKind service.Kind) lifecycle.InstallOptions {harnesses := append([]string{}, selection.OTLP...)+ // Install and repair validate the forward flags before anything is written.+ otlpForward, _ := otlpForwardOptions()return lifecycle.InstallOptions{UserMode: endpointUserMode(),LogPath: endpointOpts.logPath,@@ -132,6 +134,7 @@ func endpointInstallOptions(selection endpointTargetSelection, serviceKind serviClaudeCaptureModelContext: endpointOpts.claudeCaptureModelContext,SplunkHEC: splunkHECOptions(),FalconHEC: falconHECOptions(),+ OTLPForward: otlpForward,ServiceKind: serviceKind,LogAccess: strings.ToLower(strings.TrimSpace(endpointOpts.logAccess)),}@@ -152,6 +155,9 @@ func runEndpointInstall(cmd *cobra.Command, args []string) error {if err != nil {return err}+ if _, err := otlpForwardOptions(); err != nil {+ return err+ }if endpointOpts.dryRun {return printPlannedActions(plannedInstallActions(false, serviceKind, selection.OTLP, selection.Hooks))}@@ -451,6 +457,9 @@ func runEndpointRepair(cmd *cobra.Command, args []string) error {if err != nil {return err}+ if _, err := otlpForwardOptions(); err != nil {+ return err+ }if endpointOpts.dryRun {return printPlannedActions(plannedInstallActions(true, serviceKind, selection.OTLP, selection.Hooks))}diff --git a/cli/beacon/cmd/endpoint_test.go b/cli/beacon/cmd/endpoint_test.goindex d73dad5d..5dc4dfb6 100644--- a/cli/beacon/cmd/endpoint_test.go+++ b/cli/beacon/cmd/endpoint_test.go@@ -440,6 +440,42 @@ func TestFalconHECOptionsDefaultIsNil(t *testing.T) {}}+func TestOTLPForwardOptions(t *testing.T) {+ old := endpointOpts+ t.Cleanup(func() { endpointOpts = old })++ endpointOpts.otlpForwardProtocol = endpointconfig.OTLPForwardProtocolGRPC+ if got, err := otlpForwardOptions(); err != nil || got != nil {+ t.Fatalf("otlpForwardOptions() with no flags = %#v, %v; want nil, nil so repair keeps the existing forward", got, err)+ }++ endpointOpts.otlpForwardEndpoint = "otel.tokenize.example:4317"+ endpointOpts.otlpForwardHeaders = []string{"authorization=Bearer a=b", "x-org=rho"}+ got, err := otlpForwardOptions()+ if err != nil {+ t.Fatal(err)+ }+ if got.Endpoint != "otel.tokenize.example:4317" || got.Headers["authorization"] != "Bearer a=b" || got.Headers["x-org"] != "rho" {+ t.Fatalf("otlpForwardOptions() = %#v", got)+ }++ endpointOpts.otlpForwardHeaders = []string{"no-equals"}+ if _, err := otlpForwardOptions(); err == nil {+ t.Fatal("expected an error for a header without =")+ }++ endpointOpts.otlpForwardHeaders = nil+ endpointOpts.noOTLPForward = true+ if _, err := otlpForwardOptions(); err == nil {+ t.Fatal("expected --no-otlp-forward with an endpoint to be refused")+ }+ endpointOpts.otlpForwardEndpoint = ""+ got, err = otlpForwardOptions()+ if err != nil || got == nil || got.Enabled || got.Endpoint != "" {+ t.Fatalf("--no-otlp-forward = %#v, %v; want an empty forward that removes it", got, err)+ }+}+func TestRepairCollectorServiceRollsBackWhenReadinessFails(t *testing.T) {oldOpts := endpointOptsoldLoadConfig := repairLoadEndpointConfigdiff --git a/cli/beacon/internal/endpoint/collector/collector.go b/cli/beacon/internal/endpoint/collector/collector.goindex 5005598a..2407d265 100644--- a/cli/beacon/internal/endpoint/collector/collector.go+++ b/cli/beacon/internal/endpoint/collector/collector.go@@ -7,6 +7,7 @@ import ("os""os/exec""path/filepath"+ "sort""strings""time"@@ -146,6 +147,16 @@ func ConfigYAML(cfg endpointconfig.Config) string {exporterNames = append(exporterNames, "falcon_hec")}exporters := "[" + strings.Join(exporterNames, ", ") + "]"+ forwardExporter, forwardName := otlpForwardYAML(cfg)+ // The OTLP forward has pipelines of its own, fed by the same receiver, so what it sends is what+ // the runtimes sent: none of Beacon's processors (claude_api_body, beacon_privacy) touch it. It+ // stands in for the runtime's own export to that backend, which Beacon's settings replaced.+ forwardPipelines := ""+ if forwardName != "" {+ for _, signal := range []string{"logs", "traces", "metrics"} {+ forwardPipelines += fmt.Sprintf(" %s/forward:\n receivers: [otlp]\n processors: [memory_limiter, batch]\n exporters: [%s]\n", signal, forwardName)+ }+ }// The direct HEC exporters send what they receive, so beacon_privacy redacts before the// fanout. beaconjson redacts in its own writer; with no HEC exporter the processor would only// repeat that on every record.@@ -228,7 +239,54 @@ service:receivers: [otlp]processors: [memory_limiter, %sbatch]exporters: %s-`, cfg.Collector.GRPCPort, grpcLimitYAML, cfg.Collector.HTTPPort, modelContextYAML, privacyYAML, cfg.LogPath, runtimeMetricsYAML+codexSpansYAML+modelContextYAML+splunkExporter+falconExporter, endpointconfig.HealthCheckPort(cfg.Collector), ingestYAML, extensions, privacyStep, exporters, privacyStep, exporters, privacyStep, exporters)+%s`, cfg.Collector.GRPCPort, grpcLimitYAML, cfg.Collector.HTTPPort, modelContextYAML, privacyYAML, cfg.LogPath, runtimeMetricsYAML+codexSpansYAML+modelContextYAML+splunkExporter+falconExporter+forwardExporter, endpointconfig.HealthCheckPort(cfg.Collector), ingestYAML, extensions, privacyStep, exporters, privacyStep, exporters, privacyStep, exporters, forwardPipelines)+}++// OTLPForwardExporters are the collector exporters an OTLP forward is rendered with, by protocol.+var OTLPForwardExporters = map[string]string{+ endpointconfig.OTLPForwardProtocolGRPC: "otlp",+ endpointconfig.OTLPForwardProtocolHTTP: "otlphttp",+}++// otlpForwardYAML renders the exporter for the configured OTLP forward and returns its name, or+// "" for both when forwarding is off.+func otlpForwardYAML(cfg endpointconfig.Config) (string, string) {+ if cfg.Destinations == nil || cfg.Destinations.OTLPForward == nil || !cfg.Destinations.OTLPForward.Enabled {+ return "", ""+ }+ forward := cfg.Destinations.OTLPForward+ kind := OTLPForwardExporters[forward.Protocol]+ if kind == "" {+ kind = OTLPForwardExporters[endpointconfig.OTLPForwardProtocolGRPC]+ }+ name := kind + "/forward"+ var b strings.Builder+ fmt.Fprintf(&b, " %s:\n", name)+ fmt.Fprintf(&b, " endpoint: %q\n", forward.Endpoint)+ if len(forward.Headers) > 0 {+ keys := make([]string, 0, len(forward.Headers))+ for key := range forward.Headers {+ keys = append(keys, key)+ }+ sort.Strings(keys)+ fmt.Fprintf(&b, " headers:\n")+ for _, key := range keys {+ fmt.Fprintf(&b, " %q: %q\n", key, forward.Headers[key])+ }+ }+ if forward.Insecure || forward.InsecureSkipVerify || forward.CAFile != "" {+ fmt.Fprintf(&b, " tls:\n")+ if forward.Insecure {+ fmt.Fprintf(&b, " insecure: true\n")+ }+ if forward.InsecureSkipVerify {+ fmt.Fprintf(&b, " insecure_skip_verify: true\n")+ }+ if forward.CAFile != "" {+ fmt.Fprintf(&b, " ca_file: %q\n", forward.CAFile)+ }+ }+ return b.String(), name}func splunkHECYAML(cfg endpointconfig.Config) string {diff --git a/cli/beacon/internal/endpoint/collector/collector_test.go b/cli/beacon/internal/endpoint/collector/collector_test.goindex a28b2094..3baa4ac5 100644--- a/cli/beacon/internal/endpoint/collector/collector_test.go+++ b/cli/beacon/internal/endpoint/collector/collector_test.go@@ -426,3 +426,50 @@ func withCollectorDiscovery(t *testing.T, lookup func(string) (string, error), cfunc execLookPath(file string) (string, error) {return exec.LookPath(file)}++func TestConfigYAMLForwardsOTLPUnchangedWhenConfigured(t *testing.T) {+ for _, tc := range []struct {+ protocol, endpoint, exporter string+ }{+ {endpointconfig.OTLPForwardProtocolGRPC, "otel.tokenize.example:4317", "otlp/forward"},+ {endpointconfig.OTLPForwardProtocolHTTP, "https://otel.tokenize.example", "otlphttp/forward"},+ } {+ t.Run(tc.protocol, func(t *testing.T) {+ cfg := testConfig(t)+ cfg.Destinations = &endpointconfig.Destinations{OTLPForward: &endpointconfig.OTLPForward{+ Endpoint: tc.endpoint,+ Protocol: tc.protocol,+ Headers: map[string]string{"x-b": "2", "authorization": "Bearer secret"},+ CAFile: "/tmp/ca.pem",+ }}+ endpointconfig.NormalizeDestinations(&cfg)++ yaml := ConfigYAML(cfg)++ for _, want := range []string{+ " " + tc.exporter + ":\n endpoint: \"" + tc.endpoint + "\"\n headers:\n \"authorization\": \"Bearer secret\"\n \"x-b\": \"2\"\n tls:\n ca_file: \"/tmp/ca.pem\"\n",+ " logs/forward:\n receivers: [otlp]\n processors: [memory_limiter, batch]\n exporters: [" + tc.exporter + "]\n",+ " traces/forward:\n",+ " metrics/forward:\n",+ // Beacon's own pipelines are unchanged: the forward is not a fanout from them.+ " processors: [memory_limiter, claude_api_body, batch]\n exporters: [beaconjson]\n",+ } {+ if !strings.Contains(yaml, want) {+ t.Fatalf("ConfigYAML missing %q:\n%s", want, yaml)+ }+ }+ if strings.Contains(yaml, "beacon_privacy") {+ t.Fatalf("an OTLP forward alone should not add beacon_privacy:\n%s", yaml)+ }+ })+ }+}++func TestConfigYAMLHasNoForwardWhenDisabled(t *testing.T) {+ cfg := testConfig(t)+ cfg.Destinations = &endpointconfig.Destinations{OTLPForward: &endpointconfig.OTLPForward{}}+ endpointconfig.NormalizeDestinations(&cfg)+ if yaml := ConfigYAML(cfg); strings.Contains(yaml, "/forward") {+ t.Fatalf("ConfigYAML has a forward with none configured:\n%s", yaml)+ }+}diff --git a/cli/beacon/internal/endpoint/collector/components.go b/cli/beacon/internal/endpoint/collector/components.goindex ab517068..14ca3d81 100644--- a/cli/beacon/internal/endpoint/collector/components.go+++ b/cli/beacon/internal/endpoint/collector/components.go@@ -33,6 +33,12 @@ var listComponents = func(ctx context.Context, binary string) ([]byte, error) {// extensions names the extensions the config will use beyond health_check -- beacon_ingest, in the// restricted log access mode -- which are refused the same way.func CheckComponents(binary string, extensions ...string) error {+ return CheckComponentsFor(binary, extensions, nil)+}++// CheckComponentsFor is CheckComponents with the exporters the config will use beyond Beacon's+// own -- the OTLP forward's -- refused the same way.+func CheckComponentsFor(binary string, extensions, exporters []string) error {ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)defer cancel()out, err := listComponents(ctx, binary)@@ -46,6 +52,9 @@ func CheckComponents(binary string, extensions ...string) error {Extensions []struct {Name string `yaml:"name"`} `yaml:"extensions"`+ Exporters []struct {+ Name string `yaml:"name"`+ } `yaml:"exporters"`}if yaml.Unmarshal(out, &listed) != nil || len(listed.Processors) == 0 {return nil@@ -70,5 +79,15 @@ func CheckComponents(binary string, extensions ...string) error {"use the %s from the same Beacon release, or pass --collector with one", binary, name, BinaryName)}}+ haveExporter := map[string]bool{}+ for _, exporter := range listed.Exporters {+ haveExporter[exporter.Name] = true+ }+ for _, name := range exporters {+ if !haveExporter[name] {+ return fmt.Errorf("collector %s is older than this beacon CLI: it has no %q exporter, which OTLP forwarding needs; "++ "use the %s from the same Beacon release, or pass --collector with one", binary, name, BinaryName)+ }+ }return nil}diff --git a/cli/beacon/internal/endpoint/config/config.go b/cli/beacon/internal/endpoint/config/config.goindex 86701d50..dee857b8 100644--- a/cli/beacon/internal/endpoint/config/config.go+++ b/cli/beacon/internal/endpoint/config/config.go@@ -179,6 +179,30 @@ type InventorySettings struct {type Destinations struct {SplunkHEC *SplunkHEC `json:"splunk_hec,omitempty"`FalconHEC *FalconHEC `json:"falcon_hec,omitempty"`+ // OTLPForward sends the OTLP the local collector receives on to a second OTLP endpoint,+ // unchanged, alongside Beacon's own pipeline. It exists for machines whose runtimes already+ // exported to another OTLP backend before Beacon took over their export settings.+ OTLPForward *OTLPForward `json:"otlp_forward,omitempty"`+}++// OTLP forwarding protocols.+const (+ OTLPForwardProtocolGRPC = "grpc"+ OTLPForwardProtocolHTTP = "http/protobuf"+)++type OTLPForward struct {+ Enabled bool `json:"enabled,omitempty"`+ // Endpoint is the receiving collector: host:port or a URL for gRPC, the base URL for HTTP+ // (the exporter appends /v1/logs, /v1/traces and /v1/metrics).+ Endpoint string `json:"endpoint,omitempty"`+ // Protocol is "grpc" (the default) or "http/protobuf".+ Protocol string `json:"protocol,omitempty"`+ // Headers are sent with every export, typically an authorization header the backend issued.+ Headers map[string]string `json:"headers,omitempty"`+ Insecure bool `json:"insecure,omitempty"`+ InsecureSkipVerify bool `json:"insecure_skip_verify,omitempty"`+ CAFile string `json:"ca_file,omitempty"`}type SplunkHEC struct {@@ -413,6 +437,20 @@ func NormalizeDestinations(cfg *Config) {}}}+ if forward := cfg.Destinations.OTLPForward; forward != nil {+ forward.Endpoint = strings.TrimSpace(forward.Endpoint)+ forward.Protocol = strings.ToLower(strings.TrimSpace(forward.Protocol))+ switch forward.Protocol {+ case "http", "http/protobuf", "otlphttp":+ forward.Protocol = OTLPForwardProtocolHTTP+ }+ if forward.Endpoint != "" {+ forward.Enabled = true+ }+ if forward.Enabled && forward.Protocol == "" {+ forward.Protocol = OTLPForwardProtocolGRPC+ }+ }if falcon := cfg.Destinations.FalconHEC; falcon != nil {if falcon.Endpoint != "" || falcon.Token != "" {falcon.Enabled = true@@ -432,6 +470,35 @@ func ValidateDestinations(destinations *Destinations) error {if destinations == nil {return nil}+ if forward := destinations.OTLPForward; forward != nil {+ configured := forward.Enabled ||+ forward.Endpoint != "" ||+ len(forward.Headers) > 0 ||+ forward.Insecure ||+ forward.InsecureSkipVerify ||+ forward.CAFile != ""+ if configured {+ if strings.TrimSpace(forward.Endpoint) == "" {+ return fmt.Errorf("OTLP forward endpoint is required when OTLP forwarding is configured")+ }+ switch forward.Protocol {+ case "", OTLPForwardProtocolGRPC, OTLPForwardProtocolHTTP:+ default:+ return fmt.Errorf("unsupported OTLP forward protocol %q: use %q or %q", forward.Protocol, OTLPForwardProtocolGRPC, OTLPForwardProtocolHTTP)+ }+ if forward.Protocol == OTLPForwardProtocolHTTP && !strings.HasPrefix(forward.Endpoint, "https://") && !strings.HasPrefix(forward.Endpoint, "http://") {+ return fmt.Errorf("OTLP forward endpoint %q must be an http:// or https:// URL for the %s protocol", forward.Endpoint, OTLPForwardProtocolHTTP)+ }+ for name, value := range forward.Headers {+ if strings.TrimSpace(name) == "" || strings.ContainsAny(name, ":\r\n") {+ return fmt.Errorf("invalid OTLP forward header name %q", name)+ }+ if strings.ContainsAny(value, "\r\n") {+ return fmt.Errorf("OTLP forward header %q has a line break in its value", name)+ }+ }+ }+ }if destinations.SplunkHEC != nil {splunk := destinations.SplunkHECconfigured := splunk.Enabled ||@@ -476,5 +543,6 @@ func ValidateDestinations(destinations *Destinations) error {func HasSecretDestinations(cfg Config) bool {return cfg.Destinations != nil &&((cfg.Destinations.SplunkHEC != nil && cfg.Destinations.SplunkHEC.Token != "") ||- (cfg.Destinations.FalconHEC != nil && cfg.Destinations.FalconHEC.Token != ""))+ (cfg.Destinations.FalconHEC != nil && cfg.Destinations.FalconHEC.Token != "") ||+ (cfg.Destinations.OTLPForward != nil && len(cfg.Destinations.OTLPForward.Headers) > 0))}diff --git a/cli/beacon/internal/endpoint/config/config_test.go b/cli/beacon/internal/endpoint/config/config_test.goindex 63e0b413..b9818545 100644--- a/cli/beacon/internal/endpoint/config/config_test.go+++ b/cli/beacon/internal/endpoint/config/config_test.go@@ -252,3 +252,52 @@ func TestLoadRejectsCorruptJSON(t *testing.T) {t.Fatal("expected corrupt JSON error")}}++func TestSaveLoadOTLPForwardRoundTripAndPrivatePermissions(t *testing.T) {+ testenv.RequirePOSIXFileModes(t)+ home := t.TempDir()+ testenv.SetHome(t, home)+ cfg := Default(true, filepath.Join(home, "logs", "runtime.jsonl"))+ cfg.Destinations = &Destinations{OTLPForward: &OTLPForward{+ Endpoint: " https://otel.tokenize.example ",+ Protocol: "http",+ Headers: map[string]string{"authorization": "Bearer secret"},+ }}++ 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)+ }+ forward := loaded.Destinations.OTLPForward+ if !forward.Enabled || forward.Endpoint != "https://otel.tokenize.example" || forward.Protocol != OTLPForwardProtocolHTTP || forward.Headers["authorization"] != "Bearer secret" {+ t.Fatalf("OTLP forward did not round-trip: %#v", forward)+ }+}++func TestValidateDestinationsRejectsBadOTLPForward(t *testing.T) {+ for name, forward := range map[string]OTLPForward{+ "no endpoint": {Headers: map[string]string{"a": "b"}},+ "unknown protocol": {Endpoint: "otel.example:4317", Protocol: "udp"},+ "http without a URL": {Endpoint: "otel.example:4318", Protocol: OTLPForwardProtocolHTTP},+ "header name colon": {Endpoint: "otel.example:4317", Headers: map[string]string{"a:b": "c"}},+ "header value break": {Endpoint: "otel.example:4317", Headers: map[string]string{"a": "b\r\nx: y"}},+ } {+ t.Run(name, func(t *testing.T) {+ forward := forward+ if err := ValidateDestinations(&Destinations{OTLPForward: &forward}); err == nil {+ t.Fatal("expected an error")+ }+ })+ }+}diff --git a/cli/beacon/internal/endpoint/lifecycle/destination_status_otlp_test.go b/cli/beacon/internal/endpoint/lifecycle/destination_status_otlp_test.gonew file mode 100644index 00000000..f4a84308--- /dev/null+++ b/cli/beacon/internal/endpoint/lifecycle/destination_status_otlp_test.go@@ -0,0 +1,55 @@+package lifecycle++import (+ "encoding/json"+ "strings"+ "testing"++ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"+)++// The Kandji guide (docs/guides/kandji-otlp-forward-mdm.mdx) audits the forward by grepping+// `beacon endpoint status --json` for this text, so its shape is pinned here.+func TestDestinationStatusReportsOTLPForwardWithoutHeaderValues(t *testing.T) {+ cfg := endpointconfig.Config{Destinations: &endpointconfig.Destinations{OTLPForward: &endpointconfig.OTLPForward{+ Enabled: true,+ Endpoint: "otel.backend.example:4317",+ Protocol: endpointconfig.OTLPForwardProtocolGRPC,+ Headers: map[string]string{"authorization": "Bearer secret"},+ }}}+ data, err := json.Marshal(destinationStatus(cfg))+ if err != nil {+ t.Fatal(err)+ }+ got := string(data)+ if !strings.Contains(got, `"otlp_forward":{"configured":true,"endpoint":"otel.backend.example:4317","protocol":"grpc","headers":["authorization"]}`) {+ t.Fatalf("destination status = %s", got)+ }+ if strings.Contains(got, "secret") {+ t.Fatalf("destination status leaks a header value: %s", got)+ }+}++// A package upgrade re-runs install and repair re-runs it after a teardown; both rebuild+// config.json from defaults. The OTLP forward is what keeps another backend fed, so it is+// carried over, and only --no-otlp-forward (an empty forward) removes it.+func TestBuildConfigKeepsOTLPForwardUntilRemoved(t *testing.T) {+ testenv.SetHome(t, t.TempDir())+ writeInventoryConfig(t, true, `{"user_mode":true,"log_path":"/tmp/runtime.jsonl","destinations":{"otlp_forward":{"enabled":true,"endpoint":"otel.backend.example:4317","protocol":"grpc","headers":{"authorization":"Bearer secret"}}}}`)++ cfg := buildConfig(InstallOptions{UserMode: true})+ if cfg.Destinations == nil || cfg.Destinations.OTLPForward == nil || cfg.Destinations.OTLPForward.Endpoint != "otel.backend.example:4317" || cfg.Destinations.OTLPForward.Headers["authorization"] != "Bearer secret" {+ t.Fatalf("buildConfig dropped the OTLP forward: %+v", cfg.Destinations)+ }++ cfg = buildConfig(InstallOptions{UserMode: true, OTLPForward: &endpointconfig.OTLPForward{}})+ if cfg.Destinations != nil && cfg.Destinations.OTLPForward != nil {+ t.Fatalf("an empty OTLPForward should remove it: %+v", cfg.Destinations.OTLPForward)+ }++ cfg = buildConfig(InstallOptions{UserMode: true, OTLPForward: &endpointconfig.OTLPForward{Endpoint: "https://other.example", Protocol: "http/protobuf"}})+ if forward := cfg.Destinations.OTLPForward; forward == nil || forward.Endpoint != "https://other.example" || !forward.Enabled {+ t.Fatalf("a new OTLPForward should replace it: %+v", forward)+ }+}diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle.goindex 9772c465..0bfec92b 100644--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go@@ -5,6 +5,7 @@ import ("fmt""os""path/filepath"+ "sort""strings""time"@@ -318,6 +319,9 @@ type InstallOptions struct {ClaudeCaptureModelContext boolSplunkHEC *endpointconfig.SplunkHECFalconHEC *endpointconfig.FalconHEC+ // OTLPForward replaces the configured OTLP forward; nil keeps what the existing config has,+ // so repair and package upgrades carry it.+ OTLPForward *endpointconfig.OTLPForward// ServiceKind selects the service manager. Empty auto-detects: launchd on macOS,// systemd when it is PID 1, otherwise a supervised child process.ServiceKind service.Kind@@ -396,6 +400,15 @@ type Status struct {type DestinationStatus struct {SplunkHEC ConfiguredStatus `json:"splunk_hec"`FalconHEC ConfiguredStatus `json:"falcon_hec"`+ // OTLPForward reports the endpoint and protocol only; header values can be credentials.+ OTLPForward OTLPForwardStatus `json:"otlp_forward"`+}++type OTLPForwardStatus struct {+ Configured bool `json:"configured"`+ Endpoint string `json:"endpoint,omitempty"`+ Protocol string `json:"protocol,omitempty"`+ Headers []string `json:"headers,omitempty"`}type ConfiguredStatus struct {@@ -556,7 +569,11 @@ func Install(opts InstallOptions) (InstallResult, error) {if cfg.RestrictedLogAccess() {extensions = append(extensions, endpointcollector.IngestExtension)}- if err := endpointcollector.CheckComponents(collectorBinary, extensions...); err != nil {+ var exporters []string+ if cfg.Destinations != nil && cfg.Destinations.OTLPForward != nil && cfg.Destinations.OTLPForward.Enabled {+ exporters = append(exporters, endpointcollector.OTLPForwardExporters[cfg.Destinations.OTLPForward.Protocol])+ }+ if err := endpointcollector.CheckComponentsFor(collectorBinary, extensions, exporters); err != nil {return InstallResult{}, err}@@ -1104,6 +1121,12 @@ func buildConfig(opts InstallOptions) endpointconfig.Config {if existing.Inventory != nil {cfg.Inventory = existing.Inventory}+ // The OTLP forward replaces the export a runtime had to another backend before Beacon+ // pointed it at the collector. An upgrade or repair that dropped it would silently cut that+ // backend off, so it is kept until --no-otlp-forward removes it.+ if existing.Destinations != nil && existing.Destinations.OTLPForward != nil {+ cfg.Destinations = &endpointconfig.Destinations{OTLPForward: existing.Destinations.OTLPForward}+ }// The log access mode is an operator's security choice; a repair or upgrade that dropped// it would silently make a restricted log world-writable again.cfg.LogAccess = existing.LogAccess@@ -1149,6 +1172,16 @@ func buildConfig(opts InstallOptions) endpointconfig.Config {}cfg.Destinations.FalconHEC = opts.FalconHEC}+ if opts.OTLPForward != nil {+ if cfg.Destinations == nil {+ cfg.Destinations = &endpointconfig.Destinations{}+ }+ if opts.OTLPForward.Endpoint == "" && !opts.OTLPForward.Enabled {+ cfg.Destinations.OTLPForward = nil+ } else {+ cfg.Destinations.OTLPForward = opts.OTLPForward+ }+ }if cfg.Destinations != nil {endpointconfig.NormalizeDestinations(&cfg)}@@ -1185,6 +1218,10 @@ func installDestination(cfg endpointconfig.Config) *schema.DestinationInfo {destination.Type += ",falcon_hec"destination.Mode += ",hec"}+ if cfg.Destinations != nil && cfg.Destinations.OTLPForward != nil && cfg.Destinations.OTLPForward.Enabled {+ destination.Type += ",otlp_forward"+ destination.Mode += ",otlp"+ }return destination}@@ -1213,6 +1250,14 @@ func destinationStatus(cfg endpointconfig.Config) DestinationStatus {Sourcetype: falcon.Sourcetype,}}+ if forward := cfg.Destinations.OTLPForward; forward != nil && forward.Enabled {+ headers := make([]string, 0, len(forward.Headers))+ for name := range forward.Headers {+ headers = append(headers, name)+ }+ sort.Strings(headers)+ status.OTLPForward = OTLPForwardStatus{Configured: true, Endpoint: forward.Endpoint, Protocol: forward.Protocol, Headers: headers}+ }return status}diff --git a/collector-builder/builder.yaml b/collector-builder/builder.yamlindex f93c2835..7c673421 100644--- a/collector-builder/builder.yaml+++ b/collector-builder/builder.yaml@@ -23,6 +23,9 @@ exporters:import: github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter/falconhecexporterpath: ./exporter/beaconjsonexporter- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/exporter/splunkhecexporter v0.121.0+ # OTLP forwarding (`beacon endpoint install --otlp-forward-endpoint`) to a second OTLP backend.+ - gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.121.0+ - gomod: go.opentelemetry.io/collector/exporter/otlphttpexporter v0.121.0extensions:- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/healthcheckextension v0.121.0diff --git a/docs/changelog/cli.mdx b/docs/changelog/cli.mdxindex b20e9805..e8ed9f77 100644--- a/docs/changelog/cli.mdx+++ b/docs/changelog/cli.mdx@@ -11,6 +11,7 @@ Stay up to date with the latest changes to the Agent Beacon CLI.## Unreleased+- **Forward OTLP to a second backend** · Macs that already sent Claude Code or Codex OpenTelemetry to another backend lost that export when Beacon pointed the runtimes at its collector. `beacon endpoint install|repair --otlp-forward-endpoint <endpoint>` (with `--otlp-forward-protocol grpc|http/protobuf` and repeatable `--otlp-forward-header name=value`) now has the collector send everything it receives, unchanged, to that endpoint as well, through pipelines of its own so Beacon's processing does not touch it. Repair and package upgrades keep it; `--no-otlp-forward` removes it. See [Kandji with an existing OTLP backend](/guides/kandji-otlp-forward-mdm).- **Inherited per-signal OTLP settings no longer divert Claude telemetry** · An `OTEL_EXPORTER_OTLP_{LOGS,METRICS,TRACES}_ENDPOINT`, protocol or headers setting in the environment or Claude's settings sent Claude's telemetry past Beacon's collector, in `beacon ci` and with `beacon endpoint`, which still reported telemetry as enabled. Beacon now overrides them, and `beacon endpoint status` flags one that points elsewhere.- **`beacon git` links symlinks a session creates** · When a session's directory ran through a symlink, such as `/tmp` on macOS, a link the session created was resolved to its target: `ln -s ../shared/config.json cfg.json` linked nothing, and `ln -s a.txt alias.txt` was credited as `a.txt`. The link itself is now recorded.- **Local MCP server follows JSON-RPC more closely** · `beacon mcp serve` changed large numeric request ids (above 2^53, or forms like `1e3`) when echoing them, left out `id` on parse errors, and rejected MCP `ping`; ids are now returned exactly, errors carry `"id": null`, and `ping` is answered.diff --git a/docs/cli/endpoint-install.mdx b/docs/cli/endpoint-install.mdxindex 6bcfbb43..810e3c53 100644--- a/docs/cli/endpoint-install.mdx+++ b/docs/cli/endpoint-install.mdx@@ -52,6 +52,13 @@ The `claude` harness writes both Claude Code's OpenTelemetry settings and its us| `--falcon-sourcetype <type>` | Optional Falcon LogScale parser or sourcetype || `--falcon-insecure-skip-verify` | Skip Falcon LogScale HEC TLS certificate verification || `--falcon-ca-file <path>` | Optional CA certificate path for Falcon LogScale HEC TLS verification |+| `--otlp-forward-endpoint <endpoint>` | Also forward the OTLP the local collector receives, unchanged, to a second OTLP endpoint: `host:port` or a URL for gRPC, the base URL for HTTP. For runtimes that already exported to another backend before Beacon took over their OTLP settings. See [Kandji with an existing OTLP backend](/guides/kandji-otlp-forward-mdm). Omitted, install and repair keep the forward the endpoint already has |+| `--otlp-forward-protocol <protocol>` | `grpc` (default) or `http/protobuf` |+| `--otlp-forward-header <name=value>` | Header sent with every forwarded export, usually the backend's API key; repeatable. Makes the endpoint config root-only; status and doctor show header names only |+| `--otlp-forward-insecure` | Send the forward without TLS (plaintext gRPC) |+| `--otlp-forward-insecure-skip-verify` | Skip TLS certificate verification for the forward |+| `--otlp-forward-ca-file <path>` | Optional CA certificate path for the forward's TLS verification |+| `--no-otlp-forward` | Remove a configured OTLP forward || `--log-access <mode>` | System log access: `shared` (the default) or `restricted`. See [Restricted log access](#restricted-log-access). Omitted, an install keeps the mode the endpoint already has. System installs on macOS and Linux only || `--no-backfill` | Skip the [session backfill](#session-backfill). `BEACON_BACKFILL=0` does the same || `--connect` | After a successful install, attempt to connect this endpoint to Beacon Cloud ingest. User mode uses the signed-in CLI account; system mode opens browser approval. A connection failure does not roll back or fail the completed local install; verify with `beacon endpoint status --json` and retry with [`beacon endpoint connect`](/cli/endpoint-connect) |diff --git a/docs/cli/endpoint-repair.mdx b/docs/cli/endpoint-repair.mdxindex ad35a2cf..381de223 100644--- a/docs/cli/endpoint-repair.mdx+++ b/docs/cli/endpoint-repair.mdx@@ -50,6 +50,13 @@ On an endpoint connected to Beacon Cloud, repair leaves the forwarder service, t| `--falcon-sourcetype <type>` | Optional Falcon LogScale parser or sourcetype || `--falcon-insecure-skip-verify` | Skip Falcon LogScale HEC TLS certificate verification || `--falcon-ca-file <path>` | Optional CA certificate path for Falcon LogScale HEC TLS verification |+| `--otlp-forward-endpoint <endpoint>` | Also forward the OTLP the local collector receives, unchanged, to a second OTLP endpoint: `host:port` or a URL for gRPC, the base URL for HTTP. For runtimes that already exported to another backend before Beacon took over their OTLP settings. See [Kandji with an existing OTLP backend](/guides/kandji-otlp-forward-mdm). Omitted, install and repair keep the forward the endpoint already has |+| `--otlp-forward-protocol <protocol>` | `grpc` (default) or `http/protobuf` |+| `--otlp-forward-header <name=value>` | Header sent with every forwarded export, usually the backend's API key; repeatable. Makes the endpoint config root-only; status and doctor show header names only |+| `--otlp-forward-insecure` | Send the forward without TLS (plaintext gRPC) |+| `--otlp-forward-insecure-skip-verify` | Skip TLS certificate verification for the forward |+| `--otlp-forward-ca-file <path>` | Optional CA certificate path for the forward's TLS verification |+| `--no-otlp-forward` | Remove a configured OTLP forward |## Examplesdiff --git a/docs/docs.json b/docs/docs.jsonindex 8ab4ddab..6e8a4c98 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -561,6 +561,13 @@"pages": ["guides/fleet-s3-mdm"]+ },+ {+ "group": "Kandji",+ "expanded": true,+ "pages": [+ "guides/kandji-otlp-forward-mdm"+ ]}]}diff --git a/docs/guides/kandji-otlp-forward-mdm.mdx b/docs/guides/kandji-otlp-forward-mdm.mdxnew file mode 100644index 00000000..fe96108e--- /dev/null+++ b/docs/guides/kandji-otlp-forward-mdm.mdx@@ -0,0 +1,239 @@+---+title: "Claude Code and Codex with Kandji and an existing OTLP backend"+description: "Deploy Beacon with Kandji on Macs that already export Claude Code and Codex OpenTelemetry to another backend, and keep that backend fed through Beacon's OTLP forward"+---++## Overview++Use this runbook when your Macs already send Claude Code and Codex CLI OpenTelemetry (OTLP) to another backend, such as a token-usage or cost platform, and you are adding Beacon with Kandji.++Claude Code and Codex each export OTLP to one endpoint. Beacon needs that export to arrive at its local collector, so installing Beacon points both runtimes at `127.0.0.1:4317`, and the runtimes stop sending to the backend you already had. To keep that backend fed, Beacon's collector **forwards everything it receives, unchanged, to a second OTLP endpoint** alongside writing its own runtime log:++```mermaid+flowchart LR+ Claude[Claude Code] -->|OTLP| Collector["Beacon collector<br/>127.0.0.1:4317"]+ Codex[Codex CLI] -->|OTLP| Collector+ ClaudeHooks[Claude Code / Codex hooks] --> RuntimeLog["runtime.jsonl"]+ Collector -->|Beacon pipeline| RuntimeLog+ Collector -->|"OTLP forward (unchanged)"| Backend["Your existing OTLP backend"]+```++Kandji provides the deployment layer:++| Kandji item | Beacon use |+| --- | --- |+| Custom App (package) | Installs the signed Beacon package, which creates the system endpoint and points Claude Code and Codex at the local collector. |+| Custom App post-install script | Turns on the OTLP forward right after the package installs, so the existing backend misses nothing. |+| Custom Script (audit and remediation) | Re-applies the forward and the runtime settings if they drift, for example after a runtime update rewrites its config or a user logs in for the first time. |++<Info>+ The OTLP forward needs the first Beacon release after v1.3.51. An older package does not have the `--otlp-forward-*` flags, and its collector has no OTLP exporter.+</Info>++## What the existing backend receives++The forward has its own collector pipelines, fed by the same receiver as Beacon's. None of Beacon's processing (event normalization, API-body handling, secret redaction) is applied to it: the backend receives the OTLP logs, metrics and traces exactly as Claude Code and Codex sent them to Beacon. If the backend is unreachable, the forward retries and queues in memory on its own; Beacon's local capture is not held up.++What the runtimes send is set by Beacon's runtime settings, which can differ from the settings you rolled out for the backend. Check these with the backend's owner before rollout:++| Runtime | Beacon setting | Effect on the existing backend |+| --- | --- | --- |+| Claude Code | `OTEL_LOG_USER_PROMPTS=1`, `OTEL_LOG_TOOL_DETAILS=1` | The backend now receives prompt text and tool details (commands, file paths, MCP arguments) if it did not before. |+| Claude Code | `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta` | Metrics such as `claude_code.token.usage` and `claude_code.cost.usage` arrive as per-interval deltas. A backend that expects cumulative counters must accept delta temporality. |+| Claude Code | Logs, metrics and traces all go to the collector over gRPC | Per-signal endpoints and headers from your earlier rollout are overridden, so every signal reaches the backend through the forward. |+| Codex CLI | `[otel]` with a log exporter and a trace exporter, and no metrics exporter | The backend receives Codex logs and the turn traces that carry token usage, and no Codex metrics. |++## Prerequisites++- A signed and notarized `BeaconEndpointAgent-<version>-arm64.pkg`, from the first release after v1.3.51. The endpoint package is for Apple Silicon Macs.+- A pilot Kandji Blueprint, or an assignment rule on a library item, that targets a few Macs with Claude Code or Codex CLI installed.+- The OTLP settings your Macs use for the existing backend today:+ - **Endpoint**: for gRPC, `host:port` or a URL; for HTTP, the base URL without `/v1/logs`.+ - **Protocol**: `grpc` or `http/protobuf`.+ - **Headers**: usually an API key or authorization header, from `OTEL_EXPORTER_OTLP_HEADERS` in Claude Code's settings or `headers` in Codex's `[otel.exporter.*]` table.++<Warning>+ Kandji's documentation covers Custom Apps with pre- and post-install scripts and Custom Scripts with audit and remediation scripts. It does not document how long a Custom App's post-install script may run or whether a remediation script waits for a Custom App. Treat both as pilot acceptance checks in your tenant.+</Warning>++## Step 1: stop the old direct export from fighting Beacon++How you rolled out the existing backend decides what to change. Find the one that matches.++**Claude Code managed settings** (`/Library/Application Support/ClaudeCode/managed-settings.json`, delivered by a Kandji profile or script). Managed settings take precedence over the user's `~/.claude/settings.json`, where Beacon writes its endpoint, so Claude Code would keep exporting straight to the backend and Beacon would get no Claude OTLP. In the managed settings `env`:++- Set `OTEL_EXPORTER_OTLP_ENDPOINT` to `http://127.0.0.1:4317` and `OTEL_EXPORTER_OTLP_PROTOCOL` to `grpc`.+- Remove `OTEL_EXPORTER_OTLP_HEADERS`, every `OTEL_EXPORTER_OTLP_{LOGS,METRICS,TRACES}_ENDPOINT` and `_HEADERS`, and `BETA_TRACING_ENDPOINT`. The backend's credentials move to the forward in Step 3. Left in place, they would be sent to the local collector instead.++**Scripts or profiles that write `~/.claude/settings.json` or `~/.codex/config.toml`.** Beacon rewrites the OTLP settings in both files on every install, upgrade and repair, and replaces Codex's whole `[otel]` table. Retire or unscope the Kandji item that writes the backend's OTLP settings to those files; otherwise it and Beacon overwrite each other on every run.++## Step 2: add the Beacon package as a Custom App++In Kandji, go to **Library**, add a **Custom App**, and:++1. Name it `Beacon Endpoint Agent`.+2. Set the install type to **Package** and upload the Beacon `.pkg`.+3. Choose **Install once per device** (or self-service for the pilot).+4. Leave the pre-install script empty.+5. Paste the post-install script from Step 3.+6. Assign it to the pilot Blueprint.++The package postinstall installs Beacon under `/opt/beacon`, writes the system endpoint configuration, starts `com.beacon.endpoint.collector`, and points the logged-in user's Claude Code and Codex at the collector (`~/.claude/settings.json` and `~/.codex/config.toml`), with Beacon's Claude Code and Codex hooks.++## Step 3: turn on the OTLP forward++Use this script as the Custom App's **post-install script**. Replace the three values at the top with the endpoint, protocol and headers from the prerequisites:++```bash title="Beacon - OTLP forward (post-install script)"+#!/bin/bash+set -euo pipefail++# The existing backend's OTLP settings.+OTLP_FORWARD_ENDPOINT="https://otlp.backend.example:4317"+OTLP_FORWARD_PROTOCOL="grpc" # or http/protobuf+OTLP_FORWARD_HEADERS=( # one name=value per entry; may be empty+ "authorization=Bearer <backend-api-key>"+)++BEACON=/opt/beacon/bin/beacon++args=(endpoint repair --system+ --collector /opt/beacon/bin/beacon-otelcol+ --harness claude,codex+ --otlp-forward-endpoint "$OTLP_FORWARD_ENDPOINT"+ --otlp-forward-protocol "$OTLP_FORWARD_PROTOCOL")+for header in "${OTLP_FORWARD_HEADERS[@]}"; do+ args+=(--otlp-forward-header "$header")+done++"$BEACON" "${args[@]}"++# Point the logged-in user's Claude Code and Codex at the collector. This does nothing+# when nobody is logged in; the audit script in Step 4 catches that user later.+"$BEACON" endpoint user-config repair-installed --system --harness claude,codex++"$BEACON" endpoint status --system --json | /usr/bin/grep -q '"otlp_forward":{"configured":true' \+ || "$BEACON" endpoint status --system --json+```++`beacon endpoint repair` stores the forward in `/Library/Application Support/Beacon/Endpoint/config.json` and renders it into the collector config next to it. Both files become root-only (`0600`) when the forward has headers, because header values are usually credentials. Package upgrades and later repairs keep the forward; you do not pass the flags again. To remove it, run `beacon endpoint repair --system --no-otlp-forward`.++Flags you may also need:++| Flag | Use |+| --- | --- |+| `--otlp-forward-insecure` | The backend takes plaintext gRPC (a collector on your network, for example). |+| `--otlp-forward-ca-file <path>` | The backend's certificate is issued by a private CA. |+| `--otlp-forward-insecure-skip-verify` | Testing only. |++<Note>+ The script holds the backend's API key, and Kandji admins can read Custom App scripts. If that is not acceptable, deliver the key to the Mac another way (for example, a root-only file your secrets tooling writes) and read it into `OTLP_FORWARD_HEADERS` in the script. Beacon never prints header values: `beacon endpoint status` and `beacon endpoint doctor` list header names only.+</Note>++## Step 4: keep it applied with a Custom Script++Add a **Custom Script** library item, set it to **Run every 15 minutes** (or daily once the pilot is stable), and assign it to the same Blueprint.++**Audit script:** exits non-zero, which runs the remediation, when the forward is missing or the logged-in user's runtimes are not pointed at the collector:++```bash title="Beacon - OTLP forward (audit)"+#!/bin/bash+BEACON=/opt/beacon/bin/beacon+[ -x "$BEACON" ] || exit 0 # Beacon not installed yet; the Custom App handles it.++status="$("$BEACON" endpoint status --system --json 2>/dev/null)" || exit 1+echo "$status" | /usr/bin/grep -q '"otlp_forward":{"configured":true' || exit 1++console_user="$(/usr/bin/stat -f %Su /dev/console)"+case "$console_user" in root|loginwindow|_mbsetupuser|"") exit 0 ;; esac+home="$(/usr/bin/dscl . -read "/Users/$console_user" NFSHomeDirectory | /usr/bin/awk '{print $2}')"++if [ -d "$home/.claude" ]; then+ /usr/bin/grep -q '127.0.0.1:4317' "$home/.claude/settings.json" 2>/dev/null || exit 1+fi+if [ -d "$home/.codex" ]; then+ /usr/bin/grep -q '127.0.0.1:4317' "$home/.codex/config.toml" 2>/dev/null || exit 1+fi+exit 0+```++**Remediation script:** the same script as Step 3.++## Validate a pilot Mac++### 1. Collector and forward++```bash+sudo launchctl print system/com.beacon.endpoint.collector | grep -E 'state =|pid ='+sudo /opt/beacon/bin/beacon endpoint status --system --json | grep -o '"otlp_forward":{[^}]*}'+sudo grep -A3 -E '^ otlp(http)?/forward:' "/Library/Application Support/Beacon/Endpoint/otelcol.yaml"+```++Expect a running collector, `"configured": true` with your endpoint and protocol, and an `otlp/forward` (gRPC) or `otlphttp/forward` (HTTP) exporter in the collector config.++### 2. Runtime settings++As the logged-in user:++```bash+grep -n 'OTEL_EXPORTER_OTLP_ENDPOINT\|beacon-hooks' ~/.claude/settings.json+grep -n -A2 '^\[otel' ~/.codex/config.toml+```++Both should point at `127.0.0.1:4317`. If Claude Code has managed settings, check that `/Library/Application Support/ClaudeCode/managed-settings.json` points there too (Step 1).++### 3. Both destinations receive a session++Restart Claude Code and Codex so they read the new settings, then:++```bash+MARKER="beacon kandji fanout $(date +%s)"+claude -p "$MARKER"+codex exec "$MARKER"+sudo grep -c "$MARKER" /var/log/beacon-agent/runtime.jsonl+```++Beacon's runtime log should contain the marker from both runtimes. In the existing backend, confirm that the same sessions appear with token usage from both runtimes in the usual time window.++## Troubleshooting++### The existing backend stopped receiving data++1. Check the forward is configured (validation step 1). If not, run the Step 3 script.+2. Read the collector's log for export errors from the forward:++ ```bash+ sudo grep -i 'forward\|Exporting failed' /Library/Logs/Beacon/com.beacon.endpoint.collector.err | tail -n 20+ ```++ `Unauthenticated` or `401` means a wrong or missing header; `connection refused`, `deadline exceeded` or a TLS error means the endpoint, protocol, or `--otlp-forward-insecure`/`--otlp-forward-ca-file` is wrong. HTTP endpoints take the base URL; the exporter adds `/v1/logs`, `/v1/metrics` and `/v1/traces`.+3. Check that the runtimes still point at the collector (validation step 2). A runtime update or an old Kandji item can rewrite the settings; the Step 4 audit repairs them on its next run.++### `repair` rejects the forward flags++`unknown flag: --otlp-forward-endpoint` means the installed `beacon` predates OTLP forwarding, and `collector ... has no "otlp" exporter` means `beacon-otelcol` does (for example, an older one passed with `--collector`). Deploy the Beacon package from the first release after v1.3.51, then run the Step 3 script again.++### Beacon has no Claude Code OTLP events, but hooks work++Claude Code managed settings still point at the old backend. See Step 1.++### Codex metrics are missing in the backend++Beacon's Codex settings export logs and traces only. Codex token usage reaches the backend in the turn traces. If the backend can only read Codex metrics, contact Asymptote.++## Related++<Columns cols={2}>+ <Card title="beacon endpoint repair" icon="wrench" href="/cli/endpoint-repair">+ Every repair flag, including the OTLP forward.+ </Card>+ <Card title="MDM Deployment" icon="building-shield" href="/mdm">+ Package layout, deployment model and rollback for any MDM.+ </Card>+ <Card title="Claude Code" icon="terminal" href="/runtimes/claude-code">+ Claude Code endpoint telemetry coverage.+ </Card>+ <Card title="Codex CLI" icon="terminal" href="/runtimes/codex-cli">+ Codex CLI endpoint telemetry coverage.+ </Card>+</Columns>diff --git a/docs/log-forwarding/index.mdx b/docs/log-forwarding/index.mdxindex 205cf9f2..2e7c2847 100644--- a/docs/log-forwarding/index.mdx+++ b/docs/log-forwarding/index.mdx@@ -5,7 +5,7 @@ description: "Forward Beacon endpoint events from local JSONL into SIEMs, log ag## Forwarding overview-Beacon writes normalized [endpoint events](/concepts/core-concepts#endpoint-event) as JSONL. The active [runtime log](/concepts/core-concepts#runtime-jsonl-log) is the handoff point for local review, [customer-managed log pipelines](/concepts/core-concepts#customer-managed-forwarding), log aggregators, object storage exporters, and most SIEM content packs. Beacon can also enable optional collector exporters for [Splunk HTTP Event Collector (HEC)](/concepts/core-concepts#splunk-hec) and [CrowdStrike Falcon LogScale HEC](/concepts/core-concepts#falcon-logscale-hec) during endpoint install or repair.+Beacon writes normalized [endpoint events](/concepts/core-concepts#endpoint-event) as JSONL. The active [runtime log](/concepts/core-concepts#runtime-jsonl-log) is the handoff point for local review, [customer-managed log pipelines](/concepts/core-concepts#customer-managed-forwarding), log aggregators, object storage exporters, and most SIEM content packs. Beacon can also enable optional collector exporters for [Splunk HTTP Event Collector (HEC)](/concepts/core-concepts#splunk-hec) and [CrowdStrike Falcon LogScale HEC](/concepts/core-concepts#falcon-logscale-hec) during endpoint install or repair, and an [OTLP forward](/guides/kandji-otlp-forward-mdm) that passes the runtimes' OTLP, unchanged, on to a second OTLP backend.Use the subpages below by destination category. Beacon Cloud is the one path that sends events to a Beacon-run service; it is opt-in per device and revocable from the Beacon dashboard. SIEM pages are for destinations that become investigation or detection systems. Log aggregation pages are for customer-owned pipelines and observability stores that tail local JSONL. Object storage pages are for archival or data lake export. Local pages cover the default runtime log and dashboard source.diff --git a/docs/mdm/index.mdx b/docs/mdm/index.mdxindex e6f9e889..2f5aa35b 100644--- a/docs/mdm/index.mdx+++ b/docs/mdm/index.mdx@@ -1,11 +1,11 @@---title: "MDM Deployment"-description: "Plan managed macOS deployment of Beacon with Jamf Pro, Rippling, Fleet, or another MDM."+description: "Plan managed macOS deployment of Beacon with Jamf Pro, Rippling, Fleet, Kandji, or another MDM."---## Deployment overview-Beacon's macOS package is designed for security and IT rollout through MDM. A signed and notarized `.pkg` installs Beacon under `/opt/beacon`, creates system endpoint configuration, loads the local collector LaunchDaemon, and writes endpoint events to `/var/log/beacon-agent/runtime.jsonl`. Optional Splunk HEC or Falcon LogScale HEC settings add collector destinations while preserving the local runtime log.+Beacon's macOS package is designed for security and IT rollout through MDM. A signed and notarized `.pkg` installs Beacon under `/opt/beacon`, creates system endpoint configuration, loads the local collector LaunchDaemon, and writes endpoint events to `/var/log/beacon-agent/runtime.jsonl`. Optional Splunk HEC or Falcon LogScale HEC settings add collector destinations while preserving the local runtime log, and an optional OTLP forward keeps an existing OTLP backend fed after Beacon takes over the runtimes' OTLP export (see [Kandji with an existing OTLP backend](/guides/kandji-otlp-forward-mdm)).The package installs and inventories a local-only endpoint agent. Beacon does not require a hosted account, remote policy fetch, or MDM API credentials for normal collection. During package postinstall, Beacon tolerates a transient `launchctl bootstrap` failure when the LaunchDaemon is already registered and continues validation against the existing service registration. Endpoint package self-updates are available for Apple Silicon system package installs, but remain off by default; IT admins can opt into `check-only` monitoring or `auto` package updates during Jamf or Fleet rollout.