Headful Browser (VNC)

Headful Chromium with VNC/noVNC operator UI and Chrome CDP exports (cookies, screenshots, outerHTML).

Security Scan

The skill's code and runtime instructions match a plausible headful Chromium + VNC operator workflow; nothing in the package suggests covert exfiltration or unrelated credential access, but you should verify origin and be careful with VNC exposure and any optional auto-install steps.

Purpose & Capability

The name/description (headful Chromium with VNC and CDP exports) align with the included scripts and Node exporter. The scripts implement VNC session start/stop, Chrome launch with remote-debugging, and Playwright-based export of HTML/screenshot/cookies — all coherent with the stated purpose.

Instruction Scope

Runtime instructions and scripts read a skill-local .env and use environment variables such as VNC_PASSFILE, REMOTE_DEBUG_PORT, PROXY_URL, OUT_DIR and CHROME_USER_DATA_DIR — these are appropriate for the task. The installer can run package-manager commands, but only when explicitly confirmed. The scripts do include a global pkill fallback gated by an explicit ALLOW_CHROME_FORCE_RESTART flag and --force; this is dangerous if enabled but documented.

Install Mechanism

This is instruction/script-only (no install spec). Provided Dockerfile and setup guidance use standard public sources (apt, nodesource, Google Chrome direct URL). The installer prints commands and requires confirmation before privileged operations; no opaque third‑party binary downloads or URL shorteners are used.

Credentials

Requested env vars (VNC_PASSFILE, REMOTE_DEBUG_PORT, PROXY_URL, OUT_DIR, ALLOW_CHROME_FORCE_RESTART, CHROME_USER_DATA_DIR, VNC_IMPLEMENTATION) are reasonable for managing VNC/Chrome sessions and artifact output. No unrelated secrets are requested. There is an inconsistency in the provided metadata: the repository SKILL.md and skill.json declare required_env, but the registry summary at the top of your report showed 'Required env vars: none' — verify registry metadata and the skill-local .env before use.

Persistence & Privilege

The skill is not forced-always, does not request permanent elevated presence, and does not modify other skills. It documents optional systemd/service templates (deployment requires sudo and explicit consent). Autonomous invocation is allowed by default (normal) but not combined with other red flags here.

Assessment

This package appears to implement exactly what it claims: a server-side headful Chromium + VNC environment with CDP-based exports. Before installing or running it: (1) verify the skill origin (skill.json references a GitHub URL but the registry metadata you were shown said source/homepage unknown — confirm the upstream repository and publisher trustworthiness); (2) inspect and create a skill-local .env (chmod 600) so you control paths and flags (VNC_PASSFILE, OUT_DIR, CHROME_USER_DATA_DIR, REMOTE_DEBUG_PORT); (3) do not expose VNC/noVNC to the public Internet — use SSH tunnels or bind to localhost/token gating as documented; (4) be cautious with the installer auto-install path (it will suggest apt/curl commands that download packages — run them only on trusted hosts and review commands like nodesource or Google Chrome deb downloads); (5) avoid enabling ALLOW_CHROME_FORCE_RESTART unless you accept the possibility of global chrome pkill behavior; (6) run the included smoke test in a sandboxed environment (container) first. If you want higher assurance, confirm the upstream Git commit history and that the published package matches the upstream repo.

Overview

headful-browser-vnc provides a controlled, auditable, headful Chromium browsing environment on a server for cases where full browser rendering and occasional human interaction are required. It combines Xvfb, a window manager, and x11vnc (optional noVNC) to present the server-side browser UI to an operator, while offering programmatic integration points (Chrome Remote Debugging / CDP) for automated capture of cookies, rendered HTML, and screenshots.

Primary objective

• Enable reliable, repeatable automation workflows that require the ability to escalate to a human operator for tasks that cannot be solved purely by automation (CAPTCHA solving, challenge pages, multi-factor authentication, manual login flows). The skill's intent is to: (1) run a headful Chrome instance in an isolated profile; (2) expose a secure operator-visible UI to the server browser (VNC/noVNC) so a human can intervene; (3) preserve and export the resulting browser session artifacts (cookies, outerHTML, screenshots) back into automated pipelines for continued processing.

Key capabilities

• Headful browser execution: launch Google Chrome / Chromium with an isolated user data directory and configurable flags (proxy, remote-debugging-port, extra args) on a server X display provided by Xvfb.
• Operator UI: present the running browser to an operator via x11vnc (or optional noVNC web proxy). Operators can connect over SSH-forwarded ports or noVNC with token gating to perform manual actions (solve CAPTCHAs, authenticate), then signal the system to capture artifacts.
• Programmatic capture: export rendered outerHTML, full-page screenshots, and cookies using Chrome CDP (Playwright/Puppeteer compatible). Exports are intended for downstream automated analysis or storage.
• Safe restart and recovery: helpers to restart Chrome when flags change, with explicit user confirmation required for any action that may terminate existing browser instances.
• Artifact hygiene: captured artifacts are written to an artifacts directory with restrictive file permissions. The skill logs actions and writes diagnostic artifacts to facilitate debugging and comparison-based analysis.

Security, privacy, and operational notes

• VNC security: the skill creates per-session passfiles (rfbauth) when possible; noVNC should be bound to loopback or token-gated. Do not expose VNC/noVNC endpoints to the public internet without additional access controls. Store passfiles with mode 600.
• Sensitive artifacts: cookies and rendered page artifacts are sensitive. They are stored under the skill's out/ directory with restrictive permissions; users are responsible for secure storage and timely cleanup.
• Privileged operations: installing system packages and enabling systemd units require sudo and explicit user consent. The scripts will not perform privileged actions automatically unless the operator explicitly enables the auto-install path (see below).

Supported VNC implementations

The skill supports multiple VNC backends; behavior is controlled via the skill-local .env file (VNC_IMPLEMENTATION): auto (default), tigervnc, tightvnc, realvnc. When possible the skill prefers non-interactive rfbauth generation via vncpasswd; when unavailable it prompts the operator and documents fallback behavior.

Runtime files & usage

This section documents each file included in the skill release branch, its purpose, usage examples, preconditions, and relations to other files. All script examples assume you run them from the workspace root unless noted.

skills/headful-browser-vnc/scripts/setup.sh

• Purpose: interactive, documented installer and validator for the skill's runtime dependencies (Xvfb, x11vnc, Chrome/Chromium, node, tooling). Primarily guidance-only: prints distro-aware commands; only runs package-manager operations when explicitly allowed.
• Usage:

  ./skills/headful-browser-vnc/scripts/setup.sh [--check-only] [--auto-install] [--yes] [--set-password]
  

• Preconditions: network access to package repositories; sudo available for host installs (not required inside containers when running as root). When running inside a container, auto-installs require either root or CONTAINER_AUTO_OK=true.
• Relations: updates/creates skills/headful-browser-vnc/.env; generates VNC passfiles via vncpasswd when available; consults templates/ for service unit guidance.

skills/headful-browser-vnc/scripts/start_vnc.sh

• Purpose: start an Xvfb display, optional window manager, and x11vnc to expose the display. Emits a one-line summary with the VNC port and display id.
• Usage:

  skills/headful-browser-vnc/scripts/start_vnc.sh <session_id> [--display=:99] [--resolution=1366x768] [--port=5901]
  

• Preconditions: Xvfb and x11vnc installed (or available in Docker image), VNC_PASSFILE permission 600 if provided.
• Relations: start_vnc.sh creates the DISPLAY and user-data directory used by start_chrome_debug.sh; stop_vnc.sh undoes the session.

skills/headful-browser-vnc/scripts/stop_vnc.sh

• Purpose: stop and clean up a running VNC/Xvfb session previously started by start_vnc.sh.
• Usage:

  skills/headful-browser-vnc/scripts/stop_vnc.sh <session_id> [--display=:99]
  

• Preconditions: session id matches an active session created by start_vnc.sh.

skills/headful-browser-vnc/scripts/start_chrome_debug.sh

• Purpose: launch a headful Chrome/Chromium instance attached to a session DISPLAY with a dedicated user-data dir and remote-debugging port for CDP access.
• Usage:

  skills/headful-browser-vnc/scripts/start_chrome_debug.sh <session_id> [--proxy=http://...] [--remote-debug-port=9222]
  

• Preconditions: Chrome/Chromium binary available and readable; DISPLAY is set (start_vnc.sh must have run); user-data directory writable by the process owner.
• Relations: other scripts (export_page.sh, export_cookies.sh) connect to the remote-debugging port started by this script.

skills/headful-browser-vnc/scripts/export_page.sh

• Purpose: instruct Chrome to load a URL and export rendered outerHTML and a full-page screenshot for later analysis.
• Usage:

  skills/headful-browser-vnc/scripts/export_page.sh <session_id> <url> [--devtools-port=9222]
  

• Preconditions: headful Chrome with remote-debugging port active and reachable (start_chrome_debug.sh).

skills/headful-browser-vnc/scripts/export_cookies.sh

• Purpose: export cookies from a running Chrome instance via the Chrome DevTools Protocol.
• Usage:

  skills/headful-browser-vnc/scripts/export_cookies.sh <session_id> [--devtools-port=9222]
  

General Notes on Export Helpers

• Note: these export helpers (export_page.sh, export_cookies.sh) are designed to be idempotent and safe to run after manual operator interventions. They place artifacts into out/<session_id>/ with restrictive permissions.

Combined Script Usage Flow

• Flow: start_vnc.sh <id> → start_chrome_debug.sh <id> → operator attaches via VNC → operator interacts → export_page.sh / export_cookies.sh → stop_vnc.sh <id>

skills/headful-browser-vnc/docker/

• Purpose: reference docker/ directory containing entrypoint and docker-compose.yml plus an embedded Dockerfile in README.docker.md for reproducible builds. ClawHub does not accept Dockerfile uploads, so the Dockerfile content has been included in skills/headful-browser-vnc/README.docker.md as a code block.
• Recommendation: For reproducibility and security, build dependencies into the image (Dockerfile) rather than relying on runtime package installs inside a running container. If you must allow in-container auto-installs, see setup.sh gating (CONTAINER_AUTO_OK and container_auto_allowed()).

skills/headful-browser-vnc/templates/

• Purpose: Jinja2-style templates for systemd unit files (x11vnc/noVNC). Use them as references; deploying them on a host requires sudo and careful service permissions.

skills/headful-browser-vnc/tests/smoke_test.sh

• Purpose: non-privileged smoke test exercising start → launch → export → cleanup sequence to validate runtime behavior in CI-friendly environments.
• Usage:

  ./skills/headful-browser-vnc/tests/smoke_test.sh
  

Configuration (.env)

Place a skill-local skills/headful-browser-vnc/.env (chmod 600) to persist runtime defaults. Key fields:

• VNC_PASSFILE: path to passfile (e.g. /home/user/.vnc/passwd or ./vnc_passwd)
• VNC_PORT: optional explicit TCP port to bind x11vnc (if omitted the script will report the actual port in use)
• VNC_IMPLEMENTATION: auto|tigervnc|tightvnc|realvnc
• VNC_DISPLAY: X display (default :99)
• VNC_RESOLUTION: screen resolution (default 1366x768)
• REMOTE_DEBUG_PORT: Chrome remote debugging port (default 9222)
• PROXY_URL / HTTP_PROXY / HTTPS_PROXY: optional proxy settings

Install and dependencies

• setup.sh contains interactive guidance and optional prompts for installing Chrome, node, Playwright, and VNC helper tools. The installer will not run sudo operations without explicit consent.
• Programmatic export paths prefer Node + Playwright; a Python fallback is available but optional.

Auto-install behaviour and safety (enforced)

The installer supports an optional auto-install path but it is gated behind explicit confirmations and container-aware checks:

• CLI flag: --auto-install (sets AUTO_INSTALL=true for the run).
• Runtime confirmation: when the installer proposes a distro-specific command it will first ask for a y/N confirmation, then print the exact command and require the operator to type the full word yes (not y). Only if both confirmations are provided will the installer execute the command.
• Container extra gate: inside a detected container (/.dockerenv or /proc/1/cgroup contains docker/containerd/kubepods), automatic package-manager operations will only run if the process is root (id -u == 0) or if CONTAINER_AUTO_OK=true.

Default behaviour remains conservative: without --auto-install the installer only prints distro-appropriate commands and will not run package-manager commands automatically.

Templates and integration

• templates/x11vnc.service.j2 — systemd unit template for persistent sessions (requires sudo to install)
• templates/novnc.service.j2 — noVNC service template

Integration guidance for maintainers

• Use Chrome CDP (devtools) for deterministic exports. Prefer attaching to an already-running headful Chrome instance rather than launching short-lived headless instances when reproducing a previously observed UI state.
• Persist session artifacts and index them (timestamp, URL, session id, VNC port, devtools port) so comparison automation can operate on operator-validated examples.
• When embedding into automated pipelines, clearly separate automated actions from operator interventions; require explicit human confirmation for destructive actions (Chrome restarts, service reconfiguration).

Testing

A non-privileged smoke test is provided at skills/headful-browser-vnc/tests/smoke_test.sh. It performs a basic start → launch → export → cleanup sequence and is useful for CI verification.

Support and contribution

The skill is maintained in this workspace. When contributing changes, follow the repository conventions: create backups before modifying scripts, run bash -n for syntax validation, and preserve audit logs and artifacts.

License

Include an appropriate LICENSE file when publishing (e.g., MIT). Update author/maintainer fields in SKILL.md prior to external publication.

Example: safe auto-install run

To allow the installer to perform distro package manager actions automatically, run with explicit --auto-install and be prepared to type the full confirmation word. Example:

AUTO_INSTALL=true ./skills/headful-browser-vnc/scripts/setup.sh --auto-install

The script will: (1) detect your distro and print the exact command it plans to run; (2) ask for a normal y/N confirmation; (3) print the command and require you to type the exact word yes to proceed; (4) only then execute the command.

If you prefer to always review and run commands manually, omit --auto-install and the script will only print distro-appropriate commands for you to run yourself.

---

Short example run transcript (what prompts look like)

Below is a short, representative transcript demonstrating the installer flow when a few components are missing and the operator chooses the manual path (no auto-install). Prompts shown are exact prompts produced by the current setup.sh.

$ ./skills/headful-browser-vnc/scripts/setup.sh
Platform install hints (guidance-only — these commands will NOT be run automatically):

Debian / Ubuntu (apt):
  sudo apt-get update
  sudo apt-get install -y --no-install-recommends \
    xvfb x11vnc fluxbox x11-utils tigervnc-standalone-server tightvnc-tools \
    fonts-noto-cjk fontconfig chromium-browser google-chrome-stable \
    nodejs npm python3-pip

---
Missing requirements: Xvfb x11vnc chrome node VNC_PASSFILE .env
--- Handling missing: Xvfb ---
Install Xvfb? (y/N) n
Skip. Manual: sudo apt-get install xvfb
Press Enter when done...
--- Handling missing: x11vnc ---
Install x11vnc? (y/N) y
VNC Port [5901]: 5901
Enter VNC passfile path [/home/user/vnc_passwd]: /home/user/.vnc/passwd
Tool 'vncpasswd' found. Preparing automated generation...
Enter VNC password (hidden): ********
Confirm password: ********
SUCCESS: rfbauth generated at /home/user/.vnc/passwd
--- Handling missing: chrome ---
Select Chrome version:
1) Google Chrome (Recommended)
2) Chromium (Snap)
3) Skip
Choice [1-3] (default 1): 3
Skipped.
--- Handling missing: node ---
Install Node.js v22+ using suggested command? (y/N) n
Skipped automatic install. Please run the printed command manually.
--- Handling missing: .env ---
Create template .env? (y/N) y
Created skills/headful-browser-vnc/.env