Security and Validators
In shortHow input validators and PromptInjectionValidator work, the authorization model, and what the Full setup enables against injection and misuse.
- 9 min read
- 10 sections
- Updated
- v1.0.0
- Markdown
Validators are checks that run on incoming messages before a graph executes them. A validator subclasses BaseValidator, is registered on a CallbackManager, and raises ValidationError to reject unsafe input. Authorization defines who can call which endpoints and which scopes a caller has inside the graph. Together, they form a two-layer security model. Both reduce risk but do not eliminate it. For the full list of what the server enforces and what it leaves to you, see the Security model.
The two protection layers
A 10xGraph system needs protection at two distinct boundaries, each with different tools.
Server boundary: who may call what. The API server controls access using JWT authentication or custom auth logic. Each authenticated request becomes an Identity with a user_id, permissions and a reach. Every API endpoint checks one permission in the resource:action format (e.g., graph:invoke, threads:read, files:upload). Inside a direct Python invocation (no API), the developer passes the identity in config["user"]. The server also enforces CORS policies, request-size limits, and rate limits.
Model boundary: what text reaches the model. A user can inject instructions into a message, or a tool can fetch a document containing an attack. Validators run before the model sees input and reject suspicious content. Callbacks that inspect model output, tool calls, and tool results provide a second line of defense. Neither layer catches all attacks (indirect injection through tool results, for example), but combined they substantially reduce the attack surface.
Authorization model
Authorization inside 10xGraph is built on two concepts: reach and permissions. Both live on the Identity in config["user"], which the API builds from the verified token. Direct SDK callers may pass a dict that validates into an Identity.
Reach controls multi-tenant data isolation. It is "own" (the caller sees only their own threads and long-term data), "tenant" (every user with the same tenant values) or "all". Reach widens reads, lists and deletes only; runs and writes always stay on the caller’s own data. Storage applies it in every query, so another user’s thread answers 404. A reach that is missing or unknown raises, it never widens silently. With no identity, storage backends apply their own default.
Permissions are fine-grained strings in the format resource:action. A caller holds a set of them (e.g., {"graph:invoke", "threads:read", "files:upload"}), and * and resource:* are wildcards. They are checked at three layers: the API server rejects calls that lack the required permission at the endpoint (403), nodes inside the graph can call tenxgraph.core.authz.can(config, "resource:action") to check permissions, and tools can read the identity with get_identity(config) to enforce their own rules.
The permission registry (in 10xgraph-api):
- Graph execution:
graph:invoke,graph:stream,graph:stop,graph:fix,graph:read - Thread state and checkpointing:
threads:read,threads:write,threads:delete - Long-term memory (store):
store:read,store:write,store:delete - Files and media:
files:read,files:upload,files:delete - Configuration:
config:read - Background tasks:
tasks:trigger,tasks:read,tasks:cancel - Admin:
admin:read,admin:write
If no identity is present (common in direct SDK usage), the defaults are permissive: no reach filter is applied by the core and all permissions are allowed. This means existing code without explicit auth continues to work unchanged.
How validators run
When a run starts, validators are applied to the incoming messages before anything else executes. Here is the flow:
- The caller submits messages (user input, resume values, etc.) to
invoke()orainvoke(). - Inside the graph, the runtime calls
validate_message_content(), which invokesCallbackManager.execute_validators(). - Validators are called in the order they were registered, each awaited in sequence.
- If a validator raises
ValidationError, execution stops and the error is returned to the caller. If a publisher is configured, a rejection event is emitted. - If all validators pass, the graph continues normally.
Through the API server, a ValidationError becomes an HTTP 422 response with the error code VALIDATION_ERROR. In production mode the message is sanitized; the violation_type is not included in the response.
Input validators see only messages entering the graph on fresh runs and continued threads (resume calls). They do not inspect model output or tool arguments. To guard those, use register_before_invoke() and register_after_invoke() callbacks (see Callbacks and Command). For tool, MCP and RAG results, the guide Validate tool, MCP and RAG output has a working after_invoke example.
Writing a validator
A validator is a subclass of BaseValidator with an async validate(messages: list[Message]) -> bool method. Raise ValidationError(message, violation_type, details=None) to reject input. The violation_type is a machine-readable string (e.g., "pii_payment_card", "content_policy") available on the exception for logging.
Here is a complete example: a validator that blocks known test credit card numbers and another that blocks offensive language.
from tenxgraph import StateGraph
from tenxgraph.core.state import Message
from tenxgraph.utils.callbacks import BaseValidator, CallbackManager
from tenxgraph.utils.validators import PromptInjectionValidator, ValidationError
class NoCreditCardNumbers(BaseValidator):
"""Reject messages containing known test credit card patterns."""
async def validate(self, messages: list[Message]) -> bool:
test_cards = {
"4111111111111111", # Visa test
"5555555555554444", # Mastercard test
"378282246310005", # American Express test
}
for message in messages:
text = message.text().replace(" ", "").replace("-", "")
for card in test_cards:
if card in text:
raise ValidationError(
f"Test card number detected: {card[:4]}****",
"pii_payment_card",
details={"pattern": "credit_card"}
)
return True
class NoProfanity(BaseValidator):
"""Reject messages with offensive language from a local list."""
blocked_words = {"badword1", "badword2", "offensive_term"}
async def validate(self, messages: list[Message]) -> bool:
for message in messages:
text = message.text().lower()
for word in self.blocked_words:
if word in text:
raise ValidationError(
"Message contains prohibited language",
"content_policy"
)
return True
# Wire them into a graph
callback_manager = CallbackManager()
# Register the built-in prompt injection validator
callback_manager.register_input_validator(
PromptInjectionValidator(strict_mode=True, max_length=2000)
)
# Register custom validators
callback_manager.register_input_validator(NoCreditCardNumbers())
callback_manager.register_input_validator(NoProfanity())
# Compile the graph with the callback manager
# (AgentState and agent_node are your own state class and node function)
graph = StateGraph(AgentState)
graph.add_node("agent", agent_node)
# ... add edges and set entry point
app = graph.compile(callback_manager=callback_manager)Validators run synchronously from the graph’s perspective; make them fast and deterministic. Read from a database or call an LLM inside a validator only if absolutely necessary, as each call adds latency to every user message.
Built-in validators
PromptInjectionValidator
This validator detects prompt injection and jailbreak attempts using pattern matching and keyword analysis. It checks for:
- NUL characters (
\x00), refused with violation typeinvalid_character. They are also refused when a run loads its state, even with no validator registered. Text from the model or a tool is cleaned instead of refused; see Errors and limits - Excessive length (configurable, default 10000 characters)
- Regex patterns for common instruction-override tricks (e.g.,
"ignore all previous instructions") - Role manipulation attempts (e.g.,
"you are now a ...","pretend as a ...") - System prompt leakage techniques (e.g.,
"Reveal the system prompt") - Encoding obfuscation (Base64 payloads that decode to suspicious keywords, hidden Unicode tag characters, emoji variation selectors and bidirectional overrides, and Latin and Cyrillic letters mixed inside one word). Non-English text on its own is not flagged, so messages in any language pass.
- Template injection (
{{...}},${...},{%...%}), authority claims and payload-splitting markers - Delimiter confusion (e.g.,
"--- END OF INSTRUCTIONS ---",<system>tags) - Three or more suspicious keywords in a single message (e.g.,
"bypass","override","reveal")
It reads message text only (text, tool results, document excerpts, tool call arguments), not state or config. Anything beyond this list is your responsibility: write a BaseValidator subclass and register it with register_input_validator() (see Writing a validator).
Constructor parameters:
strict_mode=True(default): RaisesValidationErroron detection.strict_mode=False: Logs a warning and allows the message through without raising (useful for auditing without breaking the user experience). Pattern matching then covers only the firstmax_lengthcharacters.max_length=10000(default): Rejects messages longer than this. The length check runs before any pattern matching.blocked_patterns=None(optional): Add custom regex patterns to block.suspicious_keywords=None(optional): Add domain-specific suspicious keywords (e.g.,["refund", "cancel", "override"]for a support agent).
validator = PromptInjectionValidator(
strict_mode=True,
max_length=1000,
suspicious_keywords=["bypass", "secret_code", "admin_key"]
)MessageContentValidator
Validates the structure of messages themselves, independent of content. It checks:
- Allowed message roles (default
"user","assistant","system","tool") - Maximum number of content blocks per message (default 50)
Constructor parameters:
allowed_roles=None(default: user, assistant, system, tool)max_content_blocks=50(default)
register_default_validators
Convenience function to register both PromptInjectionValidator and MessageContentValidator with standard settings.
from tenxgraph.utils.validators import register_default_validators
callback_manager = CallbackManager()
register_default_validators(callback_manager, strict_mode=True)Files and media URLs
Media that a client sends is untrusted input. Three defaults protect the server:
- Media URLs. Where the server downloads a client’s media URL (Google GenAI, the Google File API, inline bytes), the download follows a
MediaFetchPolicy: public hosts only,httpandhttpsonly, redirects re-checked, 20 MiB and 10 seconds by default. The API checks client URLs before the run and returns400for a blocked one. A clientgs://URL is refused unless its bucket is inallowed_gcs_buckets. See Sending media from Python. - Uploads. The API compares the first bytes of an upload with its declared type (
415on a mismatch), caps text extraction, lets only the owner delete a file (files:delete) and deletes files when the messages and threads that use them are deleted. See Files and multimodal on the server. - File tools.
file_read,file_writeandfile_searchhide.env, key files and.ssh,.aws,.gnupgand.gitfolders by default, andcreate_file_tools(root)fixes the root in code. See File tools.
What the Full setup generates
When you run 10xgraph init --mode full, the generated project includes a security setup:
-
graph/validators/validators.pydefines aPromptInjectionValidator(strict_mode=True, max_length=10000)withmax_length=10000and a short list of suspicious keywords ("ignore previous","forget previous","disregard previous","circumvent","remove restrictions","coupon"). It no longer blocks everyday words such asbypass,override,disable,tokenorfree. Tune this list to your product. Keywords match whole words. -
graph/validators/manager.pycreates aCallbackManager, registers the validators, and registers anAgentLifecycleHook(aGraphLifecycleHooksubclass). -
graph/agent.pypasses the manager tograph.compile(callback_manager=callback_manager).
The template also sets up 10xgraph.json with an auth entry; choose the mode with --auth none|jwt|custom. The validators catch suspicious input before it reaches the model.
How tool output and authorization fit in
-
Tool, MCP and RAG output is checked with a callback. Input validators run on the messages entering the graph. For content a tool fetches, such as a document or web page, you add an
after_invokecallback onInvocationType.TOOLandInvocationType.MCP. It can check, edit or replace any result before the model reads it, and it can reusePromptInjectionValidatorinside. For checks on graph state, register aGraphLifecycleHook. See Validate tool, MCP and RAG output and Where each check runs. -
Authorization is a separate layer. Tools check access with the verified user in
configandcan(). Narrow tool permissions, and design tool side effects (refunds, deletions) to be idempotent and replay-safe. -
Tune strictness to your users. Strict mode rejects a message that matches a pattern, so test with real messages and use
strict_mode=Falseor narrower patterns where legitimate wording is flagged. -
Keep validators fast. Each message passes through every validator before the graph runs. Avoid I/O and LLM calls inside validators.
Best practices
| Practice | Why |
|---|---|
| Keep validators deterministic and fast | They run on the critical path for every message. |
| Avoid LLM calls and I/O inside validators | Each call adds latency; nondeterminism makes debugging hard. |
Raise ValidationError for policy failures, let exceptions propagate |
Callers can distinguish a policy violation (422 in the API) from a system error (500). |
| Tune keyword and pattern lists to your domain | Generic keyword lists flag legitimate phrases in some products. |
| Log rejections without logging the rejected content | Rejected messages may contain secrets or PII. Use violation_type and metadata instead. |
| Test validators with real user messages | Validation is a safety feature that changes user experience; testing is critical. |
Related concepts and guides
- Callbacks and Command: Inspect and transform messages at other execution points.
- Validate input and guard prompts: Practical guide to using validators and callbacks.
- Read the caller’s identity and scopes: How to check permissions and reach inside nodes and tools.
- Server authentication and authorization: API server setup for JWT, custom auth, roles, permissions and reach.