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:

  1. The caller submits messages (user input, resume values, etc.) to invoke() or ainvoke().
  2. Inside the graph, the runtime calls validate_message_content(), which invokes CallbackManager.execute_validators().
  3. Validators are called in the order they were registered, each awaited in sequence.
  4. 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.
  5. 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.

Python
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 type invalid_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): Raises ValidationError on 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 first max_length characters.
  • 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).
Python
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.

Python
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, http and https only, redirects re-checked, 20 MiB and 10 seconds by default. The API checks client URLs before the run and returns 400 for a blocked one. A client gs:// URL is refused unless its bucket is in allowed_gcs_buckets. See Sending media from Python.
  • Uploads. The API compares the first bytes of an upload with its declared type (415 on 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_write and file_search hide .env, key files and .ssh, .aws, .gnupg and .git folders by default, and create_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.py defines a PromptInjectionValidator(strict_mode=True, max_length=10000) with max_length=10000 and a short list of suspicious keywords ("ignore previous", "forget previous", "disregard previous", "circumvent", "remove restrictions", "coupon"). It no longer blocks everyday words such as bypass, override, disable, token or free. Tune this list to your product. Keywords match whole words.

  • graph/validators/manager.py creates a CallbackManager, registers the validators, and registers an AgentLifecycleHook (a GraphLifecycleHook subclass).

  • graph/agent.py passes the manager to graph.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_invoke callback on InvocationType.TOOL and InvocationType.MCP. It can check, edit or replace any result before the model reads it, and it can reuse PromptInjectionValidator inside. For checks on graph state, register a GraphLifecycleHook. 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 config and can(). 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=False or 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.
Last updated for v1.0.0Edit this page on GitHubReport an issue