blondres04/shieldclaw
GitHub: blondres04/shieldclaw
一个基于本地 LLM 与 Docker 沙箱的 DevSecOps 工具，用于实证生成并验证漏洞利用。
Stars: 2 | Forks: 0
# Shield Claw
**Shield Claw** 是一个本地 CLI 工具，它利用 LLM 生成的漏洞利用来实证验证基于 Docker 的应用程序层漏洞。与仅预测代码*可能*存在风险的静态分析工具不同，Shield Claw 通过对正在运行的应用程序副本引爆漏洞利用来证明风险。
主要实现位于 [`shield-claw/`](./shield-claw/)（Python 包 `shieldclaw`）。可选的离线 LLM 检查位于 [`evals/`](./evals/)。
## 先决条件
- **Python** 3.11 或更新版本
- **Docker** 搭配 Compose v2（`docker compose`，而非仅限旧版 `docker-compose`）
- **Ollama** 本地运行*或* **OpenAI** / **Anthropic** 的 API 凭证（参见 `shield-claw/.env.example`）
- **Git**（仅当目标仓库使用 `git diff HEAD~1` 而非捆绑补丁文件时需要）
## 快速开始
1. 克隆仓库并进入：
git clone
cd
2. 创建并激活虚拟环境（Unix 风格 Shell）：
python3.11 -m venv .venv
source .venv/bin/activate
在 Windows（PowerShell）下：
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
3. 安装 CLI 包及其依赖：
pip install -r shield-claw/requirements.txt
pip install -e shield-claw/
4. 配置环境变量：
cp shield-claw/.env.example shield-claw/.env
编辑 `shield-claw/.env` 以设置 `OLLAMA_MODEL`（默认 `gemma3:4b`）、`OLLAMA_BASE_URL` 或云提供商密钥（若使用 OpenAI/Anthropic）。
5. 验证 Docker 和 Compose：
docker --version
docker compose version
6. 验证 Ollama 是否可达并加载模型：
curl http://localhost:11434/api/tags
如需，拉取模型：
ollama pull gemma3:4b
7. 运行单元测试：
cd shield-claw
pytest tests/ -v
8. 对内置的易损 Flask 实验室目标运行流水线（从 `shield-claw/` 执行以便导入可编辑安装，或在仓库根目录保持 `shieldclaw` 在 `PYTHONPATH` 中）：
cd shield-claw
python -m shieldclaw run --target ../test_repos/vulnerable-flask-app --timeout 120
`test_repos/vulnerable-flask-app/` 下的实验室应用**不是** Git 仓库；当缺少 `.git` 时，它会自动加载 [`context.patch`](./test_repos/vulnerable-flask-app/context.patch) 文件。对于常规仓库，请省略该文件，改用 Git 历史（`git diff HEAD~1`）或传递 `--diff path/to.patch`。
示例 Compose 文件**未发布主机端口**（避免与已绑定 5000 端口的程序冲突）。漏洞利用仍可通过内部 Compose 网络在 `http://web:5000` 处访问应用。
在 `docker compose` 显示所有服务均已运行后，协调器会等待一段短暂的**启动后宽限期**，以便数据库和工作进程完成启动，然后再进行引爆。仅当 LLM 生成的漏洞利用退出码为 `0` 时，`is_vulnerable` 字段才为 `true`；小型模型可能需要重新运行或调整提示以应对脆弱的脚本。
## 用法
```
# 默认：Ollama 提供程序，与 git 或 context.patch 回退不同
python -m shieldclaw run --target /path/to/repo
# 可选的统一差异文件（相对路径在目标目录下解析）
python -m shieldclaw run --target /path/to/repo --diff my-change.patch
# 云 LLM 后端
python -m shieldclaw run --target /path/to/repo --provider openai
python -m shieldclaw run --target /path/to/repo --provider anthropic
# 引爆超时（秒）和 JSON 报告输出到文件
python -m shieldclaw run --target /path/to/repo --timeout 60 --output report.json
```
JSON 将输出至 **stdout**，除非设置了 `--output`。当漏洞利用进程以退出码 `0` 结束时，字段 `is_vulnerable` 为 `true`。
## 架构
```
┌─────────────────────────────────────────────────┐
│ shieldclaw/__main__.py │
│ (CLI entry point) │
│ argparse → validate → dispatch │
└─────────────────┬───────────────────────────────┘
│ depends on
▼
┌─────────────────────────────────────────────────┐
│ orchestrator.py │
│ (Pipeline state machine) │
│ Drives: Context → LLM → Sandbox → Report │
└──┬──────────┬──────────┬──────────┬─────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐
│context/│ │intelli- │ │sandbox/│ │reporting/│
│aggre- │ │gence/ │ │docker_ │ │builder │
│gator │ │ollama, │ │orches- │ │ │
│ │ │parser, │ │trator │ │ │
│ │ │prompts │ │ │ │ │
└───┬────┘ └────┬─────┘ └───┬────┘ └────┬─────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────┐
│ models.py + exceptions.py │
│ (Shared data objects) │
│ Zero internal dependencies │
└─────────────────────────────────────────────────┘
```
## 安全注意事项
- **漏洞利用执行**在**加固**的 Docker 容器内运行 LLM 编写的 Python 代码（`--read-only`、非 root 用户、内存/CPU/PID 限制、`/tmp` 使用 tmpfs）。这与在主机上运行相同代码相比显著降低了风险，但**并未将风险降至零**：内核级容器逃逸漏洞仍是潜在的威胁类别。
- **攻击者容器网络访问**：在引爆过程中，攻击者容器会运行 `pip install requests` 以引导 HTTP 能力。这使容器获得对 PyPI 的出站互联网访问。未来版本将通过内置依赖项的攻击者镜像来消除此信任边界。详见 [ADR-005](shield-claw/docs/adrs/005-attacker-container-pypi-access.md) 进行完整权衡分析。（当前实现使用 `pip install --target /tmp/pylib`，因此 `requests`/`urllib3` 在不写入系统站点包树的情况下安装；信任边界相同。）
- **基于 Compose 的目标**在与工作站相同的 Docker 守护进程上运行。仅扫描您信任到足以将其作为容器运行在机器上的代码。
- **云 LLM 提供商**会接收您传入的 **git 差异**（以及 `docker-compose.yml` 内容）。请将其视为**敏感源代码暴露**，除非您坚持完全本地推理（例如使用 Ollama）。
## 已知限制（v1）
- **单次生成**漏洞利用（无自动重试或智能优化循环）。
- **目标布局**：扫描器期望在仓库根目录存在 `docker-compose.yml`（或 `.yaml`），与 CLI 验证的布局一致。
- **无内置 CI/CD** 集成；操作员需手动运行 CLI 或将其封装到自有流水线中。
- **漏洞利用载荷**目前**仅限 Python**。
- **在小于 10B 的本地模型上评估准确率为 60–70%**；推荐在生产中使用更大模型或云提供商。
- **LLM 质量**因模型和提示而异；详见 [`evals/README.md`](./evals/README.md) 获取离线测试框架。
**LLM 评估基准：** 在 `gemma3:4b`（40 亿参数，本地通过 Ollama 运行）下，评估框架在 10 个合成测试用例中报告**60–70% 的准确率**。常见失败模式包括生成语法无效的漏洞利用以及对安全代码产生误报载荷。准确率可通过更大模型提升；提示强化和模型选择是主要的改进杠杆——详见 [`evals/README.md`](./evals/README.md) 了解方法和迭代流程。
## 仓库布局
| 路径 | 角色 |
|------|------|
| `shield-claw/` | 可安装的 `shieldclaw` 包、CLI 和测试 |
| `test_repos/vulnerable-flask-app/` | 用于集成运行的故意易损 Flask + Postgres 演示 |
| `evals/` | 独立的 LLM JSON/拒绝评估（不导入应用程序） |
## 负责任使用
仅对您拥有或明确授权测试的系统与仓库使用 Shield Claw。生成的漏洞利用是真实的攻击代码。
## 许可证
参见仓库根目录下的 [LICENSE](./LICENSE)。
标签：AI风险缓解, Anthropic, CIS基准, DevSecOps, Docker沙箱, Empirical Verification, Ephemeral环境, Git diff, GitHub Pull Request, LLM评估, Maven, Ollama, OpenAI, Shield Claw, 上游代理, 内存规避, 利用开发, 可验证安全, 安全左移, 安全规则引擎, 应用层漏洞, 开源安全工具, 本地LLM, 漏洞证明, 漏洞验证, 生成式AI安全, 虚拟机, 请求拦截, 逆向工具, 逆向工程平台, 静态分析对比