Pacote de defesa em profundidade para servidores MCP stdio: wrappers guardExec/guardSpawn de substituição, CLI de auditoria AST, servidor MCP de referência. Fecha a classe de RCE via stdio de 200k servidores do Ox-Security (CVE-2025-69256 do LiteLLM). MIT, TypeScript, Node >= 20.
Parte do StudioMeyer MCP Stack — Construído em Mallorca 🌴 · ⭐ se você usar
com allowlist + sandbox + detecção de replay, além de uma CLI de auditoria AST (mcp-shellguard-audit)
que escaneia os códigos-fonte de servidores MCP em busca de chamadas de shell não sanitizadas. Fecha a classe
de RCE via stdio em MCP da Ox-Security (200 mil servidores vulneráveis, divulgação de maio de 2026).
@modelcontextprotocol/sdk ^1.29.0npm install mcp-stdio-shellguard
Ou execute a CLI de auditoria diretamente sem instalar:
npx -y -p mcp-stdio-shellguard mcp-shellguard-audit scan ./src
A versão 0.1.3 inclui o pacote de dependências descrito abaixo.
O pacote distribui @typescript-eslint/typescript-estree, além do TypeScript e do fecho de dependências do parser necessário, através de bundledDependencies. Uma substituição (override) npm apenas na raiz não restringe a árvore de dependências de um pacote instalado; o fecho incluído transporta as versões verificadas para os consumidores. A preparação do pacote verifica @typescript-eslint/typescript-estree 8.72.1 e minimatch 11.0.3 e, em seguida, altera apenas o intervalo de dependência do manifesto do parser de minimatch ^10.2.2 para ^11.0.3. Os ficheiros de código-fonte de terceiros e os números de versão dos pacotes permanecem inalterados. A auditoria da AST chama diretamente typescript-estree.parse, com o TypeScript incluído explicitamente para satisfazer a árvore de dependências do parser; não é necessário qualquer runtime do ESLint.
O arquivo medido tem aproximadamente 4,92 MB comprimido e 26,04 MB descomprimido (MB decimais). O empacotamento aumenta o download e o uso de disco; uma atualização de segurança a uma dependência incluída exige um novo arquivo do pacote.
Para manutenção, execute npm ci e npm run test:consumer a partir do checkout do repositório. O npm pack executa o prepack automaticamente: compila o pacote e prepara o bundle declarado. A verificação do consumidor empacota duas vezes, verifica se os bytes são idênticos, instala o arquivo real num projeto novo, verifica o npm ls e ambas as auditorias de dependências, e exercita a CLI ou o runtime instalado. Reveja as atualizações de dependências em conjunto com o bundle bloqueado e as provas de licença antes de distribuir um novo arquivo. O ficheiro dist/bundled-dependencies.json do arquivo regista o bundle e os ajustes ao manifesto.
Três camadas, opcionais e utilizáveis individualmente:
guardExec / guardSpawn prontos a usar, que chama a partir do seu
próprio servidor MCP. Lista de permissões com negação por omissão, perfis de sandbox, janela de replay.mcp-shellguard-audit scan <path> percorre a AST e reporta
12 anti-padrões, de LOW (no timeout) a CRITICAL (exec(\...${userInput}...`)`).mcp-stdio-shellguard-demo expõe 8 ferramentas
para que o MCP Inspector / Claude Desktop possam controlar o bundle diretamente.| Ferramenta | Tipo | Finalidade |
|---|---|---|
guard_exec | destrutiva | child_process.exec protegido. Força o vetor args[], lista de permissões + sandbox + replay. Devolve stdout, stderr, exitCode, canonicalHash, isReplay, trustTier. |
guard_spawn | destrutiva | child_process.spawn protegido. Devolve hashes SHA-256 de stdout/stderr em vez dos corpos completos. Rejeita firmemente shell:true. |
register_allowlist | mutável | Regista um nome de ferramenta com executável + regex de args. Sem registo aplica-se a negação por omissão. |
audit_source | apenas leitura | Analisa um caminho TS/JS à procura de anti-padrões de injeção de shell. Devolve AuditFinding[] + resumo. |
audit_report | apenas leitura | Formata um resultado de auditoria como markdown / json / SARIF 2.1.0. |
replay_check | apenas leitura | Calcula o hash SHA-256 canónico de uma invocação e indica se já está na janela de replay. |
sandbox_status | apenas leitura | Reporta o perfil de sandbox ativo + limites concretos + indicador de cgroup-v2 ativo. |
trust_tier | apenas leitura | Deriva o nível LOW/MEDIUM/HIGH/CRITICAL para uma ferramenta registada, mais sugestões de melhoria. |
| Perfil | Timeout | Máx. stdout | Máx. stderr | Orçamento de FD | cgroup-v2 |
|---|---|---|---|---|---|
strict | 5 s | 1 MB | 256 KB | 32 | sim (cpu/memory) |
standard (predefinido) | 30 s | 10 MB | 1 MB | 256 | sim |
permissive | 5 min | 100 MB | 10 MB | 1024 | não |
O chamador pode restringir através de timeoutMs / fdBudget por chamada. O chamador não pode alargar
para além do perfil.
| Nível | Condição |
|---|---|
| LOW | ferramenta não registada (negação por omissão) |
| MEDIUM | registada mas argsPatterns vazio (quaisquer args permitidos) |
| HIGH | argsPatterns definido mas sandbox ou rastreador de replay inativo |
| CRITICAL | argsPatterns + sandbox + replay todos ativos |
Eleve LOW → CRITICAL registrando a ferramenta + definindo argsPatterns + executando
através de guardExec/guardSpawn (que sempre ativam sandbox + replay).
import {
AllowlistRegistry,
ReplayWindow,
guardExec,
} from "mcp-stdio-shellguard";
const registry = new AllowlistRegistry();
const replay = new ReplayWindow();
registry.register({
toolName: "git-log",
executable: "/usr/bin/git",
argsPatterns: ["^log$", "^--oneline$", "^-n$", "^\\d+$"],
sandboxProfile: "strict",
});
const result = await guardExec(
{
toolName: "git-log",
command: "/usr/bin/git",
args: ["log", "--oneline", "-n", "10"],
},
{ registry, replay },
);
console.log(result.stdout); // → commit lines
console.log(result.trustTier); // → "CRITICAL"
console.log(result.canonicalHash); // → 64-char SHA-256
mcp-shellguard-audit scan ./src
mcp-shellguard-audit scan ./src --format sarif --output audit.sarif
mcp-shellguard-audit scan ./src --severity-floor HIGH # CI gate
Códigos de saída:
0 limpo (nenhum achado no nível mínimo ou acima)1 achados presentes2 erros de análise / E/SignoreGlobs personalizados passados para scanPath ou para a ferramenta MCP audit_source aceitam
no máximo 128 strings. Cada string é limitada a 1024 unidades de código UTF-16 e 16
caracteres de agrupamento de abertura não escapados ((, {, [). Entradas acima desses
limites geram um erro controlado antes da correspondência.
Descubra as ferramentas mais usadas pela nossa comunidade.
Sem dados de popularidade ainda.