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 • Usage • Rules • Aguara MCP • Aguara Watch • Contributing
aguara.mp4
AI agents and MCP servers run code on your behalf. A single malicious skill file can exfiltrate credentials, inject prompts, or install backdoors. Aguara catches these threats before deployment with static analysis that requires no API keys, no cloud, and no LLM.
- 148+ rules across 13 categories covering prompt injection, data exfiltration, credential leaks, supply-chain attacks, MCP-specific threats, and more.
- Catches obfuscated attacks that regex-only tools miss, using NLP-based markdown structure analysis and taint tracking.
- Deterministic — same input, same output. Every scan is reproducible.
- CI-ready — JSON, SARIF, and Markdown output.
--fail-onthreshold.--changedfor incremental scans. - Extensible — write custom rules in YAML. No code required.
curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | bashInstalls the latest binary to ~/.local/bin. Customize with environment variables:
VERSION=v0.3.1 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 | bashFrom source (requires Go 1.25+):
go install github.com/garagon/aguara/cmd/aguara@latestPre-built binaries for Linux, macOS, and Windows are also available on the Releases page.
# Auto-discover and scan all MCP configs on your machine
aguara scan --auto
# Discover which MCP clients are configured (no scanning)
aguara discover
# Scan a skills directory
aguara scan .claude/skills/
# Scan a single file
aguara scan .claude/skills/deploy/SKILL.md
# Only high and critical findings
aguara scan . --severity high
# CI mode (exit 1 on high+, no color)
aguara scan .claude/skills/ --ciaguara 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)
--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
-v, --verbose Show rule descriptions for critical and high findings
-h, --help Help
Aguara can auto-detect MCP configurations across 17 clients: Claude Desktop, Cursor, VS Code, Cline, Windsurf, OpenClaw, OpenCode, Zed, Amp, Gemini CLI, Copilot CLI, Amazon Q, Claude Code, Roo Code, Kilo Code, BoltAI, and JetBrains.
# List all detected MCP configs
aguara discover
# JSON output
aguara discover --format json
# Discover + scan in one command
aguara scan --auto# GitHub Actions
- 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.sarifCreate .aguara.yml in your project root:
severity: medium
fail_on: high
ignore:
- "vendor/**"
- "node_modules/**"
rule_overrides:
CRED_004:
severity: low
EXTDL_004:
disabled: true148+ built-in rules across 13 categories:
| Category | Rules | What it detects |
|---|---|---|
| Prompt Injection | 17 + NLP | Instruction overrides, role switching, delimiter injection, jailbreaks |
| Data Exfiltration | 16 + NLP | Webhook exfil, DNS tunneling, sensitive file reads, env var leaks |
| Credential Leak | 19 | API keys (OpenAI, AWS, GCP, Stripe, ...), private keys, DB strings |
| MCP Attack | 12 | Tool injection, name shadowing, manifest tampering, capability escalation |
| MCP Config | 8 | Unpinned npx servers, hardcoded secrets, shell metacharacters |
| Supply Chain | 15 | Download-and-execute, reverse shells, obfuscated commands, privilege escalation |
| External Download | 17 | Binary downloads, curl-pipe-shell, auto-installs, profile persistence |
| Command Execution | 16 | shell=True, eval, subprocess, child_process, PowerShell |
| Indirect Injection | 6 | Fetch-and-follow, remote config, email-as-instructions |
| SSRF & Cloud | 10 | Cloud metadata, IMDS, Docker socket, internal IPs |
| Unicode Attack | 7 | RTL override, bidi, homoglyphs, tag characters |
| Third-Party Content | 5 | Mutable raw content, unvalidated API responses, remote templates |
| Toxic Flow | 3 | User input to dangerous sinks, env vars to shell, API to eval |
See RULES.md for the complete rule catalog with IDs and severity levels.
id: CUSTOM_001
name: "Internal API endpoint"
description: "Detects references to internal APIs"
severity: HIGH
category: custom
targets: ["*.md", "*.txt"]
match_mode: any
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 suppress a match when the matched line (or up to 3 lines before it) matches any exclude pattern. Useful for reducing false positives in documentation headings, installation guides, etc.
aguara scan .claude/skills/ --rules ./my-rules/Aguara MCP is an MCP server that gives AI agents the ability to scan skills and configurations for security threats — before installing or running them. It imports Aguara as a Go library — one go install, no external binary needed.
# Install and register with Claude Code
go install github.com/garagon/aguara-mcp@latest
claude mcp add aguara -- aguara-mcpYour agent gets 4 tools: scan_content, check_mcp_config, list_rules, and explain_rule. No network, no LLM, millisecond scans — the agent checks first, then decides.
Aguara Watch continuously scans 28,000+ AI agent skills across 5 public registries to track the real-world threat landscape for AI agents. All scans are powered by Aguara.
Aguara exposes a public Go API for embedding the scanner in other tools. Aguara MCP uses this 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
detail, err := aguara.ExplainRule("PROMPT_INJECTION_001")Options: WithMinSeverity(), WithDisabledRules(), WithCustomRules(), WithRuleOverrides(), WithWorkers(), WithIgnorePatterns().
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
rugpull/ Rug-pull detection analyzer
toxicflow/ Taint tracking: source -> sink flow analysis
rules/ Rule engine: YAML loader, compiler, self-tester
builtin/ 148 embedded rules across 12 YAML files (go:embed)
scanner/ Orchestrator: file discovery, parallel analysis, result aggregation
meta/ Post-processing: dedup, scoring, cross-finding correlation
output/ Formatters: terminal (ANSI), JSON, SARIF, Markdown
config/ .aguara.yml loader
state/ Persistence for incremental scanning
types/ Shared types (Finding, Severity, ScanResult)
Contributions are welcome! Please see CONTRIBUTING.md for development setup, adding rules, and the PR process.
For security vulnerabilities, see SECURITY.md.
