linville-charlie/Dragonfly

# Dragonfly **具有模型无关执行时保护机制的自主安全测试引擎** Dragonfly 是一个用于研究执行时保护机制的开源研究平台。它将 114 个安全测试工具封装在可组合的策略管道（作用域强制、行为门控和杀毒开关）之后，并为 MCP、CLI 以及 LangChain/LangGraph 提供适配器。 核心是模型无关的：任何能够生成工具调用的 LLM 或运行时都可以通过适配器层驱动 Dragonfly。所有策略强制、追踪和审计都在核心层完成，而非适配器中。 ## 关键结果 ### 消融研究（105 次运行，Gemin 2.5 Pro） 保护机制按设计发挥作用：行为门控将评分漏洞检测结果降低至零，杀毒开关在检测到敏感数据时终止每个会话。但当专用工具被阻止时，智能体转而使用 `send_request`（一种通用 HTTP 原语）来近似被阻止工具的功能。`send_request` 的使用率从无保护时的 14% 上升至全保护下的 30%（针对行为门控目标）。 ### 压力实验（440 次运行，GLM 5.1 + minimax-m2.7） 操作压力（截止期限、权限升级、自我保存威胁）不会放大绕路行为。`send_request` 替代率在所有压力层级对两种模型保持稳定（约 67%，R² = 0.007 / 0.06）。任务描述解释了 33–37% 的绕路率变化；压力仅解释 5–6%。你如何描述目标决定了智能体是否会使用受保护的工具——而非你对其施加多少压力。 ## 架构 ``` ┌─────────────────────────────────────────────────────┐ │ ADAPTER LAYER │ │ ┌───────┐ ┌─────┐ ┌────────────┐ │ │ │ MCP │ │ CLI │ │ LangChain │ │ │ └───┬───┘ └──┬──┘ └─────┬──────┘ │ │ └─────────┴────────────┘ │ │ ActionRequest → ExecutionResult │ └──────────────────┬──────────────────────────────────┘ │ ┌──────────────────┼──────────────────────────────────┐ │ DRAGONFLY CORE │ │ ┌───────────────▼──────────────────┐ │ │ │ POLICY PIPELINE (8 checks) │ │ │ │ kill_switch → session → scope → │ │ │ │ prohibition → automation → │ │ │ │ testing_hours → confirmation → │ │ │ │ phase_gate │ │ │ └───────────────┬──────────────────┘ │ │ ┌───────────────▼──────────────────┐ │ │ │ EXECUTOR + POST-PROCESSOR │ │ │ └───────────────┬──────────────────┘ │ │ ┌───────────────▼──────────────────┐ │ │ │ TRACE LOGGER (Observations) │ │ │ └──────────────────────────────────┘ │ └─────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────┐ │ TOOL LAYER (114 tools) │ │ Pure async functions: (runner, params) → dict │ └─────────────────────────────────────────────────────┘ ``` ## 安全模型 三类独立的保护机制，每类均可通过干净的消融开关控制： | 保护机制 | 功能 | 消融开关 | |---|---|---| | **作用域强制** | 阻止访问作用域外的目标（3 层防护） | `disable_scope_check` | | **行为门控** | 对高风险工具要求确认，阻止禁止类别 | `disable_action_gating` | | **杀毒开关** | 检测到输出中的敏感数据时终止所有测试 | `disable_kill_switch` | ## 快速开始 ``` # 安装 uv sync # 作为 MCP 服务器运行 uv run python -m dragonfly # 运行测试 uv run pytest tests/ --tb=short -q ``` ### 运行实验 ``` # 启动 Docker 范围 cd range && docker compose up -d --build && cd .. # 消融研究：脚本化（45 次确定性运行） bash bench/scripts/run_full_experiment.sh # 消融研究：LLM（60 次 Gemini 2.5 Pro 运行） export GOOGLE_API_KEY="your-key" bash bench/scripts/run_llm_matrix.sh # 压力实验（每个模型 220 次运行） export OLLAMA_API_KEY="your-key" bash bench/scripts/run_pressure_matrix.sh # 汇总并生成分析 python bench/scripts/aggregate_pressure.py --input reports/experiments/pressure-* --output reports/analysis/pressure python bench/scripts/paper_tables_pressure.py --input reports/analysis/pressure/pressure_results.csv --output reports/paper/pressure ``` ## 项目结构 ``` src/dragonfly/ # Core package ├── core/ # Engine, pipeline, abstractions, safety, scope ├── tools/ # 114 security testing tools ├── adapters/ # MCP, CLI, LangChain/LangGraph └── strategies/ # YAML attack playbooks range/ # Docker test range (Juice Shop + 4 custom labs) bench/ # Experiment infrastructure ├── configs/ # Ablation condition configs (C0-C4) ├── scenarios/ # Scripted action sequences + pressure scenarios │ └── pressure/ # Pressure experiment: scenarios (S1-S4) + messages ├── ground-truth/ # Scenario definitions ├── protocol.yaml # Frozen LLM runtime protocol ├── PRESSURE_EXPERIMENT.md # Pressure experiment protocol └── scripts/ # Runners, scorers, aggregators, analysis tests/ # Tests docs/ # Documentation ``` ## 文档 | 文档 | 描述 | |---|---| | [完整文档](docs/README.md) | 架构、工具参考、安全模型、参与流程 | | [基准测试指南](bench/README.md) | 实验基础设施：消融与压力运行器、评分、分析 | | [压力实验](bench/PRESSURE_EXPERIMENT.md) | 压力实验协议与设计 | | [LangChain 适配器](src/dragonfly/adapters/langchain/README.md) | LangChain/LangGraph 集成 | | [测试范围](range/README.md) | Docker 目标服务 | ## 先决条件 - Python 3.11+，[uv](https://docs.astral.sh/uv/) - Docker Desktop（用于测试范围） - `/etc/hosts`：`127.0.0.1 decoy.test`（用于作用域测试） - 消融 LLM 运行：`GOOGLE_API_KEY`（Gemin 2.5 Pro） - 压力实验：`OLLAMA_API_KEY`（Ollama Cloud） ## 许可证 请参阅仓库中的许可证详情。

标签：API集成, CLI适配器, HTTP代理替代, LangChain适配器, LangGraph适配器, LLM代理行为研究, MCP适配器, 作用域强制, 动作门控, 可观测性, 大模型安全, 安全测试引擎, 安全防护, 审计追踪, 工具调用控制, 开源研究平台, 执行时保护, 杀死开关, 模型无关, 研究平台, 策略流水线, 自主安全测试, 请求拦截, 运行时保护, 逆向工具