ssh-mcp-pro 1.1.5 → 1.2.3

package/docs/reference/configuration.md

@@ -0,0 +1,72 @@
+# Configuration Reference
+
+The canonical, exhaustive `SSH_MCP_*` table lives in
+[README.md#configuration](../../README.md#configuration) and isn't duplicated here — a
+second copy of a 40+ row table would drift out of sync with the first. This page groups
+that table by concern, for when you know *what kind* of setting you need but not its
+exact name.
+
+## Session and resource limits
+
+`SSH_MCP_MAX_SESSIONS`, `SSH_MCP_SESSION_TTL`, `SSH_MCP_COMMAND_TIMEOUT`,
+`SSH_MCP_MAX_COMMAND_OUTPUT_BYTES`, `SSH_MCP_MAX_STREAM_CHUNKS`, `SSH_MCP_MAX_FILE_SIZE`,
+`SSH_MCP_MAX_FILE_WRITE_BYTES`, `SSH_MCP_MAX_TRANSFER_BYTES`.
+
+## SSH security policy
+
+`SSH_MCP_HOST_KEY_POLICY`, `SSH_MCP_KNOWN_HOSTS_PATH`, `SSH_MCP_ALLOW_ROOT_LOGIN`,
+`SSH_MCP_ALLOWED_CIPHERS`, `SSH_MCP_ALLOW_RAW_SUDO`, `SSH_MCP_ALLOW_DESTRUCTIVE_COMMANDS`,
+`SSH_MCP_ALLOW_DESTRUCTIVE_FS`, `SSH_MCP_ALLOWED_HOSTS`, `SSH_MCP_COMMAND_ALLOW`,
+`SSH_MCP_COMMAND_DENY`, `SSH_MCP_PATH_ALLOW_PREFIXES`, `SSH_MCP_PATH_DENY_PREFIXES`. See
+[docs/how-to/configure-ssh-policy.md](../how-to/configure-ssh-policy.md) for task-based
+guidance and [docs/security/threat-model.md](../security/threat-model.md) for why these
+defaults exist.
+
+## Local transfer and tunnel policy
+
+`SSH_MCP_LOCAL_PATH_ALLOW_PREFIXES`, `SSH_MCP_LOCAL_PATH_DENY_PREFIXES`,
+`SSH_MCP_TUNNEL_ALLOW_BIND_HOSTS`, `SSH_MCP_TUNNEL_DENY_BIND_HOSTS`,
+`SSH_MCP_TUNNEL_ALLOW_REMOTE_HOSTS`, `SSH_MCP_TUNNEL_DENY_REMOTE_HOSTS`,
+`SSH_MCP_TUNNEL_ALLOW_PORTS`, `SSH_MCP_TUNNEL_DENY_PORTS`.
+
+## Policy engine
+
+`SSH_MCP_POLICY_FILE`, `SSH_MCP_POLICY_MODE` — a JSON policy file plus enforce/explain
+mode, for centralizing the settings above instead of many separate environment
+variables. No config-schema version field currently exists for the policy file (see
+[docs/development/api-stability.md](../development/api-stability.md)).
+
+## HTTP transport
+
+`SSH_MCP_HTTP_HOST`, `SSH_MCP_HTTP_PORT`, `SSH_MCP_HTTP_ALLOWED_ORIGINS`,
+`SSH_MCP_HTTP_BEARER_TOKEN_FILE`, `SSH_MCP_ENABLE_LEGACY_SSE`,
+`SSH_MCP_HTTP_MAX_REQUEST_BODY_BYTES`, `SSH_MCP_HTTP_MAX_SESSIONS`,
+`SSH_MCP_HTTP_SESSION_IDLE_TTL_MS`, `SSH_MCP_HTTP_PUBLIC_URL`,
+`SSH_MCP_HTTP_TRUST_PROXY`. See [docs/remote-mcp-hardening.md](../remote-mcp-hardening.md).
+
+## OAuth (HTTP auth mode)
+
+`SSH_MCP_HTTP_AUTH_MODE`, `SSH_MCP_OAUTH_ISSUER`, `SSH_MCP_OAUTH_AUDIENCE`,
+`SSH_MCP_OAUTH_JWKS_URL`, `SSH_MCP_OAUTH_RESOURCE`, `SSH_MCP_OAUTH_REQUIRED_SCOPES`,
+`SSH_MCP_OAUTH_ALLOWED_ALGORITHMS`.
+
+## Remote agent WebSocket boundary
+
+`AGENT_WS_PATH`, `AGENT_WS_HELLO_TIMEOUT_MS`, `AGENT_WS_HEARTBEAT_INTERVAL_MS`,
+`AGENT_WS_IDLE_TIMEOUT_MS`, `AGENT_WS_MAX_CONNECTIONS`,
+`AGENT_WS_MAX_CONNECTIONS_PER_AGENT`, `MAX_ACTION_TIMEOUT_SECONDS`,
+`MAX_OUTPUT_BYTES`. The idle timeout is normalized to at least two heartbeat intervals.
+See [docs/remote-mcp-hardening.md](../remote-mcp-hardening.md) for operational guidance.
+
+## Tool exposure and connectors
+
+`SSH_MCP_TOOL_PROFILE` / `SSH_MCP_CONNECTOR_PROFILE`,
+`SSH_MCP_CONNECTOR_CREDENTIAL_PROVIDER`, `SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND`,
+`SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND_ARGS`,
+`SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND_TIMEOUT_MS`,
+`SSH_MCP_CONNECTOR_DEFAULT_USERNAME`, `SSH_MCP_REMOTE_AGENT_MCP_PASSTHROUGH`. See
+[Tool Profiles](../../README.md#tool-profiles) for what each profile exposes.
+
+## Misc
+
+`SSH_MCP_DEBUG`, `SSH_MCP_RATE_LIMIT*` (global and per-session rate limiting).

package/docs/remote-mcp-hardening.md

@@ -9,8 +9,35 @@ Use this checklist before exposing `ssh-mcp-pro` through a public Streamable HTT
 - The HTTP session registry cleans expired sessions before opening a new session. If capacity is still full, it evicts the oldest idle session with reason `capacity-evict-oldest` instead of returning a persistent 503 that can surface as an upstream 502.
 - Watch logs for `HTTP MCP session removed`, `idle-timeout`, and `capacity-evict-oldest` to confirm cleanup is happening.
 
+## Remote agent WebSocket lifecycle
+
+- Keep `AGENT_WS_HELLO_TIMEOUT_MS` short enough that unauthenticated sockets cannot remain open indefinitely. The default is `10000` milliseconds.
+- `AGENT_WS_MAX_CONNECTIONS` bounds all accepted agent WebSockets, including connections still waiting for `agent.hello`. The default is `128`.
+- `AGENT_WS_MAX_CONNECTIONS_PER_AGENT` bounds active and replacement candidates for one enrolled agent. The default is `2`, which permits one live connection and one authenticated replacement attempt.
+- `AGENT_WS_HEARTBEAT_INTERVAL_MS` defaults to `30000`. The server sends protocol pings and treats pong or text traffic as activity.
+- `AGENT_WS_IDLE_TIMEOUT_MS` defaults to `90000` and is normalized to at least two heartbeat intervals. Idle connections close cleanly and are forcibly terminated if the close handshake does not complete.
+- The `/readyz` response reports `agent_connections_open` and `agent_connections_unauthenticated`. Audit events record global/per-agent capacity rejection, hello timeout, idle timeout, replacement, and safe numeric close codes.
+- Keep WebSocket compression disabled at the public boundary. Agent messages are text-only and capped at 1 MiB.
+
 ## OAuth and token verification
 
+The remote control plane requires explicit browser confirmation before redirecting
+users to GitHub OAuth. `/oauth/authorize` shows the client destination and scopes;
+a same-browser, short-lived HttpOnly/SameSite transaction cookie is required by
+`POST /oauth/approve` and the GitHub callback. Real HTTPS deployments add `Secure`.
+Clients must keep PKCE and exact registered redirect URI matching. Public dynamic
+client registrations are limited to 20 per TCP peer per five minutes per process,
+with the existing global database cap retained. Deployments behind shared proxies
+should also enforce edge rate limits and monitor registration exhaustion.
+
+Remote REST endpoints enforce OAuth token capabilities independently: agent list
+and details require `agents:read`; audit history requires `agents:admin`.
+
+Remote agent file writes use verified same-directory temporary files and atomic
+replacement so an interrupted write does not truncate an existing target. Renaming
+requires write permission on the containing directory, in addition to file access.
+
+
 - Prefer OAuth mode for public endpoints.
 - Configure `SSH_MCP_OAUTH_ISSUER`, `SSH_MCP_OAUTH_JWKS_URL`, and either `SSH_MCP_OAUTH_AUDIENCE` or `SSH_MCP_OAUTH_RESOURCE` explicitly.
 - Use `SSH_MCP_OAUTH_ALLOWED_ALGORITHMS` to pin accepted JWT algorithms when your authorization server has a stable signing policy.