sparkst/secureclaw
GitHub: sparkst/secureclaw
跨平台提示注入扫描器，帮助 AI 工具用户检测本地文件中的恶意注入模式并评估 AI 编程助手的安全配置。
Stars: 1 | Forks: 0
# SecureClaw
**面向 AI 工具用户的跨平台提示注入扫描器。**
你的 AI 会读取你的文件。请确保这些文件没有试图劫持它。
由 [Sparkry AI](https://sparkry.ai) 为使用 Claude Code、Cursor 和 OpenClaw 等 AI 工具的独立创始人打造。
## 快速开始
### 安装
**方式 1：pipx（推荐 — 隔离环境，无冲突）**
```
# macOS
brew install pipx
pipx install git+https://github.com/sparkst/secureclaw.git
# Linux / Windows
python3 -m pip install --user pipx
pipx install git+https://github.com/sparkst/secureclaw.git
```
**方式 2：在虚拟环境中使用 pip**
```
python3 -m venv ~/.secureclaw-venv
source ~/.secureclaw-venv/bin/activate # Windows: .secureclaw-venv\Scripts\activate
pip install git+https://github.com/sparkst/secureclaw.git
```
**方式 3：单文件下载（无需 pip）**
```
curl -sL https://raw.githubusercontent.com/sparkst/secureclaw/main/dist/secureclaw.py -o secureclaw.py
python3 secureclaw.py scan .
```
### 运行
```
# 扫描当前目录
secureclaw scan .
# 扫描特定 AI 工具目录
secureclaw scan ~/.claude ~/.cursor ~/Documents
# 检查您的 AI 工具安全态势
secureclaw posture
# 生成 HTML 报告
secureclaw scan . --format html -o report.html
# 用于 CI/CD 的 JSON 输出
secureclaw scan . --format json --fail-on-high
```
## 功能特性
- **零依赖** - 纯 Python 标准库，只要有 Python 3.9+ 即可运行
- **跨平台** - 支持 macOS、Linux、Windows，并带有自动路径处理
- **解码后扫描** - 剥离零宽度 Unicode 字符，进行 NFKC 标准化，解码 HTML 实体和 base64，以捕获经过编码的注入内容
- **允许列表系统** - 通过经过 HMAC 完整性检查的允许列表来消除误报
- **自动修复** - 自动编辑泄露的凭证并消除误报
- **三种输出格式** - 终端（彩色）、独立的 HTML、用于 CI/CD 的带版本号的 JSON
- **规范的退出代码** - `0` 干净，`1` 发现问题，`2` 用户错误，`3` 内部错误
## 它的工作内容
SecureClaw 会扫描你的文件，查找跨三个严重级别的 **28 种已知提示注入模式**：
- **极高风险** - 主动数据外泄、身份劫持、越狱尝试
- **高风险** - 指令覆盖、隐藏文本、凭证请求
- **建议** - 值得审查的可疑模式
它还会检查你 AI 工具的安全态势：
- Claude Code 设置、权限和 MCP 服务器
- Cursor 配置和规则
- OpenClaw 技能和计划任务
- 下载/文档目录中的危险脚本
- 浏览器缓存目录
## 工作原理
```
┌──────────────────────────────────────────────────────┐
│ SecureClaw Architecture │
└──────────────────────────────────────────────────────┘
┌──────────┐ ┌───────────────────────────────────────────────────┐
│ Target │ │ Scan Pipeline │
│ Directory │───▶│ │
│ │ │ ┌─────────┐ ┌──────────┐ ┌────────────────┐ │
└──────────┘ │ │ File │ │ Binary │ │ Encoding │ │
│ │ Walker │──▶│ Detector │──▶│ Handler │ │
┌──────────┐ │ │(pathlib)│ │(null-byte│ │(utf-8 + │ │
│ Allowlist│ │ └─────────┘ │ check) │ │ errors=replace)│ │
│ (JSON + │ │ └──────────┘ └───────┬────────┘ │
│ HMAC) │ │ │ │
└────┬─────┘ │ Decode-then-Scan Pipeline │
│ │ ┌──────────┐ ┌──────────┐ ┌──────┴───────┐ │
│ │ │ Strip │ │ Unicode │ │ HTML Entity │ │
│ │ │ Zero- │──▶│ NFKC │──▶│ Decode │ │
│ │ │ Width │ │ Normalize│ │ │ │
│ │ │ Chars │ │ │ └──────┬───────┘ │
│ │ └──────────┘ └──────────┘ │ │
│ │ ┌──────────▼─────────┐ │
│ │ │ Pattern Engine │ │
│ │ │ 28 rules (JSON) │ │
│ │ │ + Base64 decode │ │
│ │ └──────────┬─────────┘ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌─────▼──────┐ │
└────────▶│ │ Allowlist│──▶│ Dedup │──▶│ Sort by │ │
│ │ Filter │ │ (file + │ │ Severity │ │
│ │ │ │ line + │ │ │ │
│ │ │ │ pattern)│ │ │ │
│ └──────────┘ └──────────┘ └─────┬──────┘ │
│ │ │
└─────────────────────────────────────┼────────────┘
│
┌────────────────────────────────────┼────────────┐
│ Reporters │ │
│ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Terminal │ │ HTML │ │ JSON │ │
│ │ (ANSI │ │ (Self- │ │ (Schema │ │
│ │ auto- │ │ contained │ │ v1 for │ │
│ │ detect)│ │ + Sparkry │ │ CI/CD) │ │
│ │ │ │ branded) │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────┐
│ Security Posture Analyzer │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Claude │ │ Cursor │ │ OpenClaw │ │
│ │ Code │ │ AI │ │ │ │
│ │ ─settings│ │ ─rules │ │ ─skills │ │
│ │ ─MCP │ │ ─MCP │ │ ─cron │ │
│ │ ─perms │ │ ─config │ │ ─config │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │Downloads │ │ Browser │ │
│ │Documents │ │ Cache │ │
│ │(scripts) │ │ (Chrome, │ │
│ │ │ │ Firefox,│ │
│ │ │ │ Edge) │ │
│ └──────────┘ └──────────┘ │
└──────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────┐
│ Attack Vectors Detected │
├──────────────────────────────────────────────────────────────────┤
│ │
│ CRITICAL RISK (immediate danger) │
│ ├── PI-001 Ignore Previous Instructions │
│ ├── PI-002 New Identity Assignment (DAN, jailbreak) │
│ ├── PI-003 System Prompt Extraction │
│ ├── PI-004 Data Exfiltration via URL │
│ ├── PI-005 Markdown Image Exfiltration │
│ ├── PI-006 Tool/Function Call Manipulation │
│ ├── PI-007 MCP Server Manipulation │
│ ├── PI-008 Command Execution Injection │
│ ├── PI-009 Jailbreak Keywords (DAN, developer mode) │
│ ├── PI-022 Exposed API Keys/Credentials │
│ ├── PI-024 Indirect Injection (AI-addressed instructions) │
│ └── PI-028 Webhook/Callback Injection │
│ │
│ HIGH RISK (review soon) │
│ ├── PI-010 Instruction Boundary Delimiters │
│ ├── PI-011 Output Format Manipulation │
│ ├── PI-012 Prompt Leaking via Repetition │
│ ├── PI-013 Hidden Text via CSS/HTML │
│ ├── PI-014 Unicode Direction Override │
│ ├── PI-015 Credential/Secret Request │
│ ├── PI-016 File System Access Injection │
│ ├── PI-017 Multi-step Injection Chain │
│ ├── PI-018 Encoded Payload Marker │
│ ├── PI-019 Conversation History Manipulation │
│ ├── PI-020 Excel Formula Injection (CellShock) │
│ └── PI-023 Model-specific Prompt Tokens │
│ │
│ ADVISORY (review when convenient) │
│ ├── PI-021 AI Safety Bypass Language (hypothetical framing) │
│ ├── PI-025 Prompt Injection in Comments │
│ ├── PI-026 Environment Variable Exfiltration │
│ └── PI-027 Recursive Self-Reference Injection │
│ │
└──────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────┐
│ Cross-Platform Support │
├──────────────────────────────────────────────────────────────────┤
│ │
│ macOS Linux Windows │
│ ────── ────── ──────── │
│ pathlib pathlib pathlib (auto \ -> /) │
│ ANSI color ANSI color ANSI detection + fallback │
│ UTF-8 UTF-8 errors='replace' for cp1252 │
│ chmod 600 chmod 600 (permission checks skipped) │
│ /Library /etc C:\Windows (system dirs) │
│ brew install apt install python.org installer │
│ │
│ Python 3.9+ Python 3.9+ Python 3.9+ │
│ pip install pip install pip install │
│ Zero deps Zero deps Zero deps │
│ │
└──────────────────────────────────────────────────────────────────┘
```
## 命令
### `secureclaw scan`
扫描文件和目录以查找提示注入模式。
```
secureclaw scan . # Scan current directory
secureclaw scan ~/Documents ~/Downloads # Scan multiple directories
secureclaw scan . --format html -o report.html # HTML report
secureclaw scan . --format json -o report.json # JSON report for CI/CD
secureclaw scan . --severity critical # Only critical findings
secureclaw scan . --fail-on-high --no-posture # CI/CD mode
```
### `secureclaw posture`
检查你 AI 工具（Claude Code、Cursor、OpenClaw）的安全态势。
```
secureclaw posture
secureclaw posture /path/to/project
```
### `secureclaw fix`
对先前扫描报告中的发现进行自动修复。安全操作包括编辑泄露的凭证以及将误报添加到允许列表中。
默认情况下，`fix` 会在**演练模式**（仅预览）下运行。添加 `--apply` 以实际修改文件。
```
# 步骤 1：生成 JSON 扫描报告
secureclaw scan . --format json -o report.json
# 步骤 2：预览将要修复的内容（dry run）
secureclaw fix report.json
# 步骤 3：应用修复
secureclaw fix report.json --apply
# 仅修复 "act_now" 层级的发现（默认）
secureclaw fix report.json --apply --tier act_now
# 修复所有可自动修复的发现，无论层级如何
secureclaw fix report.json --apply --tier all
```
### `secureclaw allowlist`
管理已消除发现的允许列表。允许列表文件存储在 `.secureclaw/allowlist.json` 中，带有 HMAC 完整性检查以检测是否被篡改。
```
# 抑制特定发现
secureclaw allowlist add --file "*.md" --pattern PI-001 --reason "Legitimate AI instruction file"
# 查看所有抑制项
secureclaw allowlist list
# 移除抑制项
secureclaw allowlist remove --file "*.md" --pattern PI-001
```
## CI/CD 集成
```
# GitHub Actions 示例
- name: Scan for prompt injections
run: |
pip install secureclaw
secureclaw scan . --format json --fail-on-high --no-posture
```
退出代码：`0` = 干净，`1` = 发现问题超过阈值，`2` = 错误。
## 项目结构
```
secureclaw/
├── secureclaw/
│ ├── cli.py # CLI entry point (argparse)
│ ├── core/
│ │ ├── models.py # Finding, ScanResult, Severity dataclasses
│ │ ├── scanner.py # File walker, binary detection, encoding
│ │ ├── patterns.py # Pattern engine + decode-then-scan pipeline
│ │ └── allowlist.py # Allowlist with HMAC integrity
│ ├── reporters/
│ │ ├── terminal.py # ANSI color with auto-detection
│ │ ├── html_report.py # Self-contained branded HTML
│ │ └── json_report.py # Versioned JSON schema for CI/CD
│ ├── posture/
│ │ └── analyzer.py # Claude Code, Cursor, OpenClaw posture checks
│ └── rules/
│ └── default_rules.json # 28 detection patterns
├── tests/
├── pyproject.toml # Python packaging (hatchling)
└── README.md
```
## 许可证
MIT License - 版权所有 (c) 2026 Sparkry AI
由 [Sparkry AI](https://sparkry.ai) 使用经过实战检验的系统构建 - 你的独立创始人的 AI 优势。
标签：AI代理安全, AI工具安全, AI风险检测, CI/CD安全, Homebrew安装, Llama, LNA, Python安全工具, Unicode规范化, 人工智能安全, 代码扫描工具, 加密, 合规性, 多模态安全, 安全合规, 安全基线检查, 密钥泄露防护, 恶意文件检测, 批量测试, 提示注入防护, 文件安全扫描, 机器学习安全, 漏洞扫描器, 编码注入检测, 网络代理, 自动化安全审计, 跨平台工具, 逆向工具, 零宽字符检测, 零日漏洞检测