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 inventory
Justin D'Souza4ca4d81f735d
diff --git a/docs/detections/index.mdx b/docs/detections/index.mdxindex 9ac6aac8..c2b1b1df 100644--- a/docs/detections/index.mdx+++ b/docs/detections/index.mdx@@ -21,6 +21,8 @@ Detections focus on risky agent behavior that is hard to understand from one rawBecause rules run over the shared Beacon event model, the same rule vocabulary can apply across supported harnesses when those harnesses emit the required fields.+[Inventory](/guides/inventory) helps explain which harnesses, local config, MCP servers, and skills are present and observable on an endpoint. Detection coverage depends on the telemetry fields emitted by those supported harnesses and visible local configuration.+## Detection Flow1. A supported agent harness emits runtime telemetry.@@ -105,6 +107,9 @@ Beacon does not fetch rules automatically during scans. Pulling a remote rule pa<Card title="Endpoint Event Schema" icon="code" href="/telemetry-schema/event-schema">Review the normalized JSON fields that detections evaluate.</Card>+ <Card title="Inventory" icon="clipboard-list" href="/guides/inventory">+ Review local harness, MCP server, skill, and configuration visibility.+ </Card><Card title="beacon rules" icon="list-check" href="/cli/rules">Manage, install, lint, and inspect local detection rules.</Card>diff --git a/docs/docs.json b/docs/docs.jsonindex 7bcca76a..8c0f5e1c 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -100,6 +100,15 @@"detections/standard","detections/engine"]+ },+ {+ "group": "Inventory",+ "root": "guides/inventory",+ "pages": [+ "inventory/agent-harnesses",+ "inventory/mcp-servers",+ "inventory/skills"+ ]}]},diff --git a/docs/guides/inventory.mdx b/docs/guides/inventory.mdxindex 28641720..be6d54ea 100644--- a/docs/guides/inventory.mdx+++ b/docs/guides/inventory.mdx@@ -5,10 +5,26 @@ description: "Inventory local agent runtimes, skills, MCP servers, and Beacon-ob## Overview-This guide shows how to inventory the AI agent footprint on an endpoint: installed runtimes, local skills, MCP servers, local config files, telemetry hooks, OTLP settings, and recent observed activity.+Inventory shows the local AI agent footprint on an endpoint: installed runtimes, local skills, MCP servers, local config files, telemetry hooks, OTLP settings, and recent observed activity.Use it when you need to answer what is installed, what an agent may be able to access, and whether Beacon has recently observed activity from each runtime.+Inventory explains what is present and observable on the host. [Detections](/detections) evaluate the observed event stream and emit findings when local rules match risky behavior.++## Inventory Areas++<Columns cols={3}>+ <Card title="Agent Harnesses" icon="list-check" href="/inventory/agent-harnesses">+ Review installed, configured, managed, and observed state for supported agent harnesses.+ </Card>+ <Card title="MCP Servers" icon="server" href="/inventory/mcp-servers">+ Review local MCP server configuration and compare expected and unexpected tool access.+ </Card>+ <Card title="Skills" icon="puzzle-piece" href="/inventory/skills">+ Review local skill manifests as an agent extension and configuration surface.+ </Card>+</Columns>+## SetupInstall Beacon and configure endpoint telemetry before running inventory checks:diff --git a/docs/inventory/agent-harnesses.mdx b/docs/inventory/agent-harnesses.mdxnew file mode 100644index 00000000..e5e78a9f--- /dev/null+++ b/docs/inventory/agent-harnesses.mdx@@ -0,0 +1,81 @@+---+title: "Agent Harness Inventory"+description: "Review installed, configured, managed, and observed state for supported local agent harnesses"+---++## Overview++Agent harness inventory shows the supported local agent runtimes Beacon can see on an endpoint and how complete their telemetry coverage appears to be.++Use it to answer:++- Which supported [agent harnesses](/runtimes) are installed locally?+- Which harnesses have local telemetry config, hooks, OTLP settings, or launch environment entries?+- Which harnesses appear Beacon-managed versus customer-managed?+- Which harnesses have recently emitted Beacon endpoint events?++## Coverage States++`beacon endpoint inventory` summarizes each supported harness with coverage states that are useful for deployment review:++| State | Meaning |+|-------|---------|+| Installed | The runtime or executable appears to be present locally. |+| Configured | Beacon can inspect a local telemetry setting, hook entry, launch environment, plugin, or runtime config for the harness. |+| Managed | The telemetry surface appears to be configured by Beacon. |+| Observed | Recent events in the configured runtime log reference the harness. |++A harness can be installed but not configured, configured but not observed, or observed in a different user-mode or system-mode runtime log than the one you are reading.++## Review Workflow++Start with the fleet-friendly inventory view:++```bash title="Show harness inventory"+beacon endpoint inventory+```++Use `--all` when you want to compare all supported harnesses, including runtimes that are not detected on the endpoint:++```bash title="Show all supported harnesses"+beacon endpoint inventory --all+```++Use the narrower discovery command when you only need supported runtime detection and telemetry state:++```bash title="Discover supported harnesses"+beacon endpoint discover --all+```++For hook-based harnesses, inspect hook status directly:++```bash title="Check hook telemetry"+beacon endpoint hooks status --all+```++## What To Look For++- Expected harnesses that are installed but not configured.+- Harnesses configured through customer-managed settings instead of Beacon-managed hooks or OTLP configuration.+- Harnesses that are configured but not observed after a user has generated activity.+- User-mode and system-mode mismatches, especially when a system collector writes `/var/log/beacon-agent/runtime.jsonl` while a user command reads `~/.beacon/endpoint/logs/runtime.jsonl`.+- Hook-based runtimes that need a restart before new hook configuration is loaded.++Inventory is local-only. It reads supported local paths and the configured runtime log; it does not authenticate to hosted agent accounts to enumerate remote sessions or cloud workspaces.++## Related++<Columns cols={2}>+ <Card title="Runtime Surface Overview" icon="list-check" href="/runtimes">+ Compare supported harnesses and collection paths.+ </Card>+ <Card title="beacon endpoint inventory" icon="clipboard-list" href="/cli/endpoint-inventory">+ Review inventory flags, filtering, and JSON output.+ </Card>+ <Card title="beacon endpoint discover" icon="magnifying-glass" href="/cli/endpoint-discover">+ Discover supported harnesses and telemetry state.+ </Card>+ <Card title="beacon endpoint hooks" icon="plug" href="/cli/hooks">+ Install, inspect, and uninstall hook-based telemetry.+ </Card>+</Columns>diff --git a/docs/inventory/mcp-servers.mdx b/docs/inventory/mcp-servers.mdxnew file mode 100644index 00000000..4db8e938--- /dev/null+++ b/docs/inventory/mcp-servers.mdx@@ -0,0 +1,83 @@+---+title: "MCP Server Inventory"+description: "Review local MCP server configuration and expected tool exposure"+---++## Overview++MCP server inventory helps explain which local agent configuration files reference Model Context Protocol servers and where those references came from.++Use it to review the tool surface an agent may be able to call from local configuration:++- Expected MCP servers that should be present after workstation setup.+- Unexpected MCP servers on sensitive endpoints or repositories.+- Server references introduced by user-level, project-level, or runtime-specific config.+- User-mode versus system-mode differences when Beacon reads different endpoint paths and runtime logs.++Inventory reads local config and runtime state only. It does not authenticate to MCP servers, call their tools, or verify remote service permissions.++## Run MCP Inventory++Start with the full inventory report when reviewing MCP server configuration alongside harness and skill state:++```bash title="Show MCP server inventory"+beacon endpoint inventory --all+```++Use JSON output when comparing endpoints or attaching inventory to a support bundle:++```bash title="Export MCP server inventory"+beacon endpoint inventory --json+```++Use system mode when the endpoint service and configuration are installed under system paths:++```bash title="Review system-mode inventory"+sudo beacon endpoint inventory --system --all+```++## Expected Versus Unexpected Servers++Treat MCP inventory as a local configuration review. For each server, compare the reported name, source path, scope, and runtime context with the server list your team expects.++Common review questions:++- Is the server expected for this user, repository, or managed workstation profile?+- Did the server come from a user config or a project config that may travel with source code?+- Does the server expose filesystem, shell, browser, ticketing, messaging, or credential-adjacent tools?+- Is the server present in config but absent from recent observed activity?+- Are there recent `mcp` endpoint events that show the server or tool being used?++Beacon detections can evaluate emitted runtime telemetry when supported harnesses report MCP-like tool activity. Inventory explains that a server is configured or observable; detections evaluate the event stream when activity occurs.++## Beacon MCP Is Separate++The `beacon mcp` command group exposes local Beacon activity to MCP clients. That is different from inventorying third-party MCP servers referenced by agent configs.++Use `beacon mcp doctor` to validate Beacon's own local MCP server before connecting a client:++```bash title="Validate Beacon MCP"+beacon mcp doctor+```++Beacon MCP reads the local runtime log and should stay on stdio or loopback HTTP. It does not require a hosted Beacon account.++## Related++<Columns cols={2}>+ <Card title="Inventory Overview" icon="clipboard-list" href="/guides/inventory">+ Return to the Inventory landing page and command walkthrough.+ </Card>+ <Card title="beacon endpoint inventory" icon="clipboard-list" href="/cli/endpoint-inventory">+ Review inventory flags and JSON output behavior.+ </Card>+ <Card title="beacon mcp" icon="server" href="/cli/mcp">+ Review Beacon's local MCP command group.+ </Card>+ <Card title="beacon mcp doctor" icon="stethoscope" href="/cli/mcp-doctor">+ Validate local Beacon MCP setup.+ </Card>+ <Card title="Test MCP Access" icon="plug" href="/guides/local-testing/mcp">+ Connect Cursor or Claude Code to Beacon MCP for local testing.+ </Card>+</Columns>diff --git a/docs/inventory/skills.mdx b/docs/inventory/skills.mdxnew file mode 100644index 00000000..9c9088ad--- /dev/null+++ b/docs/inventory/skills.mdx@@ -0,0 +1,69 @@+---+title: "Skills Inventory"+description: "Review local agent skills as an extension and configuration surface"+---++## Overview++Skills are a local agent extension and configuration surface. A skill can add durable instructions, scripts, workflows, or tool guidance that changes how an agent behaves when the runtime loads it.++Beacon inventory can help identify local skill manifests under supported skill roots. It reports metadata such as names, paths, hashes, scope, modified time, and parser status. It does not retain `SKILL.md` instruction bodies in inventory output, dashboard responses, or inventory events.++## What Inventory Can Infer Today++Use `beacon endpoint inventory --all` to review skill metadata alongside harness, MCP server, hook, and config state:++```bash title="Show skill inventory"+beacon endpoint inventory --all+```++For machine-readable review, export JSON:++```bash title="Export skill metadata"+beacon endpoint inventory --json+```++Skill inventory is useful for:++- Confirming expected local skill packs are present after workstation setup.+- Spotting unexpected skills on sensitive endpoints or repositories.+- Comparing user-scope and project-scope skill roots.+- Detecting manifest changes through hashes and modified-time metadata.+- Identifying parser failures that may prevent Beacon from understanding a manifest consistently.++## What To Review Manually++Inventory is intentionally conservative. It can identify local skill manifests and change indicators, but reviewers should inspect the skill contents, scripts, and repository context when deciding whether a skill is expected.++Manual review should cover:++- What instructions the skill gives the agent.+- Whether the skill references local scripts, tools, shell commands, or external services.+- Whether the skill is user-specific, project-specific, or checked into source control.+- Whether the manifest hash changed at an expected time.+- Whether the owning team recognizes the skill name and path.++Beacon does not claim to authenticate to or fully enumerate remote skill registries. Treat inventory as local endpoint visibility into supported paths, not as a registry audit.++## Runtime Telemetry And Detections++Skills may influence later runtime behavior. When a supported harness emits telemetry for tool calls, commands, file activity, approvals, or MCP-like tool usage, Beacon normalizes those events into the runtime log.++[Detections](/detections) can evaluate that observed event stream. For example, a finding may be based on a command, file path, MCP server, approval decision, or tool call that occurred while an agent was using a skill-guided workflow. Inventory helps explain the local skill surface; detections evaluate what the agent actually did when telemetry was emitted.++## Related++<Columns cols={2}>+ <Card title="Inventory Overview" icon="clipboard-list" href="/guides/inventory">+ Return to the Inventory landing page and command walkthrough.+ </Card>+ <Card title="beacon endpoint inventory" icon="clipboard-list" href="/cli/endpoint-inventory">+ Review inventory flags, filtering, and JSON output.+ </Card>+ <Card title="Detections" icon="shield-halved" href="/detections">+ Understand how rules evaluate observed endpoint events.+ </Card>+ <Card title="Data inventory" icon="table-list" href="/security/data-inventory">+ Review endpoint event data and inventory metadata behavior.+ </Card>+</Columns>