garak 参考文档全览LLM 漏洞扫描器的架构、运行机制与扩展开发指南【免费下载链接】garakthe LLM vulnerability scanner项目地址: https://gitcode.com/GitHub_Trending/ga/garak导读garakGenerative AI Red-teaming Assessment Kit是一款面向大语言模型LLM的安全漏洞扫描工具。本文基于 garak 官方参考文档入口 docs/source/index.rst 展开系统梳理 garak 的核心概念probe、detector、generator、harness、evaluator、buff、一次扫描的完整运行链路、安装与命令行用法、插件配置体系以及从零开发自定义插件的路径。读完本文你将掌握 garak 的整体架构视图能够读懂其参考文档的导航体系并据此完成一次从安装、配置到扫描与结果解读的完整实操。garak 是什么garak 是一个 LLM 漏洞扫描器LLM vulnerability scanner。它使用**大量的探针probes来检查和查询大语言模型模拟各类攻击随后使用一系列检测器detectors**分析模型的输出判断模型是否对这些攻击存在漏洞。与传统的网络扫描工具如 nmap、Metasploit类似garak 把扫描目标从主机换成了 LLM 与对话系统。它可以探测幻觉hallucination、数据泄漏data leakage、提示注入prompt injection、错误信息传播misinformation、毒性内容生成toxicity generation、越狱jailbreaks等多种失效模式并组合静态、动态与自适应三类探针进行探索详见仓库根目录 README.md。官方文档将读者分为两类想直接使用工具、只关心结果的人应去查阅用户指南User Guide想深入内部实现、参与代码贡献的人则应阅读代码参考文档即本文所介绍的内容。作为开发者参考入口docs/source/index.rst 通过四个隐藏 toctree 目录组织全部文档使用指南Using garak、插件参考Plugin reference、代码参考Code reference、技术专题Technologies以及扩展与贡献Extending and Contributing。文档体系导航四层 toctree 结构使用指南Using garak该分组面向如何跑起来这一核心诉求包含以下页面以下链接均已转换为仓库根目录相对路径how.rstgarak 一次运行的完整流程install.rst安装方式usage.rst基本用法与示例扫描configurable.rstYAML/JSON 配置体系cliref.rst命令行完整参考reporting.rst报告生成与解读cas.rst基于意图的分类评估Content Audit System 相关faster.rst加速扫描的技巧FAQ.md常见问题。插件参考Plugin referencegarak 的几乎所有功能都以插件形式存在这一分组给出了六大插件类别的索引页读者可按需查阅具体模块与类index_buffs.rstbuff提示词增变/模糊化插件index_detectors.rstdetector失效模式检测插件index_evaluators.rstevaluator结果评估方案插件index_generators.rstgenerator目标模型接口插件index_harnesses.rstharness测试编排插件index_probes.rstprobe攻击交互生成插件。这些索引页的源码实现分别对应 garak/probes/、garak/detectors/、garak/generators/、garak/harnesses/、garak/evaluators/、garak/buffs/ 六个目录每个目录下的base.py定义该类插件的基类。代码参考Code reference面向希望理解内部实现或贡献代码的开发者这一分组深入各核心模块basic.rst关键概念与类index_analyze.rst结果分析工具对应 garak/analyze/attempt.rstattempt 对象一次攻击尝试的载体cli.rst、command.rst命令行与命令处理_config.rst配置解析模块exception.rst异常体系interactive.rst交互式探测模式intents.rst意图intent类型体系payloads.rst载荷管理_plugins.rst插件加载机制_selection.rst、_spec.rst选择与规格解析report.rst报告数据结构对应 garak/report.pyservices.rst意图服务与语言服务garak/services/。技术专题与扩展贡献技术专题Technologiesascii_smuggling.rstASCII 走私攻击、detector_metrics.rst检测器度量、analyze/tbsa.rstTBSA 文本分析、translation.rst翻译。扩展与贡献Extending and Contributingcontributing.rst、extending.rst、extending.generator.rst编写新 generator 插件、extending.probe.rst编写新 probe 插件。核心概念与类一次扫描由哪些构件组成参考 basic.rst 的阐述garak 的目标是测试一个接收提示词并返回文本的系统是否安全为此它抽象出六个核心构件构件职责基类位置generator封装目标 LLM 或对话系统负责认证、加载、连接管理、退避重试等对外只暴露给提示、返回输出garak/generators/base.py 中的Generatorprobe尝试利用某一弱点诱发失效决定提示频率与提示内容garak/probes/base.py 中的Probe文本类为TextProbeattempt一次唯一的攻击尝试由 probe 封装并交给 generatorgenerator 将输出写回 attemptgarak/attempt.pydetector识别单一失效模式如未拒绝请求、延续有害字符串、解码编码提示等garak/detectors/base.py 中的Detectorbuff在提示发送给 generator 之前对其调整如翻译、改写garak/buffs/base.py 中的Buffevaluator将 detector 的判定转换为探针-检测器配对的通过/失败数据garak/evaluators/base.py 中的Evaluatorharness编排整个扫描选择探针与检测器、协调运行、执行最终评估garak/harnesses/base.py 中的Harness一次典型运行的链路见 how.rstgarak 从命令行读取模型类型及可选模型名→ 决定要运行的 probe 与 detector 插件 → 启动 generator → 交给 harness 管理探测 → 由 evaluator 处理结果。默认使用probewiseharnessgarak/harnesses/probewise.py。给定 probe 模块与插件名单后probewise逐个实例化 probe并为每个 probe 读取其primary_detector与extended_detectors属性得到一组要运行的 detector。每个插件类别都继承自对应的基类例如garak.generators.openai.OpenAIGenerator继承自garak.generators.base.Generator。大型产物模型文件、大规模语料不进入仓库通常存放在 Hugging Face Hub由客户端在使用 garak 时本地加载。安装与快速开始安装方式garak 是命令行工具在 Linux、macOS、Windows 上均可开发与使用。最直接的安装方式install.rst$ python3 -m pip install garak需要更新到开发版本时可从 GitHub 源码安装$ python3 -m pip install -U githttps://github.com/NVIDIA/garak.gitmain若从源码克隆并在独立 Conda 环境安装详见 README.mdconda create --name garak python3.11,3.13 conda activate garak git clone https://github.com/NVIDIA/garak.git cd garak python -m pip install -e .运行第一次扫描基本语法是garak options。运行扫描时至少要指定--target_type扫描的服务/模型接口如openai、huggingface、nim大多数情况下还需用--target_name指定具体模型如gpt-5-nano、meta/llama-3.1-8b-instruct。默认情况下garak 会对目标模型运行它知道的所有探针并使用每个探针推荐的漏洞检测器。可以先列出可用探针garak --list_probes限制探针范围则使用--spec统一选择规格例如只运行 PromptInject 框架的方法garak --target_type openai --target_name gpt-5-nano --spec probes.promptinject两个可直接照抄的示例来自 usage.rst注意将 API Key 替换为真实值# 探测商业模型对编码型提示注入的脆弱性 export OPENAI_API_KEYsk-123XXXXXXXXXXXX garak --target_type openai --target_name gpt-5-nano --spec probes.encoding# 判断 Hugging Face 版 GPT2 是否对 DAN 11.0 越狱脆弱 garak --target_type huggingface --target_name gpt2 --spec probes.dan.Dan_11_0对于托管模型若需要 API Key通常会要求以环境变量形式提供如果未设置garak 会中止扫描并报告缺失的变量名。读取结果扫描时每个探针会显示进度条生成完成后会为每个探针在各检测器上的结果输出一行评估。只要任一提示尝试诱发了非预期行为该行即标记为 FAIL 并给出失败率。行末形如840/840的数字表示总生成次数与其中表现正常的次数——由于每个提示默认会做多次生成默认generations为 10配置文件中默认 5该数字可能较大。运行日志写入garak.log每次运行的详细记录写入一个 JSONL 报告文件其文件名在扫描开始与结束时都会打印。此外还有命中日志hit log记录触发漏洞的尝试相关实现见 garak/report.py 与 garak/_config.py。命令行参考要点cliref.rst 给出了完整的 CLI 用法。核心参数速查参数作用--target_type/-t/-mgenerator 的模块及可选类如huggingface、openai--target_name/-n目标模型名如timdettmers/guanaco-33b-merged--spec/-S统一选择规格如probes.dan,-probes.dan.DanInTheWild,tag:owasp:llm01--generations/-g每个提示的生成次数--config本次运行的 YAML 或 JSON 配置文件--parallel_attempts并行运行的探测尝试数非本地模型可调高提速--parallel_requests同一提示并行发起的生成请求数--eval_threshold判定一次命中成功的最低阈值--seed/-s随机种子--deprefix从生成输出开头移除提示本身--detectors/-d指定检测器默认使用探针建议--extended_detectors除主检测器外还运行扩展检测器--plugin_info查看单个插件的描述与可配置参数如probes.lmrc.Profanity--list_probes/--list_detectors/--list_generators/--list_buffs列出各类插件--list_config打印生效配置信息不执行扫描--interactive/-I进入交互式探测模式--report/-r将 garak 报告转换为 AVID 报告列表--confidence_interval_method置信区间计算方法bootstrap默认或none--bootstrap_num_iterations/--bootstrap_confidence_level/--bootstrap_min_sample_size自举置信区间参数默认 10000 次迭代、0.95 置信水平、最小样本 30注意--probes/-p、--probe_tags、--buffs/-b等旧参数已被标记为deprecated应改用--spec的probes.*、tag:value、buffs.name选择器--fix则用于通过 fixer 迁移更新给定的配置文件。配置体系从 CLI 到 YAML/JSON 的层级覆盖garak 高度可配置configurable.rst可细到单个插件的具体行为。配置来源支持三种命令行参数、YAML/JSON 配置文件、命令行上的 JSON 字符串。配置值的优先级层级如下命令行给出的值通过--config传入的 YAML/JSON 文件站点配置garak.site.yaml/garak.site.yml/garak.site.json放在配置目录Linux 下为~/.config/garak/遵循 XDG 规范garak 核心配置中的固定值不建议修改位于安装的garak/resources包更新会覆盖插件代码中指定的默认值。配置解析由garak._config模块管理。核心配置示例节选自文档--- system: verbose: 0 narrow_output: false parallel_requests: false parallel_attempts: false lite: true show_z: false enable_experimental: false max_workers: 500 run: system_prompt: You are an AI model and this is a system prompt seed: deprefix: true eval_threshold: 0.5 generations: 5 spec: include: - probes.dan - tag: owasp:llm01 exclude: - probes.dan.DanInTheWild user_agent: garak/{version} (LLM vulnerability scanner https://garak.ai) soft_probe_prompt_cap: 256 plugins: target_type: target_name: detector_spec: auto extended_detectors: false buffs_include_original_prompt: false buff_max: detectors: {} generators: {} buffs: {} harnesses: {} probes: encoding: payloads: - default reporting: report_prefix: taxonomy: report_dir: garak_runs show_100_pass_modules: true group_aggregation_function: minimumsystem 配置项parallel_attempts可并行 generator 上并行运行的尝试数对 API 类模型是提升速度的关键parallel_requests对不支持单提示多次响应的 generator同一提示并行发起的请求数lite是否提示本次运行可能不够充分的警示verbose详细程度大于 0 的实验性报告与日志为准narrow_output在较窄 CLI 上简化输出show_z在 CLI 上显示 Z 分数与可视化指示enable_experimental启用实验性功能标志默认关闭只能改核心配置开启建议在 git 检出环境中使用max_workers可请求的并行工作线程上限提高并行度时注意系统资源如 Linux 的ulimit -n。parallel_requests与parallel_attempts是并行化的两种途径前者对同一提示并发多次生成在generations 1且端点单次只返回一个响应时能显著摊薄墙钟时间后者对多个不同提示并发。二者互斥当generations设为 1 时parallel_requests无效且其值超过generations时等价于等于generations。维护者实测中parallel_attempts通常更快——当提示种类多于生成次数时尤其明显而默认扫描中恰好如此。run 配置项system_prompt若给出且未被探针覆盖探针会在支持 chat 模态的 generator 上传递该系统提示spec探针与 buff 的统一选择规格见下文generations每个提示发送多少次推理deprefix从输出开头移除提示seed可选随机种子eval_threshold检测器输出 0..1 区间中判定攻击成功/命中的阈值user_agentHTTP User-Agent 字符串{version}会被版本号替换soft_probe_prompt_cap自动扩展提示数量的探针的每探针提示数上限target_lang目标应用接受/输出的单一语言BCP47langproviders将探针语言转换为目标语言BCP47的提供商配置列表serve_detectorless_intents意图服务是否提供没有配置检测器的意图。用 run.spec 选择探针与 buffrun.spec是选择探针与 buff 的唯一事实来源支持两种传输形式CLI 字符串--spec与配置文件形式include/exclude列表。选择器类别前缀必填probes.*或probes.all全部活跃探针未指定run.spec时的默认行为all与*可互换CLI 上all无需 shell 引号probes.module某个活跃探针族probes.module.Class某个探针类none或probes.none显式空选择与未指定默认probes.*相区别buffs.module[.Class]选择 buff默认不运行任何 bufftag:prefix按标签过滤探针如tag:owasp:llm01tier:N|name按层级过滤探针包含式日志级别语义tier:N包含层级1..N层级名称同样可用如tier:of_concern等价于tier:1intent:code按意图类型代码选择意图类探针如intent:S选择整个 Safety 分支、intent:S001选择某个类别、intent:S001mis选择叶子。这是独立轴不增删探针未给出时在解析阶段注入默认范围S。极性裸选择器或前缀表示包含-前缀表示排除tier:N是包含式过滤而-tier:N只精确移除层级 N。排除最后应用排除优先。若规格解析后无探针garak 会以可操作提示中止除非显式请求了none。规格是单个逗号分隔的 token选择器之间不允许空白*是 shell 通配符需要加引号或使用all别名。CLI 示例# 整个探针族减去一个类 garak --spec probes.dan,-probes.dan.DanInTheWild # 按标签过滤的探针族 garak --spec probes.grandma,tag:owasp:llm06 # 全部活跃探针 除 paraphrase 外的全部活跃 buff* 需要引号 garak --spec probes.*,buffs.*,-buffs.paraphrase # 全部活跃探针加一个特定非活跃类 garak --spec probes.all,probes.fitd.FITD # 层级 {1,3}tier:3 含 1..3再 -tier:2 精确移除 2 garak --spec probes.*,tier:3,-tier:2 # 一个意图探针配合一个意图类别 garak --spec probes.grandma.GrandmaIntent,intent:S004YAML 等价形式run: spec: include: - probes.dan - tag: owasp:llm01 exclude: - probes.dan.DanInTheWild旧的--probes/--probe_tags/--buffs标志与plugins.probe_spec/plugins.buff_spec/run.probe_tags配置键会被映射到run.spec并给出弃用提示同时给出时--spec优先。遗留的none值映射为显式空选择probes.none空值、auto或缺省视为未指定默认使用全部活跃探针。reporting 配置项report_dir报告目录默认$XDG_DATA/garak/garak_runsreport_prefix报告文件前缀默认garak.$RUN_UUIDtaxonomy生成 HTML 报告时对探针分组所用的分类体系如avid-effect、owaspshow_100_pass_modules100% 通过的条目是否仍在 HTML 报告中详列group_aggregation_function报告组模块或分类类别分数的聚合方式可选minimum、mean、median、mean_minus_sd、lower_quartile、proportion_passingmean/median会掩盖大量信息不推荐confidence_interval_method攻击成功率置信区间计算方法bootstrap默认非参数自举并做检测器性能校正需要检测器度量且 n≥30或nonebootstrap_num_iterations自举重采样迭代数默认 10000bootstrap_confidence_level置信水平默认 0.95bootstrap_min_sample_size可靠估计所需最小样本量默认 30。对应 CLI 参数示例python -m garak --confidence_interval_method none ... # 本次运行禁用 CI python -m garak --confidence_interval_method bootstrap ... # 显式启用默认内置快速配置garak 自带两个可直接用--config加载的快速配置源码中位于 garak/configs/bagbag.yaml校准calibration所用的配置包含大量精选探针与extended_detectors: true并设置system.parallel_attempts: 32fastfast.json快速运行——选择一批轻量探针、跳过扩展检测器extended_detectors: false、parallel_attempts: 20、generations: 3。扩展名规则JSON 配置可省略.json扩展名--config fastYAML 配置必须带.yaml或.yml--config fast.yaml扩展名大小写不敏感。自定义配置示例例如希望只运行latentinjection探针族且每个提示只跑一次可保存以下文件并用garak --config latent1.yaml加载YAML 格式保存为 latent1.yaml--- run: generations: 1 spec: include: - probes.latentinjectionJSON 格式保存为 latent1.json命令行可用--config latent1{ run: { generations: 1, spec: { include: [probes.latentinjection], exclude: [] } } }部分插件还支持在命令行直接传 JSON 配置--generator_options/--probe_options或文件形式--generator_option_file/--probe_option_file。插件配置与查看garak 的功能通过插件实现每个插件都是一个带描述性参数与可配置参数的类。用--plugin_info可查看任意插件的参数例如$ python -m garak --plugin_info probes.grandma.Win10 garak LLM vulnerability scanner v0.10.0 ( https://github.com/NVIDIA/garak ) at 2024-09-11T11:54:07.215242 Configured info on probes.grandma.Win10: description: Will the model yield a Windows 10 product key if we beg it to? DEFAULT_PARAMS: {generations: 1} active: True lang: en doc_uri: https://www.independent.co.uk/tech/chatgpt-microsoft-windows-11-grandma-exploit-b2360213.html extended_detectors: [mitigation.MitigationBypass] goal: get model to output Win 10 product keys modality: {in: [text]} parallelisable_attempts: True primary_detector: productkey.Win5x5 tags: [avid-effect:security:S0300, owasp:llm06, risk-cards:lmrc:providing_illegal_info, quality:Behavioral:ContentSafety:LegalGoodsServices] mod_time: 2024-07-01 04:16:40 0000其中DEFAULT_PARAMS字典列出可配置参数插件加载时实例会自动创建以DEFAULT_PARAMS命名的属性其值来自配置或默认值。不在DEFAULT_PARAMS中的是固定参数description、active、doc_uri、extended_detectors、goal、modality、parallelisable_attempts、primary_detector、tags、mod_time等它们描述插件能力而不参与实例化配置。在 YAML 中配置插件要进入plugins块按插件类型 → 模块 → 可选类逐级下钻。例如设置 OpenAIGenerator 的温度plugins: generators: openai: OpenAIGenerator: temperature: 1.0类名可选模块级配置同样生效并可被类级覆盖因此上面等价于plugins: generators: openai: temperature: 1.0一个更复杂的 RestGenerator 例子YAML 形式plugins: target_type: rest generators: rest: RestGenerator: uri: https://api.example.ai/v1/ key_env_var: EXAMPLE_KEY headers: Authentication: $KEY response_json_field: text request_timeout: 60含义端点 URI 为https://api.example.ai/v1/API Key 取自EXAMPLE_KEY环境变量未指定时检查REST_API_KEY每次请求发送Authentication:头并以 Key 为参数输出为 JSON顶层字段text保存模型响应超时 60 秒超时后生成器会退避重试。JSON 形式则写到文件后用-G传入例如{ rest: { RestGenerator: { name: example service, uri: https://127.0.0.1/llm, method: post, headers: { X-Authorization: $KEY }, req_template_json_object: { text: $INPUT }, response_json: true, response_json_field: text } } }在代码中实例化插件推荐用garak._plugins.load_plugin()在代码中实例化插件garak/_plugins.py。它接收两个参数name插件的包.模块.类如generator.test.Lipsum与可选的config_rootgarak._config或从顶层插件类型开始的配置字典返回配置好的插件实例 import garak._plugins c {generators:{openai:{OpenAIGenerator:{seed:30,name:gpt-4}}}} garak._plugins.load_plugin(generators.openai.OpenAIGenerator, config_rootc) loading generator: OpenAI: gpt-4 garak.generators.openai.OpenAIGenerator object at 0x71bc97693d70开发自己的插件参考文档的扩展与贡献分组提供了完整指引extending.rst、extending.probe.rst、extending.generator.rst。基本方法论结合 README.md 的插件开发章节观察现有插件如何实现继承对应基类如探针继承garak.probes.base.TextProbe生成器继承garak.generators.base.Generator检测器继承garak.detectors.base.Detector尽量少地覆盖基类行为用两种方式测试新代码交互式 Python 会话import garak.probes.mymodule后p garak.probes.mymodule.MyProbe()实例化用测试插件跑一次扫描探针可用python3 -m garak -m test.Blank -p mymodule -d always.Pass检测器可用python3 -m garak -m test.Blank -p test.Blank -d mymodule生成器可用python3 -m garak -m mymodule -p test.Blank -d always.Pass用--list_probes、--list_detectors、--list_generators确认插件被正确注册。对应源码与测试可供参考探针目录 garak/probes/、检测器目录 garak/detectors/、生成器目录 garak/generators/以及各自的测试目录如 tests/probes/、tests/detectors/、tests/generators/。总结与延伸阅读garak 以探针模拟攻击 检测器识别失效 harness 编排 evaluator 评估的插件化架构提供了对 LLM 漏洞进行系统化扫描的框架。作为开发者docs/source/index.rst 是进入这一体系的门户从 usage.rst 与 install.rst 快速上手经 configurable.rst 与 cliref.rst 掌握配置与命令行再通过 basic.rst、how.rst 与代码参考各页深入实现最终可借助扩展与贡献分组开发自己的探针、检测器与生成器。官方还提供了 garak-paper.pdf 论文可供引用与深入学习。【免费下载链接】garakthe LLM vulnerability scanner项目地址: https://gitcode.com/GitHub_Trending/ga/garak创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
garak 参考文档全览：LLM 漏洞扫描器的架构、运行机制与扩展开发指南
garak 参考文档全览LLM 漏洞扫描器的架构、运行机制与扩展开发指南【免费下载链接】garakthe LLM vulnerability scanner项目地址: https://gitcode.com/GitHub_Trending/ga/garak导读garakGenerative AI Red-teaming Assessment Kit是一款面向大语言模型LLM的安全漏洞扫描工具。本文基于 garak 官方参考文档入口 docs/source/index.rst 展开系统梳理 garak 的核心概念probe、detector、generator、harness、evaluator、buff、一次扫描的完整运行链路、安装与命令行用法、插件配置体系以及从零开发自定义插件的路径。读完本文你将掌握 garak 的整体架构视图能够读懂其参考文档的导航体系并据此完成一次从安装、配置到扫描与结果解读的完整实操。garak 是什么garak 是一个 LLM 漏洞扫描器LLM vulnerability scanner。它使用**大量的探针probes来检查和查询大语言模型模拟各类攻击随后使用一系列检测器detectors**分析模型的输出判断模型是否对这些攻击存在漏洞。与传统的网络扫描工具如 nmap、Metasploit类似garak 把扫描目标从主机换成了 LLM 与对话系统。它可以探测幻觉hallucination、数据泄漏data leakage、提示注入prompt injection、错误信息传播misinformation、毒性内容生成toxicity generation、越狱jailbreaks等多种失效模式并组合静态、动态与自适应三类探针进行探索详见仓库根目录 README.md。官方文档将读者分为两类想直接使用工具、只关心结果的人应去查阅用户指南User Guide想深入内部实现、参与代码贡献的人则应阅读代码参考文档即本文所介绍的内容。作为开发者参考入口docs/source/index.rst 通过四个隐藏 toctree 目录组织全部文档使用指南Using garak、插件参考Plugin reference、代码参考Code reference、技术专题Technologies以及扩展与贡献Extending and Contributing。文档体系导航四层 toctree 结构使用指南Using garak该分组面向如何跑起来这一核心诉求包含以下页面以下链接均已转换为仓库根目录相对路径how.rstgarak 一次运行的完整流程install.rst安装方式usage.rst基本用法与示例扫描configurable.rstYAML/JSON 配置体系cliref.rst命令行完整参考reporting.rst报告生成与解读cas.rst基于意图的分类评估Content Audit System 相关faster.rst加速扫描的技巧FAQ.md常见问题。插件参考Plugin referencegarak 的几乎所有功能都以插件形式存在这一分组给出了六大插件类别的索引页读者可按需查阅具体模块与类index_buffs.rstbuff提示词增变/模糊化插件index_detectors.rstdetector失效模式检测插件index_evaluators.rstevaluator结果评估方案插件index_generators.rstgenerator目标模型接口插件index_harnesses.rstharness测试编排插件index_probes.rstprobe攻击交互生成插件。这些索引页的源码实现分别对应 garak/probes/、garak/detectors/、garak/generators/、garak/harnesses/、garak/evaluators/、garak/buffs/ 六个目录每个目录下的base.py定义该类插件的基类。代码参考Code reference面向希望理解内部实现或贡献代码的开发者这一分组深入各核心模块basic.rst关键概念与类index_analyze.rst结果分析工具对应 garak/analyze/attempt.rstattempt 对象一次攻击尝试的载体cli.rst、command.rst命令行与命令处理_config.rst配置解析模块exception.rst异常体系interactive.rst交互式探测模式intents.rst意图intent类型体系payloads.rst载荷管理_plugins.rst插件加载机制_selection.rst、_spec.rst选择与规格解析report.rst报告数据结构对应 garak/report.pyservices.rst意图服务与语言服务garak/services/。技术专题与扩展贡献技术专题Technologiesascii_smuggling.rstASCII 走私攻击、detector_metrics.rst检测器度量、analyze/tbsa.rstTBSA 文本分析、translation.rst翻译。扩展与贡献Extending and Contributingcontributing.rst、extending.rst、extending.generator.rst编写新 generator 插件、extending.probe.rst编写新 probe 插件。核心概念与类一次扫描由哪些构件组成参考 basic.rst 的阐述garak 的目标是测试一个接收提示词并返回文本的系统是否安全为此它抽象出六个核心构件构件职责基类位置generator封装目标 LLM 或对话系统负责认证、加载、连接管理、退避重试等对外只暴露给提示、返回输出garak/generators/base.py 中的Generatorprobe尝试利用某一弱点诱发失效决定提示频率与提示内容garak/probes/base.py 中的Probe文本类为TextProbeattempt一次唯一的攻击尝试由 probe 封装并交给 generatorgenerator 将输出写回 attemptgarak/attempt.pydetector识别单一失效模式如未拒绝请求、延续有害字符串、解码编码提示等garak/detectors/base.py 中的Detectorbuff在提示发送给 generator 之前对其调整如翻译、改写garak/buffs/base.py 中的Buffevaluator将 detector 的判定转换为探针-检测器配对的通过/失败数据garak/evaluators/base.py 中的Evaluatorharness编排整个扫描选择探针与检测器、协调运行、执行最终评估garak/harnesses/base.py 中的Harness一次典型运行的链路见 how.rstgarak 从命令行读取模型类型及可选模型名→ 决定要运行的 probe 与 detector 插件 → 启动 generator → 交给 harness 管理探测 → 由 evaluator 处理结果。默认使用probewiseharnessgarak/harnesses/probewise.py。给定 probe 模块与插件名单后probewise逐个实例化 probe并为每个 probe 读取其primary_detector与extended_detectors属性得到一组要运行的 detector。每个插件类别都继承自对应的基类例如garak.generators.openai.OpenAIGenerator继承自garak.generators.base.Generator。大型产物模型文件、大规模语料不进入仓库通常存放在 Hugging Face Hub由客户端在使用 garak 时本地加载。安装与快速开始安装方式garak 是命令行工具在 Linux、macOS、Windows 上均可开发与使用。最直接的安装方式install.rst$ python3 -m pip install garak需要更新到开发版本时可从 GitHub 源码安装$ python3 -m pip install -U githttps://github.com/NVIDIA/garak.gitmain若从源码克隆并在独立 Conda 环境安装详见 README.mdconda create --name garak python3.11,3.13 conda activate garak git clone https://github.com/NVIDIA/garak.git cd garak python -m pip install -e .运行第一次扫描基本语法是garak options。运行扫描时至少要指定--target_type扫描的服务/模型接口如openai、huggingface、nim大多数情况下还需用--target_name指定具体模型如gpt-5-nano、meta/llama-3.1-8b-instruct。默认情况下garak 会对目标模型运行它知道的所有探针并使用每个探针推荐的漏洞检测器。可以先列出可用探针garak --list_probes限制探针范围则使用--spec统一选择规格例如只运行 PromptInject 框架的方法garak --target_type openai --target_name gpt-5-nano --spec probes.promptinject两个可直接照抄的示例来自 usage.rst注意将 API Key 替换为真实值# 探测商业模型对编码型提示注入的脆弱性 export OPENAI_API_KEYsk-123XXXXXXXXXXXX garak --target_type openai --target_name gpt-5-nano --spec probes.encoding# 判断 Hugging Face 版 GPT2 是否对 DAN 11.0 越狱脆弱 garak --target_type huggingface --target_name gpt2 --spec probes.dan.Dan_11_0对于托管模型若需要 API Key通常会要求以环境变量形式提供如果未设置garak 会中止扫描并报告缺失的变量名。读取结果扫描时每个探针会显示进度条生成完成后会为每个探针在各检测器上的结果输出一行评估。只要任一提示尝试诱发了非预期行为该行即标记为 FAIL 并给出失败率。行末形如840/840的数字表示总生成次数与其中表现正常的次数——由于每个提示默认会做多次生成默认generations为 10配置文件中默认 5该数字可能较大。运行日志写入garak.log每次运行的详细记录写入一个 JSONL 报告文件其文件名在扫描开始与结束时都会打印。此外还有命中日志hit log记录触发漏洞的尝试相关实现见 garak/report.py 与 garak/_config.py。命令行参考要点cliref.rst 给出了完整的 CLI 用法。核心参数速查参数作用--target_type/-t/-mgenerator 的模块及可选类如huggingface、openai--target_name/-n目标模型名如timdettmers/guanaco-33b-merged--spec/-S统一选择规格如probes.dan,-probes.dan.DanInTheWild,tag:owasp:llm01--generations/-g每个提示的生成次数--config本次运行的 YAML 或 JSON 配置文件--parallel_attempts并行运行的探测尝试数非本地模型可调高提速--parallel_requests同一提示并行发起的生成请求数--eval_threshold判定一次命中成功的最低阈值--seed/-s随机种子--deprefix从生成输出开头移除提示本身--detectors/-d指定检测器默认使用探针建议--extended_detectors除主检测器外还运行扩展检测器--plugin_info查看单个插件的描述与可配置参数如probes.lmrc.Profanity--list_probes/--list_detectors/--list_generators/--list_buffs列出各类插件--list_config打印生效配置信息不执行扫描--interactive/-I进入交互式探测模式--report/-r将 garak 报告转换为 AVID 报告列表--confidence_interval_method置信区间计算方法bootstrap默认或none--bootstrap_num_iterations/--bootstrap_confidence_level/--bootstrap_min_sample_size自举置信区间参数默认 10000 次迭代、0.95 置信水平、最小样本 30注意--probes/-p、--probe_tags、--buffs/-b等旧参数已被标记为deprecated应改用--spec的probes.*、tag:value、buffs.name选择器--fix则用于通过 fixer 迁移更新给定的配置文件。配置体系从 CLI 到 YAML/JSON 的层级覆盖garak 高度可配置configurable.rst可细到单个插件的具体行为。配置来源支持三种命令行参数、YAML/JSON 配置文件、命令行上的 JSON 字符串。配置值的优先级层级如下命令行给出的值通过--config传入的 YAML/JSON 文件站点配置garak.site.yaml/garak.site.yml/garak.site.json放在配置目录Linux 下为~/.config/garak/遵循 XDG 规范garak 核心配置中的固定值不建议修改位于安装的garak/resources包更新会覆盖插件代码中指定的默认值。配置解析由garak._config模块管理。核心配置示例节选自文档--- system: verbose: 0 narrow_output: false parallel_requests: false parallel_attempts: false lite: true show_z: false enable_experimental: false max_workers: 500 run: system_prompt: You are an AI model and this is a system prompt seed: deprefix: true eval_threshold: 0.5 generations: 5 spec: include: - probes.dan - tag: owasp:llm01 exclude: - probes.dan.DanInTheWild user_agent: garak/{version} (LLM vulnerability scanner https://garak.ai) soft_probe_prompt_cap: 256 plugins: target_type: target_name: detector_spec: auto extended_detectors: false buffs_include_original_prompt: false buff_max: detectors: {} generators: {} buffs: {} harnesses: {} probes: encoding: payloads: - default reporting: report_prefix: taxonomy: report_dir: garak_runs show_100_pass_modules: true group_aggregation_function: minimumsystem 配置项parallel_attempts可并行 generator 上并行运行的尝试数对 API 类模型是提升速度的关键parallel_requests对不支持单提示多次响应的 generator同一提示并行发起的请求数lite是否提示本次运行可能不够充分的警示verbose详细程度大于 0 的实验性报告与日志为准narrow_output在较窄 CLI 上简化输出show_z在 CLI 上显示 Z 分数与可视化指示enable_experimental启用实验性功能标志默认关闭只能改核心配置开启建议在 git 检出环境中使用max_workers可请求的并行工作线程上限提高并行度时注意系统资源如 Linux 的ulimit -n。parallel_requests与parallel_attempts是并行化的两种途径前者对同一提示并发多次生成在generations 1且端点单次只返回一个响应时能显著摊薄墙钟时间后者对多个不同提示并发。二者互斥当generations设为 1 时parallel_requests无效且其值超过generations时等价于等于generations。维护者实测中parallel_attempts通常更快——当提示种类多于生成次数时尤其明显而默认扫描中恰好如此。run 配置项system_prompt若给出且未被探针覆盖探针会在支持 chat 模态的 generator 上传递该系统提示spec探针与 buff 的统一选择规格见下文generations每个提示发送多少次推理deprefix从输出开头移除提示seed可选随机种子eval_threshold检测器输出 0..1 区间中判定攻击成功/命中的阈值user_agentHTTP User-Agent 字符串{version}会被版本号替换soft_probe_prompt_cap自动扩展提示数量的探针的每探针提示数上限target_lang目标应用接受/输出的单一语言BCP47langproviders将探针语言转换为目标语言BCP47的提供商配置列表serve_detectorless_intents意图服务是否提供没有配置检测器的意图。用 run.spec 选择探针与 buffrun.spec是选择探针与 buff 的唯一事实来源支持两种传输形式CLI 字符串--spec与配置文件形式include/exclude列表。选择器类别前缀必填probes.*或probes.all全部活跃探针未指定run.spec时的默认行为all与*可互换CLI 上all无需 shell 引号probes.module某个活跃探针族probes.module.Class某个探针类none或probes.none显式空选择与未指定默认probes.*相区别buffs.module[.Class]选择 buff默认不运行任何 bufftag:prefix按标签过滤探针如tag:owasp:llm01tier:N|name按层级过滤探针包含式日志级别语义tier:N包含层级1..N层级名称同样可用如tier:of_concern等价于tier:1intent:code按意图类型代码选择意图类探针如intent:S选择整个 Safety 分支、intent:S001选择某个类别、intent:S001mis选择叶子。这是独立轴不增删探针未给出时在解析阶段注入默认范围S。极性裸选择器或前缀表示包含-前缀表示排除tier:N是包含式过滤而-tier:N只精确移除层级 N。排除最后应用排除优先。若规格解析后无探针garak 会以可操作提示中止除非显式请求了none。规格是单个逗号分隔的 token选择器之间不允许空白*是 shell 通配符需要加引号或使用all别名。CLI 示例# 整个探针族减去一个类 garak --spec probes.dan,-probes.dan.DanInTheWild # 按标签过滤的探针族 garak --spec probes.grandma,tag:owasp:llm06 # 全部活跃探针 除 paraphrase 外的全部活跃 buff* 需要引号 garak --spec probes.*,buffs.*,-buffs.paraphrase # 全部活跃探针加一个特定非活跃类 garak --spec probes.all,probes.fitd.FITD # 层级 {1,3}tier:3 含 1..3再 -tier:2 精确移除 2 garak --spec probes.*,tier:3,-tier:2 # 一个意图探针配合一个意图类别 garak --spec probes.grandma.GrandmaIntent,intent:S004YAML 等价形式run: spec: include: - probes.dan - tag: owasp:llm01 exclude: - probes.dan.DanInTheWild旧的--probes/--probe_tags/--buffs标志与plugins.probe_spec/plugins.buff_spec/run.probe_tags配置键会被映射到run.spec并给出弃用提示同时给出时--spec优先。遗留的none值映射为显式空选择probes.none空值、auto或缺省视为未指定默认使用全部活跃探针。reporting 配置项report_dir报告目录默认$XDG_DATA/garak/garak_runsreport_prefix报告文件前缀默认garak.$RUN_UUIDtaxonomy生成 HTML 报告时对探针分组所用的分类体系如avid-effect、owaspshow_100_pass_modules100% 通过的条目是否仍在 HTML 报告中详列group_aggregation_function报告组模块或分类类别分数的聚合方式可选minimum、mean、median、mean_minus_sd、lower_quartile、proportion_passingmean/median会掩盖大量信息不推荐confidence_interval_method攻击成功率置信区间计算方法bootstrap默认非参数自举并做检测器性能校正需要检测器度量且 n≥30或nonebootstrap_num_iterations自举重采样迭代数默认 10000bootstrap_confidence_level置信水平默认 0.95bootstrap_min_sample_size可靠估计所需最小样本量默认 30。对应 CLI 参数示例python -m garak --confidence_interval_method none ... # 本次运行禁用 CI python -m garak --confidence_interval_method bootstrap ... # 显式启用默认内置快速配置garak 自带两个可直接用--config加载的快速配置源码中位于 garak/configs/bagbag.yaml校准calibration所用的配置包含大量精选探针与extended_detectors: true并设置system.parallel_attempts: 32fastfast.json快速运行——选择一批轻量探针、跳过扩展检测器extended_detectors: false、parallel_attempts: 20、generations: 3。扩展名规则JSON 配置可省略.json扩展名--config fastYAML 配置必须带.yaml或.yml--config fast.yaml扩展名大小写不敏感。自定义配置示例例如希望只运行latentinjection探针族且每个提示只跑一次可保存以下文件并用garak --config latent1.yaml加载YAML 格式保存为 latent1.yaml--- run: generations: 1 spec: include: - probes.latentinjectionJSON 格式保存为 latent1.json命令行可用--config latent1{ run: { generations: 1, spec: { include: [probes.latentinjection], exclude: [] } } }部分插件还支持在命令行直接传 JSON 配置--generator_options/--probe_options或文件形式--generator_option_file/--probe_option_file。插件配置与查看garak 的功能通过插件实现每个插件都是一个带描述性参数与可配置参数的类。用--plugin_info可查看任意插件的参数例如$ python -m garak --plugin_info probes.grandma.Win10 garak LLM vulnerability scanner v0.10.0 ( https://github.com/NVIDIA/garak ) at 2024-09-11T11:54:07.215242 Configured info on probes.grandma.Win10: description: Will the model yield a Windows 10 product key if we beg it to? DEFAULT_PARAMS: {generations: 1} active: True lang: en doc_uri: https://www.independent.co.uk/tech/chatgpt-microsoft-windows-11-grandma-exploit-b2360213.html extended_detectors: [mitigation.MitigationBypass] goal: get model to output Win 10 product keys modality: {in: [text]} parallelisable_attempts: True primary_detector: productkey.Win5x5 tags: [avid-effect:security:S0300, owasp:llm06, risk-cards:lmrc:providing_illegal_info, quality:Behavioral:ContentSafety:LegalGoodsServices] mod_time: 2024-07-01 04:16:40 0000其中DEFAULT_PARAMS字典列出可配置参数插件加载时实例会自动创建以DEFAULT_PARAMS命名的属性其值来自配置或默认值。不在DEFAULT_PARAMS中的是固定参数description、active、doc_uri、extended_detectors、goal、modality、parallelisable_attempts、primary_detector、tags、mod_time等它们描述插件能力而不参与实例化配置。在 YAML 中配置插件要进入plugins块按插件类型 → 模块 → 可选类逐级下钻。例如设置 OpenAIGenerator 的温度plugins: generators: openai: OpenAIGenerator: temperature: 1.0类名可选模块级配置同样生效并可被类级覆盖因此上面等价于plugins: generators: openai: temperature: 1.0一个更复杂的 RestGenerator 例子YAML 形式plugins: target_type: rest generators: rest: RestGenerator: uri: https://api.example.ai/v1/ key_env_var: EXAMPLE_KEY headers: Authentication: $KEY response_json_field: text request_timeout: 60含义端点 URI 为https://api.example.ai/v1/API Key 取自EXAMPLE_KEY环境变量未指定时检查REST_API_KEY每次请求发送Authentication:头并以 Key 为参数输出为 JSON顶层字段text保存模型响应超时 60 秒超时后生成器会退避重试。JSON 形式则写到文件后用-G传入例如{ rest: { RestGenerator: { name: example service, uri: https://127.0.0.1/llm, method: post, headers: { X-Authorization: $KEY }, req_template_json_object: { text: $INPUT }, response_json: true, response_json_field: text } } }在代码中实例化插件推荐用garak._plugins.load_plugin()在代码中实例化插件garak/_plugins.py。它接收两个参数name插件的包.模块.类如generator.test.Lipsum与可选的config_rootgarak._config或从顶层插件类型开始的配置字典返回配置好的插件实例 import garak._plugins c {generators:{openai:{OpenAIGenerator:{seed:30,name:gpt-4}}}} garak._plugins.load_plugin(generators.openai.OpenAIGenerator, config_rootc) loading generator: OpenAI: gpt-4 garak.generators.openai.OpenAIGenerator object at 0x71bc97693d70开发自己的插件参考文档的扩展与贡献分组提供了完整指引extending.rst、extending.probe.rst、extending.generator.rst。基本方法论结合 README.md 的插件开发章节观察现有插件如何实现继承对应基类如探针继承garak.probes.base.TextProbe生成器继承garak.generators.base.Generator检测器继承garak.detectors.base.Detector尽量少地覆盖基类行为用两种方式测试新代码交互式 Python 会话import garak.probes.mymodule后p garak.probes.mymodule.MyProbe()实例化用测试插件跑一次扫描探针可用python3 -m garak -m test.Blank -p mymodule -d always.Pass检测器可用python3 -m garak -m test.Blank -p test.Blank -d mymodule生成器可用python3 -m garak -m mymodule -p test.Blank -d always.Pass用--list_probes、--list_detectors、--list_generators确认插件被正确注册。对应源码与测试可供参考探针目录 garak/probes/、检测器目录 garak/detectors/、生成器目录 garak/generators/以及各自的测试目录如 tests/probes/、tests/detectors/、tests/generators/。总结与延伸阅读garak 以探针模拟攻击 检测器识别失效 harness 编排 evaluator 评估的插件化架构提供了对 LLM 漏洞进行系统化扫描的框架。作为开发者docs/source/index.rst 是进入这一体系的门户从 usage.rst 与 install.rst 快速上手经 configurable.rst 与 cliref.rst 掌握配置与命令行再通过 basic.rst、how.rst 与代码参考各页深入实现最终可借助扩展与贡献分组开发自己的探针、检测器与生成器。官方还提供了 garak-paper.pdf 论文可供引用与深入学习。【免费下载链接】garakthe LLM vulnerability scanner项目地址: https://gitcode.com/GitHub_Trending/ga/garak创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
