English | 한국어 | Documentation
Apply privacy protection, tool authorization and content inspection to your application.
Tokenize detected PII before it reaches the model. Reveal only the originals a tool needs, then protect its result again.
Demo videos (YouTube): English · 한국어
A customer asks for a delivery update with a customer ID and an email address.
The model calls the customerLookup tool with tokens. The tool receives the original customer ID,
while the email stays tokenized. PII in the lookup result is protected again before the model answers.
This example uses a custom customer-ID detection rule and a per-tool disclosure policy.
Use these features independently or together.
| What you need | Feature |
|---|---|
| Keep detected PII out of the model and allow originals only for selected tools | Privacy |
| Limit tool visibility and execution using the current user's permissions | Tool Authorization |
| Check requests and responses with rules, local ONNX or an HTTP guard model | Content Inspection |
Two conversation-model calls surround one customer lookup. The final response passes output inspection. The application records the model calls, tool execution and guardrail decisions in Langfuse.
Output inspection detected insulting language in the reply and blocked its delivery.
Start with a minimal setup for email tokenization.
Use Java 17 or later, Spring AI 2.0.0 or later and Spring Boot 4.0.0 or later. See repository configuration and Maven setup.
Add the client starter:
dependencies {
implementation "io.github.ultramancode:spring-ai-privacy-guardrails-chat-client-spring-boot-starter:0.4.0"
}For this privacy example, enable the COMMON preset to detect email addresses.
Add to src/main/resources/application.yml:
spring:
ai:
privacy:
rules:
enabled: true
presets: [COMMON]Create the client through GuardrailsChatClientFactory in an application @Configuration class.
Select privacy protection in its policy:
@Bean
ChatClient chatClient(ChatModel chatModel, GuardrailsChatClientFactory guardrailsChatClientFactory) {
GuardrailsPolicy policy = GuardrailsPolicy.builder()
.privacy()
.build();
return guardrailsChatClientFactory.builder(chatModel, policy)
.build();
}Inject this bean into your service and call it:
String response = chatClient.prompt()
.user("Contact [email protected].")
.call()
.content();The model receives a replacement token instead of the email address.
For readability, the examples below use [EMAIL_TOKEN] to represent the generated token:
Contact [EMAIL_TOKEN].
See Getting Started for feature setup and combinations.
This customer lookup example combines privacy protection, Spring Security tool authorization and content inspection. Passing content inspection does not grant permission to run the lookup tool.
The example below uses the COMMON preset above with the Security starter
and a configured inspector.
It assumes that a ToolCallback bean named customerLookupToolCallback provides a customerLookup tool that looks up customers by email address.
This configuration replaces the earlier chatClient bean and adds an admin-only tool authorization policy:
@Bean
AuthorizationManager<ToolAuthorizationContext> toolAuthorizationManager() {
return AuthorityAuthorizationManager.hasRole("ADMIN");
}
@Bean
ChatClient chatClient(ChatModel chatModel, GuardrailsChatClientFactory guardrailsChatClientFactory,
ToolCallback customerLookupToolCallback) {
// Original PII disclosure: pass only original email addresses to customerLookup
ToolDisclosurePolicy toolDisclosurePolicy = ToolDisclosurePolicy.allowEntityTypesByToolName(
Map.of("customerLookup", List.of("EMAIL_ADDRESS")));
GuardrailsPolicy.Privacy privacySettings = GuardrailsPolicy.Privacy.builder()
.toolDisclosurePolicy(toolDisclosurePolicy)
.build();
GuardrailsPolicy policy = GuardrailsPolicy.builder()
.privacy(privacySettings) // Privacy: tokenize detected PII
.toolAuthorization(true) // Security: check the ADMIN role with Spring Security
.inspection() // Inspection: check for prompt injection, prompt leaking and toxic language
.build();
return guardrailsChatClientFactory.builder(chatModel, policy)
.defaultTools(customerLookupToolCallback)
.build();
}The authorization policy checks the current user's ADMIN role.
The disclosure map uses the registered tool name as its key and the list of allowed PII entity types as its value.
The inspection checks depend on the selected inspectors and their configuration.
Call it from an authenticated request:
String response = chatClient.prompt()
.user("Look up the customer with email [email protected].")
.call()
.content();The inspector receives the request with the email replaced by [EMAIL_TOKEN].
A BLOCK decision stops the main model call. An ALLOW decision passes the same protected request to the model,
while tool access still depends on the user:
- Admin (
ADMINrole): the model may requestcustomerLookup. Immediately before execution, permission is checked again, then[email protected]is restored for the tool. Other PII entity types remain tokenized. - User without the
ADMINrole:customerLookupis omitted from the model's tool list. Even if the model requests it by name, the tool is not executed and the email is not restored.
Before a lookup result is sent back to the model, its detected PII is tokenized and the protected content is inspected again.
If that inspection returns BLOCK, the next model call is stopped.
See tool registration and MCP integration. For custom disclosure logic, use a separate policy class. Final-response protection and inspection are separate opt-in output policies.
| Need | Next step |
|---|---|
| Detect your own employee or customer identifiers | Java rules and presets |
| Broader detection or NER models | Presidio and OpenNLP choices |
| Per-user tool visibility and execution | Spring Security setup |
| Input and optional output inspection | Content inspection setup |
| Tokenize, redact or block PII in the final answer | Output protection |
| Diagnose unexpected behavior | Troubleshooting |
The sample application uses fixed examples to illustrate Local Tool, RAG, MCP, Security and Inspection. See the Sample Guide for screenshots and run instructions.
Inspector demo videos: English · 한국어
| Component | Minimum supported version |
|---|---|
| Java | 17 |
| Spring AI | 2.0.0 |
| Spring Boot | 4.0.0 |
| Spring Security | 7.0.0 |
We continue to verify compatibility and support new releases of Java, Spring AI, Spring Boot and Spring Security as they become available. The Boot starter uses the Spring Security version selected by the Spring Boot BOM.
- Getting Started: common setup and first steps for privacy protection, tool authorization and content inspection
- Configuration: dependencies, client creation and reusable policies
- Privacy Protection: analyzers, tokenization, tool disclosure, output protection and processing limits
- Spring Security Tool Authorization: tool authorization policy, advanced tool configuration, Tool Search, and security-context handling
- Content Inspection: opt-in rules, local ONNX classifiers and HTTP guard models
- Runtime Observation: recorded normal and blocked requests and Observer usage
- Architecture: modules and model, tool, and session execution flow
- Threat Model: protected assets, trust boundaries, controls, limitations, and separately managed areas
- Evaluation and Benchmarks: verification coverage and interpretation limits
- Sample Guide: Inspector scenarios, runtime endpoints, and the evidence each view verifies
- Full Sample Guide: optional analyzer and real-model integration examples
./gradlew --no-daemon clean checkThis command runs the repository's tests and verifies its module rules.
Run ./gradlew verifyDocTranslations to check translation synchronization.
See Evaluation for the demo analyzer
regression test and JMH benchmarks.
See Contributing. All contributions are provided under the Apache License 2.0.

