fix: tighten instance API, runtime safety caps, and security posture docs (pinchtab#368)

* fix: tighten instance API usage and add runtime safety caps

* docs: clarify non-default security-reducing configs and presets

---------

Co-authored-by: Luigi Agosti <luigi@tengio.com>

Author: luigiagent

README.md

@@ -43,6 +43,9 @@ PinchTab is designed first for local, single-user control on a machine you manag
 
 If you run PinchTab on a different machine, do it only when you understand the security model. Keep it on a private or otherwise closed network, avoid exposing it directly to the public internet, and keep high-risk endpoint families disabled unless you explicitly need them. If you do enable them, lock them down so only the systems that need them can reach them.
 
+> [!WARNING]
+> The dashboard, HTTP API, MCP server, and remote CLI integrations are privileged operator control surfaces. They are not designed for untrusted users, multi-tenant exposure, or direct public-internet access. If you are unsure how to secure a non-local deployment, review [docs/guides/security.md](docs/guides/security.md) and use the private security contact path in [SECURITY.md](SECURITY.md) before exposing the service.
+
 
 If you prefer not to run a daemon, or if you're on Windows, you can instead run:
 
@@ -248,10 +251,15 @@ pinchtab text
 
 Or use the HTTP API directly:
 ```bash
-# Create an instance (returns instance id)
-INST=$(curl -s -X POST http://localhost:9867/instances/launch \
+# Create a profile first (returns profile id)
+PROF=$(curl -s -X POST http://localhost:9867/profiles \
+  -H "Content-Type: application/json" \
+  -d '{"name":"work"}' | jq -r '.id')
+
+# Start an instance for that profile (returns instance id)
+INST=$(curl -s -X POST http://localhost:9867/instances/start \
   -H "Content-Type: application/json" \
-  -d '{"name":"work","mode":"headless"}' | jq -r '.id')
+  -d "{\"profileId\":\"$PROF\",\"mode\":\"headless\"}" | jq -r '.id')
 
 # Open a tab in that instance
 TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \

cmd/pinchtab/cmd_security.go

@@ -32,7 +32,11 @@ func init() {
 	})
 	securityCmd.AddCommand(&cobra.Command{
 		Use:   "down",
-		Short: "Lower guards while keeping loopback bind and API auth enabled",
+		Short: "Apply a documented security-reducing preset while keeping loopback bind and API auth enabled",
+		Long: "Applies the guards-down preset for local operator workflows. " +
+			"This is a documented, non-default, security-reducing configuration change: " +
+			"sensitive endpoint families and attach are enabled, while IDPI protections are disabled. " +
+			"Loopback bind and API authentication remain enabled, and attach host allowlisting stays local-only until you widen it explicitly.",
 		Run: func(cmd *cobra.Command, args []string) {
 			handleSecurityDownCommand()
 		},
@@ -181,10 +185,17 @@ func promptSecurityEdit(cfg *config.RuntimeConfig, posture cli.SecurityPosture,
 func editSecurityCheck(cfg *config.RuntimeConfig, check cli.SecurityPostureCheck) (*config.RuntimeConfig, bool, error) {
 	switch check.ID {
 	case "bind_loopback":
-		value, err := promptInput("Set server.bind:", cfg.Bind)
+		value, err := promptInput("Set server.bind (127.0.0.1 keeps it local):", cfg.Bind)
 		if err != nil {
 			return nil, false, err
 		}
+		if !isLoopbackBindValue(value) {
+			fmt.Println()
+			fmt.Println("  " + cli.StyleStdout(cli.WarningStyle, "Warning: server.bind is non-loopback"))
+			fmt.Println("      " + cli.StyleStdout(cli.MutedStyle, "effect") + ": " + cli.StyleStdout(cli.ValueStyle, "may expose the server beyond the local machine unless an outer network boundary still restricts access"))
+			fmt.Println("      " + cli.StyleStdout(cli.MutedStyle, "scope") + ": " + cli.StyleStdout(cli.ValueStyle, "documented, non-default, security-reducing override"))
+			fmt.Println("      " + cli.StyleStdout(cli.MutedStyle, "hint") + ": " + cli.StyleStdout(cli.ValueStyle, "keep a token set and review reverse proxy or port-publishing behavior explicitly"))
+		}
 		return workflow.UpdateValue("server.bind", value)
 	case "api_auth_enabled":
 		picked, err := promptSelect("API authentication", []menuOption{
@@ -230,10 +241,17 @@ func editSecurityCheck(cfg *config.RuntimeConfig, check cli.SecurityPostureCheck
 		}
 		return workflow.UpdateValue("security.attach.enabled", fmt.Sprintf("%t", picked == "enable"))
 	case "attach_local_only":
-		value, err := promptInput("Set security.attach.allowHosts (comma-separated):", strings.Join(cfg.AttachAllowHosts, ","))
+		value, err := promptInput("Set security.attach.allowHosts (comma-separated; '*' disables host allowlisting):", strings.Join(cfg.AttachAllowHosts, ","))
 		if err != nil {
 			return nil, false, err
 		}
+		if attachHostsContainsWildcard(value) {
+			fmt.Println()
+			fmt.Println("  " + cli.StyleStdout(cli.WarningStyle, "Warning: security.attach.allowHosts includes '*'"))
+			fmt.Println("      " + cli.StyleStdout(cli.MutedStyle, "effect") + ": " + cli.StyleStdout(cli.ValueStyle, "disables host allowlisting and allows any reachable attach host with an allowed scheme"))
+			fmt.Println("      " + cli.StyleStdout(cli.MutedStyle, "scope") + ": " + cli.StyleStdout(cli.ValueStyle, "documented, non-default, security-reducing override"))
+			fmt.Println("      " + cli.StyleStdout(cli.MutedStyle, "hint") + ": " + cli.StyleStdout(cli.ValueStyle, "use only on isolated, operator-controlled networks"))
+		}
 		return workflow.UpdateValue("security.attach.allowHosts", value)
 	case "idpi_whitelist_scoped":
 		value, err := promptInput("Set security.idpi.allowedDomains (comma-separated):", strings.Join(cfg.IDPI.AllowedDomains, ","))
@@ -267,6 +285,24 @@ func editSecurityCheck(cfg *config.RuntimeConfig, check cli.SecurityPostureCheck
 	return cfg, false, nil
 }
 
+func attachHostsContainsWildcard(value string) bool {
+	for _, part := range strings.Split(value, ",") {
+		if strings.TrimSpace(part) == "*" {
+			return true
+		}
+	}
+	return false
+}
+
+func isLoopbackBindValue(value string) bool {
+	switch strings.TrimSpace(strings.ToLower(value)) {
+	case "", "127.0.0.1", "localhost", "::1":
+		return true
+	default:
+		return false
+	}
+}
+
 func applySecurityUp() (*config.RuntimeConfig, bool, error) {
 	configPath, changed, err := workflow.RestoreSecurityDefaults()
 	if err != nil {
@@ -291,7 +327,10 @@ func applySecurityDown() (*config.RuntimeConfig, bool, error) {
 		return nextCfg, false, nil
 	}
 	fmt.Println(cli.StyleStdout(cli.WarningStyle, fmt.Sprintf("Guards down preset applied in %s", configPath)))
-	fmt.Println(cli.StyleStdout(cli.MutedStyle, "Loopback bind and API auth remain enabled; sensitive endpoints and attach are enabled, IDPI is disabled."))
+	fmt.Println(cli.StyleStdout(cli.WarningStyle, "This is a documented, non-default, security-reducing preset."))
+	fmt.Println(cli.StyleStdout(cli.MutedStyle, "Loopback bind and API auth remain enabled; sensitive endpoints and attach are enabled, and IDPI protections are disabled."))
+	fmt.Println(cli.StyleStdout(cli.MutedStyle, "Attach host allowlisting remains local-only. Widening allowHosts or enabling bridge schemes later is an additional explicit weakening."))
+	fmt.Println(cli.StyleStdout(cli.MutedStyle, "Changing server.bind away from 127.0.0.1 later is also an additional explicit weakening unless another network boundary still constrains access."))
 	return nextCfg, true, nil
 }
 

cmd/pinchtab/cmd_security_test.go

@@ -3,6 +3,7 @@ package main
 import (
 	"io"
 	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -41,6 +42,45 @@ func TestHandleSecurityCommandDefaultConfigSkipsEmptySections(t *testing.T) {
 	}
 }
 
+func TestApplySecurityDownPrintsExplicitRiskFraming(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "pinchtab", "config.json")
+	t.Setenv("PINCHTAB_CONFIG", configPath)
+
+	fc := config.DefaultFileConfig()
+	fc.Server.Token = "guarded-token"
+	if err := os.MkdirAll(filepath.Dir(configPath), 0o755); err != nil {
+		t.Fatalf("MkdirAll() error = %v", err)
+	}
+	if err := config.SaveFileConfig(&fc, configPath); err != nil {
+		t.Fatalf("SaveFileConfig() error = %v", err)
+	}
+
+	output := captureStdout(t, func() {
+		cfg, changed, err := applySecurityDown()
+		if err != nil {
+			t.Fatalf("applySecurityDown() error = %v", err)
+		}
+		if !changed {
+			t.Fatal("expected applySecurityDown() to change config")
+		}
+		if cfg == nil {
+			t.Fatal("expected runtime config result")
+		}
+	})
+
+	for _, needle := range []string{
+		"Guards down preset applied",
+		"This is a documented, non-default, security-reducing preset.",
+		"sensitive endpoints and attach are enabled, and IDPI protections are disabled.",
+		"Attach host allowlisting remains local-only.",
+		"Changing server.bind away from 127.0.0.1 later is also an additional explicit weakening",
+	} {
+		if !strings.Contains(output, needle) {
+			t.Fatalf("expected output to contain %q\n%s", needle, output)
+		}
+	}
+}
+
 func captureStdout(t *testing.T, fn func()) string {
 	t.Helper()
 

cmd/pinchtab/root.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/pinchtab/pinchtab/internal/cli"
 	"github.com/pinchtab/pinchtab/internal/config"
+	"github.com/pinchtab/pinchtab/internal/safelog"
 	"github.com/pinchtab/pinchtab/internal/server"
 	"github.com/spf13/cobra"
 )
@@ -95,6 +96,7 @@ func menuListenStatus(cfg *config.RuntimeConfig) string {
 }
 
 func Execute() {
+	safelog.InstallDefault()
 	if err := rootCmd.Execute(); err != nil {
 		fmt.Fprintln(os.Stderr, err)
 		os.Exit(1)

dashboard/src/pages/SettingsPage.tsx

@@ -267,6 +267,15 @@ export default function SettingsPage() {
     : [];
   const idpiWildcard = idpiAllowedDomains.includes("*");
   const idpiDomainsConfigured = idpiAllowedDomains.length > 0 && !idpiWildcard;
+  const attachAllowedHosts = backendConfig
+    ? backendConfig.security.attach.allowHosts
+    : [];
+  const attachWildcard = attachAllowedHosts.includes("*");
+  const nonLoopbackBind = backendConfig
+    ? !["127.0.0.1", "localhost", "::1", ""].includes(
+        backendConfig.server.bind.trim().toLowerCase(),
+      )
+    : false;
 
   const updateBackendSection = <K extends keyof BackendConfig>(
     section: K,
@@ -1273,15 +1282,35 @@ export default function SettingsPage() {
                   </SettingRow>
                   <SettingRow
                     label="Bind address"
-                    description="Network interface the dashboard process binds to."
+                    description="Network interface the dashboard process binds to. Keeping 127.0.0.1 or localhost limits direct reachability to the local machine."
                   >
-                    <input
-                      value={backendConfig.server.bind}
-                      onChange={(e) =>
-                        updateBackendSection("server", { bind: e.target.value })
-                      }
-                      className={fieldClass}
-                    />
+                    <div className="space-y-2">
+                      <input
+                        value={backendConfig.server.bind}
+                        onChange={(e) =>
+                          updateBackendSection("server", {
+                            bind: e.target.value,
+                          })
+                        }
+                        className={fieldClass}
+                      />
+                      {nonLoopbackBind ? (
+                        <div className="rounded-sm border border-destructive/35 bg-destructive/10 px-3 py-2 text-xs leading-5 text-destructive/80">
+                          A non-loopback bind is a documented, non-default,
+                          security-reducing configuration change. It may expose
+                          the server beyond the local machine unless another
+                          network boundary still restricts access. Keep a token
+                          set and review proxy or port-publishing behavior
+                          explicitly.
+                        </div>
+                      ) : (
+                        <div className="rounded-sm border border-warning/25 bg-warning/10 px-3 py-2 text-xs leading-5 text-warning">
+                          Loopback bind keeps direct server reachability local.
+                          Moving to <code>0.0.0.0</code> or another non-local
+                          address widens the trust boundary.
+                        </div>
+                      )}
+                    </div>
                   </SettingRow>
                   <SettingRow
                     label="API token"
@@ -1363,7 +1392,9 @@ export default function SettingsPage() {
                   </SettingRow>
                   <SettingRow
                     label="Allowed attach hosts"
-                    description="Comma-separated host allowlist for attach requests. Only include hosts you control and trust."
+                    description={
+                      'Comma-separated host allowlist for attach requests. Only include hosts you control and trust. Using "*" disables host allowlisting.'
+                    }
                   >
                     <div className="space-y-2">
                       <input
@@ -1380,11 +1411,22 @@ export default function SettingsPage() {
                         }
                         className={fieldClass}
                       />
-                      <div className="rounded-sm border border-warning/25 bg-warning/10 px-3 py-2 text-xs leading-5 text-warning">
-                        Hosts in this allowlist may be used for remote attach
-                        requests. Broad or untrusted entries can expose external
-                        Chrome sessions and browser contents.
-                      </div>
+                      {attachWildcard ? (
+                        <div className="rounded-sm border border-destructive/35 bg-destructive/10 px-3 py-2 text-xs leading-5 text-destructive/80">
+                          <code>allowHosts: ["*"]</code> is a documented,
+                          non-default, security-reducing override. It disables
+                          host allowlisting entirely and allows remote attach
+                          requests to any reachable host with an allowed scheme.
+                          Use it only on isolated, operator-controlled networks.
+                        </div>
+                      ) : (
+                        <div className="rounded-sm border border-warning/25 bg-warning/10 px-3 py-2 text-xs leading-5 text-warning">
+                          Hosts in this allowlist may be used for remote attach
+                          requests. Broad or untrusted entries expand the trust
+                          boundary and can expose external Chrome sessions and
+                          browser contents.
+                        </div>
+                      )}
                     </div>
                   </SettingRow>
                   <SettingRow

docs/commands.md

@@ -180,7 +180,7 @@ pinchtab config set <path> <val>        # Set one file-config value
 pinchtab config patch <json>            # Merge JSON into the config file
 pinchtab security                       # Interactive security overview
 pinchtab security up                    # Apply stricter defaults
-pinchtab security down                  # Relax defaults
+pinchtab security down                  # Apply documented guards-down preset
 ```
 
 ## Global Flags

docs/dashboard.md

@@ -12,6 +12,9 @@ You can open the dashboard at:
 - `http://localhost:9867`
 - `http://localhost:9867/dashboard`
 
+> [!WARNING]
+> The dashboard is an operator/admin control surface, not a public or multi-user application. Do not expose it to untrusted users. Anyone who can use the dashboard can manage profiles, instances, configuration, and other browser-control capabilities that are enabled on that server.
+
 ---
 
 ## Dashboard overview

docs/endpoints.md

@@ -308,6 +308,8 @@ POST /instances/{id}/tab
 Notes:
 
 - `/instances/start` and `/instances/launch` use `mode`, not `headless`
+- `/instances/launch` is a compatibility alias over `/instances/start`
+- create profiles explicitly with `POST /profiles`; `name` is no longer supported on `/instances/launch`
 - `/profiles/{id}/start` uses `headless`
 - attach routes are gated by `security.attach`
 
@@ -348,6 +350,8 @@ Scheduler routes are only present when `scheduler.enabled` is true.
 
 Some endpoints are intentionally disabled unless the matching config allows them:
 
+These gates are not ordinary feature toggles. Enabling them is a documented, non-default, security-reducing choice that widens the control surface available to callers.
+
 - `/evaluate` and `/tabs/{id}/evaluate` -> `security.allowEvaluate`
 - `/download` and `/tabs/{id}/download` -> `security.allowDownload`
 - `/upload` and `/tabs/{id}/upload` -> `security.allowUpload`

docs/guides/attach-chrome.md

@@ -200,6 +200,8 @@ Recommended rules:
 - set `PINCHTAB_TOKEN` when the server is reachable outside localhost
 - only attach to CDP endpoints you trust
 
+If you set `allowHosts` to `["*"]`, PinchTab accepts any reachable attach host with an allowed scheme. That is a documented, non-default, security-reducing override: it removes host allowlisting entirely and should only be used on isolated, operator-controlled networks.
+
 Also remember:
 
 - Chrome DevTools gives powerful browser control

docs/guides/mcp-agents.md

@@ -2,6 +2,9 @@
 
 This guide walks through setting up PinchTab as an MCP tool server for AI coding assistants and agent frameworks.
 
+> [!WARNING]
+> When you connect an MCP client to PinchTab, that client is exercising the same privileged control plane as the dashboard, API, and remote CLI. Only trusted operators and trusted agent systems should be allowed to use it. If you are unsure whether a non-local or partially exposed deployment is safe, stop and review [Security](security.md) before proceeding.
+
 ## What is MCP?
 
 The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI models to external tools. PinchTab implements an MCP server that exposes 21 browser-control tools — navigation, interaction, screenshot, PDF export, and more — over a simple stdio interface that every major AI client supports.
@@ -152,7 +155,7 @@ security:
 
 Restart PinchTab after changing this setting.
 
-> **Warning:** Enabling evaluate allows the agent (and any page it visits) to run arbitrary JavaScript in the browser. Only enable this on trusted networks with a token set.
+> **Warning:** Enabling evaluate is a documented, non-default, security-reducing configuration change. It allows the agent (and any page it visits) to run arbitrary JavaScript in the browser. Only enable it on trusted networks with a token set.
 
 ## Connecting to a Remote PinchTab