Decepticon作为pip库使用指南：用SDK快速构建你自己的自主渗透测试编排器-平芜编程栈

Decepticon作为pip库使用指南：用SDK快速构建你自己的自主渗透测试编排器

【免费下载链接】DecepticonAutonomous Hacking Agent for Red Team项目地址: https://gitcode.com/gh_mirrors/de/Decepticon

Decepticon 是一个开源的自主渗透测试 AI 框架（Autonomous Hacking Agent for Red Team），如今你只需一条pip install命令，就能把它作为 Python 库引入自己的项目——通过官方 SDK 与插件体系，几行代码即可搭建出属于你自己的自主渗透测试编排器，无需 fork 整个仓库。

为什么选择 pip 库方式？

过去使用 Decepticon 只能通过 Docker 全家桶部署。而 pip 库方式带来三个直接好处：

方式	适用人群	特点
`pip install decepticon`	库消费者 / 产品集成方	版本可控、CI 友好、无需 Docker
`pip install decepticon-sdk`	插件作者	只依赖契约层，带脚手架 CLI 与测试假件
Docker 全家桶	终端用户	开箱即用的沙箱 + LiteLLM + Neo4j

官方将公开 API 定位为 SemVer 稳定面（v1.1.2 起），这意味着你的集成代码可以在主版本内安心升级。详见 docs/library-usage.md。

⚠️ 安全提示：渗透测试工具请仅用于已获得书面授权的目标。Decepticon 内置 RoE（作战范围规则）中间件与安全闸门，替换安全关键组件需要显式开启DECEPTICON_ALLOW_SAFETY_OVERRIDES=1才能绕过。

三种使用路径：从开箱到全自定义

Decepticon 构建在 langchain / langgraph 之上，采用"中间件 + 工具 + 提示词"的组合范式。官方文档提供了三条递进路径（见 docs/library-usage.md）：

路径 1：直接使用预置 Agent 工厂。内置 16 个角色工厂（recon、exploit、analyst 等），零参数即可创建：

from decepticon.agents.standard.recon import create_recon_agent agent = create_recon_agent() # 默认 OSS 配置，依赖自动解析

路径 2：工厂 + 显式覆盖。所有工厂都接受 langchain 风格的 kwargs，可以整体替换工具列表、中间件栈、系统提示词，或注入自定义模型与沙箱后端：

agent = create_recon_agent( tools=[my_custom_tool, ...], # 完整替换默认工具 system_prompt="...", # 完整替换提示词 llm=custom_llm, # 指定你自己的模型 recursion_limit=500, # 调参 )

路径 3：直接组合 langchain 的create_agent。完全绕过 Decepticon 工厂，直接导入它的中间件、工具与后端构建块，自行拼装——这是商业化集成的标准做法。

用 decepticon-sdk 构建你自己的插件

如果你的目标是"构建自己的自主渗透测试编排器"，SDK 是最快的起点。它只重导出契约层（decepticon-core），并自带脚手架 CLI 与测试假件。

第一步：安装 SDK

pip install "decepticon-sdk[testing]" # 附带 FakeBackend / FakeLLM / FakeSandbox

第二步：脚手架生成插件。SDK 支持六种插件类型：tool、middleware、agent、callback、skill、prompt，一条命令即可生成可发布的包：

decepticon-sdk plugin new \ --kind=middleware \ --name=my-plugin \ --path=./my-plugin

第三步：实现协议、注册入口点。例如一个审计日志中间件只需实现MiddlewareProtocol并在pyproject.toml中声明[project.entry-points."decepticon.middleware"]，框架会在用户安装 wheel 后自动发现——无需任何注册调用。

完整的六类示例插件都随仓库提供，建议对照学习：

示例目录：packages/decepticon-sdk/examples/
工具插件示例：packages/decepticon-sdk/examples/tool/pyproject.toml
SDK 说明：packages/decepticon-sdk/README.md

第四步：用内存假件做单元测试。decepticon_sdk.testing提供满足各协议的内存假件，插件测试无需真实沙箱或 LiteLLM 代理即可运行，保证测试快速、可重复。

注册自定义角色与编排器

想发布一个全新的编排器 Agent 类型（不在内置 16 个角色之列）？两个关键工具：

RoleRegistry.register()：向框架目录注册新角色（如apt），声明它的中间件槽位集合与技能源路径。LLM 工厂和中间件装配器会视它为一等公民，调用是幂等的，可安全地放在每个 worker 的启动钩子里。
build_middleware(slots=...)：为自定义角色显式声明槽位集合，即可复用 Decepticon 的槽位系统、安全闸门与插件覆盖管线。注意：不传slots时，未知角色会直接抛KeyError——这是有意为之，避免静默的空栈掩盖插件 bug。

企业级多租户场景还可以用make_agent_backend(extra_routes=)为每个租户挂载独立资产树（最长前缀优先匹配），实现技能与凭据的租户隔离。完整模式参见 docs/library-consumer-guide.md。

安全闸门：插件体系的安全底线

Decepticon 的插件加载基于 entry-point 发现（decepticon.tools、decepticon.middleware、decepticon.subagents等分组），并有一道防"意外失守"的闸门：

替换/禁用安全关键槽位（如engagement-context、sandbox-notification）或工具（如ask_user_question）会在构建 Agent 时抛出SafetyOverrideViolation；
插件作者可以追加声明自己的安全关键项（SafetyDeclaration），但永远不能移除 OSS 已有的安全保护；
生产环境可设置DECEPTICON_STRICT_REGISTRY=1，让插件冲突在启动时即报错。

插件作者全流程（含打包发布到 PyPI）可参考 docs/plugin-author-guide.md，架构契约定义在 packages/decepticon-core/。

快速上手清单

步骤	命令 / 操作	说明
1	`pip install decepticon`	安装框架（可选 extras：`[neo4j]`、`[telemetry]`、`[mcp]`）
2	`create_recon_agent()`	用预置工厂跑通第一个 Agent
3	`pip install decepticon-sdk`	安装 SDK 与脚手架
4	`decepticon-sdk plugin new`	生成你的插件包
5	实现 Protocol + entry-points	接入工具 / 中间件 / 子 Agent
6	`DECEPTICON_PLUGINS=standard,my-plugin`	显式激活你的插件包