Metadata-Version: 2.4
Name: kuiilabs-clawaudit
Version: 0.1.0
Summary: Security-first static scanner for OpenClaw skills.
Author-email: ClawAudit Team <clawaudit@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/kuiilabs/clawaudit
Project-URL: Repository, https://github.com/kuiilabs/clawaudit.git
Project-URL: Documentation, https://github.com/kuiilabs/clawaudit#readme
Project-URL: Changelog, https://github.com/kuiilabs/clawaudit/releases
Keywords: security,audit,static-analysis,openclaw,skills,cybersecurity
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1,>=0.135
Requires-Dist: uvicorn<1,>=0.44
Provides-Extra: dev
Requires-Dist: httpx<1,>=0.28; extra == "dev"

# ClawAudit

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

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

## 安装

发布版安装：

```bash
pip install kuiilabs-clawaudit
```

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

本地开发安装：

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

## 快速开始

扫描一个本地 skill：

```bash
clawaudit scan ./my-skill
```

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

```bash
clawaudit explain shell-exec
```

输出 JSON：

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

生成徽章：

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

运行时观测：

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

更完整的上手文档见 [GETTING_STARTED.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/docs/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 与策略阻断

## 本地开发

仓库内常用命令：

```bash
.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：

```bash
.venv/bin/clawaudit-api
```

或：

```bash
.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](/Users/kui/Documents/vibecoding/codex/ClawAudit/rules/network-call.md)
- [network-url-reference.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/rules/network-url-reference.md)
- [shell-exec.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/rules/shell-exec.md)
- [env-access.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/rules/env-access.md)
- [sensitive-path-write.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/rules/sensitive-path-write.md)
- [sensitive-path-read.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/rules/sensitive-path-read.md)
- [sensitive-path-reference.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/rules/sensitive-path-reference.md)
- [download-exec.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/rules/download-exec.md)
- [embedded-secret.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/rules/embedded-secret.md)
- [permission-missing.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/rules/permission-missing.md)
- [permission-mismatch.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/rules/permission-mismatch.md)

规则索引见 [rules/README.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/rules/README.md)。

## 示例仓库

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

- [clawaudit-example-skill](/Users/kui/Documents/vibecoding/codex/ClawAudit/clawaudit-example-skill/README.md)

你可以直接扫描：

```bash
.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](/Users/kui/Documents/vibecoding/codex/ClawAudit/docs/GETTING_STARTED.md)
- [docs/README.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/docs/README.md)
- [installation.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/docs/installation.md)
- [usage.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/docs/usage.md)
- [rules.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/docs/rules.md)
- [github-actions.md](/Users/kui/Documents/vibecoding/codex/ClawAudit/docs/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。
