Prism Scanner

:large_blue_diamond: Prism Scanner

[Python 3.10+] [License: Apache 2.0] [Tests: 40 passed] [Version: 0.2.2] [Awesome]

Security scanner for AI Agent skills, plugins, and MCP servers.

Prism analyzes code for malicious behavior before you install it — and checks your system for leftover threats after you uninstall.

Unlike marketplace-only trust scores, Prism gives you full lifecycle coverage with code-level transparency — pre-install, runtime, and post-uninstall — across every platform, completely open source.

:sparkles: What's new in v0.2.x

• P10 — Agent psychological manipulation detection: detects gaslighting, guilt-tripping, authority impersonation, urgency pressure, and emotional coercion patterns embedded in skill descriptions, prompts, and code strings. Based on Northeastern/Harvard/MIT research on conversational manipulation of AI agents — to our knowledge, the first open-source automated detector for this attack class.
• M7 — Publish hygiene checks: catches source maps, .env files, private keys, IDE configs, and package-manager credentials before they ship. Inspired by Anthropic's April 2026 source-map leak that exposed 512K lines of Claude Code internals via npm. Wire it into your CI:
  bash

  prism scan ./dist --fail-on high

• 47–93% fewer false positives on real-world skills (S1, S4, S8, S12 engine fixes; validated against 3 representative ClawHub skills that previously flooded with false flags).
• 41 detection rules total across S1–S14 (behavior), M1–M7 (metadata + publish hygiene), P1–P10 (patterns + manipulation), and R1–R10 (residue).
• v0.2.2 fixes a cosmetic version-string mismatch (prism --version reported 0.1.3 after upgrading to 0.2.1); detection behavior is identical to v0.2.1.

Why Prism?

Quick Start

pip install prism-scanner
# Scan a local skill directoryprism scan ./my-skill/
# Scan a GitHub repo directlyprism scan https://github.com/user/skill-repo
# Check your system for agent residueprism clean --scan
# Generate a cleanup plan (non-destructive)prism clean --plan
# Execute cleanup with automatic backupsprism clean --apply

Homebrew (macOS)

brew tap prismlab/toolsbrew install prism-scanner

npx (no install needed)

npx prism-scanner scan https://github.com/user/skill-repo

GitHub Action (CI/CD)

Add Prism to your CI pipeline — findings appear in GitHub's Security tab:

# .github/workflows/prism-scan.ymlname: Prism Security Scanon: [push, pull_request]
permissions:  security-events: write  contents: read
jobs:  scan:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - uses: aidongise-cell/prism-scanner@main        with:          path: '.'          fail-on: 'high'

MCP Server (Claude Desktop / Cursor / VS Code)

Prism Scanner can run as an MCP server, giving AI assistants direct access to security scanning tools.

pip install "prism-scanner[mcp]"

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{  "mcpServers": {    "prism-scanner": {      "command": "prism-mcp"    }  }}

Or for Claude Code:

claude mcp add prism-scanner prism-mcp

This exposes 4 tools: prism_scan, prism_grade, prism_clean_scan, prism_clean_plan.

Docker

# Build the imagedocker build -t prism-scanner .
# Scan a local directorydocker run -v $(pwd)/my-skill:/workspace/target:ro prism-scanner scan /workspace/target
# Scan a remote repodocker run prism-scanner scan https://github.com/user/skill-repo
# Generate HTML reportdocker run -v $(pwd):/workspace/output prism-scanner scan https://github.com/user/repo --format html -o /workspace/output/report.html

Or use the published image:

docker run ghcr.io/prismlab/prism-scanner scan <target>

What It Detects

Prism operates across 3 analysis layers, each targeting a different phase of the agent lifecycle:

Total: 39 detection rules with lightweight intra-file taint analysis.

Example Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  Prism Scanner v0.1.0━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Target: evil_skill  Platform: clawhub  Duration: 42ms
[1/3] Behavior Analysis  ✗ CRITICAL  S8    Data exfiltration: secrets sent to external endpoint  evil_skill.py:10  ✗ CRITICAL  S10   Download and execute: fetches remote payload          evil_skill.py:24  ✗ HIGH      S1    Shell execution with untrusted input                  evil_skill.py:14  ✗ HIGH      S13   Persistence: writes LaunchAgent plist                 evil_skill.py:36  ⚠ MEDIUM    S6    Dynamic code execution (eval/exec)                    evil_skill.py:21
[2/3] Metadata Analysis  ✗ CRITICAL  P1    Hardcoded credential: AWS Access Key                  evil_skill.py:47  ⚠ MEDIUM    P2    Base64-encoded executable content                     evil_skill.py:50  ⚠ MEDIUM    P6    Prompt injection pattern in string literal            evil_skill.py:53
[3/3] Residue Scan  (skipped — use `prism clean --scan` for system-level checks)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  Grade: F (Critical)
  Key Risks:    ▸ CRITICAL: Data exfiltration to external endpoint (S8)    ▸ CRITICAL: Download and execute remote payload (S10)    ▸ CRITICAL: Hardcoded AWS credential (P1)    ▸ HIGH: Shell execution with user input (S1)    ▸ HIGH: Persistence mechanism installed (S13)
  Behavior Profile:    exfiltrates_data, executes_shell, downloads_and_executes, installs_persistence
  Recommendation: DO NOT INSTALL — Critical security risks detected.
  Findings: 3 critical, 2 high, 3 medium━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Grading System

Output Formats

# Rich terminal output (default) — color-coded severity, grade highlightingprism scan ./skill/
# Machine-readable JSONprism scan ./skill/ --format json
# Standalone HTML report — dark-themed, self-contained, shareableprism scan ./skill/ --format html -o report.html
# SARIF for GitHub Code Scanningprism scan ./skill/ --format sarif -o results.sarif

HTML Report

Generate a standalone, self-contained HTML report with full findings, grade visualization, and risk breakdown — perfect for sharing with teammates or archiving:

prism scan https://github.com/user/skill-repo --format html -o report.html

The HTML report features a dark-themed UI with color-coded severity levels, an interactive grade ring, and a complete findings table. No external dependencies — just open the .html file in any browser.

CI/CD Integration

Add Prism to your GitHub Actions workflow to gate deployments on security findings:

name: Security Scanon: [push, pull_request]
jobs:  prism-scan:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4
      - name: Set up Python        uses: actions/setup-python@v5        with:          python-version: "3.12"
      - name: Install Prism Scanner        run: pip install prism-scanner
      - name: Run security scan        run: prism scan . --format sarif -o results.sarif --fail-on high
      - name: Upload SARIF results        if: always()        uses: github/codeql-action/upload-sarif@v3        with:          sarif_file: results.sarif

The --fail-on flag exits with code 1 if any finding meets or exceeds the specified severity (critical, high, or medium), failing the CI pipeline.

Key Features

• Taint Analysis — Tracks data flow from sources (env vars, user input) to sinks (shell, network) within each file
• Multi-Platform — Scans ClawHub skills, MCP servers, npm packages, and pip packages with platform-aware rules
• Zero Dependencies on Target — Pure static analysis; never executes scanned code
• Residue Scanner — Detects persistence mechanisms, shell config pollution, and credential leaks left by uninstalled tools
• Safe Cleanup — Three-tier workflow (scan -> plan -> apply) with automatic backup and --rollback
• Suppression — Use .prismignore to suppress known findings by rule ID with justification
• Offline Mode — Run with --offline to skip all external lookups

Adding Custom Rules

Detection rules are defined in YAML files under the rules/ directory:

rules/├── malicious_signatures.yaml   # Known malicious code signatures and hashes├── permissions.yaml            # Permission baseline definitions└── suspicious_domains.yaml     # C2 domains, dynamic DNS, disposable TLDs

The pattern engine (P1-P9) and manifest engine (M1-M6) load rules from these files at scan time. Add entries to extend detection without modifying Python code.

Project Structure

src/prism/├── cli.py                  # CLI entry point and output formatting├── scanner.py              # Orchestrator — runs engines, collects findings├── models.py               # Finding, ScanResult, Severity, Layer data models├── scoring.py              # Letter-grade risk assessment (A-F)├── report.py               # HTML report generator├── fetcher.py              # Git clone / URL fetching with security guards├── cleaner.py              # System cleanup: plan, apply, rollback├── suppression.py          # .prismignore parsing├── rules_loader.py         # YAML rule loading└── engines/    ├── ast_engine.py       # AST-based analysis (S1-S14)    ├── pattern_engine.py   # Regex pattern matching (P1-P9)    ├── manifest_engine.py  # Metadata & manifest analysis (M1-M6)    ├── residue_engine.py   # System residue scanner (R1-R10)    └── taint.py            # Intra-file taint tracking

Contributing

Contributions are welcome. Please see CONTRIBUTING.md for guidelines on:

• Adding new detection rules
• Writing and running tests
• Code style and commit conventions

License

Apache License 2.0 — free for commercial and personal use.

Prism Verified Badge

Show that your project has been scanned by Prism. Add a badge to your README:

Grade A (Safe):

[![Prism Grade A](https://img.shields.io/badge/Prism-Grade%20A-brightgreen?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAxTDMgNXY2YzAgNS41NSAzLjg0IDEwLjc0IDkgMTIgNS4xNi0xLjI2IDktNi40NSA5LTEyVjVsLTktNHoiLz48L3N2Zz4=)](https://github.com/aidongise-cell/prism-scanner)

All grades:

Preview:

[Prism Grade A] [Prism Grade B] [Prism Grade C] [Prism Grade D] [Prism Grade F]

Support

If Prism Scanner helped you catch a security risk or gave you peace of mind, please consider giving it a ⭐ on GitHub — it helps others discover the project and keeps development going.

[Star on GitHub]

Acknowledgments

Prism Scanner is developed by Prism Lab to address a gap in the AI agent ecosystem: the lack of transparent, code-level security tooling that works across platforms and covers the full agent lifecycle. We believe developers deserve to understand exactly what a skill or plugin does before trusting it with their system.