kuiilabs-clawaudit 0.1.0

Security-first static scanner for OpenClaw skills.

ClawAudit

ClawAudit 是一个面向 OpenClaw skill 生态的安全审计工具，覆盖静态扫描、运行时观测、目录展示和开发者工作流集成。

项目目标不是再做一个通用技能市场，而是补上 技能发现 -> 风险判断 -> 发布前审计 -> 版本变化追踪 这条链路中的信任层。

安装

发布版安装：

pip install kuiilabs-clawaudit

安装完成后仍然使用 clawaudit 这个命令。

本地开发安装：

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

快速开始

扫描一个本地 skill：

clawaudit scan ./my-skill

查看某条规则的详细说明：

clawaudit explain shell-exec

输出 JSON：

clawaudit scan ./my-skill --format json --no-persist

生成徽章：

clawaudit badge ./my-skill --format svg --output badge.svg

运行时观测：

clawaudit runtime-scan ./my-skill --format text

更完整的上手文档见 GETTING_STARTED.md。

当前能力

静态扫描

• 扫描本地目录、仓库 URL、带 #ref=<tag-or-branch> 的版本化 URL
• 扫描 GitHub tree/<ref>/<subpath> 子目录链接
• 批量扫描多个目标
• 解析 SKILL.md 中的权限声明
• 输出 text、json、markdown、sarif
• 支持 --fail-on、--max-risk-score、--enforce-policy
• 支持 diff、release-notes、badge、discover-targets

目录站与 API

• FastAPI API
• SQLite 报告存储
• 技能列表页、详情页、手动扫描页
• 历史 diff、badge、release notes 导出

运行时观测

• runtime-scan
• runtime_policy 与 runtime_execution
• 文件读写、环境变量、shell/subprocess、socket/HTTP 事件观测
• local-subprocess 和 local-isolated-copy runner
• timeout 与策略阻断

本地开发

仓库内常用命令：

.venv/bin/clawaudit --version
.venv/bin/clawaudit scan ./tests/fixtures/safe_skill
.venv/bin/clawaudit explain shell-exec
.venv/bin/python -m unittest discover -s tests -v

运行 API 和 Web：

.venv/bin/clawaudit-api

或：

.venv/bin/python -m uvicorn services.api.app:app --reload

默认页面：

• http://127.0.0.1:8000/
• http://127.0.0.1:8000/scan

规则文档

规则说明现在拆分到了独立文件：

• network-call.md
• network-url-reference.md
• shell-exec.md
• env-access.md
• sensitive-path-write.md
• sensitive-path-read.md
• sensitive-path-reference.md
• download-exec.md
• embedded-secret.md
• permission-missing.md
• permission-mismatch.md

规则索引见 rules/README.md。

示例仓库

仓库里已经补了一个本地样例集，可直接用于演示不同风险等级：

• clawaudit-example-skill

你可以直接扫描：

.venv/bin/clawaudit scan ./clawaudit-example-skill/safe-skill
.venv/bin/clawaudit scan ./clawaudit-example-skill/warning-skill
.venv/bin/clawaudit scan ./clawaudit-example-skill/high-risk-skill

文档索引

• GETTING_STARTED.md
• docs/README.md
• installation.md
• usage.md
• rules.md
• github-actions.md

发布前检查

当前本地已经验证通过：

• pip install -e .
• clawaudit --version
• clawaudit scan --help
• clawaudit explain --help
• python -m unittest discover -s tests -v
• python -m build --no-isolation
• python -m twine check dist/*

如果要继续做 TestPyPI / 正式 PyPI 发布，还需要可用的 TWINE_USERNAME / TWINE_PASSWORD 或 token。