Prism Scanner

:large_blue_diamond: Prism Scanner

用于扫描 AI Agent 技能、插件和 MCP 服务的安全工具。

Prism 会在你安装代码之前分析其中的恶意行为，并在你卸载后检查系统是否残留威胁。

与仅依据市场评分判断可信度的工具不同，Prism 可在整个生命周期提供全面覆盖和代码级透明度，涵盖安装前、运行时和卸载后，支持所有平台，并且完全开源。

---

:sparkles: v0.2.x 新内容

• P10 — Agent 心理操纵检测：检测嵌入技能描述、提示词和代码字符串中的煤气灯操纵、内疚诱导、冒充权威、紧迫施压和情感胁迫模式。此功能基于 Northeastern、Harvard 和 MIT 关于对话式操纵 AI Agent 的研究。据我们所知，这是首个针对这类攻击的开源自动检测工具。
• M7 — 发布卫生检查：在发布前检查并发现源映射、.env 文件、私钥、IDE 配置和包管理器凭据。此功能的灵感来自 Anthropic 于 2026 年 4 月发生的源映射泄露事件，该事件通过 npm 暴露了 512K 行 Claude Code 内部代码。将其接入 CI：

  prism scan ./dist --fail-on high
  

• 在真实技能上的误报减少了 47–93%（引擎修复涉及 S1、S4、S8、S12；已使用 3 个此前会产生大量误报的 ClawHub 代表性技能进行验证）。
• S1–S14（行为）、M1–M7（元数据与发布卫生）、P1–P10（模式与操纵）以及 R1–R10（残留）共包含 41 条检测规则。
• v0.2.2 修复了版本字符串的外观问题（升级到 0.2.1 后，prism --version 仍会报告 0.1.3）；检测行为与 v0.2.1 完全相同。

---

为什么选择 Prism？

	市场可信度评分	Prism Scanner
安装前	:white_check_mark: 信誉评分	:white_check_mark: 深度代码分析
卸载后	:x:	:white_check_mark: 残留与持久化扫描
检查方式	黑箱评分	代码级，逐条规则检查
平台	单一生态系统	ClawHub、MCP、npm、pip
源代码	闭源	开源（Apache 2.0）
执行方式	需要上传	本地优先，可离线运行

---

快速开始

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（无需安装）

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

GitHub Action（CI/CD）

将 Prism 添加到 CI 流水线，扫描结果会显示在 GitHub 的 Security 标签页中：

# .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 服务（Claude Desktop / Cursor / VS Code）

Prism Scanner 可以作为 MCP 服务运行，让 AI 助手直接使用安全扫描工具。

pip install "prism-scanner[mcp]"

将其添加到 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）：

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

或者用于 Claude Code：

claude mcp add prism-scanner prism-mcp

这会提供 4 个工具：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

或者使用已发布的镜像：

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

---

检测内容

Prism 涵盖 3 个分析层，分别针对 Agent 生命周期的不同阶段：

层级	关注点	规则数	示例
1. 代码行为（S1-S14）	代码做了什么	14	Shell 执行、数据外泄、SSRF、持久化机制、不安全的反序列化、下载并执行
2. 元数据（M1-M6、P1-P9）	软件包声称的内容与实际包含的内容	15	硬编码凭据、拼写仿冒、安装脚本、混淆的有效载荷、提示词注入、可疑域名
3. 系统残留（R1-R10）	遗留下来的内容	10	LaunchAgents、crontab 条目、Shell 配置污染、遗留凭据、systemd 单元、登录项

共 39 条检测规则，并配备轻量级文件内污点分析。

---

示例输出

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  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
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

评级系统

等级	标签	含义	建议
A	安全	没有发现项，或仅有提示信息	可安全使用
B	提醒	仅有低严重性发现项	基本安全——有少量需要留意的问题
C	谨慎	有 1-4 项中严重性发现	使用前请审查——建议手动检查
D	危险	有 1-2 项高严重性发现，或 5 项以上中严重性发现	仅在沙箱中使用——存在重大风险
F	严重	存在任何严重级别发现，或有 3 项以上高严重性发现	请勿安装——存在严重安全风险

---

输出格式

# 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 报告

生成独立、完整的 HTML 报告，包含完整的发现项、评级可视化和风险细分，非常适合与团队成员分享或存档：

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

HTML 报告采用深色主题界面，以颜色区分严重性级别，提供交互式评级环和完整的发现项表格。无需外部依赖——只需在任意浏览器中打开 .html 文件。

---

CI/CD 集成

将 Prism 添加到 GitHub Actions 工作流中，根据安全发现项控制部署：

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

如果任何发现项达到或超过指定严重性级别（critical、high 或 medium），--fail-on 标志会以代码 1 退出，从而使 CI 流水线失败。

---

主要功能

• 污点分析 — 跟踪每个文件中从来源（环境变量、用户输入）到接收端（Shell、网络）的数据流
• 多平台支持 — 使用针对平台定制的规则扫描 ClawHub 技能、MCP 服务、npm 软件包和 pip 软件包
• 目标零依赖 — 纯静态分析；绝不执行扫描的代码
• 残留扫描器 — 检测已卸载工具留下的持久化机制、Shell 配置污染和凭据泄漏
• 安全清理 — 三阶段工作流（scan -> plan -> apply），支持自动备份和 --rollback
• 抑制发现项 — 使用 .prismignore，通过规则 ID 和理由抑制已知发现项
• 离线模式 — 使用 --offline 跳过所有外部查询

---

添加自定义规则

检测规则定义在 rules/ 目录下的 YAML 文件中：

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

模式引擎（P1-P9）和清单引擎（M1-M6）会在扫描时从这些文件加载规则。添加条目即可扩展检测能力，无需修改 Python 代码。

---

项目结构

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.md：

• 添加新的检测规则
• 编写和运行测试
• 代码风格和提交规范

---

许可证

Apache License 2.0 — 可免费用于商业和个人用途。

---

Prism 已验证徽章

展示你的项目已通过 Prism 扫描。在 README 中添加徽章：

A级（安全）：

[![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)

所有等级：

等级	徽章
A	
B	
C	
D	
F	

预览：

---

支持

如果 Prism Scanner 帮你发现了安全风险，或让你感到安心，请考虑在 GitHub 上为它点亮一颗 ⭐——这有助于其他人发现这个项目，也能让开发持续下去。

---

致谢

Prism Scanner 由 Prism Lab 开发，旨在弥补 AI Agent 生态中的一项空白：缺少能够跨平台运行并覆盖 Agent 完整生命周期的透明代码级安全工具。我们相信，开发者在信任某项技能或插件并允许其访问自己的系统之前，有权准确了解它的作用。