Aguara

针对 AI agent 技能和 MCP server 的安全扫描器。
在 prompt 注入、数据泄露和供应链攻击进入生产环境之前将其检测出来。

安装 • 快速开始 • 工作原理 • 用法 • 规则 • Aguara MCP • Aguara Watch • 贡献

https://github.com/user-attachments/assets/851333be-048f-48fa-aaf3-f8cc1d4aa594 ## 为什么选择 Aguara？ AI agent 和 MCP server 代表你执行代码。单个恶意技能文件就可能泄露凭证、注入 prompt 或安装后门。Aguara 通过静态分析在**部署前**捕获这些威胁，无需 API 密钥，无需云服务，也无需 LLM。 - **涵盖 13 个类别的 177 条检测规则** —— 包括 prompt 注入、数据泄露、凭证泄漏、供应链攻击、MCP 特定威胁、命令执行、SSRF、unicode 攻击等。 - **4 层分析引擎** —— 模式匹配、基于 NLP 的 markdown 分析、污点追踪和“抽地毯式 (rug-pull)”检测协同工作，捕获任何单一技术可能遗漏的威胁。 - **置信度评分** —— 每个发现都带有置信度 (0.0-1.0)，便于你确定优先级并过滤干扰信息。 - **修复指导** —— 高影响规则在扫描输出中包含可操作的修复建议。 - **确定性** —— 输入相同，输出相同。每次扫描均可复现。 - **适配 CI** —— 支持 JSON、SARIF 和 Markdown 输出。提供 GitHub Action。支持 `--fail-on` 阈值。支持 `--changed` 增量扫描。 - **支持 17 个 MCP 客户端** —— 自动发现并扫描来自 Claude Desktop、Cursor、VS Code、Windsurf 等 13 个以上的客户端配置。 - **可扩展** —— 用 YAML 编写自定义规则。无需编写代码。 ## 安装 ``` curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | bash ``` 将最新的二进制文件安装到 `~/.local/bin`。使用环境变量自定义： ``` VERSION=v0.5.0 curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | bash INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | bash ``` ### 其他安装方法 **Homebrew** (macOS/Linux): ``` brew install garagon/tap/aguara ``` **Docker** (无需安装): ``` # 扫描当前目录 docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan # 使用选项扫描 docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan --severity high --format json # 使用特定版本 docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara:v0.5.0 scan /scan ``` **从源码构建** (需要 Go 1.25+): ``` go install github.com/garagon/aguara/cmd/aguara@latest ``` Linux、macOS 和 Windows 的预构建二进制文件也可在 [Releases 页面](https://github.com/garagon/aguara/releases)获取。 ## 快速开始 ``` # 自动发现并扫描机器上的所有 MCP 配置 aguara scan --auto # 发现已配置的 MCP 客户端（不扫描） aguara discover # 扫描 skills 目录 aguara scan .claude/skills/ # 扫描单个文件 aguara scan .claude/skills/deploy/SKILL.md # 仅显示高和严重发现 aguara scan . --severity high # CI 模式（高等级以上退出代码为 1，无颜色） aguara scan .claude/skills/ --ci # 详细模式（显示描述、置信度分数、修复建议） aguara scan . --verbose ``` ## 工作原理 Aguara 对每个文件依次运行 4 个分析层。每一层捕获不同的攻击模式： | Layer | Engine | What it catches | |-------|--------|-----------------| | **Pattern Matcher** | Regex + contains matching | 已知攻击签名、凭证模式、危险命令。解码 base64/hex 数据块并重新扫描。降低 markdown 代码块内匹配项的严重性。 | | **NLP Analyzer** | Goldmark AST walker | markdown 结构中的 prompt 注入 —— 通过对标题、段落和列表项的关键词分类，检测指令覆盖、角色切换和越狱。 | | **Taint Tracker** | Source-to-sink flow analysis | 危险的能力组合：读取私有数据 + 写入外部 URL、环境变量流入 shell 执行、API 响应通过管道传输到 eval。 | | **Rug-Pull Detector** | SHA256 hash tracking | 扫描之间发生变化的工具描述 —— 捕获在初始审查后修改其行为的 MCP server。需要 `--monitor` 标志。 | 所有层报告的发现均包含严重性、置信度分数、匹配文本、带有上下文行的文件位置，以及可用时的修复指导。 ## 用法 ``` aguara scan [path] [flags] Flags: --auto Auto-discover and scan all MCP client configs --severity string Minimum severity to report: critical, high, medium, low, info (default "info") --format string Output format: terminal, json, sarif, markdown (default "terminal") -o, --output string Output file path (default: stdout) --workers int Number of worker goroutines (default: NumCPU) --rules string Additional rules directory --disable-rule strings Rule IDs to disable (comma-separated, repeatable) --max-file-size string Maximum file size to scan (e.g. 50MB, 100MB; default 50MB, range 1MB-500MB) --no-color Disable colored output --no-update-check Disable automatic update check (also: AGUARA_NO_UPDATE_CHECK=1) --fail-on string Exit code 1 if findings at or above this severity --ci CI mode: --fail-on high --no-color --changed Only scan git-changed files --monitor Enable rug-pull detection: track file hashes across runs -v, --verbose Show rule descriptions, confidence scores, and remediation -h, --help Help ``` ### 输出格式 | Format | Flag | Use case | |--------|------|----------| | **Terminal** | `--format terminal` (default) | 人类可读，带颜色、严重性仪表盘、热门文件图表 | | **JSON** | `--format json` | 机器处理、API 集成、自定义工具 | | **SARIF** | `--format sarif` | GitHub Code Scanning、IDE 集成、SAST 仪表盘 | | **Markdown** | `--format markdown` | GitHub Actions 任务摘要、PR 评论 | ### MCP 客户端发现 Aguara 跨 **17 个客户端**自动检测 MCP 配置：Claude Desktop、Cursor、VS Code、Cline、Windsurf、OpenClaw、OpenCode、Zed、Amp、Gemini CLI、Copilot CLI、Amazon Q、Claude Code、Roo Code、Kilo Code、BoltAI 和 JetBrains。 ``` # 列出所有检测到的 MCP 配置 aguara discover # JSON 输出 aguara discover --format json # 一键发现 + 扫描 aguara scan --auto ``` ### CI 集成 #### GitHub Action ``` - uses: garagon/aguara@v1 ``` 扫描你的代码仓库，将发现上传到 GitHub Code Scanning，并可选择使构建失败： ``` - uses: garagon/aguara@v1 with: path: ./mcp-server/ severity: medium fail-on: high ``` 所有输入都是可选的。完整列表请参见 [`action.yml`](action.yml)。 | Input | Default | Description | |-------|---------|-------------| | `path` | `./` | 要扫描的路径 | | `severity` | `info` | 报告的最低严重性 | | `fail-on` | _(none)_ | 如果达到或超过此严重性则失败 | | `format` | `sarif` | 输出格式：sarif, json, terminal, markdown | | `upload-sarif` | `true` | 上传 SARIF 到 GitHub Code Scanning | | `version` | _(latest)_ | 指定固定的 Aguara 版本 | #### 在 CI 中使用 Docker ``` # GitHub Actions 与 Docker（无需安装步骤） - name: Scan for security issues run: docker run --rm -v "${{ github.workspace }}":/scan ghcr.io/garagon/aguara scan /scan --ci ``` #### 手动 / GitLab CI ``` # GitHub Actions（不使用 action） - name: Scan skills for security issues run: | curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | bash aguara scan .claude/skills/ --ci ``` ``` # GitLab CI security-scan: script: - curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | bash - aguara scan .claude/skills/ --format sarif -o gl-sast-report.sarif --fail-on high artifacts: reports: sast: gl-sast-report.sarif ``` ### 配置 在你的项目根目录创建 `.aguara.yml`： ``` severity: medium fail_on: high max_file_size: 104857600 # 100 MB (default: 50 MB, range: 1 MB-500 MB) ignore: - "vendor/**" - "node_modules/**" rule_overrides: CRED_004: severity: low EXTDL_004: disabled: true ``` ### 行内忽略 使用行内注释直接在源文件中抑制特定发现： ``` # aguara-ignore CRED_004 api_key: "sk-test-1234567890" # this finding is suppressed ``` ``` Ignore all previous instructions (this is a test) ``` 支持的指令： | Directive | Effect | |-----------|--------| | `# aguara-ignore RULE_ID` | 抑制同一行的规则 | | `# aguara-ignore RULE_ID, RULE_ID2` | 抑制同一行的多个规则 | | `# aguara-ignore-next-line RULE_ID` | 抑制下一行的规则 | | `# aguara-ignore` | 抑制同一行的所有规则 | | `` | HTML/Markdown 注释变体 | | `// aguara-ignore RULE_ID` | C 风格注释变体 | ## 规则 13 个类别中的 177 条内置规则： | Category | Rules | What it detects | |----------|-------|-----------------| | Credential Leak | 22 | API 密钥 (OpenAI, AWS, GCP, Stripe, ...)、私钥、数据库连接字符串、HMAC 密钥 | | Prompt Injection | 18 + NLP | 指令覆盖、角色切换、分隔符注入、越狱、事件注入 | | Supply Chain | 21 | 下载并执行、反向 shell、沙箱逃逸、符号链接攻击、权限提升 | | External Download | 16 | 二进制文件下载、curl 管道传输 shell、自动安装、配置文件持久化 | | MCP Attack | 16 | 工具注入、名称遮蔽、规范化绕过、权限升级 | | Data Exfiltration | 16 + NLP | Webhook 泄露、DNS 隧道、敏感文件读取、环境变量泄露 | | Command Execution | 15 | shell=True, eval, subprocess, child_process, PowerShell | | MCP Config | 11 | 未固定的 npx server、硬编码密钥、Docker cap-add、主机网络 | | Indirect Injection | 11 | 获取并执行、远程配置、数据库驱动的指令、Webhook 注册 | | SSRF & Cloud | 11 | 云元数据、IMDS、Docker socket、内部 IP、重定向跟随 | | Third-Party Content | 10 | 使用外部数据的 eval、不安全的反序列化、缺少 SRI、HTTP 降级 | | Unicode Attack | 10 | RTL 覆盖、bidi、同形异义字、零宽序列、规范化绕过 | | Toxic Flow | 3 | 用户输入进入危险 sink、环境变量进入 shell、API 响应进入 eval | 完整的规则目录（包含 ID 和严重性级别）请参见 [RULES.md](RULES.md)。 ### 修复指导 高影响规则在其发现中包含修复文本： ``` { "rule_id": "PROMPT_INJECTION_001", "severity": 4, "matched_text": "Ignore all previous instructions", "remediation": "Remove instruction override text. If this is documentation, wrap it in a code block to indicate it is an example.", "confidence": 0.85 } ``` 在终端输出中使用 `--verbose` 或使用 `--format json` 查看修复指导。 ### 自定义规则 ``` id: CUSTOM_001 name: "Internal API endpoint" description: "Detects references to internal APIs" severity: HIGH category: custom targets: ["*.md", "*.txt"] match_mode: any remediation: "Replace internal API URLs with the public endpoint or environment variable." patterns: - type: regex value: "https?://internal\\.mycompany\\.com" - type: contains value: "api.internal" exclude_patterns: # optional: suppress match in these contexts - type: contains value: "## documentation" examples: true_positive: - "Fetch data from https://internal.mycompany.com/api/users" false_positive: - "Our public API is at https://api.mycompany.com" ``` 当匹配的行（或其前最多 3 行）匹配任何排除模式时，`exclude_patterns` 会抑制该匹配。这对于减少文档标题、安装指南等中的误报非常有用。 ``` aguara scan .claude/skills/ --rules ./my-rules/ ``` ## Aguara MCP [Aguara MCP](https://github.com/garagon/aguara-mcp) 是一个 MCP server，它赋予 AI agent 在安装或运行技能和配置之前扫描其安全威胁的能力。它将 Aguara 作为 Go 库导入 —— 只需一次 `go install`，无需外部二进制文件。 ``` # 安装并注册 Claude Code go install github.com/garagon/aguara-mcp@latest claude mcp add aguara -- aguara-mcp ``` 你的 agent 将获得 4 个工具：`scan_content`、`check_mcp_config`、`list_rules` 和 `explain_rule`。无网络，无 LLM，毫秒级扫描 —— agent 先检查，再决定。 ## Aguara Watch [Aguara Watch](https://watch.aguarascan.com/) 持续扫描 5 个公共注册表中 **28,000 多个 AI agent 技能**，以追踪 AI agent 在现实世界中的威胁态势。所有扫描均由 Aguara 驱动。 ## Go 库 Aguara 暴露了一个公共 Go API，用于将扫描器嵌入到其他工具中。[Aguara MCP](https://github.com/garagon/aguara-mcp) 就使用了此 API。 ``` import "github.com/garagon/aguara" // Scan a directory result, err := aguara.Scan(ctx, "./skills/") // Scan inline content (no disk I/O) result, err := aguara.ScanContent(ctx, content, "skill.md") // Discover all MCP client configs on the machine discovered, err := aguara.Discover() for _, client := range discovered.Clients { fmt.Printf("%s: %d servers\n", client.Client, len(client.Servers)) } // List rules, optionally filtered rules := aguara.ListRules(aguara.WithCategory("prompt-injection")) // Get rule details with remediation detail, err := aguara.ExplainRule("PROMPT_INJECTION_001") fmt.Println(detail.Remediation) ``` 选项：`WithMinSeverity()`、`WithDisabledRules()`、`WithCustomRules()`、`WithRuleOverrides()`、`WithWorkers()`、`WithIgnorePatterns()`、`WithMaxFileSize()`、`WithCategory()`。 ## 架构 ``` aguara.go Public API: Scan, ScanContent, Discover, ListRules, ExplainRule options.go Functional options for the public API discover/ MCP client discovery: 17 clients, config parsers, auto-detection cmd/aguara/ CLI entry point (Cobra) internal/ engine/ pattern/ Layer 1: regex/contains matcher + base64/hex decoder + code block awareness nlp/ Layer 2: goldmark AST walker, keyword classifier, injection detector toxicflow/ Layer 3: taint tracking — source-to-sink flow analysis rugpull/ Layer 4: rug-pull detection — SHA256-based tool description change tracking rules/ Rule engine: YAML loader, compiler, self-tester builtin/ 177 embedded rules across 12 YAML files (go:embed) scanner/ Orchestrator: file discovery, parallel analysis, inline ignore, result aggregation meta/ Post-processing: dedup, scoring, correlation, confidence adjustment output/ Formatters: terminal (ANSI), JSON, SARIF, Markdown config/ .aguara.yml loader state/ Persistence for incremental scanning and rug-pull detection types/ Shared types (Finding, Severity, ScanResult) ``` ## 对比 Aguara 是专为 AI agent 内容构建的。通用 SAST 工具针对的是应用程序源代码，而不是 agent 消费的技能文件、工具描述和 MCP 配置。 | Feature | Aguara | Semgrep | Snyk Code | CodeQL | |---------|--------|---------|-----------|--------| | AI agent 技能扫描 | Yes | No | No | No | | MCP 配置分析 | Yes | No | No | No | | Prompt 注入检测 | Yes (18 rules + NLP) | No | No | No | | Rug-pull 检测 | Yes | No | No | No | | 针对技能的污点追踪 | Yes | Yes | Yes | Yes | | 离线 / 无需账户 | Yes | Partial | No | Partial | | 自定义 YAML 规则 | Yes | Yes | No | No | | SARIF 输出 | Yes | Yes | Yes | Yes | | 免费且开源 | Yes (Apache 2.0) | Partial | No | Partial | Aguara 是对传统 SAST 的补充 —— 使用 Semgrep 扫描你的应用代码，使用 Aguara 扫描你的 agent 技能和 MCP server。 ## 贡献 欢迎做出贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发设置、添加规则和 PR 流程。 关于安全漏洞，请参阅 [SECURITY.md](SECURITY.md)。 ## 许可证 [Apache License 2.0](LICENSE)

标签：AI基础设施, AI安全, Chat Copilot, DevSecOps, DNS 反向解析, EVTX分析, Go, GraphQL安全矩阵, Homebrew安装, L7防御, LNA, MCP, MCP服务器, Oktsec, Ruby工具, SAST, 上游代理, 二进制文件, 供应链攻击, 安全扫描器, 数据渗出, 文档安全, 日志审计, 智能体安全, 模型上下文协议, 盲注攻击, 网络安全, 请求拦截, 错误基检测, 防御加固, 隐私保护, 静态代码分析