aegis-audit_skill

Overview

This skill performs a deep behavioral security audit for AI agent skills and MCP tools. It runs deterministic static analysis, generates cryptographic lockfiles, and can optionally add an LLM-powered intent review. Use it to produce CWE-mapped, OWASP-tagged, line-referenced security reports before installing or deploying any skill or tool.

How this skill works

The scanner parses code with AST analysis, runs Semgrep and 15 specialized detectors (secrets, shell, JS, Dockerfile, taint analysis, etc.) to enumerate exact capabilities and risky patterns. It produces a reproducible deterministic payload (findings, scope-resolved capabilities, and a 0–100 risk score) and can generate an Ed25519-signed Merkle lockfile for tamper detection. Optionally, you may enable an LLM second opinion that annotates intent and suggests mitigations; LLM mode is disabled by default and sends data only when you configure an API key.

When to use it

• Before installing or approving any new skill, tool, plugin, or MCP server
• During pre-deployment review or continuous integration for skills and tools
• When auditing archived skill versions or third-party packages
• To generate a tamper-evident signed snapshot (aegis.lock) for provenance
• When you need CWE/OWASP-mapped, line-referenced evidence rather than a brief safety summary

Best practices

• Run scans offline by default; enable LLM analysis only when you accept provider data handling
• Pin Aegis to a specific version and verify the publisher before installing
• Commit aegis.lock alongside the skill to ensure reproducible verification
• Treat PROHIBITED findings as blockers and document or remediate RESTRICTED findings
• Use JSON output in CI pipelines to gate deployments based on deterministic risk scores

Example use cases

• Scan a downloaded skill directory before importing into an agent runtime
• Integrate aegis scan --json --no-llm into CI to fail builds for high-risk findings
• Generate and commit aegis.lock for published skills so recipients can verify integrity
• Run aegis mcp-serve to expose scan and verify tools to MCP-aware clients like Cursor
• Use the persona classifier to triage manual review workload (Permission Goblin, Spaghetti Monster)