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
State the lens trust model honestly and confirm before installing a lens
Claude8aa99ad6e07a
diff --git a/CLAUDE.md b/CLAUDE.mdindex 83eef3a9..5f817bdc 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -15,7 +15,7 @@ Beacon Endpoint Agent is a local-only endpoint telemetry agent for AI runtimes.- `plugins`: TypeScript sources for the managed runtime plugins/extensions (`opencode-beacon`, `cline-beacon`, `pi-beacon`, `omp-beacon`, `openclaw-beacon`, `prime-beacon`, `omo-beacon`), each mirrored into an embedded copy under `cli/beacon/internal/endpoint/hooks/assets/`.- `agent-skills`: publishable Agent Skills plugin for the traces-to-memory workflow (`beacon-memory-recall`, `beacon-memory-distill`, `beacon-memory-promote`) for authoring dashboard lenses (`beacon-lens-create`), and for sharing the current session to beacon.sh (`beacon-trace-share`, which runs `beacon share --current --harness <runtime> --json`, keeps the default direct visibility and asks before public) with manifests for Claude Code, Agent Plugins (Codex, Copilot, VS Code, Kiro, Devin), Cursor, Kimi Code, and Gemini CLI. At the repo root, `.claude-plugin/marketplace.json` is read by most harnesses, `.cursor-plugin/marketplace.json` by Cursor, and `package.json` (`pi.skills` only) makes the repo a Pi/Prime Agent package; keep that root `package.json` free of dependencies and scripts. `cli/beacon/cmd/agent_skills_test.go` checks every `beacon` command and flag the skills name against the real command tree, so rename a command and update the skills together. The binary carries a copy of `agent-skills/skills` in `cli/beacon/internal/agentskills/skills` for onboarding and `beacon skills install`; a test keeps it identical, so copy it across whenever a skill changes.- `rules` and `spec/threat-rules`: the open rule corpus and the Threat Rules format it conforms to. Every rule's `taxonomy.beacon_category` is its directory name, and the six embedded baseline rules in `pkg/asymptoteobserve/rulestore/baseline` are byte-identical copies of their corpus rules; conformance tests enforce both.-- `spec/lenses`: the Lenses format — single-file HTML views of one trace that the local dashboard runs in a sandboxed, network-less frame and feeds once through `window.beacon.getTrace()`. The contract types (`LensManifestV1`, `LensDataV1`) live in `pkg/asymptoteobserve/lens.go`, and `lens_test.go` pins the spec's examples and manifest schema to them. The dashboard builds the data in `BuildLensData` (`/api/lens-data`), lists lenses at `/api/lenses`, and serves each lens at `/lenses/frame/<id>` under the spec's CSP with `lenses/prelude.js` (which defines `window.beacon`) injected ahead of it; that route is the only one that may be framed. Built-in lenses are `cli/beacon/internal/endpoint/dashboard/lenses/*.lens.html`, and `activity` is byte-identical to the spec example (a test enforces it). The session page (`static/session.html`, `initLensTabs` in `app.js`) shows lenses as tabs fed by `/api/lens-data?session=`, which projects exactly the events that page lists; it is the host half of the protocol and closes a lens that errors, stalls, or navigates its own frame. Installed lenses live in the lens store (`cli/beacon/internal/endpoint/lensstore`, `<BaseDir>/lenses/<id>.lens.html`, 0600 under 0700), written only by `beacon lenses add|remove` (`cli/beacon/cmd/lenses.go`); the dashboard rescans it per request and never writes it, and a store lens can never shadow a built-in. `asymptoteobserve.CheckLensFile` is the one file check every installer, server and linter uses. User docs are `docs/concepts/lenses.mdx` and `docs/cli/lenses.mdx`; keep them in sync with the commands and built-in lenses. The authoring loop is `beacon lenses spec` (the spec carried in the binary as `dashboard/lenses/SPEC.md`, kept byte-identical to `spec/lenses/SPEC.md` by a test), `beacon lenses data` (the exact `LensDataV1` for a session), `beacon lenses lint` (`lensstore.Lint`; built-ins must lint clean) and `beacon lenses preview` (the dashboard with `Options.LensFiles`, re-read per reload).+- `spec/lenses`: the Lenses format — single-file HTML views of one trace that the local dashboard runs in a sandboxed, network-less frame and feeds once through `window.beacon.getTrace()`. The contract types (`LensManifestV1`, `LensDataV1`) live in `pkg/asymptoteobserve/lens.go`, and `lens_test.go` pins the spec's examples and manifest schema to them. The dashboard builds the data in `BuildLensData` (`/api/lens-data`), lists lenses at `/api/lenses`, and serves each lens at `/lenses/frame/<id>` under the spec's CSP with `lenses/prelude.js` (which defines `window.beacon`) injected ahead of it; that route is the only one that may be framed. Built-in lenses are `cli/beacon/internal/endpoint/dashboard/lenses/*.lens.html`, and `activity` is byte-identical to the spec example (a test enforces it). The session page (`static/session.html`, `initLensTabs` in `app.js`) shows lenses as tabs fed by `/api/lens-data?session=`, which projects exactly the events that page lists; it is the host half of the protocol and closes a lens that errors, stalls, or navigates its own frame. Trust model (SPEC "Trust model"): the opaque origin, sandbox and CSP keep a lens from touching Beacon or the dashboard and block ordinary network APIs, but cannot fully prevent a lens from sending trace data out through browser features no CSP governs (WebRTC, resource hints, speculative loading), so an installed lens is code the person trusts with the trace data it is shown; never describe the sandbox as making exfiltration impossible. `prelude.js` removes the `RTC*` globals and guards the document (refuses creating, inserting or parsing in nested frames, `<link>` elements and `<script type=speculationrules>`, refuses `document.write`, and a mutation observer removes those from the file's own markup); that is best-effort hardening, not a boundary, and the hostile `probe` fixture in `testdata/lens-e2e` pins each covered path. Installed lenses live in the lens store (`cli/beacon/internal/endpoint/lensstore`, `<BaseDir>/lenses/<id>.lens.html`, 0600 under 0700), written only by `beacon lenses add|remove` (`cli/beacon/cmd/lenses.go`; `add` prints the trust warning and confirms on a TTY, and refuses without one or in CI unless `--yes`); the dashboard rescans it per request and never writes it, and a store lens can never shadow a built-in. `asymptoteobserve.CheckLensFile` is the one file check every installer, server and linter uses. User docs are `docs/concepts/lenses.mdx` and `docs/cli/lenses.mdx`; keep them in sync with the commands and built-in lenses. The authoring loop is `beacon lenses spec` (the spec carried in the binary as `dashboard/lenses/SPEC.md`, kept byte-identical to `spec/lenses/SPEC.md` by a test), `beacon lenses data` (the exact `LensDataV1` for a session), `beacon lenses lint` (`lensstore.Lint`; built-ins must lint clean) and `beacon lenses preview` (the dashboard with `Options.LensFiles`, re-read per reload).- `beacon-sandbox`: harness that runs a real Claude Code session in a disposable sandbox and checks what Beacon captured. See `beacon-sandbox/AGENTS.md`.- `packaging`: macOS, Linux, and Windows packaging and deployment assets.- `docs`: the published documentation site (docs.asymptotelabs.ai).diff --git a/README.md b/README.mdindex 6786bdbe..1a18f3ff 100644--- a/README.md+++ b/README.md@@ -275,9 +275,11 @@ Use it to explore session history across harnesses and understand what your agenEach session page can also show **lenses**: purpose-built views of one trace, such as fileschanged with their diffs, an itemized token bill, a security review grouped by risk, or the-approval timeline. A lens is a single HTML file running in a sandboxed, network-less frame,-so you can have your coding agent write your own (`beacon lenses spec`, `lint`, `preview`,-`add`). See [Lenses](https://docs.beacon.sh/concepts/lenses).+approval timeline. A lens is a single HTML file running in a sandboxed frame with no access to+Beacon or the dashboard and no ordinary network APIs, so you can have your coding agent write+your own (`beacon lenses spec`, `lint`, `preview`, `add`). The sandbox cannot block every way a+browser can send data out, so install only lenses you trust with your traces. See+[Lenses](https://docs.beacon.sh/concepts/lenses).The underlying JSONL remains directly accessible, so you're never dependent on the UI.diff --git a/agent-skills/skills/beacon-lens-create/SKILL.md b/agent-skills/skills/beacon-lens-create/SKILL.mdindex 4ddd0678..3400730a 100644--- a/agent-skills/skills/beacon-lens-create/SKILL.md+++ b/agent-skills/skills/beacon-lens-create/SKILL.md@@ -69,7 +69,9 @@ The dashboard enforces these; a lens that breaks them fails to install or failserror). The `id` is lowercase letters, digits and hyphens, and cannot be a built-in lens's id.- **No network and nothing loaded by URL.** The frame's Content Security Policy blocks `fetch`,XHR, WebSockets, `EventSource`, `sendBeacon`, remote scripts, stylesheets, fonts and images,- `@import`, workers, nested frames, `eval` and `new Function`.+ `@import`, workers, nested frames, `eval` and `new Function`. The host also removes WebRTC and+ refuses `<iframe>`/`srcdoc` and other nested frames, `<link>` elements (resource hints such as+ `preconnect`), speculation rules and `document.write`, because the CSP does not govern them.- **No dashboard access.** The frame is `sandbox="allow-scripts"` with an opaque origin: nocookies, `localStorage`, `sessionStorage` or IndexedDB, no access to the parent page, no popupsor forms. Keep state in memory.@@ -179,8 +181,9 @@ beacon lenses lint --strict path/to/my-lens.lens.htmlErrors (size, a missing or invalid manifest) stop the lens from running. Warnings name the linewhere the lens does something the sandbox blocks or the spec forbids: HTML parsing of content,-network calls, resources loaded by URL, browser storage, navigation, viewport-height layouts, or-never calling `getTrace()`. Fix both.+network calls, resources loaded by URL, browser storage, navigation, WebRTC, nested frames, links+and resource hints, speculation rules, viewport-height layouts, or never calling `getTrace()`.+Fix both.## Step 6: preview it against real sessions@@ -211,6 +214,11 @@ Only after the user has seen it in preview and is happy with it:beacon lenses add path/to/my-lens.lens.html```+A lens sees the full content of every trace it is shown and is code the user must trust, so+`add` asks for confirmation on a terminal and refuses without one. Let the user run it, or, once+the user has told you in this conversation to install this lens, run it with `--yes`. Never pass+`--yes` for a lens the user has not read or previewed.+It now appears in the **+** menu on every session page. To change it later, edit the sourcefile, bump `version` in its manifest, and run `beacon lenses add` again; an equal or lowerversion is refused unless the user asks for `--force`. `beacon lenses remove <id>` uninstalls it.diff --git a/cli/beacon/cmd/lenses.go b/cli/beacon/cmd/lenses.goindex e00a3677..91d15adf 100644--- a/cli/beacon/cmd/lenses.go+++ b/cli/beacon/cmd/lenses.go@@ -1,21 +1,53 @@package cmdimport (+ "errors""fmt"+ "io"+ "os""github.com/spf13/cobra""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/dashboard""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lensstore"+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve")var lensesOpts struct {userMode boolsystemMode boolforce bool+ yes booljson bool}+// Test seams for the install confirmation.+var (+ lensesIsTTY = func() bool { return isTerminal(os.Stdin) }+ lensesStdin io.Reader = os.Stdin+)++// lensTrustWarning is what `beacon lenses add` says before installing a lens. The sandbox keeps a+// lens away from Beacon and the dashboard, but browsers have no control for every way a page can+// send data out, so installing a lens is trusting its code with the traces it is shown.+const lensTrustWarning = `A lens sees the full content of every trace it is shown: prompts, responses, command+output and diffs. The dashboard's sandbox keeps it away from Beacon and the dashboard and blocks+ordinary network requests, but it cannot stop every way a browser can send data out (WebRTC,+resource hints). Install only lenses whose code you trust.+`++func confirmLensInstall(errOut io.Writer, src string, manifest asymptoteobserve.LensManifestV1) error {+ if !lensesIsTTY() || isCIEnvironment() {+ return errors.New("a lens is code trusted with the full content of the traces it is shown; pass --yes to install it without a terminal to confirm")+ }+ fmt.Fprint(errOut, lensTrustWarning)+ fmt.Fprintf(errOut, "Install %s (%s v%d) from %s? [y/N] ", manifest.Title, manifest.ID, manifest.Version, src)+ if !confirmNo(lensesStdin) {+ return errors.New("not installed")+ }+ return nil+}+func lensesUserMode() bool {if lensesOpts.systemMode {return false@@ -29,8 +61,9 @@ var lensesCmd = &cobra.Command{Long: `Manage the local lens store (~/.beacon/endpoint/lenses).A lens is one HTML file that renders one trace. The dashboard ('beacon endpoint dashboard')-shows lenses as tabs on a session's page, runs each in a sandboxed frame with no network,-and hands it the trace through window.beacon.getTrace(). Beacon ships built-in lenses; the+shows lenses as tabs on a session's page, runs each in a sandboxed frame with no access to+Beacon or the dashboard and no ordinary network APIs, and hands it the trace through+window.beacon.getTrace(). A lens is code you trust with the traces it is shown. Beacon ships built-in lenses; thestore holds the ones you add. The format is spec/lenses/SPEC.md.`,}@@ -85,6 +118,10 @@ var lensesAddCmd = &cobra.Command{Short: "Install a lens file into the store",Long: `Check a lens file against the spec and copy it into the store under its manifest id.+A lens sees the full content of every trace it is shown and is trusted code: the sandbox keeps+it away from Beacon and the dashboard, but cannot stop every way a browser can send data out.+Add asks for confirmation on a terminal; without one it needs --yes.+Replacing an installed lens needs a higher manifest version, or --force. A built-in lens'sid cannot be used. The dashboard picks the lens up on its next page load.`,Args: cobra.ExactArgs(1),@@ -94,7 +131,13 @@ id cannot be used. The dashboard picks the lens up on its next page load.`,if err != nil {return err}- lens, replaced, err := lensstore.Install(lensesStoreDir(), args[0], lensstore.InstallOptions{Reserved: reserved, Force: lensesOpts.force})+ opts := lensstore.InstallOptions{Reserved: reserved, Force: lensesOpts.force}+ if !lensesOpts.yes {+ opts.Confirm = func(manifest asymptoteobserve.LensManifestV1) error {+ return confirmLensInstall(cmd.ErrOrStderr(), args[0], manifest)+ }+ }+ lens, replaced, err := lensstore.Install(lensesStoreDir(), args[0], opts)if err != nil {return err}@@ -156,6 +199,7 @@ func init() {}lensesListCmd.Flags().BoolVar(&lensesOpts.json, "json", false, "Print JSON")lensesAddCmd.Flags().BoolVar(&lensesOpts.force, "force", false, "Replace an installed lens even when the new version is not higher")+ lensesAddCmd.Flags().BoolVar(&lensesOpts.yes, "yes", false, "Install without asking; you trust this lens with the traces it is shown")lensesCmd.AddCommand(lensesListCmd, lensesAddCmd, lensesRemoveCmd, lensesShowCmd)rootCmd.AddCommand(lensesCmd)}diff --git a/cli/beacon/cmd/lenses_test.go b/cli/beacon/cmd/lenses_test.goindex 6bb91ef9..7932b8f6 100644--- a/cli/beacon/cmd/lenses_test.go+++ b/cli/beacon/cmd/lenses_test.go@@ -26,10 +26,61 @@ func useLensTestHome(t *testing.T) {t.Helper()testenv.SetHome(t, t.TempDir())prev := lensesOpts- lensesOpts.userMode, lensesOpts.systemMode, lensesOpts.force, lensesOpts.json = true, false, false, false+ lensesOpts.userMode, lensesOpts.systemMode, lensesOpts.force, lensesOpts.yes, lensesOpts.json = true, false, false, true, falset.Cleanup(func() { lensesOpts = prev })}+func TestLensesAddAsksBeforeInstallingAndRefusesWithoutATerminal(t *testing.T) {+ useLensTestHome(t)+ lensesOpts.yes = false+ for _, key := range []string{"CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "GITLAB_CI", "BUILDKITE", "JENKINS_URL", "TEAMCITY_VERSION"} {+ t.Setenv(key, "")+ }+ prevTTY, prevStdin := lensesIsTTY, lensesStdin+ t.Cleanup(func() { lensesIsTTY, lensesStdin = prevTTY, prevStdin })+ src := t.TempDir()+ installed := func() bool {+ _, err := os.Stat(filepath.Join(lensstore.Dir(true), "mine"+lensstore.FileSuffix))+ return err == nil+ }++ lensesIsTTY = func() bool { return false }+ cmd, _ := newCmd()+ if err := lensesAddCmd.RunE(cmd, []string{writeTestLens(t, src, "mine", "1")}); err == nil || !strings.Contains(err.Error(), "--yes") || installed() {+ t.Fatalf("without a terminal: err = %v, installed = %v", err, installed())+ }++ lensesIsTTY = func() bool { return true }+ lensesStdin = strings.NewReader("n\n")+ cmd, buf := newCmd()+ if err := lensesAddCmd.RunE(cmd, []string{writeTestLens(t, src, "mine", "1")}); err == nil || installed() {+ t.Fatalf("declined: err = %v, installed = %v", err, installed())+ }+ if !strings.Contains(buf.String(), "full content of every trace") || !strings.Contains(buf.String(), "Install Test mine (mine v1)") {+ t.Fatalf("prompt = %q", buf.String())+ }++ lensesStdin = strings.NewReader("y\n")+ cmd, _ = newCmd()+ if err := lensesAddCmd.RunE(cmd, []string{writeTestLens(t, src, "mine", "1")}); err != nil || !installed() {+ t.Fatalf("confirmed: err = %v, installed = %v", err, installed())+ }++ // A file that fails a check is refused before anyone is asked.+ lensesStdin = strings.NewReader("")+ cmd, buf = newCmd()+ if err := lensesAddCmd.RunE(cmd, []string{writeTestLens(t, src, "files-changed", "1")}); err == nil || strings.Contains(buf.String(), "Install ") {+ t.Fatalf("built-in id: err = %v, output = %q", err, buf.String())+ }++ lensesIsTTY = func() bool { return false }+ lensesOpts.yes = true+ cmd, _ = newCmd()+ if err := lensesAddCmd.RunE(cmd, []string{writeTestLens(t, src, "mine", "2")}); err != nil {+ t.Fatalf("--yes without a terminal: %v", err)+ }+}+func TestLensesAddListShowRemove(t *testing.T) {useLensTestHome(t)src := t.TempDir()diff --git a/cli/beacon/internal/agentskills/skills/beacon-lens-create/SKILL.md b/cli/beacon/internal/agentskills/skills/beacon-lens-create/SKILL.mdindex 4ddd0678..3400730a 100644--- a/cli/beacon/internal/agentskills/skills/beacon-lens-create/SKILL.md+++ b/cli/beacon/internal/agentskills/skills/beacon-lens-create/SKILL.md@@ -69,7 +69,9 @@ The dashboard enforces these; a lens that breaks them fails to install or failserror). The `id` is lowercase letters, digits and hyphens, and cannot be a built-in lens's id.- **No network and nothing loaded by URL.** The frame's Content Security Policy blocks `fetch`,XHR, WebSockets, `EventSource`, `sendBeacon`, remote scripts, stylesheets, fonts and images,- `@import`, workers, nested frames, `eval` and `new Function`.+ `@import`, workers, nested frames, `eval` and `new Function`. The host also removes WebRTC and+ refuses `<iframe>`/`srcdoc` and other nested frames, `<link>` elements (resource hints such as+ `preconnect`), speculation rules and `document.write`, because the CSP does not govern them.- **No dashboard access.** The frame is `sandbox="allow-scripts"` with an opaque origin: nocookies, `localStorage`, `sessionStorage` or IndexedDB, no access to the parent page, no popupsor forms. Keep state in memory.@@ -179,8 +181,9 @@ beacon lenses lint --strict path/to/my-lens.lens.htmlErrors (size, a missing or invalid manifest) stop the lens from running. Warnings name the linewhere the lens does something the sandbox blocks or the spec forbids: HTML parsing of content,-network calls, resources loaded by URL, browser storage, navigation, viewport-height layouts, or-never calling `getTrace()`. Fix both.+network calls, resources loaded by URL, browser storage, navigation, WebRTC, nested frames, links+and resource hints, speculation rules, viewport-height layouts, or never calling `getTrace()`.+Fix both.## Step 6: preview it against real sessions@@ -211,6 +214,11 @@ Only after the user has seen it in preview and is happy with it:beacon lenses add path/to/my-lens.lens.html```+A lens sees the full content of every trace it is shown and is code the user must trust, so+`add` asks for confirmation on a terminal and refuses without one. Let the user run it, or, once+the user has told you in this conversation to install this lens, run it with `--yes`. Never pass+`--yes` for a lens the user has not read or previewed.+It now appears in the **+** menu on every session page. To change it later, edit the sourcefile, bump `version` in its manifest, and run `beacon lenses add` again; an equal or lowerversion is refused unless the user asks for `--force`. `beacon lenses remove <id>` uninstalls it.diff --git a/cli/beacon/internal/endpoint/dashboard/lenses/SPEC.md b/cli/beacon/internal/endpoint/dashboard/lenses/SPEC.mdindex 9e63a33d..0c4be5ab 100644--- a/cli/beacon/internal/endpoint/dashboard/lenses/SPEC.md+++ b/cli/beacon/internal/endpoint/dashboard/lenses/SPEC.md@@ -5,8 +5,9 @@ A lens is a single HTML file that renders one Beacon trace. The local dashboardEach tab reads the same trace and answers a different question: which fileschanged, what the run cost, what the threat rules flagged.-A lens runs in a sandboxed frame with no network and no access to the dashboard.-It receives the trace through one call, `window.beacon.getTrace()`. Everything+A lens runs in a sandboxed frame with no access to Beacon or the dashboard and+no ordinary network APIs. It receives the trace through one call,+`window.beacon.getTrace()`. Everythingelse is plain HTML, CSS and JavaScript, so any coding agent can write one fromthis document.@@ -150,10 +151,11 @@ The full field list is the Go source in `pkg/asymptoteobserve/trace.go` andA lens sees whatever the local log retained. With `full` retention thatincludes prompts, responses, command output and diffs, after Beacon's local-redaction. A lens can show that content on screen and nowhere else: the-sandbox below gives it no way to send it anywhere. Forwarding privacy modes-(such as metadata-only) govern what leaves the machine. They do not reduce-what a local lens receives.+redaction. The sandbox below is built so that a lens shows that content on+screen and nowhere else, but it cannot guarantee it: see+[Trust model](#trust-model). Forwarding privacy modes (such as metadata-only)+govern what Beacon sends off the machine. They do not reduce what a local+lens receives.## Sandbox@@ -181,17 +183,24 @@ The host enforces these rules; a lens does not opt into them.script runs, every `RTC*` interface on `window` (including`RTCPeerConnection`, `RTCDataChannel` and `webkitRTCPeerConnection`) isdefined as `undefined`, non-writable and non-configurable. A lens cannot- delete or redefine them. This holds inside the lens's own realm only; it- relies on the CSP and sandbox above to keep the lens from reaching a fresh- realm (a frame, worker or popup) where the originals still exist.+ delete or redefine them. This holds in the lens's own realm only. A child+ frame is a fresh realm where they still exist: the lens cannot reach into+ one (a sandboxed child has its own opaque origin), but a `srcdoc` child+ runs its own scripts, which is why the host refuses child frames (next).+- The host refuses, before any lens script runs, the elements that can start+ a request the CSP does not see or open a fresh realm: nested frames+ (`iframe`, `frame`, `object`, `embed`, `portal`, `fencedframe`), every+ `<link>` element (a lens loads nothing by URL, and resource hints such as+ `preconnect`, `prefetch` and `preload` are links), and+ `<script type="speculationrules">`. Creating one, inserting one, or parsing+ one in through `innerHTML`, `outerHTML`, `insertAdjacentHTML`,+ `setHTMLUnsafe` or `execCommand` throws a `NotSupportedError`+ `DOMException`; `document.write` and `document.writeln` always throw; and+ any the parser puts in from the lens file's own markup is removed before+ the next script runs.- The frame is served with `X-DNS-Prefetch-Control: off`, and the hostrepeats it as a `<meta http-equiv>` in the document, so the browser does notresolve hostnames the lens mentions on its own.-- Residual risk. CSP and the sandbox are the boundary, and browsers do not- route every speculative or connection-warming request through them; some- resource-hint and speculative-loading features can still start a request a- CSP does not see, depending on the browser and its settings. Treat a lens- as code that can read the whole trace, and install only lenses you trust.- Trace data reaches the frame only over a private `MessageChannel` port. Theone `postMessage` from the host to the window carries that port andnothing else. The lens never uses `window.postMessage` itself;@@ -202,6 +211,29 @@ The host enforces these rules; a lens does not opt into them.the timeout, the host falls back to the full trace view. A broken lenscannot break the dashboard.+### Trust model++The opaque origin, the sandbox and the CSP are enforced by the browser. They+keep a lens from touching Beacon, the dashboard, its storage or its API, and+they refuse the ordinary network APIs (`fetch`, XHR, WebSocket,+`EventSource`, `sendBeacon`, remote images, fonts and scripts, frames,+workers and navigation).++They cannot fully prevent a lens from sending the trace data it is shown out+of the machine. Some browser features are not governed by CSP or any other+policy a page can set: WebRTC, and resource hints and speculative loading+such as `preconnect` and speculation rules. The removal and refusals above+are best-effort hardening inside the lens's own page, not a boundary: they+close the common ways to reach those features, and a determined lens may find+another. They do not cover what the browser's preload scanner does with the+file's own markup before any script runs, closed declarative shadow roots,+or attribute changes made through `Attr` nodes.++So an installed lens is code you trust with the trace data it is shown.+Read a lens before you install it, and install only lenses you trust.+`beacon lenses add` asks for that confirmation, and `beacon lenses lint`+warns on the features above.+## Layout and style- **Height.** The host sizes the frame to the document's height and keeps it@@ -270,3 +302,7 @@ The host enforces these rules; a lens does not opt into them.- `lenses/v1` (additive): `cache_creation_1h_input_tokens` in every usage object,the subset of `cache_creation_input_tokens` written with a one-hour TTL wherethe source reported it. It is a breakdown; never add it to a total.+- `lenses/v1` (hardening): the host removes WebRTC, refuses nested frames,+ `<link>` elements, speculation rules and `document.write`, and turns off DNS+ prefetching. A lens that follows this spec uses none of them; the+ [trust model](#trust-model) says what this does and does not guarantee.diff --git a/cli/beacon/internal/endpoint/lensstore/lensstore.go b/cli/beacon/internal/endpoint/lensstore/lensstore.goindex 18d029a2..b84c0a1e 100644--- a/cli/beacon/internal/endpoint/lensstore/lensstore.go+++ b/cli/beacon/internal/endpoint/lensstore/lensstore.go@@ -108,6 +108,9 @@ type InstallOptions struct {Reserved map[string]bool// Force replaces an installed lens even when the new file's version is not newer.Force bool+ // Confirm, when set, is asked once the file has passed every check and before anything is+ // written, with the manifest of the bytes that will be installed. An error stops the install.+ Confirm func(asymptoteobserve.LensManifestV1) error}// Install checks the lens file at src and copies it into dir under its manifest ID. It returns@@ -140,6 +143,11 @@ func Install(dir, src string, opts InstallOptions) (Lens, int, error) {// An unreadable or invalid file is in the way. Replacing it is what the user asked for.replaced = -1}+ if opts.Confirm != nil {+ if err := opts.Confirm(manifest); err != nil {+ return Lens{}, 0, err+ }+ }if err := os.MkdirAll(dir, 0o700); err != nil {return Lens{}, 0, err}diff --git a/docs/cli/lenses.mdx b/docs/cli/lenses.mdxindex 97b6442a..b28affd9 100644--- a/docs/cli/lenses.mdx+++ b/docs/cli/lenses.mdx@@ -48,18 +48,29 @@ the other lenses still list.## beacon lenses addChecks a lens file against the [spec](https://github.com/asymptote-labs/agent-beacon/blob/main/spec/lenses/SPEC.md)-(at most 16 MiB, one valid manifest) and copies it into the store under its manifest `id`.+(at most 16 MiB, one valid manifest), asks you to confirm, and copies it into the store under+its manifest `id`.++A lens sees the full content of every trace it is shown, and installing one is trusting its+code with that content. The sandbox keeps a lens away from Beacon and the dashboard and blocks+ordinary network requests, but it cannot stop every way a browser can send data out (WebRTC,+resource hints; see [what the sandbox does not guarantee](/concepts/lenses#what-the-sandbox-does-not-guarantee)).+So `add` prints that warning and asks before it writes anything. Without a terminal, or in CI,+it refuses unless you pass `--yes`.Replacing an installed lens needs a higher `version` in the new file's manifest, so addingan old copy by mistake does not downgrade it. `--force` replaces it anyway.```bashbeacon lenses add ./command-log.lens.html+# A lens sees the full content of every trace it is shown: ...+# Install Command Log (command-log v1) from ./command-log.lens.html? [y/N] y# installed command-log v1 (~/.beacon/endpoint/lenses/command-log.lens.html)```| Flag | Description ||------|-------------|+| `--yes` | Install without asking; you trust this lens with the traces it is shown || `--force` | Replace an installed lens even when the new version is not higher || `--user` / `--system` | Use the per-user (default) or system endpoint paths |@@ -103,12 +114,15 @@ Checks lens files against the spec. **Errors** (an oversized file, a missing ormanifest) stop a lens from running. **Warnings** name the line where a lens does somethingthe sandbox will block or the spec forbids:-- parsing trace content as HTML (`innerHTML`, `insertAdjacentHTML`, `document.write`)+- parsing trace content as HTML (`innerHTML`, `outerHTML`, `insertAdjacentHTML`)- network requests (`fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`, `sendBeacon`)- scripts, images, fonts or stylesheets loaded by URL- browser storage and cookies- messaging or navigating another window, or its own frame- `eval`, `new Function` and workers+- WebRTC, nested frames (`iframe`, `srcdoc`, `object`, `embed`), `<link>` elements and resource+ hints (`preconnect`, `prefetch`), speculation rules, `document.write` and declarative shadow+ roots, which the lens frame removes or refuses- a root sized to the viewport (`100vh`), which never settles because the frame grows to fit- never calling `window.beacon.getTrace()`diff --git a/docs/concepts/lenses.mdx b/docs/concepts/lenses.mdxindex 63c9bf28..faa74fbf 100644--- a/docs/concepts/lenses.mdx+++ b/docs/concepts/lenses.mdx@@ -32,12 +32,11 @@ agent can write one.## How a lens runs-A lens is untrusted code looking at sensitive data, so the dashboard runs it on a short-leash:+A lens is code looking at sensitive data, so the dashboard runs it on a short leash:-- **No network.** The lens runs in a sandboxed frame under a Content Security Policy with- `connect-src 'none'`. It cannot fetch, open a socket, load a remote image or font, or- navigate its frame anywhere else. A lens that tries to navigate is closed.+- **No ordinary network.** The lens runs in a sandboxed frame under a Content Security+ Policy with `connect-src 'none'`. It cannot fetch, open a socket, load a remote image or+ font, or navigate its frame anywhere else. A lens that tries to navigate is closed.- **No dashboard access.** The frame has an opaque origin. It cannot read the dashboard'spages, storage or API.- **One delivery of data.** The trace arrives once, through `window.beacon.getTrace()`,@@ -50,9 +49,24 @@ leash:The data is the trace bundle every Beacon trace consumer reads, plus the trace's rulefindings and its token usage as [`beacon token-usage`](/cli/token-usage) counts it. A lenssees whatever content the local log retained, after Beacon's redaction: prompts, command-output and diffs when retention is `full`. It can show that on screen and nowhere else.-[Forwarding privacy modes](/concepts/vector-forwarding) control what leaves the machine;-they do not reduce what a local lens receives.+output and diffs when retention is `full`.+[Forwarding privacy modes](/concepts/vector-forwarding) control what Beacon sends off the+machine; they do not reduce what a local lens receives.++### What the sandbox does not guarantee++The sandbox keeps a lens away from Beacon and the dashboard and blocks the ordinary network+APIs, but it cannot fully prevent a lens from sending the trace data it is shown out of the+machine. Some browser features are not governed by a Content Security Policy or any other+control a page can set: WebRTC, and resource hints and speculative loading such as+`preconnect` and speculation rules. The dashboard removes WebRTC from the lens and refuses+nested frames, `<link>` elements and speculation rules before any lens code runs. That is+best-effort hardening that closes the common paths, not a boundary: a determined lens may+find another.++So an installed lens is code you trust with the trace data it is shown. The built-in lenses+ship with Beacon. Read any other lens before you install it, and install only lenses you+trust; [`beacon lenses add`](/cli/lenses#beacon-lenses-add) asks you to confirm that.## Make your own lens@@ -86,9 +100,9 @@ beacon lenses add my.lens.html # install it into the lens storeCDN.4. **Preview.** `beacon lenses preview` serves the dashboard with the file added and printsthe session page to open. The file is read again on every reload.-5. **Install.** `beacon lenses add` copies the file into the lens store- (`~/.beacon/endpoint/lenses`), where every session page offers it. To update a lens, bump- the `version` in its manifest and add it again.+5. **Install.** `beacon lenses add` asks you to confirm that you trust the lens, then copies+ the file into the lens store (`~/.beacon/endpoint/lenses`), where every session page+ offers it. To update a lens, bump the `version` in its manifest and add it again.See [`beacon lenses`](/cli/lenses) for every command and flag, and the[lens specification](https://github.com/asymptote-labs/agent-beacon/blob/main/spec/lenses/SPEC.md)diff --git a/spec/lenses/SPEC.md b/spec/lenses/SPEC.mdindex 9e63a33d..0c4be5ab 100644--- a/spec/lenses/SPEC.md+++ b/spec/lenses/SPEC.md@@ -5,8 +5,9 @@ A lens is a single HTML file that renders one Beacon trace. The local dashboardEach tab reads the same trace and answers a different question: which fileschanged, what the run cost, what the threat rules flagged.-A lens runs in a sandboxed frame with no network and no access to the dashboard.-It receives the trace through one call, `window.beacon.getTrace()`. Everything+A lens runs in a sandboxed frame with no access to Beacon or the dashboard and+no ordinary network APIs. It receives the trace through one call,+`window.beacon.getTrace()`. Everythingelse is plain HTML, CSS and JavaScript, so any coding agent can write one fromthis document.@@ -150,10 +151,11 @@ The full field list is the Go source in `pkg/asymptoteobserve/trace.go` andA lens sees whatever the local log retained. With `full` retention thatincludes prompts, responses, command output and diffs, after Beacon's local-redaction. A lens can show that content on screen and nowhere else: the-sandbox below gives it no way to send it anywhere. Forwarding privacy modes-(such as metadata-only) govern what leaves the machine. They do not reduce-what a local lens receives.+redaction. The sandbox below is built so that a lens shows that content on+screen and nowhere else, but it cannot guarantee it: see+[Trust model](#trust-model). Forwarding privacy modes (such as metadata-only)+govern what Beacon sends off the machine. They do not reduce what a local+lens receives.## Sandbox@@ -181,17 +183,24 @@ The host enforces these rules; a lens does not opt into them.script runs, every `RTC*` interface on `window` (including`RTCPeerConnection`, `RTCDataChannel` and `webkitRTCPeerConnection`) isdefined as `undefined`, non-writable and non-configurable. A lens cannot- delete or redefine them. This holds inside the lens's own realm only; it- relies on the CSP and sandbox above to keep the lens from reaching a fresh- realm (a frame, worker or popup) where the originals still exist.+ delete or redefine them. This holds in the lens's own realm only. A child+ frame is a fresh realm where they still exist: the lens cannot reach into+ one (a sandboxed child has its own opaque origin), but a `srcdoc` child+ runs its own scripts, which is why the host refuses child frames (next).+- The host refuses, before any lens script runs, the elements that can start+ a request the CSP does not see or open a fresh realm: nested frames+ (`iframe`, `frame`, `object`, `embed`, `portal`, `fencedframe`), every+ `<link>` element (a lens loads nothing by URL, and resource hints such as+ `preconnect`, `prefetch` and `preload` are links), and+ `<script type="speculationrules">`. Creating one, inserting one, or parsing+ one in through `innerHTML`, `outerHTML`, `insertAdjacentHTML`,+ `setHTMLUnsafe` or `execCommand` throws a `NotSupportedError`+ `DOMException`; `document.write` and `document.writeln` always throw; and+ any the parser puts in from the lens file's own markup is removed before+ the next script runs.- The frame is served with `X-DNS-Prefetch-Control: off`, and the hostrepeats it as a `<meta http-equiv>` in the document, so the browser does notresolve hostnames the lens mentions on its own.-- Residual risk. CSP and the sandbox are the boundary, and browsers do not- route every speculative or connection-warming request through them; some- resource-hint and speculative-loading features can still start a request a- CSP does not see, depending on the browser and its settings. Treat a lens- as code that can read the whole trace, and install only lenses you trust.- Trace data reaches the frame only over a private `MessageChannel` port. Theone `postMessage` from the host to the window carries that port andnothing else. The lens never uses `window.postMessage` itself;@@ -202,6 +211,29 @@ The host enforces these rules; a lens does not opt into them.the timeout, the host falls back to the full trace view. A broken lenscannot break the dashboard.+### Trust model++The opaque origin, the sandbox and the CSP are enforced by the browser. They+keep a lens from touching Beacon, the dashboard, its storage or its API, and+they refuse the ordinary network APIs (`fetch`, XHR, WebSocket,+`EventSource`, `sendBeacon`, remote images, fonts and scripts, frames,+workers and navigation).++They cannot fully prevent a lens from sending the trace data it is shown out+of the machine. Some browser features are not governed by CSP or any other+policy a page can set: WebRTC, and resource hints and speculative loading+such as `preconnect` and speculation rules. The removal and refusals above+are best-effort hardening inside the lens's own page, not a boundary: they+close the common ways to reach those features, and a determined lens may find+another. They do not cover what the browser's preload scanner does with the+file's own markup before any script runs, closed declarative shadow roots,+or attribute changes made through `Attr` nodes.++So an installed lens is code you trust with the trace data it is shown.+Read a lens before you install it, and install only lenses you trust.+`beacon lenses add` asks for that confirmation, and `beacon lenses lint`+warns on the features above.+## Layout and style- **Height.** The host sizes the frame to the document's height and keeps it@@ -270,3 +302,7 @@ The host enforces these rules; a lens does not opt into them.- `lenses/v1` (additive): `cache_creation_1h_input_tokens` in every usage object,the subset of `cache_creation_input_tokens` written with a one-hour TTL wherethe source reported it. It is a breakdown; never add it to a total.+- `lenses/v1` (hardening): the host removes WebRTC, refuses nested frames,+ `<link>` elements, speculation rules and `document.write`, and turns off DNS+ prefetching. A lens that follows this spec uses none of them; the+ [trust model](#trust-model) says what this does and does not guarantee.