Aguara Is Now a GitHub Action — Security Scanning for AI Agent Repos in One Line

If you maintain an AI agent skill, an MCP server, or any repository where LLMs interact with tool definitions, your code now has a class of vulnerabilities that traditional security scanners do not catch. Prompt injection, tool shadowing, data exfiltration through agent tool outputs, malicious MCP configurations—these are not theoretical. Aguara Watch finds them in public registries every day.

Today, Aguara Security Scanner is available as a GitHub Action on the GitHub Marketplace. One line in your workflow file. 173+ detection rules. 13 security categories. Results show up directly in GitHub Code Scanning. No API keys, no cloud service, no external dependencies.

Why This Matters

AI agent ecosystems are growing fast. MCP servers are being published daily. Skills and tool definitions are being shared, forked, and composed into larger agent workflows. But the security tooling has not kept up.

Traditional static analysis tools (Semgrep, CodeQL, Bandit) are built for application-level vulnerabilities: SQL injection, XSS, buffer overflows. They do not understand the threat model of an AI agent. They do not flag a tool description that subtly instructs the LLM to exfiltrate user data. They do not detect MCP configuration patterns that grant escalated permissions. They do not know what tool shadowing is.

Aguara was built specifically for this. It understands agent skill files, MCP server definitions, tool descriptions, and the patterns that attackers use to weaponize them. And now that analysis runs automatically on every push and every pull request, directly in your CI pipeline.

Quick Start

Create .github/workflows/aguara.yml in your repository:

name: Aguara Security Scan
on: [push, pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: garagon/aguara@v1

That is the entire workflow. Two steps: checkout your code, run Aguara. On every push and every pull request, Aguara will:

1. Install itself — downloads the latest Aguara binary directly from GitHub Releases. No pre-installed dependencies, no container images, no package managers.
2. Scan your repository — runs 173+ detection rules across 13 security categories against every scannable file in your repo.
3. Upload SARIF results — findings are automatically uploaded to GitHub Code Scanning via the github/codeql-action/upload-sarif action. They appear in your repository's Security tab alongside any other code scanning alerts.
4. Report the exit code — clean exit on success. Non-zero exit if findings meet your fail-on threshold, so the workflow fails and blocks the merge.

What It Detects

Aguara scans for threats specific to AI agent ecosystems. Here is what the 13 categories cover:

Category	What it catches
Prompt Injection	Tool descriptions that instruct LLMs to override user intent, ignore safety guidelines, or execute hidden commands
Credential Leaks	Hardcoded API keys, tokens, passwords in skill files, tool configs, and environment references
Command Execution	Shell execution, eval(), dynamic code generation from untrusted input
Data Exfiltration	Patterns that send user data, conversation context, or tool outputs to external endpoints
Indirect Injection	Content that poisons downstream LLM context when fetched, rendered, or processed by tools
MCP Attacks	Tool shadowing, description injection, capability escalation in MCP server definitions
MCP Config	Insecure MCP server configurations: overly broad permissions, missing auth, unsafe defaults
SSRF / Cloud	Server-side request forgery vectors, cloud metadata access, internal network scanning via tool endpoints
Supply Chain	Dependency confusion, typosquatting indicators, unsigned or unverified external resources
Third-Party Content	Unsafe deserialization, script loading without integrity checks, unvalidated external content execution
Toxic Flow	Multi-step attack chains where individual operations look safe but the sequence is malicious
External Downloads	Runtime downloads from untrusted sources, binary fetching, archive extraction without verification
Unicode Attacks	Bidirectional text overrides, homoglyph substitution, invisible characters that alter rendered meaning

Configuration

The Action exposes every aguara scan flag as an input. You do not need to learn a new configuration format—if you already use Aguara locally, the same options work in CI.

Block merges on high-severity findings

- uses: garagon/aguara@v1
  with:
    fail-on: high

The workflow will exit with code 1 if any finding is HIGH or CRITICAL severity. The pull request check fails, the merge is blocked. Set this to critical for a lighter touch, or medium for stricter enforcement.

Scan a specific directory

- uses: garagon/aguara@v1
  with:
    path: ./src/tools/
    fail-on: high

Only scan the directory that contains your agent skill or MCP server definitions. Faster runs, focused results.

Add custom rules

- uses: garagon/aguara@v1
  with:
    rules: ./security/custom-rules/
    fail-on: medium

If you have internal threat patterns specific to your organization—custom MCP configurations, proprietary tool naming conventions, internal endpoint patterns—you can write YAML rules and point Aguara at them.

Disable specific rules

- uses: garagon/aguara@v1
  with:
    disable-rule: MCPCFG_004,EXFIL_009
    fail-on: high

If a rule generates false positives for your specific codebase, disable it by rule ID. This is per-workflow, so different repos can have different exclusions.

JSON or Markdown output

- uses: garagon/aguara@v1
  with:
    format: json
    output: aguara-results.json
    upload-sarif: false

SARIF is the default because it integrates with GitHub Code Scanning. But if you want to post-process results in a later step, use json or markdown format and disable the automatic SARIF upload.

Full Input Reference

Input	Default	Description
path	./	Path to scan
severity	info	Minimum severity to report: critical, high, medium, low, info
fail-on	none	Exit 1 if findings at or above this severity
format	sarif	Output format: terminal, json, sarif, markdown
output	aguara-results.sarif	Output file path
upload-sarif	true	Upload SARIF results to GitHub Code Scanning
verbose	false	Show rule descriptions and confidence scores
rules	none	Additional custom rules directory
disable-rule	none	Rule IDs to disable (comma-separated)
max-file-size	default	Maximum file size to scan (e.g. 50MB)
version	latest	Pin a specific Aguara version

Outputs

The Action exposes two outputs for use in subsequent workflow steps:

- uses: garagon/aguara@v1
  id: scan
  with:
    fail-on: high

- name: Show findings count
  if: always()
  run: echo "Found ${{ steps.scan.outputs.findings-count }} findings (exit code: ${{ steps.scan.outputs.exit-code }})"

• findings-count — total number of findings detected
• exit-code — the raw exit code from the scan (0 = clean, 1 = findings above threshold)

Use these to conditionally run steps, send notifications, or update dashboards based on scan results.

How It Works Under the Hood

The Action is a composite action—no Docker container, no JavaScript runtime. It runs four steps:

1. Install — downloads the Aguara binary from GitHub Releases using the official install.sh script. If you specify a version input, it installs that exact version. Otherwise, it grabs the latest release.
2. Scan — runs aguara scan with all configured inputs. The exit code and findings count are captured as outputs.
3. Upload SARIF — if the format is SARIF and upload-sarif is true (the default), the Action uses github/codeql-action/upload-sarif@v3 to push results to GitHub Code Scanning. This step runs even if the scan exits non-zero, so findings always appear in the Security tab.
4. Propagate exit code — the final step re-exits with the scan's exit code, so the workflow status correctly reflects whether findings were found above your threshold.

No data leaves the runner. No external API calls. No telemetry. The binary is self-contained.

SARIF + GitHub Code Scanning

When Aguara uploads SARIF results, findings appear in the Security > Code scanning alerts section of your repository. Each alert includes:

• Rule ID — the Aguara detection rule (e.g., PROMPT_001, MCP_003)
• Severity — critical, high, medium, low, or info
• File location — exact file and line range where the pattern was detected
• Description — what the rule detects and why it matters
• Confidence — how certain the scanner is that this is a true positive (0.0–1.0)

You can filter, dismiss, or create issues from these alerts using GitHub's standard Code Scanning UI. If you have branch protection rules that require code scanning to pass, Aguara findings at your configured severity will block merges automatically.

Tip: Set permissions: security-events: write on the job to enable SARIF upload. Without this permission, the upload step will be skipped silently.

Real-World Usage

Here is a production-ready workflow that covers the most common patterns:

name: Security
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  aguara:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: garagon/aguara@v1
        id: scan
        with:
          path: ./
          severity: low
          fail-on: high
          verbose: true

      - name: Summary
        if: always()
        run: |
          echo "### Aguara Security Scan" >> $GITHUB_STEP_SUMMARY
          echo "- Findings: ${{ steps.scan.outputs.findings-count }}" >> $GITHUB_STEP_SUMMARY
          echo "- Exit code: ${{ steps.scan.outputs.exit-code }}" >> $GITHUB_STEP_SUMMARY

This reports LOW and above, blocks merges on HIGH+, writes a summary to the GitHub Actions job page, and uploads all findings to Code Scanning.

The Same Scanner Behind Aguara Watch

This is the same Aguara engine that powers Aguara Watch, the continuous security observatory that scans 46,000+ AI agent skills across 7 public registries daily. The same 173+ rules. The same confidence scoring. The same detection categories.

The difference is where it runs. Watch runs the scans at scale across public registries. The GitHub Action runs the same analysis on your code, in your CI pipeline, before it ships.

If you are building tools that AI agents will use, this is how you make sure they are safe before they reach production.