DEV Community

Alp Allovi
Alp Allovi

Posted on

Introducing Ayeixa MCP Guardian: Capability Fencing & Parameter Sanitization for MCP

#opensource #security #ai #typescript

Introducing Ayeixa MCP Guardian: Capability Fencing & Parameter Sanitization for MCP

Model Context Protocol (MCP) empowers language models to interact directly with databases, filesystems, and CLI utilities. However, exposing tool APIs creates security vulnerabilities: unauthorized directory traversal (../../etc/passwd), destructive shell commands (rm -rf), and untracked actions.

Ayeixa MCP Guardian (@ayeixa/mcp-guardian) is a runtime capability fence and parameter sanitization middleware for Model Context Protocol servers and client tool invocations.

1. Core Architecture

MCP Guardian operates as an interceptor middleware:

  1. ToolPermissionFence: Enforces granular Role-Based Access Control (RBAC) and explicit tool allowlists/denylists.
  2. InvocationSanitizer: Sanitizes parameter arguments, blocking directory traversal patterns (../) and dangerous system commands (sudo, rm -rf, chmod 777).
  3. RuntimeAuditLogger: Records every invocation payload, argument set, and permission verdict into a tamper-evident SHA-256 cryptographic hash chain.
  4. GuardianSandbox: Permission-gated execution wrapper evaluating authorization rules and logging audit records before dispatching to tool executors.

2. Implemented Capabilities & Test Verification

Verified with hermetic unit tests:

  • Permission Fencing: RBAC and denied command enforcement (tests/permission.test.ts).
  • Audit Ledger: Cryptographic hash chain validation (tests/audit.test.ts).
  • Execution Wrapper: Permission-gated dispatch and error containment (tests/sandbox.test.ts).

Verification: 6/6 hermetic unit tests passing (0 failures).

3. Local Quick Start 

git clone https://github.com/alpallovy/ayeixa-mcp-guardian.git
cd ayeixa-mcp-guardian
npm ci
npm run build
npm test
Enter fullscreen mode Exit fullscreen mode

Usage Example 

import { GuardianSandbox, ToolPermissionFence, RuntimeAuditLogger } from './src';

const fence = new ToolPermissionFence({
  allowedTools: ['read_file', 'list_dir'],
  blockedCommands: ['rm -rf', 'sudo', 'chmod 777']
});
const audit = new RuntimeAuditLogger();
const sandbox = new GuardianSandbox(fence, audit);

const verdict = await sandbox.evaluateAndExecute({
  toolName: 'read_file',
  arguments: { path: './src/index.ts' },
  role: 'developer'
}, async (args) => {
  return "File content safely read.";
});

console.log("Allowed:", verdict.allowed);
Enter fullscreen mode Exit fullscreen mode

4. Limitations & Contributing

  • Pre-release v0.1.0-alpha. Provides application-level permission gating and parameter sanitization.
  • Public npm publication is pending.
  • We encourage security developers and researchers to contribute. See open good first issue tags on GitHub.

License: Apache-2.0

Top comments (1)

Collapse
 
deanlee profile image
Dean Lee •

The interesting bit is the runtime boundary. MCP servers tend to look harmless until they can touch shell, files, or credentials, so I like seeing tests around traversal and destructive commands. I would add one boring check next. Log every denied call with enough context to explain whether the policy or the prompt failed.