Security and Validators

In shortHow input validators and PromptInjectionValidator work, the authorization model, and what the production template enables against injection and misuse.

  • 7 min read
  • 9 sections
  • Updated
  • v0.10.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.

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 carries a user_id and a set of scopes. Every API endpoint checks scope permissions using the resource:action format (e.g., graph:invoke, checkpointer:read, files:upload). Inside a direct Python invocation (no API), the developer sets authorization in config["authz"]. 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: isolation scope and scopes.

Isolation scope controls multi-tenant data isolation. It can be "owner" (each user sees only their own threads and long-term data) or "none" (no isolation; data is not filtered by user, used in single-user deployments). When no explicit scope is set, storage backends apply their own default isolation policy.

Scopes are fine-grained permission strings in the format resource:action. A caller holds a list of scopes (e.g., ["graph:invoke", "checkpointer:read", "files:upload"]). These are checked at three layers: the API server rejects calls that lack the required scope at the endpoint, nodes inside the graph can call tenxgraph.core.authz.has_scope(config, "resource:action") to check permissions, and tools receive the full authorization block in config["authz"] to enforce their own rules.

The canonical scope set (verified in tenxgraph.core.authz):

  • Graph execution: graph:invoke, graph:stream, graph:stop, graph:fix, graph:setup, graph:read
  • Thread state and checkpointing: checkpointer:read, checkpointer:write, checkpointer:delete
  • Long-term memory (store): store:read, store:write, store:delete
  • Files and media: files:read, files:upload
  • Configuration: config:read

If no authorization is present (common in direct SDK usage), the defaults are permissive: isolation is not enforced and all scopes 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 AGENTFLOW_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).

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, keyword analysis, and heuristics. It checks for:

  • 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, messages that are mostly non-ASCII)
  • Delimiter confusion (e.g., "--- END OF INSTRUCTIONS ---", <system> tags)
  • Three or more suspicious keywords in a single message (e.g., "bypass", "override", "reveal")

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).
  • max_length=10000 (default): Rejects messages longer than this.
  • 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)

What the production template generates

When you run 10xgraph init --template production, the generated project includes a security setup:

  • graph/validators/validators.py defines a PromptInjectionValidator(strict_mode=True, max_length=1000) with domain-specific suspicious keywords: "bypass", "override", "token", "coupon", "free", and others. Tune this list to your product. Words like "free" are normal in a customer-facing e-commerce app but may be red flags in a payment processing app.

  • 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.

Limitations and tradeoffs

  • Validators are heuristic. A rephrased attack or one in a language the validator does not recognize may pass. A legitimate message with unlucky wording may be incorrectly rejected. Test with your real users.

  • Indirect injection is not covered. If a tool fetches a document or web page containing malicious instructions, validators will not catch it. Mitigate by validating tool results inside tools before using them.

  • Validators do not replace authorization. Narrow tool permissions, check scopes inside tools with has_scope(), and design tool side effects (refunds, deletions) to be idempotent and replay-safe so that authorization failures do not leave data in an inconsistent state.

  • Validators add latency. Each message passes through every validator before the graph runs. Keep them fast; 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 v0.10.0Edit this page on GitHubReport an issue