Browser Secure

Secure browser automation with Chrome profile support, vault integration, approval gates, and comprehensive audit logging. Use for authenticated sites, sensitive operations, or compliance requirements.

Security Scan

The skill broadly matches its stated purpose (vault-backed browser automation), but there are several inconsistencies and risky choices (curl|bash installer, ambiguous install metadata, profile-handling claims vs. code, and powerful local access) that merit caution and review before installing or running it.

Purpose & Capability

The description (secure browser automation with vaults/profiles/approval/audit) aligns with the implementation: many source files implement Playwright automation, vault integrations (Bitwarden/1Password), profile handling, approval gates, and audit logging. However the registry metadata and SKILL.md declare 'no install spec' and 'required binaries: none' while setup.json and README require Node.js 18+, npm, Chrome, Playwright browsers, and optional vault CLIs. That's an internal inconsistency: the code requires a runtime environment (Node + Playwright + browser CLIs) that the top-level metadata omits. Also package.json documents optional environment variables for Bitwarden/1Password which are necessary for automation — that is consistent functionally but not represented in the registry 'required env' fields.

Instruction Scope

SKILL.md instructs the agent/user to run installers and CLI tools (including a curl | bash install from raw.githubusercontent.com, npm run setup, and brew installs) and to unlock vaults (BW_SESSION, bw unlock, op signin). It explicitly offers to use existing Chrome profiles; the prose claims it 'reads from (but does not write to) existing profiles', but the code uses Playwright.launchPersistentContext with the profile directory which can and often does modify profile data. The skill runs many child processes (bw, op, security, which) to read secrets and system state — all within scope for a vault-integrated browser automation tool, but these actions grant broad local access (profile data, keychain, vault contents). SKILL.md also instructs optional creation of ~/.browser-secure/config.yaml and saving credential mappings, which persists sensitive mappings on disk.

Install Mechanism

The package has no platform install spec in the registry, yet SKILL.md and README instruct: (1) Clawdbot auto-install (proprietary flow), (2) curl -fsSL https://raw.githubusercontent.com/.../install-browser-secure.sh | bash, and (3) manual npm run setup. Piping a script from raw.githubusercontent.com into bash is a high-risk install mechanism unless you audit that script first; the repo/source is listed as 'unknown' and no homepage is provided. Auto-install will also download Playwright browser binaries (normal) and may brew install vault CLIs. The presence of scripts/onboarding.js and an installer script means arbitrary code will be written/executed during setup — this increases install-time risk.

Credentials

The code legitimately uses Bitwarden and 1Password environment tokens and session values (BW_CLIENTID, BW_CLIENTSECRET, BW_PASSWORD, BW_SESSION, OP_SERVICE_ACCOUNT_TOKEN) for vault access — those env vars are proportionate for a vault-backed automation tool. package.json marks them optionalEnv. However, the skill will also access other local secrets implicitly: it can read Chrome profile paths (and likely cookies/session tokens if a profile is used) and may read macOS Keychain via the 'security' binary. Because the skill offers to read from existing profiles, using it with your Default/personal profile risks exposing personal session data. The skill also persists credential mappings to ~/.browser-secure/config.yaml if you accept — that is sensitive and should be audited and protected.

Persistence & Privilege

always is false and the skill is user-invocable (normal). The installer and setup will create ~/.browser-secure/ for configs and audit logs and may link a global 'browser-secure' CLI (npm link). That's expected for a CLI tool. Note: autonomous invocation is allowed (default), and because the skill can access vaults, profiles, and run shell commands, autonomous invocation combined with vault/profile access would increase the blast radius — this is a risk to weigh but not alone grounds for rejection.

What to consider before installing

Key things to consider before installing or running this skill: 1) Source verification: the SKILL.md/README instruct an install via curl | bash from raw.githubusercontent.com. Do NOT pipe remote scripts to bash unless you have reviewed the exact script. Inspect scripts/install-browser-secure.sh and scripts/onboarding.js in the repository first (clone the repo and read them locally). 2) Runtime requirements mismatch: registry metadata lists no required binaries but the tool needs Node.js >=18, npm, Chrome/Playwright, and optionally brew + vault CLIs. If you install, do so on a trusted, isolated machine or VM and follow a manual install path (git clone + inspect + npm run setup) rather than blindly running the network installer. 3) Vault and env credentials: the tool expects Bitwarden/1Password credentials (BW_SESSION, BW_PASSWORD, BW_CLIENTID/SECRET, OP_SERVICE_ACCOUNT_TOKEN). Only set these env vars on trusted machines and prefer manual unlocking (bw unlock or op signin) over storing master passwords in .env. Avoid putting master credentials into long-lived env files unless you understand the risk. 4) Chrome profile handling: SKILL.md claims it "reads but does not write" existing profiles, but the code launches Playwright persistent contexts against profile directories which can modify profile data. If you must use a profile, avoid using your Default/personal profile. Prefer creating a dedicated automation profile or use incognito/isolation mode. 5) Approval/unattended modes: Do not enable unattended mode with --skip-approval or global auto-approval until you have audited behavior. Unattended execution + vault access can exfiltrate secrets if misused. 6) Audit the code paths that run shell commands (search for execSync/spawnSync calls in src/vault/* and src/browser/*) and confirm there are no unexpected network exfil endpoints or hard-coded remote uploads. Also confirm where audit logs are written and their permissions ( ~/.browser-secure/ ). 7) Safer deployment: test in a sandbox (VM or disposable container), enable interactive approval prompts, and avoid piping install scripts. If you need this capability for sensitive systems, conduct a code review or ask the publisher for a verified package (signed release or published npm package / GitHub release) and a homepage/contact for accountability. If you want, I can: - Summarize exact lines/files that call external commands and list them for targeted review, - Fetch and show the contents of scripts/install-browser-secure.sh (if you provide it) for inspection, - Suggest a minimal, safe test plan to validate behavior in a VM before use.

Secure browser automation with vault-backed credentials, approval gates, and audit trails.

Philosophy

"Never trust, always verify, encrypt everything, audit all actions"

Quick Start

# Open the welcome page (default when no URL provided)
browser-secure navigate

# Navigate to a public site
browser-secure navigate https://example.com

# Navigate with auto-vault credential discovery
browser-secure navigate https://app.neilpatel.com/ --auto-vault

# Navigate to an authenticated site (pre-configured)
browser-secure navigate https://nytimes.com --site=nytimes

# Perform actions (fully automated)
browser-secure act "click the login button"
browser-secure extract "get the article headlines"

# Use interactive mode (with approval prompts)
browser-secure navigate https://bank.com --interactive

# Close and cleanup
browser-secure close

Auto-Vault Credential Discovery

The --auto-vault flag enables interactive credential discovery from your password manager:

browser-secure navigate https://app.neilpatel.com/ --auto-vault

This will:

1. Extract the domain from the URL (app.neilpatel.com → neilpatel)
2. Search Bitwarden first (free, default), then 1Password if available
3. Present matching items interactively:

🔍 Auto-discovering credentials for app.neilpatel.com...

📋 Found 2 matching credential(s) in Bitwarden:

  1) Neil Patel Account
     Username: [e-mail]
  2) Ubersuggest API Key

  n) None of these - try another vault
  m) Manually enter credentials

Select credential to use (1-2, n, or m): 1
🔐 Retrieving credentials for neilpatel...

Save this credential mapping for future use? (y/n): y
✅ Saved credential mapping for "neilpatel" to ~/.browser-secure/config.yaml
   Default vault provider set to: Bitwarden

After saving, you can use the simpler command next time:

browser-secure navigate https://app.neilpatel.com/ --site=neilpatel

Profile Management

Create isolated Chrome profiles for secure automation with automatic welcome page setup:

# Create a new profile with welcome page
browser-secure profile --create "Funny Name"

# Create and immediately launch Chrome
browser-secure profile --create "The Crustacean Station 🦞" --launch

# List all Chrome profiles
browser-secure profile --list

What the Welcome Page Includes

When you create a new profile, it opens with a custom welcome page that guides you through:

1. 📖 Why This Profile Exists - Explains the isolated automation concept
2. 🔌 Required Extensions - Direct links to install:
   • Bitwarden password manager
   • OpenClaw Browser Relay
3. 🗝️ Vault Setup - Step-by-step for Bitwarden or 1Password
4. ✅ Setup Checklist - Interactive checklist to track progress
5. 🛡️ Security Info - "Your vault is secure" messaging with key features

Why Separate Profiles?

Aspect	Personal Profile	Automation Profile
Extensions	Your personal ones	Only automation extensions
Cookies	Personal logins	Isolated session state
Security	Shared with daily browsing	Locked down, audited
Cleanup	Manual	Automatic session timeout

Chrome Profile Support

Browser Secure can use your existing Chrome profiles, giving you access to saved cookies, session state, and existing website logins.

List Available Profiles

browser-secure navigate https://example.com --list-profiles

Output:

📋 Available Chrome profiles:

  1. Person 1 ★
     ID: Default
     Path: /Users/river/Library/Application Support/Google/Chrome/Default

  2. Work
     ID: Profile 1
     Path: /Users/river/Library/Application Support/Google/Chrome/Profile 1

Use a Specific Profile

# By profile ID
browser-secure navigate https://gmail.com --profile "Default"
browser-secure navigate https://gmail.com --profile "Profile 1"

# Interactively select
browser-secure navigate https://gmail.com --profile select

Profile vs Incognito Mode

Mode	Cookies	Logins	Extensions	Use Case
Incognito (default)	❌ None	❌ None	❌ None	Secure, isolated testing
Chrome Profile	✅ Yes	✅ Yes	✅ Yes	Access existing sessions

Security Note: Browser Secure creates isolated profiles for automation without modifying your existing Chrome profiles. When using --profile, it reads from (but does not write to) existing profiles.

Setup

Option 1: Install via Clawdbot (Recommended)

The easiest way—just ask Clawdbot:

Hey Clawdbot, install browser-secure for me

Clawdbot will handle everything: check prerequisites, auto-install dependencies, build, and configure.

Option 2: Install from GitHub

# Clone and install
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/install-browser-secure.sh | bash

Option 3: Manual Setup (Advanced)

If you prefer full control or are developing on the tool:

# Clone the repository
git clone https://github.com/openclaw/openclaw.git
cd openclaw/skills/browser-secure

# Run interactive setup
npm run setup

This will:

1. ✅ Check prerequisites (Node.js 18+, Chrome)
2. 📦 Auto-install missing dependencies (Playwright browsers, optional vault CLIs)
3. 🔨 Build and link the CLI globally
4. 📝 Create default configuration

What Gets Auto-Installed

The setup automatically handles:

• Playwright Chromium - Required browser binary (~50MB)
• Bitwarden CLI - If brew is available (recommended vault)
• 1Password CLI - If brew is available (optional)

Configure Vault (Optional)

After setup, configure your preferred vault using environment variables (recommended) or direct CLI login:

Option A: .env File (Convenience for Automation)

⚠️ Security Note: .env files store credentials in plaintext. Only use this on trusted, private machines. Vault integration (Bitwarden/1Password) is the recommended secure approach.

cd ~/.openclaw/workspace/skills/browser-secure
cp .env.example .env
# Edit .env with your credentials

Full Automation (API Key + Password):

# .env - For fully automated vault access
BW_CLIENTID=user.xxx-xxx
BW_CLIENTSECRET=your-secret-here
BW_PASSWORD=your-master-password

How it works:

1. BW_CLIENTID/BW_CLIENTSECRET → Authenticates with Bitwarden (replaces username/password)
2. BW_PASSWORD → Decrypts your vault (required for automated access)

Alternative: Session Token

# If you prefer not to store your master password:
export BW_SESSION=$(bw unlock --raw)
# Then add to .env:
# BW_SESSION=xxx...

Option B: Direct CLI Login

# Bitwarden (recommended - free)
brew install bitwarden-cli  # if not auto-installed
bw login
export BW_SESSION=$(bw unlock --raw)

# 1Password (if you have a subscription)
brew install 1password-cli  # if not auto-installed
op signin

# Test vault access
browser-secure vault --list

Verify Installation

browser-secure --version
browser-secure navigate https://example.com
browser-secure screenshot
browser-secure close

Vault Providers

Bitwarden (Default, Free) ⭐

Recommended — free for personal use, open source, cross-platform.

# Install
brew install bitwarden-cli

# Setup .env file
cd ~/.openclaw/workspace/skills/browser-secure
cp .env.example .env
# Edit .env and add:
#   BW_CLIENTID=your-api-key-id
#   BW_CLIENTSECRET=your-api-key-secret  
#   BW_PASSWORD=your-master-password

# Use - credentials auto-loaded from .env
browser-secure navigate https://app.neilpatel.com/ --auto-vault

Authentication vs Unlock:

• API Key (BW_CLIENTID/BW_CLIENTSECRET) → Logs you into Bitwarden
• Master Password (BW_PASSWORD) → Decrypts your vault contents
• Both are needed for fully automated workflows

Get API Key: https://vault.bitwarden.com/#/settings/security/keys

1Password (Paid)

Alternative — if you already have a 1Password subscription.

# Install
brew install 1password-cli

# Login
op signin
eval $(op signin)

# Use
browser-secure navigate https://app.neilpatel.com/ --auto-vault

macOS Keychain (Local)

Fallback — store credentials in macOS Keychain (no cloud sync).

Environment Variables

Emergency fallback — set credentials via env vars:

export BROWSER_SECURE_NEILPATEL_USERNAME="[e-mail]"
export BROWSER_SECURE_NEILPATEL_PASSWORD="secret"
browser-secure navigate https://app.neilpatel.com/

Commands

Command	Description
navigate	Open welcome page (default when no URL provided)
navigate <url>	Navigate to a URL
navigate <url> --profile <id>	Use specific Chrome profile
navigate <url> --profile select	Interactively choose Chrome profile
navigate <url> --list-profiles	List available Chrome profiles
navigate <url> --auto-vault	Auto-discover credentials (Bitwarden → 1Password → manual)
navigate <url> --site=<name>	Use pre-configured site credentials
profile --create <name>	Create new Chrome profile with welcome page
profile --create <name> --launch	Create profile and launch Chrome
profile --list	List all Chrome profiles
act "<instruction>"	Natural language action
extract "<instruction>"	Extract data from page
screenshot	Take screenshot
close	Close browser and cleanup
status	Show session status
audit	View audit logs

Welcome Page (Default)

When you run browser-secure navigate without a URL, it opens the welcome page located at:

~/.openclaw/workspace/skills/browser-secure/assets/welcome.html

The welcome page provides:

• 📖 Onboarding guide — Why browser-secure exists and how it works
• 🔌 Extension links — Direct install for Bitwarden and OpenClaw Browser Relay
• 🗝️ Vault setup — Step-by-step for Bitwarden or 1Password
• ✅ Setup checklist — Interactive checklist to track progress
• 🛡️ Security info — "Your vault is secure" messaging with key features

Pro tip: Use the welcome page as your starting point for new profiles:

# Create a profile, then immediately open welcome page
browser-secure profile --create "Work Automation" --launch
# Then in another terminal:
browser-secure navigate  # Opens welcome page in the active session

Approval Modes (Hybrid Design)

browser-secure operates in unattended mode by default, making it ideal for agent automation while preserving safety guardrails.

Default Mode: Unattended (Automation-First)

# All commands run unattended by default - no interactive prompts
browser-secure navigate https://example.com
browser-secure act "fill the search form"
browser-secure extract "get all links"

In this mode:

• ✅ All non-destructive actions execute immediately
• ✅ Credentials auto-injected from vault
• ✅ Audit trail written automatically
• ⚠️ Destructive actions (delete, purchase) require --skip-approval or --interactive

Interactive Mode (Human-in-the-Loop)

For sensitive operations, use --interactive to enable approval prompts:

# Enable tiered approval gates
browser-secure navigate https://bank.com --interactive

# Approve individual actions
browser-secure act "transfer $1000" --interactive

Approval tiers in interactive mode:

Tier	Actions	Approval
Read-only	navigate, screenshot, extract	None
Form fill	type, select, click	Prompt
Authentication	fill_password, submit_login	Always
Destructive	delete, purchase	2FA required

Force Override (Emergency)

# Skip ALL approvals including destructive (DANGEROUS)
browser-secure act "delete account" --skip-approval

⚠️ Warning: --skip-approval bypasses all safety checks. Use only in fully automated, sandboxed environments.

Session Security

• Time-bounded (30 min default, auto-expiry)
• Isolated work directories (UUID-based)
• Incognito mode (no persistent profile) — default
• Chrome profile support (your cookies, logins, extensions) — opt-in via --profile
• Secure cleanup (overwrite + delete)
• Network restrictions (block localhost/private IPs)

Audit Trail

{
  "event": "BROWSER_SECURE_SESSION",
  "sessionId": "bs-20260211054500-abc123",
  "site": "nytimes.com",
  "actions": [...],
  "chainHash": "sha256:..."
}

Environment Variables

Variable	Purpose
BROWSER_SECURE_CONFIG	Config file path
BW_CLIENTID	Bitwarden API key ID (for automation)
BW_CLIENTSECRET	Bitwarden API key secret (for automation)
BW_PASSWORD	Bitwarden master password (alternative)
BW_SESSION	Bitwarden session token (legacy)
OP_SERVICE_ACCOUNT_TOKEN	1Password service account
BROWSER_SECURE_{SITE}_PASSWORD	Env-based credentials

Comparison with browser-automation

Feature	browser-automation	browser-secure
Credentials	CLI (exposed)	Vault-backed
Chrome Profiles	❌ No	✅ Yes (with cookies/logins)
Approval	None	Tiered gates
Audit	None	Full trail
Session timeout	None	30 min default
Network	Unrestricted	Allow-list
Best for	Quick tasks	Sensitive/authenticated

Troubleshooting

Chrome keychain prompt on first run: This is normal! When Playwright launches Chrome for the first time, macOS asks if Chrome can access your keychain. You can click "Deny" since browser-secure manages credentials through your vault, not Chrome's built-in storage.

Vault not found: Install the CLI for your preferred vault:

• Bitwarden: brew install bitwarden-cli
• 1Password: brew install 1password-cli

Bitwarden "Vault is locked":

• If using .env file: Check that BW_CLIENTID and BW_CLIENTSECRET are set correctly
• Or run: export BW_SESSION=$(bw unlock --raw)

Bitwarden API key not working: Ensure your API key has access to the vault items you need. API keys are created at: https://vault.bitwarden.com/#/settings/security/keys

Site not configured: Use --auto-vault for interactive setup, or add manually to ~/.browser-secure/config.yaml

Session expired: Default 30-minute TTL, restart with --timeout

Approval required: Use -y for non-interactive (careful!)

Profile not found: Run browser-secure navigate https://example.com --list-profiles to see available profiles

Chrome profile in use: Close Chrome before using --profile option (Chrome locks profile when running)