secnova-ai/ClawdSecbot

# ClawSecbot **[中文文档](README_zh-CN.md)** 迁移文档： - [版本升级迁移指南 (EN)](mds/version_upgrade_migration_en.md) - [版本升级迁移指南 (ZH-CN)](mds/version_upgrade_migration_zh-CN.md) 适用于 Bot 类型终端 AI 代理的桌面安全防护软件。 ClawSecbot 负责监控并保护您机器上运行的本地 AI Bot 代理（如 Openclaw）。它充当 AI 代理与 LLM 服务之间的保护层——拦截 API 请求，实时分析风险，执行沙箱策略，并提供完整的审计追踪记录。 ## 社区评价 [](https://m.youtube.com/watch?v=Hr2uh5qSQmo) [](https://www.youtube.com/watch?v=ACVLW2OoCO0&t=4s) ## 功能特性 - **资产发现** — 自动扫描并识别您系统上的 AI Bot 进程、工作区、配置和端口 - **风险评估** — 评估已检测资产的安全风险，包括 Skill/工具安全分析 - **防护代理** — 拦截 Bot 到 LLM 的 API 流量，分析请求/响应内容中的危险操作，并在执行前向用户发出警告 - **沙箱执行** — 将 Bot 进程限制在操作系统级别的沙箱内（macOS Seatbelt / Linux LD_PRELOAD hook / Windows MinHook），如果沙箱被绕过则自动恢复 - **LLM 协议转换** — 以 OpenAI 兼容格式代理请求，并在各种 LLM 提供商之间进行双向转换 - **审计日志** — 记录所有请求、工具调用、风险检测和 token 使用情况，具备完整的可追溯性 - **插件架构** — 可扩展的插件系统，用于支持不同类型的 Bot ## 支持平台 | 平台 | 架构 | 状态 | |----------|-------------|--------| | macOS | arm64 | 支持 | | macOS | x86_64 | 支持 | | Linux | arm64 | 支持 | | Linux | x86_64 | 支持 | | Windows | x86_64 | 支持 | ### Windows 权限要求 - 在 Windows 上，`bot_sec_manager.exe` 被配置为 `requireAdministrator`。 - 每次启动（Debug/Profile/Release）都会触发 UAC 提示。 - 如果 UAC 被拒绝或无法提权，应用程序将立即退出（fail-close）。 ## 系统架构 ``` ┌──────────────────────────────────┐ │ Flutter Desktop │ │ (UI + State Management) │ ├──────────────────────────────────┤ │ FFI │ │ (JSON-based Protocol) │ ├──────────────────────────────────┤ │ Go Shared Library │ │ (botsec.dylib/so/dll) │ │ ┌───────────┬─────────────────┐ │ │ │ Core │ Plugins │ │ │ │ ┌───────┐ │ ┌───────────┐ │ │ │ │ │Scanner│ │ │ Openclaw │ │ │ │ │ │Sandbox│ │ │ Plugin │ │ │ │ │ │Proxy │ │ └───────────┘ │ │ │ │ │AuditDB│ │ │ │ │ │ └───────┘ │ │ │ │ └───────────┴─────────────────┘ │ ├──────────────────────────────────┤ │ chatmodel-routing │ │ (LLM Protocol Translation) │ ├──────────────────────────────────┤ │ SQLite (Data) │ └──────────────────────────────────┘ ``` ClawSecbot 采用**前后端分离**架构： - **Flutter Desktop** — 负责处理 UI 渲染、状态管理和用户交互 - **Go Shared Library** — 包含所有业务逻辑，编译为单个动态库（`botsec.dylib` / `botsec.so` / `botsec.dll`） - **FFI 通信** — Flutter 通过 FFI 使用统一的 JSON 协议调用 Go 函数；Go 通过原生回调将事件推回 ## 技术栈 | 层级 | 技术 | |-----------|-------------------------------| | UI | Flutter Desktop (Dart) | | 逻辑层 | Go (CGO, c-shared) | | 数据库 | SQLite (via modernc.org/sqlite) | | IPC | FFI + JSON 协议 | | 状态管理 | Provider | | i18n | Flutter Localizations | | 沙箱 | macOS Seatbelt / Linux LD_PRELOAD hook / Windows MinHook | | LLM SDK | Eino 框架 (CloudWeGo) | ### 支持的 LLM 提供商 OpenAI · Anthropic (Claude) · DeepSeek · Google (Gemini) · Ollama · Moonshot · xAI (Grok) ## 项目结构 ``` bot_sec_manager/ ├── lib/ # Flutter application │ ├── main.dart # App entry point │ ├── services/ # FFI service layer │ │ ├── native_library_service.dart │ │ ├── plugin_service.dart │ │ ├── protection_service.dart │ │ ├── protection_monitor_service.dart │ │ ├── message_bridge_service.dart │ │ ├── sandbox_service.dart │ │ └── *_database_service.dart │ ├── pages/ # UI pages │ ├── widgets/ # Reusable UI components │ ├── models/ # Data models │ ├── l10n/ # Internationalization │ └── utils/ # Utilities ├── go_lib/ # Go security engine │ ├── main.go # Dylib entry, all FFI exports │ ├── core/ # Core package │ │ ├── plugin.go # BotPlugin interface │ │ ├── plugin_manager.go # Plugin registry │ │ ├── path_manager.go # Path management │ │ ├── ffi.go # FFI helpers │ │ ├── logging/ # Logging module │ │ ├── repository/ # Data access layer │ │ ├── service/ # Business services │ │ ├── scanner/ # Asset scanner │ │ ├── sandbox/ # Sandbox policies │ │ └── callback_bridge/ # FFI callback bridge │ ├── plugins/openclaw/ # Openclaw Bot plugin │ ├── skillagent/ # Skill Agent engine │ └── chatmodel-routing/ # LLM protocol translation │ ├── adapter/ # Provider adapter │ ├── providers/ # Per-provider implementations │ │ ├── openai/ │ │ ├── anthropic/ │ │ ├── deepseek/ │ │ ├── google/ │ │ ├── ollama/ │ │ ├── moonshot/ │ │ └── xai/ │ ├── proxy.go # Forwarding proxy │ ├── filter.go # Content filter │ └── sdk/ # Protocol types ├── scripts/ # Build & deployment scripts └── macos/ linux/ windows/ # Platform runners ``` ## 前置条件 - **Flutter** >= 3.10（需启用桌面支持） - **Go** >= 1.25 - **Xcode**（macOS）/ **GCC**（Linux）— 用于 CGO 编译 - **CMake**（Linux 桌面构建） ## 构建 ### 1. 构建 Go 安全引擎 ``` ./scripts/build_go.sh ``` 这会将 Go 代码编译为特定平台的共享库： - macOS: `go_lib/botsec.dylib` - Linux: `go_lib/botsec.so` - Windows: `go_lib/botsec.dll` ### 2. 构建 Openclaw 插件 ``` ./scripts/build_openclaw_plugin.sh ``` ### 3. 以开发模式运行 ``` ./scripts/run_with_pprof.sh ``` 此脚本会构建 Go 引擎并启动启用了 pprof 性能分析的 Flutter 应用程序，适用于本地开发和调试。 ### 4. 运行 Flutter 应用程序 ``` flutter run -d macos # or -d linux, -d windows ``` ### 5. 构建 Release 包 **macOS:** ``` ./scripts/build_macos_release.sh ``` **Linux (deb):** ``` ./scripts/build_linux_deb.sh ``` **Linux (通用):** ``` ./scripts/build_linux_release.sh ``` ## 安装 ### macOS 从 [Releases](../../releases) 页面下载 `.dmg` 安装包，打开它，然后将 **ClawSecbot** 拖入您的“应用程序”文件夹。 ### Linux **Debian/Ubuntu (.deb):** ``` sudo dpkg -i clawsecbot_*.deb ``` **通用 Linux:** 解压发布归档文件并直接运行可执行文件。 ## 卸载 ## 模块概述 ### Core (`go_lib/core/`) 所有插件共用的基础模块： | 模块 | 描述 | |--------|-------------| | `plugin.go` | `BotPlugin` 接口 — 定义所有 Bot 插件的约定，包括资产发现、风险评估、防护控制和缓解措施 | | `plugin_manager.go` | 插件注册中心 — 负责自动注册、重复检测以及聚合的 FFI 方法 | | `scanner/` | 资产发现引擎 — 扫描 Bot 进程、端口和配置 | | `sandbox/` | 操作系统沙箱管理 — 生成并应用 Seatbelt/LD_PRELOAD/Windows hook 策略 | | `repository/` | 数据访问层 — SQLite CRUD 操作 | | `service/` | 业务逻辑 — 防护、审计、指标和版本检查 | | `callback_bridge/` | FFI 回调机制 — Go 到 Dart 的事件推送 | | `logging/` | 结构化日志 | | `path_manager.go` | 集中化路径管理 | ### Chatmodel 路由 (`go_lib/chatmodel-routing/`) LLM 协议转换层： - 接收来自防护代理的 **OpenAI 兼容** 格式的请求 - 将请求转换并转发至目标 LLM 提供商的原生 API - 将响应转换回 OpenAI 格式 - 支持流式传输、推理、工具调用和用量跟踪 ### Skill Agent (`go_lib/skillagent/`) 用于解析、加载和安全执行 Bot 技能/工具的引擎。包括对 Skill 定义的安全分析。 ### Plugins (`go_lib/plugins/`) 每个插件均实现了 `BotPlugin` 接口： ``` type BotPlugin interface { // Basic Info GetAssetName() string // Asset Discovery ScanAssets() ([]Asset, error) // Risk Assessment AssessRisks(scannedHashes map[string]bool) ([]Risk, error) MitigateRisk(riskInfo string) string // Protection Control (per-instance) StartProtection(assetID string, config ProtectionConfig) error StopProtection(assetID string) error GetProtectionStatus(assetID string) ProtectionStatus } // Optional lifecycle hooks type ProtectionLifecycleHooks interface { OnProtectionStart(ctx *ProtectionContext) (map[string]interface{}, error) OnBeforeProxyStop(ctx *ProtectionContext) } ``` 插件通过 `init()` 自动注册，并由 `PluginManager` 进行管理。插件系统支持： - **带重复检测的自动注册** — 插件在 `init()` 中自行注册，如果已注册则跳过 - **多实例资产支持** — 防护方法接受 `assetID` 以进行每个实例的状态管理 - **生命周期钩子** — `ProtectionLifecycleHooks` 接口，用于在启动前/停止后进行自定义操作 - **风险缓解路由** — 风险会自动打上 `SourcePlugin` 标签，以便正确路由回源插件 适用于类 Openclaw Bot 的插件适配指南： - [类 Openclaw Bot 插件适配指南](mds/openclaw_like_bot_plugin_guide.md) ## 贡献 欢迎贡献。请确保： 1. 遵循现有的代码风格 2. 为 Go 业务逻辑编写单元测试 3. 保持文件在 1500 行以内 4. 在 Go 中的所有 JSON 序列化均使用 `json.Marshal`（禁止使用 `fmt.Sprintf`） 5. 提交前运行 `flutter analyze` 和 `go vet` ## 许可证 [GNU GPLv3](LICENSE)

标签：AI代理保护, AI安全, AI应用防火墙, AI网关, API拦截, Bot安全防护, Chat Copilot, CISA项目, EVTX分析, LLM代理, LLM协议转换, OpenAI兼容, PE 加载器, 反取证, 大模型安全, 安全代理, 安全评估, 安全防护解决方案, 实时威胁检测, 异常检测, 提示词注入防护, 插件架构, 日志审计, 桌面安全软件, 端点安全, 网络安全, 网络流量分析, 补丁管理, 请求响应过滤, 隐私保护, 风险拦截