Prism Scanner

:large_blue_diamond: Prism Scanner

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:

  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 directory

prism scan ./my-skill/

Scan a GitHub repo directly

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

Check your system for agent residue

prism clean --scan

Generate a cleanup plan (non-destructive)

prism clean --plan

Execute cleanup with automatic backups

prism clean --apply

Homebrew (macOS)

brew tap prismlab/tools

brew 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.yml

name: Prism Security Scan on: [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 image

docker build -t prism-scanner .

Scan a local directory

docker run -v $(pwd)/my-skill:/workspace/target:ro prism-scanner scan /workspace/target

Scan a remote repo

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

Generate HTML report

docker 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 highlighting

prism scan ./skill/

Machine-readable JSON

prism scan ./skill/ --format json

Standalone HTML report — dark-themed, self-contained, shareable

prism scan ./skill/ --format html -o report.html

SARIF for GitHub Code Scanning

prism 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 Scan

on: [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 # M