# Aguara — Security Scanner for AI Agents and Software Supply Chains

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 metadata entries)
Analyzer families: pattern matcher (Aho-Corasick + 8 decoders), ci-trust, pkgmeta, jsrisk, NLP, toxic-flow, plus rug-pull (enabled with `--monitor`)

## Product Overview

Modern projects do not only trust the code a team wrote. They trust package versions, lockfiles, install scripts, CI workflows, MCP configs, and AI agent tools. Aguara checks those trust points locally before a project installs, runs, or delegates to them.

Key properties:
- 100% local execution — no SaaS account, no telemetry, no LLM calls
- Offline by default — threat intel embedded in the binary
- Single signed Go binary (Cosign keyless + SPDX SBOM) with zero external dependencies
- Multi-arch Docker image (linux/amd64 + linux/arm64), runs as non-root UID 10001, signed at the digest with SBOM + SLSA provenance
- Deterministic results — same input, same output, every time
- Designed for local and CI use in environments where source code, prompts, configs, and dependency data cannot be uploaded to a third-party scanner
- Extensible with custom YAML rules
- SARIF, JSON, Markdown, and terminal output

## Supply-chain check (v0.18.2)

`aguara check .` answers a practical question: does this project depend on a package version that is already known to be malicious?

It checks two real-world states:

1. Before install, when resolved versions are present in lockfiles such as `pnpm-lock.yaml`, `go.sum`, `Cargo.lock`, `composer.lock`, `Gemfile.lock`, Maven/Gradle lockfiles, or NuGet lockfiles.
2. After install, when packages are already present in trees such as `node_modules`, pnpm's `.pnpm` store, or Python `site-packages`.

Findings include ecosystem, source path, package name, version, and severity.

Plain npm projects with only `package-lock.json` or `yarn.lock` and no install are on the next-layer list, not shipping today. For pnpm projects, Aguara reads `pnpm-lock.yaml` directly without requiring `pnpm install` first.

### Ecosystem coverage

Strong embedded malicious-package coverage today:
- npm (incl. 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/*`

Scope clarity: 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.

### Threat-intel sources

The embedded snapshot is built from:
- OSV.dev — high-confidence records only. OpenSSF Malicious Packages IDs (the `MAL-` namespace), records with `database_specific.malicious-packages-origins`, plus keyword-qualified records that carry exact affected versions. Generic CVE / DoS records are filtered out at import time.
- OpenSSF Malicious Packages.
- A short hand-curated list of high-priority emergency advisories. Takes display precedence when an advisory ID also appears in OSV.

## 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. Default refreshes every supported ecosystem; scope with `--ecosystem npm,go` (repeatable or comma-separated). The refreshed cache lives at `~/.aguara/intel/snapshot.json` and layers over the embedded snapshot automatically.
- `aguara check . --fresh` refreshes only the ecosystems the current run actually 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.

## AI agent and MCP security

AI agents read instructions, tool descriptions, config files, and third-party skills as operational context. That content can ask the agent to ignore rules, leak credentials, run commands, or trust a malicious tool. Aguara scans those files before the agent uses them.

```
aguara scan --auto
aguara scan .claude/skills --ci
aguara scan ~/.config --severity high
aguara explain MCPCFG_003
```

### 17 MCP clients auto-detected

`aguara discover` and `aguara scan --auto` cover: Claude Desktop, Cursor, VS Code, Cline, Windsurf, OpenClaw, OpenCode, Zed, Amp, Gemini CLI, Copilot CLI, Amazon Q, Claude Code, Roo Code, Kilo Code, BoltAI, and JetBrains. Sensitive env values are auto-redacted in `--format json` output.

## Installation

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

Docker (multi-arch, non-root UID 10001, signed at digest):
```
docker run --rm \
  -v "$PWD:/repo:ro" \
  ghcr.io/garagon/aguara:0.18.2 \
  check /repo
```

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

aguara check .
```

Override install location for CI / containers:
```
curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh \
  | VERSION=v0.18.2 INSTALL_DIR=/usr/local/bin sh
```

Go install (developers building from source, requires Go 1.25+):
```
go install github.com/garagon/aguara/cmd/aguara@v0.18.2
```

Source builds report `dev` version metadata because Go does not inject release ldflags. For signed releases use Homebrew, Docker, or the install script.

## Verifying signed releases

Every release is signed with Cosign keyless, ships an SPDX SBOM per archive, and is built with `-trimpath` for reproducibility.

```
VERSION=v0.18.2
ARCHIVE=aguara_${VERSION#v}_linux_amd64.tar.gz

curl -fsSLO https://github.com/garagon/aguara/releases/download/${VERSION}/${ARCHIVE}
curl -fsSLO https://github.com/garagon/aguara/releases/download/${VERSION}/checksums.txt
curl -fsSLO https://github.com/garagon/aguara/releases/download/${VERSION}/checksums.txt.bundle

cosign verify-blob \
  --bundle checksums.txt.bundle \
  --certificate-identity "https://github.com/garagon/aguara/.github/workflows/release.yml@refs/tags/${VERSION}" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  checksums.txt

sha256sum --check --ignore-missing checksums.txt
```

For the container image: `cosign verify ghcr.io/garagon/aguara:${VERSION#v}` with `--certificate-identity` for `docker.yml`. SBOMs and SLSA build provenance are BuildKit attestation manifests attached to the OCI image index — inspect with `docker buildx imagetools inspect --format '{{ json .SBOM }}'`.

## GitHub Action

Pin both the action ref and the `version:` input. The action ref pins the workflow wrapper; `version:` pins the Aguara binary.

```
name: Aguara
on:
  pull_request:
  push:
    branches: [main]

jobs:
  aguara:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: garagon/aguara@v0.18.2
        with:
          path: .
          severity: medium
          fail-on: high
          format: sarif
          version: v0.18.2
```

Inputs: `path` (default `./`), `severity` (default `info`), `fail-on` (none), `format` (`sarif` default; `json`/`terminal`/`markdown`), `upload-sarif` (true by default), `version` (latest by default). SARIF upload is free for public repositories.

## Commands you'll actually use

- `aguara check .` — known compromised packages and 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 npm,go`.
- `aguara check . --fresh` — refreshes only the ecosystems the current run touches.
- `aguara status` — 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 scope today).

## What Aguara Checks

User-facing buckets, mapped to the underlying analyzer families (pattern matcher, ci-trust, pkgmeta, jsrisk, NLP, toxic-flow, plus rug-pull with `--monitor`):

- Compromised packages — known malicious package versions across package manager surfaces.
- Prompt injection — instruction overrides, hidden instructions, authority claims, delimiter abuse, heading-body divergence.
- MCP config risk — unpinned npx, shell metacharacters, hardcoded secrets, host networking, Docker privileges, capability escalation.
- CI trust chains — unsafe GitHub Actions patterns, mutable refs, suspicious workflow execution surfaces, secret exposure paths.
- Secret exfiltration — credentials combined with webhooks, DNS, external endpoints, or sensitive file reads.
- JavaScript package behavior — suspicious install-time or runtime behavior, DNS TXT exfiltration, child processes, dynamic code evaluation.
- Unicode and encoded evasion — bidi, homoglyphs, zero-width characters, encoded payloads (base64, hex, URL, HTML entities, hex escapes, base32, octal escapes).
- Toxic flows — dangerous source-to-sink paths across files, including split capabilities across MCP server tools.
- Rug-pull detection — hash-based change tracking across scans (enabled with `--monitor` and a state store).

## mcp-aguara (MCP server)

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. It imports Aguara as a Go library, so it does not shell out to a separate scanner binary.

Tools exposed:
- `scan_content` — Scan skill files or MCP server configs for security issues
- `check_mcp_config` — Audit MCP client configuration for unpinned servers, hardcoded secrets, and insecure transport
- `list_rules` — Browse cataloged detection rules by category or severity
- `explain_rule` — Get detailed explanation of any detection rule

Repository: https://github.com/garagon/mcp-aguara

## 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. Use the landing page and the GitHub README for current product capabilities.

## Frequently Asked Questions

### What is Aguara?
Aguara is an open-source security scanner for AI agents and software supply chains. It checks agent-facing files, MCP configs, CI workflows, and known compromised packages using a local deterministic engine with 219 cataloged detections. Single signed Go binary, 100% local execution, offline by default, zero dependencies, Apache-2.0 licensed.

### What does `aguara check .` do?
`aguara check .` inspects package lockfiles and installed package trees for known compromised packages and related persistence artifacts. It reports the ecosystem, source path, package count, findings, and severity.

### Can Aguara check before install?
Yes, when resolved versions are present in supported lockfiles such as `pnpm-lock.yaml`, `go.sum`, `Cargo.lock`, `composer.lock`, `Gemfile.lock`, Maven/Gradle lockfiles, or NuGet files. If packages are already installed, Aguara can also inspect `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.

### What package ecosystems does Aguara inspect?
npm (incl. pnpm), PyPI, Go modules, Rust (crates.io), PHP (Packagist), Ruby (RubyGems), Java (Maven/Gradle), and .NET (NuGet). Strong embedded malicious-package coverage today for npm/pnpm, PyPI, RubyGems, and NuGet. Go, crates.io, Packagist, and Maven/Gradle are parser-ready and surfaced in output, with range-aware matching still tracked separately.

### Does Aguara upload code or dependency data?
No. Aguara runs locally as one signed Go binary with no SaaS account, no telemetry, and no LLM calls. Source code, prompts, configs, and dependency data never leave your machine.

### Is Aguara offline by default?
Yes. All checks use the threat-intel snapshot embedded in the binary. Network access is opt-in through `aguara update` (refreshes the local cache for future offline runs) or `aguara check . --fresh` (refreshes only the ecosystems the run touches).

### How are releases signed?
Every release is signed with Cosign keyless and ships an SPDX SBOM per archive. The multi-arch container image (linux/amd64 + linux/arm64) is signed at the digest and carries SBOM and SLSA build provenance attestations attached to the OCI image index.

### How do I run Aguara in CI?
Use the official GitHub Action pinned to v0.18.2 with `path:`, `severity:`, `fail-on:`, `format:`, and `version:` inputs. Pin both the action ref and the binary version. Aguara emits SARIF, JSON, Markdown, and terminal output.

### What is mcp-aguara?
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. Repository: https://github.com/garagon/mcp-aguara.

### Is Aguara a full SCA scanner?
No. Aguara focuses on known compromised packages and high-risk trust points for AI-agent and software-supply-chain workflows. It is complementary to broader SCA platforms. Range-aware vulnerability matching for some ecosystems is tracked separately.

## Related Products

- [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.

## Links

- Website: https://aguarascan.com
- GitHub (Scanner): https://github.com/garagon/aguara
- GitHub (MCP Server): https://github.com/garagon/mcp-aguara
- Docker image: ghcr.io/garagon/aguara:0.18.2
- Blog: https://aguarascan.com/blog/
- Founder: Gustavo Aragon (https://github.com/garagon)
- License: Apache-2.0