mcp-tenant-isolation

mcp-tenant-isolation

面向多租户 SaaS 和 MCP 服务代码的静态分析扫描器。包含 57 条确定性规则，可在跨租户数据泄漏进入生产环境前将其拦截。

功能

如果你构建的是多租户软件，那么每个查询、每个缓存键、每次文件访问和每个 API 响应都需要限定到正确的租户。漏掉一处，租户 A 就可能看到租户 B 的数据。这可不是你想在生产环境中才发现的问题。

此扫描器会读取你的源代码，并检查租户隔离防护是否出现在必要的位置。它覆盖数据库查询、API 路由、缓存键、文件存储、架构设计、日志记录和 MCP 服务架构中的 57 种模式。它适用于 TypeScript、JavaScript、Prisma、Drizzle、原始 SQL、Next.js、Express 和 Fastify。

此扫描器也可作为 MCP 服务运行，因此你可以将它接入 Claude Desktop、Cursor 或任何兼容 MCP 的 Agent，让 AI 助手按需扫描代码。

适用对象

• SaaS 工程团队：需要在代码发布前发现租户隔离缺口
• MCP 服务开发者：构建处理租户范围数据的工具
• 安全团队：希望在 CI/CD 中加入租户隔离检查
• AI Agent 开发者：希望让自己的 Agent 扫描代码中的跨租户风险

项目缘由

通用安全扫描器并非专为租户隔离模式设计。它们可以检测 SQL 注入和 XSS，但不会检查你的 findMany 查询是否包含 organizationId 筛选条件，也不会检查 MCP 工具处理程序是否按租户限定工具的可见范围，更不会检查缓存键是否包含租户前缀。

此扫描器专门用于此类检查。它包含 57 条规则，每条规则都针对特定的租户隔离模式进行检查，并生成包含规则 ID、文件、行号、缺失的防护措施和修复提示的发现项。

每条规则都是确定性的。对于相同的源代码，扫描器会生成相同的发现项。它不使用机器学习，也不进行概率评分。不过，静态分析本身存在固有局限。它无法验证运行时行为、数据库层面的强制措施或动态租户隔离。扫描输出包含一个 limitations 字段，列出每次扫描检查和未检查的内容。

安装

npm install -g mcp-tenant-isolation

# or use npx (no install needed)
npx mcp-tenant-isolation scan ./src

# or use Docker (no Node.js needed)
docker run --rm -v $(pwd):/code subodhkc/mcp-tenant-isolation scan /code/src

需要 Node.js 22 或更高版本。

快速开始

mti scan ./src
mti scan ./src --format sarif --output results.sarif
mti scan ./src --format markdown --output TENANT-ISOLATION-REPORT.md
mti scan ./src --format ai --output findings.json
mti scan ./src --severity HIGH
mti rules                          # list all 57 rules
mti baseline                       # snapshot current findings for proof-of-fix tracking
mti init                           # create .mtirc.json with defaults

演示

规则

42 条通用多租户规则

前缀	类别	数量	严重性	检查内容
TCM	租户上下文管理	6	严重	租户 ID 来自会话，而非客户端输入。跨异步边界传播上下文。
DBQ	数据库查询隔离	10	严重	每个涉及租户范围数据的查询都包含租户筛选条件。适用于 Prisma、Drizzle 和原始 SQL。
IDOR	IDOR 防护	5	严重	基于 ID 查找数据时，在返回数据前验证其租户所有权。
CSI	缓存和会话隔离	4	高	缓存键和会话数据均限定在租户范围内。
API	API 安全	3	高	支持租户感知的速率限制和响应范围控制。
FSI	文件存储隔离	4	高	S3、Blob 和文件系统访问均限定在租户范围内。
LOG	日志和审计	4	中	审计日志包含租户上下文。
SCH	架构和迁移	6	高	Prisma 模型和 SQL 迁移包含租户列和索引。

15 条 MCP 专属规则

ID	标题	严重性	检查内容
MCP-001	工具可见性范围控制	严重	工具处理程序缺少基于租户的允许／拒绝筛选。
MCP-002	缓存键租户前缀	严重	工具结果缓存时未添加租户前缀。
MCP-003	将会话绑定到用户和租户	严重	将会话 ID 作为唯一授权依据。
MCP-004	令牌交换（RFC 8693）	高	转发原始令牌，而非进行令牌交换。
MCP-005	按租户进行速率限制	中	工具调用未按租户进行速率限制。
MCP-006	向量存储租户命名空间	高	使用共享向量存储，但未设置租户命名空间。
MCP-007	工具描述注入	中	工具描述可能绕过隔离。
MCP-008	凭据保管库租户范围控制	严重	凭据保管库存储令牌时未限定租户范围。
MCP-009	共享服务账户	高	所有租户的 API 调用共用单个 API 密钥。
MCP-010	断开连接时清理会话	中	未确定性地清理会话。
MCP-011	遥测租户标识符	低	遥测数据剥离了租户标识符。
MCP-012	本地绑定（127.0.0.1）	高	MCP 服务绑定到 0.0.0.0，而非 127.0.0.1。
MCP-013	文件系统租户根目录	高	工具处理程序访问文件系统时未使用租户根目录。
MCP-014	跨租户制品泄露	高	制品存储未添加租户前缀。
MCP-015	动态工具命名空间	中	注册工具时未使用租户命名空间。

MCP 规则映射到 OWASP MCP Top 10（2025）。完整映射请参阅 docs/OWASP-MAPPING.md。这些映射仅供参考，用于分类和报告。本扫描器不认证 OWASP 合规性。

架构

扫描器流水线分为六个阶段：

1. 解析器 — 使用 Babel AST 解析 TypeScript/JavaScript，使用 Prisma 架构解析器、SQL 迁移解析器，并检测 MCP SDK 导入
2. IR 和流程图 — 中间表示，用于捕获源、汇、保护条件、路由和 MCP 工具定义
3. 规则引擎 — 根据 IR 评估 57 条确定性规则。每条规则定义源、汇和必需的保护条件
4. 误报过滤器 — 测试文件检测、置信度评分、模式优化
5. 报告器 — 终端、JSON、SARIF 2.1.0、包含修复提示的 AI 友好型 JSON、Markdown
6. CLI 和 MCP 服务 — mti CLI，包含 scan/init/rules/suppress/baseline/mcp 命令。MCP 服务提供 4 个工具

结构化输出

扫描结果包含发现项之外的结构化元数据：

• 完整性 — COMPLETE、PARTIAL 或 ERROR。如果文件解析失败或规则评估失败，完整性会降至 PARTIAL，并列出原因。
• 覆盖情况 — 已发现、已解析、解析失败的文件数量；可用、已选中、已评估、评估失败、已触发的规则数量。还会统计不支持的文件类型。
• 问题类别 — 将发现项归入 8 个问题类别，便于分流（租户上下文、数据隔离、缓存和会话、MCP 安全、密钥和凭证、向量和存储、API 和访问、审计和日志记录）。
• 限制 — 扫描可以和无法验证的内容。始终包含静态分析的限制，并说明流分析范围和修复证明状态。
• 扫描凭据 — 来源元数据，包含引擎版本、规则包摘要、时间戳，以及用于篡改检测的 SHA-256 凭据哈希。
• 修复证明 — 根据基线文件，为每个发现项标记 STILL_PRESENT、NEW 或 NOT_VERIFIABLE。运行 mti baseline 建立基线。

指纹

发现项使用 v2 语义指纹，即使行位置和格式发生变化，指纹也保持稳定。指纹根据规则 ID、文件路径、规范化代码片段和排序后的缺失保护条件生成，不包含行号。这意味着，如果你在不改变代码语义的情况下调整代码位置，指纹仍会保持不变，基线跟踪也会继续准确。

MCP 服务

此软件包包含一个 MCP 服务，用于与 AI Agent 集成。它通过 stdio 传输在本地运行。无需托管，也不会暴露到网络。

{
  "mcpServers": {
    "tenant-isolation": {
      "command": "npx",
      "args": ["-y", "mcp-tenant-isolation", "mcp"]
    }
  }
}

将此配置添加到 Claude Desktop、Cursor、Windsurf 或其他 MCP 客户端的配置中，即可让 AI Agent 按需扫描代码中的租户隔离问题。

MCP 工具

工具	描述	是否写入？
scan_tenant_isolation	扫描项目路径。返回包含完整性、覆盖情况、问题类别和扫描凭据的结构化发现项。	否
list_tenant_isolation_rules	返回全部 57 条规则及其元数据。可按类别筛选。	否
explain_tenant_isolation_rule	返回规则详情、OWASP 映射、CWE ID 和修复建议。	否
suppress_tenant_isolation_finding	添加抑制项，并提供原因、审批人、控制措施和到期时间。	是（选择启用）

抑制工具默认隐藏。只有在使用 --allow-write-tools 启动服务时，它才会显示。这是一道安全边界：默认只读，写入操作需要明确选择启用。

MCP 扫描期间的所有文件系统操作都被限制在服务启动时配置的项目根目录内。遍历攻击（../）、根目录之外的绝对路径、UNC 路径和符号链接逃逸都会被拒绝。详情请参阅 SECURITY.md。

CI/CD 集成

选项 1：预构建的 GitHub Action（最简单）

将以下内容添加到 .github/workflows/tenant-isolation.yml：

name: Tenant Isolation Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: subodhkc/mcp-tenant-isolation@v2
        with:
          path: ./src
          severity: HIGH
          fail-on: HIGH

运行扫描，将 SARIF 上传到 GitHub Code Scanning，生成 Markdown 报告工件，并在检测到 HIGH 或 CRITICAL 发现项时使工作流失败。

选项 2：手动运行 npx

name: Tenant Isolation Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx mcp-tenant-isolation scan ./src --format sarif --output results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

退出代码

代码	含义
0	未发现问题
1	发现问题
2	错误（配置无效、解析失败等）

GitHub Code Scanning 集成

使用 github/codeql-action/upload-sarif@v3 上传 SARIF 输出后，发现项会显示在仓库的 Security > Code scanning alerts 标签页中。免费仓库和启用了 Advanced Security 的仓库均可使用此功能。

具体流程：

1. mti scan --format sarif --output results.sarif 会生成 SARIF 2.1.0 文件
2. upload-sarif 操作会将文件发送到 GitHub 的代码扫描 API
3. 每项发现都会成为代码扫描警报，其中包含文件、行号、严重程度和修复提示
4. 可直接在 GitHub 界面中忽略、修复或跟踪警报
5. 更改文件中会自动显示拉取请求注释

要求：

• 在工作流中设置 permissions: security-events: write
• 必须在上传步骤之前生成 SARIF 文件

配置

在项目根目录中创建 .mtirc.json：

{
  "rules": {
    "severity": {
      "DBQ-001": "HIGH",
      "MCP-001": "CRITICAL"
    },
    "exclude": ["DBQ-010"]
  },
  "paths": {
    "include": ["src/**/*"],
    "exclude": ["**/*.test.ts", "**/*.spec.ts"]
  },
  "suppressions": ".mti-suppressions.json",
  "baseline": ".mti-baseline.json"
}

高级配置

{
  "rules": {
    "severity": { "DBQ-001": "HIGH" },
    "exclude": ["DBQ-010"]
  },
  "paths": {
    "include": ["src/**/*"],
    "exclude": ["**/*.test.ts"]
  },
  "output": "terminal",
  "framework": "nextjs-app-router",
  "authHelpers": ["requireAuth", "getServerSession", "withAuth"],
  "tenantGuards": ["organizationId", "tenantId", "workspaceId"],
  "modelScopes": {
    "userScoped": ["User", "UserSession"],
    "global": ["Tenant", "AuditLog"]
  },
  "rulePacks": ["./custom-rules.json"],
  "suppressions": ".mti-suppressions.json",
  "baseline": ".mti-baseline.json"
}

字段	说明
output	默认输出格式：terminal、json、sarif、ai、markdown
framework	框架提示：nextjs-app-router、nextjs-pages、express、fastify、auto
authHelpers	要检测的自定义身份验证函数名称（减少误报）
tenantGuards	默认值之外的自定义租户保护变量名称
modelScopes	覆盖模型范围分类（userScoped、global、tenantScoped）
rulePacks	自定义规则包 JSON 文件的路径

自定义规则包

你可以通过 JSON 规则包扩展扫描器。自定义规则会在加载时进行验证：

• 规则 ID 必须符合 PREFIX-NNN 格式（例如，CUST-001）
• 规则 ID 不得与内置规则冲突
• 严重程度必须是 INFO、LOW、MEDIUM、HIGH、CRITICAL 之一
• 所有规则包中的自定义规则最多为 50 条
• 规则包路径必须位于项目根目录范围内（MCP 模式）

无效的自定义规则会被拒绝并显示警告。扫描会继续使用内置规则。

抑制项

抑制项必须包含具体发现项的指纹、规则 ID、有记录的审批人标识符、原因、补偿控制措施和到期日期。只有作为有记录的永久例外时，才允许使用规则级抑制项（不含指纹）。

documentedApprover 字段用于记录批准该抑制项的人。它不表示经过独立的人工验证。它是记录归属的字符串，并非声称经过外部审查。

基线

运行 mti baseline，为当前发现项创建快照。后续扫描会与基线进行比较，并将每项发现标记为 STILL_PRESENT、NEW 或 NOT_VERIFIABLE（如果不存在基线）。这样，你就可以跟踪修复情况随时间的变化。

报告格式

格式	标志	用途
终端	--format terminal（默认）	开发者控制台，显示通过／失败判定
JSON	--format json	供程序使用，或通过管道传递给其他工具
SARIF	--format sarif	GitHub Code Scanning、Azure DevOps
AI JSON	--format ai	供 AI Agent 使用，包含修复提示和上下文
Markdown	--format markdown	可分享的报告，适用于 PR、团队审查和文档

# Generate a Markdown report for a PR
mti scan ./src --format markdown --output TENANT-ISOLATION-REPORT.md

# Upload SARIF to GitHub Code Scanning
mti scan ./src --format sarif --output results.sarif

信任与供应链

• npm Trusted Publishing — 通过 GitHub Actions OIDC 发布软件包，而非使用长期有效的令牌。每次发布都会使用短期、特定于工作流的凭据。
• 来源证明证明 — 每个已发布的软件包都包含 Sigstore 透明日志中的签名来源证明声明。你可以验证软件包是否由本仓库中的确切源代码构建。
• 0 个 npm audit 漏洞 — 每次 CI 运行都会审计依赖项。锁文件已提交，CI 使用 npm ci 进行可复现安装。
• 确定性规则 — 不使用机器学习，也不进行概率评分。对于相同的源代码，扫描器每次都会生成相同的发现结果。
• 跨平台 CI — 在 Ubuntu、Windows 和 macOS 上使用 Node 22 和 24 进行测试。Node 26 Canary 运行仅提供参考信息。
• MIT 许可 — 免费且开源。无遥测、无回传、无数据收集。

局限性

静态分析本身存在局限。以下是对这些局限的坦诚说明：

• 仅进行过程内流程分析。 扫描器会追踪单个函数体内的数据流，不会追踪跨函数调用、文件或框架中间件边界的流程。大多数租户隔离缺陷都是接收点缺少防护的问题，无需过程间分析即可发现，但可能会遗漏某些边缘情况。
• 不进行运行时验证。 扫描器会检查源代码模式，无法验证数据库级 RLS 策略是否实际启用、中间件是否实际运行，或租户上下文是否在运行时实际传播。
• 仅支持 TypeScript 和 JavaScript。 暂不支持 Python、Go、Ruby 和其他语言。
• 可能出现误报。 扫描器使用基于模式的检测，并通过误报过滤（排除测试文件、检测认证信号、置信度评分）来减少误报。可通过 .mtirc.json 配置自定义认证辅助函数和租户防护，以减少误报。
• 仅支持 MCP stdio 传输。 MCP 服务通过 stdio 在本地运行。v2.0 不支持远程/HTTP 传输。

有关流程分析范围的详细信息，请参阅 docs/FLOW-ANALYSIS-QUALIFICATION.md。

技术栈

• AST 解析：@babel/parser（TypeScript、JSX）、Prisma 架构解析器、SQL 迁移解析器
• 规则引擎：RuleSpec 声明式模式，包含防护检测和证据构建
• CLI：Commander
• MCP：@modelcontextprotocol/server v2（stdio 传输、Zod 架构、结构化输出）
• 输出：终端、JSON、SARIF 2.1.0、AI JSON、Markdown
• 测试：Vitest（203 项测试，在 Ubuntu、Windows、macOS 上进行跨平台 CI）

路线图

v2.0.0（当前）

• 57 条规则（42 条通用规则 + 15 条 MCP 专用规则）
• 支持 TypeScript 和 JavaScript
• Prisma 架构分析
• SQL 迁移分析（RLS、租户列、索引）
• CLI，支持终端、JSON、SARIF、AI JSON、Markdown 输出
• MCP 服务 v2 SDK（stdio 传输、Zod 架构、结构化输出）
• 结构化 MCP 输出，包含完整性、覆盖范围和问题类别
• 扫描回执，包含规则包摘要和防篡改哈希
• 证据封套，用于可验证的扫描产物
• 稳定的 v2 语义指纹（不受行移动影响）
• OWASP MCP Top 10 映射（官方 2025 类别）
• 路径边界强制执行（路径遍历、符号链接、UNC、Windows 8.3）
• 写入工具门控（默认只读，可选择启用抑制）
• 抑制策略，包含到期时间和记录在案的审批人
• 基线跟踪，包含修复证明状态
• 在 .mtirc.json 中覆盖严重性
• 带验证功能的自定义规则包
• 可配置的认证辅助函数和租户防护
• 使用配置覆盖对模型范围进行分类
• 框架检测（Next.js、Express、Fastify）
• 跨平台 CI 矩阵（Node 22/24、Ubuntu/Windows/macOS）

未来

• 支持 Python（FastAPI、Django、Flask）
• SQLAlchemy ORM 分析
• 监视模式（mti scan --watch）
• VS Code 扩展
• 运行时双租户对抗测试工具
• 支持 Go 和 Ruby 语言
• 使用 AST 缓存进行增量扫描

链接

• 主页
• GitHub
• npm
• Docker Hub
• 更新日志
• 贡献指南
• 安全策略
• HAIEC（Human AI Evidence Company）— AI 安全验证与审计证据平台
• Subodh Kc — 构建者

许可证

MIT。免费且开源。