Skip to content

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

add cloudwatch support

Justin D'Souzaa7d197212821
diff --git a/.gitignore b/.gitignore
index 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.jsonl
diff --git a/README.md b/README.md
index 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.md
index 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 Beacon
endpoint 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
```bash
diff --git a/cli/beacon/cmd/endpoint.go b/cli/beacon/cmd/endpoint.go
index 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.outputDir
diff --git a/cli/beacon/cmd/endpoint_diagnostics.go b/cli/beacon/cmd/endpoint_diagnostics.go
index 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.go
index 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.logPath
oldUserMode := endpointOpts.userMode
diff --git a/cli/beacon/internal/endpoint/cloudwatch/cloudwatch.go b/cli/beacon/internal/endpoint/cloudwatch/cloudwatch.go
new file mode 100644
index 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.go
new file mode 100644
index 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.md
new file mode 100644
index 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.jsonl
new file mode 100644
index 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.tmpl
new file mode 100644
index 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 = 300
diff --git a/packaging/macos/README.md b/packaging/macos/README.md
index 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 tailing
shipper that checkpoints offsets, batches JSONL records, and avoids repeatedly
uploading 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