Skip to content

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

Add opt-in full-content capture to endpoint inventory

Claude3b60e455f3ff
diff --git a/cli/beacon/cmd/endpoint.go b/cli/beacon/cmd/endpoint.go
index 0b70b1a9..fc44c7f4 100644
--- a/cli/beacon/cmd/endpoint.go
+++ b/cli/beacon/cmd/endpoint.go
@@ -73,6 +73,7 @@ var endpointOpts struct {
inventoryMCP bool
inventorySkills bool
inventoryHooks bool
+ inventoryContents bool
inventoryHeartbeatForce bool
inventoryHeartbeatConfig string
inventoryWorkingDir string
@@ -435,6 +436,7 @@ func init() {
endpointInventoryCmd.Flags().BoolVar(&endpointOpts.inventoryMCP, "mcp", false, "Show only MCP server inventory and source configs")
endpointInventoryCmd.Flags().BoolVar(&endpointOpts.inventorySkills, "skills", false, "Show only local agent skill inventory")
endpointInventoryCmd.Flags().BoolVar(&endpointOpts.inventoryHooks, "hooks", false, "Show only hook integration and hook config inventory")
+ endpointInventoryCmd.Flags().BoolVar(&endpointOpts.inventoryContents, "contents", false, "Include redacted, size-limited config/hook/skill file contents and full MCP server definitions")
endpointInventoryCmd.Flags().BoolVar(&endpointOpts.writeInventoryEvent, "write-event", false, "Append inventory events to the endpoint runtime log")
endpointInventoryHeartbeatCmd.Flags().BoolVar(&endpointOpts.inventoryHeartbeatForce, "force", false, "Write inventory heartbeat even when TTL has not expired")
endpointInventoryHeartbeatCmd.Flags().StringVar(&endpointOpts.inventoryHeartbeatConfig, "config", "", "Endpoint config path")
@@ -450,6 +452,7 @@ func init() {
topLevelInventoryCmd.Flags().BoolVar(&endpointOpts.inventoryMCP, "mcp", false, "Show only MCP server inventory and source configs")
topLevelInventoryCmd.Flags().BoolVar(&endpointOpts.inventorySkills, "skills", false, "Show only local agent skill inventory")
topLevelInventoryCmd.Flags().BoolVar(&endpointOpts.inventoryHooks, "hooks", false, "Show only hook integration and hook config inventory")
+ topLevelInventoryCmd.Flags().BoolVar(&endpointOpts.inventoryContents, "contents", false, "Include redacted, size-limited config/hook/skill file contents and full MCP server definitions")
topLevelInventoryCmd.Flags().BoolVar(&endpointOpts.writeInventoryEvent, "write-event", false, "Append inventory events to the endpoint runtime log")
endpointTestEventCmd.Flags().BoolVar(&endpointOpts.jsonOutput, "json", false, "Print validation stages as JSON")
endpointBundleDiagnosticsCmd.Flags().StringVar(&endpointOpts.outputDir, "output", "", "Output directory for diagnostics bundle")
diff --git a/cli/beacon/cmd/endpoint_diagnostics.go b/cli/beacon/cmd/endpoint_diagnostics.go
index 35ebda96..8773cba1 100644
--- a/cli/beacon/cmd/endpoint_diagnostics.go
+++ b/cli/beacon/cmd/endpoint_diagnostics.go
@@ -211,7 +211,7 @@ func runEndpointInventory(cmd *cobra.Command, args []string) error {
if err != nil {
return err
}
- configInventory := endpointinventory.Scan(endpointinventory.Options{})
+ configInventory := endpointinventory.Scan(endpointinventory.Options{IncludeContents: endpointOpts.inventoryContents})
result := inventoryResult{
GeneratedAt: time.Now().UTC().Format(time.RFC3339),
RuntimeLog: status.RuntimeLog,
@@ -267,6 +267,7 @@ func runEndpointInventory(cmd *cobra.Command, args []string) error {
path = config.PathHash
}
fmt.Printf("Config: %s scope=%s status=%s mcp_servers=%d path=%s\n", config.Runtime, config.Scope, config.ParserStatus, config.MCPServerCount, path)
+ printInventoryContent(config.Content)
}
if showAllInventorySections || endpointOpts.inventoryMCP {
for _, server := range result.MCPServers {
@@ -275,6 +276,7 @@ func runEndpointInventory(cmd *cobra.Command, args []string) error {
name = server.ServerNameHash
}
fmt.Printf("MCP: %s %s scope=%s transport=%s command_present=%t args=%d env_keys=%d\n", server.Runtime, name, server.SourceScope, server.Transport, server.CommandPresent, server.ArgsCount, server.EnvKeyCount)
+ printInventoryDefinition(server.Definition)
}
}
if showAllInventorySections || endpointOpts.inventorySkills {
@@ -294,6 +296,7 @@ func runEndpointInventory(cmd *cobra.Command, args []string) error {
path = skill.ManifestPathHash
}
fmt.Printf("Skill: %s %s scope=%s status=%s path=%s\n", skill.Runtime, name, skill.SourceScope, skill.ParserStatus, path)
+ printInventoryContent(skill.Content)
}
}
if endpointOpts.writeInventoryEvent {
@@ -302,6 +305,28 @@ func runEndpointInventory(cmd *cobra.Command, args []string) error {
return nil
}
+func printInventoryContent(content *endpointinventory.CapturedContent) {
+ if content == nil {
+ return
+ }
+ fmt.Printf(" --- content (%d bytes, redactions=%d, truncated=%t) ---\n", content.Bytes, content.RedactedCount, content.Truncated)
+ for _, line := range strings.Split(content.Text, "\n") {
+ fmt.Printf(" %s\n", line)
+ }
+ fmt.Println(" --- end content ---")
+}
+
+func printInventoryDefinition(def map[string]interface{}) {
+ if len(def) == 0 {
+ return
+ }
+ encoded, err := json.MarshalIndent(def, " ", " ")
+ if err != nil {
+ return
+ }
+ fmt.Printf(" --- definition ---\n %s\n --- end definition ---\n", string(encoded))
+}
+
func filterInventoryDefaults(result inventoryResult) inventoryResult {
if endpointOpts.allTargets {
return result
@@ -451,9 +476,11 @@ func writeInventoryHeartbeat(cfg endpointconfig.Config, settings endpointconfig.
return inventoryHeartbeatWriteResult{SkippedReason: "attempt_backoff", PreviousDigest: state.LastSnapshotDigest}, nil
}
scanOpts := endpointinventory.Options{
- WorkingDir: workingDir,
- Runtimes: settings.Runtimes,
- Now: func() time.Time { return now },
+ WorkingDir: workingDir,
+ Runtimes: settings.Runtimes,
+ Now: func() time.Time { return now },
+ IncludeContents: settings.IncludeContents,
+ MaxContentBytes: settings.MaxContentBytes,
}
inventoryResult := endpointinventory.Scan(scanOpts)
digest := endpointinventory.SnapshotDigest(inventoryResult)
diff --git a/cli/beacon/internal/endpoint/config/config.go b/cli/beacon/internal/endpoint/config/config.go
index ee17708a..440bb7f8 100644
--- a/cli/beacon/internal/endpoint/config/config.go
+++ b/cli/beacon/internal/endpoint/config/config.go
@@ -43,15 +43,19 @@ type Collector struct {
}
type Inventory struct {
- Enabled *bool `json:"enabled,omitempty"`
- TTLSeconds int `json:"ttl_seconds,omitempty"`
- Runtimes []string `json:"runtimes,omitempty"`
+ Enabled *bool `json:"enabled,omitempty"`
+ TTLSeconds int `json:"ttl_seconds,omitempty"`
+ Runtimes []string `json:"runtimes,omitempty"`
+ IncludeContents *bool `json:"include_contents,omitempty"`
+ MaxContentBytes int `json:"max_content_bytes,omitempty"`
}
type InventorySettings struct {
- Enabled bool
- TTLSeconds int
- Runtimes []string
+ Enabled bool
+ TTLSeconds int
+ Runtimes []string
+ IncludeContents bool
+ MaxContentBytes int
}
type Destinations struct {
@@ -126,6 +130,12 @@ func InventoryConfig(cfg Config) InventorySettings {
if len(cfg.Inventory.Runtimes) > 0 {
settings.Runtimes = append([]string(nil), cfg.Inventory.Runtimes...)
}
+ if cfg.Inventory.IncludeContents != nil {
+ settings.IncludeContents = *cfg.Inventory.IncludeContents
+ }
+ if cfg.Inventory.MaxContentBytes > 0 {
+ settings.MaxContentBytes = cfg.Inventory.MaxContentBytes
+ }
return settings
}
diff --git a/cli/beacon/internal/endpoint/config/config_test.go b/cli/beacon/internal/endpoint/config/config_test.go
index e0f52474..ff3152cd 100644
--- a/cli/beacon/internal/endpoint/config/config_test.go
+++ b/cli/beacon/internal/endpoint/config/config_test.go
@@ -32,6 +32,21 @@ func TestDefaultUserConfigUsesHomeScopedPaths(t *testing.T) {
if !inventory.Enabled || inventory.TTLSeconds != 86400 || len(inventory.Runtimes) != 2 || inventory.Runtimes[0] != "cursor" || inventory.Runtimes[1] != "claude_code" {
t.Fatalf("unexpected inventory defaults: %#v", inventory)
}
+ if inventory.IncludeContents || inventory.MaxContentBytes != 0 {
+ t.Fatalf("content capture should default off: %#v", inventory)
+ }
+}
+
+func TestInventoryContentCaptureOptIn(t *testing.T) {
+ include := true
+ cfg := Config{Inventory: &Inventory{IncludeContents: &include, MaxContentBytes: 4096}}
+ inventory := InventoryConfig(cfg)
+ if !inventory.IncludeContents {
+ t.Fatal("IncludeContents = false, want true when opted in")
+ }
+ if inventory.MaxContentBytes != 4096 {
+ t.Fatalf("MaxContentBytes = %d, want 4096", inventory.MaxContentBytes)
+ }
}
func TestSaveLoadRoundTrip(t *testing.T) {
diff --git a/cli/beacon/internal/endpoint/inventory/content.go b/cli/beacon/internal/endpoint/inventory/content.go
new file mode 100644
index 00000000..cb309108
--- /dev/null
+++ b/cli/beacon/internal/endpoint/inventory/content.go
@@ -0,0 +1,155 @@
+package inventory
+
+import (
+ "regexp"
+ "strings"
+ "unicode/utf8"
+)
+
+// DefaultMaxContentBytes caps how much redacted text is retained per captured
+// file when content capture is requested. Files larger than the cap are
+// truncated to a UTF-8 rune boundary and flagged as truncated.
+const DefaultMaxContentBytes = 64 * 1024
+
+const redactedPlaceholder = "***REDACTED***"
+
+// secretMarkers are the substring markers that identify sensitive config keys.
+// They are shared by the env-key filter and the content/definition redactors so
+// captured contents and summarized metadata stay consistent.
+var secretMarkers = []string{"TOKEN", "SECRET", "PASSWORD", "KEY", "AUTH", "CREDENTIAL"}
+
+// secretAssignmentRE matches a `key: value` or `key = value` assignment where
+// the key contains a secret marker, across JSON, TOML, YAML, and shell-style
+// content. The value is captured separately so it can be replaced while
+// preserving the surrounding key, separator, and quote style.
+var secretAssignmentRE = regexp.MustCompile(
+ `(?i)("?[A-Za-z0-9_.\-]*(?:` + strings.ToLower(strings.Join(secretMarkers, "|")) + `)[A-Za-z0-9_.\-]*"?)(\s*[:=]\s*)` +
+ "(\"(?:[^\"\\\\]|\\\\.)*\"|'[^']*'|`[^`]*`|[^\\s,}\\]\\n#]+)",
+)
+
+// CapturedContent is the opt-in raw body of a config, hook, or skill file with
+// sensitive values redacted and the body truncated to a size cap. It is only
+// populated when content capture is explicitly requested.
+type CapturedContent struct {
+ Bytes int `json:"bytes"`
+ Truncated bool `json:"truncated,omitempty"`
+ RedactedCount int `json:"redacted_count,omitempty"`
+ Text string `json:"text"`
+}
+
+// contentOptions controls opt-in raw content capture during a scan.
+type contentOptions struct {
+ include bool
+ maxBytes int
+}
+
+func (c contentOptions) limit() int {
+ if c.maxBytes > 0 {
+ return c.maxBytes
+ }
+ return DefaultMaxContentBytes
+}
+
+// captureContent redacts secrets in the raw file body and truncates the result
+// to maxBytes on a UTF-8 rune boundary. Redaction runs before truncation so a
+// secret can never be partially exposed by the cut.
+func captureContent(data []byte, maxBytes int) *CapturedContent {
+ redacted, count := redactSecrets(string(data))
+ truncated := false
+ if maxBytes > 0 && len(redacted) > maxBytes {
+ redacted = truncateUTF8(redacted, maxBytes)
+ truncated = true
+ }
+ return &CapturedContent{
+ Bytes: len(data),
+ Truncated: truncated,
+ RedactedCount: count,
+ Text: redacted,
+ }
+}
+
+// redactSecrets replaces the values of secret-looking assignments with a
+// placeholder and returns the redacted text plus the number of redactions.
+func redactSecrets(text string) (string, int) {
+ count := 0
+ out := secretAssignmentRE.ReplaceAllStringFunc(text, func(match string) string {
+ sub := secretAssignmentRE.FindStringSubmatch(match)
+ if len(sub) != 4 {
+ return match
+ }
+ count++
+ return sub[1] + sub[2] + redactValueLiteral(sub[3])
+ })
+ return out, count
+}
+
+// redactValueLiteral replaces a captured value with the placeholder while
+// preserving the original quote style so the surrounding structure stays valid.
+func redactValueLiteral(value string) string {
+ switch {
+ case strings.HasPrefix(value, `"`):
+ return `"` + redactedPlaceholder + `"`
+ case strings.HasPrefix(value, "'"):
+ return "'" + redactedPlaceholder + "'"
+ case strings.HasPrefix(value, "`"):
+ return "`" + redactedPlaceholder + "`"
+ default:
+ return redactedPlaceholder
+ }
+}
+
+// redactStructured walks a parsed config value and replaces string values held
+// under secret-looking keys with the placeholder, leaving structure intact.
+func redactStructured(value interface{}) interface{} {
+ switch typed := value.(type) {
+ case map[string]interface{}:
+ out := make(map[string]interface{}, len(typed))
+ for key, val := range typed {
+ if containsSecretMarker(key) {
+ out[key] = redactedPlaceholder
+ continue
+ }
+ out[key] = redactStructured(val)
+ }
+ return out
+ case []interface{}:
+ out := make([]interface{}, len(typed))
+ for i, item := range typed {
+ out[i] = redactStructured(item)
+ }
+ return out
+ default:
+ return value
+ }
+}
+
+// redactStructuredMap redacts a definition block and returns it as a map.
+func redactStructuredMap(def map[string]interface{}) map[string]interface{} {
+ if m, ok := redactStructured(def).(map[string]interface{}); ok {
+ return m
+ }
+ return nil
+}
+
+func containsSecretMarker(key string) bool {
+ upper := strings.ToUpper(key)
+ for _, marker := range secretMarkers {
+ if strings.Contains(upper, marker) {
+ return true
+ }
+ }
+ return false
+}
+
+func truncateUTF8(s string, max int) string {
+ if max <= 0 {
+ return ""
+ }
+ if len(s) <= max {
+ return s
+ }
+ for max > 0 && !utf8.RuneStart(s[max]) {
+ max--
+ }
+ return s[:max]
+}
diff --git a/cli/beacon/internal/endpoint/inventory/inventory.go b/cli/beacon/internal/endpoint/inventory/inventory.go
index 3287ec72..d5d58072 100644
--- a/cli/beacon/internal/endpoint/inventory/inventory.go
+++ b/cli/beacon/internal/endpoint/inventory/inventory.go
@@ -56,6 +56,12 @@ type Options struct {
WorkingDir string
Runtimes []string
Now func() time.Time
+ // IncludeContents opts into capturing redacted, size-limited raw bodies of
+ // config, hook, and skill files plus full (redacted) MCP server definitions.
+ // When false (the default) inventory stays metadata- and hash-only.
+ IncludeContents bool
+ // MaxContentBytes caps retained content per file. Zero uses DefaultMaxContentBytes.
+ MaxContentBytes int
}
type Result struct {
@@ -87,9 +93,10 @@ type Config struct {
ParserStatus string `json:"parser_status"`
FileSHA256 string `json:"file_sha256,omitempty"`
ModifiedAt string `json:"modified_at,omitempty"`
- MCPServerCount int `json:"mcp_server_count"`
- BeaconManaged bool `json:"beacon_managed"`
- Redaction string `json:"redaction"`
+ MCPServerCount int `json:"mcp_server_count"`
+ BeaconManaged bool `json:"beacon_managed"`
+ Redaction string `json:"redaction"`
+ Content *CapturedContent `json:"content,omitempty"`
}
type MCPServer struct {
@@ -107,9 +114,10 @@ type MCPServer struct {
URLPresent bool `json:"url_present"`
EnvKeys []string `json:"env_keys,omitempty"`
EnvKeyCount int `json:"env_key_count,omitempty"`
- DefinitionHash string `json:"definition_hash"`
- ParserStatus string `json:"parser_status"`
- Redaction string `json:"redaction"`
+ DefinitionHash string `json:"definition_hash"`
+ ParserStatus string `json:"parser_status"`
+ Redaction string `json:"redaction"`
+ Definition map[string]interface{} `json:"definition,omitempty"`
}
type candidate struct {
@@ -144,12 +152,13 @@ func Scan(opts Options) Result {
WorkDirHash: hashString(wd),
},
}
+ co := contentOptions{include: opts.IncludeContents, maxBytes: opts.MaxContentBytes}
for _, item := range filterCandidates(candidates(home, wd), opts.Runtimes) {
- config, servers := inspectCandidate(item, redaction)
+ config, servers := inspectCandidate(item, redaction, co)
result.Configs = append(result.Configs, config)
result.MCPServers = append(result.MCPServers, servers...)
}
- result.Skills = scanSkills(home, wd, redaction, opts.Runtimes)
+ result.Skills = scanSkills(home, wd, redaction, opts.Runtimes, co)
return result
}
@@ -317,7 +326,7 @@ func shellProfilePath(home string) string {
}
}
-func inspectCandidate(item candidate, redaction string) (Config, []MCPServer) {
+func inspectCandidate(item candidate, redaction string, co contentOptions) (Config, []MCPServer) {
config := Config{
Runtime: item.runtime,
Path: valueForPath(item.path, redaction),
@@ -352,8 +361,11 @@ func inspectCandidate(item candidate, redaction string) (Config, []MCPServer) {
config.Readable = true
config.FileSHA256 = hashBytes(data)
config.BeaconManaged = beaconManaged(item, data)
+ if co.include {
+ config.Content = captureContent(data, co.limit())
+ }
- servers, parseErr := parseMCPServers(item, data, redaction)
+ servers, parseErr := parseMCPServers(item, data, redaction, co)
config.MCPServerCount = len(servers)
config.ParserStatus = StatusOK
if parseErr != nil {
@@ -363,7 +375,7 @@ func inspectCandidate(item candidate, redaction string) (Config, []MCPServer) {
return config, servers
}
-func parseMCPServers(item candidate, data []byte, redaction string) ([]MCPServer, error) {
+func parseMCPServers(item candidate, data []byte, redaction string, co contentOptions) ([]MCPServer, error) {
switch item.format {
case formatMetadataOnly:
return nil, nil
@@ -372,38 +384,38 @@ func parseMCPServers(item candidate, data []byte, redaction string) ([]MCPServer
if err := json.Unmarshal(data, &root); err != nil {
return nil, err
}
- return serversFromMap(item, root, redaction), nil
+ return serversFromMap(item, root, redaction, co), nil
case formatTOML:
var root map[string]interface{}
if err := toml.Unmarshal(data, &root); err != nil {
return nil, err
}
- return serversFromMap(item, root, redaction), nil
+ return serversFromMap(item, root, redaction, co), nil
case formatYAML:
var root map[string]interface{}
if err := yaml.Unmarshal(data, &root); err != nil {
return nil, err
}
- return serversFromMap(item, root, redaction), nil
+ return serversFromMap(item, root, redaction, co), nil
default:
return nil, fmt.Errorf("unsupported config format %q", item.format)
}
}
-func serversFromMap(item candidate, root map[string]interface{}, redaction string) []MCPServer {
+func serversFromMap(item candidate, root map[string]interface{}, redaction string, co contentOptions) []MCPServer {
var servers []MCPServer
for _, key := range []string{"mcpServers", "mcp_servers", "servers"} {
if raw, ok := root[key]; ok {
- servers = append(servers, serversFromBlock(item, raw, redaction)...)
+ servers = append(servers, serversFromBlock(item, raw, redaction, co)...)
}
}
if raw, ok := root["mcp"]; ok {
- servers = append(servers, serversFromBlock(item, raw, redaction)...)
+ servers = append(servers, serversFromBlock(item, raw, redaction, co)...)
}
return dedupeServers(servers)
}
-func serversFromBlock(item candidate, raw interface{}, redaction string) []MCPServer {
+func serversFromBlock(item candidate, raw interface{}, redaction string, co contentOptions) []MCPServer {
block, ok := raw.(map[string]interface{})
if !ok {
return nil
@@ -415,13 +427,13 @@ func serversFromBlock(item candidate, raw interface{}, redaction string) []MCPSe
continue
}
if looksLikeServerDefinition(def) {
- servers = append(servers, serverFromDefinition(item, name, def, redaction))
+ servers = append(servers, serverFromDefinition(item, name, def, redaction, co))
continue
}
for nestedName, nestedValue := range def {
nestedDef, ok := nestedValue.(map[string]interface{})
if ok && looksLikeServerDefinition(nestedDef) {
- servers = append(servers, serverFromDefinition(item, nestedName, nestedDef, redaction))
+ servers = append(servers, serverFromDefinition(item, nestedName, nestedDef, redaction, co))
}
}
}
@@ -437,7 +449,7 @@ func looksLikeServerDefinition(def map[string]interface{}) bool {
return false
}
-func serverFromDefinition(item candidate, name string, def map[string]interface{}, redaction string) MCPServer {
+func serverFromDefinition(item candidate, name string, def map[string]interface{}, redaction string, co contentOptions) MCPServer {
command := firstString(def["command"])
url := firstString(def["url"])
envKeys := mapKeys(def["env"])
@@ -462,6 +474,9 @@ func serverFromDefinition(item candidate, name string, def map[string]interface{
if command != "" {
server.CommandNameHash = hashString(filepath.Base(command))
}
+ if co.include {
+ server.Definition = redactStructuredMap(def)
+ }
return server
}
@@ -528,13 +543,7 @@ func valuesForEnvKeys(keys []string, redaction string) []string {
}
func safeEnvKey(key string) bool {
- upper := strings.ToUpper(key)
- for _, marker := range []string{"TOKEN", "SECRET", "PASSWORD", "KEY", "AUTH", "CREDENTIAL"} {
- if strings.Contains(upper, marker) {
- return false
- }
- }
- return true
+ return !containsSecretMarker(key)
}
func mapKeys(raw interface{}) []string {
diff --git a/cli/beacon/internal/endpoint/inventory/inventory_test.go b/cli/beacon/internal/endpoint/inventory/inventory_test.go
index 9258cc61..5e2a4c07 100644
--- a/cli/beacon/internal/endpoint/inventory/inventory_test.go
+++ b/cli/beacon/internal/endpoint/inventory/inventory_test.go
@@ -539,6 +539,158 @@ func TestReadStateTreatsEmptyFileAsFreshState(t *testing.T) {
}
}
+func TestScanOmitsContentsByDefault(t *testing.T) {
+ home := t.TempDir()
+ work := t.TempDir()
+ writeFile(t, filepath.Join(home, ".claude", "settings.json"), `{"mcpServers":{"fs":{"command":"npx","env":{"GITHUB_TOKEN":"ghp_secret"}}}}`)
+ writeFile(t, filepath.Join(home, ".cursor", "skills", "deploy", "SKILL.md"), "# Deploy\nbody")
+
+ result := Scan(Options{HomeDir: home, WorkingDir: work, Now: fixedNow})
+
+ for _, config := range result.Configs {
+ if config.Content != nil {
+ t.Fatalf("config %s retained content by default: %#v", config.Runtime, config.Content)
+ }
+ }
+ for _, server := range result.MCPServers {
+ if server.Definition != nil {
+ t.Fatalf("server %s retained definition by default: %#v", server.ServerName, server.Definition)
+ }
+ }
+ for _, skill := range result.Skills {
+ if skill.Content != nil {
+ t.Fatalf("skill %s retained content by default: %#v", skill.SkillName, skill.Content)
+ }
+ }
+}
+
+func TestScanCapturesRedactedContentsWhenRequested(t *testing.T) {
+ home := t.TempDir()
+ work := t.TempDir()
+ claudePath := filepath.Join(home, ".claude", "settings.json")
+ skillPath := filepath.Join(home, ".cursor", "skills", "deploy", "SKILL.md")
+ writeFile(t, claudePath, `{
+ "mcpServers": {
+ "github": {
+ "command": "gh",
+ "args": ["mcp", "serve"],
+ "env": {"GITHUB_TOKEN": "ghp_supersecret", "GH_HOST": "github.com"}
+ }
+ }
+}`)
+ writeFile(t, skillPath, "---\napi_key: sk-live-skillsecret\n---\n# Deploy instructions")
+
+ result := Scan(Options{
+ HomeDir: home,
+ WorkingDir: work,
+ Runtimes: []string{"claude_code", "cursor"},
+ IncludeContents: true,
+ Now: fixedNow,
+ })
+
+ config := findConfig(result.Configs, "claude_code", claudePath)
+ if config == nil || config.Content == nil {
+ t.Fatalf("expected captured content for claude config, got %#v", config)
+ }
+ if config.Content.Bytes == 0 || config.Content.RedactedCount < 1 {
+ t.Fatalf("content metadata = %#v, want bytes>0 and redactions>=1", config.Content)
+ }
+ if strings.Contains(config.Content.Text, "ghp_supersecret") {
+ t.Fatalf("captured content leaked secret: %s", config.Content.Text)
+ }
+ if !strings.Contains(config.Content.Text, redactedPlaceholder) {
+ t.Fatalf("captured content missing redaction placeholder: %s", config.Content.Text)
+ }
+ if !strings.Contains(config.Content.Text, "github.com") {
+ t.Fatalf("captured content dropped non-secret value: %s", config.Content.Text)
+ }
+
+ server := findServer(result.MCPServers, "claude_code", "github")
+ if server == nil || server.Definition == nil {
+ t.Fatalf("expected captured definition for github server, got %#v", server)
+ }
+ envBlock, ok := server.Definition["env"].(map[string]interface{})
+ if !ok {
+ t.Fatalf("definition env block missing: %#v", server.Definition)
+ }
+ if envBlock["GITHUB_TOKEN"] != redactedPlaceholder {
+ t.Fatalf("definition GITHUB_TOKEN not redacted: %#v", envBlock)
+ }
+ if envBlock["GH_HOST"] != "github.com" {
+ t.Fatalf("definition GH_HOST altered: %#v", envBlock)
+ }
+ if args, ok := server.Definition["args"].([]interface{}); !ok || len(args) != 2 {
+ t.Fatalf("definition args not preserved in full: %#v", server.Definition["args"])
+ }
+
+ skill := findSkill(result.Skills, "cursor", "deploy", skillPath)
+ if skill == nil || skill.Content == nil {
+ t.Fatalf("expected captured skill content, got %#v", skill)
+ }
+ if strings.Contains(skill.Content.Text, "sk-live-skillsecret") {
+ t.Fatalf("skill content leaked secret: %s", skill.Content.Text)
+ }
+ if !strings.Contains(skill.Content.Text, "Deploy instructions") {
+ t.Fatalf("skill content dropped instruction body: %s", skill.Content.Text)
+ }
+}
+
+func TestCapturedContentTruncatesToSizeLimit(t *testing.T) {
+ home := t.TempDir()
+ work := t.TempDir()
+ claudePath := filepath.Join(home, ".claude", "settings.json")
+ writeFile(t, claudePath, `{"note":"`+strings.Repeat("a", 500)+`"}`)
+
+ result := Scan(Options{
+ HomeDir: home,
+ WorkingDir: work,
+ Runtimes: []string{"claude_code"},
+ IncludeContents: true,
+ MaxContentBytes: 64,
+ Now: fixedNow,
+ })
+
+ config := findConfig(result.Configs, "claude_code", claudePath)
+ if config == nil || config.Content == nil {
+ t.Fatalf("expected captured content, got %#v", config)
+ }
+ if !config.Content.Truncated {
+ t.Fatal("expected content to be marked truncated")
+ }
+ if len(config.Content.Text) > 64 {
+ t.Fatalf("truncated text len = %d, want <= 64", len(config.Content.Text))
+ }
+ if config.Content.Bytes <= 64 {
+ t.Fatalf("Bytes should reflect original size, got %d", config.Content.Bytes)
+ }
+}
+
+func TestRedactSecretsAcrossFormats(t *testing.T) {
+ cases := []struct {
+ name string
+ input string
+ forbidden string
+ wantCount int
+ }{
+ {"json", `{"api_token": "ghp_x", "host": "h"}`, "ghp_x", 1},
+ {"toml", "GITHUB_TOKEN = \"tk_x\"\nname = \"ok\"", "tk_x", 1},
+ {"yaml", "password: hunter2\nuser: bob", "hunter2", 1},
+ {"shell", "export AWS_SECRET_ACCESS_KEY=abc123\nexport PATH=/bin", "abc123", 1},
+ {"none", `{"host": "example.com", "port": 8080}`, "", 0},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ out, count := redactSecrets(tc.input)
+ if count != tc.wantCount {
+ t.Fatalf("redaction count = %d, want %d (out=%q)", count, tc.wantCount, out)
+ }
+ if tc.forbidden != "" && strings.Contains(out, tc.forbidden) {
+ t.Fatalf("redacted output leaked %q: %s", tc.forbidden, out)
+ }
+ })
+ }
+}
+
func fixedNow() time.Time {
return time.Date(2026, 6, 5, 7, 0, 0, 0, time.UTC)
}
@@ -590,6 +742,15 @@ func assertServerPresent(servers []MCPServer, runtime, name string) bool {
return false
}
+func findServer(servers []MCPServer, runtime, name string) *MCPServer {
+ for i := range servers {
+ if servers[i].Runtime == runtime && servers[i].ServerName == name {
+ return &servers[i]
+ }
+ }
+ return nil
+}
+
func findConfig(configs []Config, runtime, path string) *Config {
pathHash := hashString(path)
for i := range configs {
diff --git a/cli/beacon/internal/endpoint/inventory/skills.go b/cli/beacon/internal/endpoint/inventory/skills.go
index 16f9a31e..f90df632 100644
--- a/cli/beacon/internal/endpoint/inventory/skills.go
+++ b/cli/beacon/internal/endpoint/inventory/skills.go
@@ -22,9 +22,10 @@ type Skill struct {
Readable bool `json:"readable"`
Reason string `json:"reason,omitempty"`
ParserStatus string `json:"parser_status"`
- FileSHA256 string `json:"file_sha256,omitempty"`
- ModifiedAt string `json:"modified_at,omitempty"`
- Redaction string `json:"redaction"`
+ FileSHA256 string `json:"file_sha256,omitempty"`
+ ModifiedAt string `json:"modified_at,omitempty"`
+ Redaction string `json:"redaction"`
+ Content *CapturedContent `json:"content,omitempty"`
}
type skillRoot struct {
@@ -33,10 +34,10 @@ type skillRoot struct {
scope string
}
-func scanSkills(home, wd, redaction string, runtimes []string) []Skill {
+func scanSkills(home, wd, redaction string, runtimes []string, co contentOptions) []Skill {
var skills []Skill
for _, root := range filterSkillRoots(skillRoots(home, wd), runtimes) {
- skills = append(skills, inspectSkillRoot(root, redaction)...)
+ skills = append(skills, inspectSkillRoot(root, redaction, co)...)
}
return dedupeSkills(skills)
}
@@ -79,7 +80,7 @@ func skillRoots(home, wd string) []skillRoot {
return out
}
-func inspectSkillRoot(root skillRoot, redaction string) []Skill {
+func inspectSkillRoot(root skillRoot, redaction string, co contentOptions) []Skill {
base := Skill{
Runtime: root.runtime,
RootPath: valueForPath(root.path, redaction),
@@ -123,7 +124,7 @@ func inspectSkillRoot(root skillRoot, redaction string) []Skill {
if _, err := os.Stat(manifestPath); os.IsNotExist(err) {
continue
}
- skills = append(skills, inspectSkillManifest(root, entry.Name(), manifestPath, redaction))
+ skills = append(skills, inspectSkillManifest(root, entry.Name(), manifestPath, redaction, co))
}
if len(skills) == 0 {
return nil
@@ -131,7 +132,7 @@ func inspectSkillRoot(root skillRoot, redaction string) []Skill {
return skills
}
-func inspectSkillManifest(root skillRoot, name, manifestPath, redaction string) Skill {
+func inspectSkillManifest(root skillRoot, name, manifestPath, redaction string, co contentOptions) Skill {
skill := Skill{
Runtime: root.runtime,
SkillName: valueForName(name, redaction),
@@ -167,6 +168,9 @@ func inspectSkillManifest(root skillRoot, name, manifestPath, redaction string)
}
skill.Readable = true
skill.FileSHA256 = hashBytes(data)
+ if co.include {
+ skill.Content = captureContent(data, co.limit())
+ }
skill.ParserStatus = StatusOK
return skill
}
diff --git a/docs/cli/endpoint-inventory.mdx b/docs/cli/endpoint-inventory.mdx
index 5e43de18..362d9a8a 100644
--- a/docs/cli/endpoint-inventory.mdx
+++ b/docs/cli/endpoint-inventory.mdx
@@ -23,7 +23,7 @@ Inventory can include:
- Detected supported runtimes and telemetry status, including MDM-managed launch-environment state for GitHub Copilot CLI and Factory Droid
- Hook integration status for Antigravity CLI, Claude Code, Cursor, Devin CLI, Devin Desktop, Factory Droid, Grok Build, Hermes Agent, and OpenCode
- Supported agent configuration files and MCP server configuration context where Beacon can inspect them locally, including Claude Code `~/.claude.json` and Cursor `mcp.json`
-- Local agent skill manifests discovered under supported skill roots, including symlinked Claude Code skill directories, reported as metadata and hashes only
+- Local agent skill manifests discovered under supported skill roots, including symlinked Claude Code skill directories, reported as metadata and hashes by default (add `--contents` for redacted full bodies)
- Recently observed Beacon runtime events when the runtime log exists
- Admin-configured integration observations such as Claude Cowork and OpenClaw Gateway events
@@ -37,6 +37,27 @@ Use the section filters when you only need one inventory surface:
The section filters can be combined. For example, `--mcp --skills --json` prints only MCP and skill inventory buckets in the JSON output.
+## Capturing Full Definitions
+
+By default inventory is metadata- and hash-only: it reports paths, hashes, MCP transport, command basenames, argument counts, and safe environment key names, but never the raw file bodies.
+
+Add `--contents` when you need to see the **full definitions** of config, hook, and skill files:
+
+- Each config and hook file gains a `content` block with the raw file body.
+- Each skill manifest gains a `content` block with the `SKILL.md` body.
+- Each MCP server gains a full `definition` block (complete command, arguments, URL, and environment) instead of only the summarized metadata.
+
+Captured contents are always passed through local redaction and a size limit:
+
+- Values held under secret-looking keys (matching `TOKEN`, `SECRET`, `PASSWORD`, `KEY`, `AUTH`, or `CREDENTIAL`) are replaced with `***REDACTED***`. The `content.redacted_count` field reports how many values were redacted.
+- Bodies are truncated to a per-file byte cap (64 KiB by default) and flagged with `content.truncated`. The `content.bytes` field always reports the original file size.
+
+```bash title="Show full, redacted MCP definitions"
+beacon endpoint inventory --mcp --contents
+```
+
+Content capture is opt-in and offline; `--contents` only reads files inventory already inspects locally.
+
## Inventory Heartbeats
Cursor and Claude Code endpoint hooks can periodically append inventory telemetry to a separate `inventory_state.jsonl` file beside `runtime.jsonl`:
@@ -44,16 +65,20 @@ Cursor and Claude Code endpoint hooks can periodically append inventory telemetr
- `inventory.heartbeat` records that Beacon checked local agent configuration inventory, including counts and a snapshot digest.
- `inventory.snapshot` records the current metadata-only inventory when the snapshot changed or when inventory is first initialized.
-Inventory snapshots include config file metadata, MCP server metadata, skill metadata, and hook config metadata. They do not include skill instruction bodies, MCP secret values, full environment values, full command arguments, or unrelated config content.
+By default, inventory snapshots include config file metadata, MCP server metadata, skill metadata, and hook config metadata. They do not include skill instruction bodies, MCP secret values, full environment values, full command arguments, or unrelated config content.
+
+Set `include_contents` to opt the snapshot/heartbeat telemetry into capturing full definitions, matching the `--contents` CLI behavior. When enabled, `inventory.snapshot` events carry redacted, size-limited config/hook/skill `content` blocks and full MCP server `definition` blocks. Secret-looking values are redacted and bodies are truncated to `max_content_bytes` (64 KiB by default). This setting is off by default so the snapshot contract stays metadata-only unless an operator explicitly enables it.
-The heartbeat TTL is configured in the existing endpoint config file:
+The heartbeat TTL and content capture are configured in the existing endpoint config file:
```json title="~/.beacon/endpoint/config.json"
{
"inventory_heartbeat": {
"enabled": true,
"ttl_seconds": 86400,
- "runtimes": ["cursor", "claude_code"]
+ "runtimes": ["cursor", "claude_code"],
+ "include_contents": false,
+ "max_content_bytes": 65536
}
}
```
@@ -72,6 +97,7 @@ For a manual smoke test, temporarily lower `ttl_seconds`, start a Cursor or Clau
| `--mcp` | Show only MCP server inventory and source configs |
| `--skills` | Show only local agent skill inventory |
| `--hooks` | Show only hook integration and hook config inventory |
+| `--contents` | Include redacted, size-limited config/hook/skill file contents and full MCP server definitions |
## Examples
diff --git a/docs/security/data-inventory.mdx b/docs/security/data-inventory.mdx
index 084dfed0..b56419c8 100644
--- a/docs/security/data-inventory.mdx
+++ b/docs/security/data-inventory.mdx
@@ -33,14 +33,16 @@ Beacon writes normalized endpoint events only when supported runtimes provide te
| MCP servers | Runtime, source path hash, server name/hash, transport, command name/hash, argument count, safe env-key names/counts, and definition hash |
| Agent skills | Runtime/source family, scope, skill name/hash, root and manifest path/hash, file hash, modified time, and parser status |
-Skill inventory is metadata-only. Beacon hashes `SKILL.md` manifests for change detection but does not retain skill instruction bodies in inventory JSON, dashboard responses, or inventory snapshot events.
+By default, inventory is metadata- and hash-only. Beacon hashes config, hook, and `SKILL.md` files for change detection but does not retain file bodies, full MCP server definitions, or skill instruction bodies in inventory JSON, dashboard responses, or inventory snapshot events.
+
+Operators can opt into capturing full definitions with the `--contents` flag (CLI) or the `include_contents` config setting (snapshot telemetry). When enabled, configs, hooks, and skills gain a redacted `content` block and MCP servers gain a full `definition` block. Captured contents always pass through local secret redaction — values under keys matching `TOKEN`, `SECRET`, `PASSWORD`, `KEY`, `AUTH`, or `CREDENTIAL` are replaced with `***REDACTED***` — and a per-file size cap (64 KiB by default, configurable via `max_content_bytes`).
Inventory heartbeat telemetry uses a separate local JSONL file, `inventory_state.jsonl`, so `runtime.jsonl` stays scoped to agent runtime activity. For Cursor and Claude Code, normal hook execution can periodically write:
- `inventory.heartbeat`, a small event showing that Beacon checked local agent configuration inventory and recording counts plus a snapshot digest.
-- `inventory.snapshot`, a metadata-only snapshot written when the digest changes or inventory is first initialized.
+- `inventory.snapshot`, a snapshot written when the digest changes or inventory is first initialized. Metadata-only unless `include_contents` is enabled.
-Snapshots include config-file metadata, MCP server metadata, skill metadata, and hook config metadata. They do not include skill instruction bodies, MCP secret values, full environment values, full command arguments, or unrelated config content.
+By default, snapshots include config-file metadata, MCP server metadata, skill metadata, and hook config metadata. They do not include skill instruction bodies, MCP secret values, full environment values, full command arguments, or unrelated config content. When `include_contents` is enabled, snapshots additionally carry redacted, size-limited `content` and `definition` blocks as described above.
## Required Fields