> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pecta.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Filesystem gate: block dangerous shell commands

> Detect destructive rm commands, path traversal sequences, and references to sensitive system directories anywhere in agent output before execution.

The filesystem gate walks every string value in `ctx.output` — including nested strings inside objects and arrays — and blocks the evaluation if it finds patterns that indicate a destructive or unauthorized filesystem operation. It is designed for agents that can generate or suggest shell commands: coding assistants, DevOps automation bots, CI/CD orchestrators, and similar tools where a single bad output could wipe data or expose credentials.

All three checks are enabled by default. You can disable any of them individually through the options if your use case requires it.

## Usage

```typescript theme={null}
import { createEngine, gates } from "@pecta/core";

const engine = createEngine({
  gates: [
    gates.filesystem(),
  ],
});

const result = await engine.evaluate({
  agent_id: "devops-bot",
  tool: "shell.suggest",
  output: { command: "rm -rf /var/app/data" },
});
// result.passed === false
```

## What it detects

### Destructive `rm` commands

The gate matches any of the following patterns:

| Pattern                           | Example                       |
| --------------------------------- | ----------------------------- |
| `rm -rf`, `rm -fr`                | `rm -rf /tmp/old`             |
| `rm -Rf`, `rm -fR`                | `rm -Rf ./build`              |
| Flags with other letters mixed in | `rm -rfv /data`               |
| Long-form flags                   | `rm --recursive --force /mnt` |
| Reversed long-form flags          | `rm --force --recursive /mnt` |

### Path traversal

Any occurrence of `..` used as a directory component — whether delimited by `/`, `\`, whitespace, or quotes — is flagged. This blocks attempts to escape a working directory such as `../../etc/passwd`.

### Sensitive directories

The gate flags references to the following paths:

| Path                                | What it protects                           |
| ----------------------------------- | ------------------------------------------ |
| `/etc`                              | System configuration files                 |
| `/usr`                              | System binaries and libraries              |
| `/var`                              | Variable data including logs and databases |
| `~/.ssh` or `/home/<user>/.ssh`     | SSH private keys                           |
| `~/.aws` or `/home/<user>/.aws`     | AWS credentials                            |
| `~/.gnupg` or `/home/<user>/.gnupg` | GPG keys                                   |

## What a failure looks like

```json theme={null}
{
  "name": "filesystem",
  "passed": false,
  "reason": "destructive rm command detected",
  "latency_ms": 0.19
}
```

```json theme={null}
{
  "name": "filesystem",
  "passed": false,
  "reason": "path traversal (..) detected",
  "latency_ms": 0.11
}
```

```json theme={null}
{
  "name": "filesystem",
  "passed": false,
  "reason": "sensitive path detected: ~/.ssh",
  "latency_ms": 0.14
}
```

## Configuration

<ParamField path="detectRmRf" type="boolean">
  Enable destructive `rm` command detection. Defaults to `true`.
</ParamField>

<ParamField path="detectTraversal" type="boolean">
  Enable path traversal (`..`) detection. Defaults to `true`.
</ParamField>

<ParamField path="detectSensitive" type="boolean">
  Enable sensitive directory detection. Defaults to `true`.
</ParamField>

<ParamField path="name" type="string">
  Override the gate name recorded in results. Defaults to `"filesystem"`.
</ParamField>

## Disabling individual checks

Turn off specific checks while keeping the others:

```typescript theme={null}
import { createEngine, gates } from "@pecta/core";

const engine = createEngine({
  gates: [
    gates.filesystem({
      detectRmRf: true,
      detectTraversal: true,
      detectSensitive: false, // your agent legitimately references /etc
    }),
  ],
});
```

<Warning>
  The gate scans strings recursively through the entire output value, including deeply nested objects and arrays. Very large or deeply nested outputs are capped at 10,000 visited nodes to prevent pathological runtime. Outputs beyond that cap are not fully scanned.
</Warning>