# MCP stdio ShellGuard [Health: Active]

**Category:** 🔒 Security  
**Repository:** https://github.com/studiomeyer-io/mcp-stdio-shellguard  
**GitHub Stars:** 0  
**npm Downloads (last month):** 483  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-stdio-shellguard

## Description
Defense-in-depth for MCP stdio servers: shell-injection guard, AST audit CLI, RCE blocking.

## Tools
Capabilities this server exposes over MCP:

- **guard_exec** — Defended `child_process.exec`. Forces args[] vector, allowlist + sandbox + replay. Returns `stdout`, `stderr`, `exitCode`, `canonicalHash`, `isReplay`, `trustTier`.
- **guard_spawn** — Defended `child_process.spawn`. Returns SHA-256 hashes of stdout/stderr instead of full bodies. Hard-rejects `shell:true`.
- **register_allowlist** — Register a tool name with executable + args regex. Without registration the default-deny applies.
- **audit_source** — Scan a TS/JS path for shell-injection anti-patterns. Returns `AuditFinding[]` + summary.
- **audit_report** — Format an audit result as markdown / json / SARIF 2.1.0.
- **replay_check** — Compute canonical SHA-256 hash for an invocation and report whether it's already in the replay window.
- **sandbox_status** — Report active sandbox profile + concrete limits + cgroup-v2 active flag.
- **trust_tier** — Derive LOW/MEDIUM/HIGH/CRITICAL tier for a registered tool plus improvement hints.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-stdio-shellguard": {
    "command": "npx",
    "args": ["-y","-p","mcp-stdio-shellguard","mcp-shellguard-audit"]
  }
}
```

## Documentation

## What MCP stdio ShellGuard does

MCP stdio ShellGuard adds controls around subprocess execution in Node.js MCP servers. Its library API provides guarded alternatives to `child_process.exec` and `child_process.spawn`, while its reference MCP server makes those controls available as MCP tools.

Execution is governed by a registered executable and argument allowlist. Unregistered tools are denied by default. Guarded calls also use sandbox profiles and a replay window, allowing the result to include a canonical SHA-256 invocation hash, replay status, and a derived trust tier.

The package also includes an AST-based audit CLI and an MCP audit tool. These inspect TypeScript and JavaScript source for unsafe shell-call patterns, including dynamic commands, shell-enabled process options, risky argument construction, missing timeouts, and unbounded output buffers.

## How it works

Register each permitted tool with an executable and optional argument regular expressions. A call through `guardExec` or `guardSpawn` then checks the registration, applies the selected sandbox profile, and evaluates the invocation against the replay window. Callers may reduce the timeout or file-descriptor budget for an individual invocation, but cannot raise those values above the profile limits.

The default `standard` profile allows a 30-second timeout, 10 MB of stdout, 1 MB of stderr, and 256 file descriptors. `strict` reduces those limits to 5 seconds, 1 MB of stdout, 256 KB of stderr, and 32 file descriptors. `permissive` allows up to 5 minutes, 100 MB of stdout, 10 MB of stderr, and 1,024 file descriptors. cgroup-v2 controls are active for the strict and standard profiles.

The audit scanner parses source code and reports findings by severity. It resolves renamed `child_process` imports and bindings, and covers synchronous process variants as well as asynchronous calls. Findings can be filtered by severity for CI use.

## Setup and configuration

Install the package with npm:

```bash
npm install mcp-stdio-shellguard
```

The audit command can also run without a project installation:

```bash
npx -y -p mcp-stdio-shellguard mcp-shellguard-audit scan ./src
```

The CLI supports output formats including SARIF and accepts an output path. Its exit status is `0` for a clean scan at the selected severity floor, `1` when findings meet that floor, and `2` for parsing or I/O errors.

Library consumers create an allowlist registry and replay window, register an executable such as Git with permitted argument patterns, and pass both objects to a guarded execution call. The package targets Node.js 20 or newer and follows the MCP specification dated 2025-06-18.

## Tools and capabilities

The reference MCP server exposes:

- `guard_exec` for defended `child_process.exec` calls, returning process output, exit status, hash, replay state, and trust tier.
- `guard_spawn` for defended `child_process.spawn` calls. It rejects `shell: true` and returns SHA-256 hashes for stdout and stderr.
- `register_allowlist` for adding an executable and argument patterns to the registry.
- `audit_source` for scanning a TypeScript or JavaScript path.
- `audit_report` for formatting audit results as Markdown, JSON, or SARIF 2.1.0.
- `replay_check` for checking whether an invocation hash is already in the replay window.
- `sandbox_status` for reporting the active profile, limits, and cgroup-v2 state.
- `trust_tier` for assigning LOW through CRITICAL status and returning improvement hints.

The scanner recognizes twelve anti-pattern categories, ranging from missing timeouts to dynamic command strings and shell-enabled execution. `shellguard:ignore-next-line` suppresses one finding, while `shellguard:ignore-file` suppresses a complete file.

## Limitations and notes

The reference server is one way to drive the package; the library API is intended for integration into an MCP server's own code. Allowlist registrations with no argument patterns receive a lower trust tier because any arguments are accepted. The scanner's ignore-glob input is bounded to 128 strings, with length and grouping-character limits.

`guard_spawn` returns hashes rather than complete stdout and stderr bodies. Sandbox limits cannot be widened per call, and the permissive profile does not use cgroup-v2 controls. The package bundles parser dependencies, which increases its archive and unpacked size and means dependency security updates require a new package archive.

_Full upstream README: https://allmcps.com/mcp/mcp-stdio-shellguard/readme_