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
add cloudwatch support
Justin D'Souzaa7d197212821
diff --git a/.gitignore b/.gitignoreindex f4c75f83..851abc9a 100644--- a/.gitignore+++ b/.gitignore@@ -34,6 +34,7 @@ cli/beacon-hooks/*.exe!cli/beacon/internal/endpoint/sumo/pack/sample-event.jsonl!cli/beacon/internal/endpoint/rapid7/pack/sample-event.jsonl!cli/beacon/internal/endpoint/s3/pack/sample-event.jsonl+!cli/beacon/internal/endpoint/cloudwatch/pack/sample-event.jsonl!cli/beacon/internal/endpoint/gcs/pack/sample-event.jsonl!cli/beacon/internal/endpoint/sentinel/pack/sample-event.jsonl!cli/beacon/internal/endpoint/gcs/pack/sample-event.jsonldiff --git a/README.md b/README.mdindex 7400048d..dfed5dee 100644--- a/README.md+++ b/README.md@@ -122,6 +122,7 @@ management (SIEM), log aggregation, and object storage destinations.| Destination | Support path || --- | --- |+| [AWS CloudWatch Logs](https://docs.asymptotelabs.ai/cli/siem-forwarding-cloudwatch) | Vector content pack over local JSONL using customer-managed AWS credentials || [Customer-managed log pipelines](https://docs.asymptotelabs.ai/cli/siem-forwarding) | Forwarding from local Beacon JSONL under customer control || [Datadog](https://docs.asymptotelabs.ai/cli/siem-forwarding-datadog) | Datadog Agent custom log collection over local JSONL || [Elastic](https://docs.asymptotelabs.ai/cli/siem-forwarding-elastic) | Filebeat or Elastic Agent content pack over local JSONL |diff --git a/cli/beacon/README.md b/cli/beacon/README.mdindex a487aafb..3f970e6e 100644--- a/cli/beacon/README.md+++ b/cli/beacon/README.md@@ -196,6 +196,20 @@ Store AWS credentials, profiles, IAM roles, bucket policies, lifecycle rules,and encryption settings in AWS, Vector, or deployment tooling, not in Beaconendpoint configuration.+## AWS CloudWatch Logs++```bash+./beacon endpoint cloudwatch print-config+./beacon endpoint cloudwatch install-pack --output ./beacon-cloudwatch-pack+./beacon endpoint cloudwatch validate+```++The AWS CloudWatch Logs pack keeps Beacon as a local JSONL producer and+documents forwarding `runtime.jsonl` into a CloudWatch Logs log group with a+customer-managed Vector host agent. Store AWS credentials, profiles, IAM roles,+log group retention, stream naming, and encryption settings in AWS, Vector, or+deployment tooling, not in Beacon endpoint configuration.+## Google Cloud Storage```bashdiff --git a/cli/beacon/cmd/endpoint.go b/cli/beacon/cmd/endpoint.goindex 65e418e5..69e61b58 100644--- a/cli/beacon/cmd/endpoint.go+++ b/cli/beacon/cmd/endpoint.go@@ -13,6 +13,7 @@ import ("github.com/spf13/cobra"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/cloudwatch"endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/dashboard""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/datadog"@@ -196,6 +197,11 @@ var endpointS3Cmd = &cobra.Command{Short: "Manage AWS S3 forwarding content",}+var endpointCloudWatchCmd = &cobra.Command{+ Use: "cloudwatch",+ Short: "Manage AWS CloudWatch Logs forwarding content",+}+var endpointGCSCmd = &cobra.Command{Use: "gcs",Short: "Manage Google Cloud Storage forwarding content",@@ -648,6 +654,35 @@ var endpointS3ValidateCmd = &cobra.Command{RunE: runEndpointS3Validate,}+var endpointCloudWatchPrintConfigCmd = &cobra.Command{+ Use: "print-config",+ Short: "Print a Vector config for AWS CloudWatch Logs forwarding",+ SilenceUsage: true,+ RunE: func(cmd *cobra.Command, args []string) error {+ cfg := loadOrDefaultConfig()+ snippet, err := cloudwatch.ConfigSnippet(cfg.LogPath)+ if err != nil {+ return err+ }+ fmt.Print(snippet)+ return nil+ },+}++var endpointCloudWatchInstallPackCmd = &cobra.Command{+ Use: "install-pack",+ Short: "Write AWS CloudWatch Logs forwarding content to a directory",+ SilenceUsage: true,+ RunE: runEndpointCloudWatchInstallPack,+}++var endpointCloudWatchValidateCmd = &cobra.Command{+ Use: "validate",+ Short: "Write and describe an AWS CloudWatch Logs validation event",+ SilenceUsage: true,+ RunE: runEndpointCloudWatchValidate,+}+var endpointGCSPrintConfigCmd = &cobra.Command{Use: "print-config",Short: "Print a Google Cloud Storage smoke-test uploader for Beacon endpoint events",@@ -723,6 +758,7 @@ func init() {endpointCmd.AddCommand(endpointSumoCmd)endpointCmd.AddCommand(endpointRapid7Cmd)endpointCmd.AddCommand(endpointS3Cmd)+ endpointCmd.AddCommand(endpointCloudWatchCmd)endpointCmd.AddCommand(endpointGCSCmd)endpointCmd.AddCommand(endpointSentinelCmd)endpointCmd.AddCommand(endpointIntegrationsCmd)@@ -750,6 +786,9 @@ func init() {endpointS3Cmd.AddCommand(endpointS3PrintConfigCmd)endpointS3Cmd.AddCommand(endpointS3InstallPackCmd)endpointS3Cmd.AddCommand(endpointS3ValidateCmd)+ endpointCloudWatchCmd.AddCommand(endpointCloudWatchPrintConfigCmd)+ endpointCloudWatchCmd.AddCommand(endpointCloudWatchInstallPackCmd)+ endpointCloudWatchCmd.AddCommand(endpointCloudWatchValidateCmd)endpointGCSCmd.AddCommand(endpointGCSPrintConfigCmd)endpointGCSCmd.AddCommand(endpointGCSInstallPackCmd)endpointGCSCmd.AddCommand(endpointGCSValidateCmd)@@ -869,6 +908,12 @@ func init() {c.Flags().StringVar(&endpointOpts.logPath, "log-path", "", "Runtime JSONL log path")}endpointS3InstallPackCmd.Flags().StringVar(&endpointOpts.outputDir, "output", "", "Output directory for AWS S3 content pack")+ for _, c := range []*cobra.Command{endpointCloudWatchPrintConfigCmd, endpointCloudWatchInstallPackCmd, endpointCloudWatchValidateCmd} {+ c.Flags().BoolVar(&endpointOpts.userMode, "user", true, "Use per-user endpoint paths")+ c.Flags().BoolVar(&endpointOpts.systemMode, "system", false, "Use system endpoint paths and launch daemon")+ c.Flags().StringVar(&endpointOpts.logPath, "log-path", "", "Runtime JSONL log path")+ }+ endpointCloudWatchInstallPackCmd.Flags().StringVar(&endpointOpts.outputDir, "output", "", "Output directory for AWS CloudWatch Logs content pack")for _, c := range []*cobra.Command{endpointGCSPrintConfigCmd, endpointGCSInstallPackCmd, endpointGCSValidateCmd} {c.Flags().BoolVar(&endpointOpts.userMode, "user", true, "Use per-user endpoint paths")c.Flags().BoolVar(&endpointOpts.systemMode, "system", false, "Use system endpoint paths and launch daemon")@@ -1441,6 +1486,32 @@ func runEndpointS3Validate(cmd *cobra.Command, args []string) error {return nil}+func runEndpointCloudWatchInstallPack(cmd *cobra.Command, args []string) error {+ cfg := loadOrDefaultConfig()+ outputDir := endpointOpts.outputDir+ if outputDir == "" {+ outputDir = cloudwatch.DefaultOutputDir+ }+ if err := cloudwatch.InstallPack(outputDir, cfg.LogPath); err != nil {+ return err+ }+ fmt.Printf("AWS CloudWatch Logs content pack written to %s\n", outputDir)+ return nil+}++func runEndpointCloudWatchValidate(cmd *cobra.Command, args []string) error {+ cfg := loadOrDefaultConfig()+ path, err := writeValidationEvent(cfg, "cloudwatch")+ if err != nil {+ return err+ }+ fmt.Printf("Validation event written to %s\n", path)+ fmt.Println("Expected AWS CloudWatch Logs fields: vendor=beacon product=endpoint-agent destination.type=cloudwatch destination.mode=aws_cloudwatch_logs")+ fmt.Println(`Confirm delivery with AWS CLI: aws logs filter-log-events --log-group-name "$BEACON_CLOUDWATCH_LOG_GROUP" --filter-pattern '"Beacon endpoint AWS CloudWatch Logs validation event"' --region "$AWS_REGION"`)+ fmt.Println(`CloudWatch Logs Insights query: fields @timestamp, vendor, product, destination.type, destination.mode, message | filter message like /Beacon endpoint AWS CloudWatch Logs validation event/ | sort @timestamp desc | limit 20`)+ return nil+}+func runEndpointGCSInstallPack(cmd *cobra.Command, args []string) error {cfg := loadOrDefaultConfig()outputDir := endpointOpts.outputDirdiff --git a/cli/beacon/cmd/endpoint_diagnostics.go b/cli/beacon/cmd/endpoint_diagnostics.goindex 318c0237..660eb983 100644--- a/cli/beacon/cmd/endpoint_diagnostics.go+++ b/cli/beacon/cmd/endpoint_diagnostics.go@@ -703,6 +703,9 @@ func syntheticEvent(destination string) schema.Event {case "s3":mode = "aws_s3_jsonl"message = "Beacon endpoint S3 validation event"+ case "cloudwatch":+ mode = "aws_cloudwatch_logs"+ message = "Beacon endpoint AWS CloudWatch Logs validation event"case "gcs":mode = "google_cloud_storage_jsonl"message = "Beacon endpoint GCS validation event"diff --git a/cli/beacon/cmd/endpoint_test.go b/cli/beacon/cmd/endpoint_test.goindex 51589e6f..e9048de1 100644--- a/cli/beacon/cmd/endpoint_test.go+++ b/cli/beacon/cmd/endpoint_test.go@@ -329,6 +329,30 @@ func TestEndpointS3CommandsRegistered(t *testing.T) {}}+func TestEndpointCloudWatchCommandsRegistered(t *testing.T) {+ for _, path := range [][]string{+ {"cloudwatch", "print-config"},+ {"cloudwatch", "install-pack"},+ {"cloudwatch", "validate"},+ } {+ cmd, _, err := endpointCmd.Find(path)+ if err != nil {+ t.Fatalf("Find %v returned error: %v", path, err)+ }+ if cmd == nil || cmd.Use != path[len(path)-1] {+ t.Fatalf("cloudwatch command %v not registered: %#v", path, cmd)+ }+ for _, name := range []string{"user", "system", "log-path"} {+ if cmd.Flags().Lookup(name) == nil {+ t.Fatalf("cloudwatch command %v missing --%s flag", path, name)+ }+ }+ }+ if endpointCloudWatchInstallPackCmd.Flags().Lookup("output") == nil {+ t.Fatal("cloudwatch install-pack command missing --output flag")+ }+}+func TestEndpointGCSCommandsRegistered(t *testing.T) {for _, path := range [][]string{{"gcs", "print-config"},@@ -761,6 +785,14 @@ func TestSyntheticEventDestinations(t *testing.T) {t.Fatalf("s3 message = %q", s3Event.Message)}+ cloudwatchEvent := syntheticEvent("cloudwatch")+ if cloudwatchEvent.Destination.Type != "cloudwatch" || cloudwatchEvent.Destination.Mode != "aws_cloudwatch_logs" {+ t.Fatalf("cloudwatch destination = %#v", cloudwatchEvent.Destination)+ }+ if cloudwatchEvent.Message != "Beacon endpoint AWS CloudWatch Logs validation event" {+ t.Fatalf("cloudwatch message = %q", cloudwatchEvent.Message)+ }+gcsEvent := syntheticEvent("gcs")if gcsEvent.Destination.Type != "gcs" || gcsEvent.Destination.Mode != "google_cloud_storage_jsonl" {t.Fatalf("gcs destination = %#v", gcsEvent.Destination)@@ -805,6 +837,72 @@ func TestEndpointS3ValidatePrintsAWSCLIInspectionGuidance(t *testing.T) {}}+func TestEndpointCloudWatchPrintConfigPrintsVectorConfig(t *testing.T) {+ oldLogPath := endpointOpts.logPath+ oldUserMode := endpointOpts.userMode+ oldSystemMode := endpointOpts.systemMode+ endpointOpts.logPath = filepath.Join(t.TempDir(), "runtime.jsonl")+ endpointOpts.userMode = true+ endpointOpts.systemMode = false+ t.Cleanup(func() {+ endpointOpts.logPath = oldLogPath+ endpointOpts.userMode = oldUserMode+ endpointOpts.systemMode = oldSystemMode+ })++ output, err := captureStdout(t, func() error {+ return endpointCloudWatchPrintConfigCmd.RunE(endpointCloudWatchPrintConfigCmd, nil)+ })+ if err != nil {+ t.Fatalf("endpoint cloudwatch print-config returned error: %v", err)+ }+ for _, want := range []string{+ "aws_cloudwatch_logs",+ "BEACON_CLOUDWATCH_LOG_GROUP",+ "BEACON_CLOUDWATCH_LOG_STREAM_PREFIX",+ endpointOpts.logPath,+ } {+ if !strings.Contains(output, want) {+ t.Fatalf("CloudWatch print-config output missing %q: %s", want, output)+ }+ }+}++func TestEndpointCloudWatchValidatePrintsAWSInspectionGuidance(t *testing.T) {+ oldLogPath := endpointOpts.logPath+ oldUserMode := endpointOpts.userMode+ oldSystemMode := endpointOpts.systemMode+ endpointOpts.logPath = filepath.Join(t.TempDir(), "runtime.jsonl")+ endpointOpts.userMode = true+ endpointOpts.systemMode = false+ t.Cleanup(func() {+ endpointOpts.logPath = oldLogPath+ endpointOpts.userMode = oldUserMode+ endpointOpts.systemMode = oldSystemMode+ })++ output, err := captureStdout(t, func() error {+ return runEndpointCloudWatchValidate(endpointCloudWatchValidateCmd, nil)+ })+ if err != nil {+ t.Fatalf("runEndpointCloudWatchValidate returned error: %v", err)+ }+ for _, want := range []string{+ "Validation event written to",+ "destination.type=cloudwatch destination.mode=aws_cloudwatch_logs",+ "aws logs filter-log-events",+ "CloudWatch Logs Insights query",+ "Beacon endpoint AWS CloudWatch Logs validation event",+ } {+ if !strings.Contains(output, want) {+ t.Fatalf("CloudWatch validation output missing %q: %s", want, output)+ }+ }+ if strings.Contains(output, "verified delivery") {+ t.Fatalf("CloudWatch validation output should not claim remote delivery verification: %s", output)+ }+}+func TestEndpointGCSValidatePrintsGoogleCloudCLIInspectionGuidance(t *testing.T) {oldLogPath := endpointOpts.logPatholdUserMode := endpointOpts.userModediff --git a/cli/beacon/internal/endpoint/cloudwatch/cloudwatch.go b/cli/beacon/internal/endpoint/cloudwatch/cloudwatch.gonew file mode 100644index 00000000..7709e0d3--- /dev/null+++ b/cli/beacon/internal/endpoint/cloudwatch/cloudwatch.go@@ -0,0 +1,100 @@+package cloudwatch++import (+ "embed"+ "fmt"+ "io/fs"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/siempack"+)++//go:embed pack/*+var packFS embed.FS++const (+ DefaultLogPath = "/var/log/beacon-agent/runtime.jsonl"+ DefaultOutputDir = "beacon-cloudwatch-pack"+)++type File struct {+ Name string+ Content string+ TemplateLogPath bool+ JSONEscape bool+}++func readAsset(path string) (string, error) {+ data, err := siempack.ReadFile(packFS, path)+ if err != nil {+ return "", fmt.Errorf("cloudwatch pack asset %q: %w", path, err)+ }+ return data, nil+}++func mustRead(path string) string {+ s, err := readAsset(path)+ if err != nil {+ panic(err.Error())+ }+ return s+}++func configSnippetFromFS(fsys fs.FS, logPath string) (string, error) {+ if logPath == "" {+ logPath = DefaultLogPath+ }+ content, err := siempack.ReadFile(fsys, "pack/vector.toml.tmpl")+ if err != nil {+ return "", fmt.Errorf("cloudwatch pack asset %q: %w", "pack/vector.toml.tmpl", err)+ }+ return siempack.RenderLogPath(content, logPath), nil+}++func filesFromFS(fsys fs.FS) ([]File, error) {+ readme, err := siempack.ReadFile(fsys, "pack/README.md")+ if err != nil {+ return nil, fmt.Errorf("cloudwatch pack asset %q: %w", "pack/README.md", err)+ }+ sample, err := siempack.ReadFile(fsys, "pack/sample-event.jsonl")+ if err != nil {+ return nil, fmt.Errorf("cloudwatch pack asset %q: %w", "pack/sample-event.jsonl", err)+ }+ vector, err := siempack.ReadFile(fsys, "pack/vector.toml.tmpl")+ if err != nil {+ return nil, fmt.Errorf("cloudwatch pack asset %q: %w", "pack/vector.toml.tmpl", err)+ }+ return []File{+ {Name: "README.md", Content: readme},+ {Name: "sample-event.jsonl", Content: sample},+ {Name: "vector.toml", Content: vector, TemplateLogPath: true},+ }, nil+}++// ConfigSnippet returns a rendered Vector configuration for AWS CloudWatch Logs.+func ConfigSnippet(logPath string) (string, error) {+ return configSnippetFromFS(packFS, logPath)+}++// Files returns all pack files, propagating any embedded asset read error.+func Files() ([]File, error) {+ return filesFromFS(packFS)+}++// InstallPack writes the AWS CloudWatch Logs pack files to outputDir with logPath substituted.+func InstallPack(outputDir, logPath string) error {+ if outputDir == "" {+ outputDir = DefaultOutputDir+ }+ if logPath == "" {+ logPath = DefaultLogPath+ }+ files, err := filesFromFS(packFS)+ if err != nil {+ return err+ }+ sfiles := make([]siempack.File, 0, len(files))+ for _, file := range files {+ sfiles = append(sfiles, siempack.File(file))+ }+ return siempack.Install(outputDir, sfiles, logPath)+}diff --git a/cli/beacon/internal/endpoint/cloudwatch/cloudwatch_test.go b/cli/beacon/internal/endpoint/cloudwatch/cloudwatch_test.gonew file mode 100644index 00000000..7605fef9--- /dev/null+++ b/cli/beacon/internal/endpoint/cloudwatch/cloudwatch_test.go@@ -0,0 +1,214 @@+package cloudwatch++import (+ "bufio"+ "encoding/json"+ "os"+ "path/filepath"+ "strings"+ "testing"+ "testing/fstest"+)++func TestConfigSnippetUsesConfiguredPath(t *testing.T) {+ got, err := ConfigSnippet("/tmp/beacon/runtime.jsonl")+ if err != nil {+ t.Fatalf("ConfigSnippet returned unexpected error: %v", err)+ }+ if !strings.Contains(got, "/tmp/beacon/runtime.jsonl") {+ t.Fatalf("config did not include configured path: %s", got)+ }+ if strings.Contains(got, "{{LOG_PATH}}") {+ t.Fatalf("config still contains template token: %s", got)+ }+ for _, want := range []string{+ "aws_cloudwatch_logs",+ "BEACON_CLOUDWATCH_LOG_GROUP",+ "BEACON_CLOUDWATCH_LOG_STREAM_PREFIX",+ "AWS_REGION",+ "credential provider chain",+ "create_missing_stream = true",+ } {+ if !strings.Contains(got, want) {+ t.Fatalf("config missing %q: %s", want, got)+ }+ }+}++func TestInstallPackWritesExpectedFiles(t *testing.T) {+ dir := t.TempDir()+ if err := InstallPack(dir, "/tmp/beacon/runtime.jsonl"); err != nil {+ t.Fatalf("InstallPack returned error: %v", err)+ }+ for _, name := range []string{"README.md", "sample-event.jsonl", "vector.toml"} {+ if _, err := os.Stat(filepath.Join(dir, name)); err != nil {+ t.Fatalf("expected %s: %v", name, err)+ }+ }+ vectorPath := filepath.Join(dir, "vector.toml")+ vectorConfig, err := os.ReadFile(vectorPath)+ if err != nil {+ t.Fatal(err)+ }+ if !strings.Contains(string(vectorConfig), "/tmp/beacon/runtime.jsonl") {+ t.Fatalf("generated vector config missing configured log path: %s", vectorConfig)+ }+ info, err := os.Stat(vectorPath)+ if err != nil {+ t.Fatal(err)+ }+ if info.Mode().Perm() != 0644 {+ t.Fatalf("generated vector config should be 0644, mode=%s", info.Mode().Perm())+ }+}++func TestVectorConfigUsesAWSCloudWatchLogsSinkAndPreservesJSONShape(t *testing.T) {+ got := mustRead("pack/vector.toml.tmpl")+ for _, want := range []string{+ `include = ["{{LOG_PATH}}"]`,+ `read_from = "end"`,+ `. = parse_json!(.message)`,+ `type = "aws_cloudwatch_logs"`,+ `group_name = "${BEACON_CLOUDWATCH_LOG_GROUP}"`,+ `stream_name = "${BEACON_CLOUDWATCH_LOG_STREAM_PREFIX:-beacon-runtime}/${HOSTNAME:-unknown-host}"`,+ `region = "${AWS_REGION:-us-east-1}"`,+ `create_missing_group = false`,+ `create_missing_stream = true`,+ `codec = "json"`,+ `max_events = 1000`,+ `retry_attempts = 10`,+ } {+ if !strings.Contains(got, want) {+ t.Fatalf("vector config missing %q: %s", want, got)+ }+ }+}++func TestSampleEventsCoverValidationHookAndOTelShapes(t *testing.T) {+ scanner := bufio.NewScanner(strings.NewReader(mustRead("pack/sample-event.jsonl")))+ var sawValidation, sawHook, sawOTel bool+ for scanner.Scan() {+ var doc map[string]interface{}+ if err := json.Unmarshal(scanner.Bytes(), &doc); err != nil {+ t.Fatalf("sample-event.jsonl is not valid JSONL: %v", err)+ }+ if destination, ok := doc["destination"].(map[string]interface{}); ok && destination["type"] == "cloudwatch" {+ sawValidation = true+ }+ if _, ok := doc["tool"].(map[string]interface{}); ok {+ sawHook = true+ }+ if raw, ok := doc["raw"].(map[string]interface{}); ok && raw["otel_signal"] != nil {+ sawOTel = true+ }+ }+ if err := scanner.Err(); err != nil {+ t.Fatal(err)+ }+ if !sawValidation || !sawHook || !sawOTel {+ t.Fatalf("sample events should include validation, hook-rich, and OTel shapes; validation=%t hook=%t otel=%t", sawValidation, sawHook, sawOTel)+ }+}++func TestPackREADMEMentionsAWSCloudWatchLogsSetupAndProductionForwarding(t *testing.T) {+ readme := mustRead("pack/README.md")+ for _, want := range []string{+ "beacon endpoint cloudwatch validate",+ "AWS CloudWatch Logs",+ "credentials available",+ "least-privilege IAM policy",+ "BEACON_CLOUDWATCH_LOG_GROUP",+ "BEACON_CLOUDWATCH_LOG_STREAM_PREFIX",+ "aws logs filter-log-events",+ "CloudWatch Logs Insights",+ "Beacon endpoint AWS CloudWatch Logs validation event",+ "vendor=beacon product=endpoint-agent destination.type=cloudwatch destination.mode=aws_cloudwatch_logs",+ "vector.toml",+ "customer-managed host-agent",+ "content retention",+ "/var/log/beacon-agent/runtime.jsonl",+ "Do not store AWS destination secrets",+ "encryption",+ } {+ if !strings.Contains(readme, want) {+ t.Fatalf("pack README missing %q", want)+ }+ }+}++func TestFiles_NoError(t *testing.T) {+ files, err := Files()+ if err != nil {+ t.Fatalf("Files() returned unexpected error: %v", err)+ }+ if len(files) == 0 {+ t.Fatal("Files() returned no files")+ }+}++func TestFiles_ContainsAllRequiredNames(t *testing.T) {+ files, err := Files()+ if err != nil {+ t.Fatal(err)+ }+ names := make(map[string]bool)+ for _, f := range files {+ names[f.Name] = true+ }+ for _, required := range []string{+ "README.md", "sample-event.jsonl", "vector.toml",+ } {+ if !names[required] {+ t.Errorf("Files() missing required file %q", required)+ }+ }+}++func TestFilesFromFS_PropagatesReadError(t *testing.T) {+ emptyFS := fstest.MapFS{}+ _, err := filesFromFS(emptyFS)+ if err == nil {+ t.Fatal("filesFromFS with empty FS should return an error")+ }+ if !strings.Contains(err.Error(), "cloudwatch pack asset") {+ t.Fatalf("error should identify the pack source, got: %v", err)+ }+}++func TestConfigSnippetFromFS_ErrorOnMissingAsset(t *testing.T) {+ emptyFS := fstest.MapFS{}+ _, err := configSnippetFromFS(emptyFS, "/some/path.jsonl")+ if err == nil {+ t.Fatal("configSnippetFromFS with empty FS should return error")+ }+ if !strings.Contains(err.Error(), "cloudwatch pack asset") {+ t.Fatalf("error should identify the pack source, got: %v", err)+ }+}++func TestInstallPack_ErrorOnWriteFailure(t *testing.T) {+ if os.Getuid() == 0 {+ t.Skip("running as root: filesystem permission restrictions do not apply")+ }+ dir := t.TempDir()+ if err := os.Chmod(dir, 0555); err != nil {+ t.Skip("cannot set directory permissions:", err)+ }+ defer os.Chmod(dir, 0755)++ subdir := filepath.Join(dir, "output")+ err := InstallPack(subdir, DefaultLogPath)+ if err == nil {+ t.Fatal("InstallPack into read-only directory should return error")+ }+}++func TestConfigSnippet_DefaultLogPath(t *testing.T) {+ got, err := ConfigSnippet("")+ if err != nil {+ t.Fatalf("ConfigSnippet with empty path returned error: %v", err)+ }+ if !strings.Contains(got, DefaultLogPath) {+ t.Fatalf("ConfigSnippet with empty logPath should use DefaultLogPath %q, got: %s", DefaultLogPath, got)+ }+}diff --git a/cli/beacon/internal/endpoint/cloudwatch/pack/README.md b/cli/beacon/internal/endpoint/cloudwatch/pack/README.mdnew file mode 100644index 00000000..d09a5606--- /dev/null+++ b/cli/beacon/internal/endpoint/cloudwatch/pack/README.md@@ -0,0 +1,143 @@+# Beacon Endpoint Agent AWS CloudWatch Logs Pack++This pack forwards Beacon endpoint JSONL events into AWS CloudWatch Logs. Beacon+still writes one local source of truth: `runtime.jsonl`. AWS credentials,+profiles, IAM roles, log groups, retention settings, and encryption stay in AWS,+Vector, or customer-managed deployment tooling, not in Beacon endpoint+configuration.++## Prerequisites++- Beacon endpoint installed and writing local JSONL.+- An AWS CloudWatch Logs log group for Beacon runtime logs.+- An IAM role or credentials available through the standard AWS credential+ provider chain for the process running Vector.++Recommended log group and stream layout:++```text+/aws/beacon/runtime+beacon-runtime/<hostname>+```++Example least-privilege IAM policy for a pre-created log group:++```json+{+ "Version": "2012-10-17",+ "Statement": [+ {+ "Effect": "Allow",+ "Action": [+ "logs:CreateLogStream",+ "logs:DescribeLogStreams",+ "logs:PutLogEvents"+ ],+ "Resource": "arn:aws:logs:us-east-1:111122223333:log-group:/aws/beacon/runtime:*"+ }+ ]+}+```++Add `logs:CreateLogGroup`, KMS permissions, or account-specific conditions only+if your AWS controls require them. Configure CloudWatch Logs retention, log group+encryption, subscription filters, exports, and access policies in AWS.++## Install++Generate this pack:++```bash+beacon endpoint cloudwatch install-pack --output ./beacon-cloudwatch-pack+```++The generated `vector.toml` points at the Beacon log path selected by the CLI:++- User mode: `~/.beacon/endpoint/logs/runtime.jsonl`+- System mode: `/var/log/beacon-agent/runtime.jsonl`+- Custom mode: the value passed with `--log-path`++For MDM or managed endpoint deployment, prefer Beacon system mode so your+customer-managed log shipper can tail `/var/log/beacon-agent/runtime.jsonl`+without per-user home directory ACLs.++## Production Forwarding++Use the generated Vector config as a customer-managed host-agent forwarding+template. Beacon remains the local JSONL producer; Vector tails `runtime.jsonl`,+checkpoints file offsets in its `data_dir`, batches Beacon events, and writes+JSON log events into AWS CloudWatch Logs.++Install Vector using your normal endpoint management tooling, then copy the+generated config into Vector's config directory. On a macOS system-mode Beacon+deployment, the generated config tails `/var/log/beacon-agent/runtime.jsonl`:++```bash+sudo mkdir -p /etc/vector+sudo cp ./beacon-cloudwatch-pack/vector.toml /etc/vector/beacon-cloudwatch.toml+export BEACON_CLOUDWATCH_LOG_GROUP="/aws/beacon/runtime"+export BEACON_CLOUDWATCH_LOG_STREAM_PREFIX="beacon-runtime"+export AWS_REGION="us-east-1"+vector validate /etc/vector/beacon-cloudwatch.toml+vector --config /etc/vector/beacon-cloudwatch.toml+```++In managed deployments, provide `BEACON_CLOUDWATCH_LOG_GROUP`, optional+`BEACON_CLOUDWATCH_LOG_STREAM_PREFIX`, `AWS_REGION`, and any AWS+credential-provider settings through the Vector service environment, host+identity, or MDM/secret tooling. Do not store AWS destination secrets in Beacon+endpoint configuration.++The Vector template is intentionally simple and expects a Vector version with+the `file` source, `remap` transform, and `aws_cloudwatch_logs` sink. It parses+each Beacon JSONL line and re-encodes the original Beacon event as a JSON+CloudWatch Logs event, without a Vector wrapper.++If you adapt the config or use another forwarder, it should:++- checkpoint file offsets,+- batch JSON records,+- use host-specific log streams,+- retry transient failures without duplicating the whole file,+- keep AWS credentials, IAM roles, log group retention, and encryption outside+ Beacon endpoint configuration.++## Validate++Write a fresh Beacon validation event:++```bash+beacon endpoint cloudwatch validate+```++Wait for your production forwarder to ship the new line. Beacon can write the+local validation event, but remote delivery must be confirmed with AWS tooling:++```bash+aws logs filter-log-events \+ --log-group-name "$BEACON_CLOUDWATCH_LOG_GROUP" \+ --filter-pattern '"Beacon endpoint AWS CloudWatch Logs validation event"' \+ --region "$AWS_REGION"+```++CloudWatch Logs Insights query:++```sql+fields @timestamp, vendor, product, destination.type, destination.mode, message+| filter message like /Beacon endpoint AWS CloudWatch Logs validation event/+| sort @timestamp desc+| limit 20+```++Expected validation fields:++```text+vendor=beacon product=endpoint-agent destination.type=cloudwatch destination.mode=aws_cloudwatch_logs+```++## Content Retention++Beacon content retention defaults to `full`, so prompt text, tool input, command+output, raw tool payloads, and other retained content may be forwarded to AWS+CloudWatch Logs. Use Beacon's `metadata` or `redacted` content retention modes+for stricter deployments.diff --git a/cli/beacon/internal/endpoint/cloudwatch/pack/sample-event.jsonl b/cli/beacon/internal/endpoint/cloudwatch/pack/sample-event.jsonlnew file mode 100644index 00000000..9b4f2784--- /dev/null+++ b/cli/beacon/internal/endpoint/cloudwatch/pack/sample-event.jsonl@@ -0,0 +1,3 @@+{"timestamp":"2026-05-11T22:20:00Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"agent.detected","category":"validation"},"severity":"info","endpoint":{"hostname":"example-mac","os":"darwin","agent_version":"0.1.0"},"user":{"name":"local-user"},"harness":{"name":"test_harness","version":"test"},"destination":{"type":"cloudwatch","mode":"aws_cloudwatch_logs","status":"configured"},"message":"Beacon endpoint AWS CloudWatch Logs validation event"}+{"timestamp":"2026-05-11T22:21:00Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"command.executed","category":"command"},"severity":"info","endpoint":{"hostname":"example-mac","os":"darwin","agent_version":"0.1.0"},"user":{"name":"local-user","uid":"501"},"harness":{"name":"cursor","version":"0.50.0"},"session":{"id":"conversation-1","working_directory":"/Users/local-user/repo"},"tool":{"name":"Shell","command":"go test ./...","path":"/bin/zsh"},"command":{"command":"go test ./...","exit_code":0,"duration_ms":1234},"content":{"retention":"full","included":true},"repository":"file:///Users/local-user/repo","branch":"main","message":"Shell command executed"}+{"timestamp":"2026-05-11T22:22:00Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"metric.observed","category":"metric"},"severity":"info","endpoint":{"hostname":"example-mac","os":"darwin","agent_version":"0.1.0"},"user":{"name":"local-user"},"harness":{"name":"codex_cli"},"content":{"retention":"full","included":true},"raw":{"otel_signal":"metrics","metric_name":"codex.tool.call.duration_ms","metric_description":"Codex tool call duration","metric_unit":"ms","attributes":{"service.name":"codex","session.id":"conversation-2"}},"message":"codex.tool.call.duration_ms"}diff --git a/cli/beacon/internal/endpoint/cloudwatch/pack/vector.toml.tmpl b/cli/beacon/internal/endpoint/cloudwatch/pack/vector.toml.tmplnew file mode 100644index 00000000..07e51066--- /dev/null+++ b/cli/beacon/internal/endpoint/cloudwatch/pack/vector.toml.tmpl@@ -0,0 +1,41 @@+# Beacon Endpoint Agent -> AWS CloudWatch Logs+#+# Run Vector as a customer-managed host agent. Keep AWS credentials, profiles,+# instance roles, log groups, retention, and encryption in AWS or deployment+# tooling, not in Beacon config. This template relies on the standard AWS+# credential provider chain.++data_dir = "/var/lib/vector/beacon-cloudwatch"++[sources.beacon_runtime]+type = "file"+include = ["{{LOG_PATH}}"]+read_from = "end"++[transforms.beacon_json]+type = "remap"+inputs = ["beacon_runtime"]+source = '''+. = parse_json!(.message)+'''++[sinks.beacon_cloudwatch]+type = "aws_cloudwatch_logs"+inputs = ["beacon_json"]+group_name = "${BEACON_CLOUDWATCH_LOG_GROUP}"+stream_name = "${BEACON_CLOUDWATCH_LOG_STREAM_PREFIX:-beacon-runtime}/${HOSTNAME:-unknown-host}"+region = "${AWS_REGION:-us-east-1}"+create_missing_group = false+create_missing_stream = true++[sinks.beacon_cloudwatch.encoding]+codec = "json"++[sinks.beacon_cloudwatch.batch]+max_events = 1000+timeout_secs = 30++[sinks.beacon_cloudwatch.request]+retry_attempts = 10+retry_initial_backoff_secs = 1+retry_max_duration_secs = 300diff --git a/packaging/macos/README.md b/packaging/macos/README.mdindex 9383da8c..4ca7148f 100644--- a/packaging/macos/README.md+++ b/packaging/macos/README.md@@ -115,6 +115,23 @@ not in Beacon endpoint configuration. For production forwarding, use a tailingshipper that checkpoints offsets, batches JSONL records, and avoids repeatedlyuploading the whole file.+For AWS CloudWatch Logs, keep Beacon as the local JSONL producer and deploy a+customer-managed Vector host agent that tails+`/var/log/beacon-agent/runtime.jsonl` into a CloudWatch Logs log group. Generate+Beacon's AWS CloudWatch Logs content pack for setup guidance, a Vector config,+sample events, and validation search guidance:++```bash+/opt/beacon/bin/beacon endpoint cloudwatch install-pack --system --output ./beacon-cloudwatch-pack+/opt/beacon/bin/beacon endpoint cloudwatch validate --system+```++Provide `BEACON_CLOUDWATCH_LOG_GROUP`, optional+`BEACON_CLOUDWATCH_LOG_STREAM_PREFIX`, `AWS_REGION`, and AWS+credential-provider settings through the Vector service environment, host+identity, MDM, or secret tooling. Keep AWS credentials, IAM roles, log group+retention, and encryption outside Beacon endpoint configuration.+Environment variables take precedence, followed by MDM script parameters:```text