Tech-Multiverse/crapi-llm-security-lab
GitHub: Tech-Multiverse/crapi-llm-security-lab
一个基于 OWASP crAPI 与 Ollama 的本地自托管红队实验室，用于实践 API 安全、LLM 越狱及 AI Agent 攻防演示。
Stars: 0 | Forks: 0
# crAPI-LLM Security Lab
一个用于 API 安全、LLM 应用安全和 Agentic AI 演示的本地化、可共享实验室。
它将 OWASP crAPI 易受攻击的 API 应用与 Ollama LLM（本地或远程）、基于 LangGraph 的聊天机器人/MCP 服务器、自定义 Python agent 以及带有流量分析的可选 API 网关结合在一起。
## 用途
本实验室是一个用于学习和实践 API 安全、LLM 应用安全以及 Agentic AI 安全的本地化、可共享环境。它的目标是：
- **可复现**：只需一个 `docker compose up` 命令即可启动 crAPI、agent、网关和演示 UI。
- **可扩展**：旨在添加 WAAP 引擎、集中式日志记录、LLM 防护栏以及更高级的 agent 工作流。
- **教学性**：直接映射到 OWASP API Security Top 10、OWASP LLM / AI 安全风险、WAAP 和运行时安全概念，以及 agent 与 API/工具的交互。
## crAPI（develop 分支）提供的内容
OWASP crAPI 的 `develop` 分支包含：
- 经典的 OWASP API Security Top 10 挑战（BOLA、BFLA、失效的身份认证、过度数据暴露、大规模赋值、速率限制、SSRF、NoSQL/SQL 注入、JWT 伪造、未授权访问）。
- 一个内置的 LLM 聊天机器人（`crapi-chatbot`），它使用 LangGraph 通过 OpenAPI 规范调用 crAPI API。
- 端口 `5500` 上的 MCP (Model Context Protocol) 服务器，将相同的 API 接口暴露为工具。
- 特定的 LLM 挑战 16–18：提示词注入、凭据提取和代表其他用户执行操作。
- 用于 SSRF 挑战的虚假外部网关服务（`api.mypremiumdealership.com`）。
## 我们添加的内容
- 一个顶层 `docker-compose.yml`，它 `include`（包含）了 crAPI 的 compose 配置，并暴露了用于本地测试的直接服务端口。
- 一个根目录下的 `.env` 文件，将所有配置集中在一处；从 `.env.example` 复制它，并将其指向你的 Ollama 实例。
- 一个用于 Python agent 开发的 `crapi-llm` Miniconda 环境。
- 一个小补丁（`infrastructure/crapi-chatbot-patches/retriever_utils.py`），使 crAPI 的聊天机器人使用 `OllamaEmbeddings` 而不是 `OpenAIEmbeddings` 作为向量存储的后端，因为后者会发送 Ollama 的 OpenAI 兼容 `/v1/embeddings` 端点所拒绝的 token 数组。
- 一个 `agent/` 目录，包含一个通过 Ollama 驱动 crAPI 的自定义 Python agent。
- 一个 `gateway/` 目录，包含 Kong 网关、速率限制、WAF 风格的路径拦截、Prometheus 指标和 Grafana 仪表板。
- 一个 `ui/` 目录，包含 Vite + React 演示界面，此外还有 `scripts/`，内含一键攻击/防御场景脚本。
## 架构
```
Host workstation
├─ Docker Desktop
│ └─ crAPI stack
│ ├─ crapi-identity :8080
│ ├─ crapi-community :8087
│ ├─ crapi-workshop :8000
│ ├─ crapi-chatbot :5002 (chat) / :5500 (MCP)
│ ├─ crapi-web :8888
│ ├─ postgres :5432
│ ├─ mongodb :27017
│ ├─ chromadb :8000
│ ├─ mailhog :8025
│ └─ api.mypremiumdealership.com
│
├─ Conda env `crapi-llm`
├─ agent/ Python demos
├─ gateway/ Kong + Prometheus + Grafana
└─ ui/ Vite + React demo interface
Ollama (local install, remote GPU box, or Docker)
├─ llama3.1:8b (chat / tool calling)
└─ nomic-embed-text:latest (embeddings)
```
## 网络拓扑
`docker-compose.yml` 使用 `include` 指令引入 `crapi/deploy/docker/docker-compose.yml`，然后覆盖选定的端口。
- Docker Compose 会创建一个名为 `crapi-llm_default` 的默认 bridge 网络。
- 在该网络内部，服务之间通过容器名称进行通信（例如 `crapi-chatbot` 调用 `http://crapi-identity:8080`）。
- 主机通过 `127.0.0.1` 访问已发布的服务：
- `http://127.0.0.1:8888` crAPI Web UI
- `http://127.0.0.1:8080` 身份服务
- `http://127.0.0.1:8087` 社区服务
- `http://127.0.0.1:8000` 研讨会服务
- `http://127.0.0.1:5002` 聊天机器人 API (`/chatbot/genai/ask`)
- `http://127.0.0.1:5500` MCP 服务器
- `http://127.0.0.1:8025` MailHog UI
- `http://127.0.0.1:3001` React 演示 UI (`crapi-ui`)
- `http://127.0.0.1:8088` Kong 网关代理
- `http://127.0.0.1:13000` Grafana (admin/admin)
- `http://127.0.0.1:19090` Prometheus
- `crapi-chatbot` 容器会离开 Docker 网络去访问 Ollama，无论 Ollama 运行在哪里（本地主机、另一个容器或远程 GPU 机器）。
## 环境要求
- macOS、Linux 或带有 WSL2 / Docker Desktop 的 Windows（已在基于 Intel / `x86_64` 架构的 macOS 上测试）
- 正在运行的 Docker
- Docker Compose v2.20+（根目录的 `docker-compose.yml` 使用了 `include`）
- Miniconda（可选，用于本地 Python agent 开发）
- Node.js / `nvm`（可选，用于 React UI 开发）
- Docker 可访问的 Ollama。选项包括：
- **本地安装** 在运行 Docker 的同一台机器上（支持 CPU 或 GPU）
- **远程机器** （例如带有 GPU 的 Linux 主机）在同一网络内
- **带有 GPU 支持的 Docker**（可选，需要 `nvidia-container-toolkit`）
## 快速开始
1. 克隆此仓库：
git clone crAPI-LLM
cd crAPI-LLM
2. 克隆 crAPI 子模块：
git clone --depth 1 --branch develop https://github.com/OWASP/crAPI.git crapi
3. 复制 `.env` 并将 crAPI 指向你的 Ollama 服务器：
cp .env.example .env
# 编辑 .env 并将 OLLAMA_HOST_IP 设置为 crAPI 容器可访问 Ollama 的 IP 或主机名
# （示例请参见下方的“将 crAPI 指向 Ollama”）。
4. 确保 Docker Desktop 正在运行，然后启动技术栈（这也会启动网关、Grafana 和 React UI）：
docker compose up -d
5. 验证：
docker compose ps
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:8888
6. 在 `http://127.0.0.1:3001` 打开演示 UI。
7. 从命令行测试聊天机器人：
curl -s -X POST http://127.0.0.1:5002/chatbot/genai/ask \
-H "Content-Type: application/json" \
-d '{"message":"hello"}'
## 将 crAPI 指向 Ollama
聊天机器人和 agent 使用 Ollama 在端口 `11434` 上暴露的 OpenAI 兼容端点。更新 `.env` 以便 crAPI 容器能够访问它。
常见设置：
| Ollama 运行位置 | `OLLAMA_HOST_IP` 值 | 备注 |
|---------------------|-------------------------|-------|
| 与 Docker Desktop 同一主机 (macOS/Windows) | `host.docker.internal` | Docker Desktop 会将其解析为主机。 |
| 同一主机，Linux Docker Engine | 主机的局域网 IP（例如 `192.168.1.42`）或 `172.17.0.1` | 在 Linux Docker Engine 上 `host.docker.internal` 不是自动的。 |
| 远程 GPU 机器 / 另一台机器 | 其 IP（例如 `192.168.1.50`） | 防火墙必须允许来自 Docker 主机的 TCP `11434` 端口。 |
例如，对于远程 GPU 机器：
```
OLLAMA_HOST_IP=192.168.1.50
CHATBOT_OPENAI_BASE_URL=http://${OLLAMA_HOST_IP}:11434/v1/
```
对于在 Docker Desktop macOS/Windows 上的本地 Ollama：
```
OLLAMA_HOST_IP=host.docker.internal
CHATBOT_OPENAI_BASE_URL=http://${OLLAMA_HOST_IP}:11434/v1/
```
对于运行在主机上（非 Docker 中）的 agent，你也可以导出：
```
export OLLAMA_BASE_URL=http://${OLLAMA_HOST_IP}:11434/v1
```
编辑 `.env` 后，重建聊天机器人容器：
```
docker compose up -d
```
## Ollama 设置
这些说明适用于 Linux、macOS 或 Windows（带有 WSL2 / Docker）。它们假设你希望将所有内容保持自托管；不需要第三方 LLM API 账户。
### 1. 安装 Ollama
请按照适用于你的操作系统的官方指南进行操作：
```
# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh
# Windows：使用来自 https://ollama.com/download/windows 的安装程序
# 或在 WSL2 内部运行，使用与 Linux 相同的命令。
```
### 2. 拉取模型
适用于 8 GB GPU 或 CPU 主机的推荐模型：
```
ollama pull llama3.1:8b
ollama pull nomic-embed-text:latest
```
### 3. 将 Ollama 暴露给网络
默认情况下，Ollama 仅监听 `127.0.0.1:11434`。如果你在 Docker 中运行 crAPI，容器需要访问它，因此请绑定到所有网络接口：
```
OLLAMA_HOST=0.0.0.0 ollama serve
```
在 Windows 命令提示符中：
```
set OLLAMA_HOST=0.0.0.0
ollama serve
```
在 Windows PowerShell 中：
```
$env:OLLAMA_HOST="0.0.0.0"
ollama serve
```
如果 Ollama 在远程机器上，请确保主机防火墙允许来自 Docker 主机子网的入站 TCP `11434` 流量。
### 4. 可选：将模型存储在不同的驱动器上
在 Windows 上：
```
set OLLAMA_MODELS=D:\OllamaModels
```
在 Linux / WSL2 上：
```
export OLLAMA_MODELS=/mnt/d/OllamaModels
```
## 测试过的配置
本仓库是基于以下环境开发的：
- 一台运行 Docker Desktop 的 Mac 主机
- 一台独立的、带有 NVIDIA GPU 并运行 Ollama（`llama3.1:8b` 和 `nomic-embed-text:latest`）的 Linux 机器
- 该 Mac 通过局域网访问位于 `http://192.168.4.55:11434/v1` 的 Ollama
任何 Docker 可以访问到你在 `.env` 中填写的 URL 对应的 Ollama 的设置，都应该能以相同的方式工作。
## 为什么需要 `retriever_utils.py` 补丁？
crAPI 的聊天机器人被硬编码为对 `openai` 提供程序使用 `OpenAIEmbeddings`。`OpenAIEmbeddings` 使用 `tiktoken` 对文本进行分词，并将 token ID 数组发送到 `/v1/embeddings`。Ollama 的 OpenAI 兼容端点期望接收字符串，因此它会返回 `invalid input type`。
`infrastructure/crapi-chatbot-patches/retriever_utils.py` 中的补丁会在设置了非默认 `CHATBOT_OPENAI_BASE_URL` 时改用 `OllamaEmbeddings`，并且它会被挂载覆盖 `crapi-chatbot` 容器中的 `/app/chatbot/retriever_utils.py`。
## React 演示 UI 和场景脚本
一个 Vite + React UI 被打包为 `crapi-ui` 容器，并在端口 `3001` 上提供服务：
- **聊天机器人** 标签页 — 通过 Ollama 与 crAPI 聊天机器人对话。
- **API 浏览器** 标签页 — 直接向 crAPI 端点发送请求。
- **场景** 标签页 — 一键重放攻击/防御演示（速率限制 DoS、SSRF 拦截、提示词注入、NoSQL 优惠券注入）。
在 `docker compose up -d` 之后打开 `http://127.0.0.1:3001`。
命令行等效脚本位于 `scripts/` 中：
```
./scripts/rate-limit-demo.sh
./scripts/ssrf-blocked-demo.sh
./scripts/prompt-injection-demo.sh
./scripts/agent-demo.sh
```
## 路线图和未来计划
有关完整的阶段计划，请参阅 `ROADMAP.md`。
crAPI 为我们提供了易受攻击的 API 和内置的 LLM 聊天机器人。本仓库使用由 Ollama 提供支持的 agent、带有指标的 Kong 网关以及 React 演示 UI 对其进行了扩展。未来可能添加的内容：
1. **WAAP / ModSecurity / open-appsec**
用真正的 WAAP 引擎和 OWASP CRS 规则替换或增强简单的 Kong 路径拦截。
2. **集中式日志分析**
添加 Loki、Vector 或 ClickHouse，以收集用于取证重放的请求/响应体和 agent 日志。
3. **LLM 防护栏**
尝试输入/输出过滤、提示词注入检测和工具调用确认 UI。
4. **高级 Agentic 演示**
多步骤 agent 攻击、自主发现以及 agent 到 agent 的工作流。
5. **刷新文档**
持续将新的挑战和缓解措施映射到 OWASP API Security、OWASP LLM / AI 安全风险以及 NIST AI RMF。
## 项目结构
```
crAPI-LLM/
├── .env # Docker Compose environment
├── docker-compose.yml # includes crAPI + port overrides + patch mount
├── README.md # this file
├── agent/ # custom Python agent demos
├── docs/ # write-ups and challenge mapping
├── gateway/ # Kong + Prometheus + Grafana configs
├── scripts/ # one-click attack/defense scenario scripts
├── infrastructure/ # support files for the lab
│ └── crapi-chatbot-patches/
│ └── retriever_utils.py # Ollama embedding fix
├── ui/ # Vite + React demo interface
└── crapi/ # cloned OWASP crAPI (develop branch)
```
## 常用命令
```
# 查看所有正在运行的 crAPI 服务
docker compose ps
# 查看 chatbot 日志
docker compose logs -f crapi-chatbot
# 停止所有操作
docker compose down
# 停止并删除 data volumes（破坏性操作）
docker compose down -v
# 直接测试 chatbot
curl -s -X POST http://127.0.0.1:5002/chatbot/genai/ask \
-H "Content-Type: application/json" \
-d '{"message":"hello"}'
# 从 Docker 主机测试 Ollama
curl http://${OLLAMA_HOST_IP}:11434/api/tags
```
## 许可证
本项目结构和文档仅用于教育和演示目的。crAPI 本身基于 Apache 2.0 许可。
标签：AI风险缓解, API安全, CISA项目, JSON输出, LangGraph, LLM评估, Ollama, 安全测试靶场, 数据展示, 红队, 自定义请求头, 请求拦截, 逆向工具