harryc295/branchbreak

# branchbreak [](https://github.com/harryc295/branchbreak/actions/workflows/ci.yml) [](LICENSE) [](CHANGELOG.md) 针对 LLM 和 AI agent 的持续自动化红队测试。branchbreak 运行一个 *自适应的攻击者模型* —— 它通过迭代细化 和树搜索来发现越狱攻击，根据 MITRE ATLAS 对每个发现进行评分，并使用 退出代码控制 CI/CD 流水线。这是一个已授权的安全评估工具：内置的目标 都是无害的、与拒绝边界相关的替身，并且它可以完全离线运行或针对真实 模型运行。 **[完整详解：PAIR 和 TAP 到底能为你带来什么](WRITEUP.md)** 大多数红队工具只是发射一*组固定*的提示词。针对现代模型的有趣 攻击并不是固定的 —— 它们是由能够 对目标的回答做出反应的攻击者发现的。branchbreak 在一个 CLI 之后实现了三种已发表的 算法：PAIR、TAP 和 Crescendo，并在其上增加了企业级 报告、扫描历史记录、告警以及 CI/CD 门禁。 ## 为什么需要自适应 单一的、未经细化的攻击（“单次攻击”）就是静态探针列表所能提供的。 它对哪怕只具备基本指令遵循能力的模型也会失效。一旦允许攻击者观察拒绝行为并进行 细化，同样的目标很快就会被攻破。从内置的离线扫描来看： | 策略 | 它是什么 | 攻击成功率 | |---|---|---| | 单次攻击 | 一个未经细化的提示词（固定探针） | 0/3 | | **PAIR** | 单个攻击者链，根据每次回复进行细化 | **3/3** | | **TAP** | 分支细化，剪枝无关内容，扩展最佳分支 | **3/3** | 这个差距就是支持自适应红队测试的全部理由，也是固定测试组工具 无法展示的能力。离线替身是确定性的，因此这张 表格展示的是*引擎的运行机制*，而不是真实模型的鲁棒性。完整 分析（包括针对真实模型的多轮运行）请见 [`results/findings.md`](results/findings.md)。 ## 算法 - **PAIR** —— *提示词自动迭代细化*（Chao 等人，2023， [arXiv:2310.08419](https://arxiv.org/abs/2310.08419)）。单个攻击者链： 提出攻击，观察目标的回复，细化，重复直到 目标被攻破或查询预算耗尽。 - **TAP** —— *带剪枝的攻击树*（Mehrotra 等人，2023， [arXiv:2312.02119](https://arxiv.org/abs/2312.02119)）。每个节点分支成多个 细化，在消耗目标查询*之前*使用评判模型剪枝无关的候选项， 扩展最佳分支，保留前 *w* 的前沿。分支 提高了成功率；剪枝保持了查询的高效性。 - **Crescendo** ——（Russinovich 等人，2024， [arXiv:2404.01833](https://arxiv.org/abs/2404.01833)）。真正的多轮交互： 与 PAIR/TAP 不同（它们每次尝试都会向目标发送全新的单次 交互），Crescendo 会保持一个真实且不断增长的对话，并在其中逐渐升级 —— 开头的几轮可以完全无害。这是一个 紧凑的实现；它不包含论文中遇到拒绝时回溯的步骤。 所有这三个算法都由一个**评判**模型引导，该模型会对回复进行 1–10 的评分，但 真实的成功与否是由**预言机**决定的，而不是评判模型。一个较弱或 可被操纵的评判模型最多只能错误地排列搜索顺序 —— 它无法伪造越狱。 测试套件明确断言了这一点。 **转换器**会在攻击提示词到达目标之前对其进行转换 —— base64、ROT13、leetspeak —— 与 PyRIT 的 Converter 类使用相同的基础机制， 用于测试混淆是否能绕过基于关键字的防护栏。在 profile 中设置 `"converters": ["base64"]`；攻击者自身的历史记录会保留 原始提示词，只有目标会看到转换后的传输格式。 ## 架构 ``` profile.json ──► scan orchestrator ──► reports (html / json / md) (config-as-code) │ │ │ SQLite history ──► trend / export ┌───────────────┼───────────────┐ │ ▼ ▼ ▼ MITRE ATLAS mapping attacker ─converters► target judge (adapts) (under test) (ranks + prunes) └──► PAIR / TAP / Crescendo / single-shot ──► oracle ──► findings ──► risk ──► CI gate ──► webhook alert provider: mock (offline) | ollama | openai-compatible | anthropic ``` 每个模块都是一个小型、可测试的单元。Provider 共享同一个 `complete(messages)` 接口，因此相同的扫描可以针对本地 Ollama 模型、任何 兼容 OpenAI 的 endpoint、Anthropic Messages API 运行，或者针对用于 CI 的确定性 mock —— 无需更改代码，只需更改 profile。 ## 安装 运行时仅使用标准库，没有 pip 依赖。未在 PyPI 上发布， 但它是一个真正的包 —— 如果你想要 `branchbreak` 控制台命令而不是 `python -m branchbreak.cli`，可以直接从 git 安装： ``` pip install git+https://github.com/harryc295/branchbreak branchbreak scan --profile profiles/default.json --out results ``` 或者直接克隆它并运行该模块： ``` git clone https://github.com/harryc295/branchbreak cd branchbreak python tests/test_branchbreak.py # 29 tests, offline ``` 对于开发：`pip install -e ".[dev]"` 会拉取 mypy、ruff 和 pytest — 这与 CI 运行的检查完全相同（`mypy branchbreak/`、`ruff check branchbreak/ tests/`）。 ## 运行扫描 离线运行，针对内置的 mock 目标（无需模型，无需密钥）： ``` python -m branchbreak.cli scan --profile profiles/default.json --out results # Crescendo vs PAIR/TAP, made concrete: this profile sets a boundary that a # single message can never reach, so PAIR/TAP hold no matter the budget — # only Crescendo breaks it, by turn 4, because it accumulates real pressure # across a growing conversation instead of starting fresh every attempt. python -m branchbreak.cli scan --profile profiles/crescendo.json --out results-crescendo ``` 针对真实模型运行： ``` # local, via Ollama's OpenAI-compatible endpoint python -m branchbreak.cli scan --provider ollama --model llama3.2:3b --fail-on high # Anthropic Messages API (reads ANTHROPIC_API_KEY) python -m branchbreak.cli scan --provider anthropic --model claude-sonnet-5 # any OpenAI-compatible gateway (reads OPENAI_BASE_URL / OPENAI_API_KEY) python -m branchbreak.cli scan --provider openai --model gpt-4o-mini ``` `--provider` 会将攻击者、目标和评判模型指向同一个后端（一个模型 对其自身进行红队测试）；在 profile 中拆分它们，以便使用强大的攻击者对抗 较弱的目标。当任何发现满足 `--fail-on` 时，该命令会以非零状态退出， 因此它可以直接放入流水线中 —— 请参见 [`examples/github-actions.yml`](examples/github-actions.yml)。 关于真实模型运行的注意事项：目标模型通常以 temperature 1.0 进行采样，因此结果是随机的。不要相信单次运行 —— 文章和 `results/findings.md` 报告的是少量多次试验的比率，而不是单个样本。 用于生产环境的另外两个 flag： ``` # cap total target queries across the whole scan — protects a paid API from # an unexpectedly expensive run (wide TAP branching over many objectives) python -m branchbreak.cli scan --max-queries 100 # run (objective, strategy) jobs concurrently instead of sequentially python -m branchbreak.cli scan --parallel 4 ``` `--max-queries` 和 `--parallel` 在实际效果上是互斥的：预算 跟踪只有在任务完成后才能知道其成本，因此如果不冒着超支的风险，它就无法遵守 并发任务的运行总量 —— `--max-queries` 会忽略 `--parallel` 以串行方式运行。 ## 运维操作 ``` # catch a broken profile.json before it fails mid-scan python -m branchbreak.cli validate --profile profiles/default.json # attack success rate over scan history — the "is our ASR rising release # over release" the README used to just promise is one query away python -m branchbreak.cli trend --db branchbreak.db # CSV export of every scan/run/finding for audit evidence (SOC 2 / ISO 27001) python -m branchbreak.cli export --db branchbreak.db --out evidence/ ``` 当扫描的门禁失败时，发送消息到 Slack（或任何兼容 Slack 的 webhook）： ``` python -m branchbreak.cli scan --webhook https://hooks.slack.com/services/... # or set BRANCHBREAK_WEBHOOK_URL instead of passing --webhook every time ``` ## 报告 每次扫描会生成三个制品： - `report.html` — 一个独立的仪表盘：风险评分、各策略的 ASR，以及 每一个发现及其成功的攻击提示词、目标的回复和 ATLAS 技术。 - `report.json` — 机器可读，用于流水线和趋势跟踪。 - `report.md` — 用于仓库或文章。 扫描历史会持久化到 SQLite —— 参见上文的 `trend` 和 `export`。 ## 安全与范围 这是一个用于**已授权的**安全评估工具，其构建方式与公开的研究 一致： - **默认使用无害的替身。** 内置的目标用于保护一个无害的 canary token；成功意味着该 token 被泄露。这衡量了自适应 攻击是否能在不产生有害内容的情况下突破指令边界。 - **与目标无关的引擎。** `taxonomy.py` 会将一个包含 用户提供目标的 JSON 文件加载为内置三种目标所使用的相同结构 —— 请参见 [`profiles/custom-objectives.example.json`](profiles/custom-objectives.example.json)。 若要在已授权的评估中针对真实的危害类别，请将其指向 来源于标准分类法（HarmBench、AdvBench、 JailbreakBench）的目标，并配合内容分类器 oracle。本仓库不提供 该内容 —— 加载器只是机制，请在已授权的评估中自带你的分类法文件 。无论哪种方式，搜索、评判、评分和报告 都保持不变。 - **发现结果映射到 MITRE ATLAS**，这是 AI 安全团队和采购方 已经在使用的框架。（技术链接指向 ATLAS 根站点，而不是 特定技术的深度链接 —— atlas.mitre.org 是一个位于 GitHub Pages 上的客户端渲染 SPA，没有用于直接导航的服务器端回退，因此 无论 URL 是什么，目前每个深度链接都会返回 404。） 请仅在你获得授权测试的系统上使用它。 ## 目录结构 ``` branchbreak/search.py PAIR, TAP, Crescendo, single-shot — the adaptive engine branchbreak/attacker.py attacker prompt construction, seeded with strategies branchbreak/converters.py base64 / rot13 / leetspeak prompt transforms branchbreak/judge.py response scoring + on-topic pruning signal branchbreak/objectives.py benign refusal-boundary surrogates + success oracle branchbreak/taxonomy.py loader for user-supplied objective sets (JSON) branchbreak/providers.py mock / ollama / openai-compatible / anthropic (retry + backoff) branchbreak/atlas.py MITRE ATLAS catalog + mapping branchbreak/validate.py profile.json schema validation branchbreak/alert.py Slack-compatible webhook alerting on a failed gate branchbreak/scoring.py findings, risk score, CI gate branchbreak/store.py SQLite scan history, trend queries, CSV export branchbreak/report.py html / json / markdown reports branchbreak/scan.py orchestration — query budget cap, parallel execution branchbreak/cli.py command line: scan, validate, trend, export profiles/ scan profiles (config-as-code) results/findings.md research writeup + how to reproduce on real models tests/ correctness tests for search, judge, scoring, atlas ``` ## 开源许可 MIT — 请参见 [LICENSE](LICENSE)。

标签：AI安全, AI风险缓解, Chat Copilot, DLL 劫持, Petitpotam, 反取证, 大语言模型, 安全评估, 自动化红队, 逆向工具