\r \r

Aegis Audit\r

\r Behavioral security scanner for AI agent skills and MCP tools.\r \r 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.\r \r

The "SSL certificate" for AI agent skills — scan, certify, and govern before you trust.\r \r Source: github.com/Aegis-Scan/aegis-scan | Package: pypi.org/project/aegis-audit | License: AGPL-3.0\r \r ---\r \r

What Aegis does\r

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

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

Install\r

\r Install from PyPI using pip or uv:\r \r

pip install aegis-audit\r
```\r
\r
```bash\r
uv tool install aegis-audit\r
```\r
\r
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](https://github.com/Aegis-Scan/aegis-scan).\r
\r
After install, the `aegis` CLI is available on your PATH.\r
\r
---\r
\r
## Quick start\r
\r
Aegis runs fully offline by default. No API keys, no network access, no data leaves your machine.\r
\r
```bash\r
aegis scan --no-llm\r
```\r
\r
This scans the current directory and produces a security report. All commands default to `.` (current directory) when no path is given.\r
\r
```bash\r
aegis scan ./some-skill --no-llm\r
```\r
\r
---\r
\r
## CLI reference\r
\r
| Command | Description |\r
|---|---|\r
| `aegis scan [path]` | Full security scan with risk scoring |\r
| `aegis lock [path]` | Scan + generate signed `aegis.lock` |\r
| `aegis verify [path]` | Verify lockfile against current code |\r
| `aegis badge [path]` | Generate shields.io badge markdown |\r
| `aegis setup` | Interactive LLM configuration wizard |\r
| `aegis mcp-serve` | Start the MCP server (stdio transport) |\r
| `aegis mcp-config` | Print MCP config JSON for Cursor / Claude Desktop |\r
| `aegis version` | Show the Aegis version |\r
\r
Common flags: `--no-llm` (skip LLM, the default), `--json` (CI output), `-v` (verbose).\r
\r
---\r
\r
## Lockfiles\r
\r
Generate a signed lockfile after scanning:\r
\r
```bash\r
aegis lock\r
```\r
\r
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.\r
\r
Verify a lockfile:\r
\r
```bash\r
aegis verify\r
```\r
\r
If any file was modified since the lockfile was created, the Merkle root will not match and verification fails.\r
\r
---\r
\r
## Optional: LLM analysis\r
\r
**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.\r
\r
To enable LLM analysis, run the interactive setup:\r
\r
```bash\r
aegis setup\r
```\r
\r
This saves your config to `~/.aegis/config.yaml`. Alternatively, set one of these environment variables:\r
\r
- `GEMINI_API_KEY` — Google Gemini\r
- `OPENAI_API_KEY` — OpenAI\r
- `ANTHROPIC_API_KEY` — Anthropic Claude\r
\r
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.\r
\r
For local LLM servers (Ollama, LM Studio, llama.cpp, vLLM), see `aegis setup` — no third-party data transmission occurs with local models.\r
\r
---\r
\r
## MCP server\r
\r
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`.\r
\r
Add this to your `.cursor/mcp.json`:\r
\r
```json\r
{\r
  "mcpServers": {\r
    "aegis": {\r
      "command": "aegis",\r
      "args": ["mcp-serve"]\r
    }\r
  }\r
}\r
```\r
\r
Or generate it automatically:\r
\r
```bash\r
aegis mcp-config\r
```\r
\r
Aegis uses stdio transport — no network server needed.\r
\r
---\r
\r
## What gets scanned\r
\r
| Scanner | What it detects |\r
|---|---|\r
| AST Parser | 750+ Python function/method patterns across 15+ categories |\r
| Semgrep Rules | 80+ regex rules for Python, JavaScript, and secrets |\r
| Secret Scanner | API keys, tokens, private keys, connection strings (30+ patterns) |\r
| Shell Analyzer | Pipe-to-shell, reverse shells, inline exec |\r
| JS Analyzer | XSS, eval, prototype pollution, dynamic imports |\r
| Dockerfile Analyzer | Privilege escalation, secrets in ENV/ARG, unpinned images |\r
| Config Analyzer | Dangerous settings in YAML, JSON, TOML, INI |\r
| Social Engineering | Misleading filenames, Unicode tricks, trust manipulation |\r
| Steganography | Hidden payloads in images, homoglyph attacks |\r
| Shadow Module Detector | Stdlib-shadowing files (os.py, sys.py in the skill) |\r
| Combo Analyzer | Multi-capability attack chains (exfiltration, C2, ransomware) |\r
| Taint Analysis | Source-to-sink data flows (commands, URLs, SQL, paths) |\r
| Complexity Analyzer | Cyclomatic complexity warnings for hard-to-audit functions |\r
| Skill Meta Analyzer | SKILL.md vs actual code cross-referencing |\r
| Persona Classifier | Overall trust profile (LGTM, Permission Goblin, etc.) |\r
\r
---\r
\r
## Vibe Check personas\r
\r
Aegis assigns each scanned skill a persona based on deterministic analysis:\r
\r
- **Cracked Dev** — Clean code, smart patterns, minimal permissions.\r
- **LGTM** — Permissions match the intent, scopes are sane, nothing weird.\r
- **Trust Me Bro** — Polished on the outside, suspicious on the inside.\r
- **You Sure About That?** — Messy code, missing pieces, docs that overpromise.\r
- **Co-Dependent Lover** — Tiny logic, huge dependency tree. Supply chain risk.\r
- **Permission Goblin** — Wants everything: filesystem, network, secrets.\r
- **Spaghetti Monster** — Unreadable chaos. High complexity.\r
- **The Snake** — Code that looks clean but is not. Potentially malicious.\r
\r
---\r
\r
## JSON output for CI\r
\r
```bash\r
aegis scan --json --no-llm\r
```\r
\r
```bash\r
aegis scan --json --no-llm | jq '.deterministic.risk_score_static'\r
```\r
\r
```bash\r
aegis scan --json --no-llm | jq -e '.deterministic.risk_score_static \x3C= 50'\r
```\r
\r
The JSON report contains two payloads:\r
\r
- **Deterministic** — Merkle tree, capabilities, findings, risk score (reproducible, signed)\r
- **Ephemeral** — LLM analysis, risk adjustment (non-deterministic, not signed)\r
\r
---\r
\r
## For skill developers\r
\r
Run Aegis on your own skill before publishing:\r
\r
```bash\r
cd ./my-skill\r
aegis scan --no-llm -v\r
```\r
\r
Fix PROHIBITED findings. Document RESTRICTED ones. Ship with an `aegis.lock`:\r
\r
```bash\r
aegis lock\r
```\r
\r
See the [Skill Developer Best Practices](https://github.com/Aegis-Scan/aegis-scan/blob/main/docs/SKILL_DEVELOPER_GUIDE.md) guide.\r
\r
---\r
\r
## Architecture\r
\r
```\r
aegis scan ./skill\r
    |\r
    +-- coordinator.py       File discovery (git-aware / directory walk)\r
    +-- ast_parser.py        AST analysis + pessimistic scope extraction\r
    +-- secret_scanner.py    30+ secret patterns\r
    +-- shell_analyzer.py    Dangerous shell patterns\r
    +-- js_analyzer.py       JS/TS vulnerability patterns\r
    +-- config_analyzer.py   YAML/JSON/TOML/INI risky settings\r
    +-- combo_analyzer.py    Multi-capability attack chains\r
    +-- taint_analyzer.py    Source-to-sink data flow tracking\r
    +-- binary_detector.py   External binary classification\r
    +-- social_eng_scanner   Social engineering detection\r
    +-- stego_scanner        Steganography + homoglyphs\r
    +-- hasher.py            Lazy Merkle tree\r
    +-- signer.py            Ed25519 signing\r
    +-- rule_engine.py       Policy evaluation\r
    +-- reporter/            JSON + Rich console output\r
         |\r
         v\r
    aegis_report.json + aegis.lock\r
```\r
\r
---\r
\r
## License\r
\r
Aegis is dual-licensed:\r
\r
- **Open Source:** AGPL-3.0 — free to use, modify, and distribute. Network service deployments must release source.\r
- **Commercial:** Proprietary license available for embedding in proprietary products, running without source disclosure, SLAs, and support.\r
\r
See [LICENSING.md](https://github.com/Aegis-Scan/aegis-scan/blob/main/aegis-core/LICENSING.md) for full details.\r
\r
---\r
\r
## Contributing\r
\r
Contributions welcome. By contributing, you agree to the [Contributor License Agreement](https://github.com/Aegis-Scan/aegis-scan/blob/main/aegis-core/CLA.md).\r
\r
```bash\r
cd aegis-core\r
pip install -e ".[dev]"\r
pytest\r
```\r
\r
---\r
\r
Python 3.11+ required. No network access needed for deterministic scans. Works offline.\r