claw-safehouse-scanner

v0.4.1

Published

2 days ago

AI-Enhanced Agent Security Scanner

0High
0Medium
0Low

aneyadeng

ai agent sandbox security isolation openclaw cursor langchain

English | 中文

🛡️ Claw Safehouse Scanner

AI 智能体安全扫描与诊断 — 支持 AI 增强分析

AI 智能体强大但难以预测。Claw Safehouse Scanner 扫描 AI 智能体的安全风险，并推荐合适的 sandbox 方案进行隔离保护（Cursor、Continue.dev、OpenClaw、NanoClaw、LangChain 等）。

为什么需要 Claw Safehouse Scanner？

| 问题 | 无 Safehouse | 有 Safehouse | |------|-------------|--------------| | Agent 读取 ~/.ssh/* | ❌ 可能的凭证泄露 | ✅ 检测风险并推荐隔离方案 | | Agent 删除 /tmp/* | ❌ 数据丢失 | ✅ 检测并阻止破坏性操作 | | Agent 调用外部 API | ❌ 未知成本/风险 | ✅ 识别并控制网络访问 | | 系统修改 | ❌ 无法追踪 | ✅ 完整的可见性和审计 |

功能特性

🔍 智能扫描 — 检测智能体行为模式（文件访问、网络调用、命令执行）
🤖 AI 增强分析 — 基于 Ollama（本地）或 OpenAI（云端）的深度安全分析
📊 HTML 报告 — 精美的卡片布局报告，支持严重度过滤、分类过滤、搜索和暗色模式
🔒 敏感信息脱敏 — 自动遮蔽报告中的 API key、token、SSH key、邮箱和 IP 地址
⚡ 并发扫描 — 批量分析，可配置并发数，加速扫描过程
🎯 Embedding 过滤 — 使用 bge-m3 嵌入模型减少噪音，聚焦相关文件
💡 Sandbox 推荐 — 根据风险等级自动推荐隔离方案
🌐 国际化 — 完整的中英文语言支持
⚙️ 灵活配置 — 支持配置文件、环境变量和命令行参数

快速开始

安装

npm install -g claw-safehouse-scanner

基础扫描

# 扫描智能体（仅静态规则）
claw-safehouse scan openclaw

# 输出 JSON 格式
claw-safehouse scan openclaw --json

AI 增强扫描

# 启用 AI 深度分析
claw-safehouse scan openclaw --ai

# AI 扫描 + JSON 输出
claw-safehouse scan openclaw --ai --json

# 设置语言
claw-safehouse scan openclaw --ai --lang zh

HTML 报告

# 生成交互式 HTML 报告
claw-safehouse scan openclaw --ai --html --output report.html

HTML 报告包含：

📋 卡片式发现布局
🔍 按严重度/分类搜索和过滤
🌙 暗色模式支持
🔒 自动敏感信息脱敏

概览 — 风险评分与统计

Overview

严重度分布与分类统计

Charts

发现列表与过滤

Findings

暗色模式

Dark Mode

配置

配置文件

创建 ~/.agent-safehouse.json：

{
  "scanner": {
    "defaultAgent": "openclaw",
    "ai": {
      "enabled": true,
      "provider": "ollama",
      "model": "qwen2.5:7b-instruct",
      "endpoint": "http://localhost:11434",
      "apiKey": ""
    }
  },
  "openclaw": {
    "auditLogPath": "~/.openclaw/audit.log",
    "workspacePath": "~/.openclaw/workspace"
  }
}

完整示例请参见 .agent-safehouse.example.json。

环境变量

环境变量优先级高于配置文件。复制示例文件并自定义：

cp .env.example .env

环境变量参考

| 变量 | 说明 | 默认值 | 示例 | |------|------|--------|------| | AGENT_SAFEHOUSE_OLLAMA_ENDPOINT | Ollama API 端点 | — | http://localhost:11434 | | AGENT_SAFEHOUSE_MODEL | AI 分析模型 | — | qwen2.5:7b-instruct | | AGENT_SAFEHOUSE_NUM_CTX | 上下文窗口大小（tokens） | 8192 | 16384 | | AGENT_SAFEHOUSE_TIMEOUT_MS | AI API 超时（毫秒） | 120000 | 300000 | | AGENT_SAFEHOUSE_CONCURRENCY | 并行分析任务数 | 4 | 2 | | AGENT_SAFEHOUSE_EMBEDDING_ENDPOINT | Embedding API 端点 | — | http://localhost:11434/api/embed | | AGENT_SAFEHOUSE_EMBEDDING_MODEL | Embedding 模型 | bge-m3 | nomic-embed-text | | AGENT_SAFEHOUSE_EMBEDDING_THRESHOLD | 相似度阈值（0.0–1.0） | 0.50 | 0.45 | | OPENAI_API_KEY | OpenAI API 密钥 | — | sk-your-api-key | | OPENAI_BASE_URL | OpenAI 兼容端点 | — | http://localhost:1234/v1 |

优先级： 环境变量 > 配置文件 > 默认值

支持的智能体

| 智能体 | 状态 | 说明 | |--------|------|------| | OpenClaw | ✅ 完全支持 | 扫描 + 风险诊断 + sandbox 推荐 | | NanoClaw | 🟡 基础支持 | 扫描器占位符（开发中） | | Cursor | 🟡 基础支持 | 扫描器占位符（开发中） | | Continue.dev | 🟡 基础支持 | 扫描器占位符（开发中） | | LangChain | 🟡 基础支持 | Python 集成（开发中） | | AutoGen | 🟡 基础支持 | Python 集成（开发中） |

风险类别

Claw Safehouse Scanner 扫描 5 个类别的安全风险：

| 类别 | 风险示例 | |------|----------| | 📁 文件系统访问 | 凭证文件（~/.ssh、~/.aws）、系统目录修改 | | 🌐 网络访问 | 未知 API 调用、第三方服务、付费端点 | | ⚙️ 命令执行 | 持久化（crontab）、破坏性命令（rm -rf）、权限提升 | | 🔑 敏感数据 | 私钥提取、数据库文件、包含密钥的配置文件 | | 🤖 智能体行为 | 高权限子智能体、权限提升、异常遍历 |

每个发现按严重度分级：🔴 严重 · 🟠 高 · 🟡 中 · 🟢 低

CI/CD 集成

Claw Safehouse Scanner 可在 CI/CD 流水线中进行持续安全扫描。

# .gitlab-ci.yml 示例
security-scan:
  stage: test
  script:
    - npm install -g claw-safehouse-scanner
    - claw-safehouse scan openclaw --ai --json --output scan-result.json
    - claw-safehouse scan openclaw --ai --html --output scan-report.html
  artifacts:
    paths:
      - scan-result.json
      - scan-report.html
  variables:
    AGENT_SAFEHOUSE_TIMEOUT_MS: "300000"
    AGENT_SAFEHOUSE_CONCURRENCY: "2"

⚠️ API 密钥等敏感配置请通过 CI/CD 变量管理（Settings → CI/CD → Variables），不要写在 YAML 文件中。

开发

# 克隆仓库
git clone https://github.com/raye-deng/claw-safehouse-scanner.git
cd claw-safehouse-scanner

# 安装依赖
npm install

# 编译
npm run build

# 运行测试
npm test

# 本地扫描
node dist/cli.js scan openclaw

路线图

v0.4.0（当前版本）✅

✅ AI 增强扫描（Ollama + OpenAI）
✅ HTML 报告（卡片布局、过滤、搜索、暗色模式）
✅ 报告中敏感信息脱敏
✅ CI/CD 集成
✅ 环境变量配置
✅ Embedding 文件过滤（bge-m3）
✅ 并发批量分析
✅ 国际化（中文 / 英文）

v0.5.0（下一版本）

🟡 更多智能体扫描器（Cursor、Continue.dev）
🟡 PDF 报告导出
🟡 Web UI 仪表盘
🟡 实时监控

v1.0.0（未来版本）

🟢 企业级功能（RBAC、SSO）
🟢 SIEM 集成（Splunk、Datadog）
🟢 合规性（SOC2、ISO27001）
🟢 自动修复

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 获取指南。

优先领域：

扫描器实现（Cursor、Continue.dev、LangChain、AutoGen）
Sandbox 方案研究
风险诊断改进
真实环境测试和反馈

许可证

AI 智能体应该强大，但不应鲁莽。用 Claw Safehouse Scanner 保护它们。 🛡️