guardana/guardana

## 为什么要有 Guardana 现有的 AI 红队扫描器（garak、Giskard、PyRIT、CyberSecEval 等）擅长*发送*攻击。它们共同的、记录在案的弱点在于：难以判断攻击是否**真正成功**：基于关键词评分的动态检查，其结果误判率据报告高达 **37%**（[Fujitsu Research, 2024](https://arxiv.org/abs/2410.16527)）。 一个无法区分“拒绝”与“合规”的扫描器算不上安全工具——它只是一个带进度条的随机数生成器。 **Guardana 的答案：** 将*“它成功了吗？我们有多大把握？”*视为一个一流的、可插拔的、带版本控制的组件——即 **Evaluator**——而不是在探测结束时硬凑一个正则表达式。每一个动态发现都包含一个 `outcome`（结果）、一个 `confidence`（置信度）、一个 `rationale`（理由），以及生成它的 evaluator 的 id。评分逻辑可以自由替换，而无需触动生成它的规则；并且置信度直接展示在报告中，让你清楚该如何信任它。 静态供应链检查（pickle 操作码、不安全的模型格式、依赖风险）没有这个问题——它们是确定性的。因此，Guardana 将它们作为可靠的、没有“虚假误报表演”的**第一道防线**，并围绕这一核心构建了由 evaluator 评分的动态检查和实时监控。 ## 对比 大多数工具只能做好以下一件事。Guardana 的赌注是：运行自托管模型的团队希望用一个引擎覆盖模型文件、实时 endpoint *以及*运行中的服务——并且对每一个动态判定都提供置信度。 | | 静态模型产物扫描 | 实时 endpoint 探测 | 长期运行监控 | 评分置信度（非关键词） | OWASP-LLM / ATLAS 映射 | SARIF / CI 门禁 | |---|:--:|:--:|:--:|:--:|:--:|:--:| | **Guardana** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | garak | — | ✅ | — | 部分 | 部分 | 部分 | | ModelScan | ✅ | — | — | 不适用 | — | — | | promptfoo | — | ✅ | — | ✅ | — | ✅ | | PyRIT | — | ✅ | — | 部分 | — | — | | Giskard | — | ✅ | — | ✅ | 部分 | — | _{勾选标记反映了截至 2026 年 7 月各工具主要且记录在案的重点——这些都是目标不同、非常优秀的工具，而非应被忽视的竞争对手。欢迎通过 PR 进行修正。} ## 快速入门 直接从 PyPI 运行，无需安装： ``` uvx --from guardana-cli guardana scan . # zero-install run (uv) # 或将其添加到项目中： uv add guardana-cli # or: pip install guardana-cli ``` 控制台脚本是 `guardana`；其发布包为 `guardana-cli`（它会拉取 `guardana-core`/`guardana-rules`/`guardana-report`），因此需要使用 `--from`。 在开发 Guardana 本身？改为克隆仓库并运行 `uv sync` —— 参见 [`docs/install.md`](docs/install.md)。 看看它如何发现真实问题——一个内置的、刻意包含漏洞的模型目录（从克隆的仓库中运行；在检出的代码目录内执行 `uv run guardana …`）： ``` $ uv run guardana scan examples/vulnerable-model ✖ [CRITICAL] guardana.supply_chain.pickle_opcode — Dangerous pickle opcode (arbitrary code on load) unpickling imports non-allowlisted callable: posix.system (examples/vulnerable-model/model.pt) ✖ [HIGH] guardana.supply_chain.dependency_risk — Unsafe model/deserialization loader call torch.load without weights_only=True (examples/vulnerable-model/load_model.py:3) ▲ [MEDIUM] guardana.supply_chain.hallucinated_package — Import of unknown package (possible slopsquat lead) unknown import 'torchutilz' (lead — verify it exists on PyPI) (examples/vulnerable-model/train.py:1) 3 finding(s); 17 rule(s) run, 0 skipped. ``` ``` uv run guardana scan path/to/your/project # static scan of a repo or model dir uv run guardana rules # list every discovered rule + its standards tags uv run guardana init # write a starter guardana.yaml policy file uv run guardana new-rule acme.prompt.demo # scaffold a custom YAML rule (run via --rules) uv run guardana scan . --format sarif # SARIF 2.1.0 for GitHub code scanning uv run guardana --version # print the installed version ``` （在仓库根目录下运行 `guardana scan .` 会故意以 `1` 退出——因为这个仓库内置了刻意包含漏洞的 `examples/vulnerable-model/` 测试数据。将其指向 `packages/` 即可干净运行。） ## 三种运行方式 一个引擎，三个入口点，无需学习其他独立工具： | 模式 | 命令 | 用途 | |---|---|---| | **开发 / CI** | `guardana scan ` | 对仓库或模型目录进行快速、静态、无网络的扫描。可作为类似 linter 的门禁直接接入 pipeline。 | | **实时探测** | `guardana probe --url --model ` | 针对实时 endpoint 的一次性动态运行：prompt 注入、越狱（单轮和多轮场景）、系统 prompt 泄露、输出机密检查——每一项都由 Evaluator 进行评分并给出置信度。默认兼容 OpenAI；`--provider ollama\|tgi` 支持 Ollama 原生的 `/api/chat` 或 HF TGI 的 `/generate`。 | | **监控** | `guardana monitor --url --model ` | 在已部署模型旁运行的长期采样观察者；在策略门禁失败、发现数量超过基线，或*未验证*检查数量增加时发出警报——当一个模型的安全检查失效时，这本身就是警报。 | 这三种方式中的任何一种都可以使用 `--reporter server://` 将发现结果转发到可选的中心收集器（参见[中心化监控](#central-monitoring--self-hosted-or-managed)）。 完整的参数参考和示例输出： [`docs/usage-scan.md`](docs/usage-scan.md) · [`docs/usage-probe.md`](docs/usage-probe.md) · [`docs/usage-monitor.md`](docs/usage-monitor.md)。 ### 接入 GitHub Actions ``` # .github/workflows/ai-security.yml name: AI security on: [push, pull_request] jobs: guardana: runs-on: ubuntu-latest permissions: contents: read security-events: write # to upload SARIF steps: - uses: actions/checkout@v4 - uses: guardana/guardana@v0.1.2 # with: # args: --preset ci --baseline guardana-baseline.yaml ``` 更倾向于本地门禁？**pre-commit** 钩子可直接从 PyPI 安装。两者均见 [`docs/integrations.md`](docs/integrations.md)。 ## 内置功能 25 条内置规则，每个发现结果都会标记到你的合规流程中已经在使用的框架： | 规则 ID | 严重程度 | 类型 | 标准 | |---|---|---|---| | `guardana.supply_chain.pickle_opcode` | CRITICAL | artifact | OWASP LLM03/LLM05 · ATLAS T0018 · NIST supply-chain | | `guardana.supply_chain.dependency_risk` | HIGH | artifact | OWASP LLM03 · NIST supply-chain | | `guardana.supply_chain.remote_code` | HIGH | artifact | OWASP LLM03 · NIST supply-chain | | `guardana.supply_chain.remote_code_config` | HIGH | artifact | OWASP LLM03 · ATLAS T0018 · NIST supply-chain | | `guardana.supply_chain.notebook_payload` | HIGH | artifact | OWASP LLM03 · NIST supply-chain | | `guardana.training.dataset_integrity` | MEDIUM | artifact | OWASP LLM04 · ML02 · NIST poisoning | | `guardana.supply_chain.code_execution` | HIGH | artifact | OWASP LLM03 · NIST supply-chain | | `guardana.supply_chain.insecure_transport` | HIGH | artifact | OWASP LLM03 · NIST supply-chain | | `guardana.supply_chain.keras_lambda` | HIGH | artifact | OWASP LLM05 · ML06 · ATLAS T0018 | | `guardana.supply_chain.saved_model_ops` | MEDIUM | artifact | OWASP LLM05 · ML06 · ATLAS T0018 | | `guardana.supply_chain.malicious_dependency` | HIGH | artifact | OWASP LLM03 · ML06 · ATLAS T0018 | | `guardana.supply_chain.model_format` | HIGH | artifact | OWASP LLM03/LLM05 · NIST supply-chain | | `guardana.supply_chain.hallucinated_package` | MEDIUM | artifact | OWASP LLM03 | | `guardana.supply_chain.provenance` | MEDIUM | artifact | OWASP LLM03 · NIST supply-chain | | `guardana.supply_chain.hardcoded_secret` | HIGH | artifact | OWASP LLM02 | | `guardana.output.secrets` | HIGH | endpoint | OWASP LLM02 | | `guardana.prompt.injection.ignore_previous` | HIGH | endpoint | OWASP LLM01 · ATLAS T0051 | | `guardana.prompt.mcp_tool_poisoning` | HIGH | artifact | OWASP LLM01/LLM05 · ATLAS T0051 | | `guardana.prompt.hidden_instructions` | HIGH | artifact | OWASP LLM01/LLM05 · ATLAS T0051 | | `guardana.prompt.jailbreak.dan_style` | HIGH | endpoint | OWASP LLM01 | | `guardana.scenario.gradual_jailbreak` | HIGH | endpoint | OWASP LLM01 · ATLAS T0051 | | `guardana.scenario.indirect_injection` | HIGH | endpoint | OWASP LLM01/LLM08 · ATLAS T0051 | | `guardana.agent.excessive_tool_use` | HIGH | endpoint | OWASP LLM06 | | `guardana.prompt.unbounded_consumption` | MEDIUM | endpoint | OWASP LLM10 | | `guardana.prompt.system_prompt_leak.canary` | CRITICAL | endpoint | OWASP LLM07 · ATLAS T0056 | 17 个静态规则（`artifact` 类型）不需要模型和网络——它们是 CI 的第一道防线。8 个动态规则（`endpoint` 类型）会探测实时模型，并通过 Evaluator 对结果进行评分；其中两个（`scenario.gradual_jailbreak` 和 `scenario.indirect_injection`）是**多轮对话场景**——基于 YAML 声明的对话，按每一步及整体进行评分。`guardana rules` 会根据实际安装的内容打印此列表，**包括你添加的任何第三方规则。** 无法得出结论的动态检查——例如无法连接的评估器（judge）、空的模型回复——永远不会被默默归入“全部安全”的假象：它会在所有四种输出格式中通过单独的**未验证**通道进行报告，并且通过在 profile 中设置 `fail_on_inconclusive: true` 可以使其判定为门禁失败。 完整且持续维护的功能全貌——以及你可以基于此构建的方案——在 [`FEATURES.md`](FEATURES.md) 中。 ## 标准和架构 每一个发现都带有映射到 **OWASP LLM Top 10 (2025)**、**OWASP ML Top 10 (2023)**、**MITRE ATLAS v5.6.0** 和 **NIST AI 100-2e2025** 攻击类别的类型化引用——因此结果可以按照你的审计已经在使用的任何框架进行过滤和报告。 Guardana 构建于五个扩展点之上——**Target、Rule、Evaluator、Report/Finding、Profile**——外加一个 **Registry**，它能够以完全相同的方式发现规则和 evaluator，无论它们是内置在这个仓库中，还是存在于你自己的私有包中。引擎本身几乎不了解特定的威胁；所有的领域知识都存在于规则、evaluator 和 target 中。你可以通过增加这其中之一来扩展覆盖范围——而绝不需要修改引擎。 **把它当作一个框架，而不仅仅是一个 CLI。** 因为每个扩展点都是通过标准 Python entry point 发现的小型公共基类，你可以在不 fork 的情况下让 Guardana 适应你自己的技术栈：在你自己的 `acme.*` 命名空间下发布你所在组织的威胁规则；当内置 evaluator 不够严格时，引入你自己的**分类器**（一个 `Evaluator`——即负责评估“攻击是否成功，我们有多大把握”的评分器）；或者通过自定义的 `Target` 教它支持新的后端。两个通过配置连线、开箱即用的 evaluator 可以直接指向你自己的模型：**`llm_judge`**（位于任何兼容 OpenAI 的 endpoint 之后的 LLM 评估器——本地的 vLLM 或 Ollama 即可运行——带有版本控制的评分标准，并将置信度衡量为多次采样间的一致性）以及可选的 **`guard`** 安全分类器（Llama Guard / Granite Guardian 风格）；这两者都可以通过 `guardana.yaml` 中的 `evaluators:` 块来启用（[docs/profiles.md](docs/profiles.md)）。你可以将其保密，也可以向上游贡献——无论哪种方式契约都是一样的，并且 `guardana-core` 是一个普通的库，根本不想要 CLI，可以从你自己的代码中驱动它（`Registry` + `Runner`）。 - 以**声明式 YAML**（“发送此 prompt，使用此 evaluator 评分”）或作为 **Python 插件**来编写规则——参见 [`docs/writing-rules.md`](docs/writing-rules.md)。`guardana new-rule` 可以生成 YAML 脚手架，并且可复用的 `--rules ` 参数（或 `guardana.yaml` 中的 `rules.paths`）可以直接运行它，无需打包。 - 在 [`examples/custom_rule/`](examples/custom_rule/) 中有一个完整的、可运行的第三方包示例——包含一个插件规则、两个 YAML 规则和一个**自定义分类器**（`Evaluator`），全部通过 entry point 发现。安装它后，`guardana rules` 会将它的 `acme.*` 规则与内置规则一同展示。 - 完整的模型架构：[`docs/architecture.md`](docs/architecture.md) · [`docs/extending.md`](docs/extending.md)。 ## 中心化监控 —— 自托管或托管版 每一次扫描、探测和监控运行都能**完全离线工作**——除了目标本身之外没有任何网络调用，不需要注册账号，也没有供应商锁定。当你需要全局可见性时，任何运行都可以通过 `--reporter server://…` 将其标准化后的发现结果转发给收集器： - **自托管（`guardana-server`，OSS）：** 在一个地方汇总来自每个 agent 的发现——开发机、CI、实时监控。通过带有版本控制的 JSON API 进行摄取/列出/趋势分析，外加一个**可选的监控仪表盘**（`GUARDANA_DASHBOARD=1`，默认关闭）——一个独立的单页面，提供严重程度、各来源/各规则以及随时间变化的活动视图。身份验证和持久化存储已列入[路线图](ROADMAP.md)。 - **托管云（已规划）：** 为你托管的同一个收集器，提供仪表盘、多团队汇总、保留策略和管理功能——适合那些不想自己运行的团队。 无论哪种方式，引擎都保持完全独立：`guardana-core` 永远不会导入 `guardana-server`，即使是传递性导入也不行——这是一条由测试强制执行的边界，而不仅仅是口头承诺。收集器严格来说是附加的；引擎无论有没有它都能发挥其全部价值。 ## 为什么叫“Guardana”？ **Guard** + **-ana**。*Guard*（守卫）是全部的工作——为你自己运行的模型、endpoint 和 agent 站岗放哨。*-ana* 后缀就像 *Americana* 或 *Victoriana* 中的那样：代表一种事物的**集合体**。所以 Guardana 是一个鲜活的** AI 守护准则体系**——是不断发展、在一个引擎中协同注视着你系统的规则、evaluator 和检查机制的集合。 这个名字是经过深思熟虑后选择的：一个简短、可发音、发明的词——而不是在这个已经拥挤不堪的安全命名空间里再增加一个 *shield-* / *sentinel-* / *guard-X*——并且在写下第一行代码之前就已经确认它在 PyPI、npm 和 GitHub 上均未被占用，因此这个名字完全属于本项目。 ## 路线图 Guardana v0.1 是可靠的静态第一道防线，加上由 evaluator 评分的动态核心。未来的发展方向： | 版本 | 主题 | 亮点 | |---|---|---| | **v0.1** *(当前)* | 可靠的核心 | 25 条规则 · 供应链 + 训练数据 + 配置 RCE + notebook + 规则文件后门 · 运行时：注入、越狱、RAG 注入、**过度工具调用 (excessive-agency)**、**无限消耗**、金丝雀泄露 · 扫描/探测/监控 · LLM-judge 和 guard evaluator · SARIF & CI 门禁 · 插件引擎 · 可选收集器 | | **v0.2** | 深度与校准 | OSV/CVE 依赖匹配 + 别名导入 · 测量 judge 校准度 (ECE/Brier) · 引擎鲁棒性（插件隔离，`errors` 通道） · 官方 GitHub Action 与 pre-commit 钩子 | | **v0.3** | 深化运行时深度 | 强化 LLM10 (finish_reason/延迟信号) · 更深入的 LLM06 工具链 · 自适应攻击者 (Crescendo/GOAT) · 行为漂移门禁 · PII/毒性 evaluator | | **v0.4+** | 合规与溯源 | AIBOM / CycloneDX ML-BOM 导出 · 模型签名验证 · 微调数据集清洁度 | | **Cloud** | 全局可见性 | 产品化的收集器：仪表盘、趋势、多仓库/多模型汇总、策略管理——OSS 引擎已经可以接入的附加层 | 详细的、持续维护的版本——包括优先级、刻意推迟的内容及其原因，以及项目的非目标——在 [`ROADMAP.md`](ROADMAP.md) 中。有关已发布的更改，请参见 [`CHANGELOG.md`](CHANGELOG.md)。 ## 文档 - [`docs/index.md`](docs/index.md) — 文档地图 - [`docs/how-it-works.md`](docs/how-it-works.md) — **整个产品，从头到尾**（引擎、层次、扩展） - [`docs/install.md`](docs/install.md) — 安装 - [`docs/usage-scan.md`](docs/usage-scan.md) · [`docs/usage-probe.md`](docs/usage-probe.md) · [`docs/usage-monitor.md`](docs/usage-monitor.md) - [`docs/profiles.md`](docs/profiles.md) — `guardana.yaml` 策略文件 - [`docs/integrations.md`](docs/integrations.md) — GitHub Action & pre-commit - [`docs/writing-rules.md`](docs/writing-rules.md) — 编写规则（YAML 或 Python） - [`docs/architecture.md`](docs/architecture.md) · [`docs/extending.md`](docs/extending.md) ## 合作伙伴 Guardana 是开源的，并将继续保持开源——但我们也在寻找那些能塑造其未来发展方向的人： - **🏢 设计合作伙伴。** 你是否在生产环境中运行自托管或自建的 AI，并希望将 Guardana 接入你的 CI 以及部署在模型旁边？尽早与我们合作——帮助确定对你的技术栈至关重要的规则和集成优先级，并在路线图尚处于初期阶段时，与维护者保持直接的沟通渠道。 - **🧩 规则与集成作者。** 你是否拥有深厚的威胁专业知识、模型格式或你非常熟悉的护栏（guardrail）？插件模型意味着你的检查可以直接存在于你自己的包和命名空间下——你可以将它们向上游贡献或保持私有，这两种方式的契约完全相同。 - **☁️ 云端抢先体验。** OSS 引擎已经可以接入的收集器的托管、托管版本——提供仪表盘、多团队汇总和保留策略，无需你自己运行 `guardana-server`。如果集中式的 AI 安全态势管理已经在你的计划之内，请联系我们，帮助塑造它——并率先使用它。 - **💬 其他所有人。** 在[讨论区](https://github.com/guardana/guardana/discussions)给出的 Star、提出的问题、想法和疑问，都在切实推动项目向前发展。 联系方式：**hello@guardana.io** · [guardana.io](https://guardana.io) · [github.com/guardana](https://github.com/guardana) ## 许可证 Apache License 2.0 — 参见 [`LICENSE`](LICENSE)。随意使用、发布并在此基础上进行构建。

_{为你自己运行的 AI 保驾护航。}

标签：逆向工具