packetcraft/Omaha-Lab

# Omaha-Lab **针对本地 LLM 安全、Agentic 工具调用和 OWASP 缓解措施的实践实验室指南。** Omaha-Lab (**O**llama + **M**ac/Windows + **H**uman + **A**gent) 是一个优先在本地运行的环境，用于探索自主 Agent 推理和安全防护机制。所有推理均在您的硬件上运行 —— 无需云端 LLM 端点。 ## 前置条件 | 需求 | 版本 | 备注 | |---|---|---| | Python | **3.11** | `python3.11 --version` | | Ollama | 0.3.x+ | [ollama.com](https://ollama.com) | | Git | 任何最新版本 | — | | RAM | 最低 16 GB | 推荐 32 GB | | 存储空间 | 剩余 25 GB | 推荐 50 GB | | 操作系统 | macOS 13+ 或 Windows 11 | — | **可选 API 密钥**（免费层级 —— 如未提供则使用 DuckDuckGo）： - [OpenWeatherMap](https://openweathermap.org/api) — `WEATHER_API_KEY` - [Tavily](https://tavily.com) — `SEARCH_API_KEY` ## 设置 ### 选项 A — 单条命令（推荐） ``` git clone https://github.com/omaha-lab/omaha-lab.git cd omaha-lab make install # venv + all deps (core, UI, observability) + spacy model + .env make models # pulls ~7 GB of Ollama models — grab a coffee ``` ### 选项 B — 手动步骤 ``` # 1. Clone git clone https://github.com/omaha-lab/omaha-lab.git cd omaha-lab # 2. 创建 venv (需要 Python 3.11) python3.11 -m venv venv # macOS py -3.11 -m venv venv # Windows Git Bash # 3. 安装依赖 venv/bin/pip install -r requirements.txt # macOS venv/Scripts/pip install -r requirements.txt # Windows # 4. 安装可选包 (Web UI + observability) venv/bin/pip install chainlit "arize-phoenix>=15.0" "arize-phoenix-otel>=0.16" \ openinference-instrumentation openinference-instrumentation-langchain \ openinference-semantic-conventions opentelemetry-api opentelemetry-sdk \ opentelemetry-exporter-otlp-proto-http # 5. 下载 spacy 模型 venv/bin/python -m spacy download en_core_web_lg # macOS venv/Scripts/python -m spacy download en_core_web_lg # Windows # 6. 拉取 Ollama 模型 (总计约 7 GB) ollama pull qwen2.5:1.5b # default model, CPU-friendly ollama pull nomic-embed-text # RAG embeddings ollama pull llama-guard3 # input safety classifier # 7. 配置环境 cp .env.example .env # then add your API keys ``` ## 快速开始 ``` make run # base agent — no guardrails, no RAG make run-secure # Llama Guard + Presidio + HITL make run-rag # RAG analyst — security_analyst persona + retrieval make run-full # full defense stack — all layers on ``` 或者直接调用 CLI 进行自定义组合： ``` # 1. Baseline — 观察原始 agent 流量，无防御 # Labs: 1.3 Reading the ReAct Trace · 1.6 Visualizing the Agent Pipeline with Phoenix venv/bin/python agent.py --persona customer_service --observe on # 2. 仅 RAG — 在 Phoenix 中观察检索 traces # Labs: 1.5 Enabling RAG with a Markdown Context Document · 4.3 RAG Pipeline Internals venv/bin/python agent.py --persona security_analyst --rag on --observe on # 3. 仅 Guard — 在 traces 中查看 Llama Guard 拦截 + Presidio 脱敏 # Labs: 3.1 Enabling Llama Guard 3 on Inputs · 3.3 PII Redaction with Microsoft Presidio venv/bin/python agent.py --persona hr_assistant --guard on --observe on # 4. RAG + Guard — 带安全过滤的检索；比较与选项 2 的延迟 # Labs: 3.2 Applying Llama Guard 3 to Retrieved RAG Chunks · 3.9 Grounding with RAG and Search venv/bin/python agent.py --persona code_assistant --rag on --guard on --observe on # 5. 完整技术栈 — 开启所有层；用作加固的评估 baseline # Labs: 3.4 HITL Authorization Breakpoint · 3.10 Measuring Guard Coverage with the Evaluation Harness venv/bin/python agent.py --persona hr_assistant --rag on --guard on --hitl on --observe on ``` **CLI 标志：** | 标志 | 值 | 默认值 | 描述 | |---|---|---|---| | `--persona` | `customer_service`, `hr_assistant`, `security_analyst`, `code_assistant` | 无 | 加载 Agent 人设 | | `--rag` | `on` / `off` | `off` | 启用从 `context_docs/` 进行 RAG 检索 | | `--guard` | `on` / `off` | `off` | 启用 Llama Guard 3 输入过滤 + Presidio 输出脱敏 | | `--hitl` | `on` / `off` | `off` | 为高风险工具调用启用 Human-in-the-Loop 授权 | | `--max-iterations` | 整数 | `10` | Agent 步骤的硬性上限 —— 停止失控的工具循环 | | `--observe` | `on` / `off` | `off` | 将追踪数据流式传输到运行在 `http://127.0.0.1:6006` 的 Phoenix 服务器 | ## Web UI（可选） 一个基于浏览器的聊天界面，将每个 Pipeline 层渲染为可折叠的步骤卡片。 ``` make ui # opens http://localhost:8000 ``` 从配置选择器中选择一个**实验模式**： | 实验模式 | 激活层 | CLI 等效项 | |---|---|---| | **Bare** | 无 | `python agent.py` | | **Guarded** | Llama Guard 3 · Presidio · HITL | `python agent.py --guard on --hitl on` | | **RAG Analyst** | RAG · Security Analyst persona | `python agent.py --persona security_analyst --rag on` | | **Full Defense** | 所有层 | `python agent.py --persona hr_assistant --rag on --guard on --hitl on` | 侧边栏的齿轮图标允许您在会话中途切换各个层，而无需重新启动。颜色编码的 Pipeline 图（🟢 已触发 · 🔵 空闲 · 🔴 已阻止）会在每次消息后更新。参见[实验 1.7](labs/module1/lab1_7_chainlit_pipeline_diagram.md)。 ## 可观测性 / LLM 追踪（可选） [Arize Phoenix](https://phoenix.arize.com) 捕获每个 Pipeline 节点的完整输入/输出，并带有 Token 级别的细节。 在**专用终端**中启动 Phoenix 并保持其运行： ``` make phoenix # opens http://127.0.0.1:6006 ``` 然后使用 observe 标志运行 Agent： ``` venv/bin/python agent.py --observe on # 或者通过 CLI 直接在任何 make run-* 命令中添加 --observe on ``` | Phoenix 显示内容 | 查看位置 | |---|---| | 每个 LLM 节点的输入/输出 | Span 详情 → Input messages / Output 标签页 | | 工具调用参数和结果 | `get_weather`, `web_search` Span | | Guard 短路（被阻止的输入） | Trace 在 `guard_input` Span 后结束 | | RAG 检索到的块 | `rag` Span → Output 标签页 | | 每个节点的 Token 计数和延迟 | Span 标题 | Trace 数据在重启后会持久化保存在 `~/.phoenix/` 中。如果您在启动 `make ui` 时 Phoenix 已经运行，Chainlit UI 会自动连接 —— 无需额外标志。参见[实验 1.6](labs/module1/lab1_6_visualizing_the_pipeline.md)。 ## Pipeline 架构 ``` User Input │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Regex Pre-filter (S15: Prompt Injection patterns) │ └──────────────────────┬──────────────────────────────────┘ │ no match ▼ ┌─────────────────────────────────────────────────────────┐ │ Llama Guard 3 (Input Guardrail — S1–S14) │ └──────────────────────┬──────────────────────────────────┘ │ safe ▼ ┌─────────────────────────────────────────────────────────┐ │ RAG Retrieval (ChromaDB + nomic-embed-text) │ └──────────────────────┬──────────────────────────────────┘ │ top-3 chunks ▼ ┌─────────────────────────────────────────────────────────┐ │ Reason Node (LLM, tools disabled) │ │ [REASON] step-by-step thought before any tool call │ └──────────────────────┬──────────────────────────────────┘ │ thought injected into context ▼ ┌─────────────────────────────────────────────────────────┐ │ Agent Node (LLM + tool registry) │ │ [ACT] tool call ─or─ [RESPOND] final answer │ └──────────────────────┬──────────────────────────────────┘ │ high-risk tool? ▼ ┌─────────────────────────────────────────────────────────┐ │ HITL Authorization (human approve/deny) │ └──────────────────────┬──────────────────────────────────┘ │ approved → Tool executes │ └─ result fed back to Agent Node ▼ ┌─────────────────────────────────────────────────────────┐ │ Output Guardrails │ │ Presidio PII Redaction │ │ Canary Token Detection │ └──────────────────────┬──────────────────────────────────┘ │ ▼ Response ``` | 层 | 技术 | |---|---| | 本地 LLM 推理 | Ollama (Metal / CUDA / CPU) | | 默认模型 | Qwen 2.5 1.5B — 对 CPU 友好，支持工具调用 | | 全性能选项 | Qwen 2.5 7B — 更强的推理能力，约 8 GB VRAM | | Agent 编排 | LangGraph (ReAct 循环) | | 向量存储 / RAG | ChromaDB + nomic-embed-text | | 输入防护栏 | 正则表达式预过滤 + Llama Guard 3 | | PII 脱敏 | Microsoft Presidio | | 授权 | Human-in-the-Loop (HITL) | ## 实验指南 | 模块 | 重点 | 实验 | |---|---|---| | [模块 1 — 基础知识](labs/module1/) | 环境、首个 Agent、人设、RAG、Phoenix、Chainlit | 1.1 – 1.7 | | [模块 2 — 进攻性安全](labs/module2/) | OWASP LLM01–LLM10 攻击练习 | 2.1 – 2.9 | | [模块 3 — 防御架构](labs/module3/) | 启用并验证每个防护栏层；衡量覆盖率 | 3.1 – 3.10 | | [模块 4 — 架构深入探讨](labs/module4/) | 阅读并修改核心代码 — LangGraph、工具、RAG、防护栏 | 4.1 – 4.5 | 从这里开始：[`labs/module1/lab1_1_environment_setup.md`](labs/module1/lab1_1_environment_setup.md) ## 开发 ``` make test # 107 tests, no live Ollama required make bench-regex # evaluation harness — regex pre-filter only, instant make bench # evaluation harness — full guard stack (needs llama-guard3) ``` ## 贡献 有关 Pull Request 指南和 Issue 分类策略，请参阅 [CONTRIBUTING.md](.github/CONTRIBUTING.md)。 ## 许可证 [MIT](LICENSE) © 2026 Omaha-Lab 贡献者

标签：AI安全防护, AI红队, AI风险缓解, Chainlit, CISA项目, Guardrails, IP 地址批量处理, LangChain, LLM Agent, LLM Red Teaming, LLM评估, Ollama, Prompt注入, Python, ReAct代理, 人工智能攻防, 大模型安全, 安全实验室, 安全指南, 安全缓解, 工具调用, 插件系统, 无后门, 本地大语言模型, 本地部署, 模型越狱测试, 沙盒, 网络安全实验, 自主智能体, 轻量级, 逆向工具