Skip to content

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

ci: add optional SIEM forwarding egress to ci exec

Claudea03a06097397
diff --git a/cli/beacon/README.md b/cli/beacon/README.md
index 0d8ed41b..eb983193 100644
--- a/cli/beacon/README.md
+++ b/cli/beacon/README.md
@@ -93,6 +93,11 @@ Validate an existing CI artifact explicitly:
--min-events 1
```
+Captured events carry the GitHub Actions run context (`run.repository`,
+`run.branch`, `run.run_id`, `run.run_attempt`, `run.job`, `run.event_name`, and
+`run.pr_number` on pull-request events) so they can be correlated per-workflow
+and per-PR downstream.
+
Upload the log from GitHub Actions for customer-controlled retention:
```yaml
@@ -107,6 +112,42 @@ Upload the log from GitHub Actions for customer-controlled retention:
path: ${{ runner.temp }}/beacon/runtime.jsonl
```
+Upload only the `runtime.jsonl` file (as above), not the whole
+`${{ runner.temp }}/beacon` directory: when forwarding is configured the
+job-scoped `otelcol.yaml` in that directory contains the SIEM token. Beacon
+writes that file with `0600` permissions, but excluding it from the artifact
+keeps the credential off the uploaded path entirely.
+
+### Forwarding to a customer-managed SIEM
+
+Because CI runners are ephemeral, the local JSONL is destroyed when the runner
+is torn down. In addition to (or instead of) uploading an artifact, `ci exec`
+can forward events from its ephemeral collector to a customer-managed Splunk or
+CrowdStrike Falcon LogScale HEC endpoint before teardown:
+
+```bash
+export BEACON_CI_SPLUNK_HEC_TOKEN="$SPLUNK_HEC_TOKEN" # from CI secrets
+beacon ci exec \
+ --forward splunk \
+ --forward-endpoint "https://splunk.example:8088/services/collector" \
+ -- claude --print "Summarize this repository"
+```
+
+- The token is read from the environment only
+ (`BEACON_CI_SPLUNK_HEC_TOKEN` / `BEACON_CI_FALCON_HEC_TOKEN`) and is never
+ accepted as a flag, so it does not appear in CI process listings. The
+ endpoint may be passed via `--forward-endpoint` or
+ `BEACON_CI_SPLUNK_HEC_ENDPOINT` / `BEACON_CI_FALCON_HEC_ENDPOINT`.
+- Forwarding is best-effort: a SIEM delivery failure does not fail the job, and
+ Beacon still writes the local JSONL.
+- Beacon remains a local JSONL producer; egress goes only to infrastructure the
+ customer already operates.
+
+By default `ci exec` fails the step when no Beacon events reach the runtime log,
+which surfaces a broken telemetry pipeline. Pass `--require-telemetry=false` to
+downgrade that to a warning when you do not want telemetry health to gate the
+build.
+
## Wazuh
```bash
diff --git a/cli/beacon/cmd/ci.go b/cli/beacon/cmd/ci.go
index e2c22a2a..60e0e00c 100644
--- a/cli/beacon/cmd/ci.go
+++ b/cli/beacon/cmd/ci.go
@@ -27,6 +27,9 @@ var ciOpts struct {
jsonOutput bool
keepArtifacts bool
minEvents int
+ forward string
+ forwardEndpoint string
+ requireTelemetry bool
}
var ciCmd = &cobra.Command{
@@ -68,6 +71,9 @@ func init() {
ciExecCmd.Flags().IntVar(&ciOpts.httpPort, "otlp-http-port", endpointconfig.DefaultHTTPPort, "Local OTLP HTTP port")
ciExecCmd.Flags().StringVar(&ciOpts.contentRetention, "content-retention", string(endpointconfig.ContentRetentionFull), "Content retention mode: metadata, redacted, or full")
ciExecCmd.Flags().BoolVar(&ciOpts.keepArtifacts, "keep-artifacts", true, "Keep CI runtime log and collector config after exit")
+ ciExecCmd.Flags().StringVar(&ciOpts.forward, "forward", "", "Optionally forward events to a customer-managed SIEM: splunk or falcon (token read from the environment)")
+ ciExecCmd.Flags().StringVar(&ciOpts.forwardEndpoint, "forward-endpoint", "", "SIEM HEC endpoint URL for --forward (token comes from BEACON_CI_*_HEC_TOKEN)")
+ ciExecCmd.Flags().BoolVar(&ciOpts.requireTelemetry, "require-telemetry", true, "Fail the command when telemetry validation fails; set false to warn only")
for _, name := range []string{"base-dir", "work-dir", "collector", "otlp-grpc-port", "otlp-http-port"} {
_ = ciExecCmd.Flags().MarkHidden(name)
}
@@ -86,6 +92,8 @@ func runCIExec(cmd *cobra.Command, args []string) error {
Harness: ciOpts.harness,
ContentRetention: endpointconfig.ContentRetention(ciOpts.contentRetention),
KeepArtifacts: ciOpts.keepArtifacts,
+ Forward: ciOpts.forward,
+ ForwardEndpoint: ciOpts.forwardEndpoint,
})
if err != nil {
return err
@@ -129,11 +137,14 @@ func runCIExec(cmd *cobra.Command, args []string) error {
fmt.Println(execResult.ArtifactMessage)
}
if result.Status == "fail" {
- fmt.Fprintln(os.Stderr, "Beacon CI telemetry validation failed")
- if childExit != 0 {
- os.Exit(childExit)
+ if ciOpts.requireTelemetry {
+ fmt.Fprintln(os.Stderr, "Beacon CI telemetry validation failed")
+ if childExit != 0 {
+ os.Exit(childExit)
+ }
+ return fmt.Errorf("Beacon CI telemetry validation failed")
}
- return fmt.Errorf("Beacon CI telemetry validation failed")
+ fmt.Fprintln(os.Stderr, "Warning: Beacon CI telemetry validation failed (continuing because --require-telemetry=false)")
}
if childExit != 0 {
os.Exit(childExit)
diff --git a/cli/beacon/internal/ci/forward.go b/cli/beacon/internal/ci/forward.go
new file mode 100644
index 00000000..8fe8296c
--- /dev/null
+++ b/cli/beacon/internal/ci/forward.go
@@ -0,0 +1,133 @@
+package ci
+
+import (
+ "fmt"
+ "os"
+ "strings"
+
+ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+)
+
+// Supported SIEM forwarding providers for ci exec egress.
+const (
+ ForwardSplunk = "splunk"
+ ForwardFalcon = "falcon"
+)
+
+// Environment variables that carry forwarding configuration. Tokens are read
+// from the environment only and never accepted as command flags, so they do
+// not land in CI process listings or shell history. Endpoints are not secret
+// and may also be supplied via the --forward-endpoint flag.
+const (
+ EnvSplunkToken = "BEACON_CI_SPLUNK_HEC_TOKEN"
+ EnvSplunkEndpoint = "BEACON_CI_SPLUNK_HEC_ENDPOINT"
+ EnvFalconToken = "BEACON_CI_FALCON_HEC_TOKEN"
+ EnvFalconEndpoint = "BEACON_CI_FALCON_HEC_ENDPOINT"
+)
+
+// forwardTokenEnv lists every environment variable that may hold a forwarding
+// secret. These are stripped from the child command environment so the agent
+// process never sees the SIEM token.
+var forwardTokenEnv = []string{EnvSplunkToken, EnvFalconToken}
+
+// normalizeForward validates and canonicalizes a --forward provider value. An
+// empty value means no forwarding is configured.
+func normalizeForward(provider string) (string, error) {
+ switch strings.ToLower(strings.TrimSpace(provider)) {
+ case "":
+ return "", nil
+ case ForwardSplunk:
+ return ForwardSplunk, nil
+ case ForwardFalcon:
+ return ForwardFalcon, nil
+ default:
+ return "", fmt.Errorf("unsupported --forward %q; supported values are %s and %s", provider, ForwardSplunk, ForwardFalcon)
+ }
+}
+
+// resolveForwardDestinations builds the SIEM forwarder configuration for the
+// ephemeral collector. The endpoint may come from the flag or the provider
+// endpoint env var; the token is read from the environment only. It returns
+// nil when no forwarding is requested.
+func resolveForwardDestinations(provider, endpointFlag string) (*endpointconfig.Destinations, error) {
+ provider, err := normalizeForward(provider)
+ if err != nil {
+ return nil, err
+ }
+ switch provider {
+ case ForwardSplunk:
+ endpoint := firstNonEmpty(endpointFlag, os.Getenv(EnvSplunkEndpoint))
+ token := strings.TrimSpace(os.Getenv(EnvSplunkToken))
+ if err := requireForwardCreds(ForwardSplunk, endpoint, token, EnvSplunkEndpoint, EnvSplunkToken); err != nil {
+ return nil, err
+ }
+ return &endpointconfig.Destinations{
+ SplunkHEC: &endpointconfig.SplunkHEC{Enabled: true, Endpoint: endpoint, Token: token},
+ }, nil
+ case ForwardFalcon:
+ endpoint := firstNonEmpty(endpointFlag, os.Getenv(EnvFalconEndpoint))
+ token := strings.TrimSpace(os.Getenv(EnvFalconToken))
+ if err := requireForwardCreds(ForwardFalcon, endpoint, token, EnvFalconEndpoint, EnvFalconToken); err != nil {
+ return nil, err
+ }
+ return &endpointconfig.Destinations{
+ FalconHEC: &endpointconfig.FalconHEC{Enabled: true, Endpoint: endpoint, Token: token},
+ }, nil
+ default:
+ return nil, nil
+ }
+}
+
+func requireForwardCreds(provider, endpoint, token, endpointEnv, tokenEnv string) error {
+ if strings.TrimSpace(endpoint) == "" {
+ return fmt.Errorf("--forward %s requires an endpoint; pass --forward-endpoint or set %s", provider, endpointEnv)
+ }
+ if token == "" {
+ return fmt.Errorf("--forward %s requires a token; set %s in the environment (tokens are not accepted as flags)", provider, tokenEnv)
+ }
+ return nil
+}
+
+// forwardEndpointOf returns the configured forwarder endpoint for display. It
+// never exposes the token.
+func forwardEndpointOf(destinations *endpointconfig.Destinations) string {
+ if destinations == nil {
+ return ""
+ }
+ if destinations.SplunkHEC != nil {
+ return destinations.SplunkHEC.Endpoint
+ }
+ if destinations.FalconHEC != nil {
+ return destinations.FalconHEC.Endpoint
+ }
+ return ""
+}
+
+// stripEnv removes the named variables from a flattened environment slice.
+func stripEnv(env []string, keys ...string) []string {
+ if len(keys) == 0 {
+ return env
+ }
+ drop := make(map[string]struct{}, len(keys))
+ for _, key := range keys {
+ drop[key] = struct{}{}
+ }
+ out := env[:0]
+ for _, kv := range env {
+ name, _, _ := strings.Cut(kv, "=")
+ if _, skip := drop[name]; skip {
+ continue
+ }
+ out = append(out, kv)
+ }
+ return out
+}
+
+func firstNonEmpty(values ...string) string {
+ for _, value := range values {
+ if trimmed := strings.TrimSpace(value); trimmed != "" {
+ return trimmed
+ }
+ }
+ return ""
+}
diff --git a/cli/beacon/internal/ci/forward_test.go b/cli/beacon/internal/ci/forward_test.go
new file mode 100644
index 00000000..8bc23483
--- /dev/null
+++ b/cli/beacon/internal/ci/forward_test.go
@@ -0,0 +1,96 @@
+package ci
+
+import (
+ "strings"
+ "testing"
+)
+
+func TestResolveForwardSplunkFromFlagEndpoint(t *testing.T) {
+ t.Setenv(EnvSplunkToken, "splunk-secret")
+ t.Setenv(EnvSplunkEndpoint, "")
+
+ dest, err := resolveForwardDestinations("Splunk", "https://splunk.example/services/collector")
+ if err != nil {
+ t.Fatalf("resolveForwardDestinations returned error: %v", err)
+ }
+ if dest == nil || dest.SplunkHEC == nil {
+ t.Fatalf("expected Splunk destination, got %+v", dest)
+ }
+ if !dest.SplunkHEC.Enabled {
+ t.Fatal("Splunk destination should be enabled")
+ }
+ if dest.SplunkHEC.Endpoint != "https://splunk.example/services/collector" {
+ t.Fatalf("Endpoint = %q", dest.SplunkHEC.Endpoint)
+ }
+ if dest.SplunkHEC.Token != "splunk-secret" {
+ t.Fatalf("Token = %q", dest.SplunkHEC.Token)
+ }
+}
+
+func TestResolveForwardFalconUsesEnvEndpoint(t *testing.T) {
+ t.Setenv(EnvFalconToken, "falcon-secret")
+ t.Setenv(EnvFalconEndpoint, "https://falcon.example/services/collector")
+
+ dest, err := resolveForwardDestinations("falcon", "")
+ if err != nil {
+ t.Fatalf("resolveForwardDestinations returned error: %v", err)
+ }
+ if dest == nil || dest.FalconHEC == nil {
+ t.Fatalf("expected Falcon destination, got %+v", dest)
+ }
+ if dest.FalconHEC.Endpoint != "https://falcon.example/services/collector" {
+ t.Fatalf("Endpoint = %q", dest.FalconHEC.Endpoint)
+ }
+ if dest.FalconHEC.Token != "falcon-secret" {
+ t.Fatalf("Token = %q", dest.FalconHEC.Token)
+ }
+}
+
+func TestResolveForwardMissingTokenErrors(t *testing.T) {
+ t.Setenv(EnvSplunkToken, "")
+
+ _, err := resolveForwardDestinations("splunk", "https://splunk.example")
+ if err == nil {
+ t.Fatal("expected error when token env var is unset")
+ }
+ if !strings.Contains(err.Error(), EnvSplunkToken) {
+ t.Fatalf("error should name the token env var, got %v", err)
+ }
+}
+
+func TestResolveForwardMissingEndpointErrors(t *testing.T) {
+ t.Setenv(EnvSplunkToken, "splunk-secret")
+ t.Setenv(EnvSplunkEndpoint, "")
+
+ if _, err := resolveForwardDestinations("splunk", ""); err == nil {
+ t.Fatal("expected error when endpoint is missing")
+ }
+}
+
+func TestResolveForwardUnsupportedProvider(t *testing.T) {
+ if _, err := resolveForwardDestinations("datadog", "https://example"); err == nil {
+ t.Fatal("expected error for unsupported provider")
+ }
+}
+
+func TestNormalizeForwardEmptyIsNoForwarding(t *testing.T) {
+ got, err := normalizeForward(" ")
+ if err != nil {
+ t.Fatalf("normalizeForward returned error: %v", err)
+ }
+ if got != "" {
+ t.Fatalf("normalizeForward = %q, want empty", got)
+ }
+}
+
+func TestStripEnvRemovesNamedKeys(t *testing.T) {
+ in := []string{"KEEP=1", EnvSplunkToken + "=secret", "ALSO=2", EnvFalconToken + "=secret2"}
+ out := stripEnv(in, forwardTokenEnv...)
+ joined := strings.Join(out, "\n")
+ if strings.Contains(joined, "secret") {
+ t.Fatalf("stripEnv left a token behind:\n%s", joined)
+ }
+ if !strings.Contains(joined, "KEEP=1") || !strings.Contains(joined, "ALSO=2") {
+ t.Fatalf("stripEnv dropped non-token vars:\n%s", joined)
+ }
+}
diff --git a/cli/beacon/internal/ci/session.go b/cli/beacon/internal/ci/session.go
index 04e9e98c..6481f431 100644
--- a/cli/beacon/internal/ci/session.go
+++ b/cli/beacon/internal/ci/session.go
@@ -42,6 +42,11 @@ type Options struct {
Harness string
ContentRetention endpointconfig.ContentRetention
KeepArtifacts bool
+ // Forward selects an optional SIEM forwarder ("splunk" or "falcon") for the
+ // ephemeral collector. ForwardEndpoint supplies the destination URL; the
+ // token is read from the environment only.
+ Forward string
+ ForwardEndpoint string
}
type Session struct {
@@ -55,6 +60,10 @@ type Session struct {
WorkDir string `json:"work_dir,omitempty"`
StartedAt string `json:"started_at"`
Run *schema.RunInfo `json:"run,omitempty"`
+ // Forward and ForwardEndpoint describe the optional SIEM egress. The token
+ // is never recorded here so it cannot leak into --json output.
+ Forward string `json:"forward,omitempty"`
+ ForwardEndpoint string `json:"forward_endpoint,omitempty"`
cfg endpointconfig.Config
startedAt time.Time
@@ -108,6 +117,19 @@ func Provision(opts Options) (*Session, error) {
cfg.Collector.SpoolPath = filepath.Join(baseDir, "spool", "otlp.jsonl")
cfg.Collector.GRPCPort = grpcPort
cfg.Collector.HTTPPort = httpPort
+ forward, err := normalizeForward(opts.Forward)
+ if err != nil {
+ return nil, err
+ }
+ var forwardEndpoint string
+ if forward != "" {
+ destinations, err := resolveForwardDestinations(forward, opts.ForwardEndpoint)
+ if err != nil {
+ return nil, err
+ }
+ cfg.Destinations = destinations
+ forwardEndpoint = forwardEndpointOf(destinations)
+ }
if err := os.MkdirAll(filepath.Dir(logPath), 0755); err != nil {
return nil, err
}
@@ -137,6 +159,8 @@ func Provision(opts Options) (*Session, error) {
WorkDir: opts.WorkDir,
StartedAt: startedAt.Format(time.RFC3339),
Run: detectRunInfo(),
+ Forward: forward,
+ ForwardEndpoint: forwardEndpoint,
cfg: cfg,
startedAt: startedAt,
}, nil
@@ -215,11 +239,13 @@ func (s *Session) RunChild(ctx context.Context, args []string, stdout, stderr io
}
cmd := childCommandContext(ctx, args[0], args[1:]...)
cmd.Dir = s.WorkDir
- cmd.Env = append(ClaudeEnv(os.Environ(), s.GRPCEndpoint, s.cfg.ContentRetention),
+ env := append(ClaudeEnv(os.Environ(), s.GRPCEndpoint, s.cfg.ContentRetention),
"BEACON_CI_BASE_DIR="+s.BaseDir,
"BEACON_CI_CONFIG_PATH="+s.ConfigPath,
"BEACON_CI_LOG_PATH="+s.LogPath,
)
+ // The agent never needs the SIEM token; keep it out of the child process.
+ cmd.Env = stripEnv(env, forwardTokenEnv...)
cmd.Stdout = stdout
cmd.Stderr = stderr
err := cmd.Run()
diff --git a/cli/beacon/internal/ci/session_test.go b/cli/beacon/internal/ci/session_test.go
index bfbd7eca..06f28cd3 100644
--- a/cli/beacon/internal/ci/session_test.go
+++ b/cli/beacon/internal/ci/session_test.go
@@ -2,6 +2,7 @@ package ci
import (
"context"
+ "encoding/json"
"os"
"path/filepath"
"runtime"
@@ -249,6 +250,104 @@ func TestParsePRNumber(t *testing.T) {
}
}
+func TestProvisionForwardWritesSecureExporterConfig(t *testing.T) {
+ runnerTemp := t.TempDir()
+ t.Setenv("RUNNER_TEMP", runnerTemp)
+ t.Setenv(EnvSplunkToken, "top-secret-token")
+ collector := fakeExecutable(t, "collector", "#!/bin/sh\nsleep 60\n")
+ oldResolve := resolveCollectorBinary
+ resolveCollectorBinary = func(string) (string, error) { return collector, nil }
+ t.Cleanup(func() { resolveCollectorBinary = oldResolve })
+
+ session, err := Provision(Options{
+ CollectorPath: collector,
+ Harness: "claude",
+ Forward: "splunk",
+ ForwardEndpoint: "https://splunk.example/services/collector",
+ })
+ if err != nil {
+ t.Fatalf("Provision returned error: %v", err)
+ }
+ if session.Forward != "splunk" || session.ForwardEndpoint != "https://splunk.example/services/collector" {
+ t.Fatalf("session forward fields = %q / %q", session.Forward, session.ForwardEndpoint)
+ }
+
+ data, err := os.ReadFile(session.ConfigPath)
+ if err != nil {
+ t.Fatal(err)
+ }
+ yaml := string(data)
+ if !strings.Contains(yaml, "splunk_hec:") {
+ t.Fatalf("collector config missing splunk_hec exporter:\n%s", yaml)
+ }
+ if !strings.Contains(yaml, "top-secret-token") {
+ t.Fatal("collector config missing forwarder token")
+ }
+
+ info, err := os.Stat(session.ConfigPath)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if perm := info.Mode().Perm(); perm != 0o600 {
+ t.Fatalf("token-bearing config mode = %o, want 600", perm)
+ }
+
+ encoded, err := json.Marshal(session)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if strings.Contains(string(encoded), "top-secret-token") {
+ t.Fatalf("token leaked into session JSON:\n%s", encoded)
+ }
+}
+
+func TestProvisionForwardMissingTokenFails(t *testing.T) {
+ t.Setenv("RUNNER_TEMP", t.TempDir())
+ t.Setenv(EnvSplunkToken, "")
+ collector := fakeExecutable(t, "collector", "#!/bin/sh\nsleep 60\n")
+ oldResolve := resolveCollectorBinary
+ resolveCollectorBinary = func(string) (string, error) { return collector, nil }
+ t.Cleanup(func() { resolveCollectorBinary = oldResolve })
+
+ _, err := Provision(Options{
+ CollectorPath: collector,
+ Harness: "claude",
+ Forward: "splunk",
+ ForwardEndpoint: "https://splunk.example",
+ })
+ if err == nil {
+ t.Fatal("Provision should fail when the forwarding token is missing")
+ }
+}
+
+func TestRunChildStripsForwardToken(t *testing.T) {
+ dir := t.TempDir()
+ output := filepath.Join(dir, "env.txt")
+ t.Setenv(EnvSplunkToken, "leak-me-not")
+ child := fakeExecutable(t, "child", "#!/bin/sh\nenv > \"$1\"\n")
+ session := &Session{
+ BaseDir: dir,
+ ConfigPath: filepath.Join(dir, "otelcol.yaml"),
+ LogPath: filepath.Join(dir, "runtime.jsonl"),
+ GRPCEndpoint: "http://127.0.0.1:4317",
+ cfg: endpointconfig.Default(true, filepath.Join(dir, "runtime.jsonl")),
+ }
+ if _, err := session.RunChild(context.Background(), []string{child, output}, nil, nil); err != nil {
+ t.Fatalf("RunChild returned error: %v", err)
+ }
+ data, err := os.ReadFile(output)
+ if err != nil {
+ t.Fatal(err)
+ }
+ env := string(data)
+ if strings.Contains(env, "leak-me-not") || strings.Contains(env, EnvSplunkToken+"=") {
+ t.Fatalf("child env exposed the SIEM token:\n%s", env)
+ }
+ if !strings.Contains(env, "CLAUDE_CODE_ENABLE_TELEMETRY=1") {
+ t.Fatalf("child env missing Claude telemetry vars:\n%s", env)
+ }
+}
+
func fakeExecutable(t *testing.T, name, script string) string {
t.Helper()
path := filepath.Join(t.TempDir(), name)