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 • Aguara MCP • Aguara Watch • Contributing

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

Why Aguara?

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.

• 173 detection rules across 13 categories — prompt injection, data exfiltration, credential leaks, supply-chain attacks, MCP-specific threats, command execution, SSRF, unicode attacks, and more.
• 4-layer analysis engine — pattern matching, NLP-based markdown analysis, taint tracking, and rug-pull detection work together to catch threats that any single technique would miss.
• Confidence scoring — every finding carries a confidence level (0.0-1.0), so you can prioritize triage and filter noise.
• Remediation guidance — high-impact rules include actionable fix suggestions in the scan output.
• Deterministic — same input, same output. Every scan is reproducible.
• CI-ready — JSON, SARIF, and Markdown output. GitHub Action. --fail-on threshold. --changed for incremental scans.
• 17 MCP clients supported — auto-discover and scan configs from Claude Desktop, Cursor, VS Code, Windsurf, and 13 more.
• Extensible — write custom rules in YAML. No code required.

Installation

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

Installs the latest binary to ~/.local/bin. Customize with environment variables:

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

Alternative methods

Homebrew (macOS/Linux):

brew install garagon/tap/aguara

Docker (no install required):

# 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:v0.5.0 scan /scan

From source (requires Go 1.25+):

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

Pre-built binaries for Linux, macOS, and Windows are also available on the Releases page.

Quick Start

# 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/ --ci

# Verbose mode (show descriptions, confidence scores, remediation)
aguara scan . --verbose

How It Works

Aguara runs 4 analysis layers sequentially on every file. Each layer catches different attack patterns:

All layers report findings with severity, confidence score, matched text, file location with context lines, and remediation guidance when available.

Usage

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

Output Formats

MCP Client Discovery

Aguara auto-detects 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

CI Integration

GitHub Action

- uses: garagon/aguara@v1

Scans your repository, uploads findings to GitHub Code Scanning, and optionally fails the build:

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

All inputs are optional. See action.yml for the full list.

Note: SARIF upload requires the security-events: write permission and is free for public repositories.

Docker in 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

Manual / 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 | 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

Configuration

Create .aguara.yml in your project root:

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

Inline Ignore

Suppress specific findings directly in your source files using inline comments:

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

<!-- aguara-ignore-next-line PROMPT_INJECTION_001 -->
Ignore all previous instructions (this is a test)

Supported directives:

Rules

173 built-in rules across 13 categories:

See RULES.md for the complete rule catalog with IDs and severity levels.

Remediation Guidance

High-impact rules include remediation text in their findings:

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

Use --verbose in terminal output or --format json to see remediation guidance.

Custom Rules

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 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

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-mcp

Your 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

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.

Go Library

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 with remediation
detail, err := aguara.ExplainRule("PROMPT_INJECTION_001")
fmt.Println(detail.Remediation)

Options: WithMinSeverity(), WithDisabledRules(), WithCustomRules(), WithRuleOverrides(), WithWorkers(), WithIgnorePatterns(), WithMaxFileSize(), WithCategory().

Architecture

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/           173 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)

Comparison

Aguara is purpose-built for AI agent content. General-purpose SAST tools target application source code, not the skill files, tool descriptions, and MCP configs that agents consume.

Aguara complements traditional SAST - use Semgrep for your app code, Aguara for your agent skills and MCP servers.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for development setup, adding rules, and the PR process.

For security vulnerabilities, see SECURITY.md.

License

Apache License 2.0