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

aguara.mp4

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.

177 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.
Context-aware scanning — pass the tool name (--tool-name Edit) and the scanner automatically skips rules that are always false positives for that tool. Built-in exemptions for Edit, Write, WebFetch, Bash, and more.
Scan profiles — strict (default), content-aware, or minimal enforcement. Findings are always preserved for audit; only the verdict (clean/flag/block) changes.
Unicode evasion prevention — NFKC normalization catches fullwidth character evasion (e.g. fullwidth "Ignore" normalized to ASCII before matching).
Confidence scoring — every finding carries a confidence level (0.0-1.0), so you can prioritize triage and filter noise.
Remediation guidance — all 177 rules include actionable fix suggestions, shown in every output format.
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.9.1 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:

Layer	Engine	What it catches
Pattern Matcher	Regex + Aho-Corasick matching	Known attack signatures, credential patterns, dangerous commands. Aho-Corasick automaton for O(n+m) multi-pattern substring search. Rules pre-grouped by file extension. Decodes base64/hex blobs and re-scans. Downgrades severity for matches inside markdown code blocks.
NLP Analyzer	Goldmark AST walker	Prompt injection in markdown structure — instruction overrides, role-switching, and jailbreaks detected via keyword classification on headings, paragraphs, and list items.
Taint Tracker	Source-to-sink flow analysis	Dangerous capability combinations: reading private data + writing to external URLs, environment variables flowing to shell execution, API responses piped to eval.
Rug-Pull Detector	SHA256 hash tracking	Tool descriptions that change between scans — catches MCP servers that modify their behavior after initial review. Requires `--monitor` flag.

All content is NFKC-normalized before scanning to prevent Unicode evasion attacks. All layers report findings with severity, confidence score, matched text, file location with context lines, and remediation guidance.

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

Output Formats

Format	Flag	Use case
Terminal	`--format terminal` (default)	Human-readable with color, severity dashboard, top-files chart
JSON	`--format json`	Machine processing, API integration, custom tooling
SARIF	`--format sarif`	GitHub Code Scanning, IDE integrations, SAST dashboards
Markdown	`--format markdown`	GitHub Actions job summaries, PR comments

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

Input	Default	Description
`path`	`./`	Path to scan
`severity`	`info`	Minimum severity to report
`fail-on`	(none)	Fail if findings at or above this severity
`format`	`sarif`	Output format: sarif, json, terminal, markdown
`upload-sarif`	`true`	Upload SARIF to GitHub Code Scanning
`version`	(latest)	Pin a specific Aguara version

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
  TC-005:
    apply_to_tools: ["Bash"]       # only enforce on Bash
  MCPCFG_004:
    exempt_tools: ["WebFetch"]     # enforce on everything except WebFetch

apply_to_tools and exempt_tools are mutually exclusive per rule. They filter findings at scan time when a tool name is provided via --tool-name or the library API.

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:

Directive	Effect
`# aguara-ignore RULE_ID`	Suppress rule on the same line
`# aguara-ignore RULE_ID, RULE_ID2`	Suppress multiple rules on the same line
`# aguara-ignore-next-line RULE_ID`	Suppress rule on the next line
`# aguara-ignore`	Suppress all rules on the same line
`<!-- aguara-ignore RULE_ID -->`	HTML/Markdown comment variant
`// aguara-ignore RULE_ID`	C-style comment variant

Rules

177 built-in rules across 13 categories:

Category	Rules	What it detects
Credential Leak	22	API keys (OpenAI, AWS, GCP, Stripe, ...), private keys, DB strings, HMAC secrets
Prompt Injection	18 + NLP	Instruction overrides, role switching, delimiter injection, jailbreaks, event injection
Supply Chain	21	Download-and-execute, reverse shells, sandbox escape, symlink attacks, privilege escalation
External Download	16	Binary downloads, curl-pipe-shell, auto-installs, profile persistence
MCP Attack	16	Tool injection, name shadowing, canonicalization bypass, capability escalation
Data Exfiltration	16 + NLP	Webhook exfil, DNS tunneling, sensitive file reads, env var leaks
Command Execution	15	shell=True, eval, subprocess, child_process, PowerShell
MCP Config	11	Unpinned npx servers, hardcoded secrets, Docker cap-add, host networking
Indirect Injection	11	Fetch-and-follow, remote config, DB-driven instructions, webhook registration
SSRF & Cloud	11	Cloud metadata, IMDS, Docker socket, internal IPs, redirect following
Third-Party Content	10	eval with external data, unsafe deserialization, missing SRI, HTTP downgrade
Unicode Attack	10	RTL override, bidi, homoglyphs, zero-width sequences, normalization bypass
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.

Remediation Guidance

All 177 rules include remediation text. It appears in every output format:

Terminal: always shown for CRITICAL findings, shown for all severities with --verbose
JSON: included in every finding object
SARIF: mapped to the help field on each rule
Markdown: shown for HIGH and CRITICAL findings
Explain: aguara explain RULE_ID shows the full remediation text

# 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.85
}

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.

Custom rules are validated at load time: unknown YAML fields are rejected, and all rules require id, name, category, and at least one pattern.

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 50,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, 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),
)

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

Architecture

aguara.go              Public API: Scan, ScanContent, ScanContentAs, Discover, ListRules, ExplainRule
options.go             Functional options (WithToolName, WithScanProfile, WithMinSeverity, ...)
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/           Layer 1: Aho-Corasick + regex 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
    exemptions.go      Tool exemptions, scan profiles, verdict computation
  meta/                Post-processing: cross-rule dedup, scoring, correlation, confidence adjustment
  output/              Formatters: terminal (ANSI), JSON, SARIF, Markdown
  config/              .aguara.yml loader (supports tool-scoped rules)
  state/               Persistence for incremental scanning and rug-pull detection
  types/               Shared types (Finding, Severity, ScanResult, Verdict, ScanProfile)

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.

Feature	Aguara	Semgrep	Snyk Code	CodeQL
AI agent skill scanning	Yes	No	No	No
MCP config analysis	Yes	No	No	No
Prompt injection detection	Yes (18 rules + NLP)	No	No	No
Rug-pull detection	Yes	No	No	No
Taint tracking for skills	Yes	Yes	Yes	Yes
Offline / no account	Yes	Partial	No	Partial
Custom YAML rules	Yes	Yes	No	No
SARIF output	Yes	Yes	Yes	Yes
Free & open source	Yes (Apache 2.0)	Partial	No	Partial

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

Name		Name	Last commit message	Last commit date
Latest commit History 78 Commits
.github		.github
cmd		cmd
discover		discover
internal		internal
.gitguardian.yaml		.gitguardian.yaml
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yml		.goreleaser.yml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
RULES.md		RULES.md
SECURITY.md		SECURITY.md
action.yml		action.yml
aguara.go		aguara.go
aguara_test.go		aguara_test.go
go.mod		go.mod
go.sum		go.sum
install.sh		install.sh
options.go		options.go

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Aguara

Why Aguara?

Installation

Alternative methods

Quick Start

How It Works

Usage

Output Formats

MCP Client Discovery

CI Integration

GitHub Action

Docker in CI

Manual / GitLab CI

Configuration

Inline Ignore

Rules

Remediation Guidance

Custom Rules

Aguara MCP

Aguara Watch

Go Library

Architecture

Comparison

Contributing

License

About

Uh oh!

Releases 12

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Aguara

Why Aguara?

Installation

Alternative methods

Quick Start

How It Works

Usage

Output Formats

MCP Client Discovery

CI Integration

GitHub Action

Docker in CI

Manual / GitLab CI

Configuration

Inline Ignore

Rules

Remediation Guidance

Custom Rules

Aguara MCP

Aguara Watch

Go Library

Architecture

Comparison

Contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages