aegis-audit✓ تایید شده

محتوای SKILL.md

---
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](https://github.com/Aegis-Scan/aegis-scan) | Package: [pypi.org/project/aegis-audit](https://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](https://pypi.org/project/aegis-audit/) 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](https://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](https://github.com/Aegis-Scan/aegis-scan/blob/main/docs/SKILL_DEVELOPER_GUIDE.md) 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](https://github.com/Aegis-Scan/aegis-scan/blob/main/aegis-core/LICENSING.md) for full details.

---

## Contributing

Contributions welcome. By contributing, you agree to the [Contributor License Agreement](https://github.com/Aegis-Scan/aegis-scan/blob/main/aegis-core/CLA.md).

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

---

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

مجوز

مجوز اعلام‌شده: MIT

MIT License

Copyright (c) 2026 openclaw

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

مشاهدهٔ مجوز در مخزن منبع — نسخهٔ منتشرشده در آن‌جا مرجع است.