aguara AGENTS.md

AGENTS.md - Aguara Reference for AI Agents

Aguara is a static security scanner for AI agent skills and MCP server configurations. Single Go binary, fully offline, deterministic, no LLM. Think "Semgrep for AI agents."

Quick Start

# Install
go install github.com/garagon/aguara@latest

# Scan a directory
aguara scan ./skills/

# Scan with CI defaults (fail on high+, no color)
aguara scan --ci ./skills/

# JSON output
aguara scan --format json ./skills/

# List all rules
aguara list-rules

Go Library API

import "github.com/garagon/aguara"

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

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

// List rules
rules := aguara.ListRules()

// Explain a rule
detail, err := aguara.ExplainRule("PROMPT_INJECTION_001")

Options

aguara.Scan(ctx, path,
    aguara.WithMinSeverity(aguara.SeverityMedium),
    aguara.WithDisabledRules("EXFIL_005", "CRED_001"),
    aguara.WithCustomRules("./custom-rules/"),
    aguara.WithWorkers(4),
    aguara.WithRuleOverrides(map[string]aguara.RuleOverride{
        "PROMPT_INJECTION_001": {Severity: "medium"},
        "EXFIL_005":           {Disabled: true},
    }),
)

Types

type ScanResult struct {
    Findings     []Finding
    FilesScanned int
    RulesLoaded  int
    DurationMs   int64    // in JSON output
}

type Finding struct {
    RuleID      string        // "PROMPT_INJECTION_001"
    RuleName    string        // "Instruction override attempt"
    Severity    Severity      // 0=INFO, 1=LOW, 2=MEDIUM, 3=HIGH, 4=CRITICAL
    Category    string        // "prompt-injection"
    Description string        // rule description
    FilePath    string        // "skills/evil.md"
    Line        int           // 1-indexed
    Column      int
    MatchedText string        // text that triggered the rule
    Context     []ContextLine // surrounding lines
    Score       float64       // 0-100 risk score
    Analyzer    string        // "pattern", "nlp-injection", "toxicflow", "rugpull"
    InCodeBlock bool          // true if match is inside a fenced code block
}

type Severity int // SeverityInfo=0, SeverityLow=1, SeverityMedium=2, SeverityHigh=3, SeverityCritical=4