High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: clarify security defaults for ClawScan findings, move schema to internal
Mariod4a2263bafd4
diff --git a/cmd/pinchtab/cmd_config.go b/cmd/pinchtab/cmd_config.goindex 481de323..1c8b5913 100644--- a/cmd/pinchtab/cmd_config.go+++ b/cmd/pinchtab/cmd_config.go@@ -10,8 +10,8 @@ import ("github.com/pinchtab/pinchtab/internal/cli""github.com/pinchtab/pinchtab/internal/config""github.com/pinchtab/pinchtab/internal/config/workflow"+ configschema "github.com/pinchtab/pinchtab/internal/schema""github.com/pinchtab/pinchtab/internal/server"- configschema "github.com/pinchtab/pinchtab/schema""github.com/spf13/cobra")diff --git a/docs/guides/security.md b/docs/guides/security.mdindex fae9a79c..c356f762 100644--- a/docs/guides/security.md+++ b/docs/guides/security.md@@ -21,6 +21,8 @@ The default security posture is:- `security.allowDownload = false`- `security.allowCookies = false`- `security.allowUpload = false`+- `autoSolver.enabled = false`+- `instanceDefaults.stealthLevel = "light"` (minimal fingerprint normalization only; anti-bot bypass requires explicit opt-in to `medium` or `full`)- `security.attach.enabled = false`- `security.attach.allowHosts = ["127.0.0.1", "localhost", "::1"]`- `security.attach.allowSchemes = ["ws", "wss"]`@@ -346,6 +348,29 @@ For a secure local setup:If you intentionally expose PinchTab beyond localhost, treat the token as mandatory and keep the sensitive endpoint families disabled unless you have a specific reason to enable them. For anything more exposed than a single-machine local setup, assume you are operating an advanced deployment and review each security control explicitly.+## Authenticated Browser Sessions++When agents reuse browser sessions that a human has authenticated (logged-in profiles), follow these practices:++- Use a **dedicated low-privilege profile** — not the user's personal browsing profile+- **Confirm with the user** before performing account-changing actions (password changes, payment, deletion, permissions) in a reused session+- Restrict navigation to the sites needed for the task via `security.allowedDomains` or instance-scoped `securityPolicy.allowedDomains`++These are operational guidelines enforced at the agent/skill layer, not API-level gates. The profile system (`POST /profiles`) supports metadata fields (`name`, `description`, `useWhen`) to help agents select the right profile for the task.++## Daemon Lifecycle++The background daemon is a convenience for persistent local browser control. It runs continuously once installed (`KeepAlive` on macOS, `Restart=always` on Linux).++When browser automation is no longer needed, disable it:++- `pinchtab daemon stop` — stop the service without removing it+- `pinchtab daemon uninstall` — stop, disable, and remove the service file++For short-lived or one-off usage, prefer `pinchtab server` (foreground process, exits when the terminal closes) over the daemon.++Agent session credentials auto-expire after **30 minutes of idle** (`sessions.agent.idleTimeoutSec: 1800`) and have a **24-hour max lifetime** (`sessions.agent.maxLifetimeSec: 86400`) by default.+## Agent SessionsFor automated agents, use **agent sessions** instead of sharing the server bearer token. Each agent gets a dedicated session token (`PINCHTAB_SESSION`) that:diff --git a/schema/config.json b/internal/schema/config.jsonsimilarity index 100%rename from schema/config.jsonrename to internal/schema/config.jsondiff --git a/schema/schema.go b/internal/schema/schema.gosimilarity index 100%rename from schema/schema.gorename to internal/schema/schema.godiff --git a/schema/schema_test.go b/internal/schema/schema_test.gosimilarity index 100%rename from schema/schema_test.gorename to internal/schema/schema_test.godiff --git a/skills/pinchtab/TRUST.md b/skills/pinchtab/TRUST.mdindex 700c7da9..5de29009 100644--- a/skills/pinchtab/TRUST.md+++ b/skills/pinchtab/TRUST.md@@ -7,7 +7,7 @@- Launches a Chrome browser (local, under your control)- Exposes navigation, clicking, typing, and page inspection via HTTP API- Extracts the page's accessibility tree (for AI agents)-- Runs screenshots, PDFs, and JavaScript evaluation+- Runs screenshots and PDFs; JavaScript evaluation is available but **disabled by default** (`security.allowEvaluate = false`)High-risk operations such as JavaScript evaluation, local-file upload, file downloads, cookie access, and network export should be treated as explicit opt-in actions for the current task, not the default workflow. These are gated by security policy and disabled by default.@@ -31,12 +31,33 @@ High-impact capabilities are **disabled by default** and require explicit config| File downloads | **Disabled** | `security.allowDownloads` || File uploads | **Disabled** | `security.allowUploads` || Network interception | **Disabled** | `security.allowNetworkIntercept` |-| Challenge solving / stealth | **Disabled** | Requires explicit `/solve` call with user approval |+| Challenge solving (autoSolver) | **Disabled** | `autoSolver.enabled`; requires explicit opt-in per deployment |+| Stealth level | **Light** (minimal) | `instanceDefaults.stealthLevel`; `light` applies only basic fingerprint normalization — anti-bot bypass requires `medium` or `full`, which must be set explicitly || Navigation domains | **Local-only allowlist** | `security.allowedDomains` (restrict or expand deliberately) || Cookie access | **Disabled** | `security.allowCookies`; use only when task requires it; do not log or expose session tokens |Agents reusing authenticated browser sessions should use dedicated low-privilege profiles and confirm with the user before performing account-changing actions.+## Network Export Defaults++Network exports capture request/response metadata but apply conservative defaults:++- **Response bodies are excluded** unless explicitly requested with `body=true`+- **Sensitive headers are redacted by default** (`redact=true`) — `Cookie`, `Set-Cookie`, `Authorization`, `Proxy-Authorization`, `X-API-Key`, and `X-CSRF-Token` are replaced with `[REDACTED]`+- Exported files are written with **0600 permissions** (owner-only access)+- Writes are atomic (temp file + rename) with path traversal prevention++## Daemon Lifecycle++The background daemon (`pinchtab daemon install`) is a convenience for persistent local use, not a requirement. When browser automation is no longer needed:++- `pinchtab daemon stop` — stop the daemon without uninstalling+- `pinchtab daemon uninstall` — disable and remove the service file entirely++As an alternative to the daemon, run `pinchtab server` in the foreground — it stops when the terminal closes.++Agent sessions expire after **30 minutes of idle** by default (`sessions.agent.idleTimeoutSec`), and tabs can auto-close via `tabPolicy.lifecycle: "close_idle"`.+## Builds & VerificationEvery release includes **checksums** alongside binaries: