muyki-labs/laravel-guardrails

# Laravel Guardrails [](https://github.com/muyki-labs/laravel-guardrails/actions/workflows/run-tests.yml) [](https://github.com/muyki-labs/laravel-guardrails/actions/workflows/phpstan.yml) [](https://packagist.org/packages/muyki-labs/laravel-guardrails) [](LICENSE.md) Laravel 中针对 LLM 输入和输出的安全层。**Laravel Guardrails** 会验证、清理并（可选地）拦截进出语言模型的数据流，使团队能够交付合规且可预测的 AI 功能——在统一、流畅且可组合的 pipeline 背后，实现 PII 修订、prompt 注入检测、内容审核以及 schema 验证。 ``` use MuykiLabs\Guardrails\Facades\Guardrails; $clean = Guardrails::for($userInput) ->stripPII() // redact emails, phones, IBANs, cards, TCKN, IPs ->blockPromptInjection() // detect jailbreak / instruction-override ->maxTokens(2000) ->guard(); // returns the sanitized value or throws $response = Guardrails::for($llmOutput) ->validateSchema($rules) // structured-output / JSON shape ->blockToxic() // moderation ->noPII() // ensure the model didn't leak PII back ->onViolation('redact') // throw | redact | retry | null ->guard(); ``` 它是**与提供商无关的，并且不需要任何外部服务即可运行**：regex PII 检测、基于启发式的 prompt 注入和审核，以及由 Laravel 验证机制支持的 schema 检查，所有这些都可以开箱即用。每个检测器都是可插拔且可通过 `extend()` 扩展的 manager，因此你无需修改调用处的代码，即可替换为 NER 服务、OpenAI 审核驱动或 LLM-as-judge。 ## 安装说明 ``` composer require muyki-labs/laravel-guardrails ``` 发布配置文件： ``` php artisan vendor:publish --tag=guardrails-config ``` 如果你需要持久化的审计日志，请发布并运行迁移： ``` php artisan vendor:publish --tag=guardrails-migrations php artisan migrate ``` 要求 PHP 8.3+ 和 Laravel 12 或 13。 ## Pipeline `Guardrails::for($value)` 返回一个流畅的 pipeline。将 guards 串联起来，然后使用以下方法之一结束： - `guard()` —— 运行 guards，应用违规策略，并返回处理后的值（或抛出异常）。 - `check()` —— 运行 guards 并返回一个 `GuardResult`（包含 `passed`、`value`、`violations`），而不会抛出异常。 - `passes()` / `fails()` —— 布尔值快捷方法。 ``` $result = Guardrails::for($input)->stripPII()->blockPromptInjection()->check(); if ($result->fails()) { foreach ($result->violations as $violation) { logger()->warning($violation->message, $violation->toArray()); } } ``` ### 输入 guards | 方法 | 作用 | | --- | --- | | `stripPII(array $types = [], ?string $strategy = null)` | 修订检测到的 PII。策略包括：`mask`、`hash`、`tokenize`、`remove`。 | | `blockPromptInjection()` | 标记越狱或指令覆盖企图。 | | `maxTokens(int $max)` | 拒绝（或截断）超过 token 预算的输入。 | | `maxLength(int $max)` | 拒绝（或截断）超过字符长度限制的输入。 | | `allow(array $terms)` | 要求输入中必须包含至少一个允许的词汇。 | | `deny(array $terms)` | 拒绝包含违禁词汇的输入。 | ### 输出 guards | 方法 | 作用 | | --- | --- | | `validateSchema(array\|Closure $rules)` | 根据 Laravel 规则或回调验证解码后的 JSON/array。 | | `blockToxic()` / `moderate()` | 对输出进行审核。 | | `noPII(array $types = [])` | 如果模型回显了 PII 则判定失败。 | ### 自定义 guards ``` use MuykiLabs\Guardrails\Contracts\Guard; use MuykiLabs\Guardrails\Support\GuardContext; use MuykiLabs\Guardrails\Support\GuardResult; Guardrails::for($input)->using(new MyGuard)->guard(); // Or register it by name so policies and config can reference it: Guardrails::extend('my_guard', fn (array $options) => new MyGuard($options)); Guardrails::for($input)->guardWith('my_guard', ['foo' => 'bar'])->guard(); ``` ## 封装 LLM 调用 `Guardrails::pipe()` 封装任何 callable：输入 guards 在调用前运行，输出 guards 在调用后运行。使用 `retry` 策略时，如果输出被拒绝，则会重新调用模型。 ``` $response = Guardrails::pipe(fn (string $clean) => $llm->generate($clean)) ->input(fn ($p) => $p->stripPII()->blockPromptInjection()) ->output(fn ($p) => $p->validateSchema($rules)->blockToxic()->noPII()) ->onViolation('retry') ->retries(2) ->run($userInput); ``` 这个 callable 与提供商无关，因此它可以与 Prism、`laravel/ai` 或你自己的客户端一起使用。输入违规总是会执行失败闭合（它们不能被“重试”）；只有输出 guards 会驱动重试循环。 ## 违规策略 通过 `onViolation()` 为每个 pipeline 设置（默认值来自 `config('guardrails.default_strategy')`）。 - `throw` —— 抛出 `GuardrailViolation` 异常（失败闭合，这也是默认行为）。 - `redact` —— 返回由 guards 生成的已清理值。 - `retry` ——（LLM 包装器）重新运行调用；在独立的 pipeline 中，这会像 `throw` 一样失败闭合。 - `null` —— 返回 `null` 以代替违规值。 ``` use MuykiLabs\Guardrails\Exceptions\GuardrailViolation; try { Guardrails::for($input)->blockPromptInjection()->guard(); } catch (GuardrailViolation $e) { $e->violations(); // list $e->guards(); // ['prompt_injection'] } ``` ## 策略 命名的、可重用的 guards 集合位于 `config/guardrails.php`： ``` 'policies' => [ 'support-bot' => [ 'strategy' => 'redact', 'input' => [ 'strip_pii' => ['strategy' => 'mask'], 'prompt_injection' => [], 'max_tokens' => ['max' => 2000], ], 'output' => [ 'moderation' => [], 'no_pii' => [], ], ], ], ``` ``` $clean = Guardrails::policy('support-bot')->guard($userInput); use MuykiLabs\Guardrails\Enums\GuardDirection; $safe = Guardrails::policy('support-bot', GuardDirection::Output)->guard($llmOutput); ``` ## PII 检测与修订 内置的 `regex` 检测器可以识别电子邮件、电话号码、IBAN、通过 Luhn 校验的信用卡、土耳其国民身份证（TCKN，已进行校验和验证）以及 IPv4。可以在 `guardrails.pii` 下配置匹配模式和启用的类型。修订策略包括： - `mask` —— 替换为标签，例如 `[EMAIL]`。 - `remove` —— 完全移除该值。 - `hash` —— 替换为稳定的 `[[EMAIL:abc123...]]` token。 - `tokenize` —— 可逆：原始值存储在缓存保险库中，可以被恢复。 注册自定义检测器（例如 NER 提供商）： ``` use MuykiLabs\Guardrails\Pii\PiiManager; app(PiiManager::class)->extend('ner', fn ($app) => new NerPiiDetector(...)); // then set GUARDRAILS_PII_DRIVER=ner ``` 审核和 prompt 注入子系统通过 `ModerationManager::extend()` 和 `InjectionManager::extend()` 以相同的方式工作。 ## 事件 绑定到以下任何事件（例如用于审计日志、仪表板或警报）： | 事件 | 触发时机 | | --- | --- | | `GuardrailPassed` | pipeline 完成且没有严重违规时。 | | `GuardrailViolated` | 一个或多个 guards 报告了违规时。 | | `InputRedacted` | 输入 guard 清理了值（例如 PII 修订）时。 | | `OutputBlocked` | 输出 pipeline 报告了违规时。 | | `GuardrailRetried` | LLM 包装器在 `retry` 策略下重新运行了调用时。 | ## 审计日志 将 `guardrails.audit.enabled` 设置为 `true`，以持久化记录违规情况，用于合规审查（KVKK / GDPR）。支持的驱动程序有：`database`（可查询）、`log`（写入 Laravel logger）或 `null`。 ``` php artisan guardrails:prune --days=90 # remove old audit entries ``` 在配置文件的 `prune.schedule` 下启用定时清理。 ## 命令 ``` php artisan guardrails:check "some text" --policy=support-bot # evaluate text php artisan guardrails:policies # list policies php artisan guardrails:prune --days=90 # prune audit log ``` ## 测试 ``` composer test composer analyse composer format ``` ## 许可证 The MIT License (MIT)。请参阅 [LICENSE.md](LICENSE.md)。

标签：DLL 劫持, ffuf, Laravel, Naabu, OpenVAS, PHP, PII脱敏, 内容安全, 大语言模型, 数据校验