yaseenkadlemakki/clawaudit

# ClawAudit [](https://github.com/yaseenkadlemakki/clawaudit/actions/workflows/test.yml) [](https://github.com/yaseenkadlemakki/clawaudit/actions/workflows/build.yml) [](LICENSE) **OpenClaw 安全智能平台** ClawAudit 审计 OpenClaw 部署的安全风险 —— 包括暴露的凭证、供应链威胁、shell 执行滥用和策略违规 —— 并通过实时 Web 仪表板、AI 驱动的调查聊天、自动修复和完整的 Skill 生命周期管理来展示所有信息。 ## 快速开始 ### Docker (推荐) ``` git clone https://github.com/yaseenkadlemakki/clawaudit.git cd clawaudit cp docker/.env.example docker/.env # 编辑 docker/.env 并设置 POSTGRES_PASSWORD docker compose --env-file docker/.env -f docker/docker-compose.yml up ``` | Service | URL | |---------|-----| | Dashboard | http://localhost:3000 | | API | http://localhost:18790 | | API Docs | http://localhost:18790/docs | ### 拉取预构建镜像 镜像在每次发布时发布到 GitHub Container Registry： ``` docker pull ghcr.io/yaseenkadlemakki/clawaudit-backend:latest docker pull ghcr.io/yaseenkadlemakki/clawaudit-frontend:latest ``` ### 本地 (不使用 Docker) ``` pip install -e ".[backend,dev]" cd frontend && npm install && cd .. # 终端 1 — backend uvicorn backend.main:app --host 0.0.0.0 --port 18790 --reload # 终端 2 — frontend cd frontend && npm run dev ``` ### CLI ``` sentinel audit # full security scan sentinel audit --format json --output r.json # export as JSON sentinel watch # continuous monitoring (60s default) sentinel skills list # list installed skills sentinel skills install ./my.skill # install a skill sentinel remediate # preview remediation proposals sentinel remediate --apply # apply fixes (with snapshots) sentinel report # generate compliance report sentinel alerts # view recent alerts sentinel policies --list # list loaded policy rules ``` ## 功能特性 ### 安全审计引擎 涵盖 6 个领域的 43 项检查 —— 配置加固、Skill 权限、Secrets、网络暴露、供应链和可观测性。 ### 高级检测 (5 条规则) - **ADV-001** 无限制的 shell 执行 (HIGH) - **ADV-002** 未知发布者/来源 (MEDIUM) - **ADV-003** 供应链风险 —— 未列出的出站域名 (HIGH) - **ADV-004** 未签名的 Skill (LOW) - **ADV-005** SKILL.md 中暴露的凭证 (CRITICAL) ### 修复引擎 自动提议并应用针对安全发现的修复，支持 dry-run 预览和基于快照的回滚。 - **三种策略**：限制 shell 访问 (ADV-001)，编辑暴露的 secrets (ADV-005)，限制过于宽泛的权限 (PERM-001) - **默认 Dry-run** —— 在应用前预览提议 - **快照回滚** —— 每个应用的修复都会创建一个快照；使用一条命令即可回滚 - **受保护路径** —— 系统 Skills 不能被修改 ``` sentinel remediate # dry-run: list proposals sentinel remediate --apply --yes # apply all proposals sentinel remediate --skill my-skill --check ADV-001 --apply sentinel snapshots list # list available snapshots sentinel snapshots rollback # restore from snapshot ``` **API:** ``` GET /api/v1/remediation/proposals # list proposed remediations POST /api/v1/remediation/apply # apply a remediation POST /api/v1/remediation/rollback # restore from snapshot GET /api/v1/remediation/history # remediation history ``` ### Skill 生命周期管理 安装、启用、禁用、卸载和恢复 Skills —— 通过 JSON 支持的注册表、基于回收站的恢复和受保护路径的强制执行。 - **Install** 从本地 `.skill` (tar.gz) 文件或 HTTPS URL - **Enable/disable** 通过 `SKILL.md` <-> `SKILL.md.disabled` 重命名 (完全可逆) - **Uninstall to trash** —— 从不删除，始终可以从 `~/.openclaw/sentinel/skill-trash/` 恢复 - **Health check** —— 按需对单个 Skill 运行安全分析器 - **Protected paths** —— `/opt/homebrew/lib/node_modules/openclaw/skills/` 下的系统 Skills 被阻止所有操作 ``` sentinel skills list # list all skills with status sentinel skills install ./my-skill.skill # install from file sentinel skills install https://clawhub.com/skills/x # install from URL sentinel skills enable # enable a disabled skill sentinel skills disable # disable a skill sentinel skills uninstall # move to trash sentinel skills recover # recover from trash sentinel skills health # run security analysis ``` **API:** ``` GET /api/v1/lifecycle/skills # list all skills with status POST /api/v1/lifecycle/skills/install # install from file path or URL POST /api/v1/lifecycle/skills/{name}/enable POST /api/v1/lifecycle/skills/{name}/disable DELETE /api/v1/lifecycle/skills/{name} # uninstall to trash GET /api/v1/lifecycle/skills/{name}/health # single-skill audit pass ``` ### 策略引擎 运行时策略执行，通过 `before_tool_call` hook 拦截每次工具执行，具有可配置的操作和实时管理 UI。 - **Actions**: ALLOW, WARN, ALERT, BLOCK, QUARANTINE - **Condition operators**: `equals`, `not_equals`, `contains`, `gt`, `gte`, `exists`, `in` 等 - **五个内置入门策略**：PTY 执行阻止、凭证文件读取警报、提权执行警报、外部浏览器导航警报、message-send 警报 - **`/policies` 管理 UI** —— 创建、编辑、启用/禁用、删除自定义策略，并提供实时违规反馈 - **Sub-500ms 评估** —— `POST /api/v1/policies/evaluate` 驱动执行 hook - **Default policy** 位于 `sentinel/policies/default.yaml` - **Hot-reload** 通过 `PolicyEngine.reload()` —— 无需重启 ``` sentinel policies --list # list loaded rules sentinel policies --validate # validate policy files ``` **API:** ``` GET /api/v1/policies # list policies POST /api/v1/policies # create policy PUT /api/v1/policies/{id} # update policy DELETE /api/v1/policies/{id} # delete policy POST /api/v1/policies/evaluate # evaluate a tool call against policies GET /api/v1/policies/stats # violation counts for the dashboard ``` ### Skill 隔离 当 QUARANTINE 策略操作触发时，违规 Skill 在数据库中被标记为已隔离，并在 UI 中显示 `QuarantineBadge`。可以通过 API 或管理 UI 取消隔离 Skill。隔离状态在 Skills 列表、Skill 详情页中可见，并作为发现结果显示在 Findings Explorer 中。 **API:** ``` POST /api/v1/skills/{id}/unquarantine # unquarantine a skill ``` ### 告警路由 将发现和运行时事件路由到多个通道，具有可配置的去重功能。 | Channel | Description | |---------|-------------| | **File** | 追加到 `~/.openclaw/sentinel/alerts.jsonl` (默认) | | **Webhook** | HTTP POST with JSON payload to any URL | | **OpenClaw** | Routes through gateway to Discord, Telegram, etc. | ``` sentinel alerts # view recent alerts sentinel alerts --last 50 # show last 50 sentinel alerts --ack # acknowledge an alert ``` ### 实时监控 五个后台收集器持续监控运行时安全事件： | Collector | What it watches | |-----------|-----------------| | **ConfigCollector** | Gateway config drift (polling + hash comparison) | | **SessionCollector** | Active agent sessions | | **CronCollector** | Scheduled jobs | | **LogCollector** | Agent execution logs (async tail) | | **SkillCollector** | Skill directory for new/modified skills | ``` sentinel watch # start all collectors (60s default) sentinel watch --interval 30 # custom interval ``` ### WebSocket 认证 扫描进度通过 WebSocket 流式传输。认证使用首次消息握手（token 不放在 URL 查询字符串中）： 1. 客户端连接到 `ws://localhost:18790/ws/scans` 2. 客户端在 5 秒内发送 `{"type": "auth", "token": ""}` 作为第一条消息 3. 服务器响应 `{"type": "auth_ok"}` —— 扫描流开始 4. 如果认证失败或超时，连接将使用代码 `4001` 关闭 这避免了在服务器访问日志中暴露 API token (CWE-598)。 ### Command Guard 预执行分类器，检测被错误作为 shell 命令执行的非 shell 代码块（Python, TypeScript, Go, Rust, YAML）。返回带有置信度和建议操作（WRITE_FILE, EXECUTE, 或 REVIEW）的判定。 ### 安全调查聊天 直接从仪表板就扫描数据提出自然语言问题。**Investigation Panel** 位于仪表板底部 —— 点击标题展开。`/chat` 路由会预先展开以便直接访问。 两种模式： - **OpenClaw mode** —— 通过本地 OpenClaw gateway 路由（无数据离开您的机器） - **BYOLLM mode** —— 使用您自己的 API key 直接调用 Anthropic 建议的入门问题： - Which skills allow shell execution? - Show me the critical findings - Which skills have unknown publishers? - What policies failed in the last scan? - Which skills contact external domains? - Explain the supply chain risks detected ### Chat Engine 设置 为了使 **OpenClaw mode** 生成真实的 AI 响应，请在 `~/.openclaw/openclaw.json` 中启用 gateway 的 chat completions endpoint： ``` { "gateway": { "http": { "endpoints": { "chatCompletions": { "enabled": true } } } } } ``` 进行此更改后重启 OpenClaw gateway。如果没有此设置，OpenClaw mode 将返回 HTTP 503 并提示您切换到 BYOLLM mode。 对于 **BYOLLM mode**，请在面板中提供您的 Anthropic API key。默认模型为 `claude-sonnet-4-6`。使用 `BYOLLM_MODEL` 环境变量覆盖。 ### 知识图谱 内存中的安全知识图谱，跟踪 Skills、工具、文件、网络端点和策略之间的关系。可按风险评分、工具使用情况和 Skill 名称查询。 **API:** ``` GET /api/v1/graph # full graph (JSON) GET /api/v1/graph/skill/{name} # single skill subgraph ``` ### 合规报告 生成 markdown 或 JSON 合规报告，包含统一的发现、严重性排序和运行 ID。 ``` sentinel report # print markdown report sentinel report --format json --output r.json sentinel baseline --create # snapshot current config sentinel baseline --diff # compare against baseline ``` ### 实时仪表板 Next.js 14 SPA，通过 WebSocket 实时显示扫描进度。 | Page | Description | |------|-------------| | `/dashboard` | Risk gauge, findings breakdown, skill trust matrix, collapsible Security Investigation panel | | `/audit` | Trigger and manage audit scans | | `/findings` | Findings list with severity/policy/skill filtering | | `/skills` | Skill explorer with lifecycle controls (install, enable/disable, uninstall) | | `/skills/[id]` | Individual skill detail and health report | | `/remediation` | View proposals, apply fixes, rollback history | | `/chat` | Direct access to the Security Investigation panel (opens pre-expanded) | | `/policies` | Policy Engine — manage rules, view violations feed, quarantine skills | ## 审计内容 | Domain | Checks | |--------|--------| | Configuration Hardening | 8 checks — debug mode, bind address, auth, agent limits, HITL gates | | Skill Permission Audit | 10 checks per skill — tool allowlists, shell access, injection risk | | Secrets & Credential Hygiene | 6 checks — hardcoded keys, env var usage, log masking | | Network Exposure & Egress | 7 checks — loopback binding, TLS, egress allowlists, webhooks | | Supply Chain Risk | 7 checks — version pinning, publisher identity, dependency locking | | Audit Logging & Observability | 5 checks — invocation logging, SIEM shipping, alerting, retention | ## 文档 | Doc | Description | |-----|-------------| | [docs/setup.md](docs/setup.md) | Full setup guide — local + Docker | | [docs/architecture.md](docs/architecture.md) | System design, data flows, component overview | | [docs/risk-scoring.md](docs/risk-scoring.md) | How risk scores are calculated; ADV-* check details | | [docs/chat-investigation.md](docs/chat-investigation.md) | Investigation chat usage + example questions | | [docs/ci-cd.md](docs/ci-cd.md) | CI/CD pipeline stages and how to extend them | ## 仓库结构 ``` clawaudit/ ├── backend/ FastAPI async API server │ ├── api/routes/ REST endpoints (scans, findings, skills, lifecycle, remediation, chat, graph, policies, ws) │ ├── engine/ Audit engine, risk scoring, knowledge graph, chat engine, scan manager │ └── models/ SQLAlchemy models (scan, skill, finding, policy, remediation) ├── frontend/ Next.js 15 dashboard UI │ ├── src/app/ Pages: dashboard, audit, findings, skills, remediation, chat, policies │ └── src/components/ Shared components: InvestigationPanel, Sidebar, QuarantineBadge, ... ├── sentinel/ Python CLI + audit engine │ ├── analyzer/ Skill analyzer, config auditor, injection detector, secret scanner │ ├── alerts/ Alert engine + channels (file, webhook, OpenClaw) │ ├── collector/ Runtime collectors (config, session, cron, log, skill) │ ├── guard/ Command guard (code block detection) │ ├── lifecycle/ Skill installer, registry, toggler, uninstaller │ ├── policy/ Policy engine, loader, actions │ ├── remediation/ Remediation engine, strategies, rollback │ └── reporter/ Compliance reporter, renderers ├── docker/ Dockerfiles + docker-compose ├── docs/ Documentation ├── data/ │ └── hardening-rules.yaml Check registry (43 checks across 6 domains) ├── references/ │ ├── domains.md Per-domain check definitions │ ├── scoring.md Severity classification rules │ └── report-template.md Report structure and formatting ├── tests/ Test suite (1,243+ Python tests · 188 Playwright E2E tests · 80% coverage gate) └── .github/ ├── workflows/ test.yml + build.yml └── dependabot.yml Weekly version bumps (Actions, pip, npm) ``` ## CI/CD 流水线 | Stage | Description | |-------|-------------| | YAML Lint | Validates all YAML files | | Python Audit | `pip-audit` on dependencies | | Node Audit | `npm audit` on frontend | | Lint | `ruff check` + `ruff format --check` | | Test | pytest with 80% coverage gate (Python 3.10/3.11/3.12) | | Docker Build | Multi-stage build (backend + frontend), cached via GitHub Actions | | Publish | Push to GHCR on version tags (`v*.*.*`) with stable + latest image tags | | Dependabot | Weekly PRs for Actions, pip, and npm dependency updates | ## 设计原则 - **Read-only audits**：审计引擎只读取文件并查询 gateway 配置。它从不写入、编辑或执行。 - **Safe remediation**：修复默认为 dry-run。应用的修复会创建快照以便即时回滚。系统 Skills 受到保护。 - **No secret leakage**：模式匹配仅报告类型 + 位置。Secret 值在进入任何事件证据之前被编辑。 - **Conservative scoring**：UNKNOWN 结果算作 FAIL。 - **Hostile-content isolation**：Skill bodies 被视为不受信任的文本 —— 从不进行求值或执行。 - **Trash, not delete**：Skill 卸载移动到回收站。没有任何东西被永久删除。 ## 许可证 本项目基于 [Apache License 2.0](LICENSE) 授权。 ## 版本 **v0.4.0** — 参见 [CHANGELOG.md](CHANGELOG.md) 了解历史。

标签：AI安全, AMSI绕过, AV绕过, Chat Copilot, Docker, FastAPI, Lerna, OpenClaw, Python, Runtime Security, StruQ, TypeScript, WSL, 仪表盘, 凭证泄露检测, 大语言模型安全, 威胁检测, 安全情报平台, 安全插件, 安全防御评估, 审计系统, 技能管理, 文档安全, 无后门, 智能体安全, 服务器监控, 机密管理, 权限控制, 模块化设计, 测试用例, 特征检测, 私有化部署, 策略执行, 自动化修复, 请求拦截, 运行时保护, 逆向工具, 速率限制, 防御规避