feat: add ai-lakera-guard plugin#13570
Open
janiussyafiq wants to merge 3 commits into
Open
Conversation
Add the ai-lakera-guard plugin (PR-1, input guard MVP) integrating APISIX with the Lakera Guard v2 /guard API to scan LLM request prompts for prompt injection, PII, content-policy violations, and malicious/unknown links at the gateway. The plugin runs in the access phase at priority 1028, below ai-proxy / ai-proxy-multi, which it requires. It extracts the whole request conversation via apisix.plugins.ai-protocols and calls Lakera POST /v2/guard. On a flagged verdict it either blocks with a provider-compatible deny response (a valid chat-completion or SSE carrying request_failure_message, returned with deny_code, default 200) or alerts (log-only shadow mode). Lakera errors and timeouts are governed by fail_open (fail-closed by default). The api_key is secret-managed via encrypt_fields and the native $secret:// / $env:// resolution. Signed-off-by: janiussyafiq <izzraff.js@gmail.com>
dosubot
Bot
added
enhancement
nic-6443
reviewed
Jun 18, 2026
- Makefile: install apisix/plugins/ai-lakera-guard/*.lua so the luarocks 'diff -rq' check no longer reports the dir as uninstalled - t/admin/plugins.t: add ai-lakera-guard to the priority-ordered expected plugin list (priority 1028, between ai-aliyun-content- moderation 1029 and proxy-mirror 1010)
Handle requests this plugin cannot inspect (no picked ai instance, or an
unsupported protocol) via the shared ai-protocols.binding helper and a
configurable fail_mode (skip/warn/error, default skip) instead of a hard
500, matching ai-aliyun-content-moderation. This lets non-AI traffic pass
through unchecked when the plugin is bound at the Consumer/Service level.
fail_mode is distinct from fail_open, which governs Lakera API failures.
Also collapse the test routes onto a single route id (overwrite-in-place,
grouping default-config tests first) to match the convention used by the
sibling AI plugins.
- schema: add fail_mode = binding.schema_property("skip")
- access: route no-instance / unsupported-protocol through on_unsupported
- docs: document fail_mode; clarify non-ai-proxy traffic behavior
- t: fail_mode=error (500) and default skip (pass-through) coverage
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR adds a new plugin,
ai-lakera-guard, that integrates APISIX with the Lakera Guard v2/guardAPI to perform ML-based security scanning of LLM requests at the gateway — prompt injection / jailbreak, PII leakage, content-policy violations, and malicious / unknown links — so each backend LLM service no longer has to implement its own guardrails.This is PR-1 (input guard MVP) of a planned, independently shippable series (input → output → streaming → observability), modeled closely on
ai-aliyun-content-moderation.How it works
accessphase at priority 1028, just belowai-proxy(1040) andai-proxy-multi(1041), so the AI context is already populated. The plugin requires one of those proxies and returns500otherwise.apisix.plugins.ai-protocols(no role distinction) and sends it to LakeraPOST /v2/guard.action:block(default) — returns a provider-compatible deny response (a valid chat-completion, or SSE for streaming requests) carryingrequest_failure_message, built viaproto.build_deny_response, so client SDKs render the refusal as a normal completion. The status isdeny_code(default200; set a 4xx to surface blocks as HTTP errors).alert— log-only shadow mode; traffic passes through.fail_open(fail-closed by default).api_keyis secret-managed viaencrypt_fields+ native$secret:///$env://resolution.reveal_failure_categoriesoptionally appends the matched detectors to the deny message; every flagged verdict logs Lakera's full per-detector breakdown andrequest_uuid.Configuration
api_keyis the only required field. Others:lakera_endpoint,project_id,direction(inputonly in this PR),action,fail_open,timeout,ssl_verify,reveal_failure_categories,deny_code,request_failure_message.Files
apisix/plugins/ai-lakera-guard.lua,apisix/plugins/ai-lakera-guard/schema.lua,apisix/plugins/ai-lakera-guard/client.luaapisix/cli/config.lua,conf/config.yaml.exampledocs/en/latest/plugins/ai-lakera-guard.md,docs/en/latest/config.jsont/plugin/ai-lakera-guard.t,t/plugin/ai-lakera-guard-secrets.t, fixtures undert/fixtures/lakera/Which issue(s) this PR fixes:
Part of #13291
Checklist