---

name: aegis-audit description: > Deep behavioral security audit for AI agent skills and MCP tools. Performs deterministic static analysis (AST + Semgrep + 15 specialized scanners), cryptographic lockfile generation, and optional LLM-powered intent analysis. Use when installing, reviewing, or approving any skill, tool, plugin, or MCP server — especially before first use. Replaces basic safety summaries with full CWE-mapped, OWASP-tagged, line-referenced security reports. version: 0.1.10 homepage: https://github.com/Aegis-Scan/aegis-scan url: https://pypi.org/project/aegis-audit/ metadata: {"openclaw":{"emoji":"🔍","homepage":"https://github.com/Aegis-Scan/aegis-scan","requires":{"bins":["aegis"],"config":["~/.aegis/config.yaml"]},"install":[{"kind":"uv","package":"aegis-audit","bins":["aegis"]}]}}

---

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: ``bash pip install aegis-audit ` `bash 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. `bash 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. `bash aegis scan ./some-skill --no-llm `

---

CLI reference

| Command | Description | |---|---| | aegis scan [path] | Full security scan with risk scoring | | aegis lock [path] | Scan + generate signed aegis.lock | | aegis verify [path] | Verify lockfile against current code | | aegis badge [path] | Generate shields.io badge markdown | | aegis setup | Interactive LLM configuration wizard | | aegis mcp-serve | Start the MCP server (stdio transport) | | aegis mcp-config | Print MCP config JSON for Cursor / Claude Desktop | | aegis version | Show the Aegis version | Common flags: --no-llm (skip LLM, the default), --json (CI output), -v (verbose).

---

Lockfiles

Generate a signed lockfile after scanning: `bash 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: `bash 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: `bash 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: `json { "mcpServers": { "aegis": { "command": "aegis", "args": ["mcp-serve"] } } } ` Or generate it automatically: `bash aegis mcp-config ` Aegis uses stdio transport — no network server needed.

---

What gets scanned

| Scanner | What it detects | |---|---| | AST Parser | 750+ Python function/method patterns across 15+ categories | | Semgrep Rules | 80+ regex rules for Python, JavaScript, and secrets | | Secret Scanner | API keys, tokens, private keys, connection strings (30+ patterns) | | Shell Analyzer | Pipe-to-shell, reverse shells, inline exec | | JS Analyzer | XSS, eval, prototype pollution, dynamic imports | | Dockerfile Analyzer | Privilege escalation, secrets in ENV/ARG, unpinned images | | Config Analyzer | Dangerous settings in YAML, JSON, TOML, INI | | Social Engineering | Misleading filenames, Unicode tricks, trust manipulation | | Steganography | Hidden payloads in images, homoglyph attacks | | Shadow Module Detector | Stdlib-shadowing files (os.py, sys.py in the skill) | | Combo Analyzer | Multi-capability attack chains (exfiltration, C2, ransomware) | | Taint Analysis | Source-to-sink data flows (commands, URLs, SQL, paths) | | Complexity Analyzer | Cyclomatic complexity warnings for hard-to-audit functions | | Skill Meta Analyzer | SKILL.md vs actual code cross-referencing | | Persona Classifier | Overall trust profile (LGTM, Permission Goblin, etc.) |

---

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

`bash aegis scan --json --no-llm ` `bash aegis scan --json --no-llm | jq '.deterministic.risk_score_static' ` `bash 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: `bash cd ./my-skill aegis scan --no-llm -v ` Fix PROHIBITED findings. Document RESTRICTED ones. Ship with an aegis.lock: `bash 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. `bash cd aegis-core pip install -e ".[dev]" pytest ``

---

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