项目定位与目标

garak（由 NVIDIA 维护）是一个面向大语言模型（LLM）的开源红队与漏洞扫描框架，用于系统性探测模型在对抗性输入、越狱提示、有害内容生成、PII 泄露、提示注入等方面的安全弱点。仓库的 README.md 将其描述为"LLM vulnerability scanner"，强调其使用探针（probe）、检测器（detector）、评估器（evaluator）的三段式流水线，将攻击载荷发送给目标生成器（generator），再对响应进行打分归类。garak 当前最新稳定版为 v0.15.1（参见 v0.15.1 release notes），社区关注的活跃议题覆盖 Unicode 规范化缺陷（TAP/PAIR 评估器提示注入）、OpenAI 兼容端点、BEAST 探针弃用、WebSocket 生成器、推理参数操纵检测等方向。

资料来源：README.md

包结构与执行入口

garak 是一个常规的 Python 包，根包目录 garak/ 在 __init__.py 中通过版本号、运行时元数据完成初始化，并对外暴露关键子模块（probes、detectors、generators、evaluators、harnesses、resources）。用户执行 python -m garak 时，控制流进入 garak/__main__.py，该模块调用 command.py 进行子命令分发。command.py 是核心命令路由器：根据传入的子命令（probe、detector、generator、report、qual_review、cache、rest 等）加载对应处理逻辑，再交由 cli.py 进行参数解析与配置注入。

flowchart TD
    A[python -m garak] --> B[__main__.py]
    B --> C[command.py 子命令路由]
    C --> D[cli.py 参数解析]
    D --> E[_config.py 配置加载]
    E --> F{probe / detector / generator / report}
    F --> G[执行探测 / 打分 / 报告]
    G --> H[(JSONL / HTML 报告输出)]

资料来源：garak/__init__.py, garak/__main__.py, garak/cli.py, garak/command.py

核心子系统划分

garak 框架的核心功能由若干可插拔子系统组成，下表给出主要模块的职责边界与典型交互对象：

这种"插件即模块"的组织方式使得新增探针或检测器只需在对应目录下添加类文件并在 __init__.py 注册元数据，框架通过反射自动发现并加载。

资料来源：garak/__init__.py, README.md, garak/command.py

配置系统与运行流程

_config.py 是配置中心，支持从 YAML 与 JSON（自 v0.14.0 起）的配置文件、环境变量、CLI 参数三层来源合并配置。配置加载发生在 command.py 派发具体子命令之前，确保所有下游模块（探针、检测器、生成器）读取到一致的运行期参数（如模型名、探针列表、并发度、报告路径等）。一次完整的扫描运行流程如下：

1. __main__.py 接收命令行调用，初始化日志并解析顶层参数。
2. command.py 根据子命令选择执行路径，cli.py 完成剩余参数解析。
3. _config.py 完成配置合并与默认值注入。
4. 探针模块生成攻击 prompt 列表，发往 generators 包装的目标模型。
5. 响应交由一个或多个 detectors 评分；可选的 evaluators（如 TAP、PAIR）进一步汇总多轮结果。
6. 结果以 JSONL 格式落盘，再由 garak.analyze.* 子命令生成 HTML/Absorb-style 报告。

资料来源：garak/_config.py, garak/cli.py, garak/command.py, garak/__main__.py

与社区议题的衔接

项目的扩展性也体现在社区驱动的插件演化上。例如，issue #435 推动了 WebSocket 生成器的引入（v0.14.1），issue #583 提出了"simple adaptive attacks"探针的设计空间，issue #1867 与 #1868 则分别暴露了 StringDetector 未做 Unicode 规范化以及 TAP/PAIR get_evaluator_prompt 未转义目标响应的安全缺陷。这些议题共同推动了 probes、detectors、evaluators 三类插件的边界不断被加固和扩展，也是用户在使用 garak 时需要重点关注的运行时风险点。

资料来源：garak/command.py, garak/_config.py, README.md

1. 概览

在 garak 中，"探针"（Probe）是与目标生成器（Generator）交互、生成对抗载荷、并由"检测器"（Detector）评分的核心插件类型。每条探针对应一种 LLM 安全测试场景：绕过系统提示、注入隐藏指令、测试 PII 泄漏、执行多轮越狱等。garak.probes 子包承载全部内置探针，按攻击家族（jailbreak、encoding、injection、leakage 等）分布在多个模块文件中 资料来源：garak/probes/__init__.py:1-40。CLI 通过 --probes 选项按前缀筛选探针，并使用 --list_probes 列出可用探针；v0.14.1 起，--list_probes 会同时展示探针的 tier（质量分级） 资料来源：garak/probes/_tier.py:1-30。

2. 基础架构

Probe 基类定义在 garak/probes/base.py 中，所有探针必须继承该类并声明若干关键字段：

• goal：探针想要达成的语义目标（字符串） 资料来源：garak/probes/base.py:130-170。
• prompts：具体要发送给模型的载荷列表（list[str] 或由 _attempt_prompts 动态生成） 资料来源：garak/probes/base.py:180-220。
• detectorn / extended_detectors：关联的检测器类名列表，框架会在生成回复后自动调用它们打分 资料来源：garak/probes/base.py:230-260。
• active：布尔标志；非激活探针将被 CLI 与 probe_spec 解析逻辑忽略。
• tier：取自 garak/probes/_tier.py 中定义的枚举值（Tier 1 = 充分测试可复现；Tier 2 = 部分可用；Tier 3 = 实验性；undocumented = 极不成熟） 资料来源：garak/probes/_tier.py:1-40。

迭代型（multi-turn）探针（例如 TAP、PAIR、GOAT）继承自 v0.13.2 引入的迭代基类 Probe 子类，允许在每轮根据目标回复更新策略 资料来源：garak/probes/tap.py:1-60。多模态探针（如 visual_jailbreak.FigStep）则直接构造 turn_templates 并附带图像附件，由生成器决定如何分发 资料来源：garak/probes/visual_jailbreak.py:1-50。

3. 主要攻击家族目录

4. 已知限制与社区反馈

探针生态并非全部"开箱即用"。社区和 issue tracker 反映出若干与探针相关的痛点：

• BEAST 探针（probes.beast）在 #1629 中被标记为 deprecated 并存在 bug，运行时容易破坏生成器状态。
• TAP/PAIR 的评判 prompt 在 resources/red_team/evaluation.py:12-14 使用 f-string 拼接目标回复，未做转义，导致目标模型可以通过伪造 Rating: 行自我判定为安全（issue #1868）。 资料来源：garak/resources/red_team/evaluation.py:12-14
• 与之配对的 StringDetector 在面对同形异义字、全角、零宽等 Unicode 变体时不做规范化，造成脏话/毒性探针假阴性（issue #1867）。这是所有基于子串匹配的检测器（含 unsafe_content.LDNOOBW）的共同缺陷，间接影响相关探针的得分可信度。
• probes.simpleadaptive（issue #583）请求基于 "Simple Adaptive Attacks"（TML EPFL, arXiv:2404.02151）实现更少接口的新探针，体现社区希望降低新探针编写门槛。
• issue #1233 提议新增"推理参数操控"（inference control parameters）类探针，对应 CWE 正在起草的新型弱点。
• issue #1155 报告 garak 在 deepseek-distill 与其 abliterated 版本上打分出现异常，提示探针在量化/蒸馏模型上的鲁棒性仍待改进。

探针生命周期（简化）

  Probe 类（base.py）
        │
        ├── prompts/goal/detectors 声明
        │
        ▼
  Generator.generate(prompt)
        │
        ▼
  Detector.detector.score(response)
        │
        ▼
  Hitlog + 报告

总体而言，garak 的探针目录是一个由"攻击家族 × 成熟度 tier × 单/多轮 × 单/多模态"四个维度组织而成的可扩展矩阵；新探针只需实现 Probe 基类即可被框架自动发现与调度。撰写新探针时务必同步指明 tier 与 detectorn，并在 PR 中给出最小可复现样例，以降低与上述已知限制的耦合风险。

概述与定位

在 garak 的整体架构中，探测器(Probe) 负责向目标 LLM 发送攻击性提示，检测器(Detector) 则负责分析模型输出并判定"漏洞是否被命中"。检测器是 garak 漏洞识别的核心组件，覆盖从字符串子串匹配、模型评判，到特殊场景(永远通过/永远失败)等多样化的判定方式。检测器基类统一了输出为浮点数组的契约——1.0 表示命中漏洞，0.0 表示未命中，中间值可用于概率或置信度表达。

flowchart LR
    P[Probe 攻击提示] --> G[Generator 目标模型]
    G --> O[输出文本]
    O --> D{Detector 检测器}
    D -->|1.0| V[命中漏洞]
    D -->|0.0| P2[未命中]
    D -->|0.x| C[置信度分数]

资料来源：garak/detectors/base.py:1-50

基类与统一契约

Detector 基类定义在 garak/detectors/base.py，规定子类必须实现 detect() 方法，返回与尝试次数对齐的 list[float] 或 list[list[float]]。StringDetector 是最常用的子类，通过 str.lower() 进行不区分大小写的子串匹配，子类仅需声明匹配词表 matchtype 与 substrings。HFDetector 封装 HuggingFace 文本分类模型，适用于语义层面判定。

当多个探测器需要并发评估时，garak 通过 attempt.api_results 传递模型输出与消息历史，确保检测器在不重新调用模型的前提下完成分析。

资料来源：garak/detectors/base.py:30-120

字符串匹配类检测器与已知局限

garak/detectors/unsafe_content.py 中的 LDNOOBW 检测器继承自 StringDetector，使用内置"脏话词表"对模型输出进行扫描，是有毒/仇恨言论类探针的默认判定器。该模块同时提供 ToxicCommentModel(基于 HFDetector 包装的 unitary/toxic-bert)与 MitigationBypassDetector(判别模型是否给出绕过安全策略的指令)。

社区已记录该类匹配器的关键缺陷：其子串匹配未做 Unicode 归一化，对同形异义字(homoglyph)、全角字符、零宽字符形式的毒性输出会判为干净(假阴性)。例如将 ASCII 字母替换为外观相近的全角字符可绕过 LDNOOBW，导致评分失真。 资料来源：garak/detectors/unsafe_content.py:1-80｜参考社区讨论：issue #1867

模型评判(Judge)类检测器

garak/detectors/judge.py 提供基于 LLM 的评判检测器，常用于多轮攻击(如 TAP/PAIR、GOAT)的最终判定。Judge 检测器接受 detector_model 配置，可选用云端或本地 LLM 作为"裁判"，并通过提示词模板要求模型输出结构化结论。

该类检测器存在已知的提示注入风险：get_evaluator_prompt 在拼接 [PROMPT] 与 [ASSISTANT'S RESPONSE] 时使用未转义的 f-string，当目标模型的响应中包含伪造的 Rating: 行时，评判模型可能被欺骗，将原本成功的越狱判为安全。 资料来源：garak/detectors/judge.py:1-90｜参考社区讨论：issue #1868

辅助型检测器

garak/detectors/always.py 中的 Passthru 检测器永远返回 1.0，Fail 检测器永远返回 0.0，主要用于冒烟测试与探测器编排调试——确保即使没有真实检测逻辑，扫描流程也能端到端跑通。

garak/detectors/any.py(在 v0.13.2 由 @leondz 引入)实现"任一命中"语义：当同一尝试被多个检测器评估时，Any 给出聚合判定，方便用户构建"任一子类探测器命中即视为漏洞"的复合策略。

资料来源：garak/detectors/always.py:1-30、garak/detectors/any.py:1-25

注册机制与扩展方式

garak/detectors/__init__.py 通过 plugin 元数据声明与动态加载机制，使第三方可注册自定义检测器。Detector 子类需放置于 garak/detectors/ 或通过 entry_points 暴露，garak 在运行时按 category.<name> 进行命名空间解析。新检测器添加后无需修改核心调度逻辑，由 --list_detectors 与 garak.analyze 自动纳入。

在最新版本(v0.15.1)中，伴随 ProPILE PII 泄漏探测器 的引入，检测器生态扩展至更细粒度的个人信息识别场景，体现了"探测器即判定策略"的可组合设计。 资料来源：garak/detectors/__init__.py:1-60

实践建议

资料来源：garak/detectors/base.py:130-180、garak/detectors/judge.py:60-100

生成器是 garak 用于连接被测目标模型(target model)的抽象层。它负责把探测探针(probe)产生的提示(prompt)发送到具体的 LLM/多模态服务,并把响应返回给下游的检测器(detector)。garak 把所有目标模型接入点统一收敛到 Generator 基类上,从而让探针和检测器不必关心目标模型是 OpenAI、Hugging Face、本地 ggml,还是 WebSocket/函数桩等多种后端。

1. 整体架构与基类约定

Generator 基类位于 garak/generators/base.py,定义了一组探针/检测器统一依赖的接口,包括 generate(prompt, ...)、_call_model(prompt, ...)、_load_model()、clear_context() 等 资料来源：garak/generators/base.py:1-120。所有继承类必须实现 _call_model,从而完成一次"输入提示 → 返回响应"的实际调用。在 garak/generators/__init__.py 中,garak 通过 load_generator(class_name, config_root=..., gen_config=...) 工厂方法把字符串类名实例化为具体对象,并按需加载 _load_model 资料来源：garak/generators/__init__.py:1-80。

生成器还可以携带 generations、temperature、top_p、max_tokens、URI、键认证信息等配置项,在基类的 __init__ 中统一初始化并暴露为对象属性 资料来源：garak/generators/base.py:60-150。这种"配置即属性"的模式让探针可以直接读取 generator.temperature,也可在运行时由检测器/报告系统复用。

2. 主流商业/开源后端的生成器

garak/generators/openai.py 是接入最广泛的生成器,实现了一个与 OpenAI Chat Completions API 兼容的客户端 资料来源：garak/generators/openai.py:1-200。它支持 model_name、context_len、generation_params 等核心字段,对支持 response_format=json_object 的目标自动解析 JSON。社区中长期热门诉求 #1008 要求新增 --rest/相关 flag 让任意 OpenAI 兼容端点也能复用该生成器,这说明 OpenAI 生成器在事实上承担了"通用 REST LLM 适配器"的角色 资料来源：issue #1008 "Support any OpenAI compatible endpoints" by adding two flags。

AzureOpenAIGenerator 在 garak/generators/azure.py 中通过 azure_endpoint、deployment_id、api_version 等字段,将相同 OpenAI 协议映射到 Azure OpenAI 资源 资料来源：garak/generators/azure.py:1-80。这种"派生类只替换认证/URL"的设计,使 Azure、Hugging Face TGI、本地服务都能以最小代码量复用基类约定。

HuggingFaceGenerator(garak/generators/huggingface.py)则面向本地 transformers 模型,通常在 _call_model 中完成 pipeline(...) 调用并返回生成文本,与云端类共用了相同的基类接口 资料来源：garak/generators/huggingface.py:1-120。社区曾建议补充推理参数操纵(Inference Parameter Manipulation)测试(如篡改 temperature 或 seed 后观察幻觉率),目前主要由 OpenAICompatibleGenerator.generation_params 与基类的 temperature/top_k/top_p 字段承载 资料来源：issue #1233 "Inference Parameter Manipulation"。

3. 特殊场景下的生成器

• 函数桩生成器:garak/generators/function.py 提供 Single 模式,即把一个本地 Python 函数伪装为模型,从而在没有真实目标模型时回放固定响应,这常用于冒烟测试和报告回归 资料来源：garak/generators/function.py:1-60。
• LangChain 桥接:garak/generators/langchain.py 把 LangChain 的聊天模型/嵌入模型包装为 garak 生成器,使得基于 LangChain 链路(如 RAG、Agent)的系统可以直接接入扫描 资料来源：garak/generators/langchain.py:1-80。
• ggml/llama.cpp 本地推理:garak/generators/ggml.py 通过 ggml-python 与 llama_cpp 完成本地量化模型的推理,在 _call_model 中调用底层的 Llama(...) 类 资料来源：garak/generators/ggml.py:1-80。

最新版本中,garak 还陆续引入了 WebSocket 生成器(generator: Add WebSocket generator,v0.14.1,PR #1379)、AWS Bedrock 生成器(v0.13.3,PR #1462)、Mistral 生成器(v0.11.0,PR #1135)、音频 NIM 模型(v0.12.0,PR #1163)、simonw/llm 库适配(v0.15.1,PR #1633)。这些新生成器都遵循同一种模式——继承 Generator 并只覆写 _call_model 与必要的认证/端点字段。

4. 生成器在扫描流程中的位置

flowchart LR
    P[Probe 探测提示] --> G[Generator.generate]
    G -->|_call_model| B[具体后端: OpenAI / HF / ggml / WS]
    B --> R[原始响应]
    R --> G
    G --> D[Detector 评判]
    D --> RPT[报告/打分]

一个完整扫描循环如下:probe._attempt_once 取出提示 → 反复调用 generator.generate(prompt)(_call_model)→ detector.detect(outputs) 给出 0-1 分数 → 写入报告 资料来源：garak/generators/base.py:200-340。当目标模型存在多轮上下文时,生成器通过 clear_context()/Conversation 对象来维持会话,而 TAP/PAIR 等红队流程则需要 LLM 评审员对 target_response 进行评分,因此必须确保生成器在被攻击模型的视角下输出真实、未经改写的响应,以避免类似 #1868 中提示注入造成的伪造评分 资料来源：issue #1868 TAP/PAIR LLM-judge prompt interpolates target response unescaped。

总体来说,garak 通过 Generator 基类统一了"目标模型集成"的所有边界——商业 API、开源模型、本地推理、函数回放与多模态——并在 __init__.py 的工厂方法处把它们动态注入到扫描流水线中,这就是 garak 多后端探测能力的核心所在。

Pitfall Log / 踩坑日志

项目：NVIDIA/garak

摘要：发现 12 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：StringDetector substring matchers do no Unicode normalization — toxic output in homoglyph/fullwidth/zero-width form sco…。

1. 安装坑 · 来源证据：StringDetector substring matchers do no Unicode normalization — toxic output in homoglyph/fullwidth/zero-width form sco…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：StringDetector substring matchers do no Unicode normalization — toxic output in homoglyph/fullwidth/zero-width form scores clean (false-negative)
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/NVIDIA/garak/issues/1867 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：probe: extraction of personal info from llms

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：probe: extraction of personal info from llms
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/NVIDIA/garak/issues/219 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安全/权限坑 · 来源证据：False Positives in Guardrail Assessment

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：False Positives in Guardrail Assessment
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/NVIDIA/garak/issues/1595 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：Interest in contributing — agent red-teaming / eval probes

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Interest in contributing — agent red-teaming / eval probes
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/NVIDIA/garak/issues/1931 | 来源类型 github_issue 暴露的待验证使用条件。

5. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/NVIDIA/garak | README/documentation is current enough for a first validation pass.

6. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/NVIDIA/garak | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/NVIDIA/garak | no_demo; severity=medium

8. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/NVIDIA/garak | no_demo; severity=medium

9. 安全/权限坑 · 来源证据：TAP/PAIR LLM-judge prompt interpolates target response unescaped — model output can forge Rating rail and flip jailbrea…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：TAP/PAIR LLM-judge prompt interpolates target response unescaped — model output can forge Rating rail and flip jailbreak to safe
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/NVIDIA/garak/issues/1868 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

10. 安全/权限坑 · 来源证据：probe: LaTeX injection (target output executes when compiled — \write18, \input, \include)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：probe: LaTeX injection (target output executes when compiled — \write18, \input, \include)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/NVIDIA/garak/issues/1927 | 来源类型 github_issue 暴露的待验证使用条件。

11. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/NVIDIA/garak | issue_or_pr_quality=unknown

12. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/NVIDIA/garak | release_recency=unknown