使用说明

气锁MCP

安全第一传递代理模型上下文协议Airlock位于您的AI主机（VS Code、Claude Desktop）和任何MCP服务器之间，在转发请求之前执行可配置的安全策略。

AI Host (VS Code / Claude Desktop)
        |
        v
  [ Airlock-MCP ]  <-- security checks run here
        |
        v
  Target MCP Server (filesystem, database, API, etc.)

为什么

MCP服务器可以公开强大的工具——文件系统访问、shell执行、数据库查询。Airlock允许您在不授予AI无限制访问权限的情况下运行它们：

允许使用的工具 按名称-默认情况下拒绝其他所有内容
阻挡危险的贝壳图案 在它们到达服务器之前
作用域文件系统访问 到特定目录
速率限制 全局或按工具调用工具
拒绝超大有效载荷 在他们击中目标之前
修改个人身份信息 从到达模型之前的响应中

所有检查都按顺序运行，具有故障保护功能，每个决定都会被记录下来。

安装

npm install -g airlock-mcp

或者在不安装的情况下运行：

npx airlock-mcp --config airlock.config.json

快速开始

1.创建 airlock.config.json:

{
  "targetCommand": "npx",
  "targetArgs": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
  "allowedTools": ["read_file", "list_directory", "search_files"],
  "allowedPaths": ["/home/user/projects"],
  "blockDangerousCommands": true,
  "logging": { "level": "info", "destination": "stdout" }
}

2.将AI主机指向Airlock （参见主机集成在......下面

主机集成

VS代码（副驾驶/MCP扩展）

在 .vscode/mcp.json 或用户 settings.json:

{
  "mcpServers": {
    "secure-filesystem": {
      "command": "npx",
      "args": ["airlock-mcp", "--config", "/absolute/path/to/airlock.config.json"]
    }
  }
}

克劳德桌面

在 claude_desktop_config.json:

{
  "mcpServers": {
    "secure-filesystem": {
      "command": "npx",
      "args": ["airlock-mcp", "--config", "/absolute/path/to/airlock.config.json"]
    }
  }
}

安全检查

每个 tools/call 请求按顺序通过这些检查。任何步骤的失败都会返回错误，并且请求永远不会被转发。

#	检查	配置字段	默认值
1	工具列表	`allowedTools`	否认一切
2	危险的命令模式	`blockDangerousCommands`	已启用
3	路径范围	`allowedPaths`	允许所有
4	速率限制	`rateLimiting`	残疾人
5	请求大小	`sizeLimits`	残疾人
6	响应大小	`sizeLimits`	残疾人
7	PII编辑	`piiRedaction`	残疾人

resources/read 根据以下内容检查请求 allowedResources （种类前缀allowlist）。

配置参考

目标服务器

正是其中之一 targetCommand 或 targetUrl 是必需的。

{
  // Spawn a local MCP server over stdio
  "targetCommand": "npx",
  "targetArgs": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
  "targetEnv": { "MY_VAR": "value" },  // optional env vars for the child process

  // OR connect to a remote HTTP MCP server
  "targetUrl": "https://my-mcp-server.example.com"
}

工具列表

{
  // Only these tools are forwarded. Everything else is blocked.
  // Empty array (the default) blocks all tools.
  "allowedTools": ["read_file", "list_directory", "search_files"]
}

资源分配表

{
  // resources/read URIs must start with one of these prefixes.
  // Empty array (the default) blocks all resources.
  "allowedResources": ["mcp://public/", "mcp://logs/"]
}

路径范围

{
  // Tool arguments containing filesystem paths must resolve inside one
  // of these directories. URL-encoding is decoded and symlinks are
  // followed before checking, so traversal tricks don't work.
  // Empty array (the default) skips path checking entirely.
  "allowedPaths": ["/home/user/projects", "/tmp/workspace"]
}

危险指令封锁

{
  // Scan tool arguments for shell operators and dangerous commands:
  // &&, pipes, semicolons before rm/sudo/curl/etc., backticks, $().
  // Default: true
  "blockDangerousCommands": true
}

速率限制

默认情况下禁用。使用滑动窗口-时间戳早于 windowMs 每张支票上都有修剪。被阻止的请求不消耗配额。

{
  "rateLimiting": {
    "enabled": true,
    "windowMs": 60000,       // sliding window in ms (default: 60 000)
    "maxRequests": 100,      // max allowed calls per window, globally

    // Per-tool overrides - inherits global windowMs/maxRequests if omitted
    "perTool": {
      "write_file": { "maxRequests": 10 },
      "execute_command": { "windowMs": 10000, "maxRequests": 3 }
    }
  }
}

有效载荷大小限制

默认情况下禁用。请求大小以JSON序列化参数的UTF-8字节长度来衡量。响应大小是所有值的总和 text 内容项。

{
  "sizeLimits": {
    "enabled": true,
    "maxRequestBytes": 1048576,    // 1 MB  (default)
    "maxResponseBytes": 10485760   // 10 MB (default)
  }
}

PII编辑

默认情况下禁用。扫描工具和资源响应文本，并用键入的占位符替换匹配项，如 [SSN:REDACTED].

{
  "piiRedaction": {
    "enabled": true,

    // Optional: list specific patterns to apply.
    // Omit to use the default set (marked below).
    "patterns": ["ssn", "credit_card", "api_key", "email"]
  }
}

可用图案：

模式	检测	默认打开
`ssn`	美国社会保障号码	是
`credit_card`	信用卡/借记卡号码	是
`bank_account`	银行账号（靠近关键字）	否
`api_key`	API密钥和令牌(`sk-`, `pk-`等）	是
`aws_key`	AWS访问密钥ID(`AKIA...`)	是的
`password`	配置/日志格式的密码	是
`private_key`	PEM私钥块	是
`jwt`	JSON Web令牌	是
`connection_string`	数据库连接字符串	是
`email`	电子邮件地址	是
`phone`	电话号码	否
`ip_address`	IPv4地址	否
`iban`	国际银行账号	否
`swift`	SWIFT/BIC代码	否
`internal_url`	内部/公司/临时网址	否

日志记录

{
  "logging": {
    "level": "info",           // "debug" | "info" | "warn" | "error"
    "destination": "stdout",   // "stdout" | "file"
    "filePath": "/var/log/airlock.log"  // required when destination is "file"
  }
}

日志的结构为JSON(皮诺).安全决策（允许/拒绝）记录在 info 或 warn 审计级别。

完整示例配置

{
  "targetCommand": "npx",
  "targetArgs": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
  "allowedTools": [
    "read_file",
    "write_file",
    "list_directory",
    "search_files"
  ],
  "allowedResources": ["mcp://public/"],
  "allowedPaths": ["/home/user/projects"],
  "blockDangerousCommands": true,
  "rateLimiting": {
    "enabled": true,
    "windowMs": 60000,
    "maxRequests": 200,
    "perTool": {
      "write_file": { "maxRequests": 20 }
    }
  },
  "sizeLimits": {
    "enabled": true,
    "maxRequestBytes": 1048576,
    "maxResponseBytes": 10485760
  },
  "piiRedaction": {
    "enabled": true,
    "patterns": ["api_key", "password", "private_key", "jwt", "connection_string"]
  },
  "logging": {
    "level": "info",
    "destination": "stdout"
  }
}

安全设计原则

默认情况下拒绝 -空的 allowedTools 或 allowedResources 阻止一切
无信息披露 -被阻止的工具错误不会显示满列表
故障保险 -任何验证错误都会阻止请求；什么都不会掉下来
被阻止的请求没有配额消耗 -费率限制预算仅用于转接呼叫
启动时验证配置 通过Zod-代理不会以无效的配置启动

发展

npm install
npm run dev -- --config airlock.config.json   # run with ts-node (no build needed)
npm run build                                  # compile TypeScript -> dist/
npm test                                       # unit tests (vitest)
npm run test:watch                             # watch mode
npm run test:integration                       # integration tests (spawns processes)
npm run typecheck                              # type check without emitting

要运行单个测试文件，请执行以下操作：

npx vitest run src/test/guard.test.ts

许可证

麻省理工学院