ExploitGym Agent 扩展接口完整教程：如何定制自己的 AI Agent 评测插件（5步上手）

【免费下载链接】exploitgymExploitGym is a large-scale, realistic benchmark built from real-world vulnerabilities designed to evaluate AI agents ability to develop exploits.项目地址https://gitcode.com/gh_mirrors/ex/exploitgym点击查看免费下载ExploitGym 是一个基于真实漏洞构建的大规模 AI Agent 漏洞利用exploit开发评测基准覆盖用户态程序、V8 引擎与 Linux 内核三大场景。本教程面向开发者手把手教你利用它的Agent 扩展接口定制属于自己的 AI Agent 评测插件——只需实现一个类、注册三行代码就能把你自研的 Agent 接入完整的 Docker 化评测管线。为什么需要定制 Agent 插件ExploitGym 的评测流程是标准化的给 Agent 一个任务描述 → Agent 在隔离的 Docker 容器里尝试构造漏洞利用 → 评测器自动判分是否拿到 flag。这套流程对任何编程式 AI Agent 都通用。官方已内置三个 Agent 插件作为参考实现Agent 插件实现文件默认模型Claude Codeclaude_code.pyclaude-sonnet-4-6Codexcodex.pygpt-5.3-codexGemini CLIgemini_cli.pygemini-3.1-pro-preview如果你想评测自研的 Agent或魔改版完全不需要改动评测器Evaluator本身——这正是 Agent 扩展接口的设计目标评测管线与 Agent 实现彻底解耦。评测架构速览Agent 在哪里被调用一切的核心在 Evaluator 基类evaluate()方法的完整管线为根据任务 ID 生成工作区任务描述 prompt启动任务对应的 Docker 容器若开启防火墙把容器挂到安装期全通网络调用Agent.install()安装依赖可选阶段切换容器到仅 API 白名单网络锁死外网调用Agent.run(args)——你的插件在这里执行收集容器内产物flag、PoC、日志等到本地输出目录自动判分写出result.json清理容器三种任务类型各有对应评测器UserEvaluator、KernelEvaluator、V8Evaluator但它们共享同一套 Agent 接口你的插件一次编写三类任务通吃。核心概念Agent 基类的 3 个方法Agent 扩展接口定义在 agents/base.py是一个只有 3 个方法的抽象基类方法作用是否必须实现run(args: AgentFnArguments)驱动 Agent 在容器内执行任务✅ 必须install(container, env, task_id, task_type)安装阶段在有外网时预装依赖可选默认空操作has_install_phase(task_type)声明该任务类型是否需要安装阶段可选默认 False 推荐直接继承 DefaultInstallAgent——它按任务类型自动执行内置的安装脚本见 INSTALL_SCRIPTS内核任务装bison/flex/gdbV8/用户态装基础网络工具你只需要实现run()。AgentFnArguments评测器交给你的任务包run()收到的 AgentFnArguments 携带了执行所需的全部上下文字段含义task_description任务描述 prompt由工作区生成container_id已启动的目标 Docker 容器 IDagent_timeout_secondsAgent 最长运行时间默认 3600sout_dir本地结果输出目录api_key/api_base_url解析好的 LLM API 密钥与代理地址credential_path可选的凭证文件路径如 Claude/Gemini 的登录文件firewall_env防火墙代理环境变量HTTP_PROXY等需合并进容器环境extra_kwargs自由扩展参数在 EvalConfig.agent_extra_kwargs 中配置5 步定制你的 AI Agent 评测插件第 1 步准备运行环境先按官方流程搭好环境详见 docs/setup.md 与 README 快速开始git clone https://gitcode.com/gh_mirrors/ex/exploitgym cd exploitgym uv sync --extra proxy bash scripts/setup/setup_data.sh # 构建静态 gdb/socat/node 与任务数据注意如果你的 Agent 是 Node.js 编写的 CLI需要把它装进静态 Node 运行时data/runtime/node/会挂载为容器内/data参考 docs/setup.md 的第 4 节。评测器约定 Agent 可执行文件放在/data/node/bin/下。第 2 步新建 Agent 模块并实现 run()在 src/cybergym/evaluation/agents/ 下新建my_agent.py模仿 run_codex_with_container 的套路——核心就三件事写入 prompt → 带环境变量的超时执行 → 落盘日志from cybergym.evaluation.agents.helper import DefaultInstallAgent from cybergym.evaluation.types import AgentFnArguments from cybergym.utils import get_docker_client def run_my_agent_with_container(args: AgentFnArguments) - None: client get_docker_client() container client.containers.get(args.container_id) # 1) 把任务描述写入容器 container.exec_run([bash, -c, fcat /tmp/prompt.txt EOF\n{args.task_description}\nEOF]) # 2) 组装环境变量API 密钥 防火墙代理 env {MY_AGENT_API_KEY: args.api_key} if args.firewall_env: env.update(args.firewall_env) # 关键容器内流量走白名单代理 # 3) 带超时执行日志写入 /logs评测结束会被自动拷回本地 container.exec_run([bash, -c, ftimeout {args.agent_timeout_seconds} /data/node/bin/my-agent.sh f /tmp/prompt.txt | tee /logs/my_agent.log], environmentenv, workdir/workspace) class MyAgent(DefaultInstallAgent): def run(self, args: AgentFnArguments) - None: run_my_agent_with_container(args)第 3 步可选定制安装阶段如果 Agent 需要特殊依赖如编译器、调试器覆盖install()即可。安装阶段运行时容器享有全量外网访问之后会被自动切回 API 白名单网络这是官方的先放开、后收紧安全设计见 Agent 基类注释class MyAgent(DefaultInstallAgent): def install(self, container, *, env, task_id, task_type) - None: container.exec_run( [bash, -c, apt-get update apt-get install -y gcc gdb], environmentenv or {})第 4 步在评测入口注册插件打开 examples/run_agent.py做三处小改动在 AGENT_API_ENV_VARS 中登记你的 API Key 环境变量名AGENT_API_ENV_VARS { ... my_agent: MY_AGENT_API_KEY, }在 AGENT_DEFAULT_MODELS 中登记默认模型在 build_agent_spec() 中返回你的 Agent 实例与agent_extra_kwargs这些 kwargs 会原样透传到args.extra_kwargs方便传递模型名等参数if args.agent my_agent: return SimpleNamespace( agentMyAgent(), agent_extra_kwargs{my_model: args.model}, direct_api_key_envMY_AGENT_API_KEY, )第 5 步启动评测并查看结果先按 docs/eval.md 启动 controller以及可选的防火墙与 LLM 预算代理然后export MY_AGENT_API_KEY... uv run examples/run_agent.py --agent my_agent --use-api-key \ --tasks-file data/task_ids/sample.txt --first-n 1结果输出在out/run_agent/family/task-id/result.json记录得分flag 命中即 1.0task.log与logs/保存 Agent 全量日志outputs/收集 flag 与 PoC详见 docs/eval.md 的 Output 一节。进阶技巧让插件像官方的一样流式日志渲染官方 Agent 都用低层client.api.exec_createexec_start(streamTrue)流式读取输出再经各自的 stream renderer 渲染成人读日志同时用 IntermediateStatsLogger 每 20 分钟记录一次耗时与 API 花费。长任务排障时非常有用。预算管控只要评测配置里提供了key_managerLiteLLM/LLM 代理模式生成的临时密钥自带预算上限你的 Agent 无需任何改动即自动受限EvalConfig.allowed_models还能把密钥限定到指定模型。防火墙兼容务必把args.firewall_env合并进容器环境变量否则开启--use-firewall后容器内流量会绕过白名单代理而失败。凭证文件若 Agent 使用登录态文件而非 API Key把宿主机路径填进credential_path用 container_credential_symlink 软链进容器结束后记得清理。✅漏洞利用归因flag 得分之外可用 agent_scorer/ 判定 Agent 是否真正利用了目标漏洞而非撞库这是排行榜的核心指标之一。关键文件清单速查用途文件Agent 扩展接口基类agents/base.py默认安装阶段 / 统计日志agents/helper.py参数与结果类型定义evaluation/types.py评测管线Evaluatorevaluation/base.py评测入口脚本examples/run_agent.py评测全流程文档docs/eval.md环境与运行时构建docs/setup.md常见问题QAgent 执行失败会影响判分吗run()抛异常会被评测器捕获并记入日志任务继续走收集/验证阶段最终result.json里体现为 0 分——不会因为一个任务炸掉整个批量评测。Q可以只改 prompt 格式吗可以不用动 Agent 接口。EvalConfig.task_description_template 支持用{task_description}模板包裹原始任务描述。Q如何保留容器现场调试运行时加--keep-container评测结束后容器不删除可直接docker exec进去检查。 总结ExploitGym 的 Agent 扩展接口 实现run() 可选install() 三行注册。理解 AgentFnArguments 的任务包结构和 Evaluator 管线 后你的自研 Agent 就能在 869 个真实漏洞任务上与官方三大 Agent 同台竞技了。赞分享【免费下载链接】exploitgymExploitGym is a large-scale, realistic benchmark built from real-world vulnerabilities designed to evaluate AI agents ability to develop exploits.项目地址https://gitcode.com/gh_mirrors/ex/exploitgym点击查看免费下载相关推荐如何为Headlong编写自己的thinkerAgent扩展开发完整指南如何为Headlong编写自己的thinkerAgent扩展开发完整指南 Headlong 是一个开源的 Agent 微内核agent microharneOpenLogi 配置容错机制详解严格校验、原子写入与 5 份自动备份如何救急OpenLogi 配置容错机制详解严格校验、原子写入与 5 份自动备份如何救急 OpenLogi 是一款用 Rust 编写的本地优先local first桌面应用DLSS Swapper:游戏里的旧版 DLSS 免费一键升级,翻车随时还原DLSS Swapper:游戏里的旧版 DLSS 免费一键升级,翻车随时还原 我刚才把 nvngx_dlss.dll 换成新版、重启游戏,同一画质档位比之前更锐桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考