FAQ

FAQ

General

What does Aguara detect?

Aguara detects security threats in AI agent skills and MCP server configurations: prompt injection, data exfiltration, credential leaks, supply-chain attacks, MCP-specific threats, and more. See Detection Rules for the full list.

Does Aguara use AI/LLM for detection?

No. Aguara uses deterministic static analysis: regex patterns, NLP-based Markdown structure analysis, and taint tracking. Same input always produces the same output. No API keys needed, no cloud calls.

What file types does Aguara scan?

Primarily Markdown (.md) and text files (.txt) — the standard formats for AI agent skills. Also scans JSON configs (MCP configurations) when using --auto or targeting .json files.

Does Aguara need network access?

No. Aguara works completely offline. Rules are embedded in the binary. The only optional network call is the update check (disable with --no-update-check).

Installation

"command not found: aguara"

Your PATH doesn't include the install directory. Fix:

# If installed via install script (default: ~/.local/bin)
export PATH="$HOME/.local/bin:$PATH"

# If installed via go install (default: ~/go/bin)
export PATH="$HOME/go/bin:$PATH"

Add the export line to your ~/.bashrc or ~/.zshrc to make it permanent.

Which Go version do I need?

Go 1.25+ for building from source. Pre-built binaries require no Go installation.

Scanning

How do I scan all my MCP configs at once?

aguara scan --auto

This auto-discovers configurations for 17 MCP clients (Claude Desktop, Cursor, VS Code, etc.) and scans them all.

How do I reduce false positives?

Several options:

1. Disable specific rules:

   aguara scan . --disable-rule CRED_004,EXTDL_004

2. Use .aguara.yml overrides:

   rule_overrides:
     CRED_004:
       severity: low
     EXTDL_004:
       disabled: true

3. Use exclude_patterns in custom rules to suppress matches in documentation contexts.

4. Filter by severity:

   aguara scan . --severity high

Can I scan only files changed in my PR?

Yes:

aguara scan . --changed

This uses git diff to find changed files and only scans those.

What's the difference between --severity and --fail-on?

• --severity controls which findings are displayed (minimum threshold)
• --fail-on controls the exit code (exit 1 if findings at or above this level)

Example: show everything but only fail CI on high+:

aguara scan . --severity info --fail-on high

Rules

How do I write custom rules?

See Custom Rules. Rules are YAML files with patterns, examples, and metadata.

Why can't I use lookaheads in regex?

Go's regexp package uses RE2, which doesn't support Perl-style lookaheads ((?!...)) or lookbehinds ((?<=...)). Use character class restrictions or match_mode: all with multiple patterns instead.

How are NLP detections different from pattern rules?

Pattern rules match explicit text patterns. NLP detections analyze the structure of Markdown documents:

• Heading says "Configuration Guide" but body contains rm -rf /
• HTML comment contains action verbs like "execute" or "install"
• Code block labeled as "yaml" but contains shell commands

These catch attacks that are structurally hidden, not pattern-based.

CI

What exit codes does Aguara use?

Code	Meaning
0	No findings above threshold
1	Findings at or above --fail-on severity
2	Runtime error

How do I upload results to GitHub Code Scanning?

aguara scan . --format sarif -o results.sarif

Then use github/codeql-action/upload-sarif in your workflow. See CI Integration.

Integration

Can I use Aguara as a Go library?

Yes. See Go Library API:

import "github.com/garagon/aguara"

result, err := aguara.ScanContent(ctx, content, "skill.md")

What is Aguara MCP?

An MCP server that gives AI agents security scanning as a tool. Install with go install github.com/garagon/aguara-mcp@latest. See Ecosystem.

What is Aguara Watch?

A public dashboard at watch.aguarascan.com that scans 28,000+ skills daily across 5 registries. See Ecosystem.