ssh-mcp 2.10.0 → 2.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +63 -4
- package/build/cli.js +3 -0
- package/build/config/schema.js +6 -0
- package/build/ssh/connection.js +75 -3
- package/build/tools/audit-effects.js +76 -0
- package/build/tools/descriptions.js +1 -1
- package/build/tools/file-tools.js +30 -11
- package/build/tools/transfer-tools.js +1 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -154,7 +154,7 @@ claude mcp add --transport stdio ssh-mcp -- ssh-mcp
|
|
|
154
154
|
| `read-command` | Execute allowlisted read-only commands (`ls`, `cat`, `grep`, ...) | ✅ | — |
|
|
155
155
|
| `run-command` | Execute arbitrary commands (destructive/privileged need approval, unless `approvalPolicy = "auto"`) | — | — |
|
|
156
156
|
| `privileged-command` | Execute with sudo (needs approval, unless `approvalPolicy = "auto"`) | — | ✅ |
|
|
157
|
-
| `sftp-upload` | Upload a file via SFTP | — | ✅ |
|
|
157
|
+
| `sftp-upload` | Upload a file via SFTP (replaces the destination unconditionally) | — | ✅ |
|
|
158
158
|
| `sftp-download` | Download a file via SFTP | ✅ | — |
|
|
159
159
|
| `sftp-list` | List a remote directory, bounded in entries and bytes | ✅ | — |
|
|
160
160
|
| `sftp-upload-file` | Stream a local file to the remote host, never through model context | — | ✅ |
|
|
@@ -168,6 +168,24 @@ the text is an argument on the way out and a response on the way back. That is
|
|
|
168
168
|
what you want for a config snippet and exactly what you do not want for a 200 MB
|
|
169
169
|
tarball or anything binary.
|
|
170
170
|
|
|
171
|
+
The two also differ on what they do to an existing destination, and the approved
|
|
172
|
+
string now says which is which. `sftp-upload` replaces unconditionally and spells
|
|
173
|
+
`--overwrite` every time, because that is what it always does; `sftp-upload-file`
|
|
174
|
+
refuses unless you pass `overwrite: true`, and only then carries the flag. Since
|
|
175
|
+
`sftp-upload` takes its content as an argument rather than naming a local file,
|
|
176
|
+
its string also carries `--bytes=<n> --sha256=<32 hex>` — without that, two
|
|
177
|
+
uploads to the same path are the same string, which means one approval covers
|
|
178
|
+
both and an auditor cannot tell which set of bytes landed. The digest is 128
|
|
179
|
+
bits rather than a short prefix because that claim has to hold against a caller
|
|
180
|
+
who picks both payloads, not only against an accidental repeat.
|
|
181
|
+
|
|
182
|
+
The path comes last in that string on purpose. `[policy].denylist` patterns are
|
|
183
|
+
matched against the whole approved string, so a rule anchored on the path —
|
|
184
|
+
`authorized_keys$`, the natural way to write "nothing may write here" — keeps
|
|
185
|
+
working. A rule anchored on the *whole* string (`^sftp:upload /root/.*$`) does
|
|
186
|
+
not: it was coupled to a format that is ours to change, and this release changes
|
|
187
|
+
it. Anchor on the path segment instead.
|
|
188
|
+
|
|
171
189
|
`sftp-upload-file` and `sftp-download-file` stream between the remote host and
|
|
172
190
|
local disk instead. Neither the bytes nor a base64 encoding of them ever reaches
|
|
173
191
|
the model — the response is a byte count and two paths.
|
|
@@ -298,6 +316,7 @@ role = "operator" # viewer | operator | admin
|
|
|
298
316
|
readOnly = false
|
|
299
317
|
approvalPolicy = "ask-all"
|
|
300
318
|
cert = false # SSH CA cert auth — auto-detects keyRef-cert.pub
|
|
319
|
+
announceAgent = true # Send AI_AGENT=ssh-mcp to this host (see below); clear it for a host you do not control
|
|
301
320
|
sessionMaxPerConnection = 3 # per-profile override
|
|
302
321
|
sessionIdleTimeoutMs = 300000 # stricter for prod
|
|
303
322
|
commandQuotaPerDay = 200 # per-profile override
|
|
@@ -322,6 +341,43 @@ and tier names: every one you write under `[policy.roleBindings]` has to be
|
|
|
322
341
|
reachable by some profile, and every profile's role and tier has to resolve to
|
|
323
342
|
real bindings. Both directions are checked at startup.
|
|
324
343
|
|
|
344
|
+
### Host-side identification
|
|
345
|
+
|
|
346
|
+
Every command this server runs announces itself to the host as the environment
|
|
347
|
+
variable `AI_AGENT=ssh-mcp`, so an operator can tell an agent's session from a
|
|
348
|
+
person's from anything on the host that reads the session environment — a
|
|
349
|
+
`/etc/profile` snippet or a `ForceCommand` wrapper, for instance. It covers all
|
|
350
|
+
three channels a command can run on: one-shot commands, background sessions and
|
|
351
|
+
interactive sessions. SFTP transfers do not carry it, because the SSH library
|
|
352
|
+
this server uses offers no way to send an environment request on a subsystem
|
|
353
|
+
channel.
|
|
354
|
+
|
|
355
|
+
**The variable only lands in the session if the host opts in** with
|
|
356
|
+
`AcceptEnv AI_AGENT` in `sshd_config`. Without that line sshd ignores it and the
|
|
357
|
+
session environment is unchanged — measured against Dropbear, which has no
|
|
358
|
+
`AcceptEnv` mechanism at all, and against Windows OpenSSH on a default
|
|
359
|
+
configuration: the command runs, the exit code is unchanged, the variable is
|
|
360
|
+
simply absent.
|
|
361
|
+
|
|
362
|
+
**The request is nevertheless sent to every host, opted in or not.** `AcceptEnv`
|
|
363
|
+
is the server's policy about what it stores; it is not a gate on what this client
|
|
364
|
+
transmits. A host that has not opted in — including one that is hostile — can
|
|
365
|
+
still see on the wire that an agent rather than a person is driving the session.
|
|
366
|
+
That is why `announceAgent = false` exists on the profile: set it for any host you
|
|
367
|
+
do not control and nothing is sent to it. It is on by default, because the
|
|
368
|
+
operators who benefit are the ones running the hosts you do control.
|
|
369
|
+
|
|
370
|
+
No version is sent, deliberately. A version would narrow a hostile host to one
|
|
371
|
+
specific build; the tool's name alone does not. (The SSH transport already
|
|
372
|
+
discloses the *library* version in its identification string, which is one
|
|
373
|
+
library's version across every program that uses it.)
|
|
374
|
+
|
|
375
|
+
Treat the variable as a courtesy label, not an attestation. Any SSH client can
|
|
376
|
+
set it and any agent can omit it, so it is useful for attributing sessions you
|
|
377
|
+
already trust and must not be used as an authorization or intrusion-detection
|
|
378
|
+
input. Authoritative attribution belongs to the key or principal that
|
|
379
|
+
authenticated.
|
|
380
|
+
|
|
325
381
|
### ProxyJump (Bastion)
|
|
326
382
|
|
|
327
383
|
Reach internal hosts behind a bastion/jump server. The `via` field specifies a profile name to tunnel through:
|
|
@@ -646,11 +702,12 @@ level number.
|
|
|
646
702
|
- **Non-root** user in all examples
|
|
647
703
|
- **TOFU** host key verification (accept on first connect, verify after — within one process; see [SECURITY.md](./SECURITY.md#host-key-trust-does-not-survive-a-restart))
|
|
648
704
|
- **RFC 9142** algorithm allow-list (no SHA-1, no CBC, no ssh-rsa)
|
|
649
|
-
- **exec()-only** (no persistent
|
|
705
|
+
- **exec()-only for elevation** (`privileged-command` takes no `session`, so sudo never runs in a persistent shell — fixes PTY leak. Interactive sessions exist for ordinary commands; this bullet is about elevation, not about every path being an exec channel)
|
|
650
706
|
- **Sudo via stdin** (not argv — fixes process list leak)
|
|
651
707
|
- **Sanitizer** strips CR/LF/NUL from all metadata
|
|
652
708
|
- **3-layer redaction** (field → regex → entropy) on audit logs
|
|
653
709
|
- **No CLI-arg secrets** (use env vars, keychain, or config)
|
|
710
|
+
- **Agent announcement is disclosed, not hidden** — every command tells the host `AI_AGENT=ssh-mcp`, including hosts that never opted in to storing it; clear `announceAgent` on a profile pointing at a host you do not control (see [Host-side identification](#host-side-identification))
|
|
654
711
|
|
|
655
712
|
### Hardening Checklist
|
|
656
713
|
|
|
@@ -858,8 +915,10 @@ is an opt-out only for hosts you have not pinned (test environments only).
|
|
|
858
915
|
## Testing
|
|
859
916
|
|
|
860
917
|
```bash
|
|
861
|
-
# Start test SSH
|
|
862
|
-
|
|
918
|
+
# Start test SSH servers. --build matters: compose reuses an existing image, and a
|
|
919
|
+
# fixture change (such as the alpine target's AcceptEnv line) then never lands,
|
|
920
|
+
# which shows up as a product failure in the integration suite.
|
|
921
|
+
docker compose --profile test up -d --build
|
|
863
922
|
|
|
864
923
|
# Run all tests
|
|
865
924
|
npm test
|
package/build/cli.js
CHANGED
|
@@ -331,6 +331,9 @@ export async function buildAppConfig(argv) {
|
|
|
331
331
|
role: 'admin',
|
|
332
332
|
group: resolveHostGroup(argv),
|
|
333
333
|
readOnly: false,
|
|
334
|
+
// Same default as the config schema. A CLI profile is the one-off case —
|
|
335
|
+
// --host/--user with no config file — and it announces like any other.
|
|
336
|
+
announceAgent: true,
|
|
334
337
|
approvalPolicy: flagEnabled(argv, 'disableApproval') ? 'auto' : defaults.approvalMode,
|
|
335
338
|
cert: false,
|
|
336
339
|
sessionMaxPerConnection: defaults.sessionMaxPerConnection,
|
package/build/config/schema.js
CHANGED
|
@@ -161,6 +161,12 @@ export const profileSchema = z.object({
|
|
|
161
161
|
role: z.string().default('operator'),
|
|
162
162
|
readOnly: z.boolean().default(false),
|
|
163
163
|
cert: z.boolean().default(false),
|
|
164
|
+
// A schema-level default rather than a [defaults] entry, like tty/readOnly/cert
|
|
165
|
+
// above: which hosts an operator trusts with the announcement is a property of
|
|
166
|
+
// the individual host, not something worth setting globally and overriding per
|
|
167
|
+
// profile. Defaults to true — the announcement is the feature; the switch is for
|
|
168
|
+
// the host you do not control.
|
|
169
|
+
announceAgent: z.boolean().default(true),
|
|
164
170
|
// Left optional on purpose: normalizeConfig() fills these from [defaults], and
|
|
165
171
|
// a schema-level .default() would make "user omitted it" indistinguishable
|
|
166
172
|
// from "user set the default value", silently shadowing [defaults].
|
package/build/ssh/connection.js
CHANGED
|
@@ -7,6 +7,51 @@ import { redactText } from '../guard/redactor.js';
|
|
|
7
7
|
import { shellSingleQuote } from '../guard/sanitizer.js';
|
|
8
8
|
import { openWithRetry } from './channel-retry.js';
|
|
9
9
|
import { terminateChannel, COULD_NOT_SIGNAL } from './channel-signal.js';
|
|
10
|
+
/**
|
|
11
|
+
* What this server tells a host it is, on every channel it opens for a command.
|
|
12
|
+
*
|
|
13
|
+
* ssh2's `exec()` calls `reqEnv(chan, opts.env)` with no callback, so the request
|
|
14
|
+
* goes out with `want_reply=0` and the server has nothing to reply to: an
|
|
15
|
+
* unaccepted name cannot fail the exec. Measured against ssh2 1.17.0
|
|
16
|
+
* (`lib/client.js:1230` and the `wantReply` line at `:1863`), against Dropbear,
|
|
17
|
+
* and against Windows OpenSSH on a default config — the command runs, the
|
|
18
|
+
* variable is simply absent, exit code unchanged.
|
|
19
|
+
*
|
|
20
|
+
* **The request is sent to every host, `AcceptEnv` or not.** `AcceptEnv` is the
|
|
21
|
+
* server's policy about whether it *stores* the pair in the session environment;
|
|
22
|
+
* it is not a client-side gate, and nothing here consults it. Measured on the
|
|
23
|
+
* wire against Dropbear, which has no `AcceptEnv` mechanism at all:
|
|
24
|
+
*
|
|
25
|
+
* Outbound: Sending CHANNEL_REQUEST (r:0, env: AI_AGENT=ssh-mcp)
|
|
26
|
+
* Outbound: Sending CHANNEL_REQUEST (r:0, exec: echo hi)
|
|
27
|
+
*
|
|
28
|
+
* So a host that never opted in still learns that an agent, not a person, is
|
|
29
|
+
* driving this session. That is a disclosure, and SECURITY.md's threat model
|
|
30
|
+
* includes a host tailoring its output to inject the model — which is why
|
|
31
|
+
* `announceAgent = false` exists on the profile. An earlier draft of this comment
|
|
32
|
+
* called the declaration "inert" on a host that had not opted in; that is true of
|
|
33
|
+
* the session environment and false of the wire, and the distinction is the whole
|
|
34
|
+
* reason the profile has a switch.
|
|
35
|
+
*
|
|
36
|
+
* Name only, deliberately — no ssh-mcp build number. The transport already
|
|
37
|
+
* discloses the *library* version in its identification string (ssh2 sends
|
|
38
|
+
* `SSH-2.0-ssh2js<ver>` and nothing here overrides `ident`), but that is one
|
|
39
|
+
* library's version across every user of it; a per-build number for this tool
|
|
40
|
+
* would narrow a hostile host to one deployment.
|
|
41
|
+
*
|
|
42
|
+
* `AI_AGENT` is deliberately outside this project's `SSH_MCP_*` namespace. Every
|
|
43
|
+
* other environment name this repo owns is prefixed; this one is not, because it
|
|
44
|
+
* is a cross-tool convention read by server-side detectors that do not know or
|
|
45
|
+
* care which client sent it, and a prefixed name would defeat the only purpose it
|
|
46
|
+
* has. Renaming it to `SSH_MCP_AGENT` would look like a consistency fix and would
|
|
47
|
+
* silently break every consumer — hence this paragraph.
|
|
48
|
+
*
|
|
49
|
+
* Frozen because it is one object shared by every channel on every connection in
|
|
50
|
+
* the process. Nothing mutates it today; the first per-command addition to a
|
|
51
|
+
* channel's `env` would, and would leak across profiles for the life of the
|
|
52
|
+
* process.
|
|
53
|
+
*/
|
|
54
|
+
const AGENT_ENV = Object.freeze({ AI_AGENT: 'ssh-mcp' });
|
|
10
55
|
/**
|
|
11
56
|
* Stop the command behind `channel`, record why on the span, and return the sentence the
|
|
12
57
|
* rejection should carry.
|
|
@@ -74,19 +119,46 @@ export class SSHConnection {
|
|
|
74
119
|
openShell: async () => {
|
|
75
120
|
await this.ensureConnected();
|
|
76
121
|
return new Promise((resolve, reject) => {
|
|
77
|
-
this.getClient().shell({ term: 'xterm-256color', cols: 200, rows: 50 },
|
|
122
|
+
this.getClient().shell({ term: 'xterm-256color', cols: 200, rows: 50 },
|
|
123
|
+
// Three-argument form, deliberately. ssh2 reclassifies the first
|
|
124
|
+
// argument as the options object when it carries `env` or `x11`
|
|
125
|
+
// (lib/client.js:1260), so folding the announcement into the window
|
|
126
|
+
// object above would silently drop term/cols/rows on every
|
|
127
|
+
// interactive session.
|
|
128
|
+
this.channelEnv(), (err, stream) => (err ? reject(err) : resolve(stream)));
|
|
78
129
|
});
|
|
79
130
|
},
|
|
80
131
|
openExec: async (command) => {
|
|
81
132
|
await this.ensureConnected();
|
|
82
133
|
return new Promise((resolve, reject) => {
|
|
83
|
-
this.getClient().exec(this.applyWorkdir(command), (err, stream) => (err ? reject(err) : resolve(stream)));
|
|
134
|
+
this.getClient().exec(this.applyWorkdir(command), this.channelEnv(), (err, stream) => (err ? reject(err) : resolve(stream)));
|
|
84
135
|
});
|
|
85
136
|
},
|
|
86
137
|
onChannelOpened: () => { this.activeChannels++; },
|
|
87
138
|
onChannelClosed: () => { this.activeChannels--; },
|
|
88
139
|
});
|
|
89
140
|
}
|
|
141
|
+
/**
|
|
142
|
+
* The announcement for a channel about to be opened, or nothing.
|
|
143
|
+
*
|
|
144
|
+
* One accessor rather than an object literal at each site. The first version of
|
|
145
|
+
* this feature wrote `{ env: AGENT_ENV }` at two of the three channel-opening
|
|
146
|
+
* sites and missed `openShell`, which left every command run inside an
|
|
147
|
+
* interactive session unannounced while the README claimed otherwise. Three
|
|
148
|
+
* literals give a site the chance to look complete while carrying nothing; a
|
|
149
|
+
* missing call to this does not.
|
|
150
|
+
*
|
|
151
|
+
* Read live, like every other profile field here: the profile object can be
|
|
152
|
+
* replaced after construction, so an operator clearing `announceAgent` is
|
|
153
|
+
* honoured on the next channel rather than at the next restart.
|
|
154
|
+
*
|
|
155
|
+
* The return type is the intersection both callers accept — `ExecOptions` and
|
|
156
|
+
* `ShellOptions` declare `env` identically — so one accessor serves `exec()`,
|
|
157
|
+
* `openExec` and `openShell` without naming either API.
|
|
158
|
+
*/
|
|
159
|
+
channelEnv() {
|
|
160
|
+
return this.profile.announceAgent === false ? {} : { env: AGENT_ENV };
|
|
161
|
+
}
|
|
90
162
|
async ensureConnected() {
|
|
91
163
|
if (this.isConnected())
|
|
92
164
|
return;
|
|
@@ -254,7 +326,7 @@ export class SSHConnection {
|
|
|
254
326
|
reject(new Error(`Command timed out after ${timeoutMs}ms${note}`));
|
|
255
327
|
}
|
|
256
328
|
}, timeoutMs);
|
|
257
|
-
const execOpts = {};
|
|
329
|
+
const execOpts = { ...this.channelEnv() };
|
|
258
330
|
if (opts.tty || this.profile.tty) {
|
|
259
331
|
execOpts.pty = { term: 'xterm-256color', cols: 200, rows: 50 };
|
|
260
332
|
}
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import { createHash } from 'crypto';
|
|
2
|
+
/**
|
|
3
|
+
* How the transfer tools spell what they are about to do, in the one string the
|
|
4
|
+
* approver reads, the policy classifies and the audit record keeps.
|
|
5
|
+
*
|
|
6
|
+
* Shared because the two tools spelled one concept differently: `sftp-upload-file`
|
|
7
|
+
* already carried `--overwrite` when it would clobber, while `sftp-upload` — which
|
|
8
|
+
* always clobbers — carried nothing, so the presence of the flag read as a
|
|
9
|
+
* difference between the tools rather than between operations (#223). A second
|
|
10
|
+
* copy of `--overwrite` is one rename away from putting them back out of step, so
|
|
11
|
+
* there is one.
|
|
12
|
+
*
|
|
13
|
+
* `--mode` is *not* at parity and was left that way deliberately. `sftp-upload`
|
|
14
|
+
* applies 0o644 on a create and never says so, while an absent `--mode=` on
|
|
15
|
+
* `sftp-upload-file` means 0o600-or-inherited — one absence, two meanings, which
|
|
16
|
+
* is the same shape of defect #223 describes. Fixing it means deciding what the
|
|
17
|
+
* effective mode even is on an overwrite (createWriteStream's mode is ignored for
|
|
18
|
+
* an existing file), which is a separate question from what this module landed for.
|
|
19
|
+
*/
|
|
20
|
+
/**
|
|
21
|
+
* Spelled once so a rename cannot reach one tool and miss the other.
|
|
22
|
+
*
|
|
23
|
+
* Exported rather than reached through `effectSuffix(true)`: `sftp-upload` has no
|
|
24
|
+
* `overwrite` parameter, so passing a literal `true` to a two-argument helper and
|
|
25
|
+
* letting the reader constant-fold it needed three lines of comment to say what
|
|
26
|
+
* one token says.
|
|
27
|
+
*/
|
|
28
|
+
export const OVERWRITE_FLAG = ' --overwrite';
|
|
29
|
+
/** The arguments that change what a transfer does, spelled for policy and the approver. */
|
|
30
|
+
export function effectSuffix(overwrite, mode) {
|
|
31
|
+
return (overwrite ? OVERWRITE_FLAG : '') + (mode !== undefined ? ` --mode=${mode.toString(8)}` : '');
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* 128 bits, because the property claimed here is adversarial, not accidental.
|
|
35
|
+
*
|
|
36
|
+
* This was 12 characters on first writing, and 48 truncated bits is ~24 bits of
|
|
37
|
+
* birthday security — measured, a collision took 12.3 seconds and 10.9M hashes on
|
|
38
|
+
* one core, producing two 96-byte payloads with the same `--bytes` and the same
|
|
39
|
+
* digest, hence the byte-identical approved string. `--bytes` costs an attacker
|
|
40
|
+
* nothing to match, since both candidates can be padded to one length. At 32
|
|
41
|
+
* characters the same search is 2^64 and not worth describing.
|
|
42
|
+
*
|
|
43
|
+
* Length is free on the redaction axis, which is the reason a short digest looked
|
|
44
|
+
* attractive. The emitted run is `--sha256=<hex>` — `-` and `=` are both in the
|
|
45
|
+
* redactor's character class, so the run is the flag *plus* the digest, and at any
|
|
46
|
+
* digest length it is past that scan's 20-character window and is inspected. It
|
|
47
|
+
* can nonetheless never be redacted: the run draws on 20 distinct symbols, so its
|
|
48
|
+
* Shannon entropy cannot exceed log2(20) = 4.32 against a 4.5 threshold. Measured
|
|
49
|
+
* 4.24 at this length. An earlier version of this comment claimed the digest sat
|
|
50
|
+
* *under* the window; it did not, and reasoning about a length change from that
|
|
51
|
+
* claim would have started from the wrong mechanism.
|
|
52
|
+
*/
|
|
53
|
+
const DIGEST_CHARS = 32;
|
|
54
|
+
/**
|
|
55
|
+
* What the approved string says about the bytes, for a tool whose payload is an
|
|
56
|
+
* argument rather than a named file.
|
|
57
|
+
*
|
|
58
|
+
* `sftp-upload` takes its content inline, so unlike the streaming tools there is
|
|
59
|
+
* no local path in the string to stand for it. Without this, two uploads to the
|
|
60
|
+
* same destination are the same string — to the approver deciding, to
|
|
61
|
+
* `ApprovalGrants` keying on it, and to an auditor later asking which one ran.
|
|
62
|
+
*
|
|
63
|
+
* Byte length rather than `content.length`: a JS string counts UTF-16 code units,
|
|
64
|
+
* and the upload writes `Buffer.from(content)` as utf8, so the two disagree on
|
|
65
|
+
* every multi-byte character. The digest is over the same encoding, which is why
|
|
66
|
+
* `update(content, 'utf8')` states the encoding rather than relying on a default.
|
|
67
|
+
*
|
|
68
|
+
* `string` only, though `SftpClient.upload` also accepts a Buffer: the one tool
|
|
69
|
+
* that calls this takes its content through `z.string()`, so a Buffer branch here
|
|
70
|
+
* would be a branch no test could reach honestly. Widen it when a caller needs it,
|
|
71
|
+
* with the case that needs it.
|
|
72
|
+
*/
|
|
73
|
+
export function payloadSuffix(content) {
|
|
74
|
+
const digest = createHash('sha256').update(content, 'utf8').digest('hex').slice(0, DIGEST_CHARS);
|
|
75
|
+
return ` --bytes=${Buffer.byteLength(content, 'utf8')} --sha256=${digest}`;
|
|
76
|
+
}
|
|
@@ -8,7 +8,7 @@ export const TOOL_DESCRIPTIONS = {
|
|
|
8
8
|
'read-command': 'Execute a READ-ONLY command from an allowlist (ls, cat, grep, find, stat, df, etc.). This tool does NOT modify the system. Prefer this tool for all read operations. Single-line only: a command containing a line break is refused, so upload a multi-line script with sftp-upload and run it by path.',
|
|
9
9
|
'run-command': 'Execute an arbitrary shell command on the remote server. May modify the system. Commands classified destructive or privileged go through the approval gate; approvalPolicy on the profile decides whether that is a prompt, an automatic allow, or a refusal. Single-line only: a command containing a line break is refused, so upload a multi-line script with sftp-upload and run it by path.',
|
|
10
10
|
'privileged-command': 'Execute a command with sudo elevation. Goes through the approval gate; approvalPolicy on the profile decides whether that is a prompt, an automatic allow, or a refusal. The sudo password is piped via stdin (never visible in process list). Single-line only: a command containing a line break is refused, so upload a multi-line script with sftp-upload and run it by path.',
|
|
11
|
-
'sftp-upload': 'Upload a file to the remote server via SFTP (secure file transfer, not shell-based).',
|
|
11
|
+
'sftp-upload': 'Upload a file to the remote server via SFTP (secure file transfer, not shell-based). Replaces an existing file at that path unconditionally — there is no overwrite flag and no way to require a new destination.',
|
|
12
12
|
'sftp-download': 'Download a file from the remote server via SFTP.',
|
|
13
13
|
'sftp-list': 'List a remote directory over SFTP, with a bounded number of entries and a bounded response size. Read-only.',
|
|
14
14
|
'sftp-upload-file': 'Upload a local file to the remote host over SFTP, streaming it without passing the contents through model context. The local file must be inside the transferRoot directory the operator configured; without that setting this tool refuses. Use this for binary or large files; use sftp-upload for short text you already have.',
|
|
@@ -2,18 +2,27 @@ import { z } from 'zod';
|
|
|
2
2
|
import { redactText } from '../guard/redactor.js';
|
|
3
3
|
import { remotePathForAudit, sanitizeRemotePath } from '../guard/sanitizer.js';
|
|
4
4
|
import { SftpClient } from '../ssh/sftp.js';
|
|
5
|
+
import { OVERWRITE_FLAG, payloadSuffix } from './audit-effects.js';
|
|
5
6
|
import { TOOL_DESCRIPTIONS as D } from './descriptions.js';
|
|
6
7
|
import { syntheticSuccess, textResult } from './results.js';
|
|
7
8
|
/**
|
|
8
9
|
* SFTP transfer tools.
|
|
9
10
|
*
|
|
10
11
|
* Both paths go through `sanitizeRemotePath`, the same bar the streaming tools
|
|
11
|
-
* hold — for the *path
|
|
12
|
-
*
|
|
13
|
-
* `sftp-upload
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
12
|
+
* hold — for the *path*.
|
|
13
|
+
*
|
|
14
|
+
* `sftp-upload` truncates an existing remote file unconditionally where
|
|
15
|
+
* `sftp-upload-file` refuses unless `overwrite` is passed. What #223 changed is
|
|
16
|
+
* that the approved string says so: before it named a destination and no effect,
|
|
17
|
+
* and said nothing at all about the bytes, so two uploads to one path were one
|
|
18
|
+
* string — one approval, one indistinguishable audit record. The behaviour is
|
|
19
|
+
* unchanged on purpose: a default of `overwrite: false` would break every caller
|
|
20
|
+
* that relies on replacement. `--overwrite` is therefore constant here, which does
|
|
21
|
+
* mean it carries no per-call information — the per-call signal is `--bytes` and
|
|
22
|
+
* `--sha256`. It stays because the sibling tool omits the flag when it will not
|
|
23
|
+
* clobber, so an approver comparing the two needs its presence to mean something.
|
|
24
|
+
*
|
|
25
|
+
* `synthetic: true` skips `sanitizeCommand`, and these two interpolated
|
|
17
26
|
* the caller's raw string, so nothing refused a bidi override or a zero-width
|
|
18
27
|
* character in a path that is quoted back in the approval prompt and written
|
|
19
28
|
* into a hash-chained audit record — the exact confusion that validator exists
|
|
@@ -32,7 +41,19 @@ export function registerFileTools({ server }, pipeline) {
|
|
|
32
41
|
content: z.string().describe('File content to upload'),
|
|
33
42
|
profile: z.string().optional().describe('Profile name'),
|
|
34
43
|
}, { destructiveHint: true }, async ({ remotePath, content, profile }, extra) => {
|
|
35
|
-
return runAudited(
|
|
44
|
+
return runAudited(
|
|
45
|
+
// Verb, then what the operation does, then the path it does it to — and the
|
|
46
|
+
// path LAST on purpose. The engine matches `[policy].denylist` against this
|
|
47
|
+
// whole string, so an operator rule anchored on the path (`authorized_keys$`,
|
|
48
|
+
// the natural and portable way to write "nothing may write here") keeps
|
|
49
|
+
// working only while the path ends the line. Measured: with the suffixes
|
|
50
|
+
// appended after the path instead, that rule silently stops matching and the
|
|
51
|
+
// refusal degrades to a prompt with no warning. A whole-string rule
|
|
52
|
+
// (`^sftp:upload /root.*$`) breaks either way — it is coupled to a format
|
|
53
|
+
// that is ours to change — so the layout is chosen for the form that is not.
|
|
54
|
+
// `sftp:list` and `sftp:download` carry no flags, so they already read this
|
|
55
|
+
// way and need no change.
|
|
56
|
+
`sftp:upload${OVERWRITE_FLAG}${payloadSuffix(content)} ${remotePathForAudit(remotePath)}`, {
|
|
36
57
|
toolName: 'sftp-upload',
|
|
37
58
|
failureClass: 'destructive',
|
|
38
59
|
profile,
|
|
@@ -43,10 +64,8 @@ export function registerFileTools({ server }, pipeline) {
|
|
|
43
64
|
await new SftpClient(rt.conn).upload({ remotePath, content });
|
|
44
65
|
return {
|
|
45
66
|
audited: syntheticSuccess(rt.profileName),
|
|
46
|
-
//
|
|
47
|
-
//
|
|
48
|
-
// multi-byte character. SftpClient.upload writes Buffer.from(content),
|
|
49
|
-
// which is utf8, so this is exactly what lands on the remote side.
|
|
67
|
+
// utf8 bytes, matching the count the approved string already carries —
|
|
68
|
+
// see `payloadSuffix` in audit-effects.ts for why `.length` is wrong.
|
|
50
69
|
output: textResult(`Uploaded ${Buffer.byteLength(content, 'utf8')} bytes to ${remotePath}`),
|
|
51
70
|
};
|
|
52
71
|
});
|
|
@@ -3,6 +3,7 @@ import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
|
|
|
3
3
|
import { redactText } from '../guard/redactor.js';
|
|
4
4
|
import { remotePathForAudit, sanitizeRemotePath } from '../guard/sanitizer.js';
|
|
5
5
|
import { SftpClient } from '../ssh/sftp.js';
|
|
6
|
+
import { effectSuffix } from './audit-effects.js';
|
|
6
7
|
import { TOOL_DESCRIPTIONS as D } from './descriptions.js';
|
|
7
8
|
import { createLocalDownload, localFileForRead, localPathForAudit, } from './local-path.js';
|
|
8
9
|
import { syntheticSuccess, textResult } from './results.js';
|
|
@@ -142,10 +143,6 @@ export function checkMode(mode) {
|
|
|
142
143
|
}
|
|
143
144
|
return mode;
|
|
144
145
|
}
|
|
145
|
-
/** The arguments that change what a transfer does, spelled for policy and the approver. */
|
|
146
|
-
function effectSuffix(overwrite, mode) {
|
|
147
|
-
return (overwrite ? ' --overwrite' : '') + (mode !== undefined ? ` --mode=${mode.toString(8)}` : '');
|
|
148
|
-
}
|
|
149
146
|
/**
|
|
150
147
|
* What the audit record adds once the local path has been resolved.
|
|
151
148
|
*
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ssh-mcp",
|
|
3
3
|
"license": "MIT",
|
|
4
|
-
"version": "2.
|
|
4
|
+
"version": "2.11.0",
|
|
5
5
|
"description": "MCP server exposing policy-gated, audited SSH access for Linux and Windows hosts via the Model Context Protocol.",
|
|
6
6
|
"mcpName": "io.github.tufantunc/ssh-mcp",
|
|
7
7
|
"type": "module",
|