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:
CODEBLOCK0
CODEBLOCK1
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.
CODEBLOCK2
This scans the current directory and produces a security report. All commands default to . (current directory) when no path is given.
CODEBLOCK3
CLI reference
| Command | Description |
|---|
| INLINECODE3 | Full security scan with risk scoring |
| INLINECODE4 |
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:
CODEBLOCK4
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:
CODEBLOCK5
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:
CODEBLOCK6
This saves your config to ~/.aegis/config.yaml. Alternatively, set one of these environment variables:
- -
GEMINI_API_KEY — Google Gemini - INLINECODE19 — OpenAI
- INLINECODE20 — 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:
CODEBLOCK7
Or generate it automatically:
CODEBLOCK8
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
CODEBLOCK9
CODEBLOCK10
CODEBLOCK11
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:
CODEBLOCK12
Fix PROHIBITED findings. Document RESTRICTED ones. Ship with an aegis.lock:
CODEBLOCK13
See the Skill Developer Best Practices guide.
Architecture
CODEBLOCK14
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.
CODEBLOCK15
Python 3.11+ required. No network access needed for deterministic scans. Works offline.
Aegis Audit
AI 代理技能和 MCP 工具的行为安全扫描器。
Aegis 是一款防御性安全审计工具。它能检测其他技能中的恶意模式，帮助用户避免危险安装。本技能不教授或启用攻击——它帮助用户在信任技能之前进行审查。
AI 代理技能的SSL 证书——在信任之前进行扫描、认证和治理。
来源：github.com/Aegis-Scan/aegis-scan | 包：pypi.org/project/aegis-audit | 许可证：AGPL-3.0
Aegis 的功能
Aegis 回答了每个代理用户都应该问的问题：这个技能实际上能做什么，我应该信任它吗？
- - 确定性静态分析 — AST 解析 + Semgrep + 15 个专业扫描器。相同代码 = 相同报告，每次如此。
- 作用域解析能力 — 不仅仅是访问文件系统，而是具体哪些文件、URL、主机和端口。
- 风险评分 — 0-100 综合评分，附带 CWE/OWASP 映射发现和严重性等级。
- 加密证明 — Ed25519 签名的锁文件，使用 Merkle 树进行防篡改检测。
- 可选的 LLM 分析 — 自带密钥（Gemini、Claude、OpenAI、Ollama、本地）。默认禁用。启用前请查看下面的隐私声明。
安装
使用 pip 或 uv 从 PyPI 安装：
bash
pip install aegis-audit
bash
uv tool install aegis-audit
两个命令安装相同的包。尽可能固定到特定版本（例如 pip install aegis-audit==1.3.0），并在安装前验证 PyPI 上的发布者。包源代码位于 github.com/Aegis-Scan/aegis-scan。
安装后，aegis CLI 将在您的 PATH 中可用。
快速开始
Aegis 默认完全离线运行。无需 API 密钥，无需网络访问，数据不会离开您的机器。
bash
aegis scan --no-llm
这会扫描当前目录并生成安全报告。当未指定路径时，所有命令默认使用 .（当前目录）。
bash
aegis scan ./some-skill --no-llm
CLI 参考
| 命令 | 描述 |
|---|
| aegis scan [path] | 带风险评分的完整安全扫描 |
| aegis lock [path] |
扫描 + 生成签名的 aegis.lock |
| aegis verify [path] | 验证锁文件与当前代码 |
| aegis badge [path] | 生成 shields.io 徽章 Markdown |
| aegis setup | 交互式 LLM 配置向导 |
| aegis mcp-serve | 启动 MCP 服务器（stdio 传输） |
| aegis mcp-config | 为 Cursor / Claude Desktop 打印 MCP 配置 JSON |
| aegis version | 显示 Aegis 版本 |
常用标志：--no-llm（跳过 LLM，默认）、--json（CI 输出）、-v（详细模式）。
锁文件
扫描后生成签名的锁文件：
bash
aegis lock
这会生成 aegis.lock — 技能安全状态的加密签名快照。将其与技能一起提交，以便消费者验证没有发生更改。
验证锁文件：
bash
aegis verify
如果自锁文件创建以来任何文件被修改，Merkle 根将不匹配，验证将失败。
可选：LLM 分析
隐私声明： LLM 分析默认禁用。启用后，Aegis 将扫描的代码发送到配置的第三方 LLM 提供商（Google、OpenAI 或 Anthropic）。除非您明确配置 API 密钥并在没有 --no-llm 的情况下运行扫描，否则不会传输任何数据。不要在包含机密或敏感代码的仓库上启用 LLM 模式，除非您信任提供商。
要启用 LLM 分析，运行交互式设置：
bash
aegis setup
这会将您的配置保存到 ~/.aegis/config.yaml。或者，设置以下环境变量之一：
- - GEMINIAPIKEY — Google Gemini
- OPENAIAPIKEY — OpenAI
- ANTHROPICAPIKEY — Anthropic Claude
这些环境变量是可选的。Aegis 在没有它们的情况下完全离线工作。只有在您想要 AI 第二意见功能并接受扫描代码将被发送到相应提供商时才设置密钥。
对于本地 LLM 服务器（Ollama、LM Studio、llama.cpp、vLLM），请参阅 aegis setup — 使用本地模型不会发生第三方数据传输。
MCP 服务器
Aegis 作为 MCP 服务器运行，适用于 Cursor、Claude Desktop 和任何兼容 MCP 的客户端。暴露了三个工具：scanskill、verifylockfile 和 list_capabilities。
将其添加到您的 .cursor/mcp.json：
json
{
mcpServers: {
aegis: {
command: aegis,
args: [mcp-serve]
}
}
}
或自动生成：
bash
aegis mcp-config
Aegis 使用 stdio 传输 — 无需网络服务器。
扫描内容
| 扫描器 | 检测内容 |
|---|
| AST 解析器 | 15+ 类别中的 750+ Python 函数/方法模式 |
| Semgrep 规则 |
80+ 针对 Python、JavaScript 和机密的正则规则 |
| 机密扫描器 | API 密钥、令牌、私钥、连接字符串（30+ 模式） |
| Shell 分析器 | 管道到 shell、反向 shell、内联执行 |
| JS 分析器 | XSS、eval、原型污染、动态导入 |
| Dockerfile 分析器 | 权限提升、ENV/ARG 中的机密、未固定镜像 |
| 配置分析器 | YAML、JSON、TOML、INI 中的危险设置 |
| 社会工程 | 误导性文件名、Unicode 技巧、信任操纵 |
| 隐写术 | 图像中的隐藏载荷、同形攻击 |
| 影子模块检测器 | 影子标准库文件（技能中的 os.py、sys.py） |
| 组合分析器 | 多能力攻击链（数据外泄、C2、勒索软件） |
| 污点分析 | 源到汇的数据流（命令、URL、SQL、路径） |
| 复杂度分析器 | 难以审计函数的圈复杂度警告 |
| 技能元分析器 | SKILL.md 与实际代码的交叉引用 |
| 角色分类器 | 整体信任概况（LGTM、权限地精等） |
氛围检查角色
Aegis 根据确定性分析为每个扫描的技能分配一个角色：
- - 破解开发者 — 干净的代码、智能的模式、最小的权限。
- LGTM — 权限与意图匹配，作用域合理，没有异常。
- 相信我兄弟 — 外表光鲜，内里可疑。
- 你确定吗？ — 凌乱的代码、缺失的部分、过度承诺的文档。
- 共依赖情人 — 微小的逻辑、巨大的依赖树。供应链风险。
- 权限地精 — 想要一切：文件系统、网络、机密。
- 意大利面怪物 — 不可读的混乱。高复杂度。
- 蛇 — 看起来干净但实际不是的代码。潜在恶意。
CI 的 JSON 输出
bash
aegis scan --json --no-llm
bash
aegis scan --json --no-llm | jq .deterministic.riskscorestatic
bash
aegis scan --json --no-llm | jq -e .deterministic.riskscorestatic <= 50
JSON 报告包含两个负载：
- - 确定性 — Merkle 树、能力、发现、风险评分（可重现、已签名）
- 临时性 — LLM 分析、风险调整（非确定性、未签名）
技能开发者指南
在发布前对自己的技能运行 Aegis：
bash
cd ./my-skill
aegis scan --no-llm -v
修复 PROHIBITED（禁止）发现。记录 RESTRICTED（受限）发现。附带 aegis.lock 发布：
bash
aegis lock
请参阅[技能开发者最佳实践](https://github.com
