From 2e3888266462424a4b5f2296b9a4ba0b368e9413 Mon Sep 17 00:00:00 2001 From: Chris Tate Date: Wed, 25 Feb 2026 15:47:26 -0600 Subject: [PATCH] prepare v0.15 (#544) * add security hardening features - Add authentication vault (`auth save/login/list/show/delete`) so credentials are stored locally and never exposed to the LLM (fixes Snyk W007) - Add `--content-boundaries` flag to wrap page-sourced output in structural markers, helping LLMs distinguish tool output from untrusted page content (fixes Snyk W011) - Add `--allowed-domains` flag to restrict browser navigation to trusted domains - Add `--action-policy` for static allow/deny gating of action categories, with opt-in `--confirm-actions`/`--confirm-interactive` for orchestrator or human-in-the-loop confirmation - Add `--max-output` flag to truncate large page outputs, preventing context flooding - New docs page at /security, updated README, SKILL.md, CLI help text, and templates * fixes * fixes * fixes * fixes * fixes * fixes * fixes * docs * prepare v0.15 --- .changeset/v0150-security-hardening.md | 7 ++ docs/src/app/changelog/page.mdx | 117 +++++++++++++++++++++++++ docs/src/app/commands/page.mdx | 52 +++++++++++ docs/src/app/configuration/page.mdx | 25 +++++- 4 files changed, 200 insertions(+), 1 deletion(-) create mode 100644 .changeset/v0150-security-hardening.md diff --git a/.changeset/v0150-security-hardening.md b/.changeset/v0150-security-hardening.md new file mode 100644 index 0000000..82a8f2b --- /dev/null +++ b/.changeset/v0150-security-hardening.md @@ -0,0 +1,7 @@ +--- +"agent-browser": minor +--- + +- Added security hardening: authentication vault, content boundary markers, domain allowlist, action policy, action confirmation, and output length limits. +- Added `--download-path` flag (and `AGENT_BROWSER_DOWNLOAD_PATH` env / `downloadPath` config key) to set a default download directory. +- Added `--selector` flag to `scroll` command for scrolling within specific container elements. diff --git a/docs/src/app/changelog/page.mdx b/docs/src/app/changelog/page.mdx index d5d8e54..7000a48 100644 --- a/docs/src/app/changelog/page.mdx +++ b/docs/src/app/changelog/page.mdx @@ -4,6 +4,123 @@ export const metadata = pageMetadata("changelog") # Changelog +## v0.15.0 + +

February 2026

+ +### New Features + +- **Authentication vault** -- Store credentials locally (always AES-256-GCM encrypted) and reference them by name. The LLM never sees passwords. Commands: `auth save`, `auth login`, `auth list`, `auth show`, `auth delete`. Passwords can be piped via stdin (`--password-stdin`) to avoid shell history exposure. +- **Content boundary markers** -- `--content-boundaries` wraps page-sourced output in structural delimiters with a per-process CSPRNG nonce, so LLMs can distinguish trusted tool output from untrusted page content. In `--json` mode, a `_boundary` object is injected with `nonce` and `origin` fields. +- **Domain allowlist** -- `--allowed-domains` restricts navigation, sub-resource requests, WebSocket connections, and EventSource streams to trusted domains. Supports exact match and wildcard prefix patterns (e.g., `*.example.com`). +- **Action policy** -- `--action-policy` gates actions using a static JSON policy file with `allow`/`deny` lists across 13 action categories. Auth vault operations bypass policy enforcement. +- **Action confirmation** -- `--confirm-actions` requires explicit approval for sensitive action categories. New `confirm` and `deny` commands for orchestrator use. `--confirm-interactive` enables human-in-the-loop terminal prompts (auto-denies if stdin is not a TTY). Pending confirmations auto-deny after 60 seconds. +- **Output length limits** -- `--max-output` truncates large page outputs to prevent LLM context flooding. +- **`--download-path` option** -- Set a default download directory via flag, `AGENT_BROWSER_DOWNLOAD_PATH` env var, or `downloadPath` config key. Without it, downloads go to a temporary directory deleted when the browser closes. +- **`--selector` flag for scroll** -- Scroll within a specific container element instead of the page: `agent-browser scroll down 500 --selector "div.scroll-container"` + +```bash +# Auth vault +echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin +agent-browser auth login github + +# Security flags +agent-browser --content-boundaries --allowed-domains "example.com,*.example.com" --max-output 50000 open https://example.com + +# Download path +agent-browser --download-path ./downloads open https://example.com + +# Scroll within container +agent-browser scroll down 500 --selector "div.content" +``` + +### Environment Variables + +Six new environment variables for security configuration: `AGENT_BROWSER_CONTENT_BOUNDARIES`, `AGENT_BROWSER_MAX_OUTPUT`, `AGENT_BROWSER_ALLOWED_DOMAINS`, `AGENT_BROWSER_ACTION_POLICY`, `AGENT_BROWSER_CONFIRM_ACTIONS`, `AGENT_BROWSER_CONFIRM_INTERACTIVE`. + +--- + +## v0.14.0 + +

February 2026

+ +### New Features + +- **`keyboard` command** -- Type with real keystrokes, insert text, and press shortcuts at the currently focused element without needing a selector (`keyboard type`, `keyboard inserttext`). +- **`--color-scheme` flag** -- Persistent dark/light mode preference across browser sessions via flag or `AGENT_BROWSER_COLOR_SCHEME` env var. + +```bash +agent-browser keyboard type "Hello world" +agent-browser keyboard inserttext "pasted text" +agent-browser --color-scheme dark open https://example.com +``` + +### Bug Fixes + +- Fixed IPC EAGAIN errors (os error 35/11) with backpressure-aware socket writes, command serialization, and lowered default Playwright timeout to 25s (configurable via `AGENT_BROWSER_DEFAULT_TIMEOUT`). +- Fixed remote debugging (CDP) reconnection. +- Fixed state load failing when no browser is running. +- Fixed `--annotate` flag warning appearing when not explicitly passed via CLI. + +--- + +## v0.13.0 + +

February 2026

+ +### New Features + +- **Diff commands** -- Compare snapshots, screenshots, and URLs between page states. Run visual pixel diffs against baseline images, compare accessibility tree snapshots with customizable depth and selectors, and diff two URLs side-by-side with optional screenshot comparison. + +```bash +agent-browser diff snapshot +agent-browser diff screenshot --baseline before.png +agent-browser diff url https://staging.example.com https://prod.example.com +``` + +--- + +## v0.12.0 + +

February 2026

+ +### New Features + +- **Annotated screenshots** -- `--annotate` flag overlays numbered labels on interactive elements and prints a legend mapping each label to its element ref. Enables multimodal AI models to reason about visual layout while using the same `@eN` refs for subsequent interactions. Also settable via `AGENT_BROWSER_ANNOTATE` env var. + +```bash +agent-browser screenshot --annotate +``` + +--- + +## v0.11.1 + +

February 2026

+ +### Documentation + +- Added documentation for command chaining with `&&` across README, CLI help output, docs, and skill files. + +--- + +## v0.11.0 + +

February 2026

+ +### New Features + +- **Configuration file support** -- Automatic loading from user (`~/.agent-browser/config.json`) and project (`./agent-browser.json`) directories with priority-based merging. +- **Profiler commands** -- Chrome DevTools profiling with `profiler start` and `profiler stop`. +- **Browser extension loading** -- `--extension` flag to load browser extensions. +- **Storage state management** -- `state save` and `state load` commands for auth state persistence. +- **iOS device emulation** -- `--device` flag for device emulation. +- **Enhanced click** -- `--new-tab` option for click commands. +- **Enhanced find** -- Additional actions and filtering options. +- **CDP WebSocket URLs** -- `--cdp` now accepts WebSocket URLs in addition to ports. + +--- + ## v0.10.0

February 2026

diff --git a/docs/src/app/commands/page.mdx b/docs/src/app/commands/page.mdx index 1a56432..582876e 100644 --- a/docs/src/app/commands/page.mdx +++ b/docs/src/app/commands/page.mdx @@ -201,6 +201,49 @@ agent-browser errors --clear # Clear error log agent-browser highlight # Highlight element ``` +## Auth vault + +```bash +agent-browser auth save [opts] # Save auth profile +agent-browser auth login # Login using saved credentials +agent-browser auth list # List saved profiles (names and URLs only) +agent-browser auth show # Show profile metadata (no passwords) +agent-browser auth delete # Delete a saved profile +``` + +Save options: + +- `--url ` -- login page URL (required) +- `--username ` -- username (required) +- `--password ` -- password (required unless `--password-stdin`) +- `--password-stdin` -- read password from stdin (recommended to avoid shell history exposure) +- `--username-selector ` -- custom CSS selector for username field +- `--password-selector ` -- custom CSS selector for password field +- `--submit-selector ` -- custom CSS selector for submit button + +```bash +echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin +agent-browser auth login github +agent-browser auth list +``` + +## Confirmation + +When `--confirm-actions` is set, certain action categories return a `confirmation_required` response instead of executing immediately. Use `confirm` or `deny` to approve or reject the action. + +```bash +agent-browser confirm # Approve a pending action +agent-browser deny # Deny a pending action +``` + +Pending confirmations auto-deny after 60 seconds. + +```bash +agent-browser --confirm-actions eval,download eval "document.title" +# Returns confirmation_required with ID +agent-browser confirm c_8f3a1234 +``` + ## State management ```bash @@ -253,6 +296,15 @@ agent-browser reload # Reload page --headed # Show browser window (not headless) --cdp # Connect via Chrome DevTools Protocol (port or WebSocket URL) --auto-connect # Auto-discover and connect to running Chrome +--color-scheme # Color scheme: dark, light, no-preference +--download-path # Default download directory +--content-boundaries # Wrap page output in boundary markers for LLM safety +--max-output # Truncate page output to N characters +--allowed-domains # Comma-separated allowed domain patterns +--action-policy # Path to action policy JSON file +--confirm-actions # Action categories requiring confirmation +--confirm-interactive # Interactive confirmation prompts (auto-denies if stdin is not a TTY) +--config # Use a custom config file --debug # Debug output ``` diff --git a/docs/src/app/configuration/page.mdx b/docs/src/app/configuration/page.mdx index d476c1d..f14a2d3 100644 --- a/docs/src/app/configuration/page.mdx +++ b/docs/src/app/configuration/page.mdx @@ -74,6 +74,12 @@ Every CLI flag can be set in the config file using its camelCase equivalent: autoConnect--auto-connectboolean colorScheme--color-schemestring (dark, light, no-preference) downloadPath--download-pathstring + contentBoundaries--content-boundariesboolean + maxOutput--max-outputnumber + allowedDomains--allowed-domainsstring[] + actionPolicy--action-policystring + confirmActions--confirm-actionsstring + confirmInteractive--confirm-interactiveboolean headers--headersstring (JSON) @@ -117,6 +123,17 @@ Every CLI flag can be set in the config file using its camelCase equivalent: } ``` +### AI Agent Security + +```json +{ + "contentBoundaries": true, + "maxOutput": 50000, + "allowedDomains": ["your-app.com", "*.your-app.com"], + "actionPolicy": "./policy.json" +} +``` + ## Overriding Boolean Options Boolean flags accept an optional `true`/`false` value to override config settings: @@ -132,7 +149,7 @@ agent-browser --headed open example.com # same as --headed true agent-browser --headed true open example.com # explicit ``` -This applies to all boolean flags: `--headed`, `--debug`, `--json`, `--ignore-https-errors`, `--allow-file-access`, `--auto-connect`. +This applies to all boolean flags: `--headed`, `--debug`, `--json`, `--ignore-https-errors`, `--allow-file-access`, `--auto-connect`, `--content-boundaries`, `--confirm-interactive`. ## Extensions Merging @@ -161,6 +178,12 @@ These environment variables configure additional daemon and runtime behavior: AGENT_BROWSER_IOS_DEVICEDefault iOS device name for the ios provider.(none) AGENT_BROWSER_IOS_UDIDDefault iOS device UDID for the ios provider.(none) AGENT_BROWSER_DEBUGEnable debug output (1 to enable).(disabled) + AGENT_BROWSER_CONTENT_BOUNDARIESWrap page output in boundary markers for LLM safety.(disabled) + AGENT_BROWSER_MAX_OUTPUTMax characters for page output (truncates beyond limit).(unlimited) + AGENT_BROWSER_ALLOWED_DOMAINSComma-separated allowed domain patterns (e.g., example.com,*.example.com).(unrestricted) + AGENT_BROWSER_ACTION_POLICYPath to action policy JSON file.(none) + AGENT_BROWSER_CONFIRM_ACTIONSComma-separated action categories requiring confirmation.(none) + AGENT_BROWSER_CONFIRM_INTERACTIVEEnable interactive confirmation prompts (auto-denies if stdin is not a TTY).(disabled)