【免费下载链接】DecepticonAutonomous Hacking Agent for Red Team项目地址https://gitcode.com/gh_mirrors/de/Decepticon点击查看免费下载Decepticon 是面向红队场景的自主攻击 Agent 框架其插件体系允许在不修改开源主代码的前提下向任意 Agent 追加或替换中间件middleware。本文以官方示例decepticon-example-middleware为骨架完整讲解中间件插件从decepticon-sdk plugin new脚手架生成、pyproject.toml入口点注册、uv build构建安装到框架端build_middleware装配的完整生命周期并给出基于FakeBackend/FakeLLM/FakeSandbox的免框架 hermetic 测试方法。读完本文你将能独立编写、打包、安装并测试一个可被 Decepticon 自动发现的中间件插件。中间件在 Decepticon 中的定位一个协议、一组命名槽位在 Decepticon 中中间件是 Agent 每次模型调用model call前后的拦截与改写层负责承载知识库注入、RoE 规则执行、HITL 审批、prompt 注入防护、预算控制、事件日志等横切能力。插件作者实现的中间件需要满足MiddlewareProtocol这是一个runtime_checkable协议定义于 decepticon_core/protocols/middleware.py必备属性name人读的中间件标识用于内省、slot该中间件占据的MiddlewareSlot接受枚举值或插件自定义字符串、priority槽位内的装配排序提示数值越小越靠前官方约定 OSS 中间件用 100/200/…插件常用 50 表示替换在标准之前、150 表示替换在标准之后。必备方法wrap_model_call(state, runtime, config)——Agent 运行器在每次模型调用时调用主回调。可选钩子框架只调用存在的部分before_agent、after_agent、modify_request。MiddlewareSlot是一个StrEnum声明顺序即装配顺序完整枚举定义于 decepticon_core/contracts/slots.py包括ENGAGEMENT_CONTEXT、ROE_GUARDRAIL、HITL_APPROVAL、UNTRUSTED_OUTPUT、PROMPT_INJECTION_SHIELD、SKILLS、FILESYSTEM、SUBAGENT、OPPLAN、KG、EVENT_LOG、SANDBOX_NOTIFICATION、OPSCONTROL_NOTIFICATION、BUDGET、MODEL_OVERRIDE、MODEL_FALLBACK、PROXY_KEY_OVERRIDE、SUMMARIZATION、PROMPT_CACHING、PATCH_TOOL_CALLS等约 20 个命名槽位。每个 Agent 角色role只装配自己声明的那部分槽位映射关系集中在SLOTS_PER_ROLE同样定义于 slots.py例如recon/exploit/postexploit等 bash 执行型专家使用_BASH_AGENT_SLOTSanalyst/contract_auditor/ad_operator在 bash 槽位集之上额外启用KG槽位而blue_cell有独立的最小槽位集。插件中间件通过slot属性声明自己挂靠的位置——示例中挂到SKILLS槽位MiddlewareSlot.SKILLS。值得注意的安全约束SAFETY_CRITICAL_SLOTS集合slots.py标记了ENGAGEMENT_CONTEXT、ROE_GUARDRAIL、UNTRUSTED_OUTPUT、PROMPT_INJECTION_SHIELD、HITL_APPROVAL等槽位为安全关键项。插件对这些槽位做替换是允许的前提是新实现遵守原契约但直接禁用会触发装配期异常除非设置环境变量DECEPTICON_ALLOW_SAFETY_OVERRIDES1——这一门禁由 decepticon/agents/build.py 中的_check_safety_gate强制实施防止误装插件静默瓦解安全护栏。示例项目解剖HelloMiddleware 的三处关键代码示例项目位于 packages/decepticon-sdk/examples/middleware是标准的 src-layout PyPI 包由脚手架命令decepticon-sdk plugin new生成命令本身定义于 decepticon_sdk/scaffold/cli.py对应的中间件代码模板在 decepticon_sdk/scaffold/templates.py。其源码只有一份文件 src/decepticon_example_middleware/init.py包含三处关键结构Custom middleware contributed to Decepticon. from __future__ import annotations from decepticon_sdk import MiddlewareProtocol, MiddlewareSlot class HelloMiddleware: Minimal MiddlewareProtocol-compliant middleware. name decepticon_example_middleware slot: MiddlewareSlot | str MiddlewareSlot.SKILLS priority 150 def wrap_model_call(self, state: object, runtime: object, config: object) - object: return state def get_middleware(role: str | None None, **_: object) - list[MiddlewareProtocol]: Plugin factory called by the frameworks middleware loader. del role return [HelloMiddleware()]逐段解读导入面Import surface只从decepticon_sdk导入不触碰任何带下划线前缀的框架内部模块。SDK 的init.py 重新导出decepticon-core的协议、契约与注册表这正是一个完整的插件只需要一条 import 语句的设计目标Phase 3 surface。__all__中列出的公开名称遵循 SemVer 稳定性承诺。中间件类HelloMiddleware声明slot MiddlewareSlot.SKILLS挂靠 skills 槽位与priority 150在标准 skills 中间件之后装配。wrap_model_call原样透传state是一个最小可用实现——真实中间件在此处对 state 做改写例如向系统消息追加策略、记录日志、改写模型请求。MiddlewareProtocol是runtime_checkable的因此isinstance(mw, MiddlewareProtocol)在运行时可以用于防御性校验。工厂函数get_middleware这是框架 loader 约定的可调用形状——接收role关键字可据此按角色裁剪贡献内容返回中间件实例列表。示例中忽略role并固定返回[HelloMiddleware()]。配套的 pyproject.toml 中注册入口是插件被发现的关键[project.entry-points.decepticon.middleware] decepticon_example_middleware decepticon_example_middleware这里decepticon.middleware是入口点组名右侧值指向模块decepticon_example_middleware模块级get_middleware工厂会被 loader 调用。其余构建元数据requires-python 3.13、依赖decepticon-sdk、构建后端hatchling、wheel 打包目标src/decepticon_example_middleware。仓库对示例结构有结构不变式测试保障tests/test_examples.py 参数化地对六类示例tool / middleware / agent / callback / skill / prompt断言三件事示例目录存在且含pyproject.toml、README.md、src/decepticon_example_kind/__init__.pypyproject.toml声明了与 kind 匹配的入口点组middleware 对应decepticon.middleware且入口点引用模块名decepticon_example_middleware生成的__init__.py在 Python 3.13 下可被 AST 解析语法可编译。构建与安装uv build 到 pip install按示例 README 的指引构建与安装分两步uv build pip install dist/*.whluv build使用 hatchling 构建出 wheel产出物位于dist/下pip install dist/*.whl将 wheel 装入当前 Python 环境。安装完成后wheel 的 metadata 会携带decepticon.middleware入口点声明此后任何 Decepticon Agent 工厂在构造时都会通过importlib.metadata.entry_points发现该贡献无需对框架做任何注册动作。也可以不先构建直接以可编辑方式安装pip install -e .入口点同样生效。适用前提示例与 SDK 均要求 Python3.13SDK 依赖decepticon-core协议与契约的载体与typer0.9.0脚手架 CLI 用。安装 SDK 本体使用pip install decepticon-sdk若需要测试辅助设施FakeBackend/FakeLLM/FakeSandbox与脚手架能力安装pip install decepticon-sdk[testing]若需要基于真实mock框架实例的 fixture则安装pip install decepticon-sdk[fixtures]该 extra 会拉入decepticon框架本体详见 packages/decepticon-sdk/README.md。框架端装配build_middleware 如何把插件放进 Agent 栈安装后插件中间件进入 Agent 栈的路径是build_middlewaredecepticon/agents/build.py其装配逻辑可以概括为四个阶段角色槽位解析slots未显式传入时按SLOTS_PER_ROLE.get(role)查表查不到且未显式传入则抛KeyError——插件自带的编排 Agent 使用自定义角色名时必须显式传slots框架拒绝静默构建空栈。覆盖解析与安全门禁_resolve_overrides合并显式overrides/disabled_slots与插件入口点返回的PluginBundle覆盖随后_check_safety_gate校验安全关键槽位前文所述。按枚举顺序装配标准槽位以DEFAULT_SLOT_FACTORIESdecepticon/agents/middleware_slots.py为基座factories.update(resolved.middleware_replace)浅合并插件替换然后遍历MiddlewareSlot枚举声明顺序跳过角色未启用或已禁用的槽位逐槽调用工厂统一签名f(*, backend, llm, role, fallback_models, sandbox, subagents)工厂返回None的槽位如无条件成立的MODEL_FALLBACK、KG 不可用时的KG被静默跳过。追加插件中间件result.extend(load_plugin_middleware(rolerole, backendbackend))build.py——非覆盖式additive插件中间件统一追加在标准槽位之后这是不替换任何标准槽位、只想尾巴上挂一个中间件的向后兼容逃生口。load_plugin_middleware最终落到decepticon_core.plugin_loader的_discover通用发现逻辑plugin_loader.py通过entry_points(groupdecepticon.middleware)枚举入口点逐个ep.load()加载失败的插件记录日志后跳过框架回退到 OSS 行为保证纯 OSS 环境与坏插件环境下框架不被拖垮对返回值做三种形状归一化可调用且不是运行时对象_looks_like_runtime_object通过invoke/before_agent/modify_request/after_agent等属性启发式判别→ 以obj(rolerole, **deps)调用工厂list/tuple→ 原样展平单个运行时实例 → 包装成单元素列表若返回PluginBundle包装则先经is_bundle_enabled(result.bundle)做 bundle 白名单过滤默认只启用standardDECEPTICON_PLUGINS环境变量或.decepticon.toml/pyproject.toml的[plugins].enabled可扩展*为通配再展平result.items。关于priority的语义示例 README 只标注了priority 150从 middleware.py 的约定看这是一个装配顺序提示数值小者优先——OSS 中间件用 100/200/…插件常用 50replace before或 150replace after。需要说明的是非覆盖式插件中间件在build_middleware中统一追加到标准槽位之后第 4 阶段因此priority的实际影响主要体现于插件之间的相对顺序及作为面向未来的契约字段。用 SDK 测试辅助设施编写免框架的 hermetic 测试示例 README 的测试部分是关键工程实践pip install decepticon-sdk[testing] pytest测试辅助设施位于 decepticon_sdk/testing/init.py提供三个内存级 fake各自满足decepticon_core.protocols对应的 Protocol因此被测代码可以安全地做isinstance(fake, BackendProtocol)之类的运行时检查而无需拉起真实框架FakeBackend以 Python dict 为后端的BackendProtocol实现。read(path, offset, limit)兼容 deepagents 的切片语义write/list/exists均无 IO。构造示例FakeBackend({/skills/recon/index.md: ...})。FakeLLM脚本化的LLMProtocol。按顺序逐次返回responses列表中的条目calls属性记录每次invoke()的输入便于断言响应耗尽后再调用会抛IndexError防止多调一次却静默成功的假阳性测试。FakeSandbox无操作SandboxProtocol。execute_command()被记录进self.commands并按构造时的responses队列返回 stdout队列耗尽后返回空串用于断言命令构造逻辑而不启动沙箱容器。一个典型的 hermetic 测试形态README 的指导用法展开from decepticon_sdk.testing import FakeBackend, FakeLLM, FakeSandbox from decepticon_example_middleware import HelloMiddleware def test_middleware_passthrough(): mw HelloMiddleware() state {messages: []} # wrap_model_call 的第二个参数是 runtime如 llm第三个是 config out mw.wrap_model_call(state, object(), object()) assert out is state # 透传语义针对更真实的中间件会读取 backend、调用 llm、执行沙箱命令可组合三者用FakeBackend预置技能文件、用FakeLLM(responses[...])固化模型输出、用FakeSandbox记录命令序列从而在完全脱离框架与容器的前提下验证插件的输入输出契约。这三个 fake 覆盖约 80% 的插件测试场景README 亦注明未来会补充make_test_engagement/make_test_opplan以支持更丰富的 engagement 级 fixture。从示例到生产替换/禁用/安全门禁与常见扩展方向示例是最小可运行真实插件往往需要与框架的PluginBundle机制配合plugin_loader.py。中间件相关的覆盖字段disabled_middleware按槽位名MiddlewareSlot的枚举值字符串跳过装配replaced_middleware槽位名 → 工厂可调用工厂签名与DEFAULT_SLOT_FACTORIES一致f(*, backend, llm, role, fallback_models, sandbox, subagents)返回中间件实例或Noneitems纯追加形态等同本文主线的入口点直返列表roles覆盖作用域过滤空元组 作用于所有触发加载的角色bundlebundle 白名单标签None 安装即加载。示例来自 plugin_loader.py 的文档示例禁用 OSS 的 prompt-caching 并用厂商版替代——PluginBundle( bundlevendor, disabled_middleware(prompt-caching,), items(VendorCacheMiddleware(),), )替换ask_user_question之类的工具、按角色重定向模型等其它能力同理。此外contracts/contributions.py 还提供聚焦的MiddlewareContributionitems/disabled_slots/replaced_slots/rolesroles为空元组时构造直接抛ValueError杜绝隐式全角色生效以及SafetyDeclaration插件只能新增安全关键项不能撤销 OSS 声明的安全项。扩展路径的常见选择对已有槽位做增强如企业审计策略注入EVENT_LOG前后优先考虑replaced_middleware或追加模式实现全新横切能力如自定义加密、流量改写可声明自定义 slot 字符串或直接追加无论如何务必遵守安全门禁——涉及SAFETY_CRITICAL_SLOTS的替换必须保证新实现遵守原契约例如替换ENGAGEMENT_CONTEXT的中间件仍须注入 RoE 范围约束否则不仅装配期会被拒更可能在运行时静默破坏安全叙事。小结从decepticon-sdk plugin new --kindmiddleware生成骨架、在__init__.py中实现MiddlewareProtocol与get_middleware工厂、在pyproject.toml的decepticon.middleware入口点组注册、uv build打包安装到框架build_middleware按枚举顺序装配并追加插件中间件——Decepticon 的中间件插件链路是一条无侵入、可回退、带安全门禁的完整闭环。配合decepticon-sdk[testing]的FakeBackend/FakeLLM/FakeSandbox插件作者可以在不启动框架、不拉起容器的前提下获得确定性的单元测试体验。本文相关的可继续深入阅读材料协议契约 decepticon_core/protocols/middleware.py、槽位与角色映射 decepticon_core/contracts/slots.py、发现机制 decepticon_core/plugin_loader.py、框架装配 decepticon/agents/build.py、默认槽位工厂 decepticon/agents/middleware_slots.py 以及 SDK 测试辅助设施 decepticon_sdk/testing/init.py。赞分享【免费下载链接】DecepticonAutonomous Hacking Agent for Red Team项目地址https://gitcode.com/gh_mirrors/de/Decepticon点击查看免费下载相关推荐Decepticon Prompt 插件开发指南从 decepticon-sdk plugin new 脚手架到 decepticon.prompts 入口点的完整实战Decepticon Prompt 插件开发指南从 decepticon sdk plugin new 脚手架到 decepticon.prompts 入口点Decepticon 插件开发完全指南基于 decepticon-sdk 构建工具、中间件与子智能体的权威实战手册Decepticon 插件开发完全指南基于 decepticon sdk 构建工具、中间件与子智能体的权威实战手册 导读 本文以 Decepticon 开源Decepticon Callback 插件开发实战基于 decepticon-sdk 构建、安装与测试可观测性回调插件Decepticon Callback 插件开发实战基于 decepticon sdk 构建、安装与测试可观测性回调插件 本文以 Decepticon 官方示上一篇TFLearn 深度学习库指南基于 TensorFlow 的高层 API 从安装、建模到训练可视化下一篇RPFM的DB表格编辑器深度评测像Excel一样编辑总战争兵种与科技数据表创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考