{
  "markdown": "# :large_blue_diamond: Prism Scanner\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776ab?style=flat-square&logo=python&logoColor=white)](https://python.org)\n[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square)](LICENSE)\n[![Tests: 40 passed](https://img.shields.io/badge/tests-40%20passed-brightgreen?style=flat-square)]()\n[![Version: 0.2.2](https://img.shields.io/badge/version-0.2.2-7b2ff7?style=flat-square)]()\n[![Awesome](https://img.shields.io/badge/Awesome-AI%20Security-fc60a8?style=flat-square&logo=awesomelists&logoColor=white)](https://github.com/TalEliyahu/Awesome-AI-Security)\n\n**Security scanner for AI Agent skills, plugins, and MCP servers.**\n\n<!-- mcp-name: io.github.aidongise-cell/prism-scanner -->\n\nPrism analyzes code for malicious behavior *before* you install it — and checks your system for leftover threats *after* you uninstall.\n\n> 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.\n\n---\n\n## :sparkles: What's new in v0.2.x\n\n- **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.\n- **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:\n  ```bash\n  prism scan ./dist --fail-on high\n  ```\n- **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).\n- **41 detection rules total** across S1–S14 (behavior), M1–M7 (metadata + publish hygiene), P1–P10 (patterns + manipulation), and R1–R10 (residue).\n- 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.\n\n---\n\n## Why Prism?\n\n|                    | Marketplace Trust Scores | **Prism Scanner** |\n|--------------------|:------------------------:|:-----------------:|\n| **Pre-install**    | :white_check_mark: Reputation score    | :white_check_mark: Deep code analysis         |\n| **Post-uninstall** | :x:                      | :white_check_mark: Residue & persistence scan |\n| **Inspection**     | Black-box rating         | Code-level, rule-by-rule |\n| **Platforms**      | Single ecosystem         | ClawHub, MCP, npm, pip   |\n| **Source**         | Closed                   | Open (Apache 2.0)        |\n| **Execution**      | Requires upload          | Local-first, offline OK  |\n\n---\n\n## Quick Start\n\n```bash\npip install prism-scanner\n\n# Scan a local skill directory\nprism scan ./my-skill/\n\n# Scan a GitHub repo directly\nprism scan https://github.com/user/skill-repo\n\n# Check your system for agent residue\nprism clean --scan\n\n# Generate a cleanup plan (non-destructive)\nprism clean --plan\n\n# Execute cleanup with automatic backups\nprism clean --apply\n```\n\n### Homebrew (macOS)\n\n```bash\nbrew tap prismlab/tools\nbrew install prism-scanner\n```\n\n### npx (no install needed)\n\n```bash\nnpx prism-scanner scan https://github.com/user/skill-repo\n```\n\n### GitHub Action (CI/CD)\n\nAdd Prism to your CI pipeline — findings appear in GitHub's Security tab:\n\n```yaml\n# .github/workflows/prism-scan.yml\nname: Prism Security Scan\non: [push, pull_request]\n\npermissions:\n  security-events: write\n  contents: read\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: aidongise-cell/prism-scanner@main\n        with:\n          path: '.'\n          fail-on: 'high'\n```\n\n### MCP Server (Claude Desktop / Cursor / VS Code)\n\nPrism Scanner can run as an MCP server, giving AI assistants direct access to security scanning tools.\n\n```bash\npip install \"prism-scanner[mcp]\"\n```\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"prism-scanner\": {\n      \"command\": \"prism-mcp\"\n    }\n  }\n}\n```\n\nOr for Claude Code:\n\n```bash\nclaude mcp add prism-scanner prism-mcp\n```\n\nThis exposes 4 tools: `prism_scan`, `prism_grade`, `prism_clean_scan`, `prism_clean_plan`.\n\n### Docker\n\n```bash\n# Build the image\ndocker build -t prism-scanner .\n\n# Scan a local directory\ndocker run -v $(pwd)/my-skill:/workspace/target:ro prism-scanner scan /workspace/target\n\n# Scan a remote repo\ndocker run prism-scanner scan https://github.com/user/skill-repo\n\n# Generate HTML report\ndocker run -v $(pwd):/workspace/output prism-scanner scan https://github.com/user/repo --format html -o /workspace/output/report.html\n```\n\nOr use the published image:\n```bash\ndocker run ghcr.io/prismlab/prism-scanner scan <target>\n```\n\n---\n\n## What It Detects\n\nPrism operates across **3 analysis layers**, each targeting a different phase of the agent lifecycle:\n\n| Layer | Focus | Rules | Examples |\n|-------|-------|:-----:|---------|\n| **1. Code Behavior** (S1-S14) | What the code *does* | 14 | Shell execution, data exfiltration, SSRF, persistence mechanisms, unsafe deserialization, download-and-execute |\n| **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 |\n| **3. System Residue** (R1-R10) | What was *left behind* | 10 | LaunchAgents, crontab entries, shell config pollution, orphaned credentials, systemd units, login items |\n\n**Total: 39 detection rules** with lightweight intra-file taint analysis.\n\n---\n\n## Example Output\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n  Prism Scanner v0.1.0\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n  Target: evil_skill\n  Platform: clawhub\n  Duration: 42ms\n\n[1/3] Behavior Analysis\n  ✗ CRITICAL  S8    Data exfiltration: secrets sent to external endpoint  evil_skill.py:10\n  ✗ CRITICAL  S10   Download and execute: fetches remote payload          evil_skill.py:24\n  ✗ HIGH      S1    Shell execution with untrusted input                  evil_skill.py:14\n  ✗ HIGH      S13   Persistence: writes LaunchAgent plist                 evil_skill.py:36\n  ⚠ MEDIUM    S6    Dynamic code execution (eval/exec)                    evil_skill.py:21\n\n[2/3] Metadata Analysis\n  ✗ CRITICAL  P1    Hardcoded credential: AWS Access Key                  evil_skill.py:47\n  ⚠ MEDIUM    P2    Base64-encoded executable content                     evil_skill.py:50\n  ⚠ MEDIUM    P6    Prompt injection pattern in string literal            evil_skill.py:53\n\n[3/3] Residue Scan\n  (skipped — use `prism clean --scan` for system-level checks)\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n  Grade: F (Critical)\n\n  Key Risks:\n    ▸ CRITICAL: Data exfiltration to external endpoint (S8)\n    ▸ CRITICAL: Download and execute remote payload (S10)\n    ▸ CRITICAL: Hardcoded AWS credential (P1)\n    ▸ HIGH: Shell execution with user input (S1)\n    ▸ HIGH: Persistence mechanism installed (S13)\n\n  Behavior Profile:\n    exfiltrates_data, executes_shell, downloads_and_executes, installs_persistence\n\n  Recommendation: DO NOT INSTALL — Critical security risks detected.\n\n  Findings: 3 critical, 2 high, 3 medium\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n---\n\n## Grading System\n\n| Grade | Label | Meaning | Recommendation |\n|:-----:|-------|---------|----------------|\n| **A** | Safe | No findings or only informational | Safe to use |\n| **B** | Notice | Only LOW severity findings | Likely safe — minor observations |\n| **C** | Caution | 1-4 MEDIUM findings | Review before use — warrants manual inspection |\n| **D** | Danger | 1-2 HIGH, or 5+ MEDIUM | Use in sandbox only — significant risks |\n| **F** | Critical | Any CRITICAL, or 3+ HIGH | **Do not install** — critical security risks |\n\n---\n\n## Output Formats\n\n```bash\n# Rich terminal output (default) — color-coded severity, grade highlighting\nprism scan ./skill/\n\n# Machine-readable JSON\nprism scan ./skill/ --format json\n\n# Standalone HTML report — dark-themed, self-contained, shareable\nprism scan ./skill/ --format html -o report.html\n\n# SARIF for GitHub Code Scanning\nprism scan ./skill/ --format sarif -o results.sarif\n```\n\n### HTML Report\n\nGenerate a **standalone, self-contained HTML report** with full findings, grade visualization, and risk breakdown — perfect for sharing with teammates or archiving:\n\n```bash\nprism scan https://github.com/user/skill-repo --format html -o report.html\n```\n\nThe 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.\n\n---\n\n## CI/CD Integration\n\nAdd Prism to your GitHub Actions workflow to gate deployments on security findings:\n\n```yaml\nname: Security Scan\non: [push, pull_request]\n\njobs:\n  prism-scan:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: Set up Python\n        uses: actions/setup-python@v5\n        with:\n          python-version: \"3.12\"\n\n      - name: Install Prism Scanner\n        run: pip install prism-scanner\n\n      - name: Run security scan\n        run: prism scan . --format sarif -o results.sarif --fail-on high\n\n      - name: Upload SARIF results\n        if: always()\n        uses: github/codeql-action/upload-sarif@v3\n        with:\n          sarif_file: results.sarif\n```\n\nThe `--fail-on` flag exits with code 1 if any finding meets or exceeds the specified severity (`critical`, `high`, or `medium`), failing the CI pipeline.\n\n---\n\n## Key Features\n\n- **Taint Analysis** — Tracks data flow from sources (env vars, user input) to sinks (shell, network) within each file\n- **Multi-Platform** — Scans ClawHub skills, MCP servers, npm packages, and pip packages with platform-aware rules\n- **Zero Dependencies on Target** — Pure static analysis; never executes scanned code\n- **Residue Scanner** — Detects persistence mechanisms, shell config pollution, and credential leaks left by uninstalled tools\n- **Safe Cleanup** — Three-tier workflow (`scan` -> `plan` -> `apply`) with automatic backup and `--rollback`\n- **Suppression** — Use `.prismignore` to suppress known findings by rule ID with justification\n- **Offline Mode** — Run with `--offline` to skip all external lookups\n\n---\n\n## Adding Custom Rules\n\nDetection rules are defined in YAML files under the `rules/` directory:\n\n```\nrules/\n├── malicious_signatures.yaml   # Known malicious code signatures and hashes\n├── permissions.yaml            # Permission baseline definitions\n└── suspicious_domains.yaml     # C2 domains, dynamic DNS, disposable TLDs\n```\n\nThe 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.\n\n---\n\n## Project Structure\n\n```\nsrc/prism/\n├── cli.py                  # CLI entry point and output formatting\n├── scanner.py              # Orchestrator — runs engines, collects findings\n├── models.py               # Finding, ScanResult, Severity, Layer data models\n├── scoring.py              # Letter-grade risk assessment (A-F)\n├── report.py               # HTML report generator\n├── fetcher.py              # Git clone / URL fetching with security guards\n├── cleaner.py              # System cleanup: plan, apply, rollback\n├── suppression.py          # .prismignore parsing\n├── rules_loader.py         # YAML rule loading\n└── engines/\n    ├── ast_engine.py       # AST-based analysis (S1-S14)\n    ├── pattern_engine.py   # Regex pattern matching (P1-P9)\n    ├── manifest_engine.py  # Metadata & manifest analysis (M1-M6)\n    ├── residue_engine.py   # System residue scanner (R1-R10)\n    └── taint.py            # Intra-file taint tracking\n```\n\n---\n\n## Contributing\n\nContributions are welcome. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:\n\n- Adding new detection rules\n- Writing and running tests\n- Code style and commit conventions\n\n---\n\n## License\n\n[Apache License 2.0](LICENSE) — free for commercial and personal use.\n\n---\n\n## Prism Verified Badge\n\nShow that your project has been scanned by Prism. Add a badge to your README:\n\n**Grade A (Safe):**\n```markdown\n[![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)\n```\n\n**All grades:**\n\n| Grade | Badge |\n|:-----:|-------|\n| A | `![Prism Grade A](https://img.shields.io/badge/Prism-Grade%20A-brightgreen?style=flat-square)` |\n| B | `![Prism Grade B](https://img.shields.io/badge/Prism-Grade%20B-green?style=flat-square)` |\n| C | `![Prism Grade C](https://img.shields.io/badge/Prism-Grade%20C-yellow?style=flat-square)` |\n| D | `![Prism Grade D](https://img.shields.io/badge/Prism-Grade%20D-orange?style=flat-square)` |\n| F | `![Prism Grade F](https://img.shields.io/badge/Prism-Grade%20F-red?style=flat-square)` |\n\nPreview:\n\n[![Prism Grade A](https://img.shields.io/badge/Prism-Grade%20A-brightgreen?style=flat-square)](https://github.com/aidongise-cell/prism-scanner) [![Prism Grade B](https://img.shields.io/badge/Prism-Grade%20B-green?style=flat-square)](https://github.com/aidongise-cell/prism-scanner) [![Prism Grade C](https://img.shields.io/badge/Prism-Grade%20C-yellow?style=flat-square)](https://github.com/aidongise-cell/prism-scanner) [![Prism Grade D](https://img.shields.io/badge/Prism-Grade%20D-orange?style=flat-square)](https://github.com/aidongise-cell/prism-scanner) [![Prism Grade F](https://img.shields.io/badge/Prism-Grade%20F-red?style=flat-square)](https://github.com/aidongise-cell/prism-scanner)\n\n---\n\n## Support\n\nIf 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.\n\n[![Star on GitHub](https://img.shields.io/github/stars/aidongise-cell/prism-scanner?style=social)](https://github.com/aidongise-cell/prism-scanner)\n\n---\n\n## Acknowledgments\n\nPrism 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.\n",
  "bytes": 14939,
  "sha": "7a7c98119d88680049074be918389630c646344a9e2583eb19afd8e08756d58a",
  "repo_slug": "aidongise-cell/prism-scanner",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aidongise_cell_prism_scanner_d29caead/readme"
}