Skip to main content

trajeckt: A Sealed-Commitment Runtime Enforcement Gateway for Agents

· 7 min read
p4r4d0xb0x
p4r4d0xb0x
Rustacean, AI, OSS Enthusiast

trajeckt is a runtime-enforcement gateway designed to address the blind spot in traditional approaches that evaluate every tool call from an agent independently. According to the supplied repository materials, its main idea is to "compile permitted trajectories into a sealed graph before agent execution, then fail closed by checking every call during execution against the graph's currently reachable frontier." The approach aims to fill the structural gap in existing systems that cannot detect a multistep data-exfiltration scenario from any single call.

Summary: the repository README, documentation, and examples present this central flow. A Docker-based stack and standalone example are provided. In the default mode, auto_commitment automatically builds a sealed graph from the tool list and installs it in the session. A tool call arriving without an installed graph is explicitly blocked. If an operator explicitly opts out, a heuristic safety net blocks only known malicious patterns. Implementation details absent from the supplied material, such as every field in internal data structures and production-scale performance data, fall outside the documentation, so this article describes only techniques supported by the source.

Core Design Elements​

  • Sealed-Commitment graph: the tools, order, and data-sink scope available to an agent are declared and compiled in advance, then sealed with HMAC or a similar mechanism. Once the seal becomes the session's authority, the gateway rejects calls outside the graph's current reachable frontier.
  • Trajectory-level enforcement: each call is checked against the entire trajectory and data-flow context accumulated by the current session. A single call may look legitimate, but the last step is blocked if sensitive data produced earlier is moving to a destination.
  • Agent-unreachable state: the agent's context window is treated as potentially compromised, while the gateway maintains validation state that the agent cannot directly access.
  • Heuristic floor: if an operator explicitly opts out of sealing, simple sequence-based heuristics block known malicious patterns such as ReadSensitive → ExternalWrite. This is designed as a last-resort safety net rather than the primary product feature.

Execution Flow: A Simple Example​

The standalone example in the documentation runs the same three-stage call sequence twice for comparison. A traditional approach that evaluates each call independently allows every call and permits data exfiltration. With trajeckt's sealed validation, the final external transmission is blocked. The example flow in pseudocode is:

read_database -> summarize -> send_email_external
# Traditional evaluation: ALLOW all
# trajeckt (sealed graph): BLOCK final stage (exfiltration detected)

The repository documentation says this example can be reproduced through cargo run --example demo and a Docker-based smoke test.

Operational and Integration Guidance​

  • Quick check: verify basic operation with docker-compose up --build and the /healthz endpoint using a Docker image. Example commands are present in the documentation.
  • Automatic sealing through auto_commitment: in the default mode, a tools/list handshake automatically creates and installs a sealed graph. If no seal is installed, the first tool call in the session is blocked.
  • Manual sealing and installation: an operator can explicitly create a seal with traj commit and install it in the gateway with trajeckt.install or a supplied tool. An installed session receives a UUID, which must be passed to the agent wrapper.
  • Session-ID consistency: according to the documentation, a session_id mismatch is treated as an intentional configuration error and blocked with a message such as "no commitment installed." This prevents a silent fallback.

What It Detects and What It Does Not​

The trajeckt documentation states the following detection scope and limitations.

Detected when a sealed graph exists:

  • Off-plan calls: a call is rejected if it is not in the sealed graph's current frontier.
  • Data exfiltration to an unauthorized sink: writes outside provenance and permission scope are blocked.
  • Taint-based blocking when sensitive data controls a high-risk action.
  • Graph-based validation when the causal structure of a trajectory deviates from declared intent.

Not detected:

  • Attacks that require complete understanding of content semantics, such as injection instructions hidden in natural language. The documentation clearly states this limitation.
  • Attacks occurring inside the declared allowed causal manifold. In other words, a trajectory is not blocked if an attacker can make it appear legitimate.
  • It does not replace configuration-based controls from existing policy engines, including allow and deny lists, argument validation, and RBAC. It must therefore be combined with existing security controls.

ClawTrojan Benchmark and Validation​

The documentation says the project was tested against an independent benchmark called ClawTrojan and explicitly describes cases in which patterns such as stealthy-delay (cs_delay_002) were blocked end to end. The repository documents that shared trust lattices and floor definitions keep test code in tests/clawtrojan_cs_delay_002.rs synchronized with enforcement code, experimentally demonstrating defense against at least some attack patterns. The supplied evidence pack does not contain a clear complete list showing whether every ClawTrojan pattern is covered, so general applicability requires further validation.

Developer Perspective: Integration Example​

The repository includes Python SDK examples and a LangGraph-wrapper integration sample for agent tool nodes. A typical integration procedure is:

  1. Create a sealed graph automatically or manually.
  2. Install the sealed graph in the gateway and receive a session ID.
  3. Relay tool calls from the agent runtime through an HTTP wrapper using that session ID.

Detailed commands and examples are included in the repository's sdk-python and examples directories. During a real integration, source examples should be used to keep environment variables and keys consistent.

Term Explainers​

Term explainer: sealed graph

Plain definition: a graph that compiles the permitted list and order of tools an agent must follow during execution and signs it cryptographically in advance. Everyday example: it resembles a meeting agenda prepared and signed in advance that defines who may speak and in what order.

Term explainer: trajectory

Plain definition: the sequence of tool calls made by an agent during a session and the data flow between them. Everyday example: it resembles the route record of a parcel passing through several hubs before reaching its destination.

Term explainer: frontier

Plain definition: the set of tool calls that may legally occur next from the current session state in a sealed graph. Everyday example: it resembles the collection of spaces a game piece can legally move to from its current position on a board.

Term explainer: taint or tainted data

Plain definition: a marker on data originating from a sensitive source, such as a customer database, that requires special handling. Everyday example: it resembles separating food from other items after a foreign substance is found in it.

Term explainer: MCP (MCP Streamable HTTP transport)

Plain definition: the name of the HTTP-based agent-tool protocol used to interact with trajeckt in the documentation. The gateway implements part of this protocol's profile. Everyday example: it is a communication protocol resembling the rules an email client uses to communicate with a server, such as IMAP or SMTP.

Term explainer: Control-Barrier-Function (CBF)

Plain definition: an action filter that challenges or isolates behavior as session state approaches a safety boundary, quantitatively controlling trajectory safety. Everyday example: it resembles a vehicle's collision-prevention system controlling the vehicle during sudden acceleration or braking, like ABS.

Term explainer: ClawTrojan benchmark

Plain definition: the name of an independent benchmark suite that defines and tests trajectory-style agent attacks. The documentation reports that trajeckt was tested against it. Everyday example: it resembles a standard set of simulated penetration-testing scenarios for evaluating a security product.

Conclusion and Recommendations​

trajeckt presents a design philosophy for defending against multistep exploits in agent-tool integrations at the trajectory level. Its documentation and examples allow initial users to experiment quickly through Docker and example scripts. The core operational pattern is a sealed graph, session installation, and strict matching through the session ID. Semantic attacks and threats inside a declared trajectory remain, however, so the gateway must be used alongside existing policy engines and context-based validation.

Note: this article summarizes and analyzes the public repository README, documentation, and example files. Detailed internals such as performance tables and complete test coverage are not fully included in the documentation. Directly review the source code and tests before production adoption.

Sources​

// COMMENTS

Comments