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

---

intent

use aegis to answer the question every agent user should ask before installing a skill: "what can this thing actually do, and should i trust it?" run a deterministic static analysis (AST parsing, Semgrep rules, 15+ specialized scanners) on any skill, tool, plugin, or MCP server to get a full CWE-mapped, OWASP-tagged security report with line references and risk scoring. aegis runs fully offline by default (no API keys, no network access, no data leaves your machine) and optionally integrates LLM analysis for behavioral intent checking. use this before first install, before code review, before approval, or before publishing your own skill.

---

inputs

installation requirement:

• Python 3.11+
• PyPI package: aegis-audit (install via pip or uv)
• CLI binary: aegis (available on PATH after install)

required for all scans:

• local filesystem path to skill/tool/MCP server (defaults to current directory .)
• read permission on all files in target path
• git metadata optional but recommended (aegis uses .gitignore to skip files)

optional: LLM analysis (disabled by default, no data transmitted unless explicitly enabled)

• one environment variable or config file entry:
  • GEMINI_API_KEY for Google Gemini
  • OPENAI_API_KEY for OpenAI
  • ANTHROPIC_API_KEY for Anthropic Claude
  • local LLM endpoint for Ollama, LM Studio, llama.cpp, vLLM (no third-party transmission)
• config file: ~/.aegis/config.yaml (created by aegis setup wizard)

optional: MCP server mode

• stdio transport (no network server needed)
• compatible with Cursor, Claude Desktop, or any MCP-compatible client

no external network connections required for deterministic scans. all static analysis runs locally.

---

procedure

procedure 1: basic offline scan

1. install aegis: pip install aegis-audit or uv tool install aegis-audit

   • input: PyPI package repository
   • output: aegis CLI binary available on PATH

2. navigate to target skill directory or provide path: cd ./my-skill or aegis scan ./path/to/skill

   • input: local filesystem path
   • output: none (ready for scan)

3. run offline scan with no LLM: aegis scan --no-llm

   • input: current directory or specified path, no API keys
   • output: colored console report + aegis_report.json (structured findings)
   • processing: AST parser + Semgrep + 15 specialized scanners analyze all files
   • runtime: typically 2-10 seconds depending on codebase size

4. review report in console (human readable):

   • input: console output (Rich formatted tables, severity colors)
   • output: visual acknowledgment of findings, risk score (0-100), persona assignment

5. review JSON report for CI/automation: cat aegis_report.json or jq queries

   • input: aegis_report.json file
   • output: structured data (deterministic payload + ephemeral payload)

procedure 2: generate cryptographic lockfile

1. run scan with lockfile generation: aegis lock

   • input: current directory or path
   • output: aegis.lock (Ed25519-signed Merkle tree snapshot)
   • processing: identical to procedure 1, step 3, plus cryptographic signing
   • file format: JSON with Ed25519 signature, Merkle root, file hashes

2. commit aegis.lock alongside skill code: git add aegis.lock && git commit -m "add aegis lockfile"

   • input: aegis.lock file in repo
   • output: version control record

3. distribute skill with lockfile. consumers verify it has not changed since signing.

procedure 3: verify lockfile integrity

1. run verification: aegis verify (or aegis verify ./path/to/skill)

   • input: aegis.lock file + current skill code
   • output: pass/fail, Merkle root match confirmation
   • processing: recomputes Merkle tree on current files, compares to locked root
   • exit code: 0 on pass, non-zero on mismatch or missing lockfile

2. if verification fails:

   • files have been modified since lockfile creation
   • either regenerate lockfile (aegis lock) or investigate changes

procedure 4: optional LLM-powered intent analysis

1. configure LLM access (one-time setup): aegis setup

   • input: interactive prompts for LLM provider, API key, local endpoint URL
   • output: ~/.aegis/config.yaml with encrypted or plaintext credentials (user choice)
   • security note: aegis does not enforce encryption; use env vars for better isolation

2. alternatively, set environment variable: export GEMINI_API_KEY="your-key-here"

   • input: API key string
   • output: config available to aegis CLI

3. run scan with LLM: aegis scan (omit --no-llm flag)

   • input: current directory or path, LLM config from env or file
   • output: additional "ephemeral" section in JSON report (LLM analysis, non-deterministic)
   • network: code snippet sent to configured LLM provider
   • privacy: code transmission only occurs with explicit config + scan without --no-llm

procedure 5: MCP server deployment (optional, for Cursor / Claude Desktop integration)

1. print MCP config: aegis mcp-config

   • input: none
   • output: JSON config block for MCP client

2. add to Cursor config file .cursor/mcp.json:

   {
     "mcpServers": {
       "aegis": {
         "command": "aegis",
         "args": ["mcp-serve"]
       }
     }
   }
   

   • input: JSON config object
   • output: aegis MCP server registered with Cursor

3. restart Cursor or Claude Desktop client.

   • input: none
   • output: aegis tools available in client (scan_skill, verify_lockfile, list_capabilities)

4. call tools from client:

   • input: skill path from UI
   • output: scan results in client chat

---

decision points

if LLM analysis is desired:

• user configures an API key (GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY) or local endpoint via aegis setup
• aegis runs scan with LLM by omitting --no-llm flag
• scanned code is sent to configured third-party provider (Google, OpenAI, Anthropic) or local server
• else: user runs with --no-llm (default, recommended), all analysis stays offline, no code transmission

if lockfile verification fails:

• lockfile Merkle root does not match current code
• either: regenerate lockfile with aegis lock (if changes are approved), or: investigate which files changed and decide if revert/approval is needed
• else: verification passes, skill code is unchanged since lockfile creation

if risk score exceeds acceptable threshold (e.g., > 60):

• skill has PROHIBITED findings (hardcoded secrets, reverse shells, obvious malware patterns)
• user should not install or should fork and remediate
• else: skill risk is acceptable, safe to install (or conditional approval based on RESTRICTED findings)

if running on skill with missing or incomplete SKILL.md:

• Skill Meta Analyzer cross-references declared intent vs actual code
• report flags mismatches (e.g., skill claims read-only filesystem access but actually writes)
• user manually reviews discrepancies before approval

if target path is a git repository:

• aegis respects .gitignore and skips ignored files (faster scan, avoids false positives on vendored code)
• else: scans all files in directory recursively

if network timeout or LLM provider unavailable (when LLM mode is enabled):

• deterministic static analysis completes normally
• LLM analysis section in JSON report is empty or contains error message
• scan succeeds, but ephemeral findings are unavailable
• user can rerun with --no-llm or retry after provider recovers

if API rate limit hit (LLM provider):

• aegis exits with rate-limit error after first request fails
• user waits and reruns scan, or uses --no-llm to skip LLM analysis

if aegis.lock file exists but is corrupted or has invalid Ed25519 signature:

• aegis verify fails immediately, no code comparison performed
• user regenerates lockfile with aegis lock

if no files match any scanner pattern (empty or minimal codebase):

• all scanners report zero findings
• risk_score_static = 0 (safe)
• persona assigned based on minimal logic (typically "Cracked Dev" or "LGTM")

---

output contract

on successful scan (aegis scan), two outputs are guaranteed:

1. console report (Rich formatted, human readable)

   • table: file-by-file findings (severity: CRITICAL, HIGH, MEDIUM, LOW, INFO)
   • section: capabilities detected (filesystem access, network, secrets, shell, etc.)
   • section: risk score (0-100 composite)
   • section: persona (e.g., "LGTM", "Permission Goblin", "The Snake")
   • section: summary (PROHIBITED vs RESTRICTED findings)

2. aegis_report.json (structured, machine parseable)

   • deterministic payload: Merkle root, file hashes, capabilities, findings (reproducible, signed)
   • ephemeral payload: LLM analysis, risk adjustment (present only if LLM enabled, non-deterministic)
   • format: valid JSON, parseable by jq or any JSON parser
   • fields: deterministic.risk_score_static, deterministic.findings[], deterministic.capabilities[], deterministic.persona, ephemeral.llm_analysis (if available)

on successful lockfile generation (aegis lock), one output is guaranteed:

1. aegis.lock (cryptographic lockfile)
   • format: JSON with Ed25519 signature and Merkle tree
   • fields: merkle_root, files[] (hash per file), signature, timestamp, aegis_version
   • invariant: identical to aegis_report.json deterministic payload, additionally signed
   • location: written to current directory (or specified path)

on successful lockfile verification (aegis verify), exit code signals result:

1. exit code 0: verification passed, Merkle root matches
2. exit code non-zero: verification failed (lockfile missing, corrupted, or code changed)
3. console output: PASS or FAIL message with details

on successful MCP config generation (aegis mcp-config), one output is guaranteed:

1. JSON config object (stdout)
   • format: valid MCP config for .cursor/mcp.json or equivalent
   • fields: mcpServers.aegis with command and args
   • ready to paste into Cursor or Claude Desktop config file

on JSON output request (--json flag), all outputs are JSON:

1. console report suppressed
2. only aegis_report.json printed to stdout
3. compatible with CI pipelines: aegis scan --json --no-llm | jq '.deterministic.risk_score_static'

error handling: on failure, exit code is non-zero and error message is printed to stderr:

1. missing path or unreadable directory: "path not found or not readable"
2. invalid YAML/JSON in config: "malformed config file"
3. aegis binary not found in PATH: "aegis command not found (install with pip or uv)"
4. Python < 3.11: "Python 3.11+ required"
5. network error during LLM request: "LLM provider unreachable"
6. corrupted lockfile: "lockfile signature verification failed"

---

outcome signal

you know the scan worked when:

1. console shows a colored report with findings, risk score, and persona assignment (takes 2-10 seconds)
2. aegis_report.json is written to disk in the current directory (or specified path)
3. risk_score_static is a number between 0-100 (0 = safe, 100 = do not install)
4. findings are listed with file paths, line numbers, severity, and CWE/OWASP mappings
5. capabilities are enumerated (e.g., "accesses /tmp", "opens TCP connections", "imports subprocess")

you know the lockfile was created when:

1. aegis.lock appears in the current directory
2. file contains Ed25519 signature (visible in JSON: "signature" field)
3. Merkle root matches the deterministic payload in aegis_report.json
4. lockfile is human-readable JSON (not binary)

you know verification passed when:

1. aegis verify exits with code 0
2. console prints "PASS: lockfile verified, code unchanged since [timestamp]"
3. no new findings reported

you know verification failed when:

1. aegis verify exits with non-zero code (typically 1)
2. console prints "FAIL: lockfile Merkle root mismatch" or "lockfile not found"
3. user must either regenerate lockfile or investigate code changes

you know LLM analysis ran when:

1. aegis_report.json contains an ephemeral section with non-empty llm_analysis
2. console report includes a "LLM Intent Check" section with prose analysis
3. risk adjustment (if any) is noted in the ephemeral payload
4. analysis includes reasoning about skill intent, potential misuse, trust profile

you know MCP server started when:

1. aegis mcp-serve command exits with no error
2. server listens on stdio (no port binding needed)
3. three tools are available to MCP client: scan_skill, verify_lockfile, list_capabilities
4. Cursor or Claude Desktop client can invoke tools without error

you know setup completed when:

1. aegis setup exits after prompts
2. ~/.aegis/config.yaml is created (check with cat ~/.aegis/config.yaml)
3. next scan can omit --no-llm and LLM analysis runs successfully

---

scanner reference

aegis runs 15+ specialized scanners covering OWASP Top 10, CWE-200 series (information exposure), CWE-600 series (OS command injection), and MITRE ATT&CK tactics:

scanner	detects	output
AST Parser	750+ Python function/method patterns (imports, network, filesystem, subprocess, crypto, eval, pickle, etc.)	capability map + risk patterns
Semgrep Rules	80+ regex rules for Python, JavaScript, YAML, secrets	line-referenced findings
Secret Scanner	API keys, tokens, private keys, connection strings (30+ patterns: AWS, GCP, Azure, etc.)	credential leaks with severity
Shell Analyzer	pipe-to-shell, reverse shells, inline exec, os.system, subprocess with shell=True	command injection risk
JS Analyzer	XSS, eval, prototype pollution, dynamic imports, innerHTML, Function() constructor	client-side vulnerability
Dockerfile Analyzer	privilege escalation (RUN as root), secrets in ENV/ARG, unpinned base images	supply chain + secrets
Config Analyzer	dangerous YAML/JSON/TOML/INI settings (e.g., insecure SSL, hardcoded credentials)	config risk
Social Engineering	misleading filenames (exe as .txt), Unicode tricks (lookalike chars), trust manipulation patterns	deception tactics
Steganography	hidden payloads in images, homoglyph attacks, font tricks	covert channels
Shadow Module Detector	stdlib-shadowing files (os.py, sys.py in the skill directory)	supply chain confusion
Combo Analyzer	multi-capability attack chains (exfiltration + command, C2 + persistence, ransomware signatures)	coordinated threats
Taint Analysis	source-to-sink data flows (user input -> commands, URLs, SQL, file paths)	injection chains
Complexity Analyzer	cyclomatic complexity per function, warns on >10 complexity (hard to audit)	maintainability + obscurity
Skill Meta Analyzer	SKILL.md vs actual code cross-referencing (declared permissions vs actual imports/calls)	intent mismatch
Persona Classifier	deterministic vibe check based on all findings	trust profile

---

persona meanings

aegis assigns each skill one of eight personas based on analysis:

• Cracked Dev: clean code, smart patterns, minimal permissions, high confidence
• LGTM: permissions match intent, scopes are sane, nothing weird, safe to install
• Trust Me Bro: polished on the outside, suspicious on the inside, claims vs code mismatch
• You Sure About That?: messy code, missing pieces, docs overpromise, quality concerns
• Co-Dependent Lover: tiny logic, huge dependency tree, supply chain risk