ssh-mcp-pro 1.1.5 → 1.2.1

package/docs/professionalization-plan.md

@@ -0,0 +1,81 @@
+# Professionalization Plan
+
+A phased plan synthesizing [docs/repo-maturity-report.md](repo-maturity-report.md)'s
+"Safe refactor opportunities," "High-risk refactor opportunities," and "Recommended
+issues" into an ordered sequence. This is a plan, not a commitment with dates — see
+[ROADMAP.md](../ROADMAP.md) for the roadmap framing of the same underlying gaps.
+
+## Phase 0 — Done (this audit)
+
+Documentation, governance, and evidence gaps that required no maintainer decision and
+no behavior change: `CODE_OF_CONDUCT.md`, `GOVERNANCE.md`, `MAINTAINERS.md`,
+`ROADMAP.md`, OpenSSF evidence/gap-analysis docs, Diátaxis documentation structure,
+development-process docs, security docs, and the `gitleaks.yml` workflow.
+
+## Phase 1 — Maintainer decisions, no code change
+
+Status as of 2026-07-03:
+
+1. Apply branch protection on `main` (import the existing ruleset or configure
+   equivalently). **Still open.**
+2. ~~Confirm private vulnerability reporting is enabled.~~ **Done** — confirmed
+   already enabled via API.
+3. ~~Decide on the Dependabot security-updates toggle.~~ **Done** — enabled, along
+   with Dependabot vulnerability alerts.
+4. Merge or re-trigger release-please PR #1 to ship the first release. **Still open**
+   — deliberately left for the maintainer; triggers a real publish action.
+5. Register the repo/workflow as an npm trusted publisher on npmjs.com (the workflow
+   side is already implemented; this is the registry-side counterpart). **Still open**
+   — an npmjs.com-side action outside the repo.
+
+**Why this order:** branch protection and the first release are the two remaining
+changes that would flip the most `Missing`/`Partial` rows in the maturity report to
+`Passed` — they have outsized leverage relative to effort.
+
+## Phase 2 — Low-risk CI additions
+
+Status as of 2026-07-03:
+
+1. ~~Container image vulnerability scanning (Trivy or Grype) in `docker.yml`.~~
+   **Done** — Trivy added, advisory-only. It found real findings: see the new Phase 3
+   item below.
+2. Hadolint for Dockerfile linting. **Still open.**
+3. ~~`publint` as an advisory (non-blocking) npm packaging check.~~ **Done** — added,
+   passes cleanly against the built package.
+
+## Phase 3 — Security follow-through
+
+Status as of 2026-07-03:
+
+1. ~~Fix CodeQL alert #1 (High: clear-text logging in `scripts/start-chatgpt-http.mjs`).~~
+   **Done.**
+2. ~~Review and record disposition for the remaining 7 CodeQL alerts.~~ **Done** — all
+   dismissed via the code-scanning API with rationale re-verified against current code;
+   written up in `SECURITY_DECISIONS.md`.
+3. Re-evaluate Scorecard `publish_results: false` — either fix the blocking
+   `env:`/`defaults:` patterns across workflows, or adjust the README badge. **Still
+   open** — investigated; relocating those blocks across all 7 workflows risks
+   silently breaking the Windows Integration job's shell default, which can't be
+   verified without a live Windows Actions run.
+4. **New: triage the Trivy container-image backlog.** Adding Trivy in item 1 above
+   surfaced 50+ open findings against the built image — mostly the Alpine base image's
+   OpenSSL packages and npm/corepack's own bundled dependencies, not this project's own
+   code. Options: rebuild on a newer/slimmer base image, prune build tooling from the
+   final layer, or accept and document the current baseline explicitly.
+
+## Phase 4 — Community growth (not schedulable)
+
+1. Land a first externally-authored, human-reviewed pull request.
+2. Reconsider a second maintainer once Phase 4.1 has happened more than once — see
+   [GOVERNANCE.md](../GOVERNANCE.md#path-to-adding-maintainers).
+3. Revisit OpenSSF Silver readiness once Phase 4.1–4.2 give real evidence to point to.
+
+## What's explicitly not in this plan
+
+- No plan to pursue OpenSSF Gold/foundation-grade on any timeline — see
+  [docs/openssf-gap-analysis.md](openssf-gap-analysis.md) for why that's an
+  organizational precondition problem, not a checklist.
+- No plan to add PyPI, Go, or Rust packaging — none of those ecosystems are used by
+  this project.
+- No plan to add a `.devcontainer` — assessed as optional given the toolchain is
+  already a single `pnpm install` away from working.

package/docs/reference/README.md

@@ -0,0 +1,21 @@
+# Reference
+
+Reference material is information-oriented: precise, exhaustive where practical, and
+organized for lookup rather than reading start-to-finish. This index follows the
+[Diátaxis](https://diataxis.fr/reference/) definition of "reference."
+
+- [Environment variables](../../README.md#configuration) — the canonical
+  `SSH_MCP_*` configuration table lives in the README so it stays next to the
+  install/quickstart instructions; this reference doesn't duplicate it.
+- [Tool profiles](../../README.md#tool-profiles) — which tools/resources/prompts each
+  connector profile (`full`, `remote-safe`, `chatgpt`, `claude`, `remote-readonly`,
+  `remote-broker`) exposes.
+- [CLI reference](cli.md) — `ssh-mcp-pro` and `ssh-mcp-pro-agent` command-line flags.
+- [Configuration reference](configuration.md) — the `SSH_MCP_*` table grouped by
+  concern, pointing back to the canonical table in the README.
+- [Compatibility reference](compatibility.md) — supported Node.js/pnpm/OS/container
+  platforms and MCP transport/client compatibility.
+- [MCP metadata](../../mcp.json) and [server metadata](../../server.json) — machine-readable
+  capability and registry declarations.
+- [Security defaults](../../SECURITY_DECISIONS.md) — the exact default-deny behaviors and
+  why each exists.

package/docs/reference/cli.md

@@ -0,0 +1,41 @@
+# CLI Reference
+
+ssh-mcp-pro installs two binaries (see `bin` in [package.json](../../package.json)):
+
+- `ssh-mcp-pro` — the MCP server itself.
+- `ssh-mcp-pro-agent` — the remote control-plane agent (see
+  [docs/remote-mcp-hardening.md](../remote-mcp-hardening.md)).
+
+## `ssh-mcp-pro`
+
+Source of truth: [src/cli.ts](../../src/cli.ts).
+
+| Flag / subcommand | Effect |
+| --- | --- |
+| (no args) | Starts the server over stdio transport (default) |
+| `stdio` | Explicitly selects stdio transport |
+| `http` | Selects the Streamable HTTP transport |
+| `agent [...]` | Delegates all remaining arguments to the agent CLI (see below); consumes the rest of `argv` |
+| `--help`, `-h` | Print help and exit |
+| `--version`, `-v` | Print version and exit |
+| `--stdio` | Forces stdio transport |
+| `--transport=stdio` \| `--transport=http` | Explicit transport selection |
+| `--host <value>` | HTTP bind host (overrides `SSH_MCP_HTTP_HOST`) |
+| `--port <value>` | HTTP bind port (overrides `SSH_MCP_HTTP_PORT`) |
+| `--bearer-token-file <path>` | Bearer token file for HTTP auth (overrides `SSH_MCP_HTTP_BEARER_TOKEN_FILE`) |
+| `--enable-legacy-sse` | Enables legacy SSE compatibility (overrides `SSH_MCP_ENABLE_LEGACY_SSE`) |
+| `--tool-profile <name>` | Selects a tool exposure profile (overrides `SSH_MCP_TOOL_PROFILE`) — see [Tool Profiles](../../README.md#tool-profiles) |
+| `--connector-credential-provider <name>` | Selects a connector credential provider (overrides `SSH_MCP_CONNECTOR_CREDENTIAL_PROVIDER`) |
+| `--no-stdio` | Unsupported/internal flag; do not rely on it |
+
+Unknown flags are ignored rather than rejected, so that MCP clients invoking the binary
+with extra arguments don't break the server.
+
+## `ssh-mcp-pro-agent`
+
+Delegates directly to `src/remote/agent-cli.ts` via `argv` passthrough. See
+[docs/remote-mcp-hardening.md](../remote-mcp-hardening.md) and
+[docs/adding-a-device.md](../adding-a-device.md) for the documented agent workflows —
+this reference intentionally doesn't restate flags that aren't yet enumerated in one
+place in the source, to avoid documenting something that could drift silently from the
+implementation.

package/docs/reference/compatibility.md

@@ -0,0 +1,46 @@
+# Compatibility Reference
+
+## Node.js
+
+| Requirement | Value | Source |
+| --- | --- | --- |
+| Minimum supported range | `>=22.22.2 \|\| >=24.15.0 \|\| >=26.3.0` | `package.json` `engines.node` |
+| CI matrix | Node 22, 24, 26 (`Unit Tests (Node 22/24/26)`) | `.github/workflows/ci.yml` |
+| Local development / release builds | Node 24.15.0 / 26.3.0 | `CONTRIBUTING.md`, `release.yml` |
+
+Note the gap between 22.22.2 and 24.15.0: Node 23.x is not supported (it was never an
+LTS line). This is expected, not an oversight.
+
+## Package manager
+
+pnpm `11.28.5`, enforced via `packageManager` in `package.json` and `engine-strict=true`.
+npm/yarn are not supported installation paths for *developing* this repo (consumers
+installing the published package via npm/npx are unaffected — see
+[README.md#installation](../../README.md#installation)).
+
+## Operating systems
+
+| OS | Status | Evidence |
+| --- | --- | --- |
+| Linux | Passed | Primary CI target; SSH fixture-based integration/E2E tests |
+| Windows command paths | Passed | Dedicated `test:integration:windows` project on `windows-2022`; the `Windows Command-Path Integration` job validates local PowerShell and package-manager dispatch, not a real Windows OpenSSH server |
+| macOS | Needs human confirmation | Listed as a supported platform in `mcp.json` (`platforms: [linux, macos, windows]`) but no macOS-specific CI job was found — likely covered incidentally by the cross-platform Node.js/SSH code paths, not by a dedicated test |
+
+## Container platforms
+
+`linux/amd64`, `linux/arm64` — built and verified in `docker.yml` via Buildx + QEMU.
+
+## MCP transport compatibility
+
+| Transport | Status |
+| --- | --- |
+| stdio | Passed — default, used by all documented client configs |
+| Streamable HTTP | Passed — `http`/`--transport=http`, with the non-loopback safety gate described in [SECURITY_DECISIONS.md](../../SECURITY_DECISIONS.md) |
+| Legacy SSE | Partial — available behind `SSH_MCP_ENABLE_LEGACY_SSE` for compatibility, not the recommended path |
+
+## MCP client compatibility
+
+Documented configs exist for a generic stdio client, VS Code, and Claude Desktop (see
+[README.md#quickstart](../../README.md#quickstart)) plus connector-shaped profiles for
+ChatGPT and Claude remote connectors (`chatgpt`, `claude` tool profiles). See
+[Tool Profiles](../../README.md#tool-profiles) for exactly what each profile exposes.

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,6 +9,16 @@ 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
 
 - Prefer OAuth mode for public endpoints.