TrustMCP——用于JavaScript和TypeScript的MCP服务器安全扫描器

CLI和GitHub Action用于对模型上下文协议（MCP）服务器存储库进行静态安全扫描。

TrustMCP是一个用于JavaScript和TypeScript存储库的MCP服务器安全扫描器。它既可以作为CLI，也可以作为GitHub Action，在本地运行未知代码或将其连接到CI之前，它会标记有风险的MCP服务器功能。

如果 npm audit 是把你带到这里的心理模型，保持比较的具体性：TrustMCP扫描源代码以寻找有风险的MCP服务器功能，而不是依赖CVE。与沙盒不同，它确实不执行服务器。

如果你想要更全面的比较，请查看 .

发布历史：更改日志.md

当前状态

npm安装今天可以使用(npm install -g trustmcp, npx trustmcp --version)
源代码安装仍然适用于贡献者(npm install && npm run build)
GitHub Actions CI在Node 18和20上运行
存在包装准备检查： npm run pack:check, npm run pack:smoke，以及 npm run publish:check
GitHub发布流程存在并保持手动
npm发布已上线： trustmcp@0.1.0

安装和释放准备就绪

TrustMCP现在可以在npm上使用， npx，以及源代码检查/本地构建。

使用立即安装TrustMCP 对于当前支持的安装路径：npm， npx，直接 node dist/cli/main.js ...，可选 npm link.
使用 npm run pack:check 在本地验证未来的npm tarball内容。
使用 npm run publish:check 在一个命令中运行本地release/package preflight。
使用和贡献.md 用于未来的软件包更新和GitHub手动发布步骤。

为什么扫描MCP服务器

MCP服务器越来越容易发现，也越来越容易连接到本地工具。信任审查仍然主要是手动的，因此TrustMCP专注于可信的第一步：扫描代码，指出具体证据，并解释为什么它很重要。

TrustMCP有意保持小规模：

一个本地CLI
一个可重用的GitHub操作
仅限静态启发式
公共GitHub仓库根URL或本地文件夹
三条有证据支持的规则

确实如此不声称目标是安全的。

常见用例

在本地使用之前检查第三方MCP服务器
在CI中打开自己的MCP服务器存储库
导出JSON、Markdown或SARIF以实现自动化、工件和代码扫描

TrustMCP扫描什么

关于简短的答案、范围和非目标，请查看 .

有关逐个规则的解释程序，请查看 TrustMCP规则解释.

mcp/shell-exec
mcp/outbound-fetch
mcp/broad-filesystem

如果要从CLI获取当前ID，请运行 node dist/cli/main.js list-rules.

对于自动化友好的规则元数据，请运行 node dist/cli/main.js list-rules --json.

如果要将附带的规则元数据持久化到文件中，请运行：

node dist/cli/main.js list-rules --json --output-file rules.json

如果你想要一个复制粘贴自动化路径，例如在shell脚本中：

node dist/cli/main.js doctor gh:modelcontextprotocol/servers --json | jq '.ok'
node dist/cli/main.js list-rules --json | jq '.[].ruleId'

每一项发现都包括：

ruleId
severity
confidence
title
file
line 如果可用
evidence
whyItMatters
remediation

快速开始

需要Node.js 18.18+。

TrustMCP在npm上发布为 trustmcp.如果你想要最小的摩擦路径，请使用npm或 npx。当您想在本地贡献或检查存储库时，源代码签出仍然是正确的路径。

全局安装：

npm install -g trustmcp

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

npx trustmcp --version

如果你想在一个地方解释安装选项，请查看立即安装TrustMCP.

从源代码安装并构建：

npm install
npm run build

如果您希望在一个命令中使用相同的基于源代码的设置，请运行：

npm run bootstrap

在本地验证包装好的皮球内容物：

npm run pack:check

在本地文件夹上运行：

node dist/cli/main.js ./fixtures/local-risky

在公共GitHub存储库上运行：

node dist/cli/main.js gh:modelcontextprotocol/servers --format text

可选：链接本地CLI命令以供重复使用：

npm link
trustmcp ./fixtures/local-risky

CLI使用情况

在本地文件夹上运行

node dist/cli/main.js ./fixtures/local-risky

在公共GitHub存储库上运行

node dist/cli/main.js https://github.com/modelcontextprotocol/servers --format text

或者使用明确的GitHub简写：

node dist/cli/main.js gh:modelcontextprotocol/servers --format text

GitHub扫描接受 仅限存储库根输入：要么 https://github.com/owner/repo 或 gh:owner/repo.尾随斜线， .git，并且仓库根查询片段针对完整URL进行了规范化。已复制 tree/..., blob/...，其他GitHub子路径URL将被拒绝，并提示使用存储库根URL。无效的速记失败 gh:/ 引导而不是陷入局部路径处理。

输出格式

为CI或其他工具发送JSON：

node dist/cli/main.js ./fixtures/local-risky --format json

为公关评论或工作总结发送紧凑的降价：

node dist/cli/main.js gh:modelcontextprotocol/servers --format markdown

发出SARIF以进行代码扫描或安全工作流接收：

node dist/cli/main.js gh:modelcontextprotocol/servers --format sarif --output-file trustmcp.sarif

将所选格式写入文件，同时仍将其打印到stdout：

node dist/cli/main.js gh:modelcontextprotocol/servers --format markdown --output-file trustmcp-report.md

仅发送终端或CI状态检查的简明摘要：

node dist/cli/main.js gh:modelcontextprotocol/servers --summary-only --fail-on high

配置文件

从显式JSON配置文件中重用稳定的CLI默认值：

{
  "format": "markdown",
  "fail-on": "high",
  "summary-only": true,
  "output-file": "reports/trustmcp.md",
  "baseline-file": "trustmcp.baseline.json"
}

node dist/cli/main.js gh:modelcontextprotocol/servers --config trustmcp.config.json

在不覆盖现有配置文件的情况下生成启动器配置文件：

node dist/cli/main.js init-config

在第一次真正扫描之前验证目标和可选配置：

node dist/cli/main.js doctor gh:modelcontextprotocol/servers --config trustmcp.config.json

将飞行前的结果以JSON格式发送以实现自动化：

node dist/cli/main.js doctor gh:modelcontextprotocol/servers --json

当你经过时 --config, doctor 还检查加载的配置 output-file 在真正的扫描开始之前，路径和捕获丢失的父目录。

配置文件选项

trustmcp.config.json 是一个平面JSON对象，它反映了可以用以下方式设置的每个CLI标志 --config （以及下面描述的两个新辅助字段）。支持的字段包括：

format：其中之一 text, json, markdown，或 sarif.
fail-on：严重程度(low, medium, high)CLI退出代码。
summary-only：一个布尔值，将控制台输出限制为紧凑摘要块。
output-file：除了stdout之外，还写入渲染报告的文件路径。
ignore-rules：一组精确的规则ID(mcp/shell-exec, mcp/outbound-fetch等等）。任何发现 ruleId matches从最终报告中删除了其中一个条目，但启发式仍然在内部运行，因此只使用它来消除您检查过的已知噪音。
ignore-paths：受审核目标内斜线分隔的相对路径（文件或目录）数组。如果发现 file 路径从配置的字符串之一开始，CLI摘要输出和结构化报告中省略了该查找。不支持globbing或正则表达式；条目按字面匹配，区分大小写。
baseline-file：一个包含以前接受的查找元组的JSON文件(ruleId, file，可选 line).提供时，TrustMCP仍会报告完整的查找列表以供查看，但 --fail-on 仅评估基线中不存在的发现。
baseline-output：TrustMCP将当前查找元组作为可重用的基线JSON写入的文件路径。这是以后明确的“接受当前发现”路径 baseline-file 跑。

两者 ignore-rules 和 ignore-paths 当您已经信任其他发现并且确信被忽略的行代表可接受的风险时，最好将其保留用于短期噪声门控。它们不会改变规则评估本身；它们仅抑制所发出的摘要和报告输出中的匹配结果。

baseline-file 解决了一个不同的采用问题：它允许现有的存储库保持历史发现可见，而只对新引入的发现进行CI失败。在TrustMCP用于报告输出的相同路径规范化之后，基线匹配是精确和字面的。在第一个切片中没有全局搜索、正则表达式匹配或自动基线更新流。

如果你想从实际扫描中创建基线文件，而不是手工写入，请运行：

node dist/cli/main.js ./fixtures/local-risky --baseline-output trustmcp.baseline.json

它还会提前标记无效的配置组合，例如 summary-only: true 随着 format: sarif.

Doctor还验证了当前的Node.js运行时是否满足TrustMCP支持的引擎层。

如果扫描开始前出现故障，请检查 TrustMCP故障排除.

列出当前发布的TrustMCP规则：

node dist/cli/main.js list-rules

直接采购装运的壳体完井件，以供本地重复使用：

source completions/trustmcp.sh
source completions/trustmcp.zsh

JSON报告包括 summary.severityCounts.low, summary.severityCounts.medium，以及 summary.severityCounts.high 因此CI消费者可以读取稳定的严重性总计，而无需重新计算查找列表。

CI退出代码

当发现达到或超过严重性阈值时，CI作业失败：

node dist/cli/main.js https://github.com/modelcontextprotocol/servers --format json --fail-on high

--fail-on low 没有任何发现， --fail-on medium 中等或高发现失败，以及 --fail-on high 仅在高发现上失败。阈值与退出代码匹配 2；TrustMCP运行时或参数错误随代码退出 1.

在GitHub操作中使用TrustMCP

TrustMCP现在在存储库根目录下提供了一个可重用的复合操作。对于可粘贴复制的工作流，请从以下内容开始对于已检出的工作空间案例，对于明确的公共GitHub目标，为了保留所呈现的降价报告，对于保留的JSON报告，对于保留的SARIF文件，或 GitHub代码扫描上传路径。

最小外部使用量如下：

jobs:
  trustmcp:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: trustmcp
        uses: Gujiassh/trustmcp@v0.1.0
        with:
          target: ${{ github.workspace }}
          format: json
          fail-on: high
      - run: |
          echo "findings=${{ steps.trustmcp.outputs.finding-count }}"
          echo "high=${{ steps.trustmcp.outputs.high-count }}"

该操作在每次运行时从自己的源代码树构建TrustMCP，然后扫描您传入的签出目标路径或公共GitHub URL。它不依赖于已发布的npm包或市场包装器。上面的示例使用当前稳定标签 v0.1.0；如果您需要更严格的供应链固定，请使用特定的提交SHA。

可重用操作公开 finding-count, low-count, medium-count，以及 high-count 从CLI以JSON格式发出的同一报告摘要中导出的输出。

当 GITHUB_STEP_SUMMARY 如果可用，可重用的操作还会自动将紧凑的TrustMCP markdown报告附加到那里，以便更容易地进行作业审查。

要在GitHub Actions中重用CLI默认值，请传递以下命令 config-file 输入指向您的 trustmcp.config.json。该操作解决了相对路径 ${{ github.workspace }} 在建造之前，所以 config-file: trustmcp.config.json 只需重用您在CLI中使用的相同配置文件，并尊重相同的配置文件 format, fail-on, ignore-rules, ignore-paths, baseline-file, baseline-output，以及 summary-only 设置。专注的 summary-only, baseline-file，以及 baseline-output 输入还允许工作流显式覆盖这些值； summary-only 默认情况下保持为空，因此配置文件可以继续驱动该值。该行动强制执行相同的操作 summary-only + format: sarif 由于CLI的限制，共享配置在本地和CI运行之间的行为是相同的。

如果以后的工作流步骤需要具体的报告文件，请设置 output-file例如 output-file: reports/trustmcp.md。相对路径是从已签出的工作区解析的，父目录必须已经存在。

真实扫描示例

在固定裁判 eed21856dcf0defa23394909e27125311fed246f，TrustMCP报告了以下内容 microsoft/playwright-mcp:

Target: microsoft/playwright-mcp
Ref: main@eed21856dcf0defa23394909e27125311fed246f
Summary: 4 finding(s) across 1 rule(s). Static heuristics only.

[HIGH][HIGH] Shell execution capability detected
Rule: mcp/shell-exec
Location: packages/playwright-mcp/update-readme.js:149
Evidence: execSync('node cli.js --help > help.txt');

这是一个时间点启发式能力匹配，而不是对项目的全面判断。在这种情况下，TrustMCP在存储库脚本和维护路径中匹配了shell执行，这正是该工具在深入审查之前要展示的功能表面。

对于一个平衡的无比赛示例，在固定参考 b1575edfefde09e3cf7c805aea79a92131271659，TrustMCP报告了以下内容 github/github-mcp-server:

Target: github/github-mcp-server
Ref: main@b1575edfefde09e3cf7c805aea79a92131271659
Summary: No matching rules were triggered. Static heuristics only; this does not mean the target is safe.

这也是一个时间点的结果，而不是一个全面的安全判断。这意味着当前的TrustMCP规则与固定提交时的shell执行、出站获取或广泛的文件系统模式不匹配。

运行包含的检查：

npm test
npm run build
npm run smoke

输出示例

TrustMCP v0.1.0
Target: /absolute/path/to/local-risky
Source: local-directory
Summary: 3 finding(s) across 3 rule(s). Static heuristics only.

[HIGH][HIGH] Shell execution capability detected
Rule: mcp/shell-exec
Location: src/shell.ts:4
Evidence: exec(args.command);
Why it matters: Shell execution can turn tool input into arbitrary host commands.
Remediation: Prefer fixed command allowlists, avoid shell string interpolation, and require explicit operator approval for host command execution.

当没有规则匹配时，TrustMCP会说：

No matching rules were triggered.

这条信息故意狭隘。它是不安全判决。

限制和非目标

TrustMCP对范围诚实：

仅限静态启发式
仅限JavaScript和TypeScript存储库
无运行时沙盒
不支持私有回购
GitHub输入是小型公共存储库的最佳选择
GitHub输入仅支持存储库根URL；树/blob/子路径URL被拒绝，而不是被模糊地扫描
无身份验证流
没有web UI、注册表或托管服务
不能保证目标是安全的或完全覆盖所有MCP风险

这个第一个版本是为60秒的演示和实用的第一次通过而设计的，而不是全面的安全审查。

贡献路径

最简单的贡献方式是添加一个夹具，添加或收紧一个规则，并保持输出契约的稳定。结账贡献.md 对于本地工作流。

安全报告

如果您发现TrustMCP本身存在错误，请按照以下步骤操作安全.md.

trustmcp (Gujiassh)

快速接入

详细介绍