aguara (Garagon)

Aguara

Security scanner for AI agent skills and MCP servers.

Detect prompt injection, data exfiltration, and supply-chain attacks before they reach production.

Installation • Quick Start • How It Works • Usage • Rules • Supply-Chain Check • Aguara MCP • Aguara Watch • Contributing

https://github.com/user-attachments/assets/851333be-048f-48fa-aaf3-f8cc1d4aa594

为什么是阿瓜拉？

AI代理和MCP服务器代表您运行代码。一个恶意技能文件可以泄露凭据、注入提示或安装后门。阿瓜拉抓住了这些威胁 部署前 静态分析不需要API键，不需要云，也不需要LLM。

• 13个类别的193条检测规则 --即时注入、数据泄露、凭证泄漏、供应链攻击、MCP特定威胁、命令执行、SSRF、unicode攻击等。
• 7台扫描分析仪 --模式匹配、GitHub Actions信任链检测（ci-trust）、npm包元数据（pkgmeta）、JavaScript有效负载风险（jsrisk）、NLP分析、污染跟踪和地毯拉取检测协同工作，以捕捉任何单一技术都会错过的威胁 aguara check / aguara audit 命令根据嵌入式威胁英特尔快照标记已安装的包树（手动紧急咨询+OSV恶意包记录，自动检测npm与Python，默认离线）。
• 8个解码器用于编码规避 --base64、十六进制、URL编码、Unicode转义、HTML实体、十六进制转义、base32和C风格八进制转义。混淆的有效载荷会自动解码和重新扫描。
• markdown、JSON和YAML上的NLP --goldmark AST分析markdown文件，以及JSON/YAML工具描述的字符串提取和分类。在结构化配置中捕获MCP工具中毒。
• 跨文件有毒流分析 --检测跨同一MCP服务器目录中的文件拆分的危险功能组合（例如，一个工具读取凭据，另一个工具发送到webhook）。
• 总风险评分 --0-100分，各发现的回报递减。提供JSON、SARIF和终端输出。
• 上下文感知扫描 --传递工具名称(--tool-name Edit)扫描仪会自动跳过该工具总是误报的规则。内置编辑、写入、WebFetch、Bash等豁免。
• 扫描配置文件 — strict （默认）， content-aware，或 minimal 执行。调查结果始终保留以供审计；只有判决（干净/标志/阻止）发生了变化。
• 规避预防 --NFKC规范化捕获全宽字符规避。8个解码器捕获编码的有效载荷。加密地址过滤可防止十六进制解码器误报。
• 动态信心评分 --每个发现都有一个反映信号质量的置信水平（0.50-0.95）：模式命中率、分类器得分和码块感知。
• 补救指导 --所有193条规则都包括可操作的修复建议，以每种输出格式显示。
• 确定性的 --相同的输入，相同的输出。每次扫描都是可重复的。
• CI就绪 --JSON、SARIF和Markdown输出。GitHub行动。 --fail-on 门槛。 --changed 用于增量扫描。
• 支持17个MCP客户端 --从Claude Desktop、Cursor、VS Code、Windsurf等13个应用程序中自动发现和扫描配置。
• 用于嵌入的库API — WithDeduplicateMode() 保留判决管道的所有交叉规则发现。 WithStateDir() 为长期消费者提供地毯拉扯检测。
• 可扩展 --用YAML编写自定义规则。无需代码。

安装

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

将最新二进制文件安装到 ~/.local/bin.使用环境变量进行自定义：

curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | VERSION=v0.16.1 sh
curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | INSTALL_DIR=/usr/local/bin sh

要更新现有安装，请重新运行安装程序。它下载所选的版本存档，验证 checksums.txt，并替换二进制：

# Update to latest
curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | sh

# Update/pin to a specific release
curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | VERSION=v0.16.1 sh

替代方法

家酿 （macOS/Linux）：

brew install garagon/tap/aguara

码头工人 （无需安装）：

# Scan current directory
docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan

# Scan with options
docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan --severity high --format json

# Use a specific version
docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara:0.16.1 scan /scan

来源 （要求Go 1.25+）：

go install github.com/garagon/aguara/cmd/aguara@latest

Linux、macOS和Windows的预构建二进制文件也可在 发布页面.

验证已签名的版本

从本节发布后的下一个版本开始，每个版本都与 共同签署 无密钥，每个存档都附带一个SPDX SBOM，并采用 -trimpath 为了可重复性。容器图像在摘要处签名，并附有SBOM+SLSA来源证明。

验证发布存档:

VERSION=vX.Y.Z
ARCHIVE=aguara_${VERSION#v}_linux_amd64.tar.gz

# Download archive, checksums, and the cosign bundle
curl -fsSLO https://github.com/garagon/aguara/releases/download/${VERSION}/${ARCHIVE}
curl -fsSLO https://github.com/garagon/aguara/releases/download/${VERSION}/checksums.txt
curl -fsSLO https://github.com/garagon/aguara/releases/download/${VERSION}/checksums.txt.bundle

# Verify checksums.txt was signed by the GitHub Actions release workflow
cosign verify-blob \
  --bundle checksums.txt.bundle \
  --certificate-identity "https://github.com/garagon/aguara/.github/workflows/release.yml@refs/tags/${VERSION}" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  checksums.txt

# Now verify the archive matches the signed checksums
sha256sum --check --ignore-missing checksums.txt

验证容器映像:

cosign verify ghcr.io/garagon/aguara:${VERSION#v} \
  --certificate-identity "https://github.com/garagon/aguara/.github/workflows/docker.yml@refs/tags/${VERSION}" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

检查SBOM和来源:

# Release archive SBOM (SPDX 2.3)
curl -fsSL https://github.com/garagon/aguara/releases/download/${VERSION}/${ARCHIVE}.sbom.json | jq .

# Container image SBOM and SLSA build provenance.
# docker/build-push-action publishes these as BuildKit attestation manifests
# (in-toto / SLSA spec) attached to the OCI image index, not as cosign
# attestations. Use `docker buildx imagetools inspect` to read them:
docker buildx imagetools inspect ghcr.io/garagon/aguara:${VERSION#v} \
  --format '{{ json .SBOM }}' | jq .
docker buildx imagetools inspect ghcr.io/garagon/aguara:${VERSION#v} \
  --format '{{ json .Provenance }}' | jq .

install.sh 自动执行SHA256验证，如果 sha256sum/shasum 不可用，因此curl管道安装路径永远不会被静默降级。

快速开始

# Am I exposed to a compromised package?
aguara check

# Same, but refresh threat intel from OSV first
aguara check --fresh

# CI gate: fail if a compromised package is installed
aguara check --ci

# Audit: scan code + check packages, single verdict
aguara audit

# Is Aguara's threat intel fresh?
aguara status

# Pull the latest threat intel for future offline checks
aguara update

# Discover which MCP clients are configured on this machine
aguara discover

# Scan a skills directory (or any path) for content threats
aguara scan .claude/skills/

# CI mode for content scan: --fail-on high, no color
aguara scan .claude/skills/ --ci

# Auto-discover and scan all MCP configs on this machine
aguara scan --auto

两者 aguara check 和 aguara audit 默认情况下使用脱机运行 二进制文件中包含了威胁情报。网络仅在以下情况下使用 选择加入 --fresh 或 aguara update.

运作原理

默认情况下，Aguara对每个文件依次运行6个扫描分析器；当出现以下情况时，第7个（Rug Pull）连接 --monitor 启用并配置状态存储。每种攻击类型都不同：

分开 aguara check 和 aguara audit 命令检查已安装的软件包 树（Python site-packages，npm node_modules 包括pnpm .pnpm 存储）以对抗嵌入式威胁英特尔快照。看 供应链检查 对于整个表面。

在扫描之前，所有内容都经过NFKC规范化，以防止Unicode规避攻击。所有层都报告了严重性、动态置信度评分（0.50-0.95）、匹配文本、带上下文行的文件位置和补救指导的发现。总风险评分（0-100）总结了总体威胁级别。

用法

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)
      --tool-name string      Tool context for false-positive reduction (e.g. Bash, Edit, WebFetch)
      --profile string        Scan profile: strict (default), content-aware, minimal
      --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

输出格式

MCP客户端发现

Aguara自动检测MCP配置 17客户：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。

# List all detected MCP configs
aguara discover

# JSON output (sensitive env values are automatically redacted)
aguara discover --format json

# Markdown output
aguara discover --format markdown

# Discover + scan in one command
aguara scan --auto

CI集成

GitHub行动

- uses: garagon/aguara@v0.16.1
  with:
    path: .
    fail-on: high
    version: v0.16.1

两个引脚（动作参考和 version: 输入）是必需的。这 actionref仅固定复合动作及其安装 脚本； version: 将动作安装的Aguara二进制文件固定。设置 两者都使工作流程具有可重复性和可靠性友好性：当 v0.16.2登陆后，机器人会同时更新两者。

扫描您的存储库，将结果上传到GitHub代码扫描，以及 可以选择使构建失败：

- uses: garagon/aguara@v0.16.1
  with:
    path: ./mcp-server/
    severity: medium
    fail-on: high
    version: v0.16.1

所有输入都是可选的。看 action.yml 查看完整列表。

备注：SARIF上传需要 security-events: write 许可，对公共存储库免费。

Docker在CI中的应用

# GitHub Actions with Docker (no install step)
- name: Scan for security issues
  run: docker run --rm -v "${{ github.workspace }}":/scan ghcr.io/garagon/aguara scan /scan --ci

手册/GitLab CI

# GitHub Actions (without the action)
- name: Scan skills for security issues
  run: |
    curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | sh
    aguara scan .claude/skills/ --ci

# GitLab CI
security-scan:
  script:
    - curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | sh
    - 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
  TC-005:
    apply_to_tools: ["Bash"]       # only enforce on Bash
  MCPCFG_004:
    exempt_tools: ["WebFetch"]     # enforce on everything except WebFetch

apply_to_tools 和 exempt_tools 根据规则，它们是相互排斥的。当通过以下方式提供工具名称时，它们会在扫描时过滤结果 --tool-name 或库API。

内联忽略

使用内联注释直接在源文件中抑制特定发现：

# aguara-ignore CRED_004
api_key: "sk-test-1234567890"  # this finding is suppressed

Ignore all previous instructions (this is a test)

支持的指令：

规则

13个模式规则类别中的193个内置规则（什么 aguara list-rules 枚举）加上具有自己的排放时间类别的有毒流链分析仪。为了可读性，该表按发射时间类别对覆盖率进行分组：

看 规则.md 对于包含ID和严重性级别的完整规则目录。

补救指南

所有193条规则都包括补救文本。它出现在每种输出格式中：

• 终端：始终显示关键发现，显示所有严重程度 --verbose
• JSON：包含在每个发现对象中
• 萨里夫：映射到 help 每个规则上的字段
• 标记语言：显示为高和关键发现
• 解释: aguara explain RULE_ID 显示完整的修正文本

# See remediation for a specific rule
aguara explain CRED_002

# Terminal output with remediation for all findings
aguara scan . --verbose

{
  "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.95
}

自定义规则

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"

exclude_patterns 当匹配行（或之前最多3行）与任何排除模式匹配时，抑制匹配。有助于减少文档标题、安装指南等中的误报。

自定义规则在加载时进行验证：未知的YAML字段被拒绝，所有规则都需要 id, name, category以及至少一个图案。

aguara scan .claude/skills/ --rules ./my-rules/

供应链检查

Aguara携带本地威胁情报：精心策划的高优先级列表 紧急咨询（事件流、ipc2022和2026节点、litellm）以及 OSV派生快照在每次发布时都会重新生成 osv.dev。两者都跑 默认离线 --二进制 带有快照。运行时更新是可选的。

检查命令按用户意图组织。

aguara check --我暴露了吗？

# Default: auto-detect npm vs Python in the current directory, run offline
aguara check

# Refresh threat intel from OSV first, then check. The only check mode that
# uses the network; the rest stay offline.
aguara check --fresh

# CI gate: --fail-on critical, no color, exit 1 on compromised packages
aguara check --ci

# Machine-readable
aguara check --format json

它检查什么：

• 已知的受损软件包版本 （手动咨询+OSV

恶意包记录）。

• .pth 包含可执行代码的文件 （导入、子流程、执行、评估）。
• pip/uv/npx缓存 因此，缓存中的一个受损包浮出水面

即使没有virtualenv。

• 持久性后门 （systemd用户服务、sysmon工件）。
• 凭证文件有风险 （SSH、AWS、K8s、git、npm、PyPI、数据库）。

自动检测规则（从最小到最具体）：

• 如果当前目录包含 node_modules，运行npm检查。
• 如果 --path 点在a node_modules 目录，运行npm检查。
• 否则，回到Python站点包发现。

aguara audit --代码与包，一个判断

aguara audit          # check + scan on the current directory
aguara audit --ci     # CI gate: --fail-on critical, no color
aguara audit --fresh  # refresh intel, then audit

aguara audit 将供应链检查和内容扫描组成一个 单一判决。JSON输出包含两个子结果(.check 和 .scan) 加上每个部分的计数，这样仪表板就可以深入到两侧。

aguara status --我的威胁情报新鲜吗？

aguara status

打印Aguara版本，嵌入式快照在日期和时间生成 记录计数，以及是否存在来自先前记录的本地缓存快照 aguara update 跑。没有网络I/O。

aguara update --刷新英特尔以备将来离线检查

aguara update                     # fetch latest OSV dumps (npm + PyPI), cache locally
aguara update --ecosystem npm     # just npm

aguara update 和 --fresh 是使用网络的唯一命令。 刷新的缓存位于 ~/.aguara/intel/snapshot.json；后续 aguara check 自动在嵌入式快照上运行layer it 保持离线。

如果刷新返回零条记录（上游中断、模式转换） 更新被拒绝，因此缓存的英特尔无法被静默擦除。通过 --allow-empty 在初始引导期间进行覆盖。

aguara clean --隔离受损包裹

aguara clean                       # interactive confirmation
aguara clean --yes --purge-caches  # non-interactive, also purge pip/uv caches
aguara clean --dry-run             # preview

文件被隔离到 /tmp/aguara-quarantine/，未删除。之后 在清洁过程中，Aguara为每个人打印了一份证书轮换清单 系统上存在凭据文件。

高级：明确的生态系统和路径

当自动检测无法找到要检查的环境时，请使用这些：

aguara check --ecosystem python --path /opt/venv/lib/python3.12/site-packages/
aguara check --ecosystem npm --path ./node_modules

威胁情报来源

嵌入式快照由两个来源构建：

• 手册 --一份简短的手工整理的高优先级紧急情况清单

咨询。当咨询ID也出现时，优先显示 在OSV中。

• OSV.dev --仅高置信度记录：OpenSSF恶意软件包

ID（ MAL- 命名空间），记录 database_specific.malicious-packages-origins，加上关键字限定 带有确切受影响版本的记录。通用CVE/DoS记录 在导入时被过滤掉，因此Aguara专注于恶意软件 包，而不是通用SCA。

最初是为了响应 litellm供应链攻击 （2026年3月），其中恶意 .pth 文件泄露了凭据和 安装了K8s后门。工具集从那次事件发展到 更广泛的检查+审计+更新+状态表。

Aguara MCP

Aguara MCP 是一个MCP服务器，它使AI代理能够在安装或运行安全威胁之前扫描技能和配置。它将Aguara作为Go库导入——一个 go install，不需要外部二进制文件。

# Install and register with Claude Code
go install github.com/garagon/aguara-mcp@latest
claude mcp add aguara -- aguara-mcp

您的代理将获得4个工具： scan_content, check_mcp_config, list_rules，以及 explain_rule。没有网络，没有LLM，毫秒扫描——代理首先进行检查，然后做出决定。

阿瓜拉手表

阿瓜拉手表 连续扫描 28000+人工智能代理技能 通过6个公共注册机构跟踪人工智能代理的现实威胁情况。所有扫描均由Aguara提供动力。

去图书馆

Aguara公开了一个公共Go API，用于将扫描仪嵌入其他工具。 Aguara MCP 使用此API。

import "github.com/garagon/aguara"

// Scan a directory
result, err := aguara.Scan(ctx, "./skills/")

// Scan inline content (no disk I/O, NFKC-normalized)
result, err := aguara.ScanContent(ctx, content, "skill.md")

// Scan with tool context for false-positive reduction
result, err := aguara.ScanContentAs(ctx, content, "skill.md", "Edit")
// result.Verdict: aguara.VerdictClean, VerdictFlag, or VerdictBlock
// result.ToolName: "Edit"
// result.Findings: always preserved (even when verdict is clean)

// Scan with a profile
result, err := aguara.ScanContent(ctx, content, "skill.md",
    aguara.WithToolName("Edit"),
    aguara.WithScanProfile(aguara.ProfileContentAware),
)
// result.RiskScore: 0-100 aggregate risk score

// Preserve cross-rule findings (for verdict pipelines)
result, err := aguara.ScanContent(ctx, content, "skill.md",
    aguara.WithDeduplicateMode(aguara.DeduplicateSameRuleOnly),
)

// Enable rug-pull detection with persistent state
result, err := aguara.ScanContent(ctx, content, "tool.md",
    aguara.WithStateDir("/var/lib/myapp/aguara-state"),
)

// 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(), WithToolName(), WithScanProfile(), WithDeduplicateMode(), WithStateDir().

建筑

aguara.go              Public API: Scan, ScanContent, ScanContentAs, Discover, ListRules, ExplainRule
options.go             Functional options (WithToolName, WithStateDir, WithDeduplicateMode, ...)
discover/              MCP client discovery: 17 clients, config parsers, auto-detection
cmd/aguara/            CLI entry point (Cobra)
cmd/wasm/              WASM build for browser-based scanning
internal/
  engine/
    pattern/           Pattern matcher: Aho-Corasick + regex, 8 decoders (base64, hex, URL, Unicode, HTML, hex-escape, base32, octal-escape)
    ci/                CI Trust: .github/workflows/ YAML parser, pwn-request / cache / OIDC / persisted-credentials chains
    pkgmeta/           PkgMeta: package.json parser, npm lifecycle / git source / publish-surface chains
    jsrisk/            JSRisk: .js / .mjs / .cjs scanner, obfuscation / daemonization / CI-secret-harvest / runner-pivot / agent-persistence
    nlp/               NLP: markdown AST + JSON/YAML string extraction, proximity-weighted classifier
    toxicflow/         Taint: single-file taint tracking + cross-file correlation across directories
    rugpull/           Rug-pull: SHA256 change detection (CLI --monitor, library WithStateDir)
  rules/               Rule engine: YAML loader, compiler, self-tester
    builtin/           193 embedded rules across 13 YAML files (go:embed)
  scanner/             Orchestrator: file discovery, parallel analysis, inline ignore, result aggregation
    exemptions.go      Tool exemptions, scan profiles, verdict computation
  meta/                Post-processing: configurable dedup, scoring, risk score, correlation, confidence
  output/              Formatters: terminal (ANSI), JSON, SARIF, Markdown
  config/              .aguara.yml loader (supports tool-scoped rules)
  incident/            Incident response: compromised package detection, cleanup, quarantine
  state/               Persistence for rug-pull detection (CLI and library mode)
  types/               Shared types (Finding, Severity, ScanResult, Verdict, DeduplicateMode)

比较

Aguara是专门为AI代理内容构建的。通用SAST工具针对的是应用程序源代码，而不是代理使用的技能文件、工具描述和MCP配置。

Aguara补充了传统的SAST——使用Semgrep编写应用程序代码，使用Aguara编写代理技能和MCP服务器。

贡献

欢迎投稿！请看 贡献.md 用于开发设置、添加规则和PR流程。

有关安全漏洞，请参阅 安全.md.

许可证

Apache许可证2.0