Skip to content

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.go
index 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.md
index 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 Sessions
For 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.json
similarity index 100%
rename from schema/config.json
rename to internal/schema/config.json
diff --git a/schema/schema.go b/internal/schema/schema.go
similarity index 100%
rename from schema/schema.go
rename to internal/schema/schema.go
diff --git a/schema/schema_test.go b/internal/schema/schema_test.go
similarity index 100%
rename from schema/schema_test.go
rename to internal/schema/schema_test.go
diff --git a/skills/pinchtab/TRUST.md b/skills/pinchtab/TRUST.md
index 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 & Verification
Every release includes **checksums** alongside binaries: