SamsonCyber/garbleworks

    **成熟度：** 已实现 · 独立验证 · 积极维护。详见 [STATUS.md](STATUS.md)。 **复现（无需模型）：** `bash scripts/repro.sh` 或 `powershell -File scripts/repro.ps1`（预期输出 `REPRO_OK`）。 ## 该工具是什么 大多数 jailbreak 工具提供的是固定的 payload 列表。Garbleworks 是一个基于可组合攻击 DSL 的**搜索与测量引擎**。 你需要提供： 1. 一个**目标**（你希望模型在受控测试中执行或泄露的内容）。 2. 一个**靶标**（本地 Ollama、兼容 OpenAI 的 endpoint、Anthropic 风格适配器，或本地可调用对象）。 3. 可选的**检测器**和**预算**。 然后它会： 1. 将候选攻击**组合**为*配方*（参数化操作的有序链）。 2. 在 SSRF 和授权范围的限制下**触发**它们。 3. 使用多信号检测器和可选的 AttackEval LLM 评判器对响应进行**评分**。 4. **搜索**组合空间（遗传算法 EVOLVE、MAP-Elites、Thompson bandit、多轮树搜索）。 5. 使用 Wilson / 完整案例置信区间**报告**攻击成功率，而不是单次侥幸命中。 6. 通过现场指南将发现**交叉映射**到 OWASP LLM Top 10、MITRE ATLAS、NIST 和 CWE，并可将配方导出为 promptfoo / garak / PyRIT 的格式。 核心单元是一个**配方**：一组有序的字符串转换。 ``` synonym:limit=3 homoglyph:coverage=0.5 zero_width:every=2 tag_wrap ``` 该链会在词汇上改写、替换易混淆的字符、注入不可见字符，然后包装结构。四个原语，组合成一个候选方案。该套件搜索的是各种组合，而不是对静态列表进行采样。 ## 测试运行的工作原理 ``` objective + target │ â–¼ compose recipe ──► apply_recipe ──► variants â–² │ │ â–¼ search loop fire (scoped) EVOLVE / MAP-Elites / │ Thompson bandit / tree search â–¼ │ target adapter │ │ │ â–¼ │ detectors + judge │ │ └──────────── history / bandit ◄───────┘ │ â–¼ report + export + field-guide crosswalk ``` | 阶段 | 发生的操作 | 代码位置 | |-------|----------------|---------------| | 组合 | 构建有序操作链（UI、MCP 或优化器） | `core.run_recipe`, `ops/*` | | 应用 | 将一个输入扩展为多个变体（应用扇出上限） | `core.py`, `app.py` | | 触发 | 通过 POST/GET 将变体发送到目标 URL 或本地可调用对象 | `fire.py`, `targets.py` | | 检测 | 多信号命中规则（contains、regex、secret_regex、refusal_bank、llm_judge 等） | `detectors.py` | | 搜索 | 偏好有效的配方；淘汰无效配方 | `evolve.py`, `optimizer.py`, `rainbow.py`, `bandit.py`, `treesearch.py` | | 测量 | Wilson / Bernstein 边界，验证重复触发 (N×)，可选 McNemar A/B | `validate_refire.py`, `benchmark_harness.py` | | 映射 | 技术标题 → 框架 + 可执行操作 | 现场指南 JSON + MCP `field_guide_*` | | 导出 | 配方 → promptfoo YAML / garak 探针 / PyRIT 编排器格式 | `exporters.py` | ## 配方 DSL（深度） 配方是一系列步骤。每个步骤都是一个操作名称加上一个参数映射表。 ``` [ {"op": "synonym", "params": {"limit": 3}}, {"op": "homoglyph", "params": {"coverage": 0.5}}, {"op": "zero_width", "params": {"every": 2}}, {"op": "tag_wrap", "params": {}} ] ``` - 除非另有说明（sampler / llm 系列），操作对字符串是**确定且纯粹的**。 - 每个操作都有一个战术**家族**，供多样性感知选择器使用（Thompson 卡组不会意外地叠加五个仅编码的分支）。 - 通过在 `backend/ops/` 下添加模块并从 `backend/ops/__init__.py` 导入它来注册新操作。 - 保存的配方位于 `backend/recipes/`。卡组（输入集）位于 `backend/decks/`。 ### 操作家族（138 个操作） | 家族 | 数量 | 作用 | |--------|------:|------| | encoding | 27 | base64/32/58/85, hex, 摩斯密码, 盲文, 经典密码, jwt 风格分割 | | character | 23 | 易混淆字符, 不可见字符 (ZWSP/ZWNJ/BiDi/VS), leet, 全角, zalgo | | template | 18 | chat-template 角色, persona/DAN, 分隔符碰撞, JSON 注入, few-shot | | jailbreak | 18 | deep-inception, cipher-persona, code-chameleon, bad-likert, policy-puppetry | | structure | 14 | tag/markdown/json/yaml/latex 包装, function-call 帧, split-join | | prose | 10 | 同义词 (WordNet), 回译, 翻译, 改写, 注入拼写错误 | | sampler | 9 | sample_n, distinct_n, diverse_k, mmr-select, seed_sweep | | stego | 6 | emoji-二进制, 变体选择器通道, 空白字符隐写 | | language | 5 | 多语言中枢, 往返, 音译, 伪语言环境 | | carrier | 5 | 间接注入载体（电子邮件、编辑器备注、memory-seed 等） | | llm | 3 | llm-reframe, llm-generate, complexify（本地模型；离线时直通） | 完整的技术覆盖范围和 StegOFF 文本方法对等情况：[`COVERAGE.md`](COVERAGE.md)。 ## 触发路径与范围 所有服务器端出站 HTTP 共享**同一个**策略模块：`backend/fire.py`。 1. **URL 策略** (`validate_target_url`) - scheme 必须是 `http` 或 `https`。 - 链路本地 / 云元数据 (`169.254.0.0/16`)、多播、保留和未指定地址均被阻止。 - 回环地址和 RFC-1918 地址默认保持允许，以便本地和局域网模型服务器正常工作。 - 设置 `GARBLEWORKS_BLOCK_PRIVATE=1` 也可阻止回环和私有地址范围。 2. **禁止重定向。** 经过验证后，302 无法转向被阻止的内部主机。 3. **执行回执 (MCP)。** 触发工具还要求主机与 `authorized_scope` 匹配。默认范围是 `local-selftest`（`127.0.0.1`、`localhost`）。范围外的主机将收到 `SCOPE DENIED`。 4. **上限。** 请求体有上限（4 MB）。扇出有界限（`max_variants ≤ 2000`，卡组输入 `≤ 1000`）。 HTTP API **没有身份验证**。仅绑定到 `127.0.0.1`。CORS 仅允许 localhost 源。详见：[`SECURITY.md`](SECURITY.md)。 ### 靶标 `targets.py` 中的适配器（以及本地可调用对象）包括： | 适配器 | 用途 | |---------|-----| | `raw` | 具有 `{payload}` body 模板和 JSON `response_path` 的任意 HTTP 请求 | | Anthropic / Gemini 风格助手 | 当你指向允许的 endpoint 时提供提供商的消息格式 | | 本地可调用对象 | 用于在没有网络的情况下进行干运行的进程内 Python 靶标 | 本地 Ollama 靶标的示例（同样位于 `backend/TARGET-abliterated-qwen.json`，仅限回环地址）： ``` { "adapter": "raw", "url": "http://127.0.0.1:11434/v1/chat/completions", "method": "POST", "headers": {"Content-Type": "application/json"}, "opts": { "body": "{\"model\":\"your-model\",\"messages\":[{\"role\":\"user\",\"content\":\"{payload}\"}],\"stream\":false}", "body_type": "json", "response_path": "choices.0.message.content" } } ``` ## 检测器与测量 触发请求接受一个检测器列表和一个组合模式（`all` / `any` / `score`）。 内置类型包括： | 类型 | 含义 | |------|---------| | `contains` / `not_contains` | 存在或不存在子字符串 | | `regex` / `not_regex` | 模式匹配 | | `status_eq` / `status_in` | HTTP 状态码 | | `secret_regex` | 响应中的常见机密格式（API key、token、PEM、JWT 等） | | `refusal_bank` | 模型拒绝短语（正向 = 已拒绝） | | `llm_judge` | AttackEval 评分 0 / 0.33 / 0.66 / 1.0 | | `min_length` | 代码片段的最小长度限制 | | `decomposition` | 蓝队 Pack Hunt 脚手架检测器 | **验证重复触发** (`validate_refire`)：将获胜的 payload 重复触发 N 次并报告 Wilson ASR。单次侥幸命中不能作为定论。 **搜索 + 统计栈：** | 机制 | 作用 | |-----------|-----| | EVOLVE | 概率单纯形上的遗传搜索（Aitchison 几何）。规格：[`EVOLVE_MATH.md`](EVOLVE_MATH.md) | | MAP-Elites (`rainbow.py`) | 在行为 × 混淆网格上的质量多样性 | | Thompson bandit | 每对（操作/配方，靶标）的 Beta 后验；`probation → active → retired` 生命周期 | | 树搜索 (`treesearch.py`) | 用于弥补单轮 DSL 遗漏的降级路径的多轮束搜索 | | 寄存器 `L(x)` (`register.py`) | 词汇负载模型；估计哪些特征与拒绝相关 | 与 h4rm3l / WildTeaming 相比的真实定位及已知差距：[`HARNESS-POSITIONING.md`](HARNESS-POSITIONING.md)，[`docs/GAPS.md`](docs/GAPS.md)。 ## 接口 ### 1. HTTP API + Web UI ``` powershell -ExecutionPolicy Bypass -File run.ps1 # http://127.0.0.1:9877 ``` 为操作、配方、触发、历史记录、卡组和导出提供单页 UI 和 REST endpoint。完整的 endpoint 映射：[`docs/USAGE-AND-API.md`](docs/USAGE-AND-API.md)。 ### 2. 操作员 TUI (OpenTUI / Bun) ``` cd tui bun install bun start ``` 标签页：Attack、Validate、Sessions、Bench、Help。仅桥接到 Python 后端（无第二触发路径）。快捷键：`1`-`5` 标签页，`Ctrl+R` 运行，`Ctrl+C` 退出。详见 [`tui/README.md`](tui/README.md)。 ### 3. MCP server (agent 操作员) ``` pip install "mcp>=1.2,<2" python backend/mcp_server.py ``` 将 [`.mcp.json.example`](.mcp.json.example) 复制到你的 MCP 客户端，并将 `cwd` 设置为仓库根目录。 **可执行工具（代表性）：** | 工具 | 用途 | |------|---------| | `generate_framings` | 目标 → 为每个命名技术生成一个框架化的 payload | | `apply_recipe` | 运行有序操作链 | | `list_techniques` | 操作目录（名称、类别、描述、参数） | | `chat_template_inject` | 将 payload 包装在 chat-template 特殊 token 中 | | `prefill_attack` | 多轮助手预填充 / 响应启动 | | `pack_hunt` / `pack_hunt_decompose` / `pack_hunt_detect` | 分解攻击 + 蓝队检测 | | `optimize` | 针对范围限定的实时靶标进行遗传演化 | | `validate_refire` | N× 重复触发 + Wilson ASR | | `auto_attack` | 多策略阶梯（baseline → pack_hunt → optimize → prefill） | | `start_run` / arena 助手 | 闭环操作员会话 | **现场指南工具：** | 工具 | 用途 | |------|---------| | `field_guide_search` | 技术全文搜索 | | `field_guide_get` | 完整的技术说明 | | `field_guide_crosswalk` | 框架 ID + 工具钩子 + 操作 | | `field_guide_ops` | 将技术目录转换为可执行操作 | | `op_technique` | 反向转换：操作 → 技术 | | `field_guide_by_framework` / `field_guide_by_tool` | 按 OWASP/ATLAS/CWE 或 garak/promptfoo/PyRIT 索引 | 目录数据内置于 `backend/data/field-guide.json`（来自 [llm-injection-field-guide](https://github.com/SamsonCyber/llm-injection-field-guide)）。概览：[`docs/FIELD-GUIDE.md`](docs/FIELD-GUIDE.md)。 ## 端到端：首次安全运行 1. **安装后端**（Python 3.11+）： ``` git clone https://github.com/SamsonCyber/garbleworks.git cd garbleworks cd backend python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt ``` 2. **启动 echo 靶标**（无需真实模型）：

标签：AI安全, Chat Copilot, DLL 劫持, LLM红队, Python, Python脚本, 大语言模型, 无后门, 逆向工具