BrowseCTL

WebDriver automation CLI for AI-driven browser control. Provides session management, tab control, element interaction, screenshots, batch execution, and an i...

Security Scan

The skill appears to be what it claims (a browsectl CLI wrapper) but includes disk/network install steps and documented behavior that can read and copy local browser profiles (cookies/extensions) automatically in non-interactive mode — a risky capability that should be considered before installing.

Purpose & Capability

Name/description align with the files and runtime behavior: this is an npm wrapper that installs and proxies to a browsectl binary and provides WebDriver-based browser automation. Requiring a browsectl binary and providing npm install instructions is coherent.

Instruction Scope

SKILL.md explicitly instructs running `browsectl setup` which will detect installed browsers and auto-download matching WebDriver binaries. The session-create docs describe copying user browser data (cookies and extensions) into the automation profile — and note that in non-interactive/background mode this copy defaults to enabled. That means the tool will access sensitive local browser profile files (Cookies SQLite DB, extensions) without additional environment variables or credentials. The instructions also persist sessions and driver info to ~/.browsectl, and start detached driver processes.

Install Mechanism

The npm package's postinstall (scripts/install.js) downloads a platform-specific prebuilt binary from GitHub Releases (https://github.com/yorelog/browsectl/releases) and extracts it into the package bin directory. Downloading releases from GitHub is common and reasonable, but it does write and chmod an executable on disk and relies on a network fetch at install time — this is moderate-risk behavior (trusted host but arbitrary binary execution).

Credentials

The skill declares no required environment variables, which is fine, but the documented runtime behavior involves reading local browser installations and profiles and (by default in non-interactive/background worker mode) copying cookies and extensions from the user's real browser profile. Access to these local files is not represented in the package metadata and is sensitive. No external API keys are requested, but local data access can still expose secrets (login cookies, extension state).

Persistence & Privilege

The skill is not marked always:true. It persists runtime state and sessions to ~/.browsectl and can spawn detached WebDriver server processes that remain running after CLI exit. Persisting sessions and storing binaries under the package are expected for a CLI tool, but you should be aware it creates files and running processes on install/use.

Scan Findings in Context

[postinstall_network_download_from_github_releases] expected: scripts/install.js downloads a platform-specific archive from GitHub Releases and extracts it to create the `browsectl` binary. This is expected for packaging a prebuilt CLI binary but means code is fetched and executed at install time.

[exec_child_process_to_proxy_binary] expected: scripts/run.js uses child_process.execFileSync to invoke the installed binary. This is the expected behavior for an npm wrapper that proxies to a native executable.

[local_browser_profile_access_and_copy] expected: SKILL.md and session docs describe detecting installed browsers, reading profile paths, and copying cookies/extensions into an automation profile (and defaulting to copy in non-interactive mode). This is consistent with a browser automation tool but represents sensitive local file access.

What to consider before installing

This package is coherent with its stated purpose (a WebDriver CLI wrapper) but has two important security considerations: 1) Install behavior: the npm postinstall will download a prebuilt binary from GitHub Releases and place an executable on disk. That binary will be executed via the wrapper. Treat that as running third-party native code — verify the publisher/repo and trustworthiness before installing. 2) Sensitive local data access: the tool is designed to detect your installed browsers and (unless you opt out) can copy cookies and extensions from your real browser profile into the automation profile. If you run it non-interactively (background worker or invoked by an agent), the docs say it defaults to copying cookies and extensions. That can expose authentication cookies and extension data. If you need this skill, either run it in interactive mode and decline copying, use the explicit --no-copy-data flag, or run it in an isolated environment (clean browser profile or VM) to avoid leaking sensitive profile data. Additional recommendations: inspect the GitHub repository/release assets referenced in the SKILL.md, verify the binary checksum if available, and prefer installing only after confirming the upstream source. If you plan to let an AI agent invoke this autonomously, consider restricting that agent's ability to request operations that would trigger profile copying or downloads.

CRITICAL: Before doing anything, run browsectl setup to detect installed browsers and auto-download the matching WebDriver binary. Sessions persist to .browsectl/sessions.json across CLI invocations — you do not need to create a new session every time.

WebDriver automation CLI for AI-driven browser control. browsectl provides subcommands for browser session management, tab control, element interaction, screenshots, batch execution, and an interactive REPL.

Installation

npm install -g @yorelog/browsectl
browsectl setup

Skills

Session & Driver Lifecycle

skills/session.md

Session & driver lifecycle management.

Command	Description
setup	Detect browsers and download WebDriver binary
status	Show driver and session status
driver-start	Start the WebDriver server
session-create	Create a new browser session
session-list	List all active sessions
session-use	Switch the default session
session-delete	Delete a session

Browser Commands

skills/browser.md

Browser interaction commands — navigate, click, type, screenshot, scroll, read state, wait.

Command	Description
run --type open	Navigate to a URL
run --type click	Click a DOM element by CSS selector
run --type fill	Type text into an input field character by character
run --type paste	Paste text via clipboard simulation
run --type screenshot	Capture a DOM element to PNG
run --type scroll	Scroll the page or a specific element
run --type title	Get the current page title
run --type last-message-content	Extract the last message block (chat UIs)
run --type wait	Wait for a condition (visible, hidden, URL, title, JS)

Tab Management

skills/tabs.md

Tab management — list, create, switch, and close browser tabs.

Command	Description
tab-list	List all open tabs
tab-create	Open a new tab
tab-switch	Switch to a tab by index, alias, or handle
tab-close	Close a tab

Batch Execution

skills/batch.md

Batch execution — run single commands, sequential batches from JSON files, and parallel groups.

Command	Description
run	Execute a single WebDriver command
batch	Run a sequence of commands from a JSON file

Selector Syntax

skills/selectors.md

CSS selectors with ::text(/regex/flags) extension for filtering elements by text content.

Interactive REPL

skills/repl.md

Interactive REPL — live command entry, tab-completion, persistent history.

Command	Description
repl	Start the interactive REPL

Global CLI Flags

Flag	Default	Description
--browser	chrome	Browser to automate: chrome or edge
--server	http://127.0.0.1:9515	WebDriver server URL
--chromedriver	(auto-detected)	Path to WebDriver binary (chromedriver / msedgedriver)
--chrome-binary	(auto-detected)	Path to browser binary
--user-data-dir	~/.browsectl/<browser>-profile	Browser user-data directory
--profile-directory	Default	Browser profile directory name
--headless	false	Run browser in headless mode
--viewport	1024,768	Viewport size as width,height
--session	(default session)	Session ID to operate on

Platform Support

OS	x64	arm64
macOS	✅	✅
Linux	✅	✅
Windows	✅	✅