Path Traversal Boundary Violation Detection Prompt

This prompt is designed for the specific moment right before a file-system agent executes a read, write, or list operation based on a user-supplied or model-generated path. Its job is to act as a semantic safety net, catching traversal attacks that might bypass simple string-matching checks. You should use this prompt when your agent operates within a defined, allowed directory scope (a sandbox) and accepts arbitrary path strings that could contain ../ sequences, symbolic links, or encoded characters designed to escape that scope. The ideal user is an AI engineer or platform developer building an agent harness that needs a model-based layer to interpret and validate path intent, producing a structured block or allow decision before the file operation is handed to the OS or filesystem API.

Deploy this prompt as a synchronous pre-check in your agent's tool-call pipeline. Before invoking any file-system tool, the harness should intercept the path argument and send it to the model with this prompt, along with the explicitly allowed base directories. The prompt instructs the model to resolve the intended target path, compare it against the allowed scope, and return a JSON block containing a decision (allow/block), the violating_path if blocked, and the nearest_allowed_alternative. This is not a replacement for OS-level sandboxing or containerization; it is an additional defense-in-depth layer that catches semantic and encoding-based attacks. Do not use this prompt for general path validation in non-agent contexts, for filesystem operations where the allowed scope is the entire filesystem, or as the sole security boundary in a production system without additional sandboxing.

After implementing this prompt, your next step is to build the validation harness that parses the model's JSON output and enforces the decision. If the decision is block, your harness must refuse the operation and log the incident for security review. Avoid the temptation to simply pass the nearest_allowed_alternative directly to the filesystem without human or heuristic confirmation, as this could introduce new attack vectors. For high-security deployments, combine this prompt with deterministic path canonicalization in code before the model call, and configure your evaluation suite to test against a comprehensive set of traversal payloads, including Unicode normalization attacks and symlink races.

This prompt template is designed to be embedded in a file-system agent's pre-execution validation step. It receives a requested file path and a set of allowed directory boundaries, then produces a structured decision indicating whether the request is safe to execute or must be blocked. The template uses square-bracket placeholders for all dynamic inputs, making it straightforward to wire into an application harness that injects the current request context before each invocation.

textCopy
You are a path traversal security validator. Your job is to determine whether a requested file path attempts to access directories outside the explicitly allowed scope. You must detect direct traversal, symlink-based escapes, encoding tricks, and relative-path attacks.

## INPUTS
- Requested Path: [REQUESTED_PATH]
- Allowed Directories (canonical, absolute): [ALLOWED_DIRECTORIES]
- Current Working Directory: [CURRENT_WORKING_DIRECTORY]
- Known Symlinks Map (target -> destination): [SYMLINKS_MAP]

## CONSTRAINTS
- Resolve the requested path to its canonical absolute form before evaluation.
- Consider `..` segments, extra slashes, dot segments, and URL-encoded characters.
- If the path traverses a symlink, resolve the symlink target and re-evaluate against allowed directories.
- Relative paths must be resolved from the current working directory.
- Case sensitivity must match the target filesystem's behavior: [CASE_SENSITIVE]

## OUTPUT_SCHEMA
Return a JSON object with exactly these fields:
{
  "decision": "allow" | "block",
  "canonical_requested_path": "string (the fully resolved absolute path)",
  "violating_component": "string | null (the path segment that caused the boundary violation)",
  "nearest_allowed_alternative": "string | null (the closest allowed directory if blocked)",
  "attack_vector": "string | null (one of: 'direct_traversal', 'symlink_escape', 'encoding_bypass', 'relative_path_escape', 'null_byte_injection', 'none')",
  "confidence": "float (0.0 to 1.0)",
  "reasoning": "string (brief explanation of the decision)"
}

## EXAMPLES
[EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

Analyze the requested path and return only the JSON object.

To adapt this template, replace each bracketed placeholder with values from your application context. [REQUESTED_PATH] should be the raw user or agent input. [ALLOWED_DIRECTORIES] must be a list of pre-resolved canonical absolute paths that define the system's operational boundary. [SYMLINKS_MAP] requires your harness to maintain a current mapping of known symlinks on the filesystem, updated whenever filesystem state changes. [EXAMPLES] should include 2-4 few-shot demonstrations covering at least one clean allow, one direct traversal block, and one symlink-based escape. [RISK_LEVEL] controls the strictness of the analysis—set to high for production systems where false allows are unacceptable, or standard for internal tools where some leniency is acceptable. After copying the template, test it against a golden dataset of known traversal attacks and benign paths before deployment.

This prompt is designed to sit as a pre-execution guard directly in front of any file-system operation (read, write, list, delete) that an agent or LLM-triggered function is about to perform. It should not be used as a standalone chat interaction. The primary integration point is inside the tool-call handler: after the model generates the function arguments (the requested file path) but before the OS-level file operation is executed. The harness must pass the resolved, absolute path to the prompt, not the raw user or model input, to prevent TOCTOU (time-of-check-time-of-use) races where a symlink is swapped between validation and execution.

The implementation flow is: (1) Intercept the tool call and resolve the requested path to its canonical, absolute form using os.path.realpath() or equivalent. (2) Inject the resolved path and the allowed directory list into the prompt's [INPUT_PATH] and [ALLOWED_DIRECTORIES] placeholders. (3) Call a fast, low-cost model (e.g., GPT-4o-mini, Claude Haiku) with the prompt. (4) Parse the JSON output and check the block_decision field. If true, log the full violation payload, do not execute the file operation, and return the nearest_allowed_alternative and explanation to the agent as a simulated tool error. If false, proceed with the file operation. (5) For high-risk deployments, add a secondary, deterministic check in code that verifies the resolved path's prefix matches an allowed directory before execution, as a defense-in-depth measure against model parsing errors.

Validation and retries: The harness must validate that the model's JSON output contains all required fields (block_decision, violating_component, nearest_allowed_alternative, explanation). If parsing fails, the safe default is to block the operation and log the raw response for inspection. Do not retry with the same model more than once; a malformed response is a signal to escalate. Logging and audit: Log every violation with the full prompt input, model output, agent's intended action, and a timestamp. This audit trail is critical for tuning the allowed directory list and detecting novel attack patterns. Symlink and encoding attacks: The harness must resolve symlinks before passing the path to the prompt. The prompt itself is instructed to flag .. segments and absolute paths outside the allowed roots, but it cannot see the underlying filesystem. The application code must handle Unicode normalization (NFC/NFD) and null-byte injection stripping before the path reaches either the prompt or the OS call.

Model choice and latency: This is a blocking check, so latency matters. Use the smallest capable model that reliably produces valid JSON. Cache the prompt prefix with the allowed directory list and instructions to reduce per-call token costs. If the agent is performing many file operations in a loop, consider batching path checks into a single prompt call with an array of paths, adjusting the output schema to an array of verdicts. When to escalate: If the model's block_decision is true but the deterministic prefix check passes, trust the deterministic check and log the discrepancy for model improvement. If the model returns false but the deterministic check fails, block the operation and treat it as a critical harness bug. This dual-check pattern prevents both model false positives (over-blocking) and false negatives (model bypass).