prism-scanner 0.1.0

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

: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.

---

Why Prism?

	Marketplace Trust Scores	Prism Scanner
Pre-install	:white_check_mark: Reputation score	:white_check_mark: Deep code analysis
Post-uninstall	:x:	:white_check_mark: Residue & persistence scan
Inspection	Black-box rating	Code-level, rule-by-rule
Platforms	Single ecosystem	ClawHub, MCP, npm, pip
Source	Closed	Open (Apache 2.0)
Execution	Requires upload	Local-first, offline OK

---

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

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:

Layer	Focus	Rules	Examples
1. Code Behavior (S1-S14)	What the code does	14	Shell execution, data exfiltration, SSRF, persistence mechanisms, unsafe deserialization, download-and-execute
2. Metadata (M1-M6, P1-P9)	What the package claims vs. contains	15	Hardcoded credentials, typo-squatting, install scripts, obfuscated payloads, prompt injection, suspicious domains
3. System Residue (R1-R10)	What was left behind	10	LaunchAgents, crontab entries, shell config pollution, orphaned credentials, systemd units, login items

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

Grade	Label	Meaning	Recommendation
A	Safe	No findings or only informational	Safe to use
B	Notice	Only LOW severity findings	Likely safe — minor observations
C	Caution	1-4 MEDIUM findings	Review before use — warrants manual inspection
D	Danger	1-2 HIGH, or 5+ MEDIUM	Use in sandbox only — significant risks
F	Critical	Any CRITICAL, or 3+ HIGH	Do not install — critical security risks

---

Output Formats

# Rich terminal output (default)
prism scan ./skill/

# Machine-readable JSON
prism scan ./skill/ --format json

# Standalone HTML report
prism scan ./skill/ --format html -o report.html

# SARIF for GitHub Code Scanning
prism scan ./skill/ --format sarif -o results.sarif

---

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  # 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.

---

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.