# Aguara

Open-source security scanner for AI agents and software supply chains. Aguara checks AI agent skills, MCP configs, CI workflows, and known compromised packages across npm (incl. pnpm), PyPI, Go, Rust (crates.io), PHP (Packagist), Ruby (RubyGems), Java (Maven/Gradle), and .NET (NuGet) surfaces. It runs locally as one signed Go binary, offline by default, with no SaaS account, no telemetry, and no LLM calls.

Current release: v0.18.2. Rule catalog: 219 cataloged detections (193 YAML pattern rules + 26 analyzer-emitted entries).

## Core Capabilities

- [Supply-chain check](https://aguarascan.com/#supply-chain): `aguara check .` inspects lockfiles and installed package trees for known compromised package versions. Pre-install mode reads `pnpm-lock.yaml`, `go.sum`, `Cargo.lock`, `composer.lock`, `Gemfile.lock`, Maven/Gradle lockfiles, or NuGet files. Post-install mode inspects `node_modules`, pnpm's `.pnpm` store, and Python `site-packages`. Plain npm projects with only `package-lock.json` / `yarn.lock` and no install are on the next-layer list, not shipping today.
- [AI-agent and MCP scanning](https://aguarascan.com/#mcp): `aguara scan` analyzes agent-facing files, MCP configs, prompts, workflows, and rule-based findings before an agent uses them.
- [CI gate](https://aguarascan.com/#ci): `aguara audit . --ci --fail-on high` produces deterministic SARIF, JSON, Markdown, and terminal output. GitHub Action pinned to v0.18.2 and multi-arch Docker image `ghcr.io/garagon/aguara:0.18.2`.
- [mcp-aguara](https://github.com/garagon/mcp-aguara): exposes Aguara as an MCP server so compatible agents can request local security checks before trusting third-party tools, pasted configs, or skill content.

## Offline by default

All checks use the threat-intel snapshot embedded in the binary. Only two commands touch the network:
- `aguara update` refreshes the local cache for future offline runs (scope with `--ecosystem npm,go`)
- `aguara check . --fresh` refreshes only the ecosystems the current run touches

If a refresh returns zero records (upstream outage, schema shift), the update is refused so cached intel cannot be silently wiped. Pass `--allow-empty` to override during initial bootstrap.

The embedded snapshot is built from:
- OSV.dev — high-confidence records only (OpenSSF Malicious Packages `MAL-` namespace plus keyword-qualified records with exact affected versions)
- OpenSSF Malicious Packages
- A short hand-curated list of high-priority emergency advisories

## Supply-chain ecosystem surface (v0.18.2)

Strong embedded malicious-package coverage today:
- npm (including pnpm) — `node_modules`, pnpm `.pnpm` store, `pnpm-lock.yaml` (works before install)
- PyPI — `site-packages`, `.pth`, pip/uv/npx caches (with persistence coverage)
- RubyGems — `Gemfile.lock`
- NuGet — `packages.lock.json`, `*.csproj`, `*.fsproj`, `*.vbproj` (strong exact-version coverage)

Parser-ready and surfaced in output, with range-aware matching tracked separately:
- Go — `go.sum`, `go.mod` (limited exact-version embedded matches today)
- Rust / crates.io — `Cargo.lock` (public registry only)
- Packagist — `composer.lock`
- Maven / Gradle — `pom.xml`, `gradle.lockfile`, `gradle/dependency-locks/*`

Aguara is not a full SCA replacement. It focuses on known malicious-package records and high-confidence advisories. General CVE / range matching is the next layer.

## Installation (v0.18.2)

```
brew install garagon/tap/aguara
aguara check .
```

```
docker run --rm \
  -v "$PWD:/repo:ro" \
  ghcr.io/garagon/aguara:0.18.2 \
  check /repo
```

Docker image is multi-arch (linux/amd64 + linux/arm64), runs as non-root UID 10001, base images are digest-pinned, and the image is signed at the digest with Cosign plus SPDX SBOM and SLSA provenance attestations.

```
curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh \
  | VERSION=v0.18.2 sh
```

`install.sh` verifies the SHA256 against `checksums.txt` from the release; for full keyless-signature verification on the curl-pipe path, follow up with `cosign verify-blob`. Override default install location with `INSTALL_DIR=/usr/local/bin` for CI or containers.

GitHub Action — pin both the action ref and the binary version:

```
- uses: garagon/aguara@v0.18.2
  with:
    path: .
    severity: medium
    fail-on: high
    format: sarif
    version: v0.18.2
```

## Commands you'll actually use

- `aguara check .` — known compromised packages + persistence artifacts. Offline.
- `aguara scan <path> --ci` — AI-agent content, MCP configs, workflows, scripts. Offline.
- `aguara audit . --ci` — combines check + scan with a single CI verdict.
- `aguara discover` — auto-detects MCP client configurations across 17 supported clients.
- `aguara update` — refreshes the threat-intel cache from OSV. Scope with `--ecosystem`.
- `aguara status` — prints version, snapshot date and record count, cache state. No network I/O.
- `aguara explain RULE_ID` — threat model, examples, and remediation for any rule.
- `aguara clean` — interactive quarantine of compromised Python packages (Python only for now).

## Public product surfaces

- CLI (`aguara`)
- GitHub Action (`garagon/aguara@v0.18.2`)
- Docker image (`ghcr.io/garagon/aguara:0.18.2`)
- Signed release binaries with Cosign keyless + SPDX SBOM
- Go library
- mcp-aguara (MCP server)

## Aguara Watch

Aguara Watch is currently being reworked and is not a supported public product surface for v0.18.2. Historical observatory data is referenced only in archived blog posts.

## Blog Posts

- [30 MCP CVEs in 60 Days: The Attack Surface That Keeps Growing](https://aguarascan.com/blog/30-mcp-cves-60-days/)
- [Aguara Is Now a GitHub Action](https://aguarascan.com/blog/aguara-github-action/) (historical — current install pins both action ref and binary version)
- [Aguara v0.5.0: Confidence Scoring & Configurable Limits](https://aguarascan.com/blog/v0-5-0-release/) (historical release)
- [The Promptware Kill Chain](https://aguarascan.com/blog/promptware-kill-chain/)
- [AI Agents Don't Understand Secrets](https://aguarascan.com/blog/ai-agents-dont-understand-secrets/)
- [CVEs in Anthropic's Own MCP Servers](https://aguarascan.com/blog/anthropic-mcp-server-cves/)
- [Mapping the Agentic AI Attack Surface](https://aguarascan.com/blog/agentic-ai-attack-surface-detection-mapping/)
- [Aguara v0.4.0 Coordinated Release](https://aguarascan.com/blog/v0-4-0-coordinated-release/) (historical release)
- [Securing Your OpenClaw Setup](https://aguarascan.com/blog/securing-openclaw-setup/)
- [Kali Linux + Claude Desktop: When Offensive Security Meets MCP](https://aguarascan.com/blog/kali-claude-desktop-mcp-security/)
- [NIST Asks How to Secure AI Agents](https://aguarascan.com/blog/nist-ai-agent-identity-authorization/)
- [The Security Flywheel](https://aguarascan.com/blog/the-security-flywheel/) (historical engineering note)
- [Docker Sandboxes Are Not Enough](https://aguarascan.com/blog/docker-sandboxes-are-not-enough/)
- [Your AI Agent Config is a Security Liability](https://aguarascan.com/blog/ai-agent-config-security-liability/)
- [OWASP Agentic Top 10 Mapped to Aguara Detection Rules](https://aguarascan.com/blog/owasp-agentic-top-10-mapped-to-detection-rules/)
- [MCP Tool Poisoning: Beyond Descriptions](https://aguarascan.com/blog/mcp-tool-poisoning-beyond-descriptions/)
- [From SKILL.md to Shell: A Security Audit Guide](https://aguarascan.com/blog/skill-md-security-audit-guide/)
- [npx -y Considered Harmful](https://aguarascan.com/blog/npx-y-considered-harmful/)
- [We Scanned 28,000 AI Agent Skills](https://aguarascan.com/blog/we-scanned-28000-ai-agent-skills/) (historical research)
- [How I Built a Semgrep-Like Scanner](https://aguarascan.com/blog/how-i-built-semgrep-for-ai-agents/) (historical architecture note)

## Optional

- [Oktsec](https://oktsec.com/): Security layer for AI agent-to-agent communication — MCP Gateway, cryptographic identity, and runtime policy enforcement, powered by the Aguara detection engine
- [Oktsec LLM Context](https://oktsec.com/llms.txt): Full product context for Oktsec
- [GitHub (Scanner)](https://github.com/garagon/aguara)
- [GitHub (MCP server)](https://github.com/garagon/mcp-aguara)