Aegis Audit

Aegis Audit

Behavioral security scanner for AI agent skills and MCP tools.

Aegis is a defensive security auditing tool. It detects malicious patterns in other skills so users can avoid dangerous installs. This skill does not teach or enable attacks — it helps users vet skills before trusting them.

The "SSL certificate" for AI agent skills — scan, certify, and govern before you trust.

Source: github.com/Aegis-Scan/aegis-scan | Package: pypi.org/project/aegis-audit | License: AGPL-3.0

What Aegis does

Aegis answers the question every agent user should ask: "What can this skill actually do, and should I trust it?"

• Deterministic static analysis — AST parsing + Semgrep + 15 specialized scanners. Same code = same report, every time.
• Scope-resolved capabilities — Not just "accesses the filesystem" but exactly which files, URLs, hosts, and ports.
• Risk scoring — 0-100 composite score with CWE/OWASP-mapped findings and severity tiers.
• Cryptographic proof — Ed25519-signed lockfile with Merkle tree for tamper detection.
• Optional LLM analysis — Bring your own key (Gemini, Claude, OpenAI, Ollama, local). Disabled by default. See the privacy notice below before enabling.

Install

Install from PyPI using pip or uv:

pip install aegis-audit

uv tool install aegis-audit

Both commands install the same package. Pin to a specific version when possible (e.g. pip install aegis-audit==1.3.0) and verify the publisher on PyPI before installing. The package source is at github.com/Aegis-Scan/aegis-scan.

After install, the aegis CLI is available on your PATH.

Quick start

Aegis runs fully offline by default. No API keys, no network access, no data leaves your machine.

aegis scan --no-llm

This scans the current directory and produces a security report. All commands default to . (current directory) when no path is given.

aegis scan ./some-skill --no-llm

CLI reference

Common flags: --no-llm (skip LLM, the default), --json (CI output), -v (verbose).

Lockfiles

Generate a signed lockfile after scanning:

aegis lock

This produces aegis.lock — a cryptographically signed snapshot of the skill's security state. Commit it alongside the skill so consumers can verify nothing changed.

Verify a lockfile:

aegis verify

If any file was modified since the lockfile was created, the Merkle root will not match and verification fails.

Optional: LLM analysis

Privacy notice: LLM analysis is disabled by default. When enabled, Aegis sends scanned code to the configured third-party LLM provider (Google, OpenAI, or Anthropic). No data is transmitted unless you explicitly configure an API key and run a scan without --no-llm. Do not enable LLM mode on repositories containing secrets or sensitive code unless you trust the provider.

To enable LLM analysis, run the interactive setup:

aegis setup

This saves your config to ~/.aegis/config.yaml. Alternatively, set one of these environment variables:

• GEMINI_API_KEY — Google Gemini
• OPENAI_API_KEY — OpenAI
• ANTHROPIC_API_KEY — Anthropic Claude

These environment variables are optional. Aegis works fully offline without them. Only set a key if you want the AI second-opinion feature and accept that scanned code will be sent to the corresponding provider.

For local LLM servers (Ollama, LM Studio, llama.cpp, vLLM), see aegis setup — no third-party data transmission occurs with local models.

MCP server

Aegis runs as an MCP server for Cursor, Claude Desktop, and any MCP-compatible client. Three tools are exposed: scan_skill, verify_lockfile, and list_capabilities.

Add this to your .cursor/mcp.json:

{
  "mcpServers": {
    "aegis": {
      "command": "aegis",
      "args": ["mcp-serve"]
    }
  }
}

Or generate it automatically:

aegis mcp-config

Aegis uses stdio transport — no network server needed.

What gets scanned

Vibe Check personas

Aegis assigns each scanned skill a persona based on deterministic analysis:

• Cracked Dev — Clean code, smart patterns, minimal permissions.
• LGTM — Permissions match the intent, scopes are sane, nothing weird.
• Trust Me Bro — Polished on the outside, suspicious on the inside.
• You Sure About That? — Messy code, missing pieces, docs that overpromise.
• Co-Dependent Lover — Tiny logic, huge dependency tree. Supply chain risk.
• Permission Goblin — Wants everything: filesystem, network, secrets.
• Spaghetti Monster — Unreadable chaos. High complexity.
• The Snake — Code that looks clean but is not. Potentially malicious.

JSON output for CI

aegis scan --json --no-llm

aegis scan --json --no-llm | jq '.deterministic.risk_score_static'

aegis scan --json --no-llm | jq -e '.deterministic.risk_score_static <= 50'

The JSON report contains two payloads:

• Deterministic — Merkle tree, capabilities, findings, risk score (reproducible, signed)
• Ephemeral — LLM analysis, risk adjustment (non-deterministic, not signed)

For skill developers

Run Aegis on your own skill before publishing:

cd ./my-skill
aegis scan --no-llm -v

Fix PROHIBITED findings. Document RESTRICTED ones. Ship with an aegis.lock:

aegis lock

See the Skill Developer Best Practices guide.

Architecture

aegis scan ./skill
    |
    +-- coordinator.py       File discovery (git-aware / directory walk)
    +-- ast_parser.py        AST analysis + pessimistic scope extraction
    +-- secret_scanner.py    30+ secret patterns
    +-- shell_analyzer.py    Dangerous shell patterns
    +-- js_analyzer.py       JS/TS vulnerability patterns
    +-- config_analyzer.py   YAML/JSON/TOML/INI risky settings
    +-- combo_analyzer.py    Multi-capability attack chains
    +-- taint_analyzer.py    Source-to-sink data flow tracking
    +-- binary_detector.py   External binary classification
    +-- social_eng_scanner   Social engineering detection
    +-- stego_scanner        Steganography + homoglyphs
    +-- hasher.py            Lazy Merkle tree
    +-- signer.py            Ed25519 signing
    +-- rule_engine.py       Policy evaluation
    +-- reporter/            JSON + Rich console output
         |
         v
    aegis_report.json + aegis.lock

License

Aegis is dual-licensed:

• Open Source: AGPL-3.0 — free to use, modify, and distribute. Network service deployments must release source.
• Commercial: Proprietary license available for embedding in proprietary products, running without source disclosure, SLAs, and support.

See LICENSING.md for full details.

Contributing

Contributions welcome. By contributing, you agree to the Contributor License Agreement.

cd aegis-core
pip install -e ".[dev]"
pytest

Python 3.11+ required. No network access needed for deterministic scans. Works offline.